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