Package org.apache.camel

Interface Exchange

All Superinterfaces:
VariableAware
All Known Subinterfaces:
PooledExchange
@ConstantProvider("org.apache.camel.ExchangeConstantProvider") public interface Exchange extends VariableAware
An Exchange is the message container holding the information during the entire routing of a Message received by a Consumer.

During processing down the Processor chain, the Exchange provides access to the current (not the original) request and response Message messages. The Exchange also holds meta-data during its entire lifetime stored as properties accessible using the various getProperty(String) methods. The setProperty(String, Object) is used to store a property. For example, you can use this to store security, SLA related data or any other information deemed useful throughout processing. If an Exchange failed during routing the Exception that caused the failure is stored and accessible via the getException() method.

An Exchange is created when a Consumer receives a request. A new Message is created, the request is set as the body of the Message and depending on the Consumer other Endpoint and protocol related information is added as headers on the Message. Then an Exchange is created and the newly created Message is set as the in on the Exchange. Therefore, an Exchange starts its life in a Consumer. The Exchange is then sent down the Route for processing along a Processor chain. The Processor as the name suggests is what processes the Message in the Exchange and Camel, in addition to providing out-of-the-box a large number of useful processors, it also allows you to create your own. The rule Camel uses is to take the out Message produced by the previous Processor and set it as the in for the next Processor. If the previous Processor did not produce an out, then the in of the previous Processor is sent as the next in. At the end of the processing chain, depending on the Message Exchange Pattern (or MEP) the last out (or in of no out available) is sent by the Consumer back to the original caller.

Camel, in addition to providing out-of-the-box a large number of useful processors, it also allows you to implement and use your own. When the Exchange is passed to a Processor, it always contains an in Message and no out Message. The Processor may produce an out, depending on the nature of the Processor. The in Message can be accessed using the getIn() method. Since the out message is null when entering the Processor, the getOut() method is actually a convenient factory method that will lazily instantiate a

invalid reference 
org.apache.camel.support.DefaultMessage
which you could populate. As an alternative you could also instantiate your specialized Message and set it on the exchange using the setOut(org.apache.camel.Message) method. Please note that a Message contains not only the body but also headers and attachments. If you are creating a new Message the headers and attachments of the in Message are not automatically copied to the out by Camel, and you'll have to set the headers and attachments you need yourself. If your Processor is not producing a different Message but only needs to slightly modify the in, you can simply update the in Message returned by getIn().

See this FAQ entry for more details.

  • Field Details

  • Method Details

    • getPattern

      ExchangePattern getPattern()
      Returns the ExchangePattern (MEP) of this exchange.
      Returns:
      the message exchange pattern of this exchange

    • setPattern

      void setPattern(ExchangePattern pattern)
      Allows the ExchangePattern (MEP) of this exchange to be customized. This typically won't be required as an exchange can be created with a specific MEP by calling Endpoint.createExchange(ExchangePattern) but it is here just in case it is needed.
      Parameters:
      pattern - the pattern

    • getProperty

      Object getProperty(ExchangePropertyKey key)
      Returns a property associated with this exchange by the key
      Parameters:
      key - the exchange key
      Returns:
      the value of the given property or null if there is no property for the given key

    • getProperty

      <T> T getProperty(ExchangePropertyKey key, Class<T> type)
      Returns a property associated with this exchange by the key and specifying the type required
      Parameters:
      key - the exchange key
      type - the type of the property
      Returns:
      the value of the given property or null if there is no property for the given name or null if it cannot be converted to the given type

    • getProperty

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

    • setProperty

      void setProperty(ExchangePropertyKey key, Object value)
      Sets a property on the exchange
      Parameters:
      key - the exchange key
      value - to associate with the name

    • removeProperty

      Object removeProperty(ExchangePropertyKey key)
      Removes the given property on the exchange
      Parameters:
      key - the exchange key
      Returns:
      the old value of the property

    • getProperty

      Object getProperty(String name)
      Returns a property associated with this exchange by name
      Parameters:
      name - the name of the property
      Returns:
      the value of the given property or null if there is no property for the given name

    • getProperty

      <T> T getProperty(String name, Class<T> type)
      Returns a property associated with this exchange by name and specifying the type required
      Parameters:
      name - the name of the property
      type - the type of the property
      Returns:
      the value of the given property or null if there is no property for the given name or null if it cannot be converted to the given type

    • getProperty

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

    • setProperty

      void setProperty(String name, Object value)
      Sets a property on the exchange
      Parameters:
      name - of the property
      value - to associate with the name

    • removeProperty

      Object removeProperty(String name)
      Removes the given property on the exchange
      Parameters:
      name - of the property
      Returns:
      the old value of the property

    • removeProperties

      boolean removeProperties(String pattern)
      Remove all the properties associated with the exchange matching a specific pattern
      Parameters:
      pattern - pattern of names
      Returns:
      boolean whether any properties matched

    • removeProperties

      boolean removeProperties(String pattern, String... excludePatterns)
      Removes the properties from this exchange 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 properties names that should be excluded (= preserved)
      Returns:
      boolean whether any properties matched

    • getProperties

      Map<String,Object> getProperties()
      Returns the properties associated with the exchange
      Returns:
      the properties in a Map
      See Also:

    • getAllProperties

      Map<String,Object> getAllProperties()
      Returns all (both internal and custom) properties associated with the exchange
      Returns:
      all (both internal and custom) properties in a Map
      See Also:

    • hasProperties

      boolean hasProperties()
      Returns whether any properties have been set
      Returns:
      true if any property has been set

    • getVariable

      Object getVariable(String name)
      Returns a variable by name
      Specified by:
      getVariable in interface VariableAware
      Parameters:
      name - the variable name. Can be prefixed with repo-id:name to lookup the variable from a specific repository. If no repo-id is provided, then variables will be from the current exchange.
      Returns:
      the value of the given variable or null if there is no variable for the given name

    • getVariable

      <T> T getVariable(String name, Class<T> type)
      Returns a variable by name and specifying the type required
      Parameters:
      name - the variable name. Can be prefixed with repo-id:name to lookup the variable from a specific repository. If no repo-id is provided, then variables will be from the current exchange.
      type - the type of the variable
      Returns:
      the value of the given variable or null if there is no variable for the given name or null if it cannot be converted to the given type

    • getVariable

      <T> T getVariable(String name, Object defaultValue, Class<T> type)
      Returns a variable by name and specifying the type required
      Parameters:
      name - the variable name. Can be prefixed with repo-id:name to look up the variable from a specific repository. If no repo-id is provided, then variables will be from the current exchange.
      defaultValue - the default value to return if variable was absent
      type - the type of the variable
      Returns:
      the value of the given variable or defaultValue if there is no variable for the given name or null if it cannot be converted to the given type

    • setVariable

      void setVariable(String name, Object value)
      Sets a variable on the exchange
      Specified by:
      setVariable in interface VariableAware
      Parameters:
      name - the variable name. Can be prefixed with repo-id:name to store the variable in a specific repository. If no repo-id is provided, then variables will be stored in the current exchange.
      value - the value of the variable

    • removeVariable

      Object removeVariable(String name)
      Removes the given variable If the name is * then all variables from the current exchange is removed, and null is returned.
      Parameters:
      name - the variable name. Can be prefixed with repo-id:name to remove the variable in a specific repository. If no repo-id is provided, then the variable from the current exchange will be removed
      Returns:
      the old value of the variable, or null if there was no variable for the given name

    • getVariables

      Map<String,Object> getVariables()
      Returns the variables from the current exchange
      Returns:
      the variables from the current exchange in a Map.

    • hasVariables

      boolean hasVariables()
      Returns whether any variables have been set on the current exchange
      Returns:
      true if any variables has been set on the current exchange

    • getIn

      Message getIn()
      Returns the inbound request message
      Returns:
      the message

    • getMessage

      Message getMessage()
      Returns the current message
      Returns:
      the current message

    • getMessage

      <T> T getMessage(Class<T> type)
      Returns the current message as the given type
      Parameters:
      type - the given type
      Returns:
      the message as the given type or null if not possible to covert to given type

    • setMessage

      void setMessage(Message message)
      Replace the current message instance.
      Parameters:
      message - the new message

    • getIn

      <T> T getIn(Class<T> type)
      Returns the inbound request message as the given type
      Parameters:
      type - the given type
      Returns:
      the message as the given type or null if not possible to covert to given type

    • setIn

      void setIn(Message in)
      Sets the inbound message instance
      Parameters:
      in - the inbound message

    • getOut

      @Deprecated(since="3.0.0") Message getOut()
      Deprecated.
      use getMessage()
      Returns the outbound message, lazily creating one if one has not already been associated with this exchange.


      Important: If you want to change the current message, then use getIn() instead as it will ensure headers etc. is kept and propagated when routing continues. Bottom line end users should rarely use this method.


      If you want to test whether an OUT message has been set or not, use the hasOut() method.

      See also the class Javadoc for this Exchange for more details and this FAQ entry.

      Returns:
      the response
      See Also:

    • getOut

      @Deprecated(since="3.0.0") <T> T getOut(Class<T> type)
      Deprecated.
      use getMessage(Class)
      Returns the outbound request message as the given type


      Important: If you want to change the current message, then use getIn() instead as it will ensure headers etc. is kept and propagated when routing continues. Bottom line end users should rarely use this method.


      If you want to test whether an OUT message has been set or not, use the hasOut() method.

      See also the class Javadoc for this Exchange for more details and this FAQ entry.

      Parameters:
      type - the given type
      Returns:
      the message as the given type or null if not possible to covert to given type
      See Also:

    • hasOut

      @Deprecated(since="3.0.0") boolean hasOut()
      Deprecated.
      use getMessage()
      Returns whether an OUT message has been set or not.
      Returns:
      true if an OUT message exists, false otherwise.

    • setOut

      @Deprecated(since="3.0.0") void setOut(Message out)
      Deprecated.
      use setMessage(Message)
      Sets the outbound message
      Parameters:
      out - the outbound message

    • getException

      Exception getException()
      Returns the exception associated with this exchange
      Returns:
      the exception (or null if no faults)

    • getException

      <T> T getException(Class<T> type)
      Returns the exception associated with this exchange.

      Is used to get the caused exception that typically have been wrapped in some sort of Camel wrapper exception

      The strategy is to look in the exception hierarchy to find the first given cause that matches the type. Will start from the bottom (the real cause) and walk upwards.

      Parameters:
      type - the exception type
      Returns:
      the exception (or null if no caused exception matched)

    • setException

      void setException(Throwable t)
      Sets the exception associated with this exchange

      Camel will wrap Throwable into Exception type to accommodate for the getException() method returning a plain Exception type.

      Parameters:
      t - the caused exception

    • isFailed

      boolean isFailed()
      Returns true if this exchange failed due to an exception
      Returns:
      true if this exchange failed due to an exception
      See Also:

    • isTransacted

      boolean isTransacted()
      Returns true if this exchange is transacted

    • isRouteStop

      boolean isRouteStop()
      Returns true if this exchange is marked to stop and not continue routing.

    • setRouteStop

      void setRouteStop(boolean routeStop)
      Sets whether this exchange is marked to stop and not continue routing.
      Parameters:
      routeStop - true to stop routing

    • isExternalRedelivered

      boolean isExternalRedelivered()
      Returns true if this exchange is an external initiated redelivered message (such as a JMS broker).

      Important: It is not always possible to determine if the message is a redelivery or not, and therefore false is returned. Such an example would be a JDBC message. However JMS brokers provides details if a message is redelivered.

      Returns:
      true if redelivered, false if not or not able to determine

    • isRollbackOnly

      boolean isRollbackOnly()
      Returns true if this exchange is marked for rollback

    • setRollbackOnly

      void setRollbackOnly(boolean rollbackOnly)
      Sets whether to mark this exchange for rollback

    • isRollbackOnlyLast

      boolean isRollbackOnlyLast()
      Returns true if this exchange is marked for rollback (only last transaction section)

    • setRollbackOnlyLast

      void setRollbackOnlyLast(boolean rollbackOnlyLast)
      Sets whether to mark this exchange for rollback (only last transaction section)

    • getContext

      CamelContext getContext()
      Returns the container so that a processor can resolve endpoints from URIs
      Returns:
      the container which owns this exchange

    • copy

      Exchange copy()
      Creates a copy of the current message exchange so that it can be forwarded to another destination

    • getFromEndpoint

      Endpoint getFromEndpoint()
      Returns the endpoint which originated this message exchange if a consumer on an endpoint created the message exchange, otherwise his property will be null. Note: In case this message exchange has been cloned through another parent message exchange (which itself has been created through the consumer of it's own endpoint), then if desired one could still retrieve the consumer endpoint of such a parent message exchange as the following: 
       getContext().getRoute(getFromRouteId()).getEndpoint()

    • getFromRouteId

      String getFromRouteId()
      Returns the route id which originated this message exchange if a route consumer on an endpoint created the message exchange, otherwise his property will be null. Note: In case this message exchange has been cloned through another parent message exchange then this method would return the fromRouteId property of that exchange.

    • getUnitOfWork

      UnitOfWork getUnitOfWork()
      Returns the unit of work that this exchange belongs to; which may map to zero, one or more physical transactions

    • getExchangeId

      String getExchangeId()
      Returns the exchange id (unique)

    • setExchangeId

      void setExchangeId(String id)
      Set the exchange id

    • getCreated

      @Deprecated(since="4.4.0") long getCreated()
      Deprecated.
      Gets the timestamp in millis when this exchange was created.
      See Also:

    • getExchangeExtension

      ExchangeExtension getExchangeExtension()
      Gets the ExchangeExtension that contains the extension points for internal exchange APIs. These APIs are intended for internal usage within Camel and end-users should avoid using them.
      Returns:
      the ExchangeExtension point for this exchange.

    • getClock

      Clock getClock()
      Gets Clock that holds time information about the exchange