Camel Step-by-Step

Tom Donohue
Table of Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  1
Introduction to this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  2
Getting ready . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3
Section I: The basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
Introducing Apache Camel . . . . . . . . . . . . . . . . . . . . . . . . . .  4
Getting on the Camel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  8
What does a Route actually look like? . . . . . . . . . . . . . . . .  12
Messages in Camel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  14
Your first Camel project . . . . . . . . . . . . . . . . . . . . . . . . . . .  16
Preface
Hey, hello, hi! Thanks very much for downloading this book.

When I first discovered Apache Camel, I was working on a

project for a finance company in London. The company was
using some integration software called Talend ESB, which
included Apache Camel as one of the supporting components.

This was my first encounter with Camel, and I remember being

very bewildered about all the terms, and how exactly to
develop Camel applications.

I came from a background as an Oracle developer (SOA Suite

and Oracle Service Bus). These products depended on point-
and-click configuration and flaky IDEs; and the source code was
nowhere to be seen. Yuck! Camel was like a breath of fresh air!

I really liked Camel for its simplicity, and that it’s pure Java
under the hood. Easy to work with and maintain.

So, I started to write some articles on Camel (the ones you now
see on cleverbuilder.com) to share common tasks that you
might want to do in Camel, or explain some core concepts.

Those articles have grown in popularity, and so has Apache

Camel. There are many new developers learning Camel every
day, so you’re in very good company.

I hope you enjoy the book, that you enjoy learning Camel —
 and that you get truly hooked, like I did.

Cheers, and happy building!

Tom

1
Introduction to this book
So you want to get started with Apache Camel the easy way?

Maybe you’ve tried other tutorials, but they all seem too
complicated. Or half-finished. Or unreadable. Or just a bunch
of code pasted onto a web page.

If you’re the kind of person who prefers to learn with a step-by-

step approach, then this book is for you!

This book is structured sequentially. That means that if you’re

really new to Apache Camel then you can read it from cover to
cover. The tutorial steps are in sequence, so you can follow
them in a linear fashion.

To begin, I’m going to introduce Apache Camel to you. You’ll

learn the basics, and what you need to know as a Camel
developer. You’ll learn about things like routes and
components, and how they fit together.

Then, you’ll create your first Camel application. We’ll look at

the source code and you’ll see how to run it from Eclipse.

In subsequent sections you’ll learn more about the tools within

Camel, and two of the most common use cases that I’ve seen
when working with Camel - transforming data and working
with web services.

At the back, there is a handy questions and answers section,

filled with the most common questions asked by Camel
developers. Finally, you’ll also find a full glossary at the back,
with Camel terms explained in plain English (no tech-speak!).

2
Getting ready
To get the most out of this book, it’s best to follow the tutorials,
step-by-step (well, the book is called Camel Step-by-Step…).

To do this, you’ll need the following tools installed:

Java Development Kit (JDK) - the development environment

for building Java applications. (search online for "java
development kit")

Apache Maven - for building your Camel applications. You can

use Camel without Maven but it is really difficult, and you’ll
waste a lot of time.

If you’ve struggled with Maven up until this point, don’t

worry. I agree it’s a massive faff (see glossary). I was once
pretty anti-Maven, too. This book will help you conquer
your fears by making heavy use of Maven and the
command line. You’ll be a Maven pro by the end, I
promise!

Eclipse - you’ll need Eclipse for the very first tutorial, as it is

written with Eclipse in mind. However, for the rest of the book,
you can use the command line.

Once you’ve installed those, turn over to the next page and
let’s get started!

3
Section I: The basics
Introducing Apache Camel

OK, this is the $64,000 question. Lots of people want to know

the answer to this one.

What exactly is Apache Camel?

Apache Camel is an integration library for Java. It’s a set of

Java APIs that help you integrate and process data between
different computer systems.

In other words, Camel is like glue between different

applications.

Camel comes with components that let you integrate lots of

different applications — everything from web services, to
reading and writing files on disk. You can even connect Camel
with web apps like Twitter and Salesforce.

You could think of Camel like a plumbing toolkit for Java. Just
like real plumbing pipes, Camel takes data from one point, and
pipes it to another. Along the way, the data can be changed,
transformed, or sent through other pipes.

4
Included in your plumbing toolkit is a range of adaptors
(components in Camel-speak) that fit all sorts of different apps
and software systems.

With a your Camel toolkit at your disposal, it’s up to you how

you choose to build the plumbing.

Where did the idea for Camel come from?

Camel was heavily inspired by the book Enterprise Integration

Patterns, written by Gregor Hohpe and Bobby Woolf. It’s a
reference book which describes some common patterns for
integrating software systems.

The authors of the book (considered a 'classic' in some circles!)

took dozens of common ways to integrate software systems
and distilled them into reusable patterns. They wrote a little bit
about each pattern, described how it might be used, and
provided some suggested code for how to implement it.

The Camel developers thought it would be a great idea to

build a Java framework that actually implemented the patterns
described in the book.

And so, many of Apache Camel’s core features are based

heavily on the book. In fact, Camel has functionality called
Enterprise Integration Patterns (EIPs), which are named directly
after the book. You’ll see these later on.

5
 Camel facts

Here are some fun facts, and reasons to get to know the
Camel!

It’s written in Java… I’ll start with an obvious point.

Since Apache Camel is written in Java, you have the full
power of Java at your disposal!

The source code is completely open… open source is

awesome! Want to know exactly how it works? Just grab
the source code from GitHub and dig away, to your
heart’s content.

It’s not just for web services… it’s a general integration

framework. You can use Camel to interact with web
services, but it’s capable of much, much more than that.

It comes with a huge library of components… if you

can think of an app you’d like to interact with, somebody
has probably already written a Camel component for it.
You can do anything from pushing files to Amazon cloud
storage, to sending a tweet. You can even write your own
components and contribute them to the community.

It’s mature… Apache Camel is well and truly mature,

and forms the foundation of some commercially-sold
integration products, like Red Hat JBoss Fuse and Talend
ESB. This means that you can always get support if you
need it, both commercial and community support.

6
What is Apache Camel used for?

Almost any time you need to ship data from A to B, you can
probably use Apache Camel.

I’ve listed some typical data shipping scenarios below. You can
implement all of these with Camel:

• Pick up invoices from your corporate file server and email

them to customers

• Move documents from your hard disk into Google Drive

• Take order messages from a JMS queue, and use them to

invoke a web service provided by one of your suppliers

• Turn some XML documents into CSV

• Make a web service that allows users to retrieve customer

details from a database

These are just a few examples. With the wide range of

components available in Camel, the sky’s the limit.

And Apache Camel is already in use in lots of places.

It’s used by lots of companies and organisations. Banks,

insurance companies, retail businesses and even governments
all use Apache Camel to integrate and move data between
computer systems.

So let’s look inside the Camel box and see how it actually
works.

7
Getting on the Camel
How do you think like a Camel? Let’s look at the main concepts.

The diagram above shows some of the core concepts in Camel.

In this section I’m going to look at each in turn.

Route

The basic concept in Camel is the route. Routes are objects

which you configure in Camel, which move your data from A to
B.

To use the plumbing example from earlier, a route is a pipe

that moves data from one place to another. It moves data
between things called endpoints.

You can create routes in Camel either using a Java syntax, or

using an XML syntax. Here’s a very simple Java route:

8
 // This is a complete Camel route definition!
from("file:home/customers/new")
  .to("file:home/customers/old");

Endpoints

In Camel, an endpoint represents any other external system to

Camel. For an example, at the start of a route, Camel receives
a message from an endpoint.

Then, the message might be processed in some way — perhaps

by an EIP — before being sent to another destination endpoint.

Components

To allow Camel to connect to an endpoint, it comes with a

library of components. A component is simply like a plug that
allows you to connect to an external system (such as a file on
disk, a mailbox, or an app like Dropbox, Twitter, etc). You can
also think of it like an adaptor.

A full library of components

Any time that you need to put data into or out of an

application, you’ll probably find that a Camel component
already exists to do the job for you. This means you don’t
need to waste time writing your own code to read a file,
or invoke a web service. You just find the component you
need, and use it.

Camel components are reusable, open source, and you can

even contribute your own. Here are some of the most common

9
components, and how you might reference them in an
endpoint:

Component Purpose Endpoint URI

HTTP for creating or consuming http:
web sites
File for reading and writing file:
files
JMS for reading and writing to jms:
messaging queues
Direct for joining your Camel direct:
routes together

You can find a list of all the Camel components here.

As you can see, each component can usually read and write:

• A component that is configured to write something is

called a producer — for example, writing to a file on disk, or
writing to a message queue.

• A component that is configured to read something is called

a consumer — for example, reading a file from disk, or
perhaps receiving a REST request.

Between each endpoint, the data can also be transformed or

modified, either by passing the data through another endpoint,
or by using an EIP.

Enterprise Integration Patterns (EIPs)

EIPs are another important part of Camel. They do special

processing on messages according to the patterns defined in
the book, Enterprise Integration Patterns, that I mentioned
earlier.

10
When you want to perform some common activities on a
message, such as transformation, splitting and logging, you’ll
use an EIP. Here are some common EIPs in Camel:

EIP name What it does Java syntax

Splitter Splits a message into .split()
multiple parts
Aggregator Combines several .aggregate()
messages into one
message
Log Writes a simple log .log()
message
Marshal Converts an object into a .marshal()
text or binary format
From* Receives a message from .from()
an endpoint
To* Sends a message to an .to()
endpoint

*Yes, from and to are EIPs too!

Camel Context

Finally, to run and manage your routes, Camel has a container

called the Camel Context. This is like an engine where your
routes will run, almost like a mini application server.

When Camel starts, it reads your route definitions (in Java or

XML), creates the routes, and adds them to a Camel Context.

When Camel terminates, it shuts down your routes, and closes

the Camel Context.

11
What does a Route actually look
like?
So. Now you know that when you develop in Camel, you create
routes that move data between endpoints, using components.

It’s probably easiest to understand all of this by looking at some

code, right?

Although Camel is a library for Java, it can be configured using

one of two languages - either Java or XML. In Camel-speak,
these are known as DSLs (Domain Specific Languages).

Each route starts with a from, configured with a uri, that

defines the endpoint that the data is coming from.

A route can consist of multiple steps — such as transforming the

data, or logging it. But a route usually ends with a to()
instruction, which describes where the data will be delivered to.

A really simple route in the Java DSL could look something like
this:

from("file:home/customers/new")
  .to("file:home/customers/old");

In this example, we use the File component (identified by the

file: prefix) to move all incoming files in the customers/new
folder, to the customers/old folder.

That same route above could be expressed in XML DSL like

this:

12
 <route>
  <from uri="file:home/customers/new"/>
  <to uri="file:home/customers/old"/>
</route>

But… what if we wanted to add another step in our route? Let’s

say we want to log a message when we’ve received a file. Then
we simply add our new step in between the existing steps, like
this:

from("file:home/customers/new")
  .log("Received a new customer!")
  .to("file:home/customers/old");

In the code above, a message is moved from the new folder to

the old folder. In the middle, we use the Enterprise Integration
Pattern (EIP) called log, which writes a simple Log message to
the console.

And in the XML DSL, it would look something like this:

<route>
  <from uri="file:home/customers/new"/>
  <log message="Received a new customer!"/>
  <to uri="file:home/customers/old"/>
</route>

13
Messages in Camel
Camel works with data using a message model.

What does this mean? It means that Camel treats data as

individual messages – like letters flowing through a post office.

Each message is an individual unit. A message can be huge, or

it can be very small. Camel has an object to represent
messages, and helpfully it’s called Message.

A Message has a body, where the message content lives. It also

has headers, which can be used to hold values associated with
the message. The Message object is then passed along a route.

A Message is part of a Camel object called an Exchange. You’ll

often see the term Exchange mentioned in Camel
documentation. An Exchange is simply a message or interaction
currently taking place inside your Camel route.

The important thing to understand about Camel’s message

model is that the message body can contain almost any kind of
Java object — it doesn’t have to be XML, JSON or even plain
text for that matter.

The real power of Camel becomes clear when you start using
different types of objects. Camel has a lot of built-in support for

14
converting between different object types.

In fact, for many common file types, you might barely even
have to write any code. (Less time writing boilerplate code?
Sounds good, doesn’t it?)

You’ve learned the basics - we’ll pick the rest up on the way.
Let’s now put things into practice and walk through creating
your first Camel project. Head to the next page to get
started!

15
Your first Camel project
In this part of the book, I’m going to show you how to create a
new Apache Camel project in Eclipse.

If you’ve never worked with Camel before, then by the end of

this chapter, you’ll have created your first project, run it, and
begun to understand the power of Camel.

We’re going to do this using a Maven archetype. Maven

archetypes are like templates for new Java projects. And, for
this first project, we’re going to use Eclipse.

Eclipse is absolutely not required to either create or build

Camel projects. In fact, I very rarely use it.

But it’s one of the most common IDEs in use today, used
by millions of developers just like you. Eclipse makes it
very easy to create a project and run it.

What are we going to do?

• Use Eclipse to create a new Maven project

• Base our new project on a Camel archetype (remember

archetypes are like templates for Maven)

• Choose an archetype that uses Camel’s Java DSL - it’s

Camel’s Java-based syntax for writing Camel routes (more
on this shortly)

• Inspect the project, and run it

The first step is to create the new project, in Eclipse. In this

tutorial I’m using a brand new installation of Eclipse Oxygen.

16
Note: you’ll need to be online to complete this tutorial.

Creating a Camel project in Eclipse

1. On your computer, launch Eclipse.

2. From the File menu, choose New → Maven Project.

3. On the first step of the New Maven Project wizard, make

sure that Create a simple project remains unchecked. Then
choose Next to accept the defaults.

17
4. The next step asks you to select a Maven archetype for your
project, from a list of available archetypes. (You might need
to wait a while for the full list to load.)

Type camel in the filter box to search for just Camel

archetypes. Then choose the archetype in the group
org.apache.camel.archetypes group, with the artifact
name camel-archetype-java.

Then click Next.

5. Finally, on the last step of the new Maven project wizard,

give your new application’s groupId and artifactId:

Once you’ve done that, click Finish.

18
 6. Now your Camel project is created in Eclipse! In a moment,
we’ll run the app and see what it does.

But first, let’s take a look at the structure of a typical Camel

project.

Inside a typical Camel project

A Camel project created from the camel-archetype-java

archetype will have a folder structure that looks like this:

project/
└ src/
  ├ main/
  │ ├ java/
  │ │ └ com/
  │ │ └ example/
  │ │ ├ MainApp.java
  │ │ └ MyRouteBuilder.java
  │ └ resources/
  │ └ log4j2.properties
  └ test/
  ├ java/
  └ resources/

The main code resides in MyRouteBuilder.java. This class

extends Camel’s RouteBuilder class, and this is where your
routes should go:

19
 package com.example;

import org.apache.camel.builder.RouteBuilder;

public class MyRouteBuilder extends RouteBuilder {

  public void configure() {

  // Route definitions go here!
  }
}

You add route definitions to the configure() method, to

describe each route that you want Camel to create.

If you check out the code, you’ll see that the MyRouteBuilder
class in the Eclipse project comes with a route defined inside it
already.

For your convenience, the project also includes another Java

class, MainApp, which is used to run your route. It uses the
familiar Java public static void main() method to initialise
MyRouteBuilder, which creates the routes:

public static void main(String... args) throws

Exception {
  Main main = new Main();
  main.addRouteBuilder(new MyRouteBuilder());
  main.run(args);
}

This is useful for testing, as you’ll see next.

20
 Which DSL should you use?

Camel supports two main ways of defining routes. Each is

described in the official Camel documentation as a DSL
(Domain Specific Languages). The two main types are:

• Java DSL - this uses standard Java syntax for defining

routes. You write your routes in a RouteBuilder class.

• XML DSL (also sometimes called Spring DSL or

Blueprint DSL) - this is where you declare your routes
in an XML file.

If you’re starting a brand new Camel project, you’re

probably going to ask which DSL to use. The answer to
this is that it really depends on the project.

Bilgin Ibryam has written a good blog post on this topic,

which you can find here.

What does the project do?

The demo project defines a route using the code below. The
code is given in special Camel syntax, or DSL (Domain-specific
Language):

21
 public void configure() {
  from("file:src/data?noop=true")
  .choice()
  .when(xpath("/person/city = 'London'"))
  .log("UK message")
  .to("file:target/messages/uk")
  .otherwise()
  .log("Other message")
  .to("file:target/messages/others");
}

This code looks complicated, but it really just moves files from
one folder to another.

It receives files from source folder using from(). The output

folder is determined based on the content of the message.
(This is Camel’s content-based routing function in action, which
you can read more about in a later chapter!)

Let’s look at each part of this statement in detail:

• The from() EIP starts the route. The part in brackets defines
the URI of the endpoint. In this case, the endpoint is a File
component (which has a URI prefix of file:). The part after
that states which folder to consume from (src/data).

• The choice() EIP states that we’re starting a content-based

routing section. In other words, we are configuring Camel
to process any incoming message according to a
condition.

• The when() keyword uses XPath (the language for

navigating XML documents) to test whether the <city>
element in the XML message equals "London". If so, it
writes a log message, "UK message", and then moves the
file to the target/messages/uk folder.

22
 • The otherwise() keyword defines what should happen if
the previous test returns false. If it’s false, it writes a log
message, "Other message", and moves the file to the
target/messages/others folder.

You’ll see that, although it’s been formatted for easier reading,
the entire route is a single Java statement – it starts with the
method call from(), and ends with a to() method call and the
statement terminator, ;.

To get you started, the demo route provides you a couple of

demo data files to test with. These are in the folder src/data.
The two files are called message1.xml and message2.xml.

When the route runs, these two files will be picked up by

Camel, inspected to see whether they are London files, and
routed accordingly.

So let’s run the route and see what happens.

Running the application

1. In the project tree, find the class MainApp.java.

2. Right-click the file and select Run As → Java Application.

23
 If you’re prompted by a Select Java
Application dialog box, tell Eclipse to run
 the app as a Camel route by selecting Main
– org.apache.camel from the list.

3. Camel will launch, process the files, and you’ll see the
output from the route in the Console window.

If you see the error "Exception in thread "main"

java.lang.UnsupportedClassVersionError" when
you try to run the project, then you might be
running a version of Eclipse containing a version

 of Java that is newer than the JRE on your

classpath. Check your Project settings in Project
Properties → Java Compiler and, if necessary,
check the Use compliance from execution
environment box.

So….what just happened?

24
Camel found your route definitions (in MyRouteBuilder) and
started a CamelContext, containing your single route.

Then, it started the route, which started the consumption of

messages (from the src/data folder). Finally, it processed each
file according to its content.

If you check the output folder (target/messages) now, you’ll

see the two files have been sorted into their output folders:

The other thing to do is have a look at the console or log

output. This shows exactly what happened when Camel
processed the files:

• The first file, message1.xml, had a city value of London, so

it was routed to the uk folder and a log message: UK
message was written to the console.

• The second file, message2.xml, had a city value of Tampa,

so it was moved to the others folder, and a log message:
Other message was written.

So Camel has just processed some files according to some

rules, and performed different actions on each file. And all
without having to drop to low-level Java code.

25
This is a very basic demo of Camel, but you can start to see
what it’s capable of. Using components and EIPs you can build
almost any kind of data flow that you can think of.

Now let’s move on and see what other cool stuff we can build
with Camel!

26
End of Preview

This is the end of this preview version of the book. I hope

you’ve enjoyed it and you’re raring to go with Camel.

In the full version of the book, you’ll learn:

• Other ways to create Camel projects, including running

Camel inside Spring Boot

• A full tutorial to follow (based on a real-world application!)

of implementing a REST service in Camel

• How to use Maven with Camel

• Common questions asked by newbie Camel developers -

and full, detailed answers to them!

• A glossary of Camel terms, to make things clearer

To download the full version of the book, head on over to

https://cleverbuilder.com/camelstepbystep.

If you’ve liked this sample, please tell your friends they can get
their own copy at https://cleverbuilder.com.

Thanks for reading!

27