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