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