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