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