View Javadoc
1   /*
2    * Copyright (c) MuleSoft, Inc.  All rights reserved.  http://www.mulesoft.com
3    * The software in this package is published under the terms of the CPAL v1.0
4    * license, a copy of which has been included with this distribution in the
5    * LICENSE.txt file.
6    */
7   package org.mule.api;
8   
9   import org.mule.api.construct.FlowConstruct;
10  import org.mule.api.endpoint.ImmutableEndpoint;
11  import org.mule.api.security.Credentials;
12  import org.mule.api.transformer.DataType;
13  import org.mule.api.transformer.TransformerException;
14  import org.mule.api.transport.ReplyToHandler;
15  import org.mule.management.stats.ProcessingTime;
16  
17  import java.io.OutputStream;
18  import java.io.Serializable;
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 component understands. The event can also maintain any number of
26   * properties that can be set and retrieved by Mule components.
27   * 
28   * @see MuleMessage
29   */
30  public interface MuleEvent extends Serializable
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       * Returns the contents of the message as a byte array.
47       * 
48       * @return the contents 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       * @deprecated Since Mule 3.0 this method does nothing.  The message is already transformed before the event reaches a component
62       * IF you need to have access to the original message, the must be no transformations before the component, this
63       * means that any 'connector-level' transfromers will have to be explicitly overriden via the service overrides on the connector.
64       */
65      @Deprecated
66      Object transformMessage() throws TransformerException;
67  
68      /**
69       * Transforms the message into the requested format. The transformer used is
70       * the one configured on the endpoint through which this event was received.
71       * 
72       * @param outputType The requested output type.
73       * @return the message transformed into it's recognised or expected format.
74       * @throws TransformerException if a failure occurs in the transformer
75       * @see org.mule.api.transformer.Transformer if the transform fails or the outputtype is null
76       */
77      <T> T transformMessage(Class<T> outputType) throws TransformerException;
78  
79       /**
80       * Transforms the message into the requested format. The transformer used is
81       * the one configured on the endpoint through which this event was received.
82       *
83       * @param outputType The requested output type.
84       * @return the message transformed into it's recognised or expected format.
85       * @throws TransformerException if a failure occurs in the transformer
86       * @see org.mule.api.transformer.Transformer if the transform fails or the outputtype is null
87       */
88      <T> T transformMessage(DataType<T> outputType) throws TransformerException;
89  
90      /**
91       * Transforms the message into it's recognised or expected format and then 
92       * into an array of bytes. The transformer used is the one configured on the
93       * endpoint through which this event was received.
94       * 
95       * @return the message transformed into it's recognised or expected format as an
96       *         array of bytes.
97       * @throws TransformerException if a failure occurs in the transformer
98       * @see org.mule.api.transformer.Transformer
99       * @deprecated use {@link #transformMessage(org.mule.api.transformer.DataType)} instead
100      */
101     @Deprecated
102     byte[] transformMessageToBytes() throws TransformerException;
103 
104     /**
105      * Returns the message transformed into it's recognised or expected format and
106      * then into a String. The transformer used is the one configured on the endpoint
107      * through which this event was received. If necessary this will use the encoding
108      * set on the event
109      * 
110      * @return the message transformed into it's recognised or expected format as a
111      *         Strings.
112      * @throws TransformerException if a failure occurs in the transformer
113      * @see org.mule.api.transformer.Transformer
114      */
115     String transformMessageToString() throws TransformerException;
116 
117     /**
118      * Returns the message contents as a string If necessary this will use the
119      * encoding set on the event
120      * 
121      * @return the message contents as a string
122      * @throws MuleException if the message cannot be converted into a string
123      */
124     String getMessageAsString() throws MuleException;
125 
126     /**
127      * Returns the message contents as a string
128      * 
129      * @param encoding the encoding to use when converting the message to string
130      * @return the message contents as a string
131      * @throws MuleException if the message cannot be converted into a string
132      */
133     String getMessageAsString(String encoding) throws MuleException;
134 
135     /**
136      * Every event in the system is assigned a universally unique id (UUID).
137      * 
138      * @return the unique identifier for the event
139      */
140     String getId();
141 
142     /**
143      * Gets a property associated with the current event. This method will check all property scopes on the currnet message
144      * and the current session
145      * 
146      * @param name the property name
147      * @return the property value or null if the property does not exist
148      * @deprecated
149      */
150     @Deprecated
151     Object getProperty(String name);
152 
153     /**
154      * Gets a property associated with the current event. This method will check all property scopes on the currnet message
155      * and the current session
156      * @param name the property name
157      * @param defaultValue a default value if the property doesn't exist in the event
158      * @return the property value or the defaultValue if the property does not exist
159      * @deprecated
160      */
161     @Deprecated
162     Object getProperty(String name, Object defaultValue);
163 
164     /**
165      * Gets the endpoint associated with this event
166      * 
167      * @return the endpoint associated with this event
168      */
169     ImmutableEndpoint getEndpoint();
170 
171     /**
172      * Retrieves the service session for the current event
173      * 
174      * @return the service session for the event
175      */
176     MuleSession getSession();
177 
178     /**
179      * Retrieves the service for the current event
180      * 
181      * @return the service for the event
182      */
183     FlowConstruct getFlowConstruct();
184 
185     /**
186      * Determines whether the default processing for this event will be executed. By
187      * default, the Mule server will route events according to a components
188      * configuration. The user can override this behaviour by obtaining a reference
189      * to the MuleEvent context, either by implementing
190      * <code>org.mule.api.lifecycle.Callable</code> or calling
191      * <code>RequestContext.getEventContext</code> to obtain the MuleEventContext for
192      * the current thread. The user can programmatically control how events are
193      * dispached.
194      * 
195      * @return Returns true is the user has set stopFurtherProcessing.
196      * @see org.mule.api.MuleContext
197      * @see MuleEventContext
198      * @see org.mule.api.lifecycle.Callable
199      */
200     boolean isStopFurtherProcessing();
201 
202     /**
203      * Determines whether the default processing for this event will be executed. By
204      * default, the Mule server will route events according to a components
205      * configuration. The user can override this behaviour by obtaining a reference
206      * to the MuleEvent context, either by implementing
207      * <code>org.mule.api.lifecycle.Callable</code> or calling
208      * <code>RequestContext.getEventContext</code> to obtain the MuleEventContext for
209      * the current thread. The user can programmatically control how events are
210      * dispached.
211      * 
212      * @param stopFurtherProcessing the value to set.
213      */
214     void setStopFurtherProcessing(boolean stopFurtherProcessing);
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 
256     /**
257      * Returns the times spent processing this event (so far)
258      */
259     ProcessingTime getProcessingTime();
260 
261     /**
262      * Return the replyToHandler (if any) that will be used to perform async reply
263      */
264     ReplyToHandler getReplyToHandler();
265 
266     /**
267      * Return the destination (if any) that will be passed to the reply-to handler.
268      */
269     Object getReplyToDestination();
270 
271     /**
272      * Set the reply-to destination from the current message, and remove it from the message, to
273      * prevent any further propagation.
274      */
275     void captureReplyToDestination();
276 }