View Javadoc

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 }