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