View Javadoc

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