Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
MuleMessage |
|
| 0.0;0 |
1 | /* | |
2 | * $Id: MuleMessage.java 20125 2010-11-09 00:38:43Z mike.schilling $ | |
3 | * -------------------------------------------------------------------------------------- | |
4 | * Copyright (c) MuleSoft, Inc. All rights reserved. http://www.mulesoft.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; | |
12 | ||
13 | import org.mule.api.transformer.DataType; | |
14 | import org.mule.api.transformer.Transformer; | |
15 | import org.mule.api.transformer.TransformerException; | |
16 | import org.mule.api.transport.PropertyScope; | |
17 | ||
18 | import java.io.Serializable; | |
19 | import java.util.List; | |
20 | import java.util.Map; | |
21 | import java.util.Set; | |
22 | ||
23 | import javax.activation.DataHandler; | |
24 | ||
25 | /** | |
26 | * <code>MuleMessage</code> represents a message payload. The Message comprises of | |
27 | * the payload itself and properties associated with the payload. | |
28 | */ | |
29 | ||
30 | public interface MuleMessage extends Serializable | |
31 | { | |
32 | /** | |
33 | * Adds a map of properties to be associated with this message | |
34 | * | |
35 | * @param properties the properties add to this message | |
36 | * @deprecated use {@link #addProperties(java.util.Map, org.mule.api.transport.PropertyScope)} instead | |
37 | */ | |
38 | @Deprecated | |
39 | void addProperties(Map<String, Object> properties); | |
40 | ||
41 | /** | |
42 | * Adds a map of properties to be associated with this message | |
43 | * | |
44 | * @param properties the properties add to this message | |
45 | * @param scope the scope in which the properties should be added | |
46 | */ | |
47 | void addProperties(Map<String, Object> properties, PropertyScope scope); | |
48 | ||
49 | /** | |
50 | * Removes all properties on this message in the {@link org.mule.api.transport.PropertyScope#INVOCATION} and | |
51 | * {@link org.mule.api.transport.PropertyScope#OUTBOUND}. | |
52 | * @deprecated use {@link #clearProperties(org.mule.api.transport.PropertyScope)} instead | |
53 | */ | |
54 | @Deprecated | |
55 | void clearProperties(); | |
56 | ||
57 | /** | |
58 | * Removes all properties on this message in the given scope. Note that the INBOUND scope is | |
59 | * read-only, so attempting to clear this scopee will result in an UnsupportedOperationException. | |
60 | * | |
61 | * @param scope the property scope to clear | |
62 | * @throws UnsupportedOperationException if scope specified is {@link org.mule.api.transport.PropertyScope#INBOUND} | |
63 | */ | |
64 | void clearProperties(PropertyScope scope); | |
65 | /** | |
66 | /** | |
67 | * | |
68 | * @deprecated use the overloaded version with an explicit lookup scope. This method will | |
69 | * now use only the outbound scope. | |
70 | * @see #getInboundProperty(String) | |
71 | * @see #getOutboundProperty(String) | |
72 | * @see #getInvocationProperty(String) | |
73 | * @see #getSessionProperty(String) | |
74 | */ | |
75 | @Deprecated | |
76 | Object getProperty(String key); | |
77 | ||
78 | /** | |
79 | * Set a property on the message. This method will now set a value on the outbound scope only. | |
80 | * @deprecated use {@link #setProperty(String, Object, org.mule.api.transport.PropertyScope)} or | |
81 | * preferrably any of the scope-specific set methods. | |
82 | * | |
83 | * @param key the key on which to associate the value | |
84 | * @param value the property value | |
85 | * @see #setInvocationProperty(String, Object) | |
86 | * @see #setOutboundProperty(String, Object) | |
87 | * @see #setSessionProperty(String, Object) | |
88 | */ | |
89 | @Deprecated | |
90 | void setProperty(String key, Object value); | |
91 | ||
92 | /** | |
93 | * @see #setProperty(String, Object, org.mule.api.transport.PropertyScope) | |
94 | */ | |
95 | void setInvocationProperty(String key, Object value); | |
96 | ||
97 | /** | |
98 | * @see #setProperty(String, Object, org.mule.api.transport.PropertyScope) | |
99 | */ | |
100 | void setOutboundProperty(String key, Object value); | |
101 | ||
102 | /** | |
103 | * Set a property on the message. End-users should prefer more | |
104 | * scope-specific methods for readability. This one is more intended for programmatic | |
105 | * scope manipulation and Mule internal use. | |
106 | * | |
107 | * @param key the key on which to associate the value | |
108 | * @param value the property value | |
109 | * @param scope The scope at which to set the property at | |
110 | * @see PropertyScope | |
111 | * @see #setInvocationProperty(String, Object) | |
112 | * @see #setOutboundProperty(String, Object) | |
113 | * @see #setSessionProperty(String, Object) | |
114 | */ | |
115 | void setProperty(String key, Object value, PropertyScope scope); | |
116 | ||
117 | /** | |
118 | * Removes a property on this message. | |
119 | * | |
120 | * @param key the property key to remove | |
121 | * @return the removed property value or null if the property did not exist | |
122 | * @deprecated use {@link #removeProperty(String, org.mule.api.transport.PropertyScope)} | |
123 | */ | |
124 | @Deprecated | |
125 | Object removeProperty(String key); | |
126 | ||
127 | /** | |
128 | * Removes a property on this message from the specified scope only. | |
129 | * | |
130 | * @param key the property key to remove | |
131 | * @param scope The scope at which to set the property at | |
132 | * @return the removed property value or null if the property did not exist | |
133 | */ | |
134 | Object removeProperty(String key, PropertyScope scope); | |
135 | ||
136 | /** | |
137 | * @return all property keys on this message. | |
138 | * @since 3.0 only the outbound scope properties are returned | |
139 | * @deprecated use {@link #getPropertyNames(org.mule.api.transport.PropertyScope)} | |
140 | */ | |
141 | @Deprecated | |
142 | Set<String> getPropertyNames(); | |
143 | ||
144 | /** | |
145 | * Gets all property names in a given scope. Prefer using one of the convenience | |
146 | * scope-aware methods instead, this one is meant for internal access mostly. | |
147 | * @param scope the scope of property names | |
148 | * @return all property keys on this message in the given scope | |
149 | * @see #getInvocationPropertyNames() | |
150 | * @see #getInboundPropertyNames() | |
151 | * @see #getOutboundPropertyNames() | |
152 | * @see #getSessionPropertyNames() | |
153 | */ | |
154 | Set<String> getPropertyNames(PropertyScope scope); | |
155 | ||
156 | Set<String> getInvocationPropertyNames(); | |
157 | Set<String> getInboundPropertyNames(); | |
158 | Set<String> getOutboundPropertyNames(); | |
159 | Set<String> getSessionPropertyNames(); | |
160 | ||
161 | ||
162 | /** | |
163 | * @return the current message | |
164 | */ | |
165 | Object getPayload(); | |
166 | ||
167 | /** | |
168 | * gets the unique identifier for the message. It's up to the implementation to | |
169 | * ensure a unique id | |
170 | * | |
171 | * @return a unique message id. The Id should never be null. If the underlying | |
172 | * transport does not have the notion of a message Id, one should be | |
173 | * generated. The generated Id should be a UUID. | |
174 | */ | |
175 | String getUniqueId(); | |
176 | ||
177 | /** | |
178 | * Gets a property from the message | |
179 | * | |
180 | * @param name the name or key of the property. This must be non-null. | |
181 | * @param defaultValue a default value if the property doesn't exist in the event. This can be null. | |
182 | * @return the property value or the defaultValue if the property does not exist | |
183 | * @deprecated use scope-aware methods instead | |
184 | * @see #getInboundProperty(String) | |
185 | * @see #getOutboundProperty(String) | |
186 | * @see #getInvocationProperty(String) | |
187 | * @see #getSessionProperty(String) | |
188 | */ | |
189 | @Deprecated | |
190 | Object getProperty(String name, Object defaultValue); | |
191 | ||
192 | /** | |
193 | * Gets a property from the message with a given scope. End-users should prefer more | |
194 | * scope-specific methods for readability. This one is more intended for programmatic | |
195 | * scope manipulation and Mule internal use. | |
196 | * | |
197 | * @param name the name or key of the property. This must be non-null. | |
198 | * @param scope The scope of the property to retrieve. This must be non-null. | |
199 | * @return the property value or null if the property does not exist in the specified scope | |
200 | * @see #getInboundProperty(String) | |
201 | * @see #getOutboundProperty(String) | |
202 | * @see #getInvocationProperty(String) | |
203 | * @see #getSessionProperty(String) | |
204 | */ | |
205 | <T> T getProperty(String name, PropertyScope scope); | |
206 | ||
207 | /** | |
208 | * @see #getProperty(String, org.mule.api.transport.PropertyScope, Object) | |
209 | */ | |
210 | <T> T getInboundProperty(String name, T defaultValue); | |
211 | ||
212 | /** | |
213 | * @see #getProperty(String, org.mule.api.transport.PropertyScope, Object) | |
214 | */ | |
215 | <T> T getInboundProperty(String name); | |
216 | ||
217 | /** | |
218 | * @see #getProperty(String, org.mule.api.transport.PropertyScope, Object) | |
219 | */ | |
220 | <T> T getInvocationProperty(String name, T defaultValue); | |
221 | ||
222 | /** | |
223 | * @see #getProperty(String, org.mule.api.transport.PropertyScope, Object) | |
224 | */ | |
225 | <T> T getInvocationProperty(String name); | |
226 | ||
227 | /** | |
228 | * @see #getProperty(String, org.mule.api.transport.PropertyScope, Object) | |
229 | */ | |
230 | <T> T getOutboundProperty(String name, T defaultValue); | |
231 | ||
232 | /** | |
233 | * @see #getProperty(String, org.mule.api.transport.PropertyScope, Object) | |
234 | */ | |
235 | <T> T getOutboundProperty(String name); | |
236 | ||
237 | /** | |
238 | * This method was added with the introduction of Property scopes. However, this method should | |
239 | * rarely be used. Instead, the scoped accessors should be used. Mule does not use this method internally | |
240 | * and may be deprecated in future versions | |
241 | * | |
242 | * The Scopes will be checked in the following order, with the first match being returned - | |
243 | * <ul> | |
244 | * <li>Outbound</li> | |
245 | * <li>Invocation</li> | |
246 | * <li>Session</li> | |
247 | * <li>Inbound</li> | |
248 | * </ul> | |
249 | * | |
250 | * @param name the name of the property to look for | |
251 | * @param defaultValue the default value that will be returned if the property is not found | |
252 | * @param <T> The Type of the property value that will be returned | |
253 | * @return TThe property value from the first scope that had the property set, or the 'defaultValue' if the property was | |
254 | * not found in any scope | |
255 | * @since 3.0 | |
256 | */ | |
257 | <T> T findPropertyInAnyScope(String name, T defaultValue); | |
258 | ||
259 | /** | |
260 | * Gets a property from the message with a given scope and provides a default value if the property is not | |
261 | * present on the message in the scope specified. The method will also type check against the default value | |
262 | * to ensure that the value is of the correct type. If null is used for the default value no type checking is | |
263 | * done. | |
264 | * @param name the name or key of the property. This must be non-null. | |
265 | * @param scope The scope of the property to retrieve. This must be non-null. | |
266 | * @param defaultValue the value to return if the property is not in the scope provided. Can be null | |
267 | * @param <T> the defaultValue type ,this is used to validate the property value type | |
268 | * @return the property value or the defaultValue if the property does not exist in the specified scope | |
269 | * @throws IllegalArgumentException if the value for the property key is not assignable from the defaultValue type | |
270 | */ | |
271 | <T> T getProperty(String name, PropertyScope scope, T defaultValue); | |
272 | ||
273 | /** | |
274 | * Gets an integer property from the message | |
275 | * | |
276 | * @param name the name or key of the property | |
277 | * @param defaultValue a default value if the property doesn't exist in the event | |
278 | * @return the property value or the defaultValue if the property does not exist | |
279 | * @deprecated use {@link #getInboundProperty(String, Object)} instead | |
280 | */ | |
281 | @Deprecated | |
282 | int getIntProperty(String name, int defaultValue); | |
283 | ||
284 | /** | |
285 | * Gets a long property from the message | |
286 | * | |
287 | * @param name the name or key of the property | |
288 | * @param defaultValue a default value if the property doesn't exist in the event | |
289 | * @return the property value or the defaultValue if the property does not exist | |
290 | * @deprecated use {@link #getInboundProperty(String, Object)} instead | |
291 | */ | |
292 | @Deprecated | |
293 | long getLongProperty(String name, long defaultValue); | |
294 | ||
295 | /** | |
296 | * Gets a double property from the message | |
297 | * | |
298 | * @param name the name or key of the property | |
299 | * @param defaultValue a default value if the property doesn't exist in the event | |
300 | * @return the property value or the defaultValue if the property does not exist | |
301 | * @deprecated use {@link #getInboundProperty(String, Object)} instead | |
302 | */ | |
303 | @Deprecated | |
304 | double getDoubleProperty(String name, double defaultValue); | |
305 | ||
306 | /** | |
307 | * Gets a String property from the message | |
308 | * | |
309 | * @param name the name or key of the property | |
310 | * @param defaultValue a default value if the property doesn't exist in the event | |
311 | * @return the property value or the defaultValue if the property does not exist | |
312 | * @deprecated use {@link #getInboundProperty(String, Object)} instead | |
313 | */ | |
314 | @Deprecated | |
315 | String getStringProperty(String name, String defaultValue); | |
316 | ||
317 | /** | |
318 | * Gets a boolean property from the message | |
319 | * | |
320 | * @param name the name or key of the property | |
321 | * @param defaultValue a default value if the property doesn't exist in the event | |
322 | * @return the property value or the defaultValue if the property does not exist | |
323 | * @deprecated use {@link #getInboundProperty(String, Object)} instead | |
324 | */ | |
325 | @Deprecated | |
326 | boolean getBooleanProperty(String name, boolean defaultValue); | |
327 | ||
328 | /** | |
329 | * Sets a boolean property on the message | |
330 | * | |
331 | * @param name the property name or key | |
332 | * @param value the property value | |
333 | * @deprecated use {@link #setOutboundProperty(String, Object)} instead | |
334 | */ | |
335 | @Deprecated | |
336 | void setBooleanProperty(String name, boolean value); | |
337 | ||
338 | /** | |
339 | * Sets a integer property on the message | |
340 | * | |
341 | * @param name the property name or key | |
342 | * @param value the property value | |
343 | * @deprecated use {@link #setOutboundProperty(String, Object)} instead | |
344 | */ | |
345 | @Deprecated | |
346 | void setIntProperty(String name, int value); | |
347 | ||
348 | /** | |
349 | * Sets a long property on the message | |
350 | * | |
351 | * @param name the property name or key | |
352 | * @param value the property value | |
353 | * @deprecated use {@link #setOutboundProperty(String, Object)} instead | |
354 | */ | |
355 | @Deprecated | |
356 | void setLongProperty(String name, long value); | |
357 | ||
358 | /** | |
359 | * Sets a double property on the message | |
360 | * | |
361 | * @param name the property name or key | |
362 | * @param value the property value | |
363 | * @deprecated use {@link #setOutboundProperty(String, Object)} instead | |
364 | */ | |
365 | @Deprecated | |
366 | void setDoubleProperty(String name, double value); | |
367 | ||
368 | /** | |
369 | * Sets a String property on the message | |
370 | * | |
371 | * @param name the property name or key | |
372 | * @param value the property value | |
373 | * @deprecated use {@link #setOutboundProperty(String, Object)} instead | |
374 | */ | |
375 | @Deprecated | |
376 | void setStringProperty(String name, String value); | |
377 | ||
378 | ||
379 | ||
380 | ||
381 | /** | |
382 | * Sets a correlationId for this message. The correlation Id can be used by | |
383 | * components in the system to manage message relations <p/> transport protocol. | |
384 | * As such not all messages will support the notion of a correlationId i.e. tcp | |
385 | * or file. In this situation the correlation Id is set as a property of the | |
386 | * message where it's up to developer to keep the association with the message. | |
387 | * For example if the message is serialised to xml the correlationId will be | |
388 | * available in the message. | |
389 | * | |
390 | * @param id the Id reference for this relationship | |
391 | */ | |
392 | void setCorrelationId(String id); | |
393 | ||
394 | /** | |
395 | * Sets a correlationId for this message. The correlation Id can be used by | |
396 | * components in the system to manage message relations. <p/> The correlationId | |
397 | * is associated with the message using the underlying transport protocol. As | |
398 | * such not all messages will support the notion of a correlationId i.e. tcp or | |
399 | * file. In this situation the correlation Id is set as a property of the message | |
400 | * where it's up to developer to keep the association with the message. For | |
401 | * example if the message is serialised to xml the correlationId will be | |
402 | * available in the message. | |
403 | * | |
404 | * @return the correlationId for this message or null if one hasn't been set | |
405 | */ | |
406 | String getCorrelationId(); | |
407 | ||
408 | /** | |
409 | * Gets the sequence or ordering number for this message in the the correlation | |
410 | * group (as defined by the correlationId) | |
411 | * | |
412 | * @return the sequence number or -1 if the sequence is not important | |
413 | */ | |
414 | int getCorrelationSequence(); | |
415 | ||
416 | /** | |
417 | * Gets the sequence or ordering number for this message in the the correlation | |
418 | * group (as defined by the correlationId) | |
419 | * | |
420 | * @param sequence the sequence number or -1 if the sequence is not important | |
421 | */ | |
422 | void setCorrelationSequence(int sequence); | |
423 | ||
424 | /** | |
425 | * Determines how many messages are in the correlation group | |
426 | * | |
427 | * @return total messages in this group or -1 if the size is not known | |
428 | */ | |
429 | int getCorrelationGroupSize(); | |
430 | ||
431 | /** | |
432 | * Determines how many messages are in the correlation group | |
433 | * | |
434 | * @param size the total messages in this group or -1 if the size is not known | |
435 | */ | |
436 | void setCorrelationGroupSize(int size); | |
437 | ||
438 | /** | |
439 | * Sets a replyTo address for this message. This is useful in an asynchronous | |
440 | * environment where the caller doesn't wait for a response and the response | |
441 | * needs to be routed somewhere for further processing. The value of this field | |
442 | * can be any valid endpointUri url. | |
443 | * | |
444 | * @param replyTo the endpointUri url to reply to | |
445 | */ | |
446 | void setReplyTo(Object replyTo); | |
447 | ||
448 | /** | |
449 | * Returns a replyTo address for this message. This is useful in an asynchronous | |
450 | * environment where the caller doesn't wait for a response and the response | |
451 | * needs to be routed somewhere for further processing. The value of this field | |
452 | * can be any valid endpointUri url. | |
453 | * | |
454 | * @return the endpointUri url to reply to or null if one has not been set | |
455 | */ | |
456 | Object getReplyTo(); | |
457 | ||
458 | /** | |
459 | * If an error occurred during the processing of this message this will return a | |
460 | * ErrorPayload that contains the root exception and Mule error code, plus any | |
461 | * other releated info | |
462 | * | |
463 | * @return The exception payload (if any) attached to this message | |
464 | */ | |
465 | ExceptionPayload getExceptionPayload(); | |
466 | ||
467 | /** | |
468 | * If an error occurs while processing this message, a ErrorPayload is attached | |
469 | * which contains the root exception and Mule error code, plus any other releated | |
470 | * info. | |
471 | * | |
472 | * @param payload The exception payload to attach to this message | |
473 | */ | |
474 | void setExceptionPayload(ExceptionPayload payload); | |
475 | ||
476 | /** | |
477 | * Allows for arbitrary data attachments to be associated with the Message. These attachments work in the | |
478 | * same way that email attachments work. Attachments can be binary or text | |
479 | * @param name the name to associate with the attachment | |
480 | * @param dataHandler The attachment datahandler to use. This will be used to interact with the attachment data | |
481 | * @throws Exception if the attachment cannot be added for any reason | |
482 | * @see javax.activation.DataHandler | |
483 | * @deprecated use {@link #addOutboundAttachment(javax.activation.DataHandler)} instead | |
484 | */ | |
485 | @Deprecated | |
486 | void addAttachment(String name, DataHandler dataHandler) throws Exception; | |
487 | ||
488 | /** | |
489 | * Allows for arbitrary data attachments to be associated with the Message. These attachments work in the | |
490 | * same way that email attachments work. Attachments can be binary or text | |
491 | * @param name the name to associate with the attachment | |
492 | * @param dataHandler The attachment {@link javax.activation.DataHandler} to use. This will be used to interact with the attachment data | |
493 | * @throws Exception if the attachment cannot be added for any reason | |
494 | * @see javax.activation.DataHandler | |
495 | * @since 3.0 | |
496 | */ | |
497 | void addOutboundAttachment(String name, DataHandler dataHandler) throws Exception; | |
498 | ||
499 | /** | |
500 | * Adds an outgoing attachment to the message | |
501 | * @param object the input stream to the contents of the attachment. This object can either be a {@link java.net.URL}, which will construct a URL data source, or | |
502 | * a {@link java.io.File}, which will construct a file data source. Any other object will be used as the raw contents of the attachment | |
503 | * @param contentType the content type of the attachment. Note that the charset attribute can be specifed too i.e. text/plain;charset=UTF-8 | |
504 | * @param name the name to associate with the attachments | |
505 | * @throws Exception if the attachment cannot be read or created | |
506 | * @since 3.0 | |
507 | */ | |
508 | void addOutboundAttachment(String name, Object object, String contentType) throws Exception; | |
509 | ||
510 | /** | |
511 | * Remove an attachment form this message with the specified name | |
512 | * @param name the name of the attachment to remove. If the attachment does not exist, the request may be ignored | |
513 | * @throws Exception different messaging systems handle attachments differently, as such some will throw an exception | |
514 | * if an attachment does dot exist. | |
515 | * @deprecated use {@link #removeOutboundAttachment(java.lang.String)} instead | |
516 | */ | |
517 | @Deprecated | |
518 | void removeAttachment(String name) throws Exception; | |
519 | ||
520 | /** | |
521 | * Remove an attachment form this message with the specified name | |
522 | * @param name the name of the attachment to remove. If the attachment does not exist, the request may be ignored | |
523 | * @throws Exception different messaging systems handle attachments differently, as such some will throw an exception | |
524 | * if an attachment does dot exist. | |
525 | * @since 3.0 | |
526 | */ | |
527 | void removeOutboundAttachment(String name) throws Exception; | |
528 | ||
529 | /** | |
530 | * Retrieve an attachment with the given name. If the attachment does not exist, null will be returned | |
531 | * @param name the name of the attachment to retrieve | |
532 | * @return the attachment with the given name or null if the attachment does not exist | |
533 | * @see javax.activation.DataHandler | |
534 | * @deprecated use {@link #getInboundAttachment(String)} instead | |
535 | */ | |
536 | @Deprecated | |
537 | DataHandler getAttachment(String name); | |
538 | ||
539 | /** | |
540 | * Retrieve an attachment with the given name. If the attachment does not exist, null will be returned | |
541 | * @param name the name of the attachment to retrieve | |
542 | * @return the attachment with the given name or null if the attachment does not exist | |
543 | * @see javax.activation.DataHandler | |
544 | * @since 3.0 | |
545 | */ | |
546 | DataHandler getInboundAttachment(String name); | |
547 | ||
548 | /** | |
549 | * Retrieve an attachment with the given name. If the attachment does not exist, null will be returned | |
550 | * @param name the name of the attachment to retrieve | |
551 | * @return the attachment with the given name or null if the attachment does not exist | |
552 | * @see javax.activation.DataHandler | |
553 | * @since 3.0 | |
554 | */ | |
555 | DataHandler getOutboundAttachment(String name); | |
556 | ||
557 | /** | |
558 | * @return a set of the names of the attachments on this message. If there are no attachments an empty set will be | |
559 | * returned. | |
560 | * @deprecated use {@link #getInboundAttachmentNames()} | |
561 | */ | |
562 | @Deprecated | |
563 | Set<String> getAttachmentNames(); | |
564 | ||
565 | /** | |
566 | * @return a set of the names of the attachments on this message. If there are no attachments an empty set will be | |
567 | * returned. | |
568 | * @since 3.0 | |
569 | */ | |
570 | Set<String> getInboundAttachmentNames(); | |
571 | ||
572 | /** | |
573 | * @return a set of the names of the attachments on this message. If there are no attachments an empty set will be | |
574 | * returned. | |
575 | * @since 3.0 | |
576 | */ | |
577 | Set<String> getOutboundAttachmentNames(); | |
578 | ||
579 | /** | |
580 | * Gets the encoding for the current message. For potocols that send encoding | |
581 | * information with the message, this method should be overriden to expose the | |
582 | * transport encoding, otherwise the default encoding in the Mule configuration | |
583 | * will be used. | |
584 | * | |
585 | * @return the encoding for this message. This method must never return null | |
586 | */ | |
587 | String getEncoding(); | |
588 | ||
589 | /** | |
590 | * Sets the encoding for this message | |
591 | * | |
592 | * @param encoding the encoding to use | |
593 | */ | |
594 | void setEncoding(String encoding); | |
595 | ||
596 | /** | |
597 | * Perform any clean up operations on the message resource. | |
598 | * Typically this is used to esure that a message stream is closed | |
599 | */ | |
600 | void release(); | |
601 | ||
602 | /** | |
603 | * Will apply a list of transformers to the payload of the message. This *Will* change the payload of the | |
604 | * message. This method provides the only way to alter the paylaod of this message without recreating a | |
605 | * copy of the message | |
606 | * @param event the event being processed | |
607 | * @param transformers the transformers to apply to the message payload | |
608 | * @throws TransformerException if a transformation error occurs or one or more of the transformers passed in a | |
609 | * are incompatible with the message payload | |
610 | */ | |
611 | void applyTransformers(MuleEvent event, List<? extends Transformer> transformers) throws MuleException; | |
612 | ||
613 | /** | |
614 | * Will apply a list of transformers to the payload of the message. This *Will* change the payload of the | |
615 | * message. This method provides the only way to alter the paylaod of this message without recreating a | |
616 | * copy of the message | |
617 | * @param event the event being processed | |
618 | * @param transformers the transformers to apply to the message payload | |
619 | * @throws TransformerException if a transformation error occurs or one or more of the transformers passed in a | |
620 | * are incompatible with the message payload | |
621 | */ | |
622 | void applyTransformers(MuleEvent event, Transformer... transformers) throws MuleException; | |
623 | ||
624 | /** | |
625 | * Will apply a list of transformers to the payload of the message. This *Will* change the payload of the | |
626 | * message. This method provides the only way to alter the paylaod of this message without recreating a | |
627 | * copy of the message | |
628 | * @param event the event being processed | |
629 | * @param transformers the transformers to apply to the message payload | |
630 | * @param outputType the required output type for this transformation. by adding this parameter some additional | |
631 | * transformations will occur on the message payload to ensure that the final payload is of the specified type. | |
632 | * If no transformers can be found in the registry that can transform from the return type of the transformation | |
633 | * list to the outputType and exception will be thrown | |
634 | * @throws TransformerException if a transformation error occurs or one or more of the transformers passed in a | |
635 | * are incompatible with the message payload | |
636 | */ | |
637 | void applyTransformers(MuleEvent event, List<? extends Transformer> transformers, Class<?> outputType) throws MuleException; | |
638 | ||
639 | /** | |
640 | * Update the message payload. This is typically only called if the | |
641 | * payload was originally an InputStream. In which case, if the InputStream | |
642 | * is consumed, it needs to be replaced for future access. | |
643 | * | |
644 | * @param payload the object to assign as the message payload | |
645 | */ | |
646 | void setPayload(Object payload); | |
647 | ||
648 | /** | |
649 | * Will attempt to obtain the payload of this message with the desired Class type. This will | |
650 | * try and resolve a transformer that can do this transformation. If a transformer cannot be found | |
651 | * an exception is thrown. Any transformers added to the registry will be checked for compatibility | |
652 | * @param outputType the desired return type | |
653 | * @return The converted payload of this message. Note that this method will not alter the payload of this | |
654 | * message *unless* the payload is an InputStream in which case the stream will be read and the payload will become | |
655 | * the fully read stream. | |
656 | * @throws TransformerException if a transformer cannot be found or there is an error during transformation of the | |
657 | * payload | |
658 | */ | |
659 | <T> T getPayload(Class<T> outputType) throws TransformerException; | |
660 | ||
661 | /** | |
662 | * Will attempt to obtain the payload of this message with the desired Class type. This will | |
663 | * try and resolve a transformer that can do this transformation. If a transformer cannot be found | |
664 | * an exception is thrown. Any transformers added to the registry will be checked for compatability | |
665 | * @param outputType the desired return type | |
666 | * @return The converted payload of this message. Note that this method will not alter the payload of this | |
667 | * message *unless* the payload is an InputStream in which case the stream will be read and the payload will become | |
668 | * the fully read stream. | |
669 | * @throws TransformerException if a transformer cannot be found or there is an error during transformation of the | |
670 | * payload | |
671 | */ | |
672 | <T> T getPayload(DataType<T> outputType) throws TransformerException; | |
673 | ||
674 | ||
675 | /** | |
676 | * Converts the message implementation into a String representation | |
677 | * | |
678 | * @param encoding The encoding to use when transforming the message (if | |
679 | * necessary). The parameter is used when converting from a byte array | |
680 | * @return String representation of the message payload | |
681 | * @throws Exception Implementation may throw an endpoint specific exception | |
682 | */ | |
683 | String getPayloadAsString(String encoding) throws Exception; | |
684 | ||
685 | /** | |
686 | * Converts the message implementation into a String representation. If encoding | |
687 | * is required it will use the encoding set on the message | |
688 | * | |
689 | * @return String representation of the message payload | |
690 | * @throws Exception Implementation may throw an endpoint specific exception | |
691 | * | |
692 | */ | |
693 | String getPayloadAsString() throws Exception; | |
694 | ||
695 | /** | |
696 | * Converts the message implementation into a byte array representation | |
697 | * | |
698 | * @return byte array of the message | |
699 | * @throws Exception Implemetation may throw an endpoint specific exception | |
700 | * | |
701 | */ | |
702 | byte[] getPayloadAsBytes() throws Exception; | |
703 | ||
704 | /** | |
705 | * Returns the original payload used to create this message. The payload of the message can change | |
706 | * if {@link #applyTransformers(MuleEvent,java.util.List)} or | |
707 | * {@link #applyTransformers(MuleEvent, java.util.List, Class)} is called. | |
708 | * @return the original payload used to create this message | |
709 | */ | |
710 | Object getOriginalPayload(); | |
711 | ||
712 | /** | |
713 | * Get the message payload for logging without throwing exception | |
714 | * Converts the message implementation into a String representation. | |
715 | * | |
716 | * @return message payload as object | |
717 | */ | |
718 | String getPayloadForLogging(); | |
719 | ||
720 | /** | |
721 | * Get the message payload for logging without throwing exception | |
722 | * Converts the message implementation into a String representation. If encoding | |
723 | * is required it will use the encoding set on the message | |
724 | * | |
725 | * @return message payload as object | |
726 | */ | |
727 | String getPayloadForLogging(String encoding); | |
728 | ||
729 | MuleContext getMuleContext(); | |
730 | ||
731 | /** | |
732 | * Returns the data type (if any) associated with the message's payload. | |
733 | */ | |
734 | DataType<?> getDataType(); | |
735 | ||
736 | <T> T getSessionProperty(String name, T defaultValue); | |
737 | ||
738 | <T> T getSessionProperty(String name); | |
739 | ||
740 | void setSessionProperty(String key, Object value); | |
741 | ||
742 | /** | |
743 | * Copy an inbound message to an outbound one, moving all message properties and attachments | |
744 | * @return the inbound message | |
745 | */ | |
746 | MuleMessage createInboundMessage() throws Exception; | |
747 | } |