Instant Apache Camel Messaging System: Tackle integration problems and learn practical ways to make data flow between your application and other systems using Apache Camel

Routing is an instruction or a list of instructions describing what to do with the message. EIP provides an exhaustive list of all possible routing schemes, including the following to name a few:

There are many others and we will look at most of them later in the book. Apache Camel implements all of them. Further, routing is the primary objective of Apache Camel. The routing strategies can be easily defined using any of the following domain-specific languages (DSL):

Transformation changes the message passed between the systems based on its content. Examples of the components performing the transformation could be Content Enricher and Content Filter. Content Enricher adds information to the message from an external resource while Content Filter removes information from the message. For example, Content Enricher could add personal information about an employee based on his employee ID, which has been passed in the message, while the Content Filter could do the opposite by stripping the personal information from the message, leaving only the employee ID.

There are several ways to monitor a working Camel application, that is, view and explore the availability of the routes/services, collect performance statistics, and so on; these are Camel Web Console, wiretapping and interception, BrowsableEndpoint, and JMX.

First, if you don't have a project yet, create one with the following command line (assuming that you want your application's name to be cuscom and packages to start with com.company, if not, change the command accordingly):

mvn archetype:generate -DgroupId=com.company -DartifactId=cuscom -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

Now, go to the project directory cuscom.

To make specifying the version of Apache Camel and its modules easier, add the following to your POM file:

<properties>
  <camel-version>2.10.4</camel-version>
</properties>

If you already have the properties element, just put the camel-version element inside it.

Add the following lines to the list of the dependencies in your pom.xml file:

<dependency>
  <groupId>org.apache.camel</groupId>
    <artifactId>camel-core</artifactId>
    <version>${camel-version}</version>
</dependency>

If you are planning on working with your project using Eclipse, run:

mvn eclipse:eclipse

If you are planning on working with your project using IntelliJ IDEA, run:

mvn idea:idea

That is it. Depending on the IDE you use, if any, you might need to update dependencies before you are able to start using them in your code.

As you may have noticed, we have added camel-core, which contains only the basic components and core functionality. The real power of Apache Camel stems from its modularity and the availability of various components that let developers integrate different systems and mediate data between them.

Copy camel-core-2.10.4.jar, according to your application layout, to a directory with other JAR files and add it to CLASSPATH.

Message in Apache Camel is an object type that implements the Message interface. Most developers deal with the implementation of the interface DefaultMessage. Everything is implemented in a good way and you likely will not need to override any of its methods or change its functionality, but you do need to know what the message is, what it consists of, and how to work with it. Message has four main parts:

If you imagine the routing diagram as a graph, then an endpoint is a node on that graph. In Apache Camel, an endpoint either produces messages, consumes them, or both. These endpoints are created by components and usually referred to by their URI. In our case, direct:start is an endpoint that allows us to send messages to it synchronously and log:end is an endpoint that lets us send messages to the log. An endpoint is also a factory of producers and consumers.

An Exchange, on the abstract level, is a link between two steps on the route in Apache Camel. It is a container that holds information for a message that is created by the producer and going to the consumer. An Exchange has a reference to the message as it leaves the producer endpoint and to the message as it enters consumer endpoint, as well as information about routing the message, protocols used, any errors or exceptions thrown, and so on.

If we represent the routing of the message as a graph, with nodes being endpoints, then an Exchange would be the edge on that graph connecting two nodes.

We construct one route using Java DSL (Domain Specific Language) to route messages from the Endpoint described by direct:start to the log (which is actually referred to by the string log:end?level=INFO):

from("direct:start")
  .to("log:end?level=INFO");

Java DSL is available inside the RouteBuilder class. It is, in fact, a set of methods that returns objects that could all be chained or wired together. More information about this design pattern called Fluent interface is available from http://martinfowler.com/bliki/FluentInterface.html.

Every route in Apache Camel is a sequence of Endpoints that could generally be depicted by the following diagram:

Target and source are endpoints and each could be either an object of class Endpoint or a string of a certain format, such as Uniform Resource Identifier.

Let's say we have an endpoint described by the URI file data/inbox. That would mean that this endpoint is dealt with through FileComponent and the file path is data/inbox.

A complete list of Apache Camel components and their URI schemes and parameters that you can use is available online at http://camel.apache.org/components.html.

Between the from and to endpoints, we can have as complex a route as we need. We can add custom processors, filters, choices, and so on using Domain Specific Language (DSL).

We will make adding components a bit more interesting and use a component camel-stream. Just add this dependency to our POM file. You can also replace dependency camel-core with camel-stream. Since camel-stream depends on camel-core, camel-core will be added to the project automatically:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-stream</artifactId>
    <version>${camel-version}</version>
</dependency>

This will add the streaming component (its documentation is located at http://camel.apache.org/stream.html), so we can now use System.in and System.out as well as any implementation of the InputStream or OutputStream for our input and output. Let's rewrite our routes as follows:

public void configure() throws Exception {
    from("stream:in")
            .to("stream:out");
}

Now, if we start the application from the console, we will see that the application got started and is waiting for the input. You can type anything and, as soon as you hit Enter, your message will be printed back to you as shown in the following screenshot:

That's pretty cool. Further, you can change routes to use FileComponent:

public void configure() throws Exception {
    from("stream:in")
            .to("file:test");
}

Before we run the previous code, we have files and directories in our project that look similar to those in the following screenshot (you may also have a target directory that contains compiled classes):

When we run the program from the console, enter something, and then hit Enter, our application will send a message:

In this example, we send messages to the file:test endpoint. FileComponent (which is described in detail at http://camel.apache.org/file.html) takes the name test, used as a path to a directory, and each message will be stored there as a file. If we look at the directory listing now, we will see the following structure:

Funny-looking filenames are actually concatenated message IDs and machine names. Each file contains the message that we sent, as shown in the following output:

% cat test/ID-senmb-local-49350-1365634410538-0-1
This is a test message!
% cat test/ID-senmb-local-49350-1365634410538-0-3
This is another test message!                                                                  

Camel created those files and put the body of the message in them using default JVM encoding. This could be changed using parameters that could be passed in the message using the URI parameters notation. Among other things, we could control the name of the file created by changing the message header Exchange.FILE_NAME. One way to do it would be to write it in DSL describing the route, as shown in the following code snippet:

public void configure() throws Exception {
    from("stream:in")
        .setHeader(Exchange.FILE_NAME, constant("test.txt"))
        .to("file:test");
}

We will look at the DSL more thoroughly later in the book; but, for now, we set the name of the file as a constant string test.txt. If you run the program again, type in the message This is a test message, hit Enter, and then close the program by pressing Ctrl + C. You will see that we have a test.txt file in our test directory as shown in the following screenshot:

Its content is the message that you typed in:

% cat test/test.txt
This is a test message

Mocking is replacing an actual object/system with a dummy that will track how our code interacts with it. Developers usually set expectations and then assert that the expectations were met. In our case, instead of dealing with the System.in stream and filesystem, we could have created mock endpoints instead and then checked the logic of message routing only. We assume that components that come with Camel have been tested already; hence, we don't need to check that the message is created from the line entered into System.in or that the file is created in the filesystem. The only thing that we need to see is how our logic works.

Apache Camel comes loaded with code that helps us to do just that and much more. Let's rewrite our test a little bit, as shown in the following code:

package com.company;

import org.apache.camel.builder.AdviceWithRouteBuilder;
import org.apache.camel.builder.RouteBuilder;
import org.apache.camel.test.junit4.CamelTestSupport;
import org.junit.Before;
import org.junit.Test;

public class AppTest extends CamelTestSupport {
    @Override
    public String isMockEndpoints() {
        return "*";
    }
    @Test()
    public void testAppRoute() throws Exception {
        String testMessage = "This is a test message!";
        getMockEndpoint("mock:file:test").expectedBodiesReceived(testMessage);
        template.sendBody("direct:in", testMessage);
        assertMockEndpointsSatisfied();
    }
    @Before
    public void replaceStreamIn() throws Exception {
        context.getRouteDefinitions().get(0).adviceWith(context,
            new AdviceWithRouteBuilder() {
                @Override
                public void configure() throws Exception {
                    replaceFromWith("direct:in");
                }
            });
    }
   @Override
    protected RouteBuilder createRouteBuilder() throws Exception {
        return new App.AppRoute();
    }
}

After you run this test with mvn compile test, you should get a message about having successfully run the test.

Some of the code remained the same. So, let's go over the changes. We removed all the trickery by replacing System.in with the pipe stream. Plus, we don't fiddle with filesystem. Instead, in our unit test we used two techniques very useful for testing Camel application: mocking and advising.

Mocking in Camel creates a new endpoint for the actual endpoint. When the message is routed through the Camel application, it is first routed to the mock endpoint and it then goes to the actual endpoint. That is, the actual endpoint in the application is decorated with the mock endpoint, then we set expectations for this endpoint, and then, after tests are run, we assert that these expectations were met during the test.

MockEndpoint works as a wrapper around the endpoint. It has two groups of methods: expectedXXX to set an expectation for the endpoint and assertXXX to check or assert that expectations are being met. You can also call a method assertMockEndpointsSatisfied() of the class CamelTestSupport to check if all expectations on all mock endpoints were met.

Advising is changing the route, for instance, by replacing some endpoints.

The result is that we've tested only business logic: routing and mediating messages. Our case is very simple now, but later, once we add splitting, aggregating, enriching, conditions, transformation, and so on, it may become very complex.

You can read more about mocking (http://camel.apache.org/mock.html) and advising (http://camel.apache.org/advicewith.html) on the Camel website.

Now, let's quickly go over the code and explain what is what.

First of all, we extended the CamelSpringTestSupport class. It, in turn, extends the TestCase class from JUnit. We have used JUnit 3.8 here, which means all methods the names of which start with test will be run and then results would be provided in the Maven test report.

Second, we have implemented/overridden the method createApplicationContext in order to create Spring Application Context. It will be created and initialized along with the Camel context as it is set up in the config.xml file.

Third, we have overridden the method isMockEndpoints(). This method returns string for endpoints that should be mocked. If you put * in it, CamelSpringTestSupport will mock all the endpoints.

Fourth, we have implemented the testing of our routes using MockingEndpoint. The method isMockEndpoints tells the Camel testing facility which endpoints should be mocked (it is log in our case). New mocking endpoints are available under a new URI, which is the same as the original one appended to mock: scheme. We then set expectations, execute the code, and then check or assert that our expectations were true.

Apache Camel is an integration framework that might integrate some systems that might not be suitable for testing due to various reasons:

There are great frameworks out there that shine in their own rights, for example, jMock or EasyMock which work great with JUnit. If you want to get more information and use it in your application, check out the sites http://jmock.org/ and http://www.easymock.org/.

Upon executing our first step, we get a mock for the endpoint file:test and set the expectation in the body of the received message:

String testMessage = "This is a test message!";
getMockEndpoint("mock:file:test")
   .expectedBodiesReceived(testMessage) 

Then, we run a test. Send a message into the route using ProducerTemplate. Then we check whether all the expectations are met using the following method:

assertMockEndpointsSatisfied(); 

There could be more than one expectation set and checked in one test. Another approach for mocking and testing is to plug endpoints with the mock: scheme URI into the route and see what is going through them.

For more information go to http://camel.apache.org/mock.html.

Apache Camel allows us to to configure its context through the Spring configuration. Let's first make our AppRoute inner class public:

    public static class AppRoute extends RouteBuilder {
        @Override
        public void configure() throws Exception {
            from("stream:in")
                    .to("file:test");
        }
    }

Remove the added route builder from the main() method of the App class:

    public static void main(String[] args) throws Exception {
        Main m = new Main();
        m.run();
    }

Now we can use this class to instantiate a bean in the Spring configuration:

    <bean id="appRoute" class="com.company.App.AppRoute" />

After that, we could refer to this bean as our route builder from inside the Camel context configuration.

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

If you now run our Camel application, it still works as it used to. Now, we have the flexibility to configure our routes through the XML configuration instead of adding them manually in the code.

We don't even need to specify each class that extends RouteBuilder in the configuration. We can tell Camel to scan a package or packages for classes, which will then be added automatically:

    <camelContext xmlns="http://camel.apache.org/schema/spring">
        <packageScan>
            <package>com.company</package>
        </packageScan>
    </camelContext>

We can now remove the code for instantiation of the bean for our route:

<bean id="appRoute" class="com.company. App.AppRoute" />

It all works. If you run the application, it still keeps running, waiting for you to enter text and hit Enter, after which this text will be converted into a message and saved into a file inside the test directory.

Using packageScan allows you to exclude and include classes from being added to the Camel Context using matching patterns:

<camelContext xmlns="http://camel.apache.org/schema/spring">
    <packageScan>
        <package>com.company</package>
        <excludes>**.*Production*</excludes>
        <includes>**.*</includes>
    </packageScan>
</camelContext>

In this example, we would have included all classes extending RouteBuilder except those that have production in their name. Matching works as described in the following list:

Read more about configuring Camel context with Spring at http://camel.apache.org/spring.html.

We've already shown how we could test our Camel application. Integration with Spring Framework adds a few things to that.

If we want that Spring support from the unit test, we would have to add another dependency camel-test-spring to our POM file.

        <dependency>
            <groupId>org.apache.camel</groupId>
            <artifactId>camel-test-spring</artifactId>
            <version>${camel-version}</version>
        </dependency>

After that, we can use the class CamelSpringTestSupport as our test base:

package com.company;

import org.apache.camel.builder.AdviceWithRouteBuilder;
import org.apache.camel.test.junit4.CamelSpringTestSupport;
import org.junit.Before;
import org.junit.Test;
import org.springframework.context.support.AbstractApplicationContext;
import org.springframework.context.support.ClassPathXmlApplicationContext;

public class AppTest extends CamelSpringTestSupport {
    @Override
    public String isMockEndpoints() {
        return "*";
    }

    @Test()
    public void testAppRoute() throws Exception {
        String testMessage = "This is a test message!";
        getMockEndpoint("mock:file:test")
                .expectedBodiesReceived(testMessage);
        template.sendBody("direct:in", testMessage);
        assertMockEndpointsSatisfied();
    }

    @Before
    public void replaceStreamIn() throws Exception {
        context.getRouteDefinitions().get(0).adviceWith(context,
            new AdviceWithRouteBuilder() {
                @Override
                public void configure() throws Exception {
                    replaceFromWith("direct:in");
                }
            });
    }

    @Override
    protected AbstractApplicationContext createApplicationContext() {
        return new ClassPathXmlApplicationContext("META-INF/spring/config.xml");
    }
}

We just need to override the createApplicationContext()method returning application context. We need to make it return Spring ApplicationContext from our configuration file. Everything else in the unit test is the same as before and this test should run with the same results.

However, the main part is when we can use annotations so that we don't have to extend the class CamelSpringTestSupport (since we are using junit4, we had probably better use annotations anyway) in order to get full Camel Spring Test support.

package com.company;

import org.apache.camel.CamelContext;
import org.apache.camel.EndpointInject;
import org.apache.camel.builder.AdviceWithRouteBuilder;
import org.apache.camel.component.mock.MockEndpoint;
import org.apache.camel.test.junit4.CamelSpringJUnit4ClassRunner;
import org.apache.camel.test.spring.MockEndpoints;
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.test.context.ContextConfiguration;

@RunWith(CamelSpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = "classpath:META-INF/spring/config.xml")
@MockEndpoints("*")
public class AppTest {
    @Autowired
    CamelContext context;

    @EndpointInject(uri = "mock:file:test")
    MockEndpoint mock;

    @Test()
    public void testAppRoute() throws Exception {
        String testMessage = "This is a test message!";
        mock.expectedBodiesReceived(testMessage);
        context.createProducerTemplate()
            .sendBody("direct:in", testMessage);
        MockEndpoint.assertIsSatisfied(mock);
    }

    @Before
    public void replaceStreamIn() throws Exception {
        context.getRouteDefinitions().get(0).adviceWith(context,
            new AdviceWithRouteBuilder() {
                @Override
                public void configure() throws Exception {
                    replaceFromWith("direct:in");
                }
            });
    }
}

If you run the test and get an error like the one shown in the following screenshot:

You probably ran into at least one example when Maven transitive dependency resolution didn't work out. In this case, some classes call a non-existent method of another class that has been caused by poor dependency resolution between Spring modules. So, if you run the following command:

% mvn dependency:tree

You should see something like what is shown in the following screenshot:

As you can see, Maven figured out that camel-spring depends on spring-3.0.7, but camel-test-spring has spring-test-3.1.2 as a dependency. It's hard to say which module is the culprit. It is sort of a trial-and-error thing; in our case, explicitly adding a version of the spring-context module in our dependencies in the POM file helped:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <version>3.1.0.RELEASE</version>
</dependency>

After that, our unit test should run tip top.

As you can see, we somewhat shortened our unit test code plus made it a bit more flexible by dropping off the inheritance from the class CamelSpringTestSupport. We don't need to override the method isMockEndpoints() as we've used the annotation @MockEndpoints("*"), the value of which is the same as the pattern returned from isMockEndpoints(). There's also the annotation @MockEndpointsAndSkip that is used for the same purpose as the isMockEndpointsAndSkip() method override for CamelSpringTestSupport. CamelContext is injected by the Spring Framework using @Autowired. Earlier, we used the getMockEndpoint() method and now we use the @EndpointInject annotation with the URI of the mock endpoint to get the reference to the mock endpoint. The annotation @EndpointInject works for any endpoint, not only for mock ones. Another thing to note is that we don't have a template variable, so we need to create one context.createProducerTemplate() template variable. Also, we use static methods from the MockEndpoint class to make the assertion that the expectation MockEndpoint.assertIsSatisfied(mock) is met, but you could have used instance methods of the mock object.

You can read more detail regarding the use of Spring-aware testing of your Camel application at http://camel.apache.org/spring-testing.html.

Let's think about the routing of documents through our Camel application. Logically, we have two sources of documents: the inbound folder and approved message queue. Also, we have two destinations for documents: the needs approval queue and outbound folder.

Java DSL

We are going to use the main() method from the class org.apache.camel.spring.Main to start our application; we don't need to have a class with the static main() method and we will use the already existing App class to express our routes using, the so called, Java DSL.

Java DSL is a domain-specific language expressed in Java using a pattern called fluent interfaces. Domain-specific, in this case, means it provides all those verbs for route building: from, to, choice, when, otherwise, filter, and so on. In more detail, Java DSL is described at http://camel.apache.org/java-dsl.html.

We will make App extend a RouteBuilder and configure our routes inside the configure() method. Let's start with the first part; we take a document from the file and then see if it needs approval. Then, we send documents that need approval to the JMS queue APPROVAL. Documents that don't need approval are sent to the block that then transforms them into broker-specific formats:

@Override
public void configure() throws Exception {
    from("file:inbound")
        .choice()
            .when(header("NeedsApproval").isEqualTo(true))
            .to("jms:queue:APPROVAL")
            .otherwise().to("seda:transform");
}

This looks pretty simple. If you use an IDE like Eclipse when you code like the preceding one, it will show in the dropdown what you can use after you've typed ..This is the fluent interface design pattern at work. It is really easy to write these routes in the IDE as shown in the following screenshot:

Endpoints with a seda: URI scheme allow for asynchronous processing of the messages. Producer and consumer work in different threads and you may look at these endpoints as analogous to JMS or MQ queues being run on the JVM. You can read more about these types of endpoints at http://camel.apache.org/seda.html.

In order to work with JMS queues / topics from Camel, we would need to add camel-jms dependency to our POM file:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-jms</artifactId>
    <version>${camel-version}</version>
</dependency>

Testing the application

It is a good practice to make sure that the application works as expected. Let's change our existing tests to reflect the changes in the route.

We will create another Spring configuration that will be used only for tests. Create a file config-test.xml in the directory src/test/resources/META-INF/spring (if some directories are not there, just create them). The following screenshot shows the layout of our project directory:

Now, we add the following code to the config-test.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
    <import resource="classpath:META-INF/spring/config.xml"/>
    <bean id="jms" class="org.apache.camel.component.seda.SedaComponent" />
</beans>

First, we import the application Spring configuration. Then, we substitute the component handling JMS because in our unit test we will test only routing. We will substitute the JMS component with the SEDA component:

<bean id="jms" class="org.apache.camel.component.seda.SedaComponent" />

Camel has default mappings of the URI schemes to the components, but it also uses Spring beans' ID to run a search for a component handling URI scheme. In our case, we overrode the jms: scheme with the SEDA component for our unit tests, so instead of starting up the whole JMS infrastructure, we will use SEDA, which is actually a message queue on JVM.

One can use this method to define new URI schemes and use existing components to handle them.

Now, we will add the following code to the unit test class AppTest (we omit the import statements for brevity; the IDE should be able to resolve them):

@RunWith(CamelSpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = "classpath:META-INF/spring/config-test.xml")
@MockEndpoints("*")
public class AppTest {
    @Autowired
    CamelContext context;

    @EndpointInject(uri = "mock:jms:queue:APPROVAL")
    MockEndpoint mockNeedsApproval;

    @EndpointInject(uri = "mock:seda:transform")
    MockEndpoint mockTransform;

    @Produce
    ProducerTemplate template;

    @DirtiesContext
    @Test
    public void testNeedsApprovalMessage() throws Exception {
        mockNeedsApproval.expectedMessageCount(1);
        mockTransform.expectedMessageCount(0);
        template.sendBodyAndHeader("direct:start", "message", "NeedsApproval", true);
        mockNeedsApproval.assertIsSatisfied();
        mockTransform.assertIsSatisfied();
    }

    @DirtiesContext
    @Test
    public void testDirectTransformMessage() throws Exception {
        mockNeedsApproval.expectedMessageCount(0);
        mockTransform.expectedMessageCount(1);
        context.createProducerTemplate()
                .sendBodyAndHeader("direct:start", "message", "NeedsApproval", false);
        mockNeedsApproval.assertIsSatisfied();
        mockTransform.assertIsSatisfied();
    }

    @Before
    public void replaceFileInbound() throws Exception {
        context.getRouteDefinitions().get(0).adviceWith(context, new AdviceWithRouteBuilder() {
            @Override
            public void configure() throws Exception {
                replaceFromWith("direct:start");
            }
        });
    }
}

A few things to note: we use CamelSpringJUnit4ClassRunner to run our test and Spring context configuration from our config-test.xml file, and we create mock endpoints for all endpoints in the Camel context. We save some space using Spring and Camel to initialize our variables:

@Autowired
CamelContext context;

@EndpointInject(uri = "mock:jms:queue:APPROVAL")
MockEndpoint mockNeedsApproval;

@EndpointInject(uri = "mock:seda:transform")
MockEndpoint mockTransform;

@Produce
ProducerTemplate template;

The Camel context will be injected by Spring and then the Camel Spring integration code will initialize our mock endpoints (as you can see, we use mock endpoints for the endpoints in the route by prepending their URI with mock:) and create ProducerTemplate that we will use to produce messages in the tests.

We marked every test with @DirtiesContext, which would make the test runner reload the context before each test. That's needed because mock endpoints will keep the messages that have been sent to them and thus may either fail the tests that should have been successful or make the failing tests succeed.

Also, before each test we use the replaceFileInbound method to replace our file:inbound endpoint using AdviseWith with direct:start endpoint as shown in the following code snippet:

@Before
public void replaceFileInbound() throws Exception {
    ....
}

We did that in order to run only routing logic in our unit tests and not to deal with external systems such as JMS or a filesystem.

The rest are tests methods, such as testNeedsApprovalMessage() and testDirectTransformMessage(). They follow a similar structure. The latter one tests the message with the header NeedsApproval set to false; the message should be routed to the Transform block and the former one's header NeedsApproval set to true. In this case, the message should be routed to the approval JMS queue. We set expectations for the mock endpoints (for approval queue and for transformation), send the message with the header set, and check that expectations for the mock endpoint were met.

As always, you can run this test using the following command line:

% mvn compile test

All the tests should succeed.

For testing the system as a whole, we can use an integration testing builder, for instance, NotifyBuilder. Read more at http://camel.apache.org/notifybuilder.html.

@Override
public void configure() throws Exception {
}

<camel:camelContext xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="file:inbound"/>
        <choice>
            <when>
                <header>NeedsApproval</header>
                <to uri="jms:queue:APPROVAL"/>
            </when>
            <otherwise>
                <to uri="seda:transform"></to>
            </otherwise>
        </choice>
    </route>
</camel:camelContext>

% mvn compile test

Spring Framework allows for greater modularity in our applications. As you have seen it before, we have split our Spring configuration into two parts: one for application and one for testing.

Spring also allows us to substitute the component handling the jms: URI scheme to SedaComponent, so we can easily do unit testing without getting involved in dealing with JMS infrastructure.

Another thing that is particularly useful in big applications is dependency injection. We can specify how to create plain old java objects (POJOs), also called beans, and make Spring Framework resolve dependencies between them and apply enterprise services, for example, make methods of those beans execute in transaction or accessible via JMX API or available for remoting, and so on. You can find out more about it by reading the documentation for the Spring Framework. Here, we are going to provide a few examples of using beans in a Camel application.

@Override
public void configure() throws Exception {
    from("file:inbound")
            .choice()
                .when(header("NeedsApproval").isEqualTo(true)).to("jms:queue:APPROVAL")
                .otherwise().to("seda:transform")
            .endChoice();
}

<camel:camelContext xmlns="http://camel.apache.org/schema/spring">
    <packageScan>
        <package>com.company</package>
    </packageScan>
</camel:camelContext>

% mvn compile test

<?xml version="1.0" encoding="iso-8859-1"?>
<BUNDLE>
  <CUSDEC>
    <DOCUMENT_NAME>914</DOCUMENT_NAME>
    <DOCUMENT_ID>SIRF40083214658</DOCUMENT_ID>
    <TOT_NET_WEIGHT>2.7</TOT_NET_WEIGHT>
    <TOT_NET_WEIGHT_UOM>KGM</TOT_NET_WEIGHT_UOM>
    <TRANS_DOC_NUM_AWB>M1052_002</TRANS_DOC_NUM_AWB>
    <TRANS_DOC_NUM_HWB>H1052_002</TRANS_DOC_NUM_HWB>
    <CARRIER_CODE>172</CARRIER_CODE>
    <TOTAL_NET_AMOUNT>2480.0</TOTAL_NET_AMOUNT>
    <TOTAL_NET_AMOUNT_CUR>EUR</TOTAL_NET_AMOUNT_CUR>
    <LINES>
      <LINE>
        <LINE_NUMBER>000001</LINE_NUMBER>
        <PRODUCT_NUMBER>6DL31008AC03</PRODUCT_NUMBER>
        <LIN_QTY>1</LIN_QTY>
        <LIN_QTY_UOM>PCE</LIN_QTY_UOM>
        <LIN_NET_WEIGHT>2.7</LIN_NET_WEIGHT>
        <LIN_NET_WEIGHT_UOM>KGM</LIN_NET_WEIGHT_UOM>
        <LIN_ITEM_NET_AMOUNT>2480.0</LIN_ITEM_NET_AMOUNT>
        <LIN_ITEM_NET_AMOUNT_CUR>EUR</LIN_ITEM_NET_AMOUNT_CUR>
        <COUNTRY_ORIGIN_CODE>DE</COUNTRY_ORIGIN_CODE>
        <DESCRIPTION>NY cou =OK ADDFEM WITH FEF POCO</DESCRIPTION>
      </LINE>
    </LINES>
  </CUSDEC>
</BUNDLE>

package com.company;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class NetValueBean {
    protected double approvalThreshold;
    // regex to get total net amount from the document
    protected static final Pattern totalNetAmountRE = Pattern.compile("<TOTAL_NET_AMOUNT>(.*)</TOTAL_NET_AMOUNT>");

    public boolean checkNetValueForApproval(String document) {
        Matcher m = totalNetAmountRE.matcher(document);
        if (m.find()) {
            String amount = m.group(1);
            return Double.parseDouble(amount) > approvalThreshold;
        } else {
            return false;
        }
    }

    public double getApprovalThreshold() {
        return approvalThreshold;
    }

    public void setApprovalThreshold(double approvalThreshold) {
        this.approvalThreshold = approvalThreshold;
    }
}

package com.company;
import org.junit.Assert;
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;

public class NetValueBeanTest {
    private NetValueBean bean;
    private String testDocument = "<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>\n" +
            "<BUNDLE>\n" +
            "  <CUSDEC>\n" +
            ....
            "  </CUSDEC>\n" +
            "</BUNDLE>\n";

    @Test
    public void testHigherAmount(){
        Assert.assertTrue(bean.checkNetValueForApproval( testDocument ));
    }

    @Test
    public void testLowerAmount(){
        bean.setApprovalThreshold(3000);
        Assert.assertFalse(bean.checkNetValueForApproval( testDocument ));
    }

    @Before
    public void createBean(){
        bean = new NetValueBean();
        bean.setApprovalThreshold(100);
    }
}

<bean id="netValueBean" class="com.company.NetValueBean">
    <property name="approvalThreshold" value="3000" />
</bean>

@Override
public void configure() throws Exception {
    from("file:inbound")
            .setHeader("NeedsApproval", method( "netValueBean" , "checkNetValueForApproval"))
            .choice()
                .when(header("NeedsApproval").isEqualTo(true))
                .to("jms:queue:APPROVAL")
                .otherwise().to("seda:transform");
}

<TOTAL_NET_AMOUNT>3480.0</TOTAL_NET_AMOUNT>

public class AppTest {
    @Autowired
    CamelContext context;

    @EndpointInject(uri = "mock:jms:queue:APPROVAL")
    MockEndpoint mockNeedsApproval;

    @EndpointInject(uri = "mock:seda:transform")
    MockEndpoint mockTransform;

    @Test
    public void testNeedsApprovalMessage() throws Exception {
        mockNeedsApproval.expectedMessageCount(1);
        mockTransform.expectedMessageCount(0);
        // copy file cusdec2.xml
        FileCopyUtils.copy(new File("src/test/data/cusdec2.xml"), new File("inbound/cusdec2.xml"));
        mockNeedsApproval.assertIsSatisfied();
        mockTransform.assertIsSatisfied();
    }

    @Test
    public void testDirectTransformMessage() throws Exception {
        mockNeedsApproval.expectedMessageCount(0);
        mockTransform.expectedMessageCount(1);
        // copy file cusdec1.xml
        FileCopyUtils.copy(new File("src/test/data/cusdec1.xml"), new File("inbound/cusdec1.xml"));
        mockNeedsApproval.assertIsSatisfied();
        mockTransform.assertIsSatisfied();
    }

    @Before
    public void setUp(){
        MockEndpoint.resetMocks(context);
    }

    @BeforeClass
    public static void clearInbound() throws IOException {
        FileUtils.deleteDirectory(new File("inbound"));
        FileUtils.forceMkdir(new File("inbound"));
    }
}

FileCopyUtils.copy(new File("src/test/data/cusdec1.xml"), new File("inbound/cusdec1.xml"));

@Before
public void setUp(){
    MockEndpoint.resetMocks(context);
}

@BeforeClass
public static void clearInbound() throws IOException {
    FileUtils.deleteDirectory(new File("inbound"));
    FileUtils.forceMkdir(new File("inbound"));
}

% mvn compile test

Apache Camel supports multiple data format converters between different text, binary, Java objects, and so on. Read more at http://camel.apache.org/data-format.html. As an example, we will un-marshal (that is convert from serialized form into Java object) our Cusdec XML files into objects using JAXB (read more about JAXB at https://jaxb.java.net/), which is a standard (such as JSR-222) in the Java world for object-XML serialization/de-serialization.

First, let's create our model. We will create a package com.company.cusdec and have three classes representing different parts of the Cusdec document: CusdecBundle as a root element, CusdecDocument as a CUSDEC element, and CusdecLine that represents the LINE element inside LINES in CUSDEC.

The layout of the classes in the IDE is as shown in the following screenshot:

Add a dependency to the POM file to use JAXB:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-jaxb</artifactId>
    <version>${camel-version}</version>
</dependency>

Now, let's add the code for the class CusdecBundle:

package com.company.cusdec;
import javax.xml.bind.annotation.*;
import java.util.ArrayList;

@XmlRootElement(name="BUNDLE")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name="BUNDLE")
public class CusdecBundle {
    @XmlElement(name="CUSDEC")
    protected ArrayList<CusdecDocument> documents = new ArrayList<CusdecDocument>();

    public ArrayList<CusdecDocument> getDocuments() {
        return documents;
    }

    public void setDocuments(ArrayList<CusdecDocument> documents) {
        this.documents = documents;
    }
}

Let's also add a code for the class CusdecDocument (we skipped getters and setters for brevity; they can be automatically generated by the IDE):

package com.company.cusdec;

import javax.xml.bind.annotation.*;
import java.util.ArrayList;

@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name="CUSDEC")
public class CusdecDocument {
    @XmlElement(name="DOCUMENT_NAME")
    protected String name;
    @XmlElement(name="DOCUMENT_ID")
    protected String id;
    @XmlElement(name="TOT_NET_WEIGHT")
    protected Float totalNetWeight;
    @XmlElement(name="TOT_NET_WEIGHT_UOM")
    protected String totalNetWeightUom;
    @XmlElement(name="TRANS_DOC_NUM_AWB")
    protected String airWaybill;
    @XmlElement(name="TRANS_DOC_NUM_HWB")
    protected String houseAirWaybill;
    @XmlElement(name="CARRIER_CODE")
    protected String carrierCode;
    @XmlElement(name="TOTAL_NET_AMOUNT")
    protected Double totalNetAmount;
    @XmlElement(name="TOTAL_NET_AMOUNT_CUR")
    protected String totalNetAmountCurrency;
    @XmlElementWrapper(name = "LINES")
    @XmlElement(name = "LINE")
    protected ArrayList<CusdecLine> lines = new ArrayList<CusdecLine>();

    // code for getters and setters follows
    ...
}

Add a code for the class CusdecLine (again, we will skip getters and setters):

package com.company.cusdec;

import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlType;
import java.util.Currency;

@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "LINE")
public class CusdecLine {
    @XmlElement(name="LINE_NUMBER")
    protected String number;
    @XmlElement(name="PRODUCT_NUMBER")
    protected String productNumber;
    @XmlElement(name="LIN_QTY")
    protected int quantity;
    @XmlElement(name="LIN_QTY_UOM")
    protected String quantityUom;
    @XmlElement(name="LIN_NET_WEIGHT")
    protected Float netWeight;
    @XmlElement(name="LIN_NET_WEIGHT_UOM")
    protected String netWeightUom;
    @XmlElement(name="LIN_ITEM_NET_AMOUNT")
    protected Float netAmount;
    @XmlElement(name="LIN_ITEM_NET_AMOUNT_CUR")
    protected String netAmountCurrency;
    @XmlElement(name="COUNTRY_ORIGIN_CODE")
    protected String country;
    @XmlElement(name="DESCRIPTION")
    protected String description;

    // code for getters and setters follows
    ...
}

Now, let's write our route in the App class:

@Override
public void configure() throws Exception {
    DataFormat jaxb = new JaxbDataFormat(JAXBContext.newInstance(CusdecBundle.class));

    from("file:inbound")
            .unmarshal(jaxb)
            .setHeader("NeedsApproval", method( "netValueBean" , "checkNetValueForApproval"))
            .choice()
                .when(header("NeedsApproval").isEqualTo(true))
                .to("jms:queue:APPROVAL")
                .otherwise().to("seda:transform");
}

The key lines in our route are unmarshal(jaxb) where we un-marshal (or de-serialize) the object from the XML using a DataFormat instance.

In real life, it may look as follows:

@Override
public void configure() throws Exception {
    from("file:inbound")
            .unmarshal().jaxb("com.company.cusdec")
            .setHeader("NeedsApproval", method( "netValueBean" , "checkNetValueForApproval"))
            .choice()
                .when(header("NeedsApproval").isEqualTo(true))
                   .to("jms:queue:APPROVAL")
                .otherwise().to("seda:transform");
}

In our route, we convert XML into a CusdecBundle object, which we then pass to the bean to set the header. Let's rewrite our NetValueBean so it works with CusdecBundle instead of String:

package com.company;

import com.company.cusdec.CusdecBundle;

public class NetValueBean {
    protected double approvalThreshold;

    /**
     * Checks if total net amount is greater than approvalThreshold
     *
     * @return true if total net amount is greater than approvalThreshold, false otherwise
     */
    public boolean checkNetValueForApproval(CusdecBundle bundle) {
        return bundle.getDocuments().get(0).getTotalNetAmount() > approvalThreshold;
    }

    public double getApprovalThreshold() {
        return approvalThreshold;
    }

    public void setApprovalThreshold(double approvalThreshold) {
        this.approvalThreshold = approvalThreshold;
    }
}

For the unit test, we will change our NetValueBeanTest class into NetValueBeanSpringTest class:

package com.company;

import com.company.cusdec.CusdecBundle;
import org.apache.camel.test.junit4.CamelSpringJUnit4ClassRunner;
import org.junit.Assert;
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.test.context.ContextConfiguration;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;
import javax.xml.bind.Unmarshaller;
import java.io.FileInputStream;
import java.io.IOException;

@RunWith(CamelSpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = "classpath:META-INF/spring/config-test.xml")
public class NetValueBeanSpringTest {
    @Autowired
    NetValueBean bean;
    Unmarshaller u;

    @Test
    public void testFileParsedLower()
            throws IOException, JAXBException {
        CusdecBundle bundle = (CusdecBundle)u.unmarshal(
            new FileInputStream("src/test/data/cusdec1.xml"));
        Assert.assertFalse(bean.checkNetValueForApproval(bundle));
    }

    @Test
    public void testFileParsedHigher()
            throws IOException, JAXBException {
        CusdecBundle bundle = (CusdecBundle)u.unmarshal(
            new FileInputStream("src/test/data/cusdec2.xml"));
        Assert.assertTrue(bean.checkNetValueForApproval(bundle));
    }

    @Before
    public void setUp () throws JAXBException {
        JAXBContext context =
            JAXBContext.newInstance(CusdecBundle.class);
        u = context.createUnmarshaller();
    }
}

Before each test, we will create JAXBContext and get an unmarshaller that will de-serialize the XML. The NetValueBean bean is automatically retrieved from the Spring ApplicationCcontext container. Then, during the test we just get a CusdecBundle object de-serialized by the unmarshaller u and check that the bean's method returns a correct result having been given the object.

Unit tests for the route in class AppTest stay the same. You can now check that everything works by running the following command:

% mvn compile test

It should display that all tests ran successfully. If there's a problem, try to delete the directory target first because it might have old compiled class files.

package com.company;
import com.company.cusdec.CusdecBundle;
import org.apache.camel.Converter;
import javax.xml.bind.JAXBContext;
import javax.xml.bind.JAXBException;
import javax.xml.bind.Unmarshaller;
import java.io.File;

@Converter
public class CusdecConverter {
    private static Unmarshaller unmarshaller;
    @Converter
    public static CusdecBundle toCusdecBundle(File cusdecFile)
                throws JAXBException {
        if (unmarshaller == null) {
            JAXBContext jaxb =JAXBContext.newInstance(CusdecBundle.class);
            unmarshaller = jaxb.createUnmarshaller();
        }
        return (CusdecBundle)unmarshaller.unmarshal(cusdecFile);
    }
}

@Override
public void configure() throws Exception {
    from("file:inbound")
      .setHeader("NeedsApproval",
                method("netValueBean", "checkNetValueForApproval"))
            .choice()
            .when(header("NeedsApproval").isEqualTo(true))
            .to("jms:queue:APPROVAL")
            .otherwise().to("seda:transform");
}

<dependency>
    <groupId>javax.xml</groupId>
    <artifactId>jaxb-api</artifactId>
    <version>2.1</version>
</dependency>

xlst:nameOfTheTransformation.xsl

<xsl:stylesheet version = '1.0' xmlns:xsl='http://www.w3.org/1999/XSL/Transform'>
    <xsl:output indent="yes" encoding="iso-8859-1"/>
    <xsl:variable name="lc">abcdefghijklmnopqrstuvwxyz</xsl:variable>
    <xsl:variable name="uc">ABCDEFGHIJKLMNOPQRSTUVWXYZ</xsl:variable>

    <xsl:template match="node()|@*">
        <xsl:copy>
            <xsl:apply-templates select="node()|@*"/>
        </xsl:copy>
    </xsl:template>

    <xsl:template match="*">
        <xsl:element name="{translate(local-name(), $uc, $lc)}">
            <xsl:apply-templates/>
        </xsl:element>
    </xsl:template>
</xsl:stylesheet>

@Override
public void configure() throws Exception {
    DataFormat jaxb = new JaxbDataFormat(JAXBContext.newInstance(CusdecBundle.class));

    from("file:inbound")
            .unmarshal(jaxb)
            .setHeader("NeedsApproval",
            method( "netValueBean" , "checkNetValueForApproval"))
            .choice()
                .when(header("NeedsApproval").isEqualTo(true))
                   .to("jms:queue:APPROVAL")
                .otherwise().to("seda:transform");

    from("seda:transform")
            .marshal(jaxb)
            .to("xslt:classpath:com/company/cusdecToDHL.xsl")
            .to("file:outbound");
}

<?xml version="1.0" encoding="iso-8859-1"?>
<bundle>
    <cusdec>
        <document_name>914</document_name>
        <document_id>SIRF40083214658</document_id>
        <tot_net_weight>2.7</tot_net_weight>
        <tot_net_weight_uom>KGM</tot_net_weight_uom>
        <trans_doc_num_awb>M1052_002</trans_doc_num_awb>
        <trans_doc_num_hwb>H1052_002</trans_doc_num_hwb>
        <carrier_code>172</carrier_code>
        <total_net_amount>2480.0</total_net_amount>
        <total_net_amount_cur>EUR</total_net_amount_cur>
        <lines>
            <line>
                <line_number>000001</line_number>
                <product_number>6DL31008AC03</product_number>
                <lin_qty>1</lin_qty>
                <lin_qty_uom>PCE</lin_qty_uom>
                <lin_net_weight>2.7</lin_net_weight>
                <lin_net_weight_uom>KGM</lin_net_weight_uom>
                <lin_item_net_amount>2480.0</lin_item_net_amount>
                <lin_item_net_amount_cur>EUR</lin_item_net_amount_cur>
                <country_origin_code>DE</country_origin_code>
                <description>NY cou =OK ADDFEM WITH FEF POCO</description>
            </line>
        </lines>
    </cusdec>
</bundle>