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 }