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