View Javadoc

1   /*
2    * $Id: MuleEvent.java 23054 2011-10-02 05:31:18Z dirk.olmes $
3    * --------------------------------------------------------------------------------------
4    * Copyright (c) MuleSoft, Inc.  All rights reserved.  http://www.mulesoft.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.MessageExchangePattern;
14  import org.mule.api.construct.FlowConstruct;
15  import org.mule.api.security.Credentials;
16  import org.mule.api.transformer.DataType;
17  import org.mule.api.transformer.TransformerException;
18  import org.mule.api.transport.ReplyToHandler;
19  import org.mule.management.stats.ProcessingTime;
20  
21  import java.io.OutputStream;
22  import java.io.Serializable;
23  import java.net.URI;
24  
25  /**
26   * <code>MuleEvent</code> represents any data event occuring in the Mule
27   * environment. All data sent or received within the mule environment will be passed
28   * between components as an MuleEvent. <p/> <p/> The MuleEvent holds a MuleMessage
29   * payload and provides helper methods for obtaining the data in a format that the
30   * receiving Mule component understands. The event can also maintain any number of
31   * properties that can be set and retrieved by Mule components.
32   * 
33   * @see MuleMessage
34   */
35  public interface MuleEvent extends Serializable
36  {
37      int TIMEOUT_WAIT_FOREVER = 0;
38      int TIMEOUT_DO_NOT_WAIT = -1;
39      int TIMEOUT_NOT_SET_VALUE = Integer.MIN_VALUE;
40  
41      /**
42       * Returns the message payload for this event
43       * 
44       * @return the message payload for this event
45       */
46      MuleMessage getMessage();
47  
48      Credentials getCredentials();
49  
50      /**
51       * Returns the contents of the message as a byte array.
52       * 
53       * @return the contents of the message as a byte array
54       * @throws MuleException if the message cannot be converted into an array of bytes
55       */
56      byte[] getMessageAsBytes() throws MuleException;
57  
58      /**
59       * Transforms the message into it's recognised or expected format. The
60       * transformer used is the one configured on the endpoint through which this
61       * event was received.
62       *
63       * @return the message transformed into it's recognised or expected format.
64       * @throws TransformerException if a failure occurs in the transformer
65       * @see org.mule.api.transformer.Transformer
66       * @deprecated Since Mule 3.0 this method does nothing.  The message is already transformed before the event reaches a component
67       * IF you need to have access to the original message, the must be no transformations before the component, this
68       * means that any 'connector-level' transfromers will have to be explicitly overriden via the service overrides on the connector.
69       */
70      @Deprecated
71      Object transformMessage() throws TransformerException;
72  
73      /**
74       * Transforms the message into the requested format. The transformer used is
75       * the one configured on the endpoint through which this event was received.
76       * 
77       * @param outputType The requested output type.
78       * @return the message transformed into it's recognised or expected format.
79       * @throws TransformerException if a failure occurs in the transformer
80       * @see org.mule.api.transformer.Transformer if the transform fails or the outputtype is null
81       */
82      <T> T transformMessage(Class<T> outputType) throws TransformerException;
83  
84       /**
85       * Transforms the message into the requested format. The transformer used is
86       * the one configured on the endpoint through which this event was received.
87       *
88       * @param outputType The requested output type.
89       * @return the message transformed into it's recognised or expected format.
90       * @throws TransformerException if a failure occurs in the transformer
91       * @see org.mule.api.transformer.Transformer if the transform fails or the outputtype is null
92       */
93      <T> T transformMessage(DataType<T> outputType) throws TransformerException;
94  
95      /**
96       * Transforms the message into it's recognised or expected format and then 
97       * into an array of bytes. The transformer used is the one configured on the
98       * endpoint through which this event was received.
99       * 
100      * @return the message transformed into it's recognised or expected format as an
101      *         array of bytes.
102      * @throws TransformerException if a failure occurs in the transformer
103      * @see org.mule.api.transformer.Transformer
104      * @deprecated use {@link #transformMessage(org.mule.api.transformer.DataType)} instead
105      */
106     @Deprecated
107     byte[] transformMessageToBytes() throws TransformerException;
108 
109     /**
110      * Returns the message transformed into it's recognised or expected format and
111      * then into a String. The transformer used is the one configured on the endpoint
112      * through which this event was received. If necessary this will use the encoding
113      * set on the event
114      * 
115      * @return the message transformed into it's recognised or expected format as a
116      *         Strings.
117      * @throws TransformerException if a failure occurs in the transformer
118      * @see org.mule.api.transformer.Transformer
119      */
120     String transformMessageToString() throws TransformerException;
121 
122     /**
123      * Returns the message contents as a string If necessary this will use the
124      * encoding set on the event
125      * 
126      * @return the message contents as a string
127      * @throws MuleException if the message cannot be converted into a string
128      */
129     String getMessageAsString() throws MuleException;
130 
131     /**
132      * Returns the message contents as a string
133      * 
134      * @param encoding the encoding to use when converting the message to string
135      * @return the message contents as a string
136      * @throws MuleException if the message cannot be converted into a string
137      */
138     String getMessageAsString(String encoding) throws MuleException;
139 
140     /**
141      * Every event in the system is assigned a universally unique id (UUID).
142      * 
143      * @return the unique identifier for the event
144      */
145     String getId();
146 
147     /**
148      * Gets a property associated with the current event. This method will check all property scopes on the currnet message
149      * and the current session
150      * 
151      * @param name the property name
152      * @return the property value or null if the property does not exist
153      * @deprecated
154      */
155     @Deprecated
156     Object getProperty(String name);
157 
158     /**
159      * Gets a property associated with the current event. This method will check all property scopes on the currnet message
160      * and the current session
161      * @param name the property name
162      * @param defaultValue a default value if the property doesn't exist in the event
163      * @return the property value or the defaultValue if the property does not exist
164      * @deprecated
165      */
166     @Deprecated
167     Object getProperty(String name, Object defaultValue);
168 
169     /**
170      * Retrieves the service session for the current event
171      * 
172      * @return the service session for the event
173      */
174     MuleSession getSession();
175 
176     /**
177      * Retrieves the service for the current event
178      * 
179      * @return the service for the event
180      */
181     FlowConstruct getFlowConstruct();
182 
183     /**
184      * Determines whether the default processing for this event will be executed. By
185      * default, the Mule server will route events according to a components
186      * configuration. The user can override this behaviour by obtaining a reference
187      * to the MuleEvent context, either by implementing
188      * <code>org.mule.api.lifecycle.Callable</code> or calling
189      * <code>RequestContext.getEventContext</code> to obtain the MuleEventContext for
190      * the current thread. The user can programmatically control how events are
191      * dispached.
192      * 
193      * @return Returns true is the user has set stopFurtherProcessing.
194      * @see org.mule.api.MuleContext
195      * @see MuleEventContext
196      * @see org.mule.api.lifecycle.Callable
197      */
198     boolean isStopFurtherProcessing();
199 
200     /**
201      * Determines whether the default processing for this event will be executed. By
202      * default, the Mule server will route events according to a components
203      * configuration. The user can override this behaviour by obtaining a reference
204      * to the MuleEvent context, either by implementing
205      * <code>org.mule.api.lifecycle.Callable</code> or calling
206      * <code>RequestContext.getEventContext</code> to obtain the MuleEventContext for
207      * the current thread. The user can programmatically control how events are
208      * dispached.
209      * 
210      * @param stopFurtherProcessing the value to set.
211      */
212     void setStopFurtherProcessing(boolean stopFurtherProcessing);
213 
214     /**
215      * The number of milliseconds to wait for a return event when running
216      * synchronously. 0 wait forever -1 try and receive, but do not wait or a
217      * positive millisecond value
218      * 
219      * @return the event timeout in milliseconds
220      */
221     int getTimeout();
222 
223     /**
224      * The number of milliseconds to wait for a return event when running
225      * synchronously. 0 wait forever -1 try and receive, but do not wait or a
226      * positive millisecod value
227      * 
228      * @param timeout the event timeout in milliseconds
229      */
230     void setTimeout(int timeout);
231 
232     /**
233      * An outputstream the can optionally be used write response data to an incoming
234      * message.
235      * 
236      * @return an output strem if one has been made available by the message receiver
237      *         that received the message
238      */
239     OutputStream getOutputStream();
240 
241     /**
242      * Gets the encoding for this message.
243      * 
244      * @return the encoding for the event. This must never return null.
245      */
246     String getEncoding();
247 
248     /**
249      * Returns the muleContext for the Mule node that this event was received in
250      * @return the muleContext for the Mule node that this event was received in
251      */
252     MuleContext getMuleContext();
253 
254     /**
255      * Returns the times spent processing this event (so far)
256      */
257     ProcessingTime getProcessingTime();
258     
259     /**
260      * Returns the message exchange pattern for this event
261      */
262     MessageExchangePattern getExchangePattern();
263     
264     /**
265      * Returns true is this event is being processed in a transaction
266      */
267     boolean isTransacted();
268 
269     /**
270      * Returns the {@link URI} of the MessageSource that recieved or generated the message being processed.
271      */
272     URI getMessageSourceURI();
273 
274     /**
275      * Returns the message source name if it has one, otherwise returns toString() of the URI returned be
276      * getMessageSourceURI()
277      */
278     String getMessageSourceName();
279 
280     /**
281      * Return the replyToHandler (if any) that will be used to perform async reply
282      */
283     ReplyToHandler getReplyToHandler();
284 
285     /**
286      * Return the destination (if any) that will be passed to the reply-to handler.
287      */
288     Object getReplyToDestination();
289 
290     /**
291      * Set the reply-to destination from the current message, and remove it from the message, to
292      * prevent any further propagation.
293      */
294     void captureReplyToDestination();
295     
296     boolean isSynchronous();
297     
298 }