Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
MuleMessage |
|
| 1.0;1 |
1 | /* | |
2 | * $Id: MuleMessage.java 12269 2008-07-10 04:19:03Z dfeist $ | |
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; | |
12 | ||
13 | import org.mule.api.transformer.TransformerException; | |
14 | import org.mule.api.transport.MessageAdapter; | |
15 | ||
16 | import java.util.List; | |
17 | ||
18 | /** | |
19 | * <code>MuleMessage</code> represents a message payload. The Message comprises of | |
20 | * the payload itself and properties associated with the payload. | |
21 | */ | |
22 | ||
23 | public interface MuleMessage extends MessageAdapter | |
24 | { | |
25 | ||
26 | /** | |
27 | * Returns the currently edited Message adapter for this message. If no edits have been made | |
28 | * this methd will return the same as {@link #getOriginalAdapter()} | |
29 | * @return | |
30 | */ | |
31 | MessageAdapter getAdapter(); | |
32 | ||
33 | /** | |
34 | * Returns the original payload used to create this message. The payload of the message can change if {@link #applyTransformers(java.util.List)} or | |
35 | * {@link #applyTransformers(java.util.List, Class)} is called. | |
36 | * @return the original payload used to create this message | |
37 | */ | |
38 | MessageAdapter getOriginalAdapter(); | |
39 | ||
40 | /** | |
41 | * Will apply a list of transformers to the payload of the message. This *Will* change the payload of the | |
42 | * message. This method provides the only way to alter the paylaod of this message without recreating a | |
43 | * copy of the message | |
44 | * @param transformers the transformers to apply to the message payload | |
45 | * @throws TransformerException if a transformation error occurs or one or more of the transformers passed in a | |
46 | * are incompatible with the message payload | |
47 | */ | |
48 | void applyTransformers(List transformers) throws TransformerException; | |
49 | ||
50 | /** | |
51 | * Will apply a list of transformers to the payload of the message. This *Will* change the payload of the | |
52 | * message. This method provides the only way to alter the paylaod of this message without recreating a | |
53 | * copy of the message | |
54 | * @param transformers the transformers to apply to the message payload | |
55 | * @param outputType the required output type for this transformation. by adding this parameter some additional | |
56 | * transformations will occur on the message payload to ensure that the final payload is of the specified type. | |
57 | * If no transformers can be found in the registry that can transform from the return type of the transformation | |
58 | * list to the outputType and exception will be thrown | |
59 | * @throws TransformerException if a transformation error occurs or one or more of the transformers passed in a | |
60 | * are incompatible with the message payload | |
61 | */ | |
62 | void applyTransformers(List transformers, Class outputType) throws TransformerException; | |
63 | ||
64 | /** | |
65 | * Update the message payload. This is typically only called if the | |
66 | * payload was originally an InputStream. In which case, if the InputStream | |
67 | * is consumed, it needs to be replaced for future access. | |
68 | * | |
69 | * @param payload the object to assign as the message payload | |
70 | */ | |
71 | void setPayload(Object payload); | |
72 | ||
73 | /** | |
74 | * Will attempt to obtain the payload of this message with the desired Class type. This will | |
75 | * try and resolve a trnsformr that can do this transformation. If a transformer cannot be found | |
76 | * an exception is thrown. Any transfromers added to the reqgistry will be checked for compatability | |
77 | * @param outputType the desired return type | |
78 | * @return The converted payload of this message. Note that this method will not alter the payload of this | |
79 | * message *unless* the payload is an inputstream in which case the stream will be read and the payload will become | |
80 | * the fully read stream. | |
81 | * @throws TransformerException if a transformer cannot be found or there is an error during transformation of the | |
82 | * payload | |
83 | */ | |
84 | Object getPayload(Class outputType) throws TransformerException; | |
85 | ||
86 | /** | |
87 | * Converts the message implementation into a String representation | |
88 | * | |
89 | * @param encoding The encoding to use when transforming the message (if | |
90 | * necessary). The parameter is used when converting from a byte array | |
91 | * @return String representation of the message payload | |
92 | * @throws Exception Implementation may throw an endpoint specific exception | |
93 | */ | |
94 | String getPayloadAsString(String encoding) throws Exception; | |
95 | ||
96 | /** | |
97 | * Converts the message implementation into a String representation. If encoding | |
98 | * is required it will use the encoding set on the message | |
99 | * | |
100 | * @return String representation of the message payload | |
101 | * @throws Exception Implementation may throw an endpoint specific exception | |
102 | */ | |
103 | String getPayloadAsString() throws Exception; | |
104 | ||
105 | /** | |
106 | * Converts the message implementation into a byte array representation | |
107 | * | |
108 | * @return byte array of the message | |
109 | * @throws Exception Implemetation may throw an endpoint specific exception | |
110 | */ | |
111 | byte[] getPayloadAsBytes() throws Exception; | |
112 | ||
113 | /** | |
114 | * Returns the original payload used to create this message. The payload of the message can change if {@link #applyTransformers(java.util.List)} or | |
115 | * {@link #applyTransformers(java.util.List, Class)} is called. | |
116 | * @return the original payload used to create this message | |
117 | */ | |
118 | Object getOrginalPayload(); | |
119 | ||
120 | } |