Add Camel Route at Runtime in Java

1. Overview

Apache Camel is a Java framework that makes it easy to implement various Enterprise Integration Patterns (EIPs) for providing solutions to enterprise integration.

One of the common tasks in an integration pattern is to determine the message route at a runtime based on specific rules and conditions. Apache Camel simplifies this process by providing a method to implement Dynamic Router EIP.

In this tutorial, we’ll delve into details of how to implement dynamic routing in Apache Camel and walk through an example.

2. Understanding the Dynamic Router

Occasionally, there are cases where we want to send messages to different routes based on specific rules and conditions at runtime. Solutions like the Routing Slip EIP can help solve the problem, but it is less efficient because it use trial-and-error.

In Routing Slip EIP, a message contains the list of endpoints to route to in a defined order. This requires pre-configuring the endpoint list and uses a trial-and-error approach to send messages through each endpoint.

The Dynamic Router EIP provides better implementation to add a route at runtime, especially in a case where we have multiple recipients or none at all. It provides flexibility to route messages without pre-configured strict endpoints.

Additionally, it knows every destination and rules for routing a message to a specific destination. Also, it has a control channel that potential destinations communicate to by announcing their presence and rule of engagement on startup.

Furthermore, it stores the rules for all possible destinations in a rule base. Once a message arrives, it checks the rule base and fulfills the request of a recipient.

Here’s an image showing the internals of Dynamic Router EIP:

Moreover, a common use case is dynamic service discovery, where a client application can access a service by sending a message containing the name of the service.

The core goal of Dynamic Router EIP is to defer the routing decision to runtime rather than building static rules upfront.

3. Maven Dependencies

Let’s bootstrap a simple Apache Camel project by adding the camel-core and camel-test-junit5 to the pom.xml:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-core</artifactId>
    <version>4.3.0</version>
</dependency>

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-test-junit5</artifactId>
    <version>4.3.0</version>
</dependency>

The Camel Core provides the Dynamic Router EIP along with other routing capabilities, and Camel Test JUnit5 helps make testing message routes easier with the CamelSupport interface.

Notably, we can also bootstrap the Camel project as a Spring Boot project.

4. Add Route at Runtime Using the Dynamic Router

The Dynamic Router EIP ensures that we specify rules for an integration system to aid right matching to a specific route at runtime. It checks for the incoming message’s body and matches it to a route.

4.1. Configuration

First, let’s create a class named DynamicRouteBean and add a method to define rules and conditions:

class DynamicRouterBean {
    public String route(String body, @ExchangeProperties Map<String, Object> properties) {
        int invoked = (int) properties.getOrDefault("invoked", 0) + 1;

        properties.put("invoked", invoked);

        if (invoked == 1) {
            switch (body.toLowerCase()) {
                case "mock":
                    return "mock:dynamicRouter";
                case "direct":
                    return "mock:directDynamicRouter";
                case "seda":
                    return "mock:sedaDynamicRouter";
                case "file":
                    return "mock:fileDynamicRouter";
                default:
                    break;
            }
        }
        return null;
    }
}

In the code above, we dynamically determine the appropriate route based on the incoming message body and current invocation count. The route() method checks if the message body matches any of the predefined keyword rules and returns the corresponding route.

Furthermore, we use the @ExchangeProperties annotation on a Map object. This map serves as a container to store and retrieve the current state of the exchange and update the invocation count.

Also, the invoked variable represents the number of times the route() method has been invoked. If the message matches a predefined condition and it’s the first invocation, the corresponding route is returned. The invoked == 1 check helps to execute the dynamic routing logic on the first invocation. This simplifies the code in this specific case and prevents unnecessary re-execution.

Also, to prevent endless execution of the Dynamic Router, the route() method returns null after routing to the appropriate endpoint. This ensures dynamic routing concludes after a route is identified based on the message.

Simply put, the route() method is called for every exchange until a null is returned.

Finally, let’s configure the Dynamic Router EIP in our Camel route builder:

class DynamicRouterRoute extends RouteBuilder {
    @Override
    void configure() {
        from("direct:dynamicRouter")
          .dynamicRouter(method(DynamicRouterBean.class, "route"));
    }
}

In the code above, we create the DynamicRouterRoute class that extends RouteBuilder. Next, we override the configure method and add the dynamic route bean by invoking the dyamicRouter() method to wire the Dynamic Router call to our custom route().

Notably, we can use @DynamicRouter annotation on the method that defines our rules:

class DynamicRouterBean {
    @DynamicRouter
    String route(String body, @ExchangeProperties Map<String, Object> properties) {
        // ...
    }
}

The annotation eliminates the need to explicitly configure dynamicRouter() method in the Camel route:

// ...
@Override
void configure() {
    from("direct:dynamicRouter").bean(DynamicRouterBean.class, "route");
}  
// ...

In the code above, we specify the class that contains the routing logic using the bean() method. The dynamicRouter() method is no longer needed because the route() method is annotated with @DynamicRouter.

4.2. Unit Test

Let’s write a unit test to assert if some of the conditions are true. First, let’s ensure our test class extends CamelTestSupport:

class DynamicRouterRouteUnitTest extends CamelTestSupport {
    @Override
    protected RoutesBuilder createRouteBuilder() {
        return new DynamicRouterRoute();
    } 
}

Here, provide an instance of DynamicRouterRoute to be used as a route builder for testing.

Next, let’s see an incoming message body named mock:

@Test
void whenMockEndpointExpectedMessageCountOneAndMockAsMessageBody_thenMessageSentToDynamicRouter() throws InterruptedException {
    MockEndpoint mockDynamicEndpoint = getMockEndpoint("mock:dynamicRouter");
    mockDynamicEndpoint.expectedMessageCount(1);

    template.send("direct:dynamicRouter", exchange -> exchange.getIn().setBody("mock"));
    MockEndpoint.assertIsSatisfied(context);
}

Here, we mock the dynamic endpoint and set the expected message route as its value. Next, we set the expected message count to one. Finally, we set an incoming message route with an expected body message and assert the MockEndpoint route is satisfied.

Also, let’s mock the “mock:directDynamicRouter” message route:

@Test
void whenMockEndpointExpectedMessageCountOneAndDirectAsMessageBody_thenMessageSentToDynamicRouter() throws InterruptedException {
    MockEndpoint mockDynamicEndpoint = context.getEndpoint("mock:directDynamicRouter", MockEndpoint.class);
    mockDynamicEndpoint.expectedMessageCount(1);

    template.send("direct:dynamicRouter", exchange -> exchange.getIn().setBody("direct"));

    MockEndpoint.assertIsSatisfied(context);
}

This test validates that when “direct” is sent as the message body, it gets routed dynamically to the “mock:directDynamicRouter” endpoint. Also, we set the expected message count to one, indicating the number of message exchanges that the endpoint should receive.

5. Conclusion

In this article, we learned how to add routes at runtime in Apache Camel using the Dynamic Router EIP. Unlike Routing Slip which uses a try-and-error approach to send a message to a route, Dynamic Router EIP provides a solid implementation to route to an endpoint based on specific rules and conditions.