001: /*
002: * $Id: MuleEventContext.java 10961 2008-02-22 19:01:02Z dfeist $
003: * --------------------------------------------------------------------------------------
004: * Copyright (c) MuleSource, Inc. All rights reserved. http://www.mulesource.com
005: *
006: * The software in this package is published under the terms of the CPAL v1.0
007: * license, a copy of which has been included with this distribution in the
008: * LICENSE.txt file.
009: */
010:
011: package org.mule.api;
012:
013: import org.mule.api.endpoint.EndpointURI;
014: import org.mule.api.endpoint.InboundEndpoint;
015: import org.mule.api.endpoint.OutboundEndpoint;
016: import org.mule.api.service.Service;
017: import org.mule.api.transaction.Transaction;
018: import org.mule.api.transaction.TransactionException;
019: import org.mule.api.transformer.TransformerException;
020:
021: import java.io.OutputStream;
022:
023: /**
024: * <code>MuleEventContext</code> is the context object for the current request.
025: * Using the context, developers can send/dispatch/receive events programmatically as
026: * well as manage transactions.
027: */
028: public interface MuleEventContext {
029: /**
030: * Returns the message payload for this event
031: *
032: * @return the message payload for this event
033: */
034: MuleMessage getMessage();
035:
036: /**
037: * Returns the contents of the message as a byte array.
038: *
039: * @return the contents of the message as a byte array
040: * @throws MuleException if the message cannot be converted into an array of bytes
041: */
042: byte[] getMessageAsBytes() throws MuleException;
043:
044: /**
045: * Returns the message transformed into it's recognised or expected format. The
046: * transformer used is the one configured on the endpoint through which this
047: * event was received.
048: *
049: * @return the message transformed into it's recognised or expected format.
050: * @throws org.mule.api.transformer.TransformerException if a failure occurs in
051: * the transformer
052: * @see org.mule.api.transformer.Transformer
053: */
054: Object transformMessage() throws TransformerException;
055:
056: /**
057: * Returns the message transformed into it's recognised or expected format. The
058: * transformer used is the one configured on the endpoint through which this
059: * event was received.
060: *
061: * @param expectedType The class type required for the return object. This param
062: * just provides a convienient way to manage type casting of
063: * transformed objects
064: * @return the message transformed into it's recognised or expected format.
065: * @throws org.mule.api.transformer.TransformerException if a failure occurs or
066: * if the return type is not the same as the expected type in the
067: * transformer
068: * @see org.mule.api.transformer.Transformer
069: */
070: Object transformMessage(Class expectedType)
071: throws TransformerException;
072:
073: /**
074: * Returns the message transformed into it's recognised or expected format and
075: * then into an array of bytes. The transformer used is the one configured on the
076: * endpoint through which this event was received.
077: *
078: * @return the message transformed into it's recognised or expected format as an
079: * array of bytes.
080: * @throws TransformerException if a failure occurs in the transformer
081: * @see org.mule.api.transformer.Transformer
082: */
083: byte[] transformMessageToBytes() throws TransformerException;
084:
085: /**
086: * Returns the message transformed into it's recognised or expected format and
087: * then into a String. The transformer used is the one configured on the endpoint
088: * through which this event was received. This method will use the encoding set
089: * on the event
090: *
091: * @return the message transformed into it's recognised or expected format as a
092: * Strings.
093: * @throws TransformerException if a failure occurs in the transformer
094: * @see org.mule.api.transformer.Transformer
095: */
096: String transformMessageToString() throws TransformerException;
097:
098: /**
099: * 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)
165: throws MuleException;
166:
167: /**
168: * Depending on the session state this methods either Passes an event
169: * synchronously to the next available Mule UMO in the pool or via the endpoint
170: * configured for the event
171: *
172: * @param message the event message payload to send
173: * @param endpointName The endpoint name to disptch the event through. This will
174: * be looked up first on the service configuration and then on the
175: * mule manager configuration
176: * @return the return Message from the call or null if there was no result
177: * @throws MuleException if the event fails to be processed by the service or
178: * the transport for the endpoint
179: */
180: MuleMessage sendEvent(MuleMessage message, String endpointName)
181: throws MuleException;
182:
183: /**
184: * Depending on the session state this methods either Passes an event
185: * synchronously to the next available Mule UMO in the pool or via the endpoint
186: * configured for the event
187: *
188: * @param message the event message payload to send
189: * @param endpoint The endpoint to disptch the event through.
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, OutboundEndpoint endpoint)
195: throws MuleException;
196:
197: /**
198: * sends an event request via the configured outbound router for this service.
199: * This method return immediately, but the result of the event invocation
200: * available from the returned a Future result that can be accessed later by the
201: * the returned FutureMessageResult. the Future messageResult can be queried at
202: * any time to check that the invocation has completed. A timeout is associated
203: * with the invocation, which is the maximum time in milli-seconds that the
204: * invocation should take to complete
205: *
206: * @param message the object that is the payload of the event
207: * @param timeout how long to block in milliseconds waiting for a result
208: * @return the result message if any of the invocation
209: * @throws org.mule.api.MuleException if the dispatch fails or the components or
210: * transfromers cannot be found
211: * @see FutureMessageResult
212: */
213: FutureMessageResult sendEventAsync(Object message, int timeout)
214: throws MuleException;
215:
216: /**
217: * sends an event request via the configured outbound router for this service.
218: * This method return immediately, but the result of the event invocation
219: * available from the returned a Future result that can be accessed later by the
220: * the returned FutureMessageResult. the Future messageResult can be queried at
221: * any time to check that the invocation has completed. A timeout is associated
222: * with the invocation, which is the maximum time in milli-seconds that the
223: * invocation should take to complete
224: *
225: * @param message the MuleMessage of the event
226: * @param timeout how long to block in milliseconds waiting for a result
227: * @return the result message if any of the invocation
228: * @throws org.mule.api.MuleException if the dispatch fails or the components or
229: * transfromers cannot be found
230: * @see FutureMessageResult
231: */
232: FutureMessageResult sendEventAsync(MuleMessage message, int timeout)
233: throws MuleException;
234:
235: /**
236: * sends an event request via the configured outbound router for this service.
237: * This method return immediately, but the result of the event invocation
238: * available from the returned a Future result that can be accessed later by the
239: * the returned FutureMessageResult. the Future messageResult can be queried at
240: * any time to check that the invocation has completed. A timeout is associated
241: * with the invocation, which is the maximum time in milli-seconds that the
242: * invocation should take to complete
243: *
244: * @param message the MuleMessage of the event
245: * @param endpoint the endpointUri to dispatch to
246: * @param timeout how long to block in milliseconds waiting for a result
247: * @return the result message if any of the invocation
248: * @throws org.mule.api.MuleException if the dispatch fails or the components or
249: * transfromers cannot be found
250: * @see FutureMessageResult
251: */
252: FutureMessageResult sendEventAsync(MuleMessage message,
253: EndpointURI endpoint, int timeout) throws MuleException;
254:
255: /**
256: * sends an event request via the configured outbound router for this service.
257: * This method return immediately, but the result of the event invocation
258: * available from the returned a Future result that can be accessed later by the
259: * the returned FutureMessageResult. the Future messageResult can be queried at
260: * any time to check that the invocation has completed. A timeout is associated
261: * with the invocation, which is the maximum time in milli-seconds that the
262: * invocation should take to complete
263: *
264: * @param message the MuleMessage of the event
265: * @param endpointName The endpoint name to disptch the event through. This will
266: * be looked up first on the service configuration and then on the
267: * mule manager configuration
268: * @param timeout how long to block in milliseconds waiting for a result
269: * @return the result message if any of the invocation
270: * @throws org.mule.api.MuleException if the dispatch fails or the components or
271: * transfromers cannot be found
272: * @see FutureMessageResult
273: */
274: FutureMessageResult sendEventAsync(MuleMessage message,
275: String endpointName, int timeout) throws MuleException;
276:
277: /**
278: * This will dispatch an event asynchronously via the configured outbound
279: * endpoint on the service for this session
280: *
281: * @param message the message to send
282: * @throws MuleException if there is no outbound endpoint configured on the
283: * service or the events fails during dispatch
284: */
285: void dispatchEvent(MuleMessage message) 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 payload the message payloadto send
292: * @throws MuleException if there is no outbound endpoint configured on the
293: * service or the events fails during dispatch
294: */
295: void dispatchEvent(Object payload) throws MuleException;
296:
297: /**
298: * Depending on the session state this methods either Passes an event
299: * asynchronously to the next available Mule UMO in the pool or via the endpoint
300: * configured for the event
301: *
302: * @param message the event message payload to send
303: * @param endpoint the endpointUri to dispatc the event to first on the service
304: * configuration and then on the mule manager configuration
305: * @throws MuleException if the event fails to be processed by the service or
306: * the transport for the endpoint
307: */
308: void dispatchEvent(MuleMessage message, EndpointURI endpoint)
309: throws MuleException;
310:
311: /**
312: * Depending on the session state this methods either Passes an event
313: * asynchronously to the next available Mule UMO in the pool or via the endpoint
314: * configured for the event.
315: *
316: * @param message the event message payload to send
317: * @param endpointName The endpoint name to disptch the event through. This will
318: * be looked up first on the service configuration and then on the
319: * mule manager configuration
320: * @throws MuleException if the event fails to be processed by the service or
321: * the transport for the endpoint
322: */
323: void dispatchEvent(MuleMessage message, String endpointName)
324: throws MuleException;
325:
326: /**
327: * Depending on the session state this methods either Passes an event
328: * asynchronously to the next available Mule UMO in the pool or via the endpoint
329: * configured for the event
330: *
331: * @param message the event message payload to send
332: * @param endpoint The endpoint name to disptch the event through.
333: * @throws MuleException if the event fails to be processed by the service or
334: * the transport for the endpoint
335: */
336: void dispatchEvent(MuleMessage message, OutboundEndpoint endpoint)
337: throws MuleException;
338:
339: /**
340: * Requests a synchronous receive of an event on the service.
341: *
342: * @param endpoint the endpoint identifying the endpointUri on which the event
343: * will be received
344: * @param timeout time in milliseconds before the request times out
345: * @return The requested event or null if the request times out
346: * @throws MuleException if the request operation fails
347: */
348: MuleMessage requestEvent(InboundEndpoint endpoint, long timeout)
349: throws MuleException;
350:
351: /**
352: * Requests a synchronous receive of an event on the service.
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 MuleException if the request operation fails
359: */
360: MuleMessage requestEvent(String endpointName, long timeout)
361: throws MuleException;
362:
363: /**
364: * Requests a synchronous receive of an event on the service.
365: *
366: * @param endpoint the endpointUri on which the 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(EndpointURI endpoint, long timeout)
372: throws MuleException;
373:
374: Service getService();
375:
376: /**
377: * Determines whether the default processing for this event will be executed. By
378: * default, the Mule server will route events according to a components
379: * configuration. The user can override this behaviour by obtaining a reference
380: * to the MuleEvent context, either by implementing
381: * <code>org.mule.api.lifecycle.Callable</code> or calling
382: * <code>UMOManager.getEventContext</code> to obtain the MuleEventContext for
383: * the current thread. The user can programmatically control how events are
384: * dispached.
385: *
386: * @return Returns true is the user has set stopFurtherProcessing.
387: * @see org.mule.api.context.UMOManager
388: * @see MuleEventContext
389: * @see org.mule.api.lifecycle.Callable
390: */
391: boolean isStopFurtherProcessing();
392:
393: /**
394: * Determines whether the default processing for this event will be executed. By
395: * default, the Mule server will route events according to a components
396: * configuration. The user can override this behaviour by obtaining a reference
397: * to the MuleEvent context, either by implementing
398: * <code>org.mule.api.lifecycle.Callable</code> or calling
399: * <code>UMOManager.getEventContext</code> to obtain the MuleEventContext for
400: * the current thread. The user can programmatically control how events are
401: * dispached.
402: *
403: * @param stopFurtherProcessing the value to set.
404: */
405: void setStopFurtherProcessing(boolean stopFurtherProcessing);
406:
407: /**
408: * An outputstream the can optionally be used write response data to an incoming
409: * message.
410: *
411: * @return an output strem if one has been made available by the message receiver
412: * that received the message
413: */
414: OutputStream getOutputStream();
415:
416: /**
417: * Determines whether the was sent synchrounously or not
418: *
419: * @return true if the event is synchronous
420: */
421: boolean isSynchronous();
422:
423: /**
424: * Returns a reference to the Endpoint Uri for this context This is the endpoint
425: * on which the event was received
426: *
427: * @return the receive endpoint for this event context
428: */
429: EndpointURI getEndpointURI();
430:
431: /**
432: * Returns the transaction for the current event or null if there is no
433: * transaction in progresss
434: *
435: * @return the transaction for the current event or null if there is no
436: * transaction in progresss
437: */
438: Transaction getTransaction();
439:
440: /**
441: * Get the timeout value associated with the event
442: *
443: * @return the timeout for the event
444: */
445: int getTimeout();
446:
447: /**
448: * Gets the encoding for the current message. For potocols that send encoding
449: * Information with the message, this method should be overriden to expose the
450: * transport encoding, otherwise the default encoding in the Mule configuration
451: * will be used
452: *
453: * @return the encoding for this message. This method must never return null
454: */
455: String getEncoding();
456:
457: MuleSession getSession();
458:
459: MuleContext getMuleContext();
460: }
|