View Javadoc

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 }