View Javadoc

1   /*
2    * $Id: UMOConnector.java 7963 2007-08-21 08:53:15Z 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.umo.provider;
12  
13  import org.mule.umo.MessagingException;
14  import org.mule.umo.UMOComponent;
15  import org.mule.umo.UMOEvent;
16  import org.mule.umo.UMOException;
17  import org.mule.umo.UMOMessage;
18  import org.mule.umo.endpoint.UMOEndpoint;
19  import org.mule.umo.endpoint.UMOEndpointURI;
20  import org.mule.umo.endpoint.UMOImmutableEndpoint;
21  import org.mule.umo.lifecycle.Disposable;
22  import org.mule.umo.lifecycle.Initialisable;
23  
24  import java.beans.ExceptionListener;
25  import java.io.InputStream;
26  import java.io.OutputStream;
27  
28  import edu.emory.mathcs.backport.java.util.concurrent.ScheduledExecutorService;
29  
30  /**
31   * <code>UMOConnector</code> is the mechanism used to connect to external systems
32   * and protocols in order to send and receive data.
33   */
34  public interface UMOConnector extends Disposable, Initialisable
35  {
36      int INT_VALUE_NOT_SET = -1;
37  
38      /**
39       * This creates a <code>UMOMessageReceiver</code> associated with this endpoint
40       * and registers it with the connector.
41       * 
42       * @param component the listening component
43       * @param endpoint the endpoint contains the listener endpointUri on which to
44       *            listen on.
45       * @throws Exception if the UMOMessageReceiver cannot be created or the Receiver
46       *             cannot be registered
47       * @return message receiver
48       */
49      UMOMessageReceiver registerListener(UMOComponent component, UMOEndpoint endpoint) throws Exception;
50  
51      /**
52       * @param component the listening component
53       * @param endpoint the associated endpointDescriptor with the listener
54       * @throws Exception if the listener cannot be unregistered. If a listener is not
55       *             associated with the given endpoint this will not throw an
56       *             exception
57       */
58      void unregisterListener(UMOComponent component, UMOEndpoint endpoint) throws Exception;
59  
60      /**
61       * @return true if the endpoint is started
62       */
63      boolean isStarted();
64  
65      /**
66       * @return false if the connector is alive and well or true if the connector is
67       *         being destroyed
68       */
69      boolean isDisposed();
70  
71      /**
72       * @return false if the connector is alive and well or true if the connector has
73       *         been told to dispose
74       */
75      boolean isDisposing();
76  
77      /**
78       * Gets a {@link UMOMessageAdapter} from the connector for the given message
79       * (data)
80       * 
81       * @param message the data with which to initialise the {@link UMOMessageAdapter}
82       * @return the {@link UMOMessageAdapter} for the endpoint
83       * @throws MessagingException if the message parameter is not supported
84       * @see UMOMessageAdapter
85       */
86      UMOMessageAdapter getMessageAdapter(Object message) throws MessagingException;
87  
88      /**
89       * Gets a {@link UMOStreamMessageAdapter} from the connector for the given
90       * message. This Adapter will correctly handle data streaming for this type of
91       * connector
92       * 
93       * @param in the input stream to read the data from
94       * @param out the outputStream to write data to. This can be null.
95       * @return the {@link UMOStreamMessageAdapter} for the endpoint
96       * @throws MessagingException if the message parameter is not supported
97       * @see UMOStreamMessageAdapter
98       */
99      UMOStreamMessageAdapter getStreamMessageAdapter(InputStream in, OutputStream out)
100         throws MessagingException;
101 
102     /**
103      * @return the name associated with the connector
104      */
105     String getName();
106 
107     /**
108      * @param newName the name to associate with the connector
109      */
110     void setName(String newName);
111 
112     /**
113      * @return the primary protocol name for endpoints of this connector
114      */
115     String getProtocol();
116 
117     /**
118      * @param protocol protocol name
119      * @return true if the protocol is supported by this connector.
120      */
121     boolean supportsProtocol(String protocol);
122 
123     /**
124      * @param listener the exception strategy to use with this endpoint
125      * @see ExceptionListener
126      */
127     void setExceptionListener(ExceptionListener listener);
128 
129     /**
130      * @return the Exception stategy used by the endpoint
131      * @see ExceptionListener
132      */
133     ExceptionListener getExceptionListener();
134 
135     /**
136      * @param exception the exception that was caught
137      */
138     void handleException(Exception exception);
139 
140     /**
141      * Returns a Scheduler service for execution of periodic tasks.
142      * @return scheduler
143      */
144     ScheduledExecutorService getScheduler();
145 
146     /**
147      * The dispatcher factory is used to create a message dispatcher of the current
148      * request
149      * 
150      * @param factory the factory to use when a dispatcher request is madr
151      */
152     void setDispatcherFactory(UMOMessageDispatcherFactory factory);
153 
154     /**
155      * The dispatcher factory is used to create a message dispatcher of the current
156      * request
157      * 
158      * @return the factory to use when a dispatcher request is madr
159      */
160     UMOMessageDispatcherFactory getDispatcherFactory();
161 
162     void startConnector() throws UMOException;
163 
164     void stopConnector() throws UMOException;
165 
166     boolean isRemoteSyncEnabled();
167 
168     /**
169      * Dispatches an event from the endpoint to the external system
170      * 
171      * @param event The event to dispatch
172      * @param endpoint endpoint to dispatch from
173      * @throws DispatchException if the event fails to be dispatched
174      */
175     void dispatch(UMOImmutableEndpoint endpoint, UMOEvent event) throws DispatchException;
176 
177     /**
178      * Make a specific request to the underlying transport
179      * 
180      * @param endpointUri the endpoint URI to use when connecting to the resource
181      * @param timeout the maximum time the operation should block before returning.
182      *            The call should return immediately if there is data available. If
183      *            no data becomes available before the timeout elapses, null will be
184      *            returned
185      * @return the result of the request wrapped in a UMOMessage object. Null will be
186      *         returned if no data was avaialable
187      * @throws Exception if the call to the underlying protocal cuases an exception
188      * @deprecated Use receive(UMOImmutableEndpoint endpoint, long timeout)
189      */
190     UMOMessage receive(UMOEndpointURI endpointUri, long timeout) throws Exception;
191 
192     /**
193      * Make a specific request to the underlying transport
194      * 
195      * @param endpoint the endpoint to use when connecting to the resource
196      * @param timeout the maximum time the operation should block before returning.
197      *            The call should return immediately if there is data available. If
198      *            no data becomes available before the timeout elapses, null will be
199      *            returned
200      * @return the result of the request wrapped in a UMOMessage object. Null will be
201      *         returned if no data was avaialable
202      * @throws Exception if the call to the underlying protocal cuases an exception
203      */
204     UMOMessage receive(UMOImmutableEndpoint endpoint, long timeout) throws Exception;
205 
206     /**
207      * Sends an event from the endpoint to the external system
208      * 
209      * @param event The event to send
210      * @param endpoint endpoint to send from
211      * @return event the response form the external system wrapped in a UMOEvent
212      * @throws DispatchException if the event fails to be dispatched
213      */
214     UMOMessage send(UMOImmutableEndpoint endpoint, UMOEvent event) throws DispatchException;
215 
216 
217     /**
218      * Will get the output stream for this type of transport. Typically this
219      * will be called only when Streaming is being used on an outbound endpoint.
220      * If Streaming is not supported by this transport an {@link UnsupportedOperationException}
221      * is thrown.   Note that the stream MUST release resources on close.  For help doing so, see
222      * {@link org.mule.impl.model.streaming.CallbackOutputStream}.
223      *
224      * @param endpoint the endpoint that releates to this Dispatcher
225      * @param message the current message being processed
226      * @return the output stream to use for this request
227      * @throws UMOException in case of any error
228      */
229     OutputStream getOutputStream(UMOImmutableEndpoint endpoint, UMOMessage message) throws UMOException;
230 
231 }