Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
MuleEvent |
|
| 1.0;1 |
1 | /* | |
2 | * $Id: MuleEvent.java 10529 2008-01-25 05:58:36Z dfeist $ | |
3 | * -------------------------------------------------------------------------------------- | |
4 | * Copyright (c) MuleSource, Inc. All rights reserved. http://www.mulesource.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.endpoint.ImmutableEndpoint; | |
14 | import org.mule.api.security.Credentials; | |
15 | import org.mule.api.service.Service; | |
16 | import org.mule.api.transformer.TransformerException; | |
17 | ||
18 | import java.io.OutputStream; | |
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 UMO understands. The event can also maintain any number of | |
26 | * properties that can be set and retrieved by Mule UMO components. | |
27 | * | |
28 | * @see MuleMessage | |
29 | */ | |
30 | public interface MuleEvent | |
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 | * Reterns the conents of the message as a byte array. | |
47 | * | |
48 | * @return the conents 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 | */ | |
62 | Object transformMessage() throws TransformerException; | |
63 | ||
64 | /** | |
65 | * Transforms the message into the requested format. The transformer used is | |
66 | * the one configured on the endpoint through which this event was received. | |
67 | * | |
68 | * @param outputType The requested output type. | |
69 | * @return the message transformed into it's recognised or expected format. | |
70 | * @throws TransformerException if a failure occurs in the transformer | |
71 | * @see org.mule.api.transformer.Transformer | |
72 | */ | |
73 | Object transformMessage(Class outputType) throws TransformerException; | |
74 | ||
75 | /** | |
76 | * Transforms the message into it's recognised or expected format and then | |
77 | * into an array of bytes. The transformer used is the one configured on the | |
78 | * endpoint through which this event was received. | |
79 | * | |
80 | * @return the message transformed into it's recognised or expected format as an | |
81 | * array of bytes. | |
82 | * @throws TransformerException if a failure occurs in the transformer | |
83 | * @see org.mule.api.transformer.Transformer | |
84 | */ | |
85 | byte[] transformMessageToBytes() throws TransformerException; | |
86 | ||
87 | /** | |
88 | * Returns the message transformed into it's recognised or expected format and | |
89 | * then into a String. The transformer used is the one configured on the endpoint | |
90 | * through which this event was received. If necessary this will use the encoding | |
91 | * set on the event | |
92 | * | |
93 | * @return the message transformed into it's recognised or expected format as a | |
94 | * Strings. | |
95 | * @throws TransformerException if a failure occurs in the transformer | |
96 | * @see org.mule.api.transformer.Transformer | |
97 | */ | |
98 | String transformMessageToString() throws TransformerException; | |
99 | ||
100 | /** | |
101 | * Returns the message contents as a string If necessary this will use the | |
102 | * encoding set on the event | |
103 | * | |
104 | * @return the message contents as a string | |
105 | * @throws MuleException if the message cannot be converted into a string | |
106 | */ | |
107 | String getMessageAsString() throws MuleException; | |
108 | ||
109 | /** | |
110 | * Returns the message contents as a string | |
111 | * | |
112 | * @param encoding the encoding to use when converting the message to string | |
113 | * @return the message contents as a string | |
114 | * @throws MuleException if the message cannot be converted into a string | |
115 | */ | |
116 | String getMessageAsString(String encoding) throws MuleException; | |
117 | ||
118 | /** | |
119 | * Every event in the system is assigned a universally unique id (UUID). | |
120 | * | |
121 | * @return the unique identifier for the event | |
122 | */ | |
123 | String getId(); | |
124 | ||
125 | /** | |
126 | * Gets a property associated with the current event. If | |
127 | * <code>exhaustiveSearch</code> is true, the endpoint and connector associated | |
128 | * with the event will also be searched for the property. | |
129 | * | |
130 | * @param name the property name | |
131 | * @param exhaustiveSearch also search the endpoint and connector for the | |
132 | * property | |
133 | * @return the property value or null if the property does not exist | |
134 | */ | |
135 | Object getProperty(String name, boolean exhaustiveSearch); | |
136 | ||
137 | /** | |
138 | * Gets a property associated with the current event. If | |
139 | * <code>exhaustiveSearch</code> is true, the endpoint and connector associated | |
140 | * with the event will also be searched for the property. | |
141 | * | |
142 | * @param name the property name | |
143 | * @param defaultValue a default value if the property doesn't exist in the event | |
144 | * @param exhaustiveSearch also search the endpoint and connector for the | |
145 | * property | |
146 | * @return the property value or the defaultValue if the property does not exist | |
147 | */ | |
148 | Object getProperty(String name, Object defaultValue, boolean exhaustiveSearch); | |
149 | ||
150 | /** | |
151 | * Gets the endpoint associated with this event | |
152 | * | |
153 | * @return the endpoint associated with this event | |
154 | */ | |
155 | ImmutableEndpoint getEndpoint(); | |
156 | ||
157 | /** | |
158 | * Retrieves the service session for the current event | |
159 | * | |
160 | * @return the service session for the event | |
161 | */ | |
162 | MuleSession getSession(); | |
163 | ||
164 | /** | |
165 | * Retrieves the service for the current event | |
166 | * | |
167 | * @return the service for the event | |
168 | */ | |
169 | Service getService(); | |
170 | ||
171 | /** | |
172 | * Determines whether the default processing for this event will be executed. By | |
173 | * default, the Mule server will route events according to a components | |
174 | * configuration. The user can override this behaviour by obtaining a reference | |
175 | * to the MuleEvent context, either by implementing | |
176 | * <code>org.mule.api.lifecycle.Callable</code> or calling | |
177 | * <code>UMOManager.getEventContext</code> to obtain the MuleEventContext for | |
178 | * the current thread. The user can programmatically control how events are | |
179 | * dispached. | |
180 | * | |
181 | * @return Returns true is the user has set stopFurtherProcessing. | |
182 | * @see org.mule.api.context.UMOManager | |
183 | * @see MuleEventContext | |
184 | * @see org.mule.api.lifecycle.Callable | |
185 | */ | |
186 | boolean isStopFurtherProcessing(); | |
187 | ||
188 | /** | |
189 | * Determines whether the default processing for this event will be executed. By | |
190 | * default, the Mule server will route events according to a components | |
191 | * configuration. The user can override this behaviour by obtaining a reference | |
192 | * to the MuleEvent context, either by implementing | |
193 | * <code>org.mule.api.lifecycle.Callable</code> or calling | |
194 | * <code>UMOManager.getEventContext</code> to obtain the MuleEventContext for | |
195 | * the current thread. The user can programmatically control how events are | |
196 | * dispached. | |
197 | * | |
198 | * @param stopFurtherProcessing the value to set. | |
199 | */ | |
200 | void setStopFurtherProcessing(boolean stopFurtherProcessing); | |
201 | ||
202 | /** | |
203 | * Determines whether the was sent synchrounously or not | |
204 | * | |
205 | * @return true if the event is synchronous | |
206 | */ | |
207 | boolean isSynchronous(); | |
208 | ||
209 | /** | |
210 | * Determines whether the was sent synchrounously or not | |
211 | * | |
212 | * @param value true if the event is synchronous | |
213 | */ | |
214 | void setSynchronous(boolean value); | |
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 | } |