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