001: /*
002: * $Id: Connector.java 11311 2008-03-10 20:15:57Z dfeist $
003: * --------------------------------------------------------------------------------------
004: * Copyright (c) MuleSource, Inc. All rights reserved. http://www.mulesource.com
005: *
006: * The software in this package is published under the terms of the CPAL v1.0
007: * license, a copy of which has been included with this distribution in the
008: * LICENSE.txt file.
009: */
010:
011: package org.mule.api.transport;
012:
013: import org.mule.api.MessagingException;
014: import org.mule.api.MuleContext;
015: import org.mule.api.MuleEvent;
016: import org.mule.api.MuleException;
017: import org.mule.api.MuleMessage;
018: import org.mule.api.NamedObject;
019: import org.mule.api.context.MuleContextAware;
020: import org.mule.api.endpoint.ImmutableEndpoint;
021: import org.mule.api.endpoint.InboundEndpoint;
022: import org.mule.api.endpoint.OutboundEndpoint;
023: import org.mule.api.lifecycle.Lifecycle;
024: import org.mule.api.service.Service;
025:
026: import java.beans.ExceptionListener;
027: import java.io.OutputStream;
028:
029: /**
030: * <code>Connector</code> is the mechanism used to connect to external systems
031: * and protocols in order to send and receive data.
032: */
033: public interface Connector extends Lifecycle, MuleContextAware,
034: NamedObject {
035: int INT_VALUE_NOT_SET = -1;
036:
037: /**
038: * This creates a <code>MessageReceiver</code> associated with this endpoint
039: * and registers it with the connector
040: *
041: * @param service the listening service
042: * @param endpoint the endpoint contains the listener endpointUri on which to
043: * listen on.
044: * @throws Exception if the MessageReceiver cannot be created or the Receiver
045: * cannot be registered
046: */
047: MessageReceiver registerListener(Service service,
048: InboundEndpoint endpoint) throws Exception;
049:
050: /**
051: * @param service the listening service
052: * @param endpoint the associated endpointDescriptor with the listener
053: * @throws Exception if the listener cannot be unregistered. If a listener is not
054: * associated with the given endpoint this will not throw an
055: * exception
056: */
057: void unregisterListener(Service service, InboundEndpoint endpoint)
058: throws Exception;
059:
060: /**
061: * @return true if the endpoint is started
062: */
063: boolean isStarted();
064:
065: /**
066: * @return false if the connector is alive and well or true if the connector is
067: * being destroyed
068: */
069: boolean isDisposed();
070:
071: /**
072: * @return false if the connector is alive and well or true if the connector has
073: * been told to dispose
074: */
075: boolean isDisposing();
076:
077: /**
078: * Gets a {@link MessageAdapter} from the connector for the given message
079: * (data)
080: *
081: * @param message the data with which to initialise the {@link MessageAdapter}
082: * @return the {@link MessageAdapter} for the endpoint
083: * @throws MessagingException if the message parameter is not supported
084: * @see MessageAdapter
085: */
086: MessageAdapter getMessageAdapter(Object message)
087: throws MessagingException;
088:
089: /**
090: * @return the primary protocol name for endpoints of this connector
091: */
092: String getProtocol();
093:
094: /**
095: * @return true if the protocol is supported by this connector.
096: */
097: boolean supportsProtocol(String protocol);
098:
099: /**
100: * @param listener the exception strategy to use with this endpoint
101: * @see ExceptionListener
102: */
103: void setExceptionListener(ExceptionListener listener);
104:
105: /**
106: * @return the Exception stategy used by the endpoint
107: * @see ExceptionListener
108: */
109: ExceptionListener getExceptionListener();
110:
111: /**
112: * @param exception the exception that was caught
113: */
114: void handleException(Exception exception);
115:
116: /**
117: * The dispatcher factory is used to create a message dispatcher of the current
118: * request
119: *
120: * @param factory the factory to use when a dispatcher request is madr
121: */
122: void setDispatcherFactory(MessageDispatcherFactory factory);
123:
124: /**
125: * The dispatcher factory is used to create a message dispatcher of the current
126: * request
127: *
128: * @return the factory to use when a dispatcher request is madr
129: */
130: MessageDispatcherFactory getDispatcherFactory();
131:
132: /**
133: * The requester factory is used to create a message requester of the current
134: * request
135: *
136: * @param factory the factory to use when a request is made
137: */
138: void setRequesterFactory(MessageRequesterFactory factory);
139:
140: /**
141: * The requester factory is used to create a message requester of the current
142: * request
143: *
144: * @return the factory to use when a request is made
145: */
146: MessageRequesterFactory getRequesterFactory();
147:
148: boolean isRemoteSyncEnabled();
149:
150: /**
151: * Used to define is this connectors endpoints' should be synchronous by default rather than using mule's
152: * instance wide default. The endpoint is passed through to this method so that transports like axis/xfire
153: * can determine if synchronous should be default depending on the endpoint transport e.g. http/vm/jms
154: * etc.
155: *
156: * @param endpoint
157: * @return
158: * @see ImmutableEndpoint#isSynchronous()
159: */
160: boolean isSyncEnabled(String protocol);
161:
162: /**
163: * Dispatches an event from the endpoint to the external system
164: *
165: * @param event The event to dispatch
166: * @throws DispatchException if the event fails to be dispatched
167: */
168: void dispatch(OutboundEndpoint endpoint, MuleEvent event)
169: throws DispatchException;
170:
171: /**
172: * Make a specific request to the underlying transport
173: *
174: * @param uri the endpoint uri to use when connecting to the resource
175: * @param timeout the maximum time the operation should block before returning.
176: * The call should return immediately if there is data available. If
177: * no data becomes available before the timeout elapses, null will be
178: * returned
179: * @return the result of the request wrapped in a MuleMessage object. Null will be
180: * returned if no data was avaialable
181: * @throws Exception if the call to the underlying protocal cuases an exception
182: * @deprecated Use request(ImmutableEndpoint endpoint, long timeout)
183: */
184: MuleMessage request(String uri, long timeout) throws Exception;
185:
186: /**
187: * Make a specific request to the underlying transport
188: *
189: * @param endpoint the endpoint to use when connecting to the resource
190: * @param timeout the maximum time the operation should block before returning.
191: * The call should return immediately if there is data available. If
192: * no data becomes available before the timeout elapses, null will be
193: * returned
194: * @return the result of the request wrapped in a MuleMessage object. Null will be
195: * returned if no data was avaialable
196: * @throws Exception if the call to the underlying protocal cuases an exception
197: */
198: MuleMessage request(InboundEndpoint endpoint, long timeout)
199: throws Exception;
200:
201: /**
202: * Sends an event from the endpoint to the external system
203: *
204: * @param event The event to send
205: * @return event the response form the external system wrapped in a MuleEvent
206: * @throws DispatchException if the event fails to be dispatched
207: */
208: MuleMessage send(OutboundEndpoint endpoint, MuleEvent event)
209: throws DispatchException;
210:
211: /**
212: * Will get the output stream for this type of transport. Typically this
213: * will be called only when Streaming is being used on an outbound endpoint.
214: * If Streaming is not supported by this transport an {@link UnsupportedOperationException}
215: * is thrown. Note that the stream MUST release resources on close. For help doing so, see
216: * {@link org.mule.model.streaming.CallbackOutputStream}.
217: *
218: * @param endpoint the endpoint that releates to this Dispatcher
219: * @param message the current message being processed
220: * @return the output stream to use for this request
221: * @throws MuleException
222: */
223: OutputStream getOutputStream(OutboundEndpoint endpoint,
224: MuleMessage message) throws MuleException;
225:
226: MuleContext getMuleContext();
227: }
|