Apache Camel Exception Handling

1. Overview

Apache Camel is a powerful open-source integration framework implementing several of the known Enterprise Integration Patterns.

Typically when working with message routing using Camel, we’ll want a way to handle errors effectively. For this, Camel provides a couple of strategies for handling exceptions.

In this tutorial, we’ll take a look at two approaches we can use for exception handling inside our Camel application.

2. Dependencies

All we’ll need to get started is the camel-spring-boot-starter added to our pom.xml:

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

3. Creating a Route

Let’s begin by defining a fairly elementary route that deliberately throws an exception:

@Component
public class ExceptionThrowingRoute extends RouteBuilder {

    private static final Logger LOGGER = LoggerFactory.getLogger(ExceptionThrowingRoute.class);

    @Override
    public void configure() throws Exception {
        
        from("direct:start-exception")
          .routeId("exception-handling-route")
          .process(new Processor() {
              
              @Override
              public void process(Exchange exchange) throws Exception {
                  LOGGER.error("Exception Thrown");
                  throw new IllegalArgumentException("An exception happened on purpose");
                  
              }
          }).to("mock:received");
    }
}

To quickly recap, a route in Apache Camel is a fundamental building block, normally formed of a sequence of steps, executed in order by Camel, that consumes and processes a message.

As we can see in our trivial example, we configure our route to consume messages from a direct endpoint called start.

Then, we throw an IllegalArgumentException from within a new Processor, which we create inline inside our route using Java DSL.

Currently, our route contains no kind of exception handling, so when we run it, we’ll see something a little bit ugly in the output of our application:

...
10:21:57.087 [main] ERROR c.b.c.e.ExceptionThrowingRoute - Exception Thrown
10:21:57.094 [main] ERROR o.a.c.p.e.DefaultErrorHandler - Failed delivery for (MessageId: 50979CFF47E7816-0000000000000000 on ExchangeId: 50979CFF47E7816-0000000000000000). 
Exhausted after delivery attempt: 1 caught: java.lang.IllegalArgumentException: An exception happened on purpose

Message History (source location and message history is disabled)
---------------------------------------------------------------------------------------------------------------------------------------
Source                                   ID                             Processor                                          Elapsed (ms)
                                         exception-handling-route/excep from[direct://start-exception]                               11
	...
                                         exception-handling-route/proce Processor@0x3e28af44                                          0

Stacktrace
---------------------------------------------------------------------------------------------------------------------------------------
java.lang.IllegalArgumentException: An exception happened on purpose
...

4. Using a doTry() Block

Now let’s go ahead and add some exception handling to our route. In this section, we’ll take a look at Camel’s doTry() block, which we can think of as the Java equivalent of try​ catch finally, but directly embedded in the DSL.

But first, to help simplify our code, we’re going to define a dedicated processor class that throws an IllegalArgumentException – this will make our code more readable, and we can reuse our processor in other routes later on:

@Component
public class IllegalArgumentExceptionThrowingProcessor implements Processor {

    private static final Logger LOGGER = LoggerFactory.getLogger(ExceptionLoggingProcessor.class);

    @Override
    public void process(Exchange exchange) throws Exception {
        LOGGER.error("Exception Thrown");
        throw new IllegalArgumentException("An exception happened on purpose");
    }
}

With our new processor in place, let’s make use of it in our first exception-handling route:

@Component
public class ExceptionHandlingWithDoTryRoute extends RouteBuilder {

    @Override
    public void configure() throws Exception {
        
        from("direct:start-handling-exception")
          .routeId("exception-handling-route")
          .doTry()
            .process(new IllegalArgumentExceptionThrowingProcessor())
            .to("mock:received")
          .doCatch(IOException.class, IllegalArgumentException.class)
            .to("mock:caught")
          .doFinally()
            .to("mock:finally")
          .end();
    }
}

As we can see, the code in our route is pretty self-explanatory. We’re basically mimicking a regular Java try catch finally statement using the Camel equivalents.

However, let’s walk through the key parts of our route:

• First, we surround the part of the route where we want thrown exceptions to be immediately caught using the doTry() method
• Next, we close this block using and latterly the doCatch method. Notice we can pass a list of different exception types we wish to catch
• Lastly, we call doFinally(), which defines code that’s always run after the doTry(), and any doCatch() blocks

Furthermore, we should note that it is important to call the end() method to denote the end of the block in Java DSL.

Camel also provides another powerful feature that lets us work with predicates when using the doCatch() block:

...
.doCatch(IOException.class, IllegalArgumentException.class).onWhen(exceptionMessage().contains("Hello"))
   .to("mock:catch")
...

Here we add a runtime predicate to determine if the catch block should be triggered or not. In this case, we only want to trigger it if the caused exception message contains the word Hello. Pretty cool!

5. Working With the Exception Clause

Unfortunately, one of the limitations of the previous approach is that it is applicable only to a single route.

Typically as our application grows and we add more and more routes, we probably don’t want to handle exceptions on a route-by-route basis. This will likely lead to duplicated code, and we may want a common error-handling strategy for our application.

Thankfully Camel provides an Exception Clause mechanism via Java DSL to specify the error handling we require on a per exception type basis or global basis:

Let’s imagine we want to implement an exception-handling policy for our application. For our simple example, we’ll assume we only have one route:

@Component
public class ExceptionHandlingWithExceptionClauseRoute extends RouteBuilder {
    
    @Autowired
    private ExceptionLoggingProcessor exceptionLogger;
    
    @Override
    public void configure() throws Exception {
        onException(IllegalArgumentException.class).process(exceptionLogger)
          .handled(true)
          .to("mock:handled")
        
        from("direct:start-exception-clause")
          .routeId("exception-clause-route")
          .process(new IllegalArgumentExceptionThrowingProcessor())
          .to("mock:received");
    }
}

As we can see, we’re using the onException method to handle when an IllegalArgumentException occurs and apply some specific piece of processing.

For our example, we pass the processing to a custom ExceptionLoggingProcessor class that simply logs the message headers. Finally, we use the handled(true) method to mark the message exchange as handled before sending the result to a mock endpoint called handled.

However, we should note that in Camel, the global scope for our code is per RouteBuilder instance. Therefore if we want to share this exception-handling code via multiple RouteBuilder classes, we can use the following technique.

Simply create a base abstract RouteBuilder class and put the error-handling logic in its configure method.

Subsequently, we can simply extend this class and make sure we call the super.configure() method. In essence, we are just using the Java inheritance technique.

6. Conclusion

In this article, we learned how we could handle exceptions in our routes. First, we created a simple Camel application with several routes to learn about exceptions.

Then we learned about two concrete approaches using the doTry() and doCatch() block syntax and, latterly, the onException() clause.