View Javadoc

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