Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
MuleEvent |
|
| 0.0;0 |
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 | } |