UMOEvent


1   /*
2    * $Id: UMOEvent.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.UMOImmutableEndpoint;
14  import org.mule.umo.security.UMOCredentials;
15  import org.mule.umo.transformer.TransformerException;
16  
17  import java.io.OutputStream  ;
18  
19  /**
20   * <code>UMOEvent</code> represents any data event occuring in the Mule
21   * environment. All data sent or received within the mule environment will be passed
22   * between components as an UMOEvent. <p/> <p/> The UMOEvent holds a UMOMessage
23   * payload and provides helper methods for obtaining the data in a format that the
24   * receiving Mule UMO understands. The event can also maintain any number of
25   * properties that can be set and retrieved by Mule UMO components.
26   * 
27   * @see UMOMessage
28   * @author <a HREF="mailto:ross.mason@symphonysoft.com">Ross Mason</a>
29   * @version $Revision: 3798 $
30   */
31  public interface UMOEvent
32  {
33      public static final int TIMEOUT_WAIT_FOREVER = 0;
34      public static final int TIMEOUT_DO_NOT_WAIT = -1;
35      public static final int TIMEOUT_NOT_SET_VALUE = Integer.MIN_VALUE;
36  
37      /**
38       * Returns the message payload for this event
39       * 
40       * @return the message payload for this event
41       */
42      UMOMessage getMessage();
43  
44      public UMOCredentials getCredentials();
45  
46      /**
47       * Reterns the conents of the message as a byte array.
48       * 
49       * @return the conents of the message as a byte array
50       * @throws UMOException if the message cannot be converted into an array of bytes
51       */
52      byte[] getMessageAsBytes() throws UMOException;
53  
54      /**
55       * Returns the message transformed into it's recognised or expected format. The
56       * transformer used is the one configured on the endpoint through which this
57       * event was received.
58       * 
59       * @return the message transformed into it's recognised or expected format.
60       * @throws TransformerException if a failure occurs in the transformer
61       * @see org.mule.umo.transformer.UMOTransformer
62       */
63      Object   getTransformedMessage() throws TransformerException;
64  
65      /**
66       * Returns the message transformed into it's recognised or expected format and
67       * then into an array of bytes. The transformer used is the one configured on the
68       * endpoint through which this event was received.
69       * 
70       * @return the message transformed into it's recognised or expected format as an
71       *         array of bytes.
72       * @throws TransformerException if a failure occurs in the transformer
73       * @see org.mule.umo.transformer.UMOTransformer
74       */
75      byte[] getTransformedMessageAsBytes() throws TransformerException;
76  
77      /**
78       * Returns the message transformed into it's recognised or expected format and
79       * then into a String. The transformer used is the one configured on the endpoint
80       * through which this event was received. If necessary this will use the encoding
81       * set on the event
82       * 
83       * @return the message transformed into it's recognised or expected format as a
84       *         Strings.
85       * @throws TransformerException if a failure occurs in the transformer
86       * @see org.mule.umo.transformer.UMOTransformer
87       */
88      String   getTransformedMessageAsString() throws TransformerException;
89  
90      /**
91       * Returns the message contents as a string If necessary this will use the
92       * encoding set on the event
93       * 
94       * @return the message contents as a string
95       * @throws UMOException if the message cannot be converted into a string
96       */
97      String   getMessageAsString() throws UMOException;
98  
99      /**
100      * Returns the message transformed into it's recognised or expected format and
101      * then into a String. The transformer used is the one configured on the endpoint
102      * through which this event was received.
103      * 
104      * @param encoding the encoding to use when converting the message to string
105      * @return the message transformed into it's recognised or expected format as a
106      *         Strings.
107      * @throws TransformerException if a failure occurs in the transformer
108      * @see org.mule.umo.transformer.UMOTransformer
109      */
110     String   getTransformedMessageAsString(String   encoding) throws TransformerException;
111 
112     /**
113      * Returns the message contents as a string
114      * 
115      * @param encoding the encoding to use when converting the message to string
116      * @return the message contents as a string
117      * @throws UMOException if the message cannot be converted into a string
118      */
119     String   getMessageAsString(String   encoding) throws UMOException;
120 
121     /**
122      * Every event in the system is assigned a universally unique id (UUID).
123      * 
124      * @return the unique identifier for the event
125      */
126     String   getId();
127 
128     /**
129      * Gets a property associated with the current event. Calling this method is
130      * equivilent to calling <code>event.getMessage().getProperty(...)</code>
131      * 
132      * @param name the property name
133      * @return the property value or null if the property does not exist
134      * @deprecated use event.getMessage().getProperty()
135      */
136     Object   getProperty(String   name);
137 
138     /**
139      * Gets a property associated with the current event. If
140      * <code>exhaustiveSearch</code> is true, the endpoint and connector associated
141      * with the event will also be searched for the property.
142      * 
143      * @param name the property name
144      * @param exhaustiveSearch also search the endpoint and connector for the
145      *            property
146      * @return the property value or null if the property does not exist
147      */
148     Object   getProperty(String   name, boolean exhaustiveSearch);
149 
150     /**
151      * Gets a property associated with the current event. Calling this method is
152      * equivilent to calling <code>event.getMessage().getProperty(..., ...)</code>
153      * 
154      * @param name the property name
155      * @param defaultValue a default value if the property doesn't exist in the event
156      * @return the property value or the defaultValue if the property does not exist
157      * @deprecated use event.getMessage().getProperty()
158      */
159     Object   getProperty(String   name, Object   defaultValue);
160 
161     /**
162      * Gets a property associated with the current event. If
163      * <code>exhaustiveSearch</code> is true, the endpoint and connector associated
164      * with the event will also be searched for the property.
165      * 
166      * @param name the property name
167      * @param defaultValue a default value if the property doesn't exist in the event
168      * @param exhaustiveSearch also search the endpoint and connector for the
169      *            property
170      * @return the property value or the defaultValue if the property does not exist
171      */
172     Object   getProperty(String   name, Object   defaultValue, boolean exhaustiveSearch);
173 
174     /**
175      * Gets an Integer property associated with the current event. Calling this
176      * method is equivilent to calling
177      * <code>event.getMessage().getIntProperty(..., ...)</code>
178      * 
179      * @param name the property name
180      * @param defaultValue a default value if the property doesn't exist in the event
181      * @return the property value or the defaultValue if the property does not exist
182      * @deprecated use event.getMessage().getProperty()
183      */
184     int getIntProperty(String   name, int defaultValue);
185 
186     /**
187      * Gets a Long property associated with the current event. Calling this method is
188      * equivilent to calling
189      * <code>event.getMessage().getLongProperty(..., ...)</code>
190      * 
191      * @param name the property name
192      * @param defaultValue a default value if the property doesn't exist in the event
193      * @return the property value or the defaultValue if the property does not exist
194      * @deprecated use event.getMessage().getProperty()
195      */
196     long getLongProperty(String   name, long defaultValue);
197 
198     /**
199      * Gets a Double property associated with the current event. Calling this method
200      * is equivilent to calling
201      * <code>event.getMessage().getDoubleProperty(..., ...)</code>
202      * 
203      * @param name the property name
204      * @param defaultValue a default value if the property doesn't exist in the event
205      * @return the property value or the defaultValue if the property does not exist
206      * @deprecated use event.getMessage().getProperty()
207      */
208     double getDoubleProperty(String   name, double defaultValue);
209 
210     /**
211      * Gets a Boolean property associated with the current event. Calling this method
212      * is equivilent to calling
213      * <code>event.getMessage().getbooleanProperty(..., ...)</code>
214      * 
215      * @param name the property name
216      * @param defaultValue a default value if the property doesn't exist in the event
217      * @return the property value or the defaultValue if the property does not exist
218      * @deprecated use event.getMessage().getProperty()
219      */
220     boolean getBooleanProperty(String   name, boolean defaultValue);
221 
222     /**
223      * Gets a String property associated with the current event. Calling this method
224      * is equivilent to calling
225      * <code>event.getMessage().getStringProperty(..., ...)</code>
226      * 
227      * @param name the property name
228      * @param defaultValue a default value if the property doesn't exist in the event
229      * @return the property value or the defaultValue if the property does not exist
230      * @deprecated use event.getMessage().getStringProperty()
231      */
232     String   getStringProperty(String   name, String   defaultValue);
233 
234     /**
235      * Sets a property associated with the current event. Calling this method is
236      * equivilent to calling <code>event.getMessage().setProperty(..., ...)</code>
237      * 
238      * @param name the property name or key
239      * @param value the property value
240      * @deprecated use event.getMessage().setProperty()
241      */
242     void setProperty(String   name, Object   value);
243 
244     /**
245      * Sets a Boolean property associated with the current event. Calling this method
246      * is equivilent to calling
247      * <code>event.getMessage().setBooleanProperty(..., ...)</code>
248      * 
249      * @param name the property name or key
250      * @param value the property value
251      * @deprecated use event.getMessage().setBooleanProperty()
252      */
253     void setBooleanProperty(String   name, boolean value);
254 
255     /**
256      * Sets an Integer property associated with the current event. Calling this
257      * method is equivilent to calling
258      * <code>event.getMessage().setIntProperty(..., ...)</code>
259      * 
260      * @param name the property name or key
261      * @param value the property value
262      * @deprecated use event.getMessage().setIntProperty()
263      */
264     void setIntProperty(String   name, int value);
265 
266     /**
267      * Sets a Long property associated with the current event. Calling this method is
268      * equivilent to calling
269      * <code>event.getMessage().setLongProperty(..., ...)</code>
270      * 
271      * @param name the property name or key
272      * @param value the property value
273      * @deprecated use event.getMessage().setLongProperty()
274      */
275     void setLongProperty(String   name, long value);
276 
277     /**
278      * Sets a Double property associated with the current event. Calling this method
279      * is equivilent to calling
280      * <code>event.getMessage().setDoubleProperty(..., ...)</code>
281      * 
282      * @param name the property name or key
283      * @param value the property value
284      * @deprecated use event.getMessage().setDoubleProperty()
285      */
286     void setDoubleProperty(String   name, double value);
287 
288     /**
289      * Sets a String property associated with the current event. Calling this method
290      * is equivilent to calling
291      * <code>event.getMessage().setStringProperty(..., ...)</code>
292      * 
293      * @param name the property name or key
294      * @param value the property value
295      * @deprecated use event.getMessage().setStringProperty()
296      */
297     void setStringProperty(String   name, String   value);
298 
299     /**
300      * Gets the endpoint associated with this event
301      * 
302      * @return the endpoint associated with this event
303      */
304     UMOImmutableEndpoint getEndpoint();
305 
306     /**
307      * Retrieves the component session for the current event
308      * 
309      * @return the component session for the event
310      */
311     UMOSession getSession();
312 
313     /**
314      * Retrieves the component for the current event
315      * 
316      * @return the component for the event
317      */
318     UMOComponent getComponent();
319 
320     /**
321      * Determines whether the default processing for this event will be executed. By
322      * default, the Mule server will route events according to a components
323      * configuration. The user can override this behaviour by obtaining a reference
324      * to the Event context, either by implementing
325      * <code>org.mule.umo.lifecycle.Callable</code> or calling
326      * <code>UMOManager.getEventContext</code> to obtain the UMOEventContext for
327      * the current thread. The user can programmatically control how events are
328      * dispached.
329      * 
330      * @return Returns true is the user has set stopFurtherProcessing.
331      * @see org.mule.umo.manager.UMOManager
332      * @see UMOEventContext
333      * @see org.mule.umo.lifecycle.Callable
334      */
335     boolean isStopFurtherProcessing();
336 
337     /**
338      * Determines whether the default processing for this event will be executed. By
339      * default, the Mule server will route events according to a components
340      * configuration. The user can override this behaviour by obtaining a reference
341      * to the Event context, either by implementing
342      * <code>org.mule.umo.lifecycle.Callable</code> or calling
343      * <code>UMOManager.getEventContext</code> to obtain the UMOEventContext for
344      * the current thread. The user can programmatically control how events are
345      * dispached.
346      * 
347      * @param stopFurtherProcessing the value to set.
348      */
349     void setStopFurtherProcessing(boolean stopFurtherProcessing);
350 
351     /**
352      * Determines whether the was sent synchrounously or not
353      * 
354      * @return true if the event is synchronous
355      */
356     boolean isSynchronous();
357 
358     /**
359      * Determines whether the was sent synchrounously or not
360      * 
361      * @param value true if the event is synchronous
362      */
363     void setSynchronous(boolean value);
364 
365     /**
366      * The number of milliseconds to wait for a return event when running
367      * synchronously. 0 wait forever -1 try and receive, but do not wait or a
368      * positive millisecond value
369      * 
370      * @return the event timeout in milliseconds
371      */
372     int getTimeout();
373 
374     /**
375      * The number of milliseconds to wait for a return event when running
376      * synchronously. 0 wait forever -1 try and receive, but do not wait or a
377      * positive millisecod value
378      * 
379      * @param timeout the event timeout in milliseconds
380      */
381     void setTimeout(int timeout);
382 
383     /**
384      * An outputstream the can optionally be used write response data to an incoming
385      * message.
386      * 
387      * @return an output strem if one has been made available by the message receiver
388      *         that received the message
389      */
390     OutputStream   getOutputStream();
391 
392     /**
393      * Removes a property from the event
394      * 
395      * @param key the property key to remove
396      * @return the removed property or null if the property was not found or if the
397      *         underlying message does not return the removed property
398      * @deprecated use event.getMessage().removeProperty()
399      */
400     Object   removeProperty(String   key);
401 
402     /**
403      * Determines whether the event flow is being streamed
404      * 
405      * @return true if the request should be streamed
406      */
407     boolean isStreaming();
408 
409     /**
410      * Gets the encoding for this message.
411      * 
412      * @return the encoding for the event. This must never return null.
413      */
414     String   getEncoding();
415 
416 }
417
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags