Package org.apache.camel

Interface Message

public interface Message
Implements the Message pattern and represents an inbound or outbound message as part of an Exchange.

Headers are represented in Camel using a CaseInsensitiveMap. The implementation of the map can be configured by the HeadersMapFactory which can be set on the CamelContext. The default implementation uses the CaseInsensitiveMap.

  • Method Details

    • newInstance

      Message newInstance()
      Returns a new instance of this type.

    • reset

      void reset()
      Clears the message from user data, so the message can be reused.

      Important: This API is NOT intended for Camel end users, but used internally by Camel itself.

    • getMessageId

      String getMessageId()
      Returns the id of the message.

      By default, the message uses the same id as Exchange.getExchangeId() as messages are associated with the exchange and using different IDs does not offer much value. Another reason is to optimize for performance to avoid generating new IDs.

      A few Camel components do provide their own message IDs such as the JMS components.

      Returns:
      the message id

    • getMessageTimestamp

      long getMessageTimestamp()
      Returns the timestamp that this messages originates from.

      Some systems like JMS, Kafka, AWS have a timestamp on the event/message, that Camel received. This method returns the timestamp, if a timestamp exists.

      The message timestamp and exchange created are not the same. An exchange always have a created timestamp which is the local timestamp when Camel created the exchange. The message timestamp is only available in some Camel components when the consumer is able to extract the timestamp from the source event.

      Returns:
      the timestamp, or 0 if the message has no source timestamp.
      See Also:

    • setMessageId

      void setMessageId(String messageId)
      Sets the id of the message
      Parameters:
      messageId - id of the message

    • hasMessageId

      boolean hasMessageId()
      Whether the message has any message ID assigned.

    • getExchange

      Exchange getExchange()
      Returns the exchange this message is related to
      Returns:
      the exchange

    • getHeader

      Object getHeader(String name)
      Accesses a specific header
      Parameters:
      name - name of header
      Returns:
      the value of the given header or null if there is no header for the given name

    • getHeader

      Object getHeader(String name, Object defaultValue)
      Accesses a specific header
      Parameters:
      name - name of header
      defaultValue - the default value to return if header was absent
      Returns:
      the value of the given header or defaultValue if there is no header for the given name

    • getHeader

      Object getHeader(String name, Supplier<Object> defaultValueSupplier)
      Accesses a specific header
      Parameters:
      name - name of header
      defaultValueSupplier - the default value supplier used to generate the value to return if header was absent
      Returns:
      the value of the given header or the value generated by the defaultValueSupplier if there is no header for the given name

    • getHeader

      <T> T getHeader(String name, Class<T> type)
      Returns a header associated with this message by name and specifying the type required
      Parameters:
      name - the name of the header
      type - the type of the header
      Returns:
      the value of the given header or null if there is no header for the given name
      Throws:
      TypeConversionException - is thrown if error during type conversion

    • getHeader

      <T> T getHeader(String name, Object defaultValue, Class<T> type)
      Returns a header associated with this message by name and specifying the type required
      Parameters:
      name - the name of the header
      defaultValue - the default value to return if header was absent
      type - the type of the header
      Returns:
      the value of the given header or defaultValue if there is no header for the given name or null if it cannot be converted to the given type

    • getHeader

      <T> T getHeader(String name, Supplier<Object> defaultValueSupplier, Class<T> type)
      Returns a header associated with this message by name and specifying the type required
      Parameters:
      name - the name of the header
      defaultValueSupplier - the default value supplier used to generate the value to return if header was absent
      type - the type of the header
      Returns:
      the value of the given header or the value generated by the defaultValueSupplier if there is no header for the given name or null if it cannot be converted to the given type

    • setHeader

      void setHeader(String name, Object value)
      Sets a header on the message
      Parameters:
      name - of the header
      value - to associate with the name

    • removeHeader

      Object removeHeader(String name)
      Removes the named header from this message
      Parameters:
      name - name of the header
      Returns:
      the old value of the header

    • removeHeaders

      boolean removeHeaders(String pattern)
      Removes the headers from this message
      Parameters:
      pattern - pattern of names
      Returns:
      boolean whether any headers matched

    • removeHeaders

      boolean removeHeaders(String pattern, String... excludePatterns)
      Removes the headers from this message that match the given pattern, except for the ones matching one or more excludePatterns
      Parameters:
      pattern - pattern of names that should be removed
      excludePatterns - one or more pattern of header names that should be excluded (= preserved)
      Returns:
      boolean whether any headers matched

    • getHeaders

      Map<String,Object> getHeaders()
      Returns all the headers associated with the message.

      Headers are represented in Camel using a CaseInsensitiveMap. The implementation of the map can be configured by the HeadersMapFactory which can be set on the CamelContext. The default implementation uses the CaseInsensitiveMap.

      Important: If you want to walk the returned Map and fetch all the keys and values, you should use the Map.entrySet() method, which ensure you get the keys in the original case.

      Returns:
      all the headers in a Map

    • setHeaders

      void setHeaders(Map<String,Object> headers)
      Set all the headers associated with this message

      Important: If you want to copy headers from another Message to this Message, then use getHeaders().putAll(other) to copy the headers, where other is the other headers.

      Parameters:
      headers - headers to set

    • hasHeaders

      boolean hasHeaders()
      Returns whether any headers have been set.
      Returns:
      true if any headers has been set

    • getBody

      Object getBody()
      Returns the body of the message as a POJO

      The body can be null if body has not been set.

      Notice if the message body is stream based then calling this method multiple times may lead to the stream not being able to be re-read again. You can enable stream caching and call the StreamCache.reset() method to reset the stream to be able to re-read again (if possible). See more details about stream caching.

      Returns:
      the body, can be null

    • getMandatoryBody

      Object getMandatoryBody() throws InvalidPayloadException
      Returns the body of the message as a POJO

      Notice if the message body is stream based then calling this method multiple times may lead to the stream not being able to be re-read again. See more details about stream caching.

      Returns:
      the body, is never null
      Throws:
      InvalidPayloadException - Is thrown if the body being null or wrong class type

    • getBody

      <T> T getBody(Class<T> type)
      Returns the body as the specified type

      Notice if the message body is stream based then calling this method multiple times may lead to the stream not being able to be re-read again. You can enable stream caching and call the StreamCache.reset() method to reset the stream to be able to re-read again (if possible). See more details about stream caching.

      The helper method

      invalid reference 
      org.apache.camel.support.ExchangeHelper#getBodyAndResetStreamCache(Exchange, Class)
      can be used instead that gets the body, convert to the given type, and ensures to reset the body if its stream based.
      Parameters:
      type - the type that the body
      Returns:
      the body of the message as the specified type, or null if body does not exist
      Throws:
      TypeConversionException - is thrown if error during type conversion
      See Also:
      • invalid reference 
        org.apache.camel.support.ExchangeHelper#getBodyAndResetStreamCache(Exchange, Class)

    • getMandatoryBody

      <T> T getMandatoryBody(Class<T> type) throws InvalidPayloadException
      Returns the mandatory body as the specified type

      Notice if the message body is stream based then calling this method multiple times may lead to the stream not being able to be re-read again. You can enable stream caching and call the StreamCache.reset() method to reset the stream to be able to re-read again (if possible). See more details about stream caching.

      The helper method

      invalid reference 
      org.apache.camel.support.ExchangeHelper#getBodyAndResetStreamCache(Exchange, Class)
      can be used instead that gets the body, convert to the given type, and ensures to reset the body if its stream based.
      Parameters:
      type - the type that the body
      Returns:
      the body of the message as the specified type, is never null.
      Throws:
      InvalidPayloadException - Is thrown if the body being null or wrong class type
      See Also:
      • invalid reference 
        org.apache.camel.support.ExchangeHelper#getBodyAndResetStreamCache(Exchange, Class)

    • setBody

      void setBody(Object body)
      Sets the body of the message
      Parameters:
      body - the body

    • setBody

      <T> void setBody(Object body, Class<T> type)
      Sets the body of the message as a specific type
      Parameters:
      body - the body
      type - the type of the body

    • copy

      Message copy()
      Creates a copy of this message so that it can be used and possibly modified further in another exchange.

      The returned Message copy will have its Exchange set to the same Exchange instance as from the source.

      Returns:
      a new message instance copied from this message

    • copyFrom

      void copyFrom(Message message)
      Copies the contents of the other message into this message

      If you need to do a copy and then set a new body, then use copyFromWithNewBody(Message, Object) method instead.

      The returned Message copy will have its Exchange set to the same Exchange instance as from the source.

      Parameters:
      message - the other message
      See Also:

    • copyFromWithNewBody

      void copyFromWithNewBody(Message message, Object newBody)
      Copies the contents (except the body) of the other message into this message and uses the provided new body instead

      The returned Message copy will have its Exchange set to the same Exchange instance as from the source.

      Parameters:
      message - the other message
      newBody - the new body to use

    • hasTrait

      boolean hasTrait(MessageTrait trait)
      Checks whether the message has a given MessageTrait
      Parameters:
      trait - the MessageTrait to check
      Returns:
      true if the message instance has the trait or false otherwise

    • getPayloadForTrait

      Object getPayloadForTrait(MessageTrait trait)
      Gets the payload for the MessageTrait
      Parameters:
      trait - the MessageTrait to obtain the payload
      Returns:
      The trait payload or null if not available

    • setPayloadForTrait

      void setPayloadForTrait(MessageTrait trait, Object object)
      Sets the payload for the MessageTrait
      Parameters:
      trait - the MessageTrait to set the payload
      object - the payload

    • removeTrait

      void removeTrait(MessageTrait trait)
      Removes the trait