Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
UMOEvent |
|
| 1.0;1 |
1 | /* | |
2 | * $Id: UMOEvent.java 7976 2007-08-21 14:26:13Z dirk.olmes $ | |
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.umo; | |
12 | ||
13 | import org.mule.umo.endpoint.UMOImmutableEndpoint; | |
14 | import org.mule.umo.security.UMOCredentials; | |
15 | import org.mule.umo.transformer.TransformerException; | |
16 | ||
17 | import java.io.OutputStream; | |
18 | ||
19 | /** | |
20 | * <code>UMOEvent</code> represents any data event occuring in the Mule | |
21 | * environment. All data sent or received within the mule environment will be passed | |
22 | * between components as an UMOEvent. <p/> <p/> The UMOEvent holds a UMOMessage | |
23 | * payload and provides helper methods for obtaining the data in a format that the | |
24 | * receiving Mule UMO understands. The event can also maintain any number of | |
25 | * properties that can be set and retrieved by Mule UMO components. | |
26 | * | |
27 | * @see UMOMessage | |
28 | */ | |
29 | public interface UMOEvent | |
30 | { | |
31 | int TIMEOUT_WAIT_FOREVER = 0; | |
32 | int TIMEOUT_DO_NOT_WAIT = -1; | |
33 | int TIMEOUT_NOT_SET_VALUE = Integer.MIN_VALUE; | |
34 | ||
35 | /** | |
36 | * Returns the message payload for this event | |
37 | * | |
38 | * @return the message payload for this event | |
39 | */ | |
40 | UMOMessage getMessage(); | |
41 | ||
42 | UMOCredentials getCredentials(); | |
43 | ||
44 | /** | |
45 | * Reterns the conents of the message as a byte array. | |
46 | * | |
47 | * @return the conents of the message as a byte array | |
48 | * @throws UMOException if the message cannot be converted into an array of bytes | |
49 | */ | |
50 | byte[] getMessageAsBytes() throws UMOException; | |
51 | ||
52 | /** | |
53 | * Returns the message transformed into it's recognised or expected format. The | |
54 | * transformer used is the one configured on the endpoint through which this | |
55 | * event was received. | |
56 | * | |
57 | * @return the message transformed into it's recognised or expected format. | |
58 | * @throws TransformerException if a failure occurs in the transformer | |
59 | * @see org.mule.umo.transformer.UMOTransformer | |
60 | */ | |
61 | Object getTransformedMessage() throws TransformerException; | |
62 | ||
63 | /** | |
64 | * Returns the message transformed into it's recognised or expected format and | |
65 | * then into an array of bytes. The transformer used is the one configured on the | |
66 | * endpoint through which this event was received. | |
67 | * | |
68 | * @return the message transformed into it's recognised or expected format as an | |
69 | * array of bytes. | |
70 | * @throws TransformerException if a failure occurs in the transformer | |
71 | * @see org.mule.umo.transformer.UMOTransformer | |
72 | */ | |
73 | byte[] getTransformedMessageAsBytes() throws TransformerException; | |
74 | ||
75 | /** | |
76 | * Returns the message transformed into it's recognised or expected format and | |
77 | * then into a String. The transformer used is the one configured on the endpoint | |
78 | * through which this event was received. If necessary this will use the encoding | |
79 | * set on the event | |
80 | * | |
81 | * @return the message transformed into it's recognised or expected format as a | |
82 | * Strings. | |
83 | * @throws TransformerException if a failure occurs in the transformer | |
84 | * @see org.mule.umo.transformer.UMOTransformer | |
85 | */ | |
86 | String getTransformedMessageAsString() throws TransformerException; | |
87 | ||
88 | /** | |
89 | * Returns the message contents as a string If necessary this will use the | |
90 | * encoding set on the event | |
91 | * | |
92 | * @return the message contents as a string | |
93 | * @throws UMOException if the message cannot be converted into a string | |
94 | */ | |
95 | String getMessageAsString() throws UMOException; | |
96 | ||
97 | /** | |
98 | * Returns the message transformed into it's recognised or expected format and | |
99 | * then into a String. The transformer used is the one configured on the endpoint | |
100 | * through which this event was received. | |
101 | * | |
102 | * @param encoding the encoding to use when converting the message to string | |
103 | * @return the message transformed into it's recognised or expected format as a | |
104 | * Strings. | |
105 | * @throws TransformerException if a failure occurs in the transformer | |
106 | * @see org.mule.umo.transformer.UMOTransformer | |
107 | */ | |
108 | String getTransformedMessageAsString(String encoding) throws TransformerException; | |
109 | ||
110 | /** | |
111 | * Returns the message contents as a string | |
112 | * | |
113 | * @param encoding the encoding to use when converting the message to string | |
114 | * @return the message contents as a string | |
115 | * @throws UMOException if the message cannot be converted into a string | |
116 | */ | |
117 | String getMessageAsString(String encoding) throws UMOException; | |
118 | ||
119 | /** | |
120 | * Every event in the system is assigned a universally unique id (UUID). | |
121 | * | |
122 | * @return the unique identifier for the event | |
123 | */ | |
124 | String getId(); | |
125 | ||
126 | /** | |
127 | * Gets a property associated with the current event. If | |
128 | * <code>exhaustiveSearch</code> is true, the endpoint and connector associated | |
129 | * with the event will also be searched for the property. | |
130 | * | |
131 | * @param name the property name | |
132 | * @param exhaustiveSearch also search the endpoint and connector for the | |
133 | * property | |
134 | * @return the property value or null if the property does not exist | |
135 | */ | |
136 | Object getProperty(String name, boolean exhaustiveSearch); | |
137 | ||
138 | /** | |
139 | * Gets a property associated with the current event. If | |
140 | * <code>exhaustiveSearch</code> is true, the endpoint and connector associated | |
141 | * with the event will also be searched for the property. | |
142 | * | |
143 | * @param name the property name | |
144 | * @param defaultValue a default value if the property doesn't exist in the event | |
145 | * @param exhaustiveSearch also search the endpoint and connector for the | |
146 | * property | |
147 | * @return the property value or the defaultValue if the property does not exist | |
148 | */ | |
149 | Object getProperty(String name, Object defaultValue, boolean exhaustiveSearch); | |
150 | ||
151 | /** | |
152 | * Gets the endpoint associated with this event | |
153 | * | |
154 | * @return the endpoint associated with this event | |
155 | */ | |
156 | UMOImmutableEndpoint getEndpoint(); | |
157 | ||
158 | /** | |
159 | * Retrieves the component session for the current event | |
160 | * | |
161 | * @return the component session for the event | |
162 | */ | |
163 | UMOSession getSession(); | |
164 | ||
165 | /** | |
166 | * Retrieves the component for the current event | |
167 | * | |
168 | * @return the component for the event | |
169 | */ | |
170 | UMOComponent getComponent(); | |
171 | ||
172 | /** | |
173 | * Determines whether the default processing for this event will be executed. By | |
174 | * default, the Mule server will route events according to a components | |
175 | * configuration. The user can override this behaviour by obtaining a reference | |
176 | * to the Event context, either by implementing | |
177 | * <code>org.mule.umo.lifecycle.Callable</code> or calling | |
178 | * <code>UMOManager.getEventContext</code> to obtain the UMOEventContext for | |
179 | * the current thread. The user can programmatically control how events are | |
180 | * dispached. | |
181 | * | |
182 | * @return Returns true is the user has set stopFurtherProcessing. | |
183 | * @see org.mule.umo.manager.UMOManager | |
184 | * @see UMOEventContext | |
185 | * @see org.mule.umo.lifecycle.Callable | |
186 | */ | |
187 | boolean isStopFurtherProcessing(); | |
188 | ||
189 | /** | |
190 | * Determines whether the default processing for this event will be executed. By | |
191 | * default, the Mule server will route events according to a components | |
192 | * configuration. The user can override this behaviour by obtaining a reference | |
193 | * to the Event context, either by implementing | |
194 | * <code>org.mule.umo.lifecycle.Callable</code> or calling | |
195 | * <code>UMOManager.getEventContext</code> to obtain the UMOEventContext for | |
196 | * the current thread. The user can programmatically control how events are | |
197 | * dispached. | |
198 | * | |
199 | * @param stopFurtherProcessing the value to set. | |
200 | */ | |
201 | void setStopFurtherProcessing(boolean stopFurtherProcessing); | |
202 | ||
203 | /** | |
204 | * Determines whether the was sent synchrounously or not | |
205 | * | |
206 | * @return true if the event is synchronous | |
207 | */ | |
208 | boolean isSynchronous(); | |
209 | ||
210 | /** | |
211 | * Determines whether the was sent synchrounously or not | |
212 | * | |
213 | * @param value true if the event is synchronous | |
214 | */ | |
215 | void setSynchronous(boolean value); | |
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 | * Determines whether the event flow is being streamed | |
246 | * | |
247 | * @return true if the request should be streamed | |
248 | */ | |
249 | boolean isStreaming(); | |
250 | ||
251 | /** | |
252 | * Gets the encoding for this message. | |
253 | * | |
254 | * @return the encoding for the event. This must never return null. | |
255 | */ | |
256 | String getEncoding(); | |
257 | ||
258 | } |