Getting started with Apache Camel with Java

Trying out Camel with few Groovy lines is one thing, but
getting a full scale project in Java is another matter. Today, I will show you how to get things started on Apache Camel with
Maven based project. You may also use the provided camel-demo as project template to jump start your own Apache Camel
project. You would just need to rename the Java package and rename the pom's group and artifact id's to match your need.

Preparing a Maven based project with Camel dependencies

Unzip the camel-demo project source, and you will see the basic directory layout.

camel-demo
+- bin
+- config
+- data
+- src
+- pom.xml
+- README.txt

What makes this demo a Camel based project is just the declaration in pom.xml. Let's take a look the file and its dependencies.

This pom.xml decalares a Java based application and it will produce jar. It requires minimal of JDK 6 or higher. Besides the typical junit and hamcrest for unit testing, I also added slf4j for logging. I have added couple Apache's commons-lang/io to the project as well. I think these are basic settings that any Java based application should use them.

The maven-assembly-plugin I have declared is only for this demo packging purpose, and you may change or remove to suite your own project need.

For Camel dependencies, you would need minimal camel-core for routes building. And then you can add any additional components you plan to use in your project. I have added the following for building typical message based application development:

The camel-spring - we want to have option to declare Camel routes in xml files as configuration. See camel-demo/config directory for samples.

The camel-jackson - we want to process messaging data in our application as JSON format.

The camel-groovy - [optional] we want to be able to add dynamic scripting to route, even inside the xml config. This is great for debug and POC.

Note that since we use multiple camel components dependencies, I choose to set a Maven property ${camel.version} so that when we upgrade Camel,
it's easier to maintain the pom.xml file in one place.

You should able to cd into the project directory and run mvn compile to verify that the project. It should compile without error.

Improving startup of routes with a CamelRunner

With the project pom.xml file ready, you can start creating Camel routes to handle your own business logics. Before we get too excited, let's try out
a simple HelloRoute to see how it works and how we can run it first. Here is the route defnition code in src/main/java/deng/cameldemo/HelloRoute.java.

Take a test ride with the Camel

To see above in action, we need to add it into a CamelContext and start the context. For Java standalone program, we would write this setup code
in a Main class. The Camel actually comes with a org.apache.camel.main.MainSupport abstract class that you may use to extend your own Main.
However, I think it would be even nicer if Camel would provide a CamelRunner that can run like this.

$ java CamelRunner deng.cameldemo.HelloRoute

Such CamelRunner would be very user friendly and re-usable to have, so that's what I did. I wrote one like this:

You will see that the program will load the HelloRoute in a DefaultCamelContext and start it as a server. The HelloRoute itself will
generate a 3 seconds timer message and send it to a logger, which should be printing onto your console screen. This will continue forever
until you hit CTRL+C to end it.

NOTE: You only have to invoke mvn package command once, so that it will package up all the dependencies jars in order for run-java to auto-detect
them. If you are not going to use maven-assembly-plugin during package phase, then use mvn dependency:copy-dependencies command
explicitly will work fine as well.

Take a test ride with the Camel, Part 2: running Camel with Spring xml configuration

The HelloRoute example above would simply provide route definition that formed by using component URI's. It will be nice if
we can configure the route in a declarative manner so that we may change the route without re-compile a class file. This will be very handy especially
if you are not familiar with each component's options and want to explore and try things out. Well, that's what the camel-spring is for. Beside
giving you an option to load route in xml config file, it also provides a very flexible way to register custom services/processors bean in the Spring
IoC container.

If you are a keen reader, you will notice in the CamelRunner code above that it has an extra runWithSpringConfig part. So the CamelRunner
can actually bootstrap any Spring xml file and start a context as a server. You may use it like this:

This remove the need to compile/re-compile HelloRoute to define the Camel route to run.

Building message based application using Camel

To present you with a more practical demo, I would show you further on how to setup Camel to process message based application. In many IT
shops, it's common that you would have a server to take message data as input and process them. A practical use case is to take any JSON
formated message and transform it into object and process it. To do this in Camel, what you want to build is a route that will take
input messages from a TCP port, and then process it in a pipeflow with any business logic you may have. You will run the route as a server,
and then client may use any mean to submit the message to the TCP port. Client may even be another thin Camel client app to submit data as well.
Let me show you how to get started.

Writing the server side code with Camel route

The server side would need a route to listen from a TCP port, and this is provided by camel-mina component. The first step is you need a route.

Voila! The server is up and waiting for your users to send messages through port 12345. Not too bad for few lines of code.

Writing the client side code with Camel ProducerTemplate

Since our server expose a TCP port and take in any text content message, you can create any client that's capable writing to a TCP socket. In here,
I will show you how to use Camel to write a thin client.

Now let us improve the above xml to further process the JSON message data. We will like to transform the plain text to a Java object then process
by a custom bean. To do that, we first would need to add unmarshal component to the route. This is where the camel-jackson comes into play.
In our demo, the unmarshalling step would convert the JSON text into a java.util.Map and then pass it to a processor bean named myMsgProcessor.
Let's create a new xml file named config/tcpmsgserver-json-spring.xml as follow.

The myMsgProcessor is an Spring bean that we provide custom logic code to process the data. At this point we have a full Java object
to manipulate. The content of the processor can be any POJO with the method name specified in the URI. Here is an example one:

Pay attention that Camel will auto convert the data format in your route! Our client only sends the plain text as JSON format, but when
server receives it, it unmarshals it using Jackson library, and then converts it into a java Map object. It then passes the map object into our
processor bean. Also, in this demo, I choose to use a generic java.util.Map as processor method argument (which is output of the JSON unmarshal), but
you can easily define your own business data type, such as MyCustomerData. This reveals the power of Camel, since you don't need to push the message
in your flow, but only worry about writing your "processor" as a POJO. The Camel will "glue" components together to form a route and carry the message data through the pipeline flow.

On the same token, when you write your business logic in one or more processors, it's a good idea that you limit your POJO logic to be as small
unit as possible. When you do this, then you can maximize the reusability of the processors. The bigger POJO you make, with many business logics mixed in, it will also make it
difficult to test. So I recommend you when developing these processor beans, try to think them as LEGO pieces -- small POJO. You want to let Camel define the route and glue the LEGO
pieces togther. Once you get into this habit of thiking, then you can use Camel in a more effectively way to solve many of your domain problems.

Well, that's all for today folks. I hope you enjoyed the Camel ride. Happy programming!