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 Message via getMessage(). 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 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. Camel provides a large number of useful processors out-of-the-box, and it also allows you to create your own.

To access or modify the current message, use the getMessage() method. Camel uses getMessage() to obtain the current message during routing. If a Processor modifies the message, those changes are visible to subsequent processors. The ExchangePattern determines whether a reply is expected (InOut) or not (InOnly).

See Also:

  • 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

      @Nullable 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
      Since:
      3.9

    • getProperty

      <T> @Nullable 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
      Since:
      3.9

    • getProperty

      <T> @Nullable 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
      Since:
      3.9

    • setProperty

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

    • removeProperty

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

    • getProperty

      @Nullable 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> @Nullable 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> @Nullable 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, @Nullable Object value)
      Sets a property on the exchange
      Parameters:
      name - of the property
      value - to associate with the name

    • removeProperty

      @Nullable 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

      @Nullable 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
      Since:
      4.4

    • getVariable

      <T> @Nullable 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
      Since:
      4.4

    • getVariable

      <T> @Nullable 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
      Since:
      4.4

    • setVariable

      void setVariable(String name, @Nullable 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
      Since:
      4.4

    • removeVariable

      @Nullable 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
      Since:
      4.4

    • getVariables

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

    • 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
      Since:
      4.4

    • getIn

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

    • getMessage

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

    • getMessage

      <T> @Nullable 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 convert to given type
      Since:
      3.0

    • setMessage

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

    • getIn

      <T> @Nullable 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 convert 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.

      Returns:
      the response
      See Also:

    • getOut

      @Deprecated(since="3.0.0") <T> @Nullable 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.

      Parameters:
      type - the given type
      Returns:
      the message as the given type or null if not possible to convert 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

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

    • getException

      <T> @Nullable 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(@Nullable 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

      @Nullable Endpoint getFromEndpoint()
      Returns the endpoint which originated this message exchange if a consumer on an endpoint created the message exchange, otherwise this 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

      @Nullable 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.

    • getFromRouteGroup

      @Nullable String getFromRouteGroup()
      Returns the route group of the route that originated this message exchange, or null if the route has no group or if this exchange was not created by a route consumer.

    • getUnitOfWork

      @Nullable 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.
      Since:
      4.0

    • getClock

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

Apache Camel