Route Definitions (Technical Guide)
- Mike Deskis
Apache Camel supports two alternative Domain-Specific Languages (DSL) for defining its routes: a Java DSL and a Spring XML DSL. The major building blocks for defining routes are endpoints and processors, where the behavior of a processor is typically modified by expressions or logical predicates. Apache Camel enables you to define expressions and predicates using a variety of different languages.
Concept of a DSL
A Domain-Specific Language (DSL) is a mini-language designed for a special purpose. It tends to be a tier on top of an existing object-oriented language (Java, Groovy, etc), and this provides the DSL with the constructs cleanly map to the host language API. A DSL does not have to be logically complete (like Java or Groovy), but needs enough power to describe problems adequately in the chosen domain. Typically, a DSL does not require a dedicated parser, interpreter, or compiler.
Syntax of Router Rule
Apache Camel defines a router DSL for defining routing rules. You can use this DSL to define your rules and the illustration below shows an overview of the basic syntax for defining local routing rules.
Local Routing Rules
A local rule always will always start with a from(“EnpointURL”) method, which specifies the source of messages (consumer endpoint) for the routing rule. Then, we can add an arbitrarily long chain of processors to the rule (for example, filter()). You typically finish off the rule with a to(“EndpointURL”) method, which specifies the target (producer endpoint) for all of the messages that are passing through the routing rule.
Consumers and producers
A local rule will always start by defining a consumer endpoint, using the from(“EndpointURL”) method and then generally it will end by identifying a producer endpoint with to(“EndpointURL”). The endpoint URLs, EndpointURL, can use any of the components configured at deployment time.
For example, you could use a file endpoint, file:MyMessageDirectory, an Apache CXF endpoint, cxf:MyServiceName, or an Apache ActiveMQ endpoint, activemq:queue:MyQName.
Exchanges
An exchange object consists of a message and is then augmented by metadata. Exchanges are of central importance in Apache Camel, because the exchange is the standard form in which messages are propagated through routing rules. The main ingredients of an exchange are, as follows:
Input message
This will be the current message encapsulated by the exchange. As the exchange progresses through a route, this message may be modified in many different ways via different integration patterns. Therefore, the message at the inception of a route is typically NOT the same as the message at the conclusion of the route. The org.apache.camel.Message type provides a generic model of a message, with the following parts; Body, Headers, Attachments.
NOTE: It is important to recognize that this format is only for a generic model of a message. Apache Camel supports a large variety of protocols and endpoint types. Hence, it isn't possible or conceivable to standardize the format of the message body or the message headers.
Output message
This is a temporary holding area for a reply message or for a message that has been transformed. Certain processing nodes can modify the current message by treating the input message as a request, routing it to a producer endpoint, and then receiving a reply back from that endpoint. The reply message from the endpoint will then be inserted into the output message slot in the exchange.
Message Exchange Patterns (MEP)
These are patterns that will impact the interaction between the exchange and endpoints in the route, as follows:
Consumer endpoint — this creates the original exchange and will define the initial value of the MEP. This starting value will indicate whether the consumer endpoint expects to receive a reply (by using the InOut MEP) or not (with the use of the InOnly MEP).
Producer endpoints — the MEP will impact the producer endpoints that our exchange passes through along the route. For example, if the current MEP has been set InOnly, a destination node would not expect to receive a reply from the endpoint. There may be occasions when we need to change the state of the MEP to customize the exchange’s interaction with a producer endpoint.
Message exchange patterns
The use of an Exchange object makes it simple to generalize message processing to different message exchange patterns. As an example, an asynchronous protocol might define an MEP that consists of a single message that travels from the consumer to producer endpoint (ie. InOnly MEP).
An RPC protocol (remote procedure call), might define an MEP that consists of only a request and a reply message (ie. InOut MEP). Currently, Apache Camel supports the following MEPs:
InOnly
RobustInOnly
InOut
OutOnly
InOptionalOut
OutIn
OutOptionalIn
RobutstOutOnly
Processors
A processor is a node in a route that can access and modify the stream of exchanges passing through the route. Processors can accept either expression or predicate arguments that can modify their behavior. As an example, the local routing rule shown earlier on this page includes a Filter processor that takes an XPath() predicate as its passed argument.
Expressions and Predicates
Within our routing rules, we will use; Expressions (evaluating to strings or other data types), and predicates (evaluating to true or false) and these can occur frequently as arguments to the different processor types. For example, the following filter rule propagates input messages, only if the hello header is equal to the value of “helloworld”:
from("account:a"").filter(header("hello").isEqualTo("helloworld").to("acct:b"")