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