1 /* 2 * $Id: UMOEventContext.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.UMOEndpoint; 14 import org.mule.umo.endpoint.UMOEndpointURI; 15 import org.mule.umo.transformer.TransformerException; 16 17 import java.io.OutputStream; 18 19 /** 20 * <code>UMOEventContext</code> is the context object for the current request. 21 * Using the context, developers can send/dispatch/receive events programmatically as 22 * well as manage transactions. 23 */ 24 public interface UMOEventContext 25 { 26 /** 27 * Returns the message payload for this event 28 * 29 * @return the message payload for this event 30 */ 31 UMOMessage getMessage(); 32 33 /** 34 * Returns the contents of the message as a byte array. 35 * 36 * @return the contents of the message as a byte array 37 * @throws UMOException if the message cannot be converted into an array of bytes 38 */ 39 byte[] getMessageAsBytes() throws UMOException; 40 41 /** 42 * Returns the message transformed into it's recognised or expected format. The 43 * transformer used is the one configured on the endpoint through which this 44 * event was received. 45 * 46 * @return the message transformed into it's recognised or expected format. 47 * @throws org.mule.umo.transformer.TransformerException if a failure occurs in 48 * the transformer 49 * @see org.mule.umo.transformer.UMOTransformer 50 */ 51 Object getTransformedMessage() throws TransformerException; 52 53 /** 54 * Returns the message transformed 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 * @param expectedType The class type required for the return object. This param 59 * just provides a convienient way to manage type casting of 60 * transformed objects 61 * @return the message transformed into it's recognised or expected format. 62 * @throws org.mule.umo.transformer.TransformerException if a failure occurs or 63 * if the return type is not the same as the expected type in the 64 * transformer 65 * @see org.mule.umo.transformer.UMOTransformer 66 */ 67 Object getTransformedMessage(Class expectedType) throws TransformerException; 68 69 /** 70 * Returns the message transformed into it's recognised or expected format and 71 * then into an array of bytes. The transformer used is the one configured on the 72 * endpoint through which this event was received. 73 * 74 * @return the message transformed into it's recognised or expected format as an 75 * array of bytes. 76 * @throws TransformerException if a failure occurs in the transformer 77 * @see org.mule.umo.transformer.UMOTransformer 78 */ 79 byte[] getTransformedMessageAsBytes() throws TransformerException; 80 81 /** 82 * Returns the message transformed into it's recognised or expected format and 83 * then into a String. The transformer used is the one configured on the endpoint 84 * through which this event was received. This method will use the encoding set 85 * on the event 86 * 87 * @return the message transformed into it's recognised or expected format as a 88 * Strings. 89 * @throws TransformerException if a failure occurs in the transformer 90 * @see org.mule.umo.transformer.UMOTransformer 91 */ 92 String getTransformedMessageAsString() throws TransformerException; 93 94 /** 95 * Returns the message contents as a string This method will use the encoding set 96 * on the event 97 * 98 * @return the message contents as a string 99 * @throws UMOException if the message cannot be converted into a string 100 */ 101 String getMessageAsString() throws UMOException; 102 103 /** 104 * Returns the message transformed into it's recognised or expected format and 105 * then into a String. The transformer used is the one configured on the endpoint 106 * through which this event was received. 107 * 108 * @param encoding The encoding to use when transforming the message 109 * @return the message transformed into it's recognised or expected format as a 110 * Strings. 111 * @throws TransformerException if a failure occurs in the transformer 112 * @see org.mule.umo.transformer.UMOTransformer 113 */ 114 String getTransformedMessageAsString(String encoding) throws TransformerException; 115 116 /** 117 * Returns the message contents as a string 118 * 119 * @param encoding The encoding to use when transforming the message 120 * @return the message contents as a string 121 * @throws UMOException if the message cannot be converted into a string 122 */ 123 String getMessageAsString(String encoding) throws UMOException; 124 125 /** 126 * Returns the current transaction (if any) for the session 127 * 128 * @return the current transaction for the session or null if there is no 129 * transaction in progress 130 */ 131 UMOTransaction getCurrentTransaction(); 132 133 /** 134 * Mark the current transaction (if any) for rollback 135 * 136 * @throws TransactionException 137 */ 138 void markTransactionForRollback() throws TransactionException; 139 140 /** 141 * This will send an event via the configured outbound router on the component 142 * 143 * @param message the message to send 144 * @return the result of the send if any 145 * @throws UMOException if there is no outbound endpoint configured on the 146 * component or the events fails during dispatch 147 */ 148 UMOMessage sendEvent(Object message) throws UMOException; 149 150 /** 151 * Depending on the session state this methods either Passes an event 152 * synchronously to the next available Mule UMO in the pool or via the endpoint 153 * configured for the event 154 * 155 * @param message the message payload to send 156 * @return the return Message from the call or null if there was no result 157 * @throws UMOException if the event fails to be processed by the component or 158 * the transport for the endpoint 159 */ 160 UMOMessage sendEvent(UMOMessage message) throws UMOException; 161 162 /** 163 * Depending on the session state this methods either Passes an event 164 * synchronously to the next available Mule UMO in the pool or via the endpoint 165 * configured for the event 166 * 167 * @param message the event message payload to send 168 * @param endpoint The endpointUri to disptch the event through 169 * @return the return Message from the call or null if there was no result 170 * @throws UMOException if the event fails to be processed by the component or 171 * the transport for the endpoint 172 */ 173 UMOMessage sendEvent(UMOMessage message, UMOEndpointURI endpoint) throws UMOException; 174 175 /** 176 * Depending on the session state this methods either Passes an event 177 * synchronously to the next available Mule UMO in the pool or via the endpoint 178 * configured for the event 179 * 180 * @param message the event message payload to send 181 * @param endpointName The endpoint name to disptch the event through. This will 182 * be looked up first on the component configuration and then on the 183 * mule manager configuration 184 * @return the return Message from the call or null if there was no result 185 * @throws UMOException if the event fails to be processed by the component or 186 * the transport for the endpoint 187 */ 188 UMOMessage sendEvent(UMOMessage message, String endpointName) throws UMOException; 189 190 /** 191 * Depending on the session state this methods either Passes an event 192 * synchronously to the next available Mule UMO in the pool or via the endpoint 193 * configured for the event 194 * 195 * @param message the event message payload to send 196 * @param endpoint The endpoint to disptch the event through. 197 * @return the return Message from the call or null if there was no result 198 * @throws UMOException if the event fails to be processed by the component or 199 * the transport for the endpoint 200 */ 201 UMOMessage sendEvent(UMOMessage message, UMOEndpoint endpoint) throws UMOException; 202 203 /** 204 * sends an event request via the configured outbound router for this component. 205 * This method return immediately, but the result of the event invocation 206 * available from the returned a Future result that can be accessed later by the 207 * the returned FutureMessageResult. the Future messageResult can be queried at 208 * any time to check that the invocation has completed. A timeout is associated 209 * with the invocation, which is the maximum time in milli-seconds that the 210 * invocation should take to complete 211 * 212 * @param message the object that is the payload of the event 213 * @param timeout how long to block in milliseconds waiting for a result 214 * @return the result message if any of the invocation 215 * @throws org.mule.umo.UMOException if the dispatch fails or the components or 216 * transfromers cannot be found 217 * @see FutureMessageResult 218 */ 219 FutureMessageResult sendEventAsync(Object message, int timeout) throws UMOException; 220 221 /** 222 * sends an event request via the configured outbound router for this component. 223 * This method return immediately, but the result of the event invocation 224 * available from the returned a Future result that can be accessed later by the 225 * the returned FutureMessageResult. the Future messageResult can be queried at 226 * any time to check that the invocation has completed. A timeout is associated 227 * with the invocation, which is the maximum time in milli-seconds that the 228 * invocation should take to complete 229 * 230 * @param message the UMOMessage of the event 231 * @param timeout how long to block in milliseconds waiting for a result 232 * @return the result message if any of the invocation 233 * @throws org.mule.umo.UMOException if the dispatch fails or the components or 234 * transfromers cannot be found 235 * @see FutureMessageResult 236 */ 237 FutureMessageResult sendEventAsync(UMOMessage message, int timeout) throws UMOException; 238 239 /** 240 * sends an event request via the configured outbound router for this component. 241 * This method return immediately, but the result of the event invocation 242 * available from the returned a Future result that can be accessed later by the 243 * the returned FutureMessageResult. the Future messageResult can be queried at 244 * any time to check that the invocation has completed. A timeout is associated 245 * with the invocation, which is the maximum time in milli-seconds that the 246 * invocation should take to complete 247 * 248 * @param message the UMOMessage of the event 249 * @param endpoint the endpointUri to dispatch to 250 * @param timeout how long to block in milliseconds waiting for a result 251 * @return the result message if any of the invocation 252 * @throws org.mule.umo.UMOException if the dispatch fails or the components or 253 * transfromers cannot be found 254 * @see FutureMessageResult 255 */ 256 FutureMessageResult sendEventAsync(UMOMessage message, UMOEndpointURI endpoint, int timeout) 257 throws UMOException; 258 259 /** 260 * sends an event request via the configured outbound router for this component. 261 * This method return immediately, but the result of the event invocation 262 * available from the returned a Future result that can be accessed later by the 263 * the returned FutureMessageResult. the Future messageResult can be queried at 264 * any time to check that the invocation has completed. A timeout is associated 265 * with the invocation, which is the maximum time in milli-seconds that the 266 * invocation should take to complete 267 * 268 * @param message the UMOMessage of the event 269 * @param endpointName The endpoint name to disptch the event through. This will 270 * be looked up first on the component configuration and then on the 271 * mule manager configuration 272 * @param timeout how long to block in milliseconds waiting for a result 273 * @return the result message if any of the invocation 274 * @throws org.mule.umo.UMOException if the dispatch fails or the components or 275 * transfromers cannot be found 276 * @see FutureMessageResult 277 */ 278 FutureMessageResult sendEventAsync(UMOMessage message, String endpointName, int timeout) 279 throws UMOException; 280 281 /** 282 * This will dispatch an event asynchronously via the configured outbound 283 * endpoint on the component for this session 284 * 285 * @param message the message to send 286 * @throws UMOException if there is no outbound endpoint configured on the 287 * component or the events fails during dispatch 288 */ 289 void dispatchEvent(UMOMessage message) throws UMOException; 290 291 /** 292 * This will dispatch an event asynchronously via the configured outbound 293 * endpoint on the component for this session 294 * 295 * @param payload the message payloadto send 296 * @throws UMOException if there is no outbound endpoint configured on the 297 * component or the events fails during dispatch 298 */ 299 void dispatchEvent(Object payload) throws UMOException; 300 301 /** 302 * Depending on the session state this methods either Passes an event 303 * asynchronously to the next available Mule UMO in the pool or via the endpoint 304 * configured for the event 305 * 306 * @param message the event message payload to send 307 * @param endpoint the endpointUri to dispatc the event to first on the component 308 * configuration and then on the mule manager configuration 309 * @throws UMOException if the event fails to be processed by the component or 310 * the transport for the endpoint 311 */ 312 void dispatchEvent(UMOMessage message, UMOEndpointURI endpoint) throws UMOException; 313 314 /** 315 * Depending on the session state this methods either Passes an event 316 * asynchronously to the next available Mule UMO in the pool or via the endpoint 317 * configured for the event. 318 * 319 * @param message the event message payload to send 320 * @param endpointName The endpoint name to disptch the event through. This will 321 * be looked up first on the component configuration and then on the 322 * mule manager configuration 323 * @throws UMOException if the event fails to be processed by the component or 324 * the transport for the endpoint 325 */ 326 void dispatchEvent(UMOMessage message, String endpointName) throws UMOException; 327 328 /** 329 * Depending on the session state this methods either Passes an event 330 * asynchronously to the next available Mule UMO in the pool or via the endpoint 331 * configured for the event 332 * 333 * @param message the event message payload to send 334 * @param endpoint The endpoint name to disptch the event through. 335 * @throws UMOException if the event fails to be processed by the component or 336 * the transport for the endpoint 337 */ 338 void dispatchEvent(UMOMessage message, UMOEndpoint endpoint) throws UMOException; 339 340 /** 341 * Requests a synchronous receive of an event on the component. 342 * 343 * @param endpoint the endpoint identifying the endpointUri on which the event 344 * will be received 345 * @param timeout time in milliseconds before the request times out 346 * @return The requested event or null if the request times out 347 * @throws UMOException if the request operation fails 348 */ 349 UMOMessage receiveEvent(UMOEndpoint endpoint, long timeout) throws UMOException; 350 351 /** 352 * Requests a synchronous receive of an event on the component. 353 * 354 * @param endpointName the endpoint identifying the endpointUri on which the 355 * event will be received 356 * @param timeout time in milliseconds before the request timesout 357 * @return The requested event or null if the request times out 358 * @throws UMOException if the request operation fails 359 */ 360 UMOMessage receiveEvent(String endpointName, long timeout) throws UMOException; 361 362 /** 363 * Requests a synchronous receive of an event on the component. 364 * 365 * @param endpoint the endpointUri on which the event will be received 366 * @param timeout time in milliseconds before the request timesout 367 * @return The requested event or null if the request times out 368 * @throws UMOException if the request operation fails 369 */ 370 UMOMessage receiveEvent(UMOEndpointURI endpoint, long timeout) throws UMOException; 371 372 UMODescriptor getComponentDescriptor(); 373 374 /** 375 * Determines whether the default processing for this event will be executed. By 376 * default, the Mule server will route events according to a components 377 * configuration. The user can override this behaviour by obtaining a reference 378 * to the Event context, either by implementing 379 * <code>org.mule.umo.lifecycle.Callable</code> or calling 380 * <code>UMOManager.getEventContext</code> to obtain the UMOEventContext for 381 * the current thread. The user can programmatically control how events are 382 * dispached. 383 * 384 * @return Returns true is the user has set stopFurtherProcessing. 385 * @see org.mule.umo.manager.UMOManager 386 * @see UMOEventContext 387 * @see org.mule.umo.lifecycle.Callable 388 */ 389 boolean isStopFurtherProcessing(); 390 391 /** 392 * Determines whether the default processing for this event will be executed. By 393 * default, the Mule server will route events according to a components 394 * configuration. The user can override this behaviour by obtaining a reference 395 * to the Event context, either by implementing 396 * <code>org.mule.umo.lifecycle.Callable</code> or calling 397 * <code>UMOManager.getEventContext</code> to obtain the UMOEventContext for 398 * the current thread. The user can programmatically control how events are 399 * dispached. 400 * 401 * @param stopFurtherProcessing the value to set. 402 */ 403 void setStopFurtherProcessing(boolean stopFurtherProcessing); 404 405 /** 406 * An outputstream the can optionally be used write response data to an incoming 407 * message. 408 * 409 * @return an output strem if one has been made available by the message receiver 410 * that received the message 411 */ 412 OutputStream getOutputStream(); 413 414 /** 415 * Determines whether the was sent synchrounously or not 416 * 417 * @return true if the event is synchronous 418 */ 419 boolean isSynchronous(); 420 421 /** 422 * Returns a reference to the Endpoint Uri for this context This is the endpoint 423 * on which the event was received 424 * 425 * @return the receive endpoint for this event context 426 */ 427 UMOEndpointURI getEndpointURI(); 428 429 /** 430 * Returns the transaction for the current event or null if there is no 431 * transaction in progresss 432 * 433 * @return the transaction for the current event or null if there is no 434 * transaction in progresss 435 */ 436 UMOTransaction getTransaction(); 437 438 /** 439 * Get the timeout value associated with the event 440 * 441 * @return the timeout for the event 442 */ 443 int getTimeout(); 444 445 /** 446 * Determines whether the event flow is being streamed 447 * 448 * @return true if the request should be streamed 449 */ 450 boolean isStreaming(); 451 452 /** 453 * Gets the encoding for the current message. For potocols that send encoding 454 * Information with the message, this method should be overriden to expose the 455 * transport encoding, otherwise the default encoding in the Mule configuration 456 * will be used 457 * 458 * @return the encoding for this message. This method must never return null 459 */ 460 String getEncoding(); 461 462 UMOSession getSession(); 463 }