Package org.apache.camel

Interface Exchange

All Known Subinterfaces:
ExtendedExchange, PooledExchange
@ConstantProvider("org.apache.camel.ExchangeConstantProvider") public interface Exchange
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 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.