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