Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
UMOMessageAdapter |
|
| 1.0;1 |
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 | } |