1 /* 2 * $Id: UMOEvent.java 7963 2007-08-21 08:53:15Z dirk.olmes $ 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.umo; 12 13 import org.mule.umo.endpoint.UMOImmutableEndpoint; 14 import org.mule.umo.security.UMOCredentials; 15 import org.mule.umo.transformer.TransformerException; 16 17 import java.io.OutputStream; 18 19 /** 20 * <code>UMOEvent</code> represents any data event occuring in the Mule 21 * environment. All data sent or received within the mule environment will be passed 22 * between components as an UMOEvent. <p/> <p/> The UMOEvent holds a UMOMessage 23 * payload and provides helper methods for obtaining the data in a format that the 24 * receiving Mule UMO understands. The event can also maintain any number of 25 * properties that can be set and retrieved by Mule UMO components. 26 * 27 * @see UMOMessage 28 */ 29 public interface UMOEvent 30 { 31 int TIMEOUT_WAIT_FOREVER = 0; 32 int TIMEOUT_DO_NOT_WAIT = -1; 33 int TIMEOUT_NOT_SET_VALUE = Integer.MIN_VALUE; 34 35 /** 36 * Returns the message payload for this event 37 * 38 * @return the message payload for this event 39 */ 40 UMOMessage getMessage(); 41 42 UMOCredentials getCredentials(); 43 44 /** 45 * Reterns the conents of the message as a byte array. 46 * 47 * @return the conents of the message as a byte array 48 * @throws UMOException if the message cannot be converted into an array of bytes 49 */ 50 byte[] getMessageAsBytes() throws UMOException; 51 52 /** 53 * Returns the message transformed into it's recognised or expected format. The 54 * transformer used is the one configured on the endpoint through which this 55 * event was received. 56 * 57 * @return the message transformed into it's recognised or expected format. 58 * @throws TransformerException if a failure occurs in the transformer 59 * @see org.mule.umo.transformer.UMOTransformer 60 */ 61 Object getTransformedMessage() throws TransformerException; 62 63 /** 64 * Returns the message transformed into it's recognised or expected format and 65 * then into an array of bytes. The transformer used is the one configured on the 66 * endpoint through which this event was received. 67 * 68 * @return the message transformed into it's recognised or expected format as an 69 * array of bytes. 70 * @throws TransformerException if a failure occurs in the transformer 71 * @see org.mule.umo.transformer.UMOTransformer 72 */ 73 byte[] getTransformedMessageAsBytes() throws TransformerException; 74 75 /** 76 * Returns the message transformed into it's recognised or expected format and 77 * then into a String. The transformer used is the one configured on the endpoint 78 * through which this event was received. If necessary this will use the encoding 79 * set on the event 80 * 81 * @return the message transformed into it's recognised or expected format as a 82 * Strings. 83 * @throws TransformerException if a failure occurs in the transformer 84 * @see org.mule.umo.transformer.UMOTransformer 85 */ 86 String getTransformedMessageAsString() throws TransformerException; 87 88 /** 89 * Returns the message contents as a string If necessary this will use the 90 * encoding set on the event 91 * 92 * @return the message contents as a string 93 * @throws UMOException if the message cannot be converted into a string 94 */ 95 String getMessageAsString() throws UMOException; 96 97 /** 98 * Returns the message transformed into it's recognised or expected format and 99 * then into a String. The transformer used is the one configured on the endpoint 100 * through which this event was received. 101 * 102 * @param encoding the encoding to use when converting the message to string 103 * @return the message transformed into it's recognised or expected format as a 104 * Strings. 105 * @throws TransformerException if a failure occurs in the transformer 106 * @see org.mule.umo.transformer.UMOTransformer 107 */ 108 String getTransformedMessageAsString(String encoding) throws TransformerException; 109 110 /** 111 * Returns the message contents as a string 112 * 113 * @param encoding the encoding to use when converting the message to string 114 * @return the message contents as a string 115 * @throws UMOException if the message cannot be converted into a string 116 */ 117 String getMessageAsString(String encoding) throws UMOException; 118 119 /** 120 * Every event in the system is assigned a universally unique id (UUID). 121 * 122 * @return the unique identifier for the event 123 */ 124 String getId(); 125 126 /** 127 * Gets a property associated with the current event. If 128 * <code>exhaustiveSearch</code> is true, the endpoint and connector associated 129 * with the event will also be searched for the property. 130 * 131 * @param name the property name 132 * @param exhaustiveSearch also search the endpoint and connector for the 133 * property 134 * @return the property value or null if the property does not exist 135 */ 136 Object getProperty(String name, boolean exhaustiveSearch); 137 138 /** 139 * Gets a property associated with the current event. If 140 * <code>exhaustiveSearch</code> is true, the endpoint and connector associated 141 * with the event will also be searched for the property. 142 * 143 * @param name the property name 144 * @param defaultValue a default value if the property doesn't exist in the event 145 * @param exhaustiveSearch also search the endpoint and connector for the 146 * property 147 * @return the property value or the defaultValue if the property does not exist 148 */ 149 Object getProperty(String name, Object defaultValue, boolean exhaustiveSearch); 150 151 /** 152 * Gets the endpoint associated with this event 153 * 154 * @return the endpoint associated with this event 155 */ 156 UMOImmutableEndpoint getEndpoint(); 157 158 /** 159 * Retrieves the component session for the current event 160 * 161 * @return the component session for the event 162 */ 163 UMOSession getSession(); 164 165 /** 166 * Retrieves the component for the current event 167 * 168 * @return the component for the event 169 */ 170 UMOComponent getComponent(); 171 172 /** 173 * Determines whether the default processing for this event will be executed. By 174 * default, the Mule server will route events according to a components 175 * configuration. The user can override this behaviour by obtaining a reference 176 * to the Event context, either by implementing 177 * <code>org.mule.umo.lifecycle.Callable</code> or calling 178 * <code>UMOManager.getEventContext</code> to obtain the UMOEventContext for 179 * the current thread. The user can programmatically control how events are 180 * dispached. 181 * 182 * @return Returns true is the user has set stopFurtherProcessing. 183 * @see org.mule.umo.manager.UMOManager 184 * @see UMOEventContext 185 * @see org.mule.umo.lifecycle.Callable 186 */ 187 boolean isStopFurtherProcessing(); 188 189 /** 190 * Determines whether the default processing for this event will be executed. By 191 * default, the Mule server will route events according to a components 192 * configuration. The user can override this behaviour by obtaining a reference 193 * to the Event context, either by implementing 194 * <code>org.mule.umo.lifecycle.Callable</code> or calling 195 * <code>UMOManager.getEventContext</code> to obtain the UMOEventContext for 196 * the current thread. The user can programmatically control how events are 197 * dispached. 198 * 199 * @param stopFurtherProcessing the value to set. 200 */ 201 void setStopFurtherProcessing(boolean stopFurtherProcessing); 202 203 /** 204 * Determines whether the was sent synchrounously or not 205 * 206 * @return true if the event is synchronous 207 */ 208 boolean isSynchronous(); 209 210 /** 211 * Determines whether the was sent synchrounously or not 212 * 213 * @param value true if the event is synchronous 214 */ 215 void setSynchronous(boolean value); 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 * Determines whether the event flow is being streamed 246 * 247 * @return true if the request should be streamed 248 */ 249 boolean isStreaming(); 250 251 /** 252 * Gets the encoding for this message. 253 * 254 * @return the encoding for the event. This must never return null. 255 */ 256 String getEncoding(); 257 258 }