Exchange

Camel doesn't transport a message directly. The main reason is that a message flows only in one direction. When dealing with messaging, there are many Message Exchange Patterns (MEP) that we can use.

Depending on the use cases, we can send a message without expecting any return from the destination: this pattern is named event message and uses InOnlyMEP. For instance, when you read a file from the filesystem, you just process the file content, without returning anything to the endpoint that read the file. In that case, the component responsible for reading the filesystem will define an InOnlyMEP.

On the other hand, you may want to implement a request reply pattern: a response message should be returned to the sender of the request message, and so it uses an InOutMEP. For instance, you receive a SOAP Request from a WebService component, so you should return a SOAP Response (or SOAP Fault) to the message sender.

In Camel, MEP are described in the org.apache.camel.ExchangePattern enumeration (http://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/ExchangePattern.html). We can see that Camel supports the following MEP:

• InOnly
• InOptionalOut
• InOut
• OutIn
• OutOptionalIn
• RobustInOnly
• RobustOutOnly

As a message flows in only one direction, in order to support the different MEPs, we need two messages:

• The first message is mandatory as it's the in message
• The second message is optional (depending on the MEP) as it's the out message

That's why Camel wraps the messages into an Exchange object: the actual object transported is the Exchange, acting as a messages container with all meta-data required for the routing logic.

This Exchange object is used for the complete mediation process execution.

The org.apache.camel.Exchange interface describes an exchange.

Basically, an exchange contains the following:

• Exchange ID: An exchange ID as a String. This is a unique identifier for the exchange. Camel creates it for you.
• MEP: The Message Exchange Pattern (MEP) defines the exchange pattern.
• Exception: The Exception is used by the error handler, as we will see later. It stores the current cause of an exchange failure. If an error occurs at any time during routing, it will be set in this exception field.
• Properties: The properties is a Map<String, Object> and may look like message headers. The main difference is their lifetime: the properties exist during the whole exchange execution, whereas the headers are limited to the message duration (and a message can change a lot during routing, so during the exchange execution). Camel itself may add some properties for some use cases.
• Finally, we have the in and out messages.
  • In Message: The in message is mandatory and always set. It's the only message populated in the exchange with InOnlyMEP.
  • Out Message: The out message is optional and is only used with InOutMEP.

  With InOutMEP, at the end of the processing of the exchange, the out message will be used and returned to the mediation beginner (the first endpoint of the routing who created the exchange).