1 /* 2 * $Id: Connector.java 12294 2008-07-11 08:30:31Z dirk.olmes $ 3 * -------------------------------------------------------------------------------------- 4 * Copyright (c) MuleSource, Inc. All rights reserved. http://www.mulesource.com 5 * 6 * The software in this package is published under the terms of the CPAL v1.0 7 * license, a copy of which has been included with this distribution in the 8 * LICENSE.txt file. 9 */ 10 11 package org.mule.api.transport; 12 13 import org.mule.api.MessagingException; 14 import org.mule.api.MuleContext; 15 import org.mule.api.MuleEvent; 16 import org.mule.api.MuleException; 17 import org.mule.api.MuleMessage; 18 import org.mule.api.NamedObject; 19 import org.mule.api.context.MuleContextAware; 20 import org.mule.api.endpoint.InboundEndpoint; 21 import org.mule.api.endpoint.OutboundEndpoint; 22 import org.mule.api.lifecycle.Lifecycle; 23 import org.mule.api.service.Service; 24 25 import java.beans.ExceptionListener; 26 import java.io.OutputStream; 27 28 /** 29 * <code>Connector</code> is the mechanism used to connect to external systems 30 * and protocols in order to send and receive data. 31 */ 32 public interface Connector extends Lifecycle, MuleContextAware, NamedObject 33 { 34 int INT_VALUE_NOT_SET = -1; 35 36 /** 37 * This creates a <code>MessageReceiver</code> associated with this endpoint 38 * and registers it with the connector 39 * 40 * @param service the listening service 41 * @param endpoint the endpoint contains the listener endpointUri on which to 42 * listen on. 43 * @throws Exception if the MessageReceiver cannot be created or the Receiver 44 * cannot be registered 45 */ 46 MessageReceiver registerListener(Service service, InboundEndpoint endpoint) throws Exception; 47 48 /** 49 * @param service the listening service 50 * @param endpoint the associated endpointDescriptor with the listener 51 * @throws Exception if the listener cannot be unregistered. If a listener is not 52 * associated with the given endpoint this will not throw an 53 * exception 54 */ 55 void unregisterListener(Service service, InboundEndpoint endpoint) throws Exception; 56 57 /** 58 * @return true if the endpoint is started 59 */ 60 boolean isStarted(); 61 62 /** 63 * @return false if the connector is alive and well or true if the connector is 64 * being destroyed 65 */ 66 boolean isDisposed(); 67 68 /** 69 * @return false if the connector is alive and well or true if the connector has 70 * been told to dispose 71 */ 72 boolean isDisposing(); 73 74 /** 75 * Gets a {@link MessageAdapter} from the connector for the given message 76 * (data) 77 * 78 * @param message the data with which to initialise the {@link MessageAdapter} 79 * @return the {@link MessageAdapter} for the endpoint 80 * @throws MessagingException if the message parameter is not supported 81 * @see MessageAdapter 82 */ 83 MessageAdapter getMessageAdapter(Object message) throws MessagingException; 84 85 /** 86 * @return the primary protocol name for endpoints of this connector 87 */ 88 String getProtocol(); 89 90 /** 91 * @return true if the protocol is supported by this connector. 92 */ 93 boolean supportsProtocol(String protocol); 94 95 /** 96 * @param listener the exception strategy to use with this endpoint 97 * @see ExceptionListener 98 */ 99 void setExceptionListener(ExceptionListener listener); 100 101 /** 102 * @return the Exception stategy used by the endpoint 103 * @see ExceptionListener 104 */ 105 ExceptionListener getExceptionListener(); 106 107 /** 108 * @param exception the exception that was caught 109 */ 110 void handleException(Exception exception); 111 112 /** 113 * The dispatcher factory is used to create a message dispatcher of the current 114 * request 115 * 116 * @param factory the factory to use when a dispatcher request is madr 117 */ 118 void setDispatcherFactory(MessageDispatcherFactory factory); 119 120 /** 121 * The dispatcher factory is used to create a message dispatcher of the current 122 * request 123 * 124 * @return the factory to use when a dispatcher request is madr 125 */ 126 MessageDispatcherFactory getDispatcherFactory(); 127 128 /** 129 * The requester factory is used to create a message requester of the current 130 * request 131 * 132 * @param factory the factory to use when a request is made 133 */ 134 void setRequesterFactory(MessageRequesterFactory factory); 135 136 /** 137 * The requester factory is used to create a message requester of the current 138 * request 139 * 140 * @return the factory to use when a request is made 141 */ 142 MessageRequesterFactory getRequesterFactory(); 143 144 boolean isRemoteSyncEnabled(); 145 146 /** 147 * Used to define is this connectors endpoints' should be synchronous by default rather than 148 * using Mule's instance wide default. The endpoint is passed through to this method so that 149 * transports like Axis/CXF can determine if synchronous should be default depending on the 150 * endpoint transport e.g. http/vm/jms etc. 151 * 152 * @param endpoint 153 * @return 154 * @see ImmutableEndpoint#isSynchronous() 155 */ 156 boolean isSyncEnabled(String protocol); 157 158 /** 159 * Dispatches an event from the endpoint to the external system 160 * 161 * @param event The event to dispatch 162 * @throws DispatchException if the event fails to be dispatched 163 */ 164 void dispatch(OutboundEndpoint endpoint, MuleEvent event) throws DispatchException; 165 166 /** 167 * Make a specific request to the underlying transport 168 * 169 * @param uri the endpoint uri to use when connecting to the resource 170 * @param timeout the maximum time the operation should block before returning. 171 * The call should return immediately if there is data available. If 172 * no data becomes available before the timeout elapses, null will be 173 * returned 174 * @return the result of the request wrapped in a MuleMessage object. Null will be 175 * returned if no data was avaialable 176 * @throws Exception if the call to the underlying protocal cuases an exception 177 * @deprecated Use request(ImmutableEndpoint endpoint, long timeout) 178 */ 179 MuleMessage request(String uri, long timeout) throws Exception; 180 181 /** 182 * Make a specific request to the underlying transport 183 * 184 * @param endpoint the endpoint to use when connecting to the resource 185 * @param timeout the maximum time the operation should block before returning. 186 * The call should return immediately if there is data available. If 187 * no data becomes available before the timeout elapses, null will be 188 * returned 189 * @return the result of the request wrapped in a MuleMessage object. Null will be 190 * returned if no data was avaialable 191 * @throws Exception if the call to the underlying protocal cuases an exception 192 */ 193 MuleMessage request(InboundEndpoint endpoint, long timeout) throws Exception; 194 195 /** 196 * Sends an event from the endpoint to the external system 197 * 198 * @param event The event to send 199 * @return event the response form the external system wrapped in a MuleEvent 200 * @throws DispatchException if the event fails to be dispatched 201 */ 202 MuleMessage send(OutboundEndpoint endpoint, MuleEvent event) throws DispatchException; 203 204 205 /** 206 * Will get the output stream for this type of transport. Typically this 207 * will be called only when Streaming is being used on an outbound endpoint. 208 * If Streaming is not supported by this transport an {@link UnsupportedOperationException} 209 * is thrown. Note that the stream MUST release resources on close. For help doing so, see 210 * {@link org.mule.model.streaming.CallbackOutputStream}. 211 * 212 * @param endpoint the endpoint that releates to this Dispatcher 213 * @param message the current message being processed 214 * @return the output stream to use for this request 215 * @throws MuleException 216 */ 217 OutputStream getOutputStream(OutboundEndpoint endpoint, MuleMessage message) throws MuleException; 218 219 MuleContext getMuleContext(); 220 }