View Javadoc

1   /*
2    * $Id: UMOMessageAdapter.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.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 }