DIGEST OF GETTING STARTED WITH APACHE CAMEL

Getting Started with Apache Camel

THE ENTERPRISE INTEGRATION PATTERNS (EIP) BOOK

The purpose of a patterns book is not to advocate new techniques that the authors have invented, but rather to document existing best practices within a particular field. By doing this, the authors of a patterns book hope to spread knowledge of best practices and promote a vocabulary for discussing architectural designs.

Design Patterns: Elements of Reusable Object-oriented Software by GoF(Gang of Four)
EIP: Enterprise Integration Patterns: Design, Building, and Deploying Messaging Solutions by Gregor Hohpe and Bobby Woolf

As the subtitle of EIP suggests, the book focuses on design patterns for asynchronous messaging systems.

CONCEPTS AND TERMINOLOGY FUNDAMENTAL TO CAMEL

ENDPOINT

Camel provides out-of-the-box support for endpoints implemented with many different communication technologies. Here are some examples of the Camel-supported endpoint technologies.

• A JMS queue.
• A web service.
• A file. A file may sound like an unlikely type of endpoint, until you realize that in some systems one application might write information to a file and, later, another application might read that file.
• An FTP server.
• An email address. A client can send a message to an email address, and a server can read an incoming message from a mail server.
• A POJO (plain old Java object).

In a Camel-based application, you create (Camel wrappers around) some endpoints and connect these endpoints with routes.
Each Camel-supported endpoint has a class that implements this Endpoint interface.

CAMELCONTEXT

A CamelContext object represents the Camel runtime system. You typically have one CamelContext object in an application. A typical application executes the following steps:

1. Create a CamelContext object.
2. Add endpoints – and possibly components to the CamelContext object.
3. Add routes to the CamelContext object to connect the endpoints.
4. Invoke the start() operation on the CamelContext object. This starts Camel-internal threads that are used to process the sending, receiving and processing of messages in the endpoints.
5. Eventually invoke the stop() operation on the CamelContext object. Doing this gracefully stops all the endpoints and Camel-internal threads.

Note that the CamelContext.start() operation does not block indefinitely. Rather, it starts threads internal to each Component and Endpoint and then start() returns. Conversely, CamelContext.stop() waits for all the threads internal to each Endpoint and Component to terminate and then stop() returns.

If you neglect to call CamelContext.start() in your application then messages will not be processed because internal threads will not have been created.

If you neglect to call CamelContext.stop() before terminating your application then the application may terminate in an inconsistent state. If you neglect to call CamelContext.stop() in a JUnit test then the test may fail due to messages not having had a chance to be fully processed.

CAMELTEMPLATE

The CamelTemplate class is a thin wrapper around the CamelContext class. It has methods that send a Message or Exchange to an Endpoint . This provides a way to enter messages into source endpoints, so that the messages will move along routes to destination endpoints.

COMPONENTS

Component is confusing terminology; EndpointFactory would have been more appropriate because a Component is a factory for creating Endpoint instances.

Actually, application-level code does not invoke Component.createEndpoint() directly. Instead, application-level code normally invokes CamelContext.getEndpoint(); internally, the CamelContext object finds the desired Component object (as I will discuss shortly) and then invokes createEndpoint() on it.

A CamelContext object maintains a mapping from component names to Component objects.
There are two ways of populating the map.

• The first way is for application-level code to invoke CamelContext.addComponent(String componentName, Component component).
• The second (and preferred) way to populate the map of named Component objects in the CamelContext object is to let the CamelContext object perform lazy initialization.

Let’s assume you write a class called com.example.myproject.FooComponent and you want Camel to automatically recognize this by the name foo. To do this, you have to write a properties file called META-INF/services/org/apache/camel/component/foo (without a .properties file extension) that has a single entry in it called class, the value of which is the fully-scoped name of your class. This is shown below:

META-INF/services/org/apache/camel/component/foo

class=com.example.myproject.FooComponent

MESSAGE AND EXCHANGE

The Message interface provides an abstraction for a single message, such as a request, reply or exception message.

The Exchange interface provides an abstraction for an exchange of messages, that is, a request message and its corresponding reply or exception message. In Camel terminology, the request, reply and exception messages are called in, out and fault messages.

PROCESSOR

The Processor interface represents a class that processes a message. The signature of this interface is shown below:

Processor

package org.apache.camel;
public interface Processor {
    void process(Exchange exchange) throws Exception;
}

An application-level developer might implement the Processor interface with a class that executes some business logic. However, there are many classes in the Camel library that implement the Processor interface in a way that provides support for a design pattern in the EIP book. For example, ChoiceProcessor implements the message router pattern, that is, it uses a cascading if-then-else statement to route a message from an input queue to one of several output queues. Another example is the FilterProcessor class which discards messages that do not satisfy a stated predicate (that is, condition).

ROUTES, ROUTEBUILDERS AND JAVA DSL

A route is the step-by-step movement of a Message from an input queue, through arbitrary types of decision making (such as filters and routers) to a destination queue (if any).

Camel provides two ways for an application developer to specify routes.
One way is to specify route information in an XML file. A discussion of that approach is outside the scope of this document.
The other way is through what Camel calls a Java DSL (domain-specific language).

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        from("queue:a").filter(header("foo").isEqualTo("bar")).to("queue:b");
        from("queue:c").choice()
                .when(header("foo").isEqualTo("bar")).to("queue:d")
                .when(header("foo").isEqualTo("cheese")).to("queue:e")
                .otherwise().to("queue:f");
    }
};
CamelContext myCamelContext = new DefaultCamelContext();
myCamelContext.addRoutes(builder);

The online Camel documentation compares Java DSL favorably against the alternative of configuring routes and endpoints in a XML-based Spring configuration file. In particular, Java DSL is less verbose than its XML counterpart. In addition, many integrated development environments (IDEs) provide an auto-completion feature in their editors. This auto-completion feature works with Java DSL, thereby making it easier for developers to write Java DSL.