UMOMessageAdapter


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