001: /*
002: * $Id: MuleEvent.java 10529 2008-01-25 05:58:36Z 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.ImmutableEndpoint;
014: import org.mule.api.security.Credentials;
015: import org.mule.api.service.Service;
016: import org.mule.api.transformer.TransformerException;
017:
018: import java.io.OutputStream;
019:
020: /**
021: * <code>MuleEvent</code> represents any data event occuring in the Mule
022: * environment. All data sent or received within the mule environment will be passed
023: * between components as an MuleEvent. <p/> <p/> The MuleEvent holds a MuleMessage
024: * payload and provides helper methods for obtaining the data in a format that the
025: * receiving Mule UMO understands. The event can also maintain any number of
026: * properties that can be set and retrieved by Mule UMO components.
027: *
028: * @see MuleMessage
029: */
030: public interface MuleEvent {
031: int TIMEOUT_WAIT_FOREVER = 0;
032: int TIMEOUT_DO_NOT_WAIT = -1;
033: int TIMEOUT_NOT_SET_VALUE = Integer.MIN_VALUE;
034:
035: /**
036: * Returns the message payload for this event
037: *
038: * @return the message payload for this event
039: */
040: MuleMessage getMessage();
041:
042: Credentials getCredentials();
043:
044: /**
045: * Reterns the conents of the message as a byte array.
046: *
047: * @return the conents of the message as a byte array
048: * @throws MuleException if the message cannot be converted into an array of bytes
049: */
050: byte[] getMessageAsBytes() throws MuleException;
051:
052: /**
053: * Transforms the message into it's recognised or expected format. The
054: * transformer used is the one configured on the endpoint through which this
055: * event was received.
056: *
057: * @return the message transformed into it's recognised or expected format.
058: * @throws TransformerException if a failure occurs in the transformer
059: * @see org.mule.api.transformer.Transformer
060: */
061: Object transformMessage() throws TransformerException;
062:
063: /**
064: * Transforms the message into the requested format. The transformer used is
065: * the one configured on the endpoint through which this event was received.
066: *
067: * @param outputType The requested output type.
068: * @return the message transformed into it's recognised or expected format.
069: * @throws TransformerException if a failure occurs in the transformer
070: * @see org.mule.api.transformer.Transformer
071: */
072: Object transformMessage(Class outputType)
073: throws TransformerException;
074:
075: /**
076: * Transforms the message into it's recognised or expected format and then
077: * into an array of bytes. The transformer used is the one configured on the
078: * endpoint through which this event was received.
079: *
080: * @return the message transformed into it's recognised or expected format as an
081: * array of bytes.
082: * @throws TransformerException if a failure occurs in the transformer
083: * @see org.mule.api.transformer.Transformer
084: */
085: byte[] transformMessageToBytes() throws TransformerException;
086:
087: /**
088: * Returns the message transformed into it's recognised or expected format and
089: * then into a String. The transformer used is the one configured on the endpoint
090: * through which this event was received. If necessary this will use the encoding
091: * set on the event
092: *
093: * @return the message transformed into it's recognised or expected format as a
094: * Strings.
095: * @throws TransformerException if a failure occurs in the transformer
096: * @see org.mule.api.transformer.Transformer
097: */
098: String transformMessageToString() throws TransformerException;
099:
100: /**
101: * Returns the message contents as a string If necessary this will use the
102: * encoding set on the event
103: *
104: * @return the message contents as a string
105: * @throws MuleException if the message cannot be converted into a string
106: */
107: String getMessageAsString() throws MuleException;
108:
109: /**
110: * Returns the message contents as a string
111: *
112: * @param encoding the encoding to use when converting the message to string
113: * @return the message contents as a string
114: * @throws MuleException if the message cannot be converted into a string
115: */
116: String getMessageAsString(String encoding) throws MuleException;
117:
118: /**
119: * Every event in the system is assigned a universally unique id (UUID).
120: *
121: * @return the unique identifier for the event
122: */
123: String getId();
124:
125: /**
126: * Gets a property associated with the current event. If
127: * <code>exhaustiveSearch</code> is true, the endpoint and connector associated
128: * with the event will also be searched for the property.
129: *
130: * @param name the property name
131: * @param exhaustiveSearch also search the endpoint and connector for the
132: * property
133: * @return the property value or null if the property does not exist
134: */
135: Object getProperty(String name, boolean exhaustiveSearch);
136:
137: /**
138: * Gets a property associated with the current event. If
139: * <code>exhaustiveSearch</code> is true, the endpoint and connector associated
140: * with the event will also be searched for the property.
141: *
142: * @param name the property name
143: * @param defaultValue a default value if the property doesn't exist in the event
144: * @param exhaustiveSearch also search the endpoint and connector for the
145: * property
146: * @return the property value or the defaultValue if the property does not exist
147: */
148: Object getProperty(String name, Object defaultValue,
149: boolean exhaustiveSearch);
150:
151: /**
152: * Gets the endpoint associated with this event
153: *
154: * @return the endpoint associated with this event
155: */
156: ImmutableEndpoint getEndpoint();
157:
158: /**
159: * Retrieves the service session for the current event
160: *
161: * @return the service session for the event
162: */
163: MuleSession getSession();
164:
165: /**
166: * Retrieves the service for the current event
167: *
168: * @return the service for the event
169: */
170: Service getService();
171:
172: /**
173: * Determines whether the default processing for this event will be executed. By
174: * default, the Mule server will route events according to a components
175: * configuration. The user can override this behaviour by obtaining a reference
176: * to the MuleEvent context, either by implementing
177: * <code>org.mule.api.lifecycle.Callable</code> or calling
178: * <code>UMOManager.getEventContext</code> to obtain the MuleEventContext for
179: * the current thread. The user can programmatically control how events are
180: * dispached.
181: *
182: * @return Returns true is the user has set stopFurtherProcessing.
183: * @see org.mule.api.context.UMOManager
184: * @see MuleEventContext
185: * @see org.mule.api.lifecycle.Callable
186: */
187: boolean isStopFurtherProcessing();
188:
189: /**
190: * Determines whether the default processing for this event will be executed. By
191: * default, the Mule server will route events according to a components
192: * configuration. The user can override this behaviour by obtaining a reference
193: * to the MuleEvent context, either by implementing
194: * <code>org.mule.api.lifecycle.Callable</code> or calling
195: * <code>UMOManager.getEventContext</code> to obtain the MuleEventContext for
196: * the current thread. The user can programmatically control how events are
197: * dispached.
198: *
199: * @param stopFurtherProcessing the value to set.
200: */
201: void setStopFurtherProcessing(boolean stopFurtherProcessing);
202:
203: /**
204: * Determines whether the was sent synchrounously or not
205: *
206: * @return true if the event is synchronous
207: */
208: boolean isSynchronous();
209:
210: /**
211: * Determines whether the was sent synchrounously or not
212: *
213: * @param value true if the event is synchronous
214: */
215: void setSynchronous(boolean value);
216:
217: /**
218: * The number of milliseconds to wait for a return event when running
219: * synchronously. 0 wait forever -1 try and receive, but do not wait or a
220: * positive millisecond value
221: *
222: * @return the event timeout in milliseconds
223: */
224: int getTimeout();
225:
226: /**
227: * The number of milliseconds to wait for a return event when running
228: * synchronously. 0 wait forever -1 try and receive, but do not wait or a
229: * positive millisecod value
230: *
231: * @param timeout the event timeout in milliseconds
232: */
233: void setTimeout(int timeout);
234:
235: /**
236: * An outputstream the can optionally be used write response data to an incoming
237: * message.
238: *
239: * @return an output strem if one has been made available by the message receiver
240: * that received the message
241: */
242: OutputStream getOutputStream();
243:
244: /**
245: * Gets the encoding for this message.
246: *
247: * @return the encoding for the event. This must never return null.
248: */
249: String getEncoding();
250:
251: /**
252: * Returns the muleContext for the Mule node that this event was received in
253: * @return the muleContext for the Mule node that this event was received in
254: */
255: MuleContext getMuleContext();
256: }
|