001: /*
002: * $Id: MuleMessage.java 10489 2008-01-23 17:53:38Z dfeist $
003: * --------------------------------------------------------------------------------------
004: * Copyright (c) MuleSource, Inc. All rights reserved. http://www.mulesource.com
005: *
006: * The software in this package is published under the terms of the CPAL v1.0
007: * license, a copy of which has been included with this distribution in the
008: * LICENSE.txt file.
009: */
010:
011: package org.mule.api;
012:
013: import org.mule.api.transformer.TransformerException;
014: import org.mule.api.transport.MessageAdapter;
015:
016: import java.util.List;
017:
018: /**
019: * <code>MuleMessage</code> represents a message payload. The Message comprises of
020: * the payload itself and properties associated with the payload.
021: */
022:
023: public interface MuleMessage extends MessageAdapter {
024:
025: /**
026: * Returns the currently edited Message adapter for this message. If no edits have been made
027: * this methd will return the same as {@link #getOriginalAdapter()}
028: * @return
029: */
030: MessageAdapter getAdapter();
031:
032: /**
033: * Returns the original payload used to create this message. The payload of the message can change if {@link #applyTransformers(java.util.List)} or
034: * {@link #applyTransformers(java.util.List, Class)} is called.
035: * @return the original payload used to create this message
036: */
037: MessageAdapter getOriginalAdapter();
038:
039: /**
040: * Will apply a list of transformers to the payload of the message. This *Will* change the payload of the
041: * message. This method provides the only way to alter the paylaod of this message without recreating a
042: * copy of the message
043: * @param transformers the transformers to apply to the message payload
044: * @throws TransformerException if a transformation error occurs or one or more of the transformers passed in a
045: * are incompatible with the message payload
046: */
047: public void applyTransformers(List transformers)
048: throws TransformerException;
049:
050: /**
051: * Will apply a list of transformers to the payload of the message. This *Will* change the payload of the
052: * message. This method provides the only way to alter the paylaod of this message without recreating a
053: * copy of the message
054: * @param transformers the transformers to apply to the message payload
055: * @param outputType the required output type for this transformation. by adding this parameter some additional
056: * transformations will occur on the message payload to ensure that the final payload is of the specified type.
057: * If no transformers can be found in the registry that can transform from the return type of the transformation
058: * list to the outputType and exception will be thrown
059: * @throws TransformerException if a transformation error occurs or one or more of the transformers passed in a
060: * are incompatible with the message payload
061: */
062: public void applyTransformers(List transformers, Class outputType)
063: throws TransformerException;
064:
065: /**
066: * Update the message payload. This is typically only called if the
067: * payload was originally an InputStream. In which case, if the InputStream
068: * is consumed, it needs to be replaced for future access.
069: *
070: * @param payload the object to assign as the message payload
071: */
072: void setPayload(Object payload);
073:
074: /**
075: * Will attempt to obtain the payload of this message with the desired Class type. This will
076: * try and resolve a trnsformr that can do this transformation. If a transformer cannot be found
077: * an exception is thrown. Any transfromers added to the reqgistry will be checked for compatability
078: * @param outputType the desired return type
079: * @return The converted payload of this message. Note that this method will not alter the payload of this
080: * message *unless* the payload is an inputstream in which case the stream will be read and the payload will become
081: * the fully read stream.
082: * @throws TransformerException if a transformer cannot be found or there is an error during transformation of the
083: * payload
084: */
085: Object getPayload(Class outputType) throws TransformerException;
086:
087: /**
088: * Converts the message implementation into a String representation
089: *
090: * @param encoding The encoding to use when transforming the message (if
091: * necessary). The parameter is used when converting from a byte array
092: * @return String representation of the message payload
093: * @throws Exception Implementation may throw an endpoint specific exception
094: */
095: String getPayloadAsString(String encoding) throws Exception;
096:
097: /**
098: * Converts the message implementation into a String representation. If encoding
099: * is required it will use the encoding set on the message
100: *
101: * @return String representation of the message payload
102: * @throws Exception Implementation may throw an endpoint specific exception
103: */
104: String getPayloadAsString() throws Exception;
105:
106: /**
107: * Converts the message implementation into a byte array representation
108: *
109: * @return byte array of the message
110: * @throws Exception Implemetation may throw an endpoint specific exception
111: */
112: byte[] getPayloadAsBytes() throws Exception;
113:
114: /**
115: * Returns the original payload used to create this message. The payload of the message can change if {@link #applyTransformers(java.util.List)} or
116: * {@link #applyTransformers(java.util.List, Class)} is called.
117: * @return the original payload used to create this message
118: */
119: Object getOrginalPayload();
120:
121: }
|