View Javadoc

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 }