Introduction To Apache Camel

1. Overview

In this article, we’ll introduce Apache Camel and explore one of its core concepts – message routing.

We’ll start by covering some foundational concepts and terminology, and then we’ll present two options for defining routes – Java DSL and Spring DSL.

We’ll also demonstrate these with an example by defining a route that consumes files from one folder and moves them to another while prepending a date to each file name.

2. About Apache Camel

Apache Camel is an open-source integration framework designed to make integrating systems simple and easy.

It allows end users to integrate various systems using the same API, providing support for multiple protocols and data types while being extensible and allowing the introduction of custom protocols.

3. Maven Dependencies

Let’s start by declaring the camel-spring-boot-starter and spring-boot-starter-web dependencies in our pom.xml:

<dependency>
    <groupId>org.apache.camel.springboot</groupId>
    <artifactId>camel-spring-boot-starter</artifactId>
    <version>4.3.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <version>2.7.11</version>
</dependency>

Also, for testing, we need to add the camel-test-spring-junit5 and awaitility dependencies to the pom.xml file:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-test-spring-junit5</artifactId>
    <version>4.3.0</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.awaitility</groupId>
    <artifactId>awaitility</artifactId>
    <version>4.2.0</version>
    <scope>test</scope>
</dependency>

4. Domain-Specific Language

Routes and the routing engine are a central part of Camel. Routes contain the flow and logic of integration between different systems.

In order to define routes more easily and cleanly, Camel offers several different domain-specific languages (DSL) for programming languages like Java or Groovy. On the other hand, it also provides defining routes in XML with Spring DSL.

Using either Java DSL or Spring DSL is mostly user preference, as most of the features are available in both.

Java DSL offers a bit more features that are not supported in Spring DSL. However, Spring DSL is sometimes more beneficial as configuration XML can be changed without the need to recompile the code.

5. Terminology and Architecture

Let’s now discuss the basic Camel terminology and architecture.

First, we’ll have a look at the core Camel concepts:

• Message contains data that is being transferred to a route. Each message has a unique identifier, and it’s constructed out of a body, headers, and attachments.
• Exchange is the container of a message, and it is created when a message is received by a consumer during the routing process. Exchange allows different types of interaction between systems – it can define a one-way message or a request-response message.
• Endpoint is a channel through which the system can receive or send a message. It can refer to a web service URI, queue URI, file, email address, etc.
• Component acts as an endpoint factory. To put it simply, components offer an interface to different technologies using the same approach and syntax. Camel already supports a lot of components in its DSLs for almost every possible technology, but it also gives the ability to write custom components.
• Processor is a simple Java interface that is used to add custom integration logic to a route. It contains a single process method used to perform custom business logic on a message received by a consumer.

At a high level, the architecture of Camel is simple. CamelContext represents the Camel runtime system, and it wires different concepts such as routes, components, or endpoints.

And below that, processors handle routing and transformations between endpoints while endpoints integrate different systems.

6. Defining a Route

Routes can be defined with Java DSL or Spring DSL.

We’ll illustrate both styles by defining a route that consumes files from one folder and moves them into another folder while prepending a date to each file name.

6.1. Routing With Java DSL

To define a route with Java DSL, we will first need to create a DefaultCamelContext instance. After that, we need to extend the RouteBuilder class and implement the configure method, which will contain route flow:

private static final long DURATION_MILIS = 10000;
private static final String SOURCE_FOLDER = "src/test/source-folder";
private static final String DESTINATION_FOLDER = "src/test/destination-folder";

@Test
public void givenJavaDSLRoute_whenCamelStart_thenMoveFolderContent() throws Exception {
    CamelContext camelContext = new DefaultCamelContext();
    camelContext.addRoutes(new RouteBuilder() {
      @Override
      public void configure() throws Exception {
        from("file://" + SOURCE_FOLDER + "?delete=true")
          .process(new FileProcessor())
          .to("file://" + DESTINATION_FOLDER);
      }
    });
    camelContext.start();
    Date date = new Date();
    SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
    File destinationFile1 = new File(DESTINATION_FOLDER + "/" + dateFormat.format(date) + "File1.txt");
    File destinationFile2 = new File(DESTINATION_FOLDER + "/" + dateFormat.format(date) + "File2.txt");

    Awaitility.await().atMost(DURATION_MILIS, TimeUnit.MILLISECONDS).untilAsserted(() -> {
      assertThat(destinationFile1.exists()).isTrue();
      assertThat(destinationFile2.exists()).isTrue();
    });
    camelContext.stop();
}

The configure method can be read like this: read files from the source folder, process them with FileProcessor, and send the result to a destination folder. Setting delete=true means the file will be deleted from the source folder after it is processed successfully.

In order to start Camel, we need to call the start method on CamelContext. After that, we use the await() method (one of the static methods of the Awaitility class) in order to allow Camel the time necessary to move the files from one folder to another. The atMost() method sets an upper limit on how long Awaitility should wait for the conditions to be met. In this case, it will wait up to DURATION_MILIS milliseconds.

In addition, we can use the untilAsserted() method. This method allows us to provide a lambda or method reference that contains one or more assertions. Awaitility will repeatedly run these assertions until they all pass or the specified atMost() duration is reached. Here, there are two assertions being made using the assertThat() method. In these assertions, we check the file’s existence in the destination folder.

FileProcessor implements the Processor interface and contains a single process method that contains logic for modifying file names:

@Component
public class FileProcessor implements Processor {
    @Override
    public void process(Exchange exchange) throws Exception {
        String originalFileName = (String) exchange.getIn().getHeader(Exchange.FILE_NAME, String.class);

        Date date = new Date();
        SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
        String changedFileName = dateFormat.format(date) + originalFileName;
        exchange.getIn().setHeader(Exchange.FILE_NAME, changedFileName);
    }
}

In order to retrieve the file name, we have to retrieve an incoming message from an exchange and access its header. Similarly, to modify the file name, we have to update the message header.

6.2. Routing With Spring DSL

When defining a route with Spring DSL, we use an XML file to set up our routes and processors. This allows us to configure routes using no code by using Spring and, ultimately, gives us the benefit of total inversion of control.

This was already covered in the existing article, so we will focus on using both Spring DSL along with Java DSL, which is commonly a preferred way of defining routes.

In this arrangement, CamelContext is defined in Spring XML file using custom XML syntax for Camel, but without the route definition like in the case of “pure” Spring DSL using XML:

<camelContext xmlns="http://camel.apache.org/schema/spring">
    <routeBuilder ref="fileRouter" />
</camelContext>

This way, we tell Camel to use the FileRouter class, which holds the definition of our route in Java DSL:

@Component
public class FileRouter extends RouteBuilder {

    private static final String SOURCE_FOLDER =  "src/test/source-folder";
    private static final String DESTINATION_FOLDER = "src/test/destination-folder";

    @Override
    public void configure() throws Exception {
        from("file://" + SOURCE_FOLDER + "?delete=true")
          .process(new FileProcessor())
          .to("file://" + DESTINATION_FOLDER);
    }
}

In order to test this, we have to create an instance of ClassPathXmlApplicationContext, which will load up our CamelContext in Spring:

@Test
public void givenSpringDSLRoute_whenCamelStart_thenMoveFolderContent() throws Exception {
    ClassPathXmlApplicationContext applicationContext = 
      new ClassPathXmlApplicationContext("camel-context-test.xml");

    Date date = new Date();
    SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
    File destinationFile1 = new File(DESTINATION_FOLDER + "/" + dateFormat.format(date) + "File1.txt");
    File destinationFile2 = new File(DESTINATION_FOLDER + "/" + dateFormat.format(date) + "File2.txt");

    Awaitility.await().atMost(DURATION_MILIS, TimeUnit.MILLISECONDS).untilAsserted(() -> {
      assertThat(destinationFile1.exists()).isTrue();
      assertThat(destinationFile2.exists()).isTrue();
    });
    applicationContext.close();
}

By using this approach, we get additional flexibility and benefits provided by Spring, as well as all the possibilities of Java language by using Java DSL.

7. Conclusion

In this quick article, we presented an introduction to Apache Camel and demonstrated the benefits of using Camel for integration tasks such as routing files from one folder to another.

In our example, we saw that Camel lets us focus on business logic and reduces the amount of boilerplate code.