Apache Camel: Integration Nirvana

<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-2.5.xsd
       http://activemq.apache.org/camel/schema/spring
       http://activemq.apache.org/camel/schema/spring/camel-spring.xsd
       http://activemq.apache.org/schema/core
       http://activemq.apache.org/schema/core/activemq-core.xsd">

  <broker xmlns="http://activemq.apache.org/schema/core" useJmx="false" persistent="false">
    <transportConnectors>
      <transportConnector uri="tcp://localhost:61616" />
    </transportConnectors>
  </broker>

  <bean id="jms" class="org.apache.activemq.camel.component.ActiveMQComponent">
    <property name="brokerURL" value="tcp://localhost:61616"/>
  </bean>

  <bean id="normalizer" class="org.fusesource.camel.OrderNormalizer"/>
  <bean id="orderHelper" class="org.fusesource.camel.OrderHelper"/>
 
  <camelContext xmlns="http://activemq.apache.org/camel/schema/spring">
    <package>org.fusesource.camel</package>
  </camelContext>

</beans>

The real meat of the Camel implementation lies in the OrderRouter class (shown in Listing 3). This class extends RouteBuilder, so it will be automatically picked up and loaded by Camel's runtime.

Looking back at Figure 2, we need to receive orders from an FTP (substituted with File) and HTTP endpoint, formatted as shown in Listing 4. In the DSL we can specify these incoming endpoints with two from elements. Both from elements are connected to a to("jms:incomingOrderQueue") element, which will send the messages to a queue on the ActiveMQ broker.



Listing 3: Route definitions for the example. The routing rules are specified using a fluent API, referred to as Camel's DSL.

public class OrderRouter extends RouteBuilder {

    @Override
    public void configure() throws Exception {
        JaxbDataFormat jaxb = new JaxbDataFormat("org.fusesource.camel");
        
        // Receive orders from two endpoints
        from("file:src/data?noop=true").to("jms:incomingOrderQueue");
        from("jetty:http://localhost:8888/placeorder")
          .inOnly().to("jms:incomingOrderQueue")
          .transform().constant("OK");

        // Do the normalization
        from("jms:incomingOrderQueue")
         .convertBodyTo(String.class)
         .choice()
           .when().method("orderHelper", "isXml")
             .unmarshal(jaxb)
             .to("jms:orderQueue")
           .when().method("orderHelper", "isCsv")
             .unmarshal().csv()         
             .to("bean:normalizer")
             .to("jms:orderQueue");
    }

}

In the case of the HTTP endpoint, there are a couple of extra things to mention. First off the HTTP client will be expecting a response from the application so we have to handle that. In Camel, we have full control over what the client gets back from the HTTP endpoint. Each response is determined by the last method in our current route definition (each Java statement is a route definition). In our case we use the transform method to set the response to the constant string "OK". Since we handle the response ourselves, we don’t want any response to come from the JMS incomingOrderQueue. To send to this queue in a fire-and-forget fashion we add the inOnly modifier.  

It is important to note at this point that when writing Camel DSL in a modern Java IDE, selection of the next processing step is easy because of auto complete. The auto complete feature basically gives you a list of processors (i.e. EIPs) to choose from at any point in your route. Since fluent APIs chain methods together, the only method you need to remember is the from; all other methods are shown via auto complete.



Listing 4: Incoming message formats; XML on top, CSV below.

<?xml version="1.0" encoding="UTF-8"?>
<order name="motor" amount="1"/>

"name", "amount"
"brake pad", "2"

The next section of DSL in Listing 3 specifies the Normalizer, complete with Content-Based Router and two Message Translators. First we specify that we want to consume messages from the incomingOrderQueue on the ActiveMQ broker. The content based routing of the messages is done with the choice and when methods. In our case, we want to send CSV messages to one Message Translator and XML messages to another. To check what type of message we have we will be using a simple Java bean shown in Listing 5. Of course, this is demonstration code only; for production cases you would want to add more thorough checking of content types.

Listing 5: Java bean that contains helper methods to be used in the DSL.

public class OrderHelper {
    public boolean isCsv(String body) {
        return !body.contains("<?xml");
    }
    
    public boolean isXml(String body) {
        return body.contains("<?xml");
    }
}

If the message has XML content, we use the JAXB data format to unmarshal the XML payload into an Order object. As shown in Listing 6, the Order object has JAXB annotations to describe the mapping to XML. You of course don't need to use JAXB here; it just makes things very easy as you don't have to do any nasty XML parsing by hand.

Listing 6: The Order domain class with JAXB annotations for easy mapping to and from XML.

@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class Order implements Serializable {
    @XmlAttribute
    private String name;
    @XmlAttribute
    private int amount;
    
    public Order() {
    }
    
    public Order(String name, int amount) {
        this.name = name;
        this.amount = amount;
    }
    
    @Override
    public String toString() {
        return "Order[" + name + " , " + amount + "]";
    }
}

For the transformation from CSV to Order object, we don't have a nice JAXB analogue. We do have support in Camel for unmarhsaling CSV content into a List though. We use this in combination with a custom bean to do the complete transformation. The OrderNormalizer bean shown in Listing 7 takes the List of Lists created by the CSV unmarshaler and creates a new Order object from it.

Listing 7: Java bean that takes the CSV data and creates a new Order domain object from it.

public class OrderNormalizer {
    public Order fromCsvToOrder(List<List<String>> body) {
        List<String> orderHeaders = body.get(0);
        List<String> orderValues = body.get(1);
        return new Order(orderValues.get(0), Integer.parseInt(orderValues.get(1)));
    }
}

At this point, successfully normalized messages are sent to the orderQueue for processing by some other application at the Rider Auto Parts business.

Conclusion

In this article I've shown two common problems that an integration developer may face: dealing with the specifics of applications and transports, and coming up with good solutions to integration problems. The Apache Camel project provides a nice answer to both of these problems. As the example has shown, solving integration problems with Camel is straight forward and results in relatively concise code. In my opinion it is the closest thing to integration nirvana that we have today.

1. Apache Camel – http://camel.apache.org
2. FUSE Mediation Router (based on Apache Camel) – http://fusesource.com/products/enterprise-camel
3. Enterprise Integration Patterns – http://www.enterpriseintegrationpatterns.com
4. Jon’s Blog – http://janstey.blogspot.com
5. Camel in Action book - http://www.manning.com/ibsen
6. Article source code - http://repo.fusesource.com/maven2/org/fusesource/examples/rider-auto-example/1.0/rider-auto-example-1.0.zip

Jonathan Anstey is a senior engineer working for Progress Software Corporation specializing in the enterprise integration space. Jon focuses mostly on Apache Camel and its Progress endorsed likeness, FUSE Mediation Router. He also works on the Apache ActiveMQ and Apache ServiceMix projects