1 /* 2 * $Id: MuleEvent.java 23054 2011-10-02 05:31:18Z dirk.olmes $ 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.security.Credentials; 16 import org.mule.api.transformer.DataType; 17 import org.mule.api.transformer.TransformerException; 18 import org.mule.api.transport.ReplyToHandler; 19 import org.mule.management.stats.ProcessingTime; 20 21 import java.io.OutputStream; 22 import java.io.Serializable; 23 import java.net.URI; 24 25 /** 26 * <code>MuleEvent</code> represents any data event occuring in the Mule 27 * environment. All data sent or received within the mule environment will be passed 28 * between components as an MuleEvent. <p/> <p/> The MuleEvent holds a MuleMessage 29 * payload and provides helper methods for obtaining the data in a format that the 30 * receiving Mule component understands. The event can also maintain any number of 31 * properties that can be set and retrieved by Mule components. 32 * 33 * @see MuleMessage 34 */ 35 public interface MuleEvent extends Serializable 36 { 37 int TIMEOUT_WAIT_FOREVER = 0; 38 int TIMEOUT_DO_NOT_WAIT = -1; 39 int TIMEOUT_NOT_SET_VALUE = Integer.MIN_VALUE; 40 41 /** 42 * Returns the message payload for this event 43 * 44 * @return the message payload for this event 45 */ 46 MuleMessage getMessage(); 47 48 Credentials getCredentials(); 49 50 /** 51 * Returns the contents of the message as a byte array. 52 * 53 * @return the contents of the message as a byte array 54 * @throws MuleException if the message cannot be converted into an array of bytes 55 */ 56 byte[] getMessageAsBytes() throws MuleException; 57 58 /** 59 * Transforms the message into it's recognised or expected format. The 60 * transformer used is the one configured on the endpoint through which this 61 * event was received. 62 * 63 * @return the message transformed into it's recognised or expected format. 64 * @throws TransformerException if a failure occurs in the transformer 65 * @see org.mule.api.transformer.Transformer 66 * @deprecated Since Mule 3.0 this method does nothing. The message is already transformed before the event reaches a component 67 * IF you need to have access to the original message, the must be no transformations before the component, this 68 * means that any 'connector-level' transfromers will have to be explicitly overriden via the service overrides on the connector. 69 */ 70 @Deprecated 71 Object transformMessage() throws TransformerException; 72 73 /** 74 * Transforms the message into the requested format. The transformer used is 75 * the one configured on the endpoint through which this event was received. 76 * 77 * @param outputType The requested output type. 78 * @return the message transformed into it's recognised or expected format. 79 * @throws TransformerException if a failure occurs in the transformer 80 * @see org.mule.api.transformer.Transformer if the transform fails or the outputtype is null 81 */ 82 <T> T transformMessage(Class<T> outputType) throws TransformerException; 83 84 /** 85 * Transforms the message into the requested format. The transformer used is 86 * the one configured on the endpoint through which this event was received. 87 * 88 * @param outputType The requested output type. 89 * @return the message transformed into it's recognised or expected format. 90 * @throws TransformerException if a failure occurs in the transformer 91 * @see org.mule.api.transformer.Transformer if the transform fails or the outputtype is null 92 */ 93 <T> T transformMessage(DataType<T> outputType) throws TransformerException; 94 95 /** 96 * Transforms the message into it's recognised or expected format and then 97 * into an array of bytes. The transformer used is the one configured on the 98 * endpoint through which this event was received. 99 * 100 * @return the message transformed into it's recognised or expected format as an 101 * array of bytes. 102 * @throws TransformerException if a failure occurs in the transformer 103 * @see org.mule.api.transformer.Transformer 104 * @deprecated use {@link #transformMessage(org.mule.api.transformer.DataType)} instead 105 */ 106 @Deprecated 107 byte[] transformMessageToBytes() throws TransformerException; 108 109 /** 110 * Returns the message transformed into it's recognised or expected format and 111 * then into a String. The transformer used is the one configured on the endpoint 112 * through which this event was received. If necessary this will use the encoding 113 * set on the event 114 * 115 * @return the message transformed into it's recognised or expected format as a 116 * Strings. 117 * @throws TransformerException if a failure occurs in the transformer 118 * @see org.mule.api.transformer.Transformer 119 */ 120 String transformMessageToString() throws TransformerException; 121 122 /** 123 * Returns the message contents as a string If necessary this will use the 124 * encoding set on the event 125 * 126 * @return the message contents as a string 127 * @throws MuleException if the message cannot be converted into a string 128 */ 129 String getMessageAsString() throws MuleException; 130 131 /** 132 * Returns the message contents as a string 133 * 134 * @param encoding the encoding to use when converting the message to string 135 * @return the message contents as a string 136 * @throws MuleException if the message cannot be converted into a string 137 */ 138 String getMessageAsString(String encoding) throws MuleException; 139 140 /** 141 * Every event in the system is assigned a universally unique id (UUID). 142 * 143 * @return the unique identifier for the event 144 */ 145 String getId(); 146 147 /** 148 * Gets a property associated with the current event. This method will check all property scopes on the currnet message 149 * and the current session 150 * 151 * @param name the property name 152 * @return the property value or null if the property does not exist 153 * @deprecated 154 */ 155 @Deprecated 156 Object getProperty(String name); 157 158 /** 159 * Gets a property associated with the current event. This method will check all property scopes on the currnet message 160 * and the current session 161 * @param name the property name 162 * @param defaultValue a default value if the property doesn't exist in the event 163 * @return the property value or the defaultValue if the property does not exist 164 * @deprecated 165 */ 166 @Deprecated 167 Object getProperty(String name, Object defaultValue); 168 169 /** 170 * Retrieves the service session for the current event 171 * 172 * @return the service session for the event 173 */ 174 MuleSession getSession(); 175 176 /** 177 * Retrieves the service for the current event 178 * 179 * @return the service for the event 180 */ 181 FlowConstruct getFlowConstruct(); 182 183 /** 184 * Determines whether the default processing for this event will be executed. By 185 * default, the Mule server will route events according to a components 186 * configuration. The user can override this behaviour by obtaining a reference 187 * to the MuleEvent context, either by implementing 188 * <code>org.mule.api.lifecycle.Callable</code> or calling 189 * <code>RequestContext.getEventContext</code> to obtain the MuleEventContext for 190 * the current thread. The user can programmatically control how events are 191 * dispached. 192 * 193 * @return Returns true is the user has set stopFurtherProcessing. 194 * @see org.mule.api.MuleContext 195 * @see MuleEventContext 196 * @see org.mule.api.lifecycle.Callable 197 */ 198 boolean isStopFurtherProcessing(); 199 200 /** 201 * Determines whether the default processing for this event will be executed. By 202 * default, the Mule server will route events according to a components 203 * configuration. The user can override this behaviour by obtaining a reference 204 * to the MuleEvent context, either by implementing 205 * <code>org.mule.api.lifecycle.Callable</code> or calling 206 * <code>RequestContext.getEventContext</code> to obtain the MuleEventContext for 207 * the current thread. The user can programmatically control how events are 208 * dispached. 209 * 210 * @param stopFurtherProcessing the value to set. 211 */ 212 void setStopFurtherProcessing(boolean stopFurtherProcessing); 213 214 /** 215 * The number of milliseconds to wait for a return event when running 216 * synchronously. 0 wait forever -1 try and receive, but do not wait or a 217 * positive millisecond value 218 * 219 * @return the event timeout in milliseconds 220 */ 221 int getTimeout(); 222 223 /** 224 * The number of milliseconds to wait for a return event when running 225 * synchronously. 0 wait forever -1 try and receive, but do not wait or a 226 * positive millisecod value 227 * 228 * @param timeout the event timeout in milliseconds 229 */ 230 void setTimeout(int timeout); 231 232 /** 233 * An outputstream the can optionally be used write response data to an incoming 234 * message. 235 * 236 * @return an output strem if one has been made available by the message receiver 237 * that received the message 238 */ 239 OutputStream getOutputStream(); 240 241 /** 242 * Gets the encoding for this message. 243 * 244 * @return the encoding for the event. This must never return null. 245 */ 246 String getEncoding(); 247 248 /** 249 * Returns the muleContext for the Mule node that this event was received in 250 * @return the muleContext for the Mule node that this event was received in 251 */ 252 MuleContext getMuleContext(); 253 254 /** 255 * Returns the times spent processing this event (so far) 256 */ 257 ProcessingTime getProcessingTime(); 258 259 /** 260 * Returns the message exchange pattern for this event 261 */ 262 MessageExchangePattern getExchangePattern(); 263 264 /** 265 * Returns true is this event is being processed in a transaction 266 */ 267 boolean isTransacted(); 268 269 /** 270 * Returns the {@link URI} of the MessageSource that recieved or generated the message being processed. 271 */ 272 URI getMessageSourceURI(); 273 274 /** 275 * Returns the message source name if it has one, otherwise returns toString() of the URI returned be 276 * getMessageSourceURI() 277 */ 278 String getMessageSourceName(); 279 280 /** 281 * Return the replyToHandler (if any) that will be used to perform async reply 282 */ 283 ReplyToHandler getReplyToHandler(); 284 285 /** 286 * Return the destination (if any) that will be passed to the reply-to handler. 287 */ 288 Object getReplyToDestination(); 289 290 /** 291 * Set the reply-to destination from the current message, and remove it from the message, to 292 * prevent any further propagation. 293 */ 294 void captureReplyToDestination(); 295 296 boolean isSynchronous(); 297 298 }