Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
UMOEventContext |
|
| 1.0;1 |
1 | /* | |
2 | * $Id: UMOEventContext.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; | |
12 | ||
13 | import org.mule.umo.endpoint.UMOEndpoint; | |
14 | import org.mule.umo.endpoint.UMOEndpointURI; | |
15 | import org.mule.umo.transformer.TransformerException; | |
16 | ||
17 | import java.io.OutputStream; | |
18 | ||
19 | /** | |
20 | * <code>UMOEventContext</code> is the context object for the current request. | |
21 | * Using the context, developers can send/dispatch/receive events programmatically as | |
22 | * well as manage transactions. | |
23 | */ | |
24 | public interface UMOEventContext | |
25 | { | |
26 | /** | |
27 | * Returns the message payload for this event | |
28 | * | |
29 | * @return the message payload for this event | |
30 | */ | |
31 | UMOMessage getMessage(); | |
32 | ||
33 | /** | |
34 | * Returns the contents of the message as a byte array. | |
35 | * | |
36 | * @return the contents of the message as a byte array | |
37 | * @throws UMOException if the message cannot be converted into an array of bytes | |
38 | */ | |
39 | byte[] getMessageAsBytes() throws UMOException; | |
40 | ||
41 | /** | |
42 | * Returns the message transformed into it's recognised or expected format. The | |
43 | * transformer used is the one configured on the endpoint through which this | |
44 | * event was received. | |
45 | * | |
46 | * @return the message transformed into it's recognised or expected format. | |
47 | * @throws org.mule.umo.transformer.TransformerException if a failure occurs in | |
48 | * the transformer | |
49 | * @see org.mule.umo.transformer.UMOTransformer | |
50 | */ | |
51 | Object getTransformedMessage() throws TransformerException; | |
52 | ||
53 | /** | |
54 | * Returns the message transformed into it's recognised or expected format. The | |
55 | * transformer used is the one configured on the endpoint through which this | |
56 | * event was received. | |
57 | * | |
58 | * @param expectedType The class type required for the return object. This param | |
59 | * just provides a convienient way to manage type casting of | |
60 | * transformed objects | |
61 | * @return the message transformed into it's recognised or expected format. | |
62 | * @throws org.mule.umo.transformer.TransformerException if a failure occurs or | |
63 | * if the return type is not the same as the expected type in the | |
64 | * transformer | |
65 | * @see org.mule.umo.transformer.UMOTransformer | |
66 | */ | |
67 | Object getTransformedMessage(Class expectedType) throws TransformerException; | |
68 | ||
69 | /** | |
70 | * Returns the message transformed into it's recognised or expected format and | |
71 | * then into an array of bytes. The transformer used is the one configured on the | |
72 | * endpoint through which this event was received. | |
73 | * | |
74 | * @return the message transformed into it's recognised or expected format as an | |
75 | * array of bytes. | |
76 | * @throws TransformerException if a failure occurs in the transformer | |
77 | * @see org.mule.umo.transformer.UMOTransformer | |
78 | */ | |
79 | byte[] getTransformedMessageAsBytes() throws TransformerException; | |
80 | ||
81 | /** | |
82 | * Returns the message transformed into it's recognised or expected format and | |
83 | * then into a String. The transformer used is the one configured on the endpoint | |
84 | * through which this event was received. This method will use the encoding set | |
85 | * on the event | |
86 | * | |
87 | * @return the message transformed into it's recognised or expected format as a | |
88 | * Strings. | |
89 | * @throws TransformerException if a failure occurs in the transformer | |
90 | * @see org.mule.umo.transformer.UMOTransformer | |
91 | */ | |
92 | String getTransformedMessageAsString() throws TransformerException; | |
93 | ||
94 | /** | |
95 | * Returns the message contents as a string This method will use the encoding set | |
96 | * on the event | |
97 | * | |
98 | * @return the message contents as a string | |
99 | * @throws UMOException if the message cannot be converted into a string | |
100 | */ | |
101 | String getMessageAsString() throws UMOException; | |
102 | ||
103 | /** | |
104 | * Returns the message transformed into it's recognised or expected format and | |
105 | * then into a String. The transformer used is the one configured on the endpoint | |
106 | * through which this event was received. | |
107 | * | |
108 | * @param encoding The encoding to use when transforming the message | |
109 | * @return the message transformed into it's recognised or expected format as a | |
110 | * Strings. | |
111 | * @throws TransformerException if a failure occurs in the transformer | |
112 | * @see org.mule.umo.transformer.UMOTransformer | |
113 | */ | |
114 | String getTransformedMessageAsString(String encoding) throws TransformerException; | |
115 | ||
116 | /** | |
117 | * Returns the message contents as a string | |
118 | * | |
119 | * @param encoding The encoding to use when transforming the message | |
120 | * @return the message contents as a string | |
121 | * @throws UMOException if the message cannot be converted into a string | |
122 | */ | |
123 | String getMessageAsString(String encoding) throws UMOException; | |
124 | ||
125 | /** | |
126 | * Returns the current transaction (if any) for the session | |
127 | * | |
128 | * @return the current transaction for the session or null if there is no | |
129 | * transaction in progress | |
130 | */ | |
131 | UMOTransaction getCurrentTransaction(); | |
132 | ||
133 | /** | |
134 | * Mark the current transaction (if any) for rollback | |
135 | * | |
136 | * @throws TransactionException | |
137 | */ | |
138 | void markTransactionForRollback() throws TransactionException; | |
139 | ||
140 | /** | |
141 | * This will send an event via the configured outbound router on the component | |
142 | * | |
143 | * @param message the message to send | |
144 | * @return the result of the send if any | |
145 | * @throws UMOException if there is no outbound endpoint configured on the | |
146 | * component or the events fails during dispatch | |
147 | */ | |
148 | UMOMessage sendEvent(Object message) throws UMOException; | |
149 | ||
150 | /** | |
151 | * Depending on the session state this methods either Passes an event | |
152 | * synchronously to the next available Mule UMO in the pool or via the endpoint | |
153 | * configured for the event | |
154 | * | |
155 | * @param message the message payload to send | |
156 | * @return the return Message from the call or null if there was no result | |
157 | * @throws UMOException if the event fails to be processed by the component or | |
158 | * the transport for the endpoint | |
159 | */ | |
160 | UMOMessage sendEvent(UMOMessage message) throws UMOException; | |
161 | ||
162 | /** | |
163 | * Depending on the session state this methods either Passes an event | |
164 | * synchronously to the next available Mule UMO in the pool or via the endpoint | |
165 | * configured for the event | |
166 | * | |
167 | * @param message the event message payload to send | |
168 | * @param endpoint The endpointUri to disptch the event through | |
169 | * @return the return Message from the call or null if there was no result | |
170 | * @throws UMOException if the event fails to be processed by the component or | |
171 | * the transport for the endpoint | |
172 | */ | |
173 | UMOMessage sendEvent(UMOMessage message, UMOEndpointURI endpoint) throws UMOException; | |
174 | ||
175 | /** | |
176 | * Depending on the session state this methods either Passes an event | |
177 | * synchronously to the next available Mule UMO in the pool or via the endpoint | |
178 | * configured for the event | |
179 | * | |
180 | * @param message the event message payload to send | |
181 | * @param endpointName The endpoint name to disptch the event through. This will | |
182 | * be looked up first on the component configuration and then on the | |
183 | * mule manager configuration | |
184 | * @return the return Message from the call or null if there was no result | |
185 | * @throws UMOException if the event fails to be processed by the component or | |
186 | * the transport for the endpoint | |
187 | */ | |
188 | UMOMessage sendEvent(UMOMessage message, String endpointName) throws UMOException; | |
189 | ||
190 | /** | |
191 | * Depending on the session state this methods either Passes an event | |
192 | * synchronously to the next available Mule UMO in the pool or via the endpoint | |
193 | * configured for the event | |
194 | * | |
195 | * @param message the event message payload to send | |
196 | * @param endpoint The endpoint to disptch the event through. | |
197 | * @return the return Message from the call or null if there was no result | |
198 | * @throws UMOException if the event fails to be processed by the component or | |
199 | * the transport for the endpoint | |
200 | */ | |
201 | UMOMessage sendEvent(UMOMessage message, UMOEndpoint endpoint) throws UMOException; | |
202 | ||
203 | /** | |
204 | * sends an event request via the configured outbound router for this component. | |
205 | * This method return immediately, but the result of the event invocation | |
206 | * available from the returned a Future result that can be accessed later by the | |
207 | * the returned FutureMessageResult. the Future messageResult can be queried at | |
208 | * any time to check that the invocation has completed. A timeout is associated | |
209 | * with the invocation, which is the maximum time in milli-seconds that the | |
210 | * invocation should take to complete | |
211 | * | |
212 | * @param message the object that is the payload of the event | |
213 | * @param timeout how long to block in milliseconds waiting for a result | |
214 | * @return the result message if any of the invocation | |
215 | * @throws org.mule.umo.UMOException if the dispatch fails or the components or | |
216 | * transfromers cannot be found | |
217 | * @see FutureMessageResult | |
218 | */ | |
219 | FutureMessageResult sendEventAsync(Object message, int timeout) throws UMOException; | |
220 | ||
221 | /** | |
222 | * sends an event request via the configured outbound router for this component. | |
223 | * This method return immediately, but the result of the event invocation | |
224 | * available from the returned a Future result that can be accessed later by the | |
225 | * the returned FutureMessageResult. the Future messageResult can be queried at | |
226 | * any time to check that the invocation has completed. A timeout is associated | |
227 | * with the invocation, which is the maximum time in milli-seconds that the | |
228 | * invocation should take to complete | |
229 | * | |
230 | * @param message the UMOMessage of the event | |
231 | * @param timeout how long to block in milliseconds waiting for a result | |
232 | * @return the result message if any of the invocation | |
233 | * @throws org.mule.umo.UMOException if the dispatch fails or the components or | |
234 | * transfromers cannot be found | |
235 | * @see FutureMessageResult | |
236 | */ | |
237 | FutureMessageResult sendEventAsync(UMOMessage message, int timeout) throws UMOException; | |
238 | ||
239 | /** | |
240 | * sends an event request via the configured outbound router for this component. | |
241 | * This method return immediately, but the result of the event invocation | |
242 | * available from the returned a Future result that can be accessed later by the | |
243 | * the returned FutureMessageResult. the Future messageResult can be queried at | |
244 | * any time to check that the invocation has completed. A timeout is associated | |
245 | * with the invocation, which is the maximum time in milli-seconds that the | |
246 | * invocation should take to complete | |
247 | * | |
248 | * @param message the UMOMessage of the event | |
249 | * @param endpoint the endpointUri to dispatch to | |
250 | * @param timeout how long to block in milliseconds waiting for a result | |
251 | * @return the result message if any of the invocation | |
252 | * @throws org.mule.umo.UMOException if the dispatch fails or the components or | |
253 | * transfromers cannot be found | |
254 | * @see FutureMessageResult | |
255 | */ | |
256 | FutureMessageResult sendEventAsync(UMOMessage message, UMOEndpointURI endpoint, int timeout) | |
257 | throws UMOException; | |
258 | ||
259 | /** | |
260 | * sends an event request via the configured outbound router for this component. | |
261 | * This method return immediately, but the result of the event invocation | |
262 | * available from the returned a Future result that can be accessed later by the | |
263 | * the returned FutureMessageResult. the Future messageResult can be queried at | |
264 | * any time to check that the invocation has completed. A timeout is associated | |
265 | * with the invocation, which is the maximum time in milli-seconds that the | |
266 | * invocation should take to complete | |
267 | * | |
268 | * @param message the UMOMessage of the event | |
269 | * @param endpointName The endpoint name to disptch the event through. This will | |
270 | * be looked up first on the component configuration and then on the | |
271 | * mule manager configuration | |
272 | * @param timeout how long to block in milliseconds waiting for a result | |
273 | * @return the result message if any of the invocation | |
274 | * @throws org.mule.umo.UMOException if the dispatch fails or the components or | |
275 | * transfromers cannot be found | |
276 | * @see FutureMessageResult | |
277 | */ | |
278 | FutureMessageResult sendEventAsync(UMOMessage message, String endpointName, int timeout) | |
279 | throws UMOException; | |
280 | ||
281 | /** | |
282 | * This will dispatch an event asynchronously via the configured outbound | |
283 | * endpoint on the component for this session | |
284 | * | |
285 | * @param message the message to send | |
286 | * @throws UMOException if there is no outbound endpoint configured on the | |
287 | * component or the events fails during dispatch | |
288 | */ | |
289 | void dispatchEvent(UMOMessage message) throws UMOException; | |
290 | ||
291 | /** | |
292 | * This will dispatch an event asynchronously via the configured outbound | |
293 | * endpoint on the component for this session | |
294 | * | |
295 | * @param payload the message payloadto send | |
296 | * @throws UMOException if there is no outbound endpoint configured on the | |
297 | * component or the events fails during dispatch | |
298 | */ | |
299 | void dispatchEvent(Object payload) throws UMOException; | |
300 | ||
301 | /** | |
302 | * Depending on the session state this methods either Passes an event | |
303 | * asynchronously to the next available Mule UMO in the pool or via the endpoint | |
304 | * configured for the event | |
305 | * | |
306 | * @param message the event message payload to send | |
307 | * @param endpoint the endpointUri to dispatc the event to first on the component | |
308 | * configuration and then on the mule manager configuration | |
309 | * @throws UMOException if the event fails to be processed by the component or | |
310 | * the transport for the endpoint | |
311 | */ | |
312 | void dispatchEvent(UMOMessage message, UMOEndpointURI endpoint) throws UMOException; | |
313 | ||
314 | /** | |
315 | * Depending on the session state this methods either Passes an event | |
316 | * asynchronously to the next available Mule UMO in the pool or via the endpoint | |
317 | * configured for the event. | |
318 | * | |
319 | * @param message the event message payload to send | |
320 | * @param endpointName The endpoint name to disptch the event through. This will | |
321 | * be looked up first on the component configuration and then on the | |
322 | * mule manager configuration | |
323 | * @throws UMOException if the event fails to be processed by the component or | |
324 | * the transport for the endpoint | |
325 | */ | |
326 | void dispatchEvent(UMOMessage message, String endpointName) throws UMOException; | |
327 | ||
328 | /** | |
329 | * Depending on the session state this methods either Passes an event | |
330 | * asynchronously to the next available Mule UMO in the pool or via the endpoint | |
331 | * configured for the event | |
332 | * | |
333 | * @param message the event message payload to send | |
334 | * @param endpoint The endpoint name to disptch the event through. | |
335 | * @throws UMOException if the event fails to be processed by the component or | |
336 | * the transport for the endpoint | |
337 | */ | |
338 | void dispatchEvent(UMOMessage message, UMOEndpoint endpoint) throws UMOException; | |
339 | ||
340 | /** | |
341 | * Requests a synchronous receive of an event on the component. | |
342 | * | |
343 | * @param endpoint the endpoint identifying the endpointUri on which the event | |
344 | * will be received | |
345 | * @param timeout time in milliseconds before the request times out | |
346 | * @return The requested event or null if the request times out | |
347 | * @throws UMOException if the request operation fails | |
348 | */ | |
349 | UMOMessage receiveEvent(UMOEndpoint endpoint, long timeout) throws UMOException; | |
350 | ||
351 | /** | |
352 | * Requests a synchronous receive of an event on the component. | |
353 | * | |
354 | * @param endpointName the endpoint identifying the endpointUri on which the | |
355 | * event will be received | |
356 | * @param timeout time in milliseconds before the request timesout | |
357 | * @return The requested event or null if the request times out | |
358 | * @throws UMOException if the request operation fails | |
359 | */ | |
360 | UMOMessage receiveEvent(String endpointName, long timeout) throws UMOException; | |
361 | ||
362 | /** | |
363 | * Requests a synchronous receive of an event on the component. | |
364 | * | |
365 | * @param endpoint the endpointUri on which the event will be received | |
366 | * @param timeout time in milliseconds before the request timesout | |
367 | * @return The requested event or null if the request times out | |
368 | * @throws UMOException if the request operation fails | |
369 | */ | |
370 | UMOMessage receiveEvent(UMOEndpointURI endpoint, long timeout) throws UMOException; | |
371 | ||
372 | UMODescriptor getComponentDescriptor(); | |
373 | ||
374 | /** | |
375 | * Determines whether the default processing for this event will be executed. By | |
376 | * default, the Mule server will route events according to a components | |
377 | * configuration. The user can override this behaviour by obtaining a reference | |
378 | * to the Event context, either by implementing | |
379 | * <code>org.mule.umo.lifecycle.Callable</code> or calling | |
380 | * <code>UMOManager.getEventContext</code> to obtain the UMOEventContext for | |
381 | * the current thread. The user can programmatically control how events are | |
382 | * dispached. | |
383 | * | |
384 | * @return Returns true is the user has set stopFurtherProcessing. | |
385 | * @see org.mule.umo.manager.UMOManager | |
386 | * @see UMOEventContext | |
387 | * @see org.mule.umo.lifecycle.Callable | |
388 | */ | |
389 | boolean isStopFurtherProcessing(); | |
390 | ||
391 | /** | |
392 | * Determines whether the default processing for this event will be executed. By | |
393 | * default, the Mule server will route events according to a components | |
394 | * configuration. The user can override this behaviour by obtaining a reference | |
395 | * to the Event context, either by implementing | |
396 | * <code>org.mule.umo.lifecycle.Callable</code> or calling | |
397 | * <code>UMOManager.getEventContext</code> to obtain the UMOEventContext for | |
398 | * the current thread. The user can programmatically control how events are | |
399 | * dispached. | |
400 | * | |
401 | * @param stopFurtherProcessing the value to set. | |
402 | */ | |
403 | void setStopFurtherProcessing(boolean stopFurtherProcessing); | |
404 | ||
405 | /** | |
406 | * An outputstream the can optionally be used write response data to an incoming | |
407 | * message. | |
408 | * | |
409 | * @return an output strem if one has been made available by the message receiver | |
410 | * that received the message | |
411 | */ | |
412 | OutputStream getOutputStream(); | |
413 | ||
414 | /** | |
415 | * Determines whether the was sent synchrounously or not | |
416 | * | |
417 | * @return true if the event is synchronous | |
418 | */ | |
419 | boolean isSynchronous(); | |
420 | ||
421 | /** | |
422 | * Returns a reference to the Endpoint Uri for this context This is the endpoint | |
423 | * on which the event was received | |
424 | * | |
425 | * @return the receive endpoint for this event context | |
426 | */ | |
427 | UMOEndpointURI getEndpointURI(); | |
428 | ||
429 | /** | |
430 | * Returns the transaction for the current event or null if there is no | |
431 | * transaction in progresss | |
432 | * | |
433 | * @return the transaction for the current event or null if there is no | |
434 | * transaction in progresss | |
435 | */ | |
436 | UMOTransaction getTransaction(); | |
437 | ||
438 | /** | |
439 | * Get the timeout value associated with the event | |
440 | * | |
441 | * @return the timeout for the event | |
442 | */ | |
443 | int getTimeout(); | |
444 | ||
445 | /** | |
446 | * Determines whether the event flow is being streamed | |
447 | * | |
448 | * @return true if the request should be streamed | |
449 | */ | |
450 | boolean isStreaming(); | |
451 | ||
452 | /** | |
453 | * Gets the encoding for the current message. For potocols that send encoding | |
454 | * Information with the message, this method should be overriden to expose the | |
455 | * transport encoding, otherwise the default encoding in the Mule configuration | |
456 | * will be used | |
457 | * | |
458 | * @return the encoding for this message. This method must never return null | |
459 | */ | |
460 | String getEncoding(); | |
461 | ||
462 | UMOSession getSession(); | |
463 | } |