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