Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
MuleMessage |
|
| 0.0;0 |
1 | /* | |
2 | * Copyright (c) MuleSoft, Inc. All rights reserved. http://www.mulesoft.com | |
3 | * The software in this package is published under the terms of the CPAL v1.0 | |
4 | * license, a copy of which has been included with this distribution in the | |
5 | * LICENSE.txt file. | |
6 | */ | |
7 | package org.mule.api; | |
8 | ||
9 | import org.mule.api.transformer.DataType; | |
10 | import org.mule.api.transformer.Transformer; | |
11 | import org.mule.api.transformer.TransformerException; | |
12 | import org.mule.api.transport.PropertyScope; | |
13 | ||
14 | import java.io.Serializable; | |
15 | import java.util.List; | |
16 | import java.util.Map; | |
17 | import java.util.Set; | |
18 | ||
19 | import javax.activation.DataHandler; | |
20 | ||
21 | /** | |
22 | * <code>MuleMessage</code> represents a message payload. The Message comprises of | |
23 | * the payload itself and properties associated with the payload. | |
24 | */ | |
25 | ||
26 | public interface MuleMessage extends Serializable | |
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 | * @deprecated use {@link #addProperties(java.util.Map, org.mule.api.transport.PropertyScope)} instead | |
33 | */ | |
34 | @Deprecated | |
35 | void addProperties(Map<String, Object> properties); | |
36 | ||
37 | /** | |
38 | * Adds a map of properties to be associated with this message | |
39 | * | |
40 | * @param properties the properties add to this message | |
41 | * @param scope the scope in which the properties should be added | |
42 | */ | |
43 | void addProperties(Map<String, Object> properties, PropertyScope scope); | |
44 | ||
45 | /** | |
46 | * Removes all properties on this message in the {@link org.mule.api.transport.PropertyScope#INVOCATION} and | |
47 | * {@link org.mule.api.transport.PropertyScope#OUTBOUND}. | |
48 | * @deprecated use {@link #clearProperties(org.mule.api.transport.PropertyScope)} instead | |
49 | */ | |
50 | @Deprecated | |
51 | void clearProperties(); | |
52 | ||
53 | /** | |
54 | * Removes all properties on this message in the given scope. Note that the INBOUND scope is | |
55 | * read-only, so attempting to clear this scopee will result in an UnsupportedOperationException. | |
56 | * | |
57 | * @param scope the property scope to clear | |
58 | * @throws UnsupportedOperationException if scope specified is {@link org.mule.api.transport.PropertyScope#INBOUND} | |
59 | */ | |
60 | void clearProperties(PropertyScope scope); | |
61 | /** | |
62 | /** | |
63 | * | |
64 | * @deprecated use the overloaded version with an explicit lookup scope. This method will | |
65 | * now use only the outbound scope. | |
66 | * @see #getInboundProperty(String) | |
67 | * @see #getOutboundProperty(String) | |
68 | * @see #getInvocationProperty(String) | |
69 | * @see #getSessionProperty(String) | |
70 | */ | |
71 | @Deprecated | |
72 | Object getProperty(String key); | |
73 | ||
74 | /** | |
75 | * Set a property on the message. This method will now set a value on the outbound scope only. | |
76 | * @deprecated use {@link #setProperty(String, Object, org.mule.api.transport.PropertyScope)} or | |
77 | * preferrably any of the scope-specific set methods. | |
78 | * | |
79 | * @param key the key on which to associate the value | |
80 | * @param value the property value | |
81 | * @see #setInvocationProperty(String, Object) | |
82 | * @see #setOutboundProperty(String, Object) | |
83 | * @see #setSessionProperty(String, Object) | |
84 | */ | |
85 | @Deprecated | |
86 | void setProperty(String key, Object value); | |
87 | ||
88 | /** | |
89 | * @see #setProperty(String, Object, org.mule.api.transport.PropertyScope) | |
90 | */ | |
91 | void setInvocationProperty(String key, Object value); | |
92 | ||
93 | /** | |
94 | * @see #setProperty(String, Object, org.mule.api.transport.PropertyScope) | |
95 | */ | |
96 | void setOutboundProperty(String key, Object value); | |
97 | ||
98 | /** | |
99 | * Set a property on the message. End-users should prefer more | |
100 | * scope-specific methods for readability. This one is more intended for programmatic | |
101 | * scope manipulation and Mule internal use. | |
102 | * | |
103 | * @param key the key on which to associate the value | |
104 | * @param value the property value | |
105 | * @param scope The scope at which to set the property at | |
106 | * @see PropertyScope | |
107 | * @see #setInvocationProperty(String, Object) | |
108 | * @see #setOutboundProperty(String, Object) | |
109 | * @see #setSessionProperty(String, Object) | |
110 | */ | |
111 | void setProperty(String key, Object value, PropertyScope scope); | |
112 | ||
113 | /** | |
114 | * Removes a property on this message. | |
115 | * | |
116 | * @param key the property key to remove | |
117 | * @return the removed property value or null if the property did not exist | |
118 | * @deprecated use {@link #removeProperty(String, org.mule.api.transport.PropertyScope)} | |
119 | */ | |
120 | @Deprecated | |
121 | Object removeProperty(String key); | |
122 | ||
123 | /** | |
124 | * Removes a property on this message from the specified scope only. | |
125 | * | |
126 | * @param key the property key to remove | |
127 | * @param scope The scope at which to set the property at | |
128 | * @return the removed property value or null if the property did not exist | |
129 | */ | |
130 | Object removeProperty(String key, PropertyScope scope); | |
131 | ||
132 | /** | |
133 | * @return all property keys on this message. | |
134 | * @since 3.0 only the outbound scope properties are returned | |
135 | * @deprecated use {@link #getPropertyNames(org.mule.api.transport.PropertyScope)} | |
136 | */ | |
137 | @Deprecated | |
138 | Set<String> getPropertyNames(); | |
139 | ||
140 | /** | |
141 | * Gets all property names in a given scope. Prefer using one of the convenience | |
142 | * scope-aware methods instead, this one is meant for internal access mostly. | |
143 | * @param scope the scope of property names | |
144 | * @return all property keys on this message in the given scope | |
145 | * @see #getInvocationPropertyNames() | |
146 | * @see #getInboundPropertyNames() | |
147 | * @see #getOutboundPropertyNames() | |
148 | * @see #getSessionPropertyNames() | |
149 | */ | |
150 | Set<String> getPropertyNames(PropertyScope scope); | |
151 | ||
152 | Set<String> getInvocationPropertyNames(); | |
153 | Set<String> getInboundPropertyNames(); | |
154 | Set<String> getOutboundPropertyNames(); | |
155 | Set<String> getSessionPropertyNames(); | |
156 | ||
157 | ||
158 | /** | |
159 | * @return the current message | |
160 | */ | |
161 | Object getPayload(); | |
162 | ||
163 | /** | |
164 | * gets the unique identifier for the message. It's up to the implementation to | |
165 | * ensure a unique id | |
166 | * | |
167 | * @return a unique message id. The Id should never be null. If the underlying | |
168 | * transport does not have the notion of a message Id, one should be | |
169 | * generated. The generated Id should be a UUID. | |
170 | */ | |
171 | String getUniqueId(); | |
172 | ||
173 | /** | |
174 | * Gets a property from the message | |
175 | * | |
176 | * @param name the name or key of the property. This must be non-null. | |
177 | * @param defaultValue a default value if the property doesn't exist in the event. This can be null. | |
178 | * @return the property value or the defaultValue if the property does not exist | |
179 | * @deprecated use scope-aware methods instead | |
180 | * @see #getInboundProperty(String) | |
181 | * @see #getOutboundProperty(String) | |
182 | * @see #getInvocationProperty(String) | |
183 | * @see #getSessionProperty(String) | |
184 | */ | |
185 | @Deprecated | |
186 | Object getProperty(String name, Object defaultValue); | |
187 | ||
188 | /** | |
189 | * Gets a property from the message with a given scope. End-users should prefer more | |
190 | * scope-specific methods for readability. This one is more intended for programmatic | |
191 | * scope manipulation and Mule internal use. | |
192 | * | |
193 | * @param name the name or key of the property. This must be non-null. | |
194 | * @param scope The scope of the property to retrieve. This must be non-null. | |
195 | * @return the property value or null if the property does not exist in the specified scope | |
196 | * @see #getInboundProperty(String) | |
197 | * @see #getOutboundProperty(String) | |
198 | * @see #getInvocationProperty(String) | |
199 | * @see #getSessionProperty(String) | |
200 | */ | |
201 | <T> T getProperty(String name, PropertyScope scope); | |
202 | ||
203 | /** | |
204 | * @see #getProperty(String, org.mule.api.transport.PropertyScope, Object) | |
205 | */ | |
206 | <T> T getInboundProperty(String name, T defaultValue); | |
207 | ||
208 | /** | |
209 | * @see #getProperty(String, org.mule.api.transport.PropertyScope, Object) | |
210 | */ | |
211 | <T> T getInboundProperty(String name); | |
212 | ||
213 | /** | |
214 | * @see #getProperty(String, org.mule.api.transport.PropertyScope, Object) | |
215 | */ | |
216 | <T> T getInvocationProperty(String name, T defaultValue); | |
217 | ||
218 | /** | |
219 | * @see #getProperty(String, org.mule.api.transport.PropertyScope, Object) | |
220 | */ | |
221 | <T> T getInvocationProperty(String name); | |
222 | ||
223 | /** | |
224 | * @see #getProperty(String, org.mule.api.transport.PropertyScope, Object) | |
225 | */ | |
226 | <T> T getOutboundProperty(String name, T defaultValue); | |
227 | ||
228 | /** | |
229 | * @see #getProperty(String, org.mule.api.transport.PropertyScope, Object) | |
230 | */ | |
231 | <T> T getOutboundProperty(String name); | |
232 | ||
233 | /** | |
234 | * This method was added with the introduction of Property scopes. However, this method should | |
235 | * rarely be used. Instead, the scoped accessors should be used. Mule does not use this method internally | |
236 | * and may be deprecated in future versions | |
237 | * | |
238 | * The Scopes will be checked in the following order, with the first match being returned - | |
239 | * <ul> | |
240 | * <li>Outbound</li> | |
241 | * <li>Invocation</li> | |
242 | * <li>Session</li> | |
243 | * <li>Inbound</li> | |
244 | * </ul> | |
245 | * | |
246 | * @param name the name of the property to look for | |
247 | * @param defaultValue the default value that will be returned if the property is not found | |
248 | * @param <T> The Type of the property value that will be returned | |
249 | * @return TThe property value from the first scope that had the property set, or the 'defaultValue' if the property was | |
250 | * not found in any scope | |
251 | * @since 3.0 | |
252 | */ | |
253 | <T> T findPropertyInAnyScope(String name, T defaultValue); | |
254 | ||
255 | /** | |
256 | * Gets a property from the message with a given scope and provides a default value if the property is not | |
257 | * present on the message in the scope specified. The method will also type check against the default value | |
258 | * to ensure that the value is of the correct type. If null is used for the default value no type checking is | |
259 | * done. | |
260 | * @param name the name or key of the property. This must be non-null. | |
261 | * @param scope The scope of the property to retrieve. This must be non-null. | |
262 | * @param defaultValue the value to return if the property is not in the scope provided. Can be null | |
263 | * @param <T> the defaultValue type ,this is used to validate the property value type | |
264 | * @return the property value or the defaultValue if the property does not exist in the specified scope | |
265 | * @throws IllegalArgumentException if the value for the property key is not assignable from the defaultValue type | |
266 | */ | |
267 | <T> T getProperty(String name, PropertyScope scope, T defaultValue); | |
268 | ||
269 | /** | |
270 | * Gets an integer property from the message | |
271 | * | |
272 | * @param name the name or key of the property | |
273 | * @param defaultValue a default value if the property doesn't exist in the event | |
274 | * @return the property value or the defaultValue if the property does not exist | |
275 | * @deprecated use {@link #getInboundProperty(String, Object)} instead | |
276 | */ | |
277 | @Deprecated | |
278 | int getIntProperty(String name, int defaultValue); | |
279 | ||
280 | /** | |
281 | * Gets a long property from the message | |
282 | * | |
283 | * @param name the name or key of the property | |
284 | * @param defaultValue a default value if the property doesn't exist in the event | |
285 | * @return the property value or the defaultValue if the property does not exist | |
286 | * @deprecated use {@link #getInboundProperty(String, Object)} instead | |
287 | */ | |
288 | @Deprecated | |
289 | long getLongProperty(String name, long defaultValue); | |
290 | ||
291 | /** | |
292 | * Gets a double property from the message | |
293 | * | |
294 | * @param name the name or key of the property | |
295 | * @param defaultValue a default value if the property doesn't exist in the event | |
296 | * @return the property value or the defaultValue if the property does not exist | |
297 | * @deprecated use {@link #getInboundProperty(String, Object)} instead | |
298 | */ | |
299 | @Deprecated | |
300 | double getDoubleProperty(String name, double defaultValue); | |
301 | ||
302 | /** | |
303 | * Gets a String property from the message | |
304 | * | |
305 | * @param name the name or key of the property | |
306 | * @param defaultValue a default value if the property doesn't exist in the event | |
307 | * @return the property value or the defaultValue if the property does not exist | |
308 | * @deprecated use {@link #getInboundProperty(String, Object)} instead | |
309 | */ | |
310 | @Deprecated | |
311 | String getStringProperty(String name, String defaultValue); | |
312 | ||
313 | /** | |
314 | * Gets a boolean property from the message | |
315 | * | |
316 | * @param name the name or key of the property | |
317 | * @param defaultValue a default value if the property doesn't exist in the event | |
318 | * @return the property value or the defaultValue if the property does not exist | |
319 | * @deprecated use {@link #getInboundProperty(String, Object)} instead | |
320 | */ | |
321 | @Deprecated | |
322 | boolean getBooleanProperty(String name, boolean defaultValue); | |
323 | ||
324 | /** | |
325 | * Sets a boolean property on the message | |
326 | * | |
327 | * @param name the property name or key | |
328 | * @param value the property value | |
329 | * @deprecated use {@link #setOutboundProperty(String, Object)} instead | |
330 | */ | |
331 | @Deprecated | |
332 | void setBooleanProperty(String name, boolean value); | |
333 | ||
334 | /** | |
335 | * Sets a integer property on the message | |
336 | * | |
337 | * @param name the property name or key | |
338 | * @param value the property value | |
339 | * @deprecated use {@link #setOutboundProperty(String, Object)} instead | |
340 | */ | |
341 | @Deprecated | |
342 | void setIntProperty(String name, int value); | |
343 | ||
344 | /** | |
345 | * Sets a long property on the message | |
346 | * | |
347 | * @param name the property name or key | |
348 | * @param value the property value | |
349 | * @deprecated use {@link #setOutboundProperty(String, Object)} instead | |
350 | */ | |
351 | @Deprecated | |
352 | void setLongProperty(String name, long value); | |
353 | ||
354 | /** | |
355 | * Sets a double property on the message | |
356 | * | |
357 | * @param name the property name or key | |
358 | * @param value the property value | |
359 | * @deprecated use {@link #setOutboundProperty(String, Object)} instead | |
360 | */ | |
361 | @Deprecated | |
362 | void setDoubleProperty(String name, double value); | |
363 | ||
364 | /** | |
365 | * Sets a String property on the message | |
366 | * | |
367 | * @param name the property name or key | |
368 | * @param value the property value | |
369 | * @deprecated use {@link #setOutboundProperty(String, Object)} instead | |
370 | */ | |
371 | @Deprecated | |
372 | void setStringProperty(String name, String value); | |
373 | ||
374 | ||
375 | ||
376 | ||
377 | /** | |
378 | * Sets a correlationId for this message. The correlation Id can be used by | |
379 | * components in the system to manage message relations <p/> transport protocol. | |
380 | * As such not all messages will support the notion of a correlationId i.e. tcp | |
381 | * or file. In this situation the correlation Id is set as a property of the | |
382 | * message where it's up to developer to keep the association with the message. | |
383 | * For example if the message is serialised to xml the correlationId will be | |
384 | * available in the message. | |
385 | * | |
386 | * @param id the Id reference for this relationship | |
387 | */ | |
388 | void setCorrelationId(String id); | |
389 | ||
390 | /** | |
391 | * Sets a correlationId for this message. The correlation Id can be used by | |
392 | * components in the system to manage message relations. <p/> The correlationId | |
393 | * is associated with the message using the underlying transport protocol. As | |
394 | * such not all messages will support the notion of a correlationId i.e. tcp or | |
395 | * file. In this situation the correlation Id is set as a property of the message | |
396 | * where it's up to developer to keep the association with the message. For | |
397 | * example if the message is serialised to xml the correlationId will be | |
398 | * available in the message. | |
399 | * | |
400 | * @return the correlationId for this message or null if one hasn't been set | |
401 | */ | |
402 | String getCorrelationId(); | |
403 | ||
404 | /** | |
405 | * Gets the sequence or ordering number for this message in the the correlation | |
406 | * group (as defined by the correlationId) | |
407 | * | |
408 | * @return the sequence number or -1 if the sequence is not important | |
409 | */ | |
410 | int getCorrelationSequence(); | |
411 | ||
412 | /** | |
413 | * Gets the sequence or ordering number for this message in the the correlation | |
414 | * group (as defined by the correlationId) | |
415 | * | |
416 | * @param sequence the sequence number or -1 if the sequence is not important | |
417 | */ | |
418 | void setCorrelationSequence(int sequence); | |
419 | ||
420 | /** | |
421 | * Determines how many messages are in the correlation group | |
422 | * | |
423 | * @return total messages in this group or -1 if the size is not known | |
424 | */ | |
425 | int getCorrelationGroupSize(); | |
426 | ||
427 | /** | |
428 | * Determines how many messages are in the correlation group | |
429 | * | |
430 | * @param size the total messages in this group or -1 if the size is not known | |
431 | */ | |
432 | void setCorrelationGroupSize(int size); | |
433 | ||
434 | /** | |
435 | * Sets a replyTo address for this message. This is useful in an asynchronous | |
436 | * environment where the caller doesn't wait for a response and the response | |
437 | * needs to be routed somewhere for further processing. The value of this field | |
438 | * can be any valid endpointUri url. | |
439 | * | |
440 | * @param replyTo the endpointUri url to reply to | |
441 | */ | |
442 | void setReplyTo(Object replyTo); | |
443 | ||
444 | /** | |
445 | * Returns a replyTo address for this message. This is useful in an asynchronous | |
446 | * environment where the caller doesn't wait for a response and the response | |
447 | * needs to be routed somewhere for further processing. The value of this field | |
448 | * can be any valid endpointUri url. | |
449 | * | |
450 | * @return the endpointUri url to reply to or null if one has not been set | |
451 | */ | |
452 | Object getReplyTo(); | |
453 | ||
454 | /** | |
455 | * If an error occurred during the processing of this message this will return a | |
456 | * ErrorPayload that contains the root exception and Mule error code, plus any | |
457 | * other releated info | |
458 | * | |
459 | * @return The exception payload (if any) attached to this message | |
460 | */ | |
461 | ExceptionPayload getExceptionPayload(); | |
462 | ||
463 | /** | |
464 | * If an error occurs while processing this message, a ErrorPayload is attached | |
465 | * which contains the root exception and Mule error code, plus any other releated | |
466 | * info. | |
467 | * | |
468 | * @param payload The exception payload to attach to this message | |
469 | */ | |
470 | void setExceptionPayload(ExceptionPayload payload); | |
471 | ||
472 | /** | |
473 | * Allows for arbitrary data attachments to be associated with the Message. These | |
474 | * attachments work in the same way that email attachments work. Attachments can | |
475 | * be binary or text | |
476 | * | |
477 | * @param name the name to associate with the attachment | |
478 | * @param dataHandler The attachment datahandler to use. This will be used to | |
479 | * interact with the attachment data. | |
480 | * @throws Exception if the attachment cannot be added for any reason | |
481 | * @see javax.activation.DataHandler | |
482 | * @deprecated use | |
483 | * {@link #addOutboundAttachment(java.lang.String, javax.activation.DataHandler)} | |
484 | * instead | |
485 | */ | |
486 | @Deprecated | |
487 | void addAttachment(String name, DataHandler dataHandler) throws Exception; | |
488 | ||
489 | /** | |
490 | * Allows for arbitrary data attachments to be associated with the Message. These attachments work in the | |
491 | * same way that email attachments work. Attachments can be binary or text | |
492 | * @param name the name to associate with the attachment | |
493 | * @param dataHandler The attachment {@link javax.activation.DataHandler} to use. This will be used to interact with the attachment data | |
494 | * @throws Exception if the attachment cannot be added for any reason | |
495 | * @see javax.activation.DataHandler | |
496 | * @since 3.0 | |
497 | */ | |
498 | void addOutboundAttachment(String name, DataHandler dataHandler) throws Exception; | |
499 | ||
500 | /** | |
501 | * Adds an outgoing attachment to the message | |
502 | * @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 | |
503 | * 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 | |
504 | * @param contentType the content type of the attachment. Note that the charset attribute can be specifed too i.e. text/plain;charset=UTF-8 | |
505 | * @param name the name to associate with the attachments | |
506 | * @throws Exception if the attachment cannot be read or created | |
507 | * @since 3.0 | |
508 | */ | |
509 | void addOutboundAttachment(String name, Object object, String contentType) throws Exception; | |
510 | ||
511 | /** | |
512 | * Remove an attachment form this message with the specified name | |
513 | * @param name the name of the attachment to remove. If the attachment does not exist, the request may be ignored | |
514 | * @throws Exception different messaging systems handle attachments differently, as such some will throw an exception | |
515 | * if an attachment does dot exist. | |
516 | * @deprecated use {@link #removeOutboundAttachment(java.lang.String)} instead | |
517 | */ | |
518 | @Deprecated | |
519 | void removeAttachment(String name) throws Exception; | |
520 | ||
521 | /** | |
522 | * Remove an attachment form this message with the specified name | |
523 | * @param name the name of the attachment to remove. If the attachment does not exist, the request may be ignored | |
524 | * @throws Exception different messaging systems handle attachments differently, as such some will throw an exception | |
525 | * if an attachment does dot exist. | |
526 | * @since 3.0 | |
527 | */ | |
528 | void removeOutboundAttachment(String name) throws Exception; | |
529 | ||
530 | /** | |
531 | * Retrieve an attachment with the given name. If the attachment does not exist, null will be returned | |
532 | * @param name the name of the attachment to retrieve | |
533 | * @return the attachment with the given name or null if the attachment does not exist | |
534 | * @see javax.activation.DataHandler | |
535 | * @deprecated use {@link #getInboundAttachment(String)} instead | |
536 | */ | |
537 | @Deprecated | |
538 | DataHandler getAttachment(String name); | |
539 | ||
540 | /** | |
541 | * Retrieve an attachment with the given name. If the attachment does not exist, null will be returned | |
542 | * @param name the name of the attachment to retrieve | |
543 | * @return the attachment with the given name or null if the attachment does not exist | |
544 | * @see javax.activation.DataHandler | |
545 | * @since 3.0 | |
546 | */ | |
547 | DataHandler getInboundAttachment(String name); | |
548 | ||
549 | /** | |
550 | * Retrieve an attachment with the given name. If the attachment does not exist, null will be returned | |
551 | * @param name the name of the attachment to retrieve | |
552 | * @return the attachment with the given name or null if the attachment does not exist | |
553 | * @see javax.activation.DataHandler | |
554 | * @since 3.0 | |
555 | */ | |
556 | DataHandler getOutboundAttachment(String name); | |
557 | ||
558 | /** | |
559 | * @return a set of the names of the attachments on this message. If there are no attachments an empty set will be | |
560 | * returned. | |
561 | * @deprecated use {@link #getInboundAttachmentNames()} | |
562 | */ | |
563 | @Deprecated | |
564 | Set<String> getAttachmentNames(); | |
565 | ||
566 | /** | |
567 | * @return a set of the names of the attachments on this message. If there are no attachments an empty set will be | |
568 | * returned. | |
569 | * @since 3.0 | |
570 | */ | |
571 | Set<String> getInboundAttachmentNames(); | |
572 | ||
573 | /** | |
574 | * @return a set of the names of the attachments on this message. If there are no attachments an empty set will be | |
575 | * returned. | |
576 | * @since 3.0 | |
577 | */ | |
578 | Set<String> getOutboundAttachmentNames(); | |
579 | ||
580 | /** | |
581 | * Gets the encoding for the current message. For potocols that send encoding | |
582 | * information with the message, this method should be overriden to expose the | |
583 | * transport encoding, otherwise the default encoding in the Mule configuration | |
584 | * will be used. | |
585 | * | |
586 | * @return the encoding for this message. This method must never return null | |
587 | */ | |
588 | String getEncoding(); | |
589 | ||
590 | /** | |
591 | * Sets the encoding for this message | |
592 | * | |
593 | * @param encoding the encoding to use | |
594 | */ | |
595 | void setEncoding(String encoding); | |
596 | ||
597 | /** | |
598 | * Perform any clean up operations on the message resource. | |
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 | } |