Chapter 49. Exchange Interface
Abstract
This chapter describes the
Exchange
interface. Since the refactoring of the camel-core module performed in Apache Camel 2.0, there is no longer any necessity to define custom exchange types. The DefaultExchange
implementation can now be used in all cases.
49.1. The Exchange Interface
Overview
An instance of
org.apache.camel.Exchange
type encapsulates the current message passing through a route, with additional metadata encoded as exchange properties.
Figure 49.1, “Exchange Inheritance Hierarchy” shows the inheritance hierarchy for the exchange type. The default implementation,
DefaultExchange
, is always used.
Figure 49.1. Exchange Inheritance Hierarchy
![Exchange inheritance hierarchy](https://access.redhat.com/webassets/avalon/d/Red_Hat_JBoss_Fuse-6.1-Apache_Camel_Development_Guide-en-US/images/6e935d1034f17a49d0957e13a1698a01/exchange_intf_01.gif)
The Exchange interface
Example 49.1, “Exchange Interface” shows the definition of the
org.apache.camel.Exchange
interface.
Example 49.1. Exchange Interface
package org.apache.camel; import java.util.Map; import org.apache.camel.spi.Synchronization; import org.apache.camel.spi.UnitOfWork; public interface Exchange { // Exchange property names (string constants) // (Not shown here) ... ExchangePattern getPattern(); void setPattern(ExchangePattern pattern); Object getProperty(String name); Object getProperty(String name, Object defaultValue); <T> T getProperty(String name, Class<T> type); <T> T getProperty(String name, Object defaultValue, Class<T> type); void setProperty(String name, Object value); Object removeProperty(String name); Map<String, Object> getProperties(); boolean hasProperties(); Message getIn(); <T> T getIn(Class<T> type); void setIn(Message in); Message getOut(); <T> T getOut(Class<T> type); void setOut(Message out); boolean hasOut(); Throwable getException(); <T> T getException(Class<T> type); void setException(Throwable e); boolean isFailed(); boolean isTransacted(); boolean isRollbackOnly(); CamelContext getContext(); Exchange copy(); Endpoint getFromEndpoint(); void setFromEndpoint(Endpoint fromEndpoint); String getFromRouteId(); void setFromRouteId(String fromRouteId); UnitOfWork getUnitOfWork(); void setUnitOfWork(UnitOfWork unitOfWork); String getExchangeId(); void setExchangeId(String id); void addOnCompletion(Synchronization onCompletion); void handoverCompletions(Exchange target); }
Exchange methods
The
Exchange
interface defines the following methods:
getPattern()
,setPattern()
—The exchange pattern can be one of the values enumerated inorg.apache.camel.ExchangePattern
. The following exchange pattern values are supported:InOnly
RobustInOnly
InOut
InOptionalOut
OutOnly
RobustOutOnly
OutIn
OutOptionalIn
setProperty()
,getProperty()
,getProperties()
,removeProperty()
,hasProperties()
—Use the property setter and getter methods to associate named properties with the exchange instance. The properties consist of miscellaneous metadata that you might need for your component implementation.setIn()
,getIn()
—Setter and getter methods for the In message.ThegetIn()
implementation provided by theDefaultExchange
class implements lazy creation semantics: if the In message is null whengetIn()
is called, theDefaultExchange
class creates a default In message.setOut()
,getOut()
,hasOut()
—Setter and getter methods for the Out message.ThegetOut()
method implicitly supports lazy creation of an Out message. That is, if the current Out message isnull
, a new message instance is automatically created.setException()
,getException()
—Getter and setter methods for an exception object (ofThrowable
type).isFailed()
—Returnstrue
, if the exchange failed either due to an exception or due to a fault.isTransacted()
—Returnstrue
, if the exchange is transacted.isRollback()
—Returnstrue
, if the exchange is marked for rollback.getContext()
—Returns a reference to the associatedCamelContext
instance.copy()
—Creates a new, identical (apart from the exchange ID) copy of the current custom exchange object. The body and headers of the In message, the Out message (if any), and the Fault message (if any) are also copied by this operation.setFromEndpoint()
,getFromEndpoint()
—Getter and setter methods for the consumer endpoint that orginated this message (which is typically the endpoint appearing in thefrom()
DSL command at the start of a route).setFromRouteId()
,getFromRouteId()
—Getters and setters for the route ID that originated this exchange. ThegetFromRouteId()
method should only be called internally.setUnitOfWork()
,getUnitOfWork()
—Getter and setter methods for theorg.apache.camel.spi.UnitOfWork
bean property. This property is only required for exchanges that can participate in a transaction.setExchangeId()
,getExchangeId()
—Getter and setter methods for the exchange ID. Whether or not a custom component uses and exchange ID is an implementation detail.addOnCompletion()
—Adds anorg.apache.camel.spi.Synchronization
callback object, which gets called when processing of the exchange has completed.handoverCompletions()
—Hands over all of the OnCompletion callback objects to the specified exchange object.