KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > mule > umo > 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 JavaDoc;
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 JavaDoc 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 JavaDoc getTransformedMessage(Class JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getTransformedMessageAsString(String JavaDoc 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 JavaDoc getMessageAsString(String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getProperty(String JavaDoc 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 JavaDoc getProperty(String JavaDoc name, Object JavaDoc 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 JavaDoc getStringProperty(String JavaDoc 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 JavaDoc getStringProperty(String JavaDoc name, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc name, Object JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getEncoding();
610
611     UMOSession getSession();
612 }
613
Popular Tags