UMOEventContext


1   /*
2    * $Id: UMOEventContext.java 3798 2006-11-04 04:07:14Z aperepel $
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 MuleSource MPL
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   * @author <a HREF="mailto:ross.mason@symphonysoft.com">Ross Mason</a>
25   * @version $Revision: 3798 $
26   */
27  public interface UMOEventContext
28  {
29      /**
30       * Returns the message payload for this event
31       * 
32       * @return the message payload for this event
33       */
34      UMOMessage getMessage();
35  
36      /**
37       * Returns the contents of the message as a byte array.
38       * 
39       * @return the contents of the message as a byte array
40       * @throws UMOException if the message cannot be converted into an array of bytes
41       */
42      byte[] getMessageAsBytes() throws UMOException;
43  
44      /**
45       * Returns the message transformed into it's recognised or expected format. The
46       * transformer used is the one configured on the endpoint through which this
47       * event was received.
48       * 
49       * @return the message transformed into it's recognised or expected format.
50       * @throws org.mule.umo.transformer.TransformerException if a failure occurs in
51       *             the transformer
52       * @see org.mule.umo.transformer.UMOTransformer
53       */
54      Object   getTransformedMessage() throws TransformerException;
55  
56      /**
57       * Returns the message transformed into it's recognised or expected format. The
58       * transformer used is the one configured on the endpoint through which this
59       * event was received.
60       * 
61       * @param expectedType The class type required for the return object. This param
62       *            just provides a convienient way to manage type casting of
63       *            transformed objects
64       * @return the message transformed into it's recognised or expected format.
65       * @throws org.mule.umo.transformer.TransformerException if a failure occurs or
66       *             if the return type is not the same as the expected type in the
67       *             transformer
68       * @see org.mule.umo.transformer.UMOTransformer
69       */
70      Object   getTransformedMessage(Class   expectedType) throws TransformerException;
71  
72      /**
73       * Returns the message transformed into it's recognised or expected format and
74       * then into an array of bytes. The transformer used is the one configured on the
75       * endpoint through which this event was received.
76       * 
77       * @return the message transformed into it's recognised or expected format as an
78       *         array of bytes.
79       * @throws TransformerException if a failure occurs in the transformer
80       * @see org.mule.umo.transformer.UMOTransformer
81       */
82      byte[] getTransformedMessageAsBytes() throws TransformerException;
83  
84      /**
85       * Returns the message transformed into it's recognised or expected format and
86       * then into a String. The transformer used is the one configured on the endpoint
87       * through which this event was received. This method will use the encoding set
88       * on the event
89       * 
90       * @return the message transformed into it's recognised or expected format as a
91       *         Strings.
92       * @throws TransformerException if a failure occurs in the transformer
93       * @see org.mule.umo.transformer.UMOTransformer
94       */
95      String   getTransformedMessageAsString() throws TransformerException;
96  
97      /**
98       * Returns the message contents as a string This method will use the encoding set
99       * on the event
100      * 
101      * @return the message contents as a string
102      * @throws UMOException if the message cannot be converted into a string
103      */
104     String   getMessageAsString() throws UMOException;
105 
106     /**
107      * Returns the message transformed into it's recognised or expected format and
108      * then into a String. The transformer used is the one configured on the endpoint
109      * through which this event was received.
110      * 
111      * @param encoding The encoding to use when transforming the message
112      * @return the message transformed into it's recognised or expected format as a
113      *         Strings.
114      * @throws TransformerException if a failure occurs in the transformer
115      * @see org.mule.umo.transformer.UMOTransformer
116      */
117     String   getTransformedMessageAsString(String   encoding) throws TransformerException;
118 
119     /**
120      * Returns the message contents as a string
121      * 
122      * @param encoding The encoding to use when transforming the message
123      * @return the message contents as a string
124      * @throws UMOException if the message cannot be converted into a string
125      */
126     String   getMessageAsString(String   encoding) throws UMOException;
127 
128     /**
129      * Returns the current transaction (if any) for the session
130      * 
131      * @return the current transaction for the session or null if there is no
132      *         transaction in progress
133      */
134     UMOTransaction getCurrentTransaction();
135 
136     /**
137      * Mark the current transaction (if any) for rollback
138      * 
139      * @throws TransactionException
140      */
141     void markTransactionForRollback() throws TransactionException;
142 
143     /**
144      * This will send an event via the configured outbound router on the component
145      * 
146      * @param message the message to send
147      * @return the result of the send if any
148      * @throws UMOException if there is no outbound endpoint configured on the
149      *             component or the events fails during dispatch
150      */
151     UMOMessage sendEvent(Object   message) throws UMOException;
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 message payload to send
159      * @return the return Message from the call or null if there was no result
160      * @throws UMOException if the event fails to be processed by the component or
161      *             the transport for the endpoint
162      */
163     UMOMessage sendEvent(UMOMessage message) throws UMOException;
164 
165     /**
166      * Depending on the session state this methods either Passes an event
167      * synchronously to the next available Mule UMO 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 UMOException if the event fails to be processed by the component or
174      *             the transport for the endpoint
175      */
176     UMOMessage sendEvent(UMOMessage message, UMOEndpointURI endpoint) throws UMOException;
177 
178     /**
179      * Depending on the session state this methods either Passes an event
180      * synchronously to the next available Mule UMO in the pool or via the endpoint
181      * configured for the event
182      * 
183      * @param message the event message payload to send
184      * @param endpointName The endpoint name to disptch the event through. This will
185      *            be looked up first on the component configuration and then on the
186      *            mule manager configuration
187      * @return the return Message from the call or null if there was no result
188      * @throws UMOException if the event fails to be processed by the component or
189      *             the transport for the endpoint
190      */
191     UMOMessage sendEvent(UMOMessage message, String   endpointName) throws UMOException;
192 
193     /**
194      * Depending on the session state this methods either Passes an event
195      * synchronously to the next available Mule UMO in the pool or via the endpoint
196      * configured for the event
197      * 
198      * @param message the event message payload to send
199      * @param endpoint The endpoint to disptch the event through.
200      * @return the return Message from the call or null if there was no result
201      * @throws UMOException if the event fails to be processed by the component or
202      *             the transport for the endpoint
203      */
204     UMOMessage sendEvent(UMOMessage message, UMOEndpoint endpoint) throws UMOException;
205 
206     /**
207      * sends an event request via the configured outbound router for this component.
208      * This method return immediately, but the result of the event invocation
209      * available from the returned a Future result that can be accessed later by the
210      * the returned FutureMessageResult. the Future messageResult can be queried at
211      * any time to check that the invocation has completed. A timeout is associated
212      * with the invocation, which is the maximum time in milli-seconds that the
213      * invocation should take to complete
214      * 
215      * @param message the object that is the payload of the event
216      * @param timeout how long to block in milliseconds waiting for a result
217      * @return the result message if any of the invocation
218      * @throws org.mule.umo.UMOException if the dispatch fails or the components or
219      *             transfromers cannot be found
220      * @see FutureMessageResult
221      */
222     FutureMessageResult sendEventAsync(Object   message, int timeout) throws UMOException;
223 
224     /**
225      * sends an event request via the configured outbound router for this component.
226      * This method return immediately, but the result of the event invocation
227      * available from the returned a Future result that can be accessed later by the
228      * the returned FutureMessageResult. the Future messageResult can be queried at
229      * any time to check that the invocation has completed. A timeout is associated
230      * with the invocation, which is the maximum time in milli-seconds that the
231      * invocation should take to complete
232      * 
233      * @param message the UMOMessage of the event
234      * @param timeout how long to block in milliseconds waiting for a result
235      * @return the result message if any of the invocation
236      * @throws org.mule.umo.UMOException if the dispatch fails or the components or
237      *             transfromers cannot be found
238      * @see FutureMessageResult
239      */
240     FutureMessageResult sendEventAsync(UMOMessage message, int timeout) throws UMOException;
241 
242     /**
243      * sends an event request via the configured outbound router for this component.
244      * This method return immediately, but the result of the event invocation
245      * available from the returned a Future result that can be accessed later by the
246      * the returned FutureMessageResult. the Future messageResult can be queried at
247      * any time to check that the invocation has completed. A timeout is associated
248      * with the invocation, which is the maximum time in milli-seconds that the
249      * invocation should take to complete
250      * 
251      * @param message the UMOMessage of the event
252      * @param endpoint the endpointUri to dispatch to
253      * @param timeout how long to block in milliseconds waiting for a result
254      * @return the result message if any of the invocation
255      * @throws org.mule.umo.UMOException if the dispatch fails or the components or
256      *             transfromers cannot be found
257      * @see FutureMessageResult
258      */
259     FutureMessageResult sendEventAsync(UMOMessage message, UMOEndpointURI endpoint, int timeout)
260         throws UMOException;
261 
262     /**
263      * sends an event request via the configured outbound router for this component.
264      * This method return immediately, but the result of the event invocation
265      * available from the returned a Future result that can be accessed later by the
266      * the returned FutureMessageResult. the Future messageResult can be queried at
267      * any time to check that the invocation has completed. A timeout is associated
268      * with the invocation, which is the maximum time in milli-seconds that the
269      * invocation should take to complete
270      * 
271      * @param message the UMOMessage of the event
272      * @param endpointName The endpoint name to disptch the event through. This will
273      *            be looked up first on the component configuration and then on the
274      *            mule manager configuration
275      * @param timeout how long to block in milliseconds waiting for a result
276      * @return the result message if any of the invocation
277      * @throws org.mule.umo.UMOException if the dispatch fails or the components or
278      *             transfromers cannot be found
279      * @see FutureMessageResult
280      */
281     FutureMessageResult sendEventAsync(UMOMessage message, String   endpointName, int timeout)
282         throws UMOException;
283 
284     /**
285      * This will dispatch an event asynchronously via the configured outbound
286      * endpoint on the component for this session
287      * 
288      * @param message the message to send
289      * @throws UMOException if there is no outbound endpoint configured on the
290      *             component or the events fails during dispatch
291      */
292     void dispatchEvent(UMOMessage message) throws UMOException;
293 
294     /**
295      * This will dispatch an event asynchronously via the configured outbound
296      * endpoint on the component for this session
297      * 
298      * @param payload the message payloadto send
299      * @throws UMOException if there is no outbound endpoint configured on the
300      *             component or the events fails during dispatch
301      */
302     void dispatchEvent(Object   payload) throws UMOException;
303 
304     /**
305      * Depending on the session state this methods either Passes an event
306      * asynchronously to the next available Mule UMO in the pool or via the endpoint
307      * configured for the event
308      * 
309      * @param message the event message payload to send
310      * @param endpoint the endpointUri to dispatc the event to first on the component
311      *            configuration and then on the mule manager configuration
312      * @throws UMOException if the event fails to be processed by the component or
313      *             the transport for the endpoint
314      */
315     void dispatchEvent(UMOMessage message, UMOEndpointURI endpoint) throws UMOException;
316 
317     /**
318      * Depending on the session state this methods either Passes an event
319      * asynchronously to the next available Mule UMO in the pool or via the endpoint
320      * configured for the event
321      * 
322      * @param message the event message payload to send
323      * @param endpointName The endpoint name to disptch the event through. This will
324      *            be looked up first on the component configuration and then on the
325      *            mule manager configuration
326      * @throws UMOException if the event fails to be processed by the component or
327      *             the transport for the endpoint
328      */
329     void dispatchEvent(UMOMessage message, String   endpointName) throws UMOException;
330 
331     /**
332      * Depending on the session state this methods either Passes an event
333      * asynchronously to the next available Mule UMO in the pool or via the endpoint
334      * configured for the event
335      * 
336      * @param message the event message payload to send
337      * @param endpoint The endpoint name to disptch the event through.
338      * @throws UMOException if the event fails to be processed by the component or
339      *             the transport for the endpoint
340      */
341     void dispatchEvent(UMOMessage message, UMOEndpoint endpoint) throws UMOException;
342 
343     /**
344      * Requests a synchronous receive of an event on the component
345      * 
346      * @param endpoint the endpoint identifing the endpointUri on ewhich the event
347      *            will be received
348      * @param timeout time in milliseconds before the request timesout
349      * @return The requested event or null if the request times out
350      * @throws UMOException if the request operation fails
351      */
352     UMOMessage receiveEvent(UMOEndpoint endpoint, long timeout) throws UMOException;
353 
354     /**
355      * Requests a synchronous receive of an event on the component
356      * 
357      * @param endpointName the endpoint identifing the endpointUri on ewhich the
358      *            event will be received
359      * @param timeout time in milliseconds before the request timesout
360      * @return The requested event or null if the request times out
361      * @throws UMOException if the request operation fails
362      */
363     UMOMessage receiveEvent(String   endpointName, long timeout) throws UMOException;
364 
365     /**
366      * Requests a synchronous receive of an event on the component
367      * 
368      * @param endpoint the endpointUri on which the event will be received
369      * @param timeout time in milliseconds before the request timesout
370      * @return The requested event or null if the request times out
371      * @throws UMOException if the request operation fails
372      */
373     UMOMessage receiveEvent(UMOEndpointURI endpoint, long timeout) throws UMOException;
374 
375     UMODescriptor getComponentDescriptor();
376 
377     /**
378      * Gets a property associated with the current event. Calling this method is
379      * equivilent to calling <code>event.getMessage().getProperty(...)</code>
380      * 
381      * @param name the property name
382      * @return the property value or null if the property does not exist
383      * @deprecated use eventContext.getMessage().getProperty()
384      */
385     Object   getProperty(String   name);
386 
387     /**
388      * Gets a property associated with the current event. Calling this method is
389      * equivilent to calling <code>event.getMessage().getProperty(..., ...)</code>
390      * 
391      * @param name the property name
392      * @param defaultValue a default value if the property doesn't exist in the event
393      * @return the property value or the defaultValue if the property does not exist
394      * @deprecated use eventContext.getMessage().getProperty()
395      */
396     Object   getProperty(String   name, Object   defaultValue);
397 
398     /**
399      * Gets a property associated with the current event. Calling this method is
400      * equivilent to calling <code>event.getMessage().getProperty(...)</code> This
401      * will convert the returned value into a string
402      * 
403      * @param name the property name
404      * @return the property value or null if the property does not exist
405      * @deprecated use eventContext.getMessage().getStringProperty()
406      */
407     String   getStringProperty(String   name);
408 
409     /**
410      * Gets a String property associated with the current event. Calling this method
411      * is equivilent to calling <code>event.getMessage().getProperty(..., ...)</code>
412      * This will convert the returned value into a string
413      * 
414      * @param name the property name
415      * @param defaultValue a default value if the property doesn't exist in the event
416      * @return the property value or the defaultValue if the property does not exist
417      * @deprecated use eventContext.getMessage().getStringProperty()
418      */
419     String   getStringProperty(String   name, String   defaultValue);
420 
421     /**
422      * Gets an Integer property associated with the current event. Calling this
423      * method is equivilent to calling
424      * <code>event.getMessage().getIntProperty(..., ...)</code>
425      * 
426      * @param name the property name
427      * @param defaultValue a default value if the property doesn't exist in the event
428      * @return the property value or the defaultValue if the property does not exist
429      * @deprecated use eventContext.getMessage().getIntProperty()
430      */
431     int getIntProperty(String   name, int defaultValue);
432 
433     /**
434      * Gets a Long property associated with the current event. Calling this method is
435      * equivilent to calling
436      * <code>event.getMessage().getLongProperty(..., ...)</code>
437      * 
438      * @param name the property name
439      * @param defaultValue a default value if the property doesn't exist in the event
440      * @return the property value or the defaultValue if the property does not exist
441      * @deprecated use eventContext.getMessage().getLongProperty()
442      */
443     long getLongProperty(String   name, long defaultValue);
444 
445     /**
446      * Gets a Double property associated with the current event. Calling this method
447      * is equivilent to calling
448      * <code>event.getMessage().getDoubleProperty(..., ...)</code>
449      * 
450      * @param name the property name
451      * @param defaultValue a default value if the property doesn't exist in the event
452      * @return the property value or the defaultValue if the property does not exist
453      * @deprecated use eventContext.getMessage().getDoubleProperty()
454      */
455     double getDoubleProperty(String   name, double defaultValue);
456 
457     /**
458      * Gets a Boolean property associated with the current event. Calling this method
459      * is equivilent to calling
460      * <code>event.getMessage().getbooleanProperty(..., ...)</code>
461      * 
462      * @param name the property name
463      * @param defaultValue a default value if the property doesn't exist in the event
464      * @return the property value or the defaultValue if the property does not exist
465      * @deprecated use eventContext.getMessage().getBooleanProperty()
466      */
467     boolean getBooleanProperty(String   name, boolean defaultValue);
468 
469     /**
470      * Sets a property associated with the current event. Calling this method is
471      * equivilent to calling <code>event.getMessage().setProperty(..., ...)</code>
472      * 
473      * @param name the property name or key
474      * @param value the property value
475      * @deprecated use eventContext.getMessage().setProperty()
476      */
477     void setProperty(String   name, Object   value);
478 
479     /**
480      * Sets a Boolean property associated with the current event. Calling this method
481      * is equivilent to calling
482      * <code>event.getMessage().setBooleanProperty(..., ...)</code>
483      * 
484      * @param name the property name or key
485      * @param value the property value
486      * @deprecated use eventContext.getMessage().setBooleanProperty()
487      */
488     void setBooleanProperty(String   name, boolean value);
489 
490     /**
491      * Sets an Integer property associated with the current event. Calling this
492      * method is equivilent to calling
493      * <code>event.getMessage().setIntProperty(..., ...)</code>
494      * 
495      * @param name the property name or key
496      * @param value the property value
497      * @deprecated use eventContext.getMessage().setIntProperty()
498      */
499     void setIntProperty(String   name, int value);
500 
501     /**
502      * Sets a Long property associated with the current event. Calling this method is
503      * equivilent to calling
504      * <code>event.getMessage().setLongProperty(..., ...)</code>
505      * 
506      * @param name the property name or key
507      * @param value the property value
508      * @deprecated use eventContext.getMessage().setLongProperty()
509      */
510     void setLongProperty(String   name, long value);
511 
512     /**
513      * Sets a Double property associated with the current event. Calling this method
514      * is equivilent to calling
515      * <code>event.getMessage().setDoubleProperty(..., ...)</code>
516      * 
517      * @param name the property name or key
518      * @param value the property value
519      * @deprecated use eventContext.getMessage().setDoubleProperty()
520      */
521     void setDoubleProperty(String   name, double value);
522 
523     /**
524      * Determines whether the default processing for this event will be executed. By
525      * default, the Mule server will route events according to a components
526      * configuration. The user can override this behaviour by obtaining a reference
527      * to the Event context, either by implementing
528      * <code>org.mule.umo.lifecycle.Callable</code> or calling
529      * <code>UMOManager.getEventContext</code> to obtain the UMOEventContext for
530      * the current thread. The user can programmatically control how events are
531      * dispached.
532      * 
533      * @return Returns true is the user has set stopFurtherProcessing.
534      * @see org.mule.umo.manager.UMOManager
535      * @see UMOEventContext
536      * @see org.mule.umo.lifecycle.Callable
537      */
538     boolean isStopFurtherProcessing();
539 
540     /**
541      * Determines whether the default processing for this event will be executed. By
542      * default, the Mule server will route events according to a components
543      * configuration. The user can override this behaviour by obtaining a reference
544      * to the Event context, either by implementing
545      * <code>org.mule.umo.lifecycle.Callable</code> or calling
546      * <code>UMOManager.getEventContext</code> to obtain the UMOEventContext for
547      * the current thread. The user can programmatically control how events are
548      * dispached.
549      * 
550      * @param stopFurtherProcessing the value to set.
551      */
552     void setStopFurtherProcessing(boolean stopFurtherProcessing);
553 
554     /**
555      * An outputstream the can optionally be used write response data to an incoming
556      * message.
557      * 
558      * @return an output strem if one has been made available by the message receiver
559      *         that received the message
560      */
561     OutputStream   getOutputStream();
562 
563     /**
564      * Determines whether the was sent synchrounously or not
565      * 
566      * @return true if the event is synchronous
567      */
568     boolean isSynchronous();
569 
570     /**
571      * Returns a reference to the Endpoint Uri for this context This is the endpoint
572      * on which the event was received
573      * 
574      * @return the receive endpoint for this event context
575      */
576     UMOEndpointURI getEndpointURI();
577 
578     /**
579      * Returns the transaction for the current event or null if there is no
580      * transaction in progresss
581      * 
582      * @return the transaction for the current event or null if there is no
583      *         transaction in progresss
584      */
585     UMOTransaction getTransaction();
586 
587     /**
588      * Get the timeout value associated with the event
589      * 
590      * @return the timeout for the event
591      */
592     int getTimeout();
593 
594     /**
595      * Determines whether the event flow is being streamed
596      * 
597      * @return true if the request should be streamed
598      */
599     boolean isStreaming();
600 
601     /**
602      * Gets the encoding for the current message. For potocols that send encoding
603      * Information with the message, this method should be overriden to expose the
604      * transport encoding, otherwise the default encoding in the Mule configuration
605      * will be used
606      * 
607      * @return the encoding for this message. This method must never return null
608      */
609     public String   getEncoding();
610 
611     UMOSession getSession();
612 }
613
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags