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