View Javadoc

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