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