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