View Javadoc

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