Chapter 5. Messaging Systems


This chapter introduces the fundamental building blocks of a messaging system, such as endpoints, messaging channels, and message routers.

5.1. Message


A message is the smallest unit for transmitting data in a messaging system (represented by the grey dot in the figure below). The message itself might have some internal structure—for example, a message containing multiple parts—which is represented by geometrical figures attached to the grey dot in Figure 5.1, “Message Pattern”.

Figure 5.1. Message Pattern

Message pattern

Types of message

Apache Camel defines the following distinct message types:
  • In message — A message that travels through a route from a consumer endpoint to a producer endpoint (typically, initiating a message exchange).
  • Out message — A message that travels through a route from a producer endpoint back to a consumer endpoint (usually, in response to an In message).
All of these message types are represented internally by the org.apache.camel.Message interface.

Message structure

By default, Apache Camel applies the following structure to all message types:
  • Headers — Contains metadata or header data extracted from the message.
  • Body — Usually contains the entire message in its original form.
  • Attachments — Message attachments (required for integrating with certain messaging systems, such as JBI).
It is important to remember that this division into headers, body, and attachments is an abstract model of the message. Apache Camel supports many different components, that generate a wide variety of message formats. Ultimately, it is the underlying component implementation that decides what gets placed into the headers and body of a message.

Correlating messages

Internally, Apache Camel remembers the message IDs, which are used to correlate individual messages. In practice, however, the most important way that Apache Camel correlates messages is through exchange objects.

Exchange objects

An exchange object is an entity that encapsulates related messages, where the collection of related messages is referred to as a message exchange and the rules governing the sequence of messages are referred to as an exchange pattern. For example, two common exchange patterns are: one-way event messages (consisting of an In message), and request-reply exchanges (consisting of an In message, followed by an Out message).

Accessing messages

When defining a routing rule in the Java DSL, you can access the headers and body of a message using the following DSL builder methods:
  • header(String name), body() — Returns the named header and the body of the current In message.
  • outBody() — Returns the body of the current Out message.
For example, to populate the In message's username header, you can use the following Java DSL route:
from(SourceURL).setHeader("username", "John.Doe").to(TargetURL);