Chapter 40. Understanding Message Formats
Abstract
Before you can begin programming with Apache Camel, you should have a clear understanding of how messages and message exchanges are modelled. Because Apache Camel can process many message formats, the basic message type is designed to have an abstract format. Apache Camel provides the APIs needed to access and transform the data formats that underly message bodies and message headers.
40.1. Exchanges
Overview
An exchange object is a wrapper that encapsulates a received message and stores its associated metadata (including the exchange properties). In addition, if the current message is dispatched to a producer endpoint, the exchange provides a temporary slot to hold the reply (the Out message).
An important feature of exchanges in Apache Camel is that they support lazy creation of messages. This can provide a significant optimization in the case of routes that do not require explicit access to messages.
Figure 40.1. Exchange Object Passing through a Route
Figure 40.1, “Exchange Object Passing through a Route” shows an exchange object passing through a route. In the context of a route, an exchange object gets passed as the argument of the
Processor.process() method. This means that the exchange object is directly accessible to the source endpoint, the target endpoint, and all of the processors in between.
The Exchange interface
The
org.apache.camel.Exchange interface defines methods to access In and Out messages, as shown in Example 40.1, “Exchange Methods”.
Example 40.1. Exchange Methods
// Access the In message Message getIn(); void setIn(Message in); // Access the Out message (if any) Message getOut(); void setOut(Message out); boolean hasOut(); // Access the exchange ID String getExchangeId(); void setExchangeId(String id);
For a complete description of the methods in the
Exchange interface, see Section 49.1, “The Exchange Interface”.
Lazy creation of messages
Apache Camel supports lazy creation of In, Out, and Fault messages. This means that message instances are not created until you try to access them (for example, by calling
getIn() or getOut()). The lazy message creation semantics are implemented by the org.apache.camel.impl.DefaultExchange class.
If you call one of the no-argument accessors (
getIn() or getOut()), or if you call an accessor with the boolean argument equal to true (that is, getIn(true) or getOut(true)), the default method implementation creates a new message instance, if one does not already exist.
If you call an accessor with the boolean argument equal to
false (that is, getIn(false) or getOut(false)), the default method implementation returns the current message value.[2]
Lazy creation of exchange IDs
Apache Camel supports lazy creation of exchange IDs. You can call
getExchangeId() on any exchange to obtain a unique ID for that exchange instance, but the ID is generated only when you actually call the method. The DefaultExchange.getExchangeId() implementation of this method delegates ID generation to the UUID generator that is registered with the CamelContext.
For details of how to register UUID generators with the
CamelContext, see Section 40.4, “Built-In UUID Generators”.
