View Javadoc

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