Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
UMOConnector |
|
| 1.0;1 |
1 | /* | |
2 | * $Id: UMOConnector.java 7976 2007-08-21 14:26:13Z 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 | } |