View Javadoc

1   /*
2    * $Id: UMOEvent.java 7963 2007-08-21 08:53:15Z dirk.olmes $
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.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   */
29  public interface UMOEvent
30  {
31      int TIMEOUT_WAIT_FOREVER = 0;
32      int TIMEOUT_DO_NOT_WAIT = -1;
33      int TIMEOUT_NOT_SET_VALUE = Integer.MIN_VALUE;
34  
35      /**
36       * Returns the message payload for this event
37       * 
38       * @return the message payload for this event
39       */
40      UMOMessage getMessage();
41  
42      UMOCredentials getCredentials();
43  
44      /**
45       * Reterns the conents of the message as a byte array.
46       * 
47       * @return the conents of the message as a byte array
48       * @throws UMOException if the message cannot be converted into an array of bytes
49       */
50      byte[] getMessageAsBytes() throws UMOException;
51  
52      /**
53       * Returns the message transformed into it's recognised or expected format. The
54       * transformer used is the one configured on the endpoint through which this
55       * event was received.
56       * 
57       * @return the message transformed into it's recognised or expected format.
58       * @throws TransformerException if a failure occurs in the transformer
59       * @see org.mule.umo.transformer.UMOTransformer
60       */
61      Object getTransformedMessage() throws TransformerException;
62  
63      /**
64       * Returns the message transformed into it's recognised or expected format and
65       * then into an array of bytes. The transformer used is the one configured on the
66       * endpoint through which this event was received.
67       * 
68       * @return the message transformed into it's recognised or expected format as an
69       *         array of bytes.
70       * @throws TransformerException if a failure occurs in the transformer
71       * @see org.mule.umo.transformer.UMOTransformer
72       */
73      byte[] getTransformedMessageAsBytes() throws TransformerException;
74  
75      /**
76       * Returns the message transformed into it's recognised or expected format and
77       * then into a String. The transformer used is the one configured on the endpoint
78       * through which this event was received. If necessary this will use the encoding
79       * set on the event
80       * 
81       * @return the message transformed into it's recognised or expected format as a
82       *         Strings.
83       * @throws TransformerException if a failure occurs in the transformer
84       * @see org.mule.umo.transformer.UMOTransformer
85       */
86      String getTransformedMessageAsString() throws TransformerException;
87  
88      /**
89       * Returns the message contents as a string If necessary this will use the
90       * encoding set on the event
91       * 
92       * @return the message contents as a string
93       * @throws UMOException if the message cannot be converted into a string
94       */
95      String getMessageAsString() throws UMOException;
96  
97      /**
98       * Returns the message transformed into it's recognised or expected format and
99       * then into a String. The transformer used is the one configured on the endpoint
100      * through which this event was received.
101      * 
102      * @param encoding the encoding to use when converting the message to string
103      * @return the message transformed into it's recognised or expected format as a
104      *         Strings.
105      * @throws TransformerException if a failure occurs in the transformer
106      * @see org.mule.umo.transformer.UMOTransformer
107      */
108     String getTransformedMessageAsString(String encoding) throws TransformerException;
109 
110     /**
111      * Returns the message contents as a string
112      * 
113      * @param encoding the encoding to use when converting the message to string
114      * @return the message contents as a string
115      * @throws UMOException if the message cannot be converted into a string
116      */
117     String getMessageAsString(String encoding) throws UMOException;
118 
119     /**
120      * Every event in the system is assigned a universally unique id (UUID).
121      * 
122      * @return the unique identifier for the event
123      */
124     String getId();
125 
126     /**
127      * Gets a property associated with the current event. If
128      * <code>exhaustiveSearch</code> is true, the endpoint and connector associated
129      * with the event will also be searched for the property.
130      * 
131      * @param name the property name
132      * @param exhaustiveSearch also search the endpoint and connector for the
133      *            property
134      * @return the property value or null if the property does not exist
135      */
136     Object getProperty(String name, boolean exhaustiveSearch);
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 defaultValue a default value if the property doesn't exist in the event
145      * @param exhaustiveSearch also search the endpoint and connector for the
146      *            property
147      * @return the property value or the defaultValue if the property does not exist
148      */
149     Object getProperty(String name, Object defaultValue, boolean exhaustiveSearch);
150 
151     /**
152      * Gets the endpoint associated with this event
153      * 
154      * @return the endpoint associated with this event
155      */
156     UMOImmutableEndpoint getEndpoint();
157 
158     /**
159      * Retrieves the component session for the current event
160      * 
161      * @return the component session for the event
162      */
163     UMOSession getSession();
164 
165     /**
166      * Retrieves the component for the current event
167      * 
168      * @return the component for the event
169      */
170     UMOComponent getComponent();
171 
172     /**
173      * Determines whether the default processing for this event will be executed. By
174      * default, the Mule server will route events according to a components
175      * configuration. The user can override this behaviour by obtaining a reference
176      * to the Event context, either by implementing
177      * <code>org.mule.umo.lifecycle.Callable</code> or calling
178      * <code>UMOManager.getEventContext</code> to obtain the UMOEventContext for
179      * the current thread. The user can programmatically control how events are
180      * dispached.
181      * 
182      * @return Returns true is the user has set stopFurtherProcessing.
183      * @see org.mule.umo.manager.UMOManager
184      * @see UMOEventContext
185      * @see org.mule.umo.lifecycle.Callable
186      */
187     boolean isStopFurtherProcessing();
188 
189     /**
190      * Determines whether the default processing for this event will be executed. By
191      * default, the Mule server will route events according to a components
192      * configuration. The user can override this behaviour by obtaining a reference
193      * to the Event context, either by implementing
194      * <code>org.mule.umo.lifecycle.Callable</code> or calling
195      * <code>UMOManager.getEventContext</code> to obtain the UMOEventContext for
196      * the current thread. The user can programmatically control how events are
197      * dispached.
198      * 
199      * @param stopFurtherProcessing the value to set.
200      */
201     void setStopFurtherProcessing(boolean stopFurtherProcessing);
202 
203     /**
204      * Determines whether the was sent synchrounously or not
205      * 
206      * @return true if the event is synchronous
207      */
208     boolean isSynchronous();
209 
210     /**
211      * Determines whether the was sent synchrounously or not
212      * 
213      * @param value true if the event is synchronous
214      */
215     void setSynchronous(boolean value);
216 
217     /**
218      * The number of milliseconds to wait for a return event when running
219      * synchronously. 0 wait forever -1 try and receive, but do not wait or a
220      * positive millisecond value
221      * 
222      * @return the event timeout in milliseconds
223      */
224     int getTimeout();
225 
226     /**
227      * The number of milliseconds to wait for a return event when running
228      * synchronously. 0 wait forever -1 try and receive, but do not wait or a
229      * positive millisecod value
230      * 
231      * @param timeout the event timeout in milliseconds
232      */
233     void setTimeout(int timeout);
234 
235     /**
236      * An outputstream the can optionally be used write response data to an incoming
237      * message.
238      * 
239      * @return an output strem if one has been made available by the message receiver
240      *         that received the message
241      */
242     OutputStream getOutputStream();
243 
244     /**
245      * Determines whether the event flow is being streamed
246      * 
247      * @return true if the request should be streamed
248      */
249     boolean isStreaming();
250 
251     /**
252      * Gets the encoding for this message.
253      * 
254      * @return the encoding for the event. This must never return null.
255      */
256     String getEncoding();
257 
258 }