View Javadoc

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