1 /* 2 * $Id: MuleEvent.java 10529 2008-01-25 05:58:36Z dfeist $ 3 * -------------------------------------------------------------------------------------- 4 * Copyright (c) MuleSource, Inc. All rights reserved. http://www.mulesource.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.endpoint.ImmutableEndpoint; 14 import org.mule.api.security.Credentials; 15 import org.mule.api.service.Service; 16 import org.mule.api.transformer.TransformerException; 17 18 import java.io.OutputStream; 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 UMO understands. The event can also maintain any number of 26 * properties that can be set and retrieved by Mule UMO components. 27 * 28 * @see MuleMessage 29 */ 30 public interface MuleEvent 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 * Reterns the conents of the message as a byte array. 47 * 48 * @return the conents 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 */ 62 Object transformMessage() throws TransformerException; 63 64 /** 65 * Transforms the message into the requested format. The transformer used is 66 * the one configured on the endpoint through which this event was received. 67 * 68 * @param outputType The requested output type. 69 * @return the message transformed into it's recognised or expected format. 70 * @throws TransformerException if a failure occurs in the transformer 71 * @see org.mule.api.transformer.Transformer 72 */ 73 Object transformMessage(Class outputType) throws TransformerException; 74 75 /** 76 * Transforms the message into it's recognised or expected format and then 77 * into an array of bytes. The transformer used is the one configured on the 78 * endpoint through which this event was received. 79 * 80 * @return the message transformed into it's recognised or expected format as an 81 * array of bytes. 82 * @throws TransformerException if a failure occurs in the transformer 83 * @see org.mule.api.transformer.Transformer 84 */ 85 byte[] transformMessageToBytes() throws TransformerException; 86 87 /** 88 * Returns the message transformed into it's recognised or expected format and 89 * then into a String. The transformer used is the one configured on the endpoint 90 * through which this event was received. If necessary this will use the encoding 91 * set on the event 92 * 93 * @return the message transformed into it's recognised or expected format as a 94 * Strings. 95 * @throws TransformerException if a failure occurs in the transformer 96 * @see org.mule.api.transformer.Transformer 97 */ 98 String transformMessageToString() throws TransformerException; 99 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, boolean exhaustiveSearch); 149 150 /** 151 * Gets the endpoint associated with this event 152 * 153 * @return the endpoint associated with this event 154 */ 155 ImmutableEndpoint getEndpoint(); 156 157 /** 158 * Retrieves the service session for the current event 159 * 160 * @return the service session for the event 161 */ 162 MuleSession getSession(); 163 164 /** 165 * Retrieves the service for the current event 166 * 167 * @return the service for the event 168 */ 169 Service getService(); 170 171 /** 172 * Determines whether the default processing for this event will be executed. By 173 * default, the Mule server will route events according to a components 174 * configuration. The user can override this behaviour by obtaining a reference 175 * to the MuleEvent context, either by implementing 176 * <code>org.mule.api.lifecycle.Callable</code> or calling 177 * <code>UMOManager.getEventContext</code> to obtain the MuleEventContext for 178 * the current thread. The user can programmatically control how events are 179 * dispached. 180 * 181 * @return Returns true is the user has set stopFurtherProcessing. 182 * @see org.mule.api.context.UMOManager 183 * @see MuleEventContext 184 * @see org.mule.api.lifecycle.Callable 185 */ 186 boolean isStopFurtherProcessing(); 187 188 /** 189 * Determines whether the default processing for this event will be executed. By 190 * default, the Mule server will route events according to a components 191 * configuration. The user can override this behaviour by obtaining a reference 192 * to the MuleEvent context, either by implementing 193 * <code>org.mule.api.lifecycle.Callable</code> or calling 194 * <code>UMOManager.getEventContext</code> to obtain the MuleEventContext for 195 * the current thread. The user can programmatically control how events are 196 * dispached. 197 * 198 * @param stopFurtherProcessing the value to set. 199 */ 200 void setStopFurtherProcessing(boolean stopFurtherProcessing); 201 202 /** 203 * Determines whether the was sent synchrounously or not 204 * 205 * @return true if the event is synchronous 206 */ 207 boolean isSynchronous(); 208 209 /** 210 * Determines whether the was sent synchrounously or not 211 * 212 * @param value true if the event is synchronous 213 */ 214 void setSynchronous(boolean value); 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 }