1 /* 2 * $Id: UMOMessageAdapter.java 7976 2007-08-21 14:26:13Z 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.provider; 12 13 import org.mule.umo.UMOExceptionPayload; 14 15 import java.io.Serializable; 16 import java.util.Map; 17 import java.util.Set; 18 19 import javax.activation.DataHandler; 20 21 /** 22 * <code>UMOMessageAdapter</code> provides a common abstraction of different 23 * message implementations provided by different underlying technologies. 24 */ 25 public interface UMOMessageAdapter extends Serializable 26 { 27 28 /** 29 * Adds a map of properties to be associated with this message 30 * 31 * @param properties the properties add to this message 32 */ 33 void addProperties(Map properties); 34 35 /** 36 * Removes all properties on this message 37 */ 38 void clearProperties(); 39 40 /** 41 * Gets a property of the message implementation 42 * 43 * @param key the key on which to lookup the property value 44 * @return the property value or null if the property does not exist 45 */ 46 Object getProperty(String key); 47 48 /** 49 * Set a property on the message 50 * 51 * @param key the key on which to associate the value 52 * @param value the property value 53 */ 54 void setProperty(String key, Object value); 55 56 /** 57 * Removes a property on this message 58 * 59 * @param key the property key to remove 60 * @return the removed property value or null if the property did not exist 61 */ 62 Object removeProperty(String key); 63 64 /** 65 * Converts the message implementation into a String representation 66 * 67 * @param encoding The encoding to use when transforming the message (if 68 * necessary). The parameter is used when converting from a byte array 69 * @return String representation of the message payload 70 * @throws Exception Implementation may throw an endpoint specific exception 71 */ 72 String getPayloadAsString(String encoding) throws Exception; 73 74 /** 75 * Converts the message implementation into a String representation. If encoding 76 * is required it will use the encoding set on the message 77 * 78 * @return String representation of the message payload 79 * @throws Exception Implementation may throw an endpoint specific exception 80 */ 81 String getPayloadAsString() throws Exception; 82 83 /** 84 * @return all property keys on this message 85 */ 86 Set getPropertyNames(); 87 88 /** 89 * Converts the message implementation into a byte array representation 90 * 91 * @return byte array of the message 92 * @throws Exception Implemetation may throw an endpoint specific exception 93 */ 94 byte[] getPayloadAsBytes() throws Exception; 95 96 /** 97 * @return the current message 98 */ 99 Object getPayload(); 100 101 /** 102 * gets the unique identifier for the message. It's up to the implementation to 103 * ensure a unique id 104 * 105 * @return a unique message id. The Id should never be null. If the underlying 106 * transport does not have the notion of a message Id, one shuold be 107 * generated. The generated Id should be a UUID. 108 */ 109 String getUniqueId(); 110 111 /** 112 * Gets a property from the event 113 * 114 * @param name the name or key of the property 115 * @param defaultValue a default value if the property doesn't exist in the event 116 * @return the property value or the defaultValue if the property does not exist 117 */ 118 Object getProperty(String name, Object defaultValue); 119 120 /** 121 * Gets an integer property from the event 122 * 123 * @param name the name or key of the property 124 * @param defaultValue a default value if the property doesn't exist in the event 125 * @return the property value or the defaultValue if the property does not exist 126 */ 127 int getIntProperty(String name, int defaultValue); 128 129 /** 130 * Gets a long property from the event 131 * 132 * @param name the name or key of the property 133 * @param defaultValue a default value if the property doesn't exist in the event 134 * @return the property value or the defaultValue if the property does not exist 135 */ 136 long getLongProperty(String name, long defaultValue); 137 138 /** 139 * Gets a double property from the event 140 * 141 * @param name the name or key of the property 142 * @param defaultValue a default value if the property doesn't exist in the event 143 * @return the property value or the defaultValue if the property does not exist 144 */ 145 double getDoubleProperty(String name, double defaultValue); 146 147 /** 148 * Gets a boolean property from the event 149 * 150 * @param name the name or key of the property 151 * @param defaultValue a default value if the property doesn't exist in the event 152 * @return the property value or the defaultValue if the property does not exist 153 */ 154 boolean getBooleanProperty(String name, boolean defaultValue); 155 156 /** 157 * Sets a boolean property on the event 158 * 159 * @param name the property name or key 160 * @param value the property value 161 */ 162 void setBooleanProperty(String name, boolean value); 163 164 /** 165 * Sets a integerproperty on the event 166 * 167 * @param name the property name or key 168 * @param value the property value 169 */ 170 void setIntProperty(String name, int value); 171 172 /** 173 * Sets a long property on the event 174 * 175 * @param name the property name or key 176 * @param value the property value 177 */ 178 void setLongProperty(String name, long value); 179 180 /** 181 * Sets a double property on the event 182 * 183 * @param name the property name or key 184 * @param value the property value 185 */ 186 void setDoubleProperty(String name, double value); 187 188 /** 189 * Gets a String property from the event 190 * 191 * @param name the name or key of the property 192 * @param defaultValue a default value if the property doesn't exist in the event 193 * @return the property value or the defaultValue if the property does not exist 194 */ 195 String getStringProperty(String name, String defaultValue); 196 197 /** 198 * Sets a String property on the event 199 * 200 * @param name the property name or key 201 * @param value the property value 202 */ 203 void setStringProperty(String name, String value); 204 205 /** 206 * Sets a correlationId for this message. The correlation Id can be used by 207 * components in the system to manage message relations <p/> transport protocol. 208 * As such not all messages will support the notion of a correlationId i.e. tcp 209 * or file. In this situation the correlation Id is set as a property of the 210 * message where it's up to developer to keep the association with the message. 211 * For example if the message is serialised to xml the correlationId will be 212 * available in the message. 213 * 214 * @param id the Id reference for this relationship 215 */ 216 void setCorrelationId(String id); 217 218 /** 219 * Sets a correlationId for this message. The correlation Id can be used by 220 * components in the system to manage message relations. <p/> The correlationId 221 * is associated with the message using the underlying transport protocol. As 222 * such not all messages will support the notion of a correlationId i.e. tcp or 223 * file. In this situation the correlation Id is set as a property of the message 224 * where it's up to developer to keep the association with the message. For 225 * example if the message is serialised to xml the correlationId will be 226 * available in the message. 227 * 228 * @return the correlationId for this message or null if one hasn't been set 229 */ 230 String getCorrelationId(); 231 232 /** 233 * Gets the sequence or ordering number for this message in the the correlation 234 * group (as defined by the correlationId) 235 * 236 * @return the sequence number or -1 if the sequence is not important 237 */ 238 int getCorrelationSequence(); 239 240 /** 241 * Gets the sequence or ordering number for this message in the the correlation 242 * group (as defined by the correlationId) 243 * 244 * @param sequence the sequence number or -1 if the sequence is not important 245 */ 246 void setCorrelationSequence(int sequence); 247 248 /** 249 * Determines how many messages are in the correlation group 250 * 251 * @return total messages in this group or -1 if the size is not known 252 */ 253 int getCorrelationGroupSize(); 254 255 /** 256 * Determines how many messages are in the correlation group 257 * 258 * @param size the total messages in this group or -1 if the size is not known 259 */ 260 void setCorrelationGroupSize(int size); 261 262 /** 263 * Sets a replyTo address for this message. This is useful in an asynchronous 264 * environment where the caller doesn't wait for a response and the response 265 * needs to be routed somewhere for further processing. The value of this field 266 * can be any valid endpointUri url. 267 * 268 * @param replyTo the endpointUri url to reply to 269 */ 270 void setReplyTo(Object replyTo); 271 272 /** 273 * Returns a replyTo address for this message. This is useful in an asynchronous 274 * environment where the caller doesn't wait for a response and the response 275 * needs to be routed somewhere for further processing. The value of this field 276 * can be any valid endpointUri url. 277 * 278 * @return the endpointUri url to reply to or null if one has not been set 279 */ 280 Object getReplyTo(); 281 282 /** 283 * If an error occurred during the processing of this message this will return a 284 * ErrorPayload that contains the root exception and Mule error code, plus any 285 * other releated info 286 * 287 * @return The exception payload (if any) attached to this message 288 */ 289 UMOExceptionPayload getExceptionPayload(); 290 291 /** 292 * If an error occurs while processing this message, a ErrorPayload is attached 293 * which contains the root exception and Mule error code, plus any other releated 294 * info 295 * 296 * @param payload The exception payloaad to attach to this message 297 */ 298 void setExceptionPayload(UMOExceptionPayload payload); 299 300 void addAttachment(String name, DataHandler dataHandler) throws Exception; 301 302 void removeAttachment(String name) throws Exception; 303 304 DataHandler getAttachment(String name); 305 306 Set getAttachmentNames(); 307 308 /** 309 * Gets the encoding for the current message. For potocols that send encoding 310 * information with the message, this method should be overriden to expose the 311 * transport encoding, otherwise the default encoding in the Mule configuration 312 * will be used. 313 * 314 * @return the encoding for this message. This method must never return null 315 */ 316 String getEncoding(); 317 318 /** 319 * Sets the encoding for this message 320 * 321 * @param encoding the encoding to use 322 */ 323 void setEncoding(String encoding); 324 325 }