Camel Manual Fuse 1.x

camel-manual-1.x-fuse-20111110.013830-10

camel-manual-fuse-1.x

User Manual:

Open the PDF directly: View PDF .
Page Count: 956 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Apache Camel
- User Guide
  - Version 1.x-fuse-SNAPSHOT
Table of Contents
Introduction
Quickstart
Getting Started with Apache Camel
Architecture
- URIs
  - Current Supported URIs
  - URI's for external components
Enterprise Integration Patterns
- Pattern Index
CookBook
Introduction
Using a Producer
Tutorials
Languages Supported Appendix
Data Format Appendix
Protobuf - Protocol Buffers
Pattern Appendix
Component Appendix

Apache Camel

USER GUIDE

Version 1.x-fuse-SNAPSHOT

Table of Contents

Table of Contents ....................................................ii

Chapter 1

Introduction........................................................... 1

Chapter 2

Quickstart.............................................................. 1

Chapter 3

Getting Started ...................................................... 7

Chapter 4

Architecture..........................................................18

Chapter 5

Enterprise Integration Patterns .............................34

Chapter 6

Cook Book............................................................. 39

Chapter 7

Tutorials ............................................................. 109

Chapter 8

Language Appendix............................................. 221

Chapter 9

DataFormat Appendix.......................................... 293

Chapter 10

Pattern Appendix ................................................ 366

Chapter 11

Component Appendix .......................................... 524

Index ..................................................................... 0

ii APACHE CAMEL

CHAPTER 1

°°°°

Introduction

Apache Camel is a powerful open source integration framework based on

known Enterprise Integration Patterns with powerful Bean Integration.

Camel lets you create the Enterprise Integration Patterns to implement

routing and mediation rules in either a Java based Domain Specic Language

(or Fluent API), via Spring based Xml Conguration les or via the Scala DSL.

This means you get smart completion of routing rules in your IDE whether in

your Java, Scala or XML editor.

Apache Camel uses URIs so that it can easily work directly with any kind of

Transport or messaging model such as HTTP, ActiveMQ, JMS, JBI, SCA, MINA

or CXF Bus API together with working with pluggable Data Format options.

Apache Camel is a small library which has minimal dependencies for easy

embedding in any Java application. Apache Camel lets you work with the

same API regardless which kind of Transport used, so learn the API once and

you will be able to interact with all the Components that is provided out-of-

the-box.

Apache Camel has powerful Bean Binding and integrated seamless with

popular frameworks such as Spring and Guice.

Apache Camel has extensive Testing support allowing you to easily unit

test your routes.

Apache Camel can be used as a routing and mediation engine for the

following projects:

• Apache ServiceMix which is the most popular and powerful

distributed open source ESB and JBI container

• Apache ActiveMQ which is the most popular and powerful open

source message broker

• Apache CXF which is a smart web services suite (JAX-WS)

• Apache MINA a networking framework

So don't get the hump, try Camel today!

CHAPTER 1 - INTRODUCTION 1

CHAPTER 2

°°°°

Quickstart

To start using Apache Camel quickly, you can read through some simple

examples in this chapter. For readers who would like a more thorough

introduction, please skip ahead to Chapter 3.

WALK THROUGH AN EXAMPLE CODE

This mini-guide takes you through the source code of a simple example.

Camel can be congured either by using Spring or directly in Java - which

this example does.

We start with creating a CamelContext - which is a container for

Components, Routes etc:

CamelContext context = new DefaultCamelContext();

There is more than one way of adding a Component to the CamelContext.

You can add components implicitly - when we set up the routing - as we do

here for the FileComponent:

context.addRoutes(new RouteBuilder() {

public void configure() {

from("test-jms:queue:test.queue").to("file://test");

// set up a listener on the file component

from("file://test").process(new Processor() {

public void process(Exchange e) {

System.out.println("Received exchange: " + e.getIn());

}

});

}

});

or explicitly - as we do here when we add the JMS Component:

1CHAPTER 2 - QUICKSTART

ConnectionFactory connectionFactory = new

ActiveMQConnectionFactory("vm://localhost?broker.persistent=false");

// Note we can explicit name the component

context.addComponent("test-jms",

JmsComponent.jmsComponentAutoAcknowledge(connectionFactory));

The above works with any JMS provider. If we know we are using ActiveMQ

we can use an even simpler form using the activeMQComponent() method

while specifying the brokerURL used to connect to ActiveMQ

camelContext.addComponent("activemq",

activeMQComponent("vm://localhost?broker.persistent=false"));

In normal use, an external system would be ring messages or events

directly into Camel through one if its Components but we are going to use

the ProducerTemplate which is a really easy way for testing your

conguration:

ProducerTemplate template = context.createProducerTemplate();

Next you must start the camel context. If you are using Spring to congure

the camel context this is automatically done for you; though if you are using

a pure Java approach then you just need to call the start() method

camelContext.start();

This will start all of the congured routing rules.

So after starting the CamelContext, we can re some objects into camel:

for (int i = 0; i < 10; i++) {

template.sendBody("test-jms:queue:test.queue","Test Message: " + i);

}

WHAT HAPPENS?

From the ProducerTemplate - we send objects (in this case text) into the

CamelContext to the Component test-jms:queue:test.queue. These text

objects will be converted automatically into JMS Messages and posted to a

JMS Queue named test.queue. When we set up the Route, we congured the

FileComponent to listen of the test.queue.

CHAPTER 2 - QUICKSTART 2

The File FileComponent will take messages o the Queue, and save them

to a directory named test. Every message will be saved in a le that

corresponds to its destination and message id.

Finally, we congured our own listener in the Route - to take notications

from the FileComponent and print them out as text.

That's it!

If you have the time then use 5 more minutes to Walk through another

example that demonstrates the Spring DSL (XML based) routing.

WALK THROUGH ANOTHER EXAMPLE

Introduction

We continue the walk from Walk through an Example. This time we take a

closer look at the routing and explains a few pointers so you wont walk into a

bear trap, but can enjoy a walk after hours to the local pub for a large beer

First we take a moment to look at the Enterprise Integration Patterns that

is the base pattern catalog for integrations. In particular we focus on the

Pipes and Filters EIP pattern, that is a central pattern. This is used for: route

through a sequence of processing steps, each performing a specic function -

much like the Java Servlet Filters.

Pipes and lters

In this sample we want to process a message in a sequence of steps where

each steps can perform their specic function. In our example we have a JMS

queue for receiving new orders. When an order is received we need to

process it in several steps:

▪ validate

▪ register

▪ send conrm email

This can be created in a route like this:

<route>

</pipeline>

</route>

3CHAPTER 2 - QUICKSTART

Camel 1.4.0 change

In Camel 1.4.0, CamelTemplate has been marked as @deprecated.

ProducerTemplate should be used instead and its created from the

CamelContext itself.

ProducerTemplate template = context.createProducerTemplate();

Where as the bean ref is a reference for a spring bean id, so we dene our

beans using regular Spring XML as:

Our validator bean is a plain POJO that has no dependencies to Camel what

so ever. So you can implement this POJO as you like. Camel uses rather

intelligent Bean Binding to invoke your POJO with the payload of the received

message. In this example we will not dig into this how this happens. You

should return to this topic later when you got some hands on experience with

Camel how it can easily bind routing using your existing POJO beans.

So what happens in the route above. Well when an order is received from

the JMS queue the message is routed like Pipes and Filters:

1. payload from the JMS is sent as input to the validateOrder bean

2. the output from validateOrder bean is sent as input to the registerOrder

bean

3. the output from registerOrder bean is sent as input to the

sendConrmEmail bean

Using Camel Components

In the route lets imagine that the registration of the order has to be done by

sending data to a TCP socket that could be a big mainframe. As Camel has

many Components we will use the camel-mina component that supports TCP

connectivity. So we change the route to:

<route>

</route>

CHAPTER 2 - QUICKSTART 4

Pipeline is default

In the route above we specify pipeline but it can be omitted as its

default, so you can write the route as:

<route>

</route>

This is commonly used not to state the pipeline.

An example where the pipeline needs to be used, is when using a

multicast and "one" of the endpoints to send to (as a logical group) is a

pipeline of other endpoints. For example.

<route>

</pipeline>

</multicast>

</route>

The above sends the order (from jms:queue:order) to two locations at the

same time, our log component, and to the "pipeline" of beans which goes

one to the other. If you consider the opposite, sans the <pipeline>

<route>

</multicast>

</route>

you would see that multicast would not "ow" the message from one bean

to the next, but rather send the order to all 4 endpoints (1x log, 3x bean) in

5CHAPTER 2 - QUICKSTART

parallel, which is not (for this example) what we want. We need the

message to ow to the validateOrder, then to the registerOrder, then the

sendConrmEmail so adding the pipeline, provides this facility.

What we now have in the route is a to type that can be used as a direct

replacement for the bean type. The steps is now:

1. payload from the JMS is sent as input to the validateOrder bean

2. the output from validateOrder bean is sent as text to the mainframe using

TCP

3. the output from mainframe is sent back as input to the sendConrmEmai

bean

What to notice here is that the to is not the end of the route (the world

) in this example it's used in the middle of the Pipes and Filters. In fact we

can change the bean types to to as well:

<route>

</route>

As the to is a generic type we must state in the uri scheme which component

it is. So we must write bean: for the Bean component that we are using.

Conclusion

This example was provided to demonstrate the Spring DSL (XML based) as

opposed to the pure Java DSL from the rst example. And as well to point

about that the to doesn't have to be the last node in a route graph.

This example is also based on the in-only message exchange pattern.

What you must understand as well is the in-out message exchange pattern,

where the caller expects a response. We will look into this in another

example.

See also

▪ Examples

▪ Tutorials

▪ User Guide

CHAPTER 2 - QUICKSTART 6

CHAPTER 3

°°°°

Getting Started with Apache

Camel

THE ENTERPRISE INTEGRATION PATTERNS (EIP) BOOK

The purpose of a "patterns" book is not to advocate new techniques that the

authors have invented, but rather to document existing best practices within

a particular eld. By doing this, the authors of a patterns book hope to

spread knowledge of best practices and promote a vocabulary for discussing

architectural designs.

One of the most famous patterns books is Design Patterns: Elements of

Reusable Object-oriented Software by Erich Gamma, Richard Helm, Ralph

Johnson and John Vlissides, commonly known as the "Gang of Four" (GoF)

book. Since the publication of Design Patterns, many other pattern books, of

varying quality, have been written. One famous patterns book is called

Enterprise Integration Patterns: Designing, Building, and Deploying

Messaging Solutions by Gregor Hohpe and Bobby Woolf. It is common for

people to refer to this book by its initials EIP. As the subtitle of EIP suggests,

the book focuses on design patterns for asynchronous messaging systems.

The book discusses 65 patterns. Each pattern is given a textual name and

most are also given a graphical symbol, intended to be used in architectural

diagrams.

THE CAMEL PROJECT

Camel (http://camel.apache.org) is an open-source, Java-based project that

helps the user implement many of the design patterns in the EIP book.

Because Camel implements many of the design patterns in the EIP book, it

would be a good idea for people who work with Camel to have the EIP book

as a reference.

7CHAPTER 3 - GETTING STARTED WITH APACHE CAMEL

ONLINE DOCUMENTATION FOR CAMEL

The documentation is all under the Documentation category on the right-side

menu of the Camel website (also available in PDF form. Camel-related books

are also available, in particular the Camel in Action book, presently serving

as the Camel bible--it has a free Chapter One (pdf), which is highly

recommended to read to get more familiar with Camel.

A useful tip for navigating the online documentation

The breadcrumbs at the top of the online Camel documentation can help you

navigate between parent and child subsections.

For example, If you are on the "Languages" documentation page then the

left-hand side of the reddish bar contains the following links.

Apache Camel > Documentation > Architecture > Languages

As you might expect, clicking on "Apache Camel" takes you back to the home

page of the Apache Camel project, and clicking on "Documentation" takes

you to the main documentation page. You can interpret the "Architecture"

and "Languages" buttons as indicating you are in the "Languages" section of

the "Architecture" chapter. Adding browser bookmarks to pages that you

frequently reference can also save time.

ONLINE JAVADOC DOCUMENTATION

The Apache Camel website provides Javadoc documentation. It is important

to note that the Javadoc documentation is spread over several independent

Javadoc hierarchies rather than being all contained in a single Javadoc

hierarchy. In particular, there is one Javadoc hierarchy for the core APIs of

Camel, and a separate Javadoc hierarchy for each component technology

supported by Camel. For example, if you will be using Camel with ActiveMQ

and FTP then you need to look at the Javadoc hierarchies for the core API and

Spring API.

CONCEPTS AND TERMINOLOGY FUNDAMENTAL TO CAMEL

In this section some of the concepts and terminology that are fundamental to

Camel are explained. This section is not meant as a complete Camel tutorial,

but as a rst step in that direction.

CHAPTER 3 - GETTING STARTED WITH APACHE CAMEL 8

Endpoint

The term endpoint is often used when talking about inter-process

communication. For example, in client-server communication, the client is

one endpoint and the server is the other endpoint. Depending on the

context, an endpoint might refer to an address, such as a host:port pair for

TCP-based communication, or it might refer to a software entity that is

contactable at that address. For example, if somebody uses

"www.example.com:80" as an example of an endpoint, they might be

referring to the actual port at that host name (that is, an address), or they

might be referring to the web server (that is, software contactable at that

address). Often, the distinction between the address and software

contactable at that address is not an important one.

Some middleware technologies make it possible for several software entities

to be contactable at the same physical address. For example, CORBA is an

object-oriented, remote-procedure-call (RPC) middleware standard. If a

CORBA server process contains several objects then a client can

communicate with any of these objects at the same physical address

(host:port), but a client communicates with a particular object via that

object's logical address (called an IOR in CORBA terminology), which consists

of the physical address (host:port) plus an id that uniquely identies the

object within its server process. (An IOR contains some additional information

that is not relevant to this present discussion.) When talking about CORBA,

some people may use the term "endpoint" to refer to a CORBA server's

physical address, while other people may use the term to refer to the logical

address of a single CORBA object, and other people still might use the term

to refer to any of the following:

• The physical address (host:port) of the CORBA server process

• The logical address (host:port plus id) of a CORBA object.

• The CORBA server process (a relatively heavyweight software entity)

• A CORBA object (a lightweight software entity)

Because of this, you can see that the term endpoint is ambiguous in at least

two ways. First, it is ambiguous because it might refer to an address or to a

software entity contactable at that address. Second, it is ambiguous in the

granularity of what it refers to: a heavyweight versus lightweight software

entity, or physical address versus logical address. It is useful to understand

that dierent people use the term endpoint in slightly dierent (and hence

ambiguous) ways because Camel's usage of this term might be dierent to

whatever meaning you had previously associated with the term.

Camel provides out-of-the-box support for endpoints implemented with many

dierent communication technologies. Here are some examples of the

Camel-supported endpoint technologies.

• A JMS queue.

• A web service.

9CHAPTER 3 - GETTING STARTED WITH APACHE CAMEL

• A le. A le may sound like an unlikely type of endpoint, until you

realize that in some systems one application might write information

to a le and, later, another application might read that le.

• An FTP server.

• An email address. A client can send a message to an email address,

and a server can read an incoming message from a mail server.

• A POJO (plain old Java object).

In a Camel-based application, you create (Camel wrappers around) some

endpoints and connect these endpoints with routes, which I will discuss later

in Section 4.8 ("Routes, RouteBuilders and Java DSL"). Camel denes a Java

interface called Endpoint. Each Camel-supported endpoint has a class that

implements this Endpoint interface. As I discussed in Section 3.3 ("Online

Javadoc documentation"), Camel provides a separate Javadoc hierarchy for

each communications technology supported by Camel. Because of this, you

will nd documentation on, say, the JmsEndpoint class in the JMS Javadoc

hierarchy, while documentation for, say, the FtpEndpoint class is in the FTP

Javadoc hierarchy.

CamelContext

ACamelContext object represents the Camel runtime system. You typically

have one CamelContext object in an application. A typical application

executes the following steps.

1. Create a CamelContext object.

2. Add endpoints – and possibly Components, which are discussed in

Section 4.5 ("Components") – to the CamelContext object.

3. Add routes to the CamelContext object to connect the endpoints.

4. Invoke the start() operation on the CamelContext object. This

starts Camel-internal threads that are used to process the sending,

receiving and processing of messages in the endpoints.

5. Eventually invoke the stop() operation on the CamelContext object.

Doing this gracefully stops all the endpoints and Camel-internal

threads.

Note that the CamelContext.start() operation does not block indenitely.

Rather, it starts threads internal to each Component and Endpoint and then

start() returns. Conversely, CamelContext.stop() waits for all the threads

internal to each Endpoint and Component to terminate and then stop()

returns.

If you neglect to call CamelContext.start() in your application then

messages will not be processed because internal threads will not have been

created.

If you neglect to call CamelContext.stop() before terminating your

application then the application may terminate in an inconsistent state. If

CHAPTER 3 - GETTING STARTED WITH APACHE CAMEL 10

you neglect to call CamelContext.stop() in a JUnit test then the test may

fail due to messages not having had a chance to be fully processed.

CamelTemplate

Camel used to have a class called CamelClient, but this was renamed to be

CamelTemplate to be similar to a naming convention used in some other

open-source projects, such as the TransactionTemplate and JmsTemplate

classes in Spring.

The CamelTemplate class is a thin wrapper around the CamelContext class. It

has methods that send a Message or Exchange – both discussed in Section

4.6 ("Message and Exchange")) – to an Endpoint – discussed in Section 4.1

("Endpoint"). This provides a way to enter messages into source endpoints,

so that the messages will move along routes – discussed in Section 4.8

("Routes, RouteBuilders and Java DSL") – to destination endpoints.

The Meaning of URL, URI, URN and IRI

Some Camel methods take a parameter that is a URI string. Many people

know that a URI is "something like a URL" but do not properly understand the

relationship between URI and URL, or indeed its relationship with other

acronyms such as IRI and URN.

Most people are familiar with URLs (uniform resource locators), such as

"http://...", "ftp://...", "mailto:...". Put simply, a URL species the location of a

resource.

AURI (uniform resource identier) is a URL or a URN. So, to fully understand

what URI means, you need to rst understand what is a URN.

URN is an acronym for uniform resource name. There are may "unique

identier" schemes in the world, for example, ISBNs (globally unique for

books), social security numbers (unique within a country), customer numbers

(unique within a company's customers database) and telephone numbers.

Each "unique identier" scheme has its own notation. A URN is a wrapper for

dierent "unique identier" schemes. The syntax of a URN is "urn:<scheme-

name>:<unique-identier>". A URN uniquely identies a resource, such as a

book, person or piece of equipment. By itself, a URN does not specify the

location of the resource. Instead, it is assumed that a registry provides a

mapping from a resource's URN to its location. The URN specication does

not state what form a registry takes, but it might be a database, a server

application, a wall chart or anything else that is convenient. Some

hypothetical examples of URNs are "urn:employee:08765245",

"urn:customer:uk:3458:hul8" and "urn:foo:0000-0000-9E59-0000-5E-2". The

<scheme-name> ("employee", "customer" and "foo" in these examples) part

of a URN implicitly denes how to parse and interpret the <unique-

11 CHAPTER 3 - GETTING STARTED WITH APACHE CAMEL

identier> that follows it. An arbitrary URN is meaningless unless: (1) you

know the semantics implied by the <scheme-name>, and (2) you have

access to the registry appropriate for the <scheme-name>. A registry does

not have to be public or globally accessible. For example,

"urn:employee:08765245" might be meaningful only within a specic

company.

To date, URNs are not (yet) as popular as URLs. For this reason, URI is widely

misused as a synonym for URL.

IRI is an acronym for internationalized resource identier. An IRI is simply an

internationalized version of a URI. In particular, a URI can contain letters and

digits in the US-ASCII character set, while a IRI can contain those same

letters and digits, and also European accented characters, Greek letters,

Chinese ideograms and so on.

Components

Component is confusing terminology; EndpointFactory would have been

more appropriate because a Component is a factory for creating Endpoint

instances. For example, if a Camel-based application uses several JMS

queues then the application will create one instance of the JmsComponent

class (which implements the Component interface), and then the application

invokes the createEndpoint() operation on this JmsComponent object

several times. Each invocation of JmsComponent.createEndpoint() creates

an instance of the JmsEndpoint class (which implements the Endpoint

interface). Actually, application-level code does not invoke

Component.createEndpoint() directly. Instead, application-level code

normally invokes CamelContext.getEndpoint(); internally, the

CamelContext object nds the desired Component object (as I will discuss

shortly) and then invokes createEndpoint() on it.

Consider the following code.

myCamelContext.getEndpoint("pop3://john.smith@mailserv.example.com?password=myPassword");

The parameter to getEndpoint() is a URI. The URI prex (that is, the part

before ":") species the name of a component. Internally, the CamelContext

object maintains a mapping from names of components to Component

objects. For the URI given in the above example, the CamelContext object

would probably map the pop3 prex to an instance of the MailComponent

class. Then the CamelContext object invokes

createEndpoint("pop3://john.smith@mailserv.example.com?password=myPassword")

on that MailComponent object. The createEndpoint() operation splits the

URI into its component parts and uses these parts to create and congure an

Endpoint object.

CHAPTER 3 - GETTING STARTED WITH APACHE CAMEL 12

In the previous paragraph, I mentioned that a CamelContext object

maintains a mapping from component names to Component objects. This

raises the question of how this map is populated with named Component

objects. There are two ways of populating the map. The rst way is for

application-level code to invoke CamelContext.addComponent(String

componentName, Component component). The example below shows a

single MailComponent object being registered in the map under 3 dierent

names.

Component mailComponent = new org.apache.camel.component.mail.MailComponent();

myCamelContext.addComponent("pop3", mailComponent);

myCamelContext.addComponent("imap", mailComponent);

myCamelContext.addComponent("smtp", mailComponent);

The second (and preferred) way to populate the map of named Component

objects in the CamelContext object is to let the CamelContext object perform

lazy initialization. This approach relies on developers following a convention

when they write a class that implements the Component interface. I illustrate

the convention by an example. Let's assume you write a class called

com.example.myproject.FooComponent and you want Camel to

automatically recognize this by the name "foo". To do this, you have to write

a properties le called "META-INF/services/org/apache/camel/component/foo"

(without a ".properties" le extension) that has a single entry in it called

class, the value of which is the fully-scoped name of your class. This is

shown below.

Listing 1. META-INF/services/org/apache/camel/component/foo

class=com.example.myproject.FooComponent

If you want Camel to also recognize the class by the name "bar" then you

write another properties le in the same directory called "bar" that has the

same contents. Once you have written the properties le(s), you create a jar

le that contains the com.example.myproject.FooComponent class and the

properties le(s), and you add this jar le to your CLASSPATH. Then, when

application-level code invokes createEndpoint("foo:...") on a

CamelContext object, Camel will nd the "foo"" properties le on the

CLASSPATH, get the value of the class property from that properties le, and

use reection APIs to create an instance of the specied class.

As I said in Section 4.1 ("Endpoint"), Camel provides out-of-the-box support

for numerous communication technologies. The out-of-the-box support

consists of classes that implement the Component interface plus properties

les that enable a CamelContext object to populate its map of named

Component objects.

13 CHAPTER 3 - GETTING STARTED WITH APACHE CAMEL

Earlier in this section I gave the following example of calling

CamelContext.getEndpoint().

myCamelContext.getEndpoint("pop3://john.smith@mailserv.example.com?password=myPassword");

When I originally gave that example, I said that the parameter to

getEndpoint() was a URI. I said that because the online Camel

documentation and the Camel source code both claim the parameter is a

URI. In reality, the parameter is restricted to being a URL. This is because

when Camel extracts the component name from the parameter, it looks for

the rst ":", which is a simplistic algorithm. To understand why, recall from

Section 4.4 ("The Meaning of URL, URI, URN and IRI") that a URI can be a URL

or a URN. Now consider the following calls to getEndpoint.

myCamelContext.getEndpoint("pop3:...");

myCamelContext.getEndpoint("jms:...");

myCamelContext.getEndpoint("urn:foo:...");

myCamelContext.getEndpoint("urn:bar:...");

Camel identies the components in the above example as "pop3", "jms",

"urn" and "urn". It would be more useful if the latter components were

identied as "urn:foo" and "urn:bar" or, alternatively, as "foo" and "bar" (that

is, by skipping over the "urn:" prex). So, in practice you must identify an

endpoint with a URL (a string of the form "<scheme>:...") rather than with a

URN (a string of the form "urn:<scheme>:..."). This lack of proper support for

URNs means the you should consider the parameter to getEndpoint() as

being a URL rather than (as claimed) a URI.

Message and Exchange

The Message interface provides an abstraction for a single message, such as

a request, reply or exception message.

There are concrete classes that implement the Message interface for each

Camel-supported communications technology. For example, the JmsMessage

class provides a JMS-specic implementation of the Message interface. The

public API of the Message interface provides get- and set-style methods to

access the message id,body and individual header elds of a messge.

The Exchange interface provides an abstraction for an exchange of

messages, that is, a request message and its corresponding reply or

exception message. In Camel terminology, the request, reply and exception

messages are called in,out and fault messages.

There are concrete classes that implement the Exchange interface for each

Camel-supported communications technology. For example, the JmsExchange

class provides a JMS-specic implementation of the Exchange interface. The

CHAPTER 3 - GETTING STARTED WITH APACHE CAMEL 14

public API of the Exchange interface is quite limited. This is intentional, and it

is expected that each class that implements this interface will provide its

own technology-specic operations.

Application-level programmers rarely access the Exchange interface (or

classes that implement it) directly. However, many classes in Camel are

generic types that are instantiated on (a class that implements) Exchange.

Because of this, the Exchange interface appears a lot in the generic

signatures of classes and methods.

Processor

The Processor interface represents a class that processes a message. The

signature of this interface is shown below.

Listing 2. Processor

package org.apache.camel;

public interface Processor {

void process(Exchange exchange) throws Exception;

}

Notice that the parameter to the process() method is an Exchange rather

than a Message. This provides exibility. For example, an implementation of

this method initially might call exchange.getIn() to get the input message

and process it. If an error occurs during processing then the method can call

exchange.setException().

An application-level developer might implement the Processor interface

with a class that executes some business logic. However, there are many

classes in the Camel library that implement the Processor interface in a way

that provides support for a design pattern in the EIP book. For example,

ChoiceProcessor implements the message router pattern, that is, it uses a

cascading if-then-else statement to route a message from an input queue to

one of several output queues. Another example is the FilterProcessor

class which discards messages that do not satisfy a stated predicate (that is,

condition).

Routes, RouteBuilders and Java DSL

Aroute is the step-by-step movement of a Message from an input queue,

through arbitrary types of decision making (such as lters and routers) to a

destination queue (if any). Camel provides two ways for an application

developer to specify routes. One way is to specify route information in an

XML le. A discussion of that approach is outside the scope of this document.

The other way is through what Camel calls a Java DSL (domain-specic

language).

15 CHAPTER 3 - GETTING STARTED WITH APACHE CAMEL

Introduction to Java DSL

For many people, the term "domain-specic language" implies a compiler or

interpreter that can process an input le containing keywords and syntax

specic to a particular domain. This is not the approach taken by Camel.

Camel documentation consistently uses the term "Java DSL" instead of

"DSL", but this does not entirely avoid potential confusion. The Camel "Java

DSL" is a class library that can be used in a way that looks almost like a DSL,

except that it has a bit of Java syntactic baggage. You can see this in the

example below. Comments afterwards explain some of the constructs used in

the example.

Listing 3. Example of Camel's "Java DSL"

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from("queue:a").filter(header("foo").isEqualTo("bar")).to("queue:b");

from("queue:c").choice()

.when(header("foo").isEqualTo("bar")).to("queue:d")

.when(header("foo").isEqualTo("cheese")).to("queue:e")

.otherwise().to("queue:f");

}

};

CamelContext myCamelContext = new DefaultCamelContext();

myCamelContext.addRoutes(builder);

The rst line in the above example creates an object which is an instance of

an anonymous subclass of RouteBuilder with the specied configure()

method.

The CamelContext.addRoutes(RouterBuilder builder) method invokes

builder.setContext(this) – so the RouteBuilder object knows which

CamelContext object it is associated with – and then invokes

builder.configure(). The body of configure() invokes methods such as

from(),filter(),choice(),when(),isEqualTo(),otherwise() and to().

The RouteBuilder.from(String uri) method invokes getEndpoint(uri)

on the CamelContext associated with the RouteBuilder object to get the

specied Endpoint and then puts a FromBuilder "wrapper" around this

Endpoint. The FromBuilder.filter(Predicate predicate) method

creates a FilterProcessor object for the Predicate (that is, condition)

object built from the header("foo").isEqualTo("bar") expression. In this

way, these operations incrementally build up a Route object (with a

RouteBuilder wrapper around it) and add it to the CamelContext object

associated with the RouteBuilder.

CHAPTER 3 - GETTING STARTED WITH APACHE CAMEL 16

Critique of Java DSL

The online Camel documentation compares Java DSL favourably against the

alternative of conguring routes and endpoints in a XML-based Spring

conguration le. In particular, Java DSL is less verbose than its XML

counterpart. In addition, many integrated development environments (IDEs)

provide an auto-completion feature in their editors. This auto-completion

feature works with Java DSL, thereby making it easier for developers to write

Java DSL.

However, there is another option that the Camel documentation neglects to

consider: that of writing a parser that can process DSL stored in, say, an

external le. Currently, Camel does not provide such a DSL parser, and I do

not know if it is on the "to do" list of the Camel maintainers. I think that a

DSL parser would oer a signicant benet over the current Java DSL. In

particular, the DSL would have a syntactic denition that could be expressed

in a relatively short BNF form. The eort required by a Camel user to learn

how to use DSL by reading this BNF would almost certainly be signicantly

less than the eort currently required to study the API of the RouterBuilder

classes.

Continue Learning about Camel

Return to the main Getting Started page for additional introductory reference

information.

17 CHAPTER 3 - GETTING STARTED WITH APACHE CAMEL

CHAPTER 4

°°°°

Architecture

Camel uses a Java based Routing Domain Specic Language (DSL) or an Xml

Conguration to congure routing and mediation rules which are added to a

CamelContext to implement the various Enterprise Integration Patterns.

At a high level Camel consists of a CamelContext which contains a

collection of Component instances. A Component is essentially a factory of

Endpoint instances. You can explicitly congure Component instances in Java

code or an IoC container like Spring or Guice, or they can be auto-discovered

using URIs.

An Endpoint acts rather like a URI or URL in a web application or a

Destination in a JMS system; you can communicate with an endpoint; either

sending messages to it or consuming messages from it. You can then create

a Producer or Consumer on an Endpoint to exchange messages with it.

The DSL makes heavy use of pluggable Languages to create an Expression

or Predicate to make a truly powerful DSL which is extensible to the most

suitable language depending on your needs. The following languages are

supported

• Bean Language for using Java for expressions

• Constant

• the unied EL from JSP and JSF

• Header

• JXPath

• Mvel

• OGNL

• Ref Language

• Property

• Scala DSL

• Scripting Languages such as

◦ BeanShell

◦ JavaScript

◦ Groovy

◦ Python

◦ PHP

◦ Ruby

• Simple

CHAPTER 4 - ARCHITECTURE 18

◦ File Language

• Spring Expression Language

• SQL

• Tokenizer

• XPath

• XQuery

Most of these languages is also supported used as Annotation Based

Expression Language.

For a full details of the individual languages see the Language Appendix

URIS

Camel makes extensive use of URIs to allow you to refer to endpoints which

are lazily created by a Component if you refer to them within Routes

Current Supported URIs

Component / ArtifactId / URI Description

AHC / camel-ahc

ahc:hostname:[port]

To call external HTTP

services using Async Http

Client

AMQP / camel-amqp

amqp:[topic:]destinationName

For Messaging with AMQP

protocol

APNS / camel-apns

apns:notify[?options]

For sending notications to

Apple iOS devices

Atom / camel-atom

atom:uri

Working with Apache

Abdera for atom integration,

such as consuming an atom

feed.

AWS-SNS / camel-aws

aws-sns://topicname[?options]

For Messaging with

Amazon's Simple

Notication Service (SNS).

19 CHAPTER 4 - ARCHITECTURE

AWS-SQS / camel-aws

aws-sqs://queuename[?options]

For Messaging with

Amazon's Simple Queue

Service (SQS).

AWS-S3 / camel-aws

aws-s3://bucketname[?options]

For working with Amazon's

Simple Storage Service (S3).

Bean / camel-core

bean:beanName[?method=someMethod]

Uses the Bean Binding to

bind message exchanges to

beans in the Registry. Is also

used for exposing and

invoking POJO (Plain Old

Java Objects).

Bean Validation / camel-bean-validator

bean-validator:something

Validates the payload of a

message using the Java

Validation API (JSR 303 and

JAXP Validation) and its

reference implementation

Hibernate Validator

Browse / camel-core

browse:someName

Provides a simple

BrowsableEndpoint which

can be useful for testing,

visualisation tools or

debugging. The exchanges

sent to the endpoint are all

available to be browsed.

Cache / camel-cache

cache://cachename[?options]

The cache component

facilitates creation of

caching endpoints and

processors using EHCache

as the cache

implementation.

Class / camel-core

class:className[?method=someMethod]

Uses the Bean Binding to

bind message exchanges to

beans in the Registry. Is also

used for exposing and

invoking POJO (Plain Old

Java Objects).

CHAPTER 4 - ARCHITECTURE 20

Cometd / camel-cometd

cometd://host:port/channelname

Used to deliver messages

using the jetty cometd

implementation of the

bayeux protocol

Context / camel-context

context:camelContextId:localEndpointName

Used to refer to endpoints

within a separate

CamelContext to provide a

simple black box

composition approach so

that routes can be combined

into a CamelContext and

then used as a black box

component inside other

routes in other

CamelContexts

Crypto (Digital Signatures) / camel-crypto

crypto:sign:name[?options]

crypto:verify:name[?options]

Used to sign and verify

exchanges using the

Signature Service of the

Java Cryptographic

Extension.

CXF / camel-cxf

cxf:address[?serviceClass=...]

Working with Apache CXF

for web services integration

CXF Bean / camel-cxf

cxf:bean name

Proceess the exchange

using a JAX WS or JAX RS

annotated bean from the

registry. Requires less

conguration than the

above CXF Component

CXFRS / camel-cxf

cxfrs:address[?resourcesClasses=...]

Working with Apache CXF

for REST services

integration

21 CHAPTER 4 - ARCHITECTURE

DataSet / camel-core

dataset:name

For load & soak testing the

DataSet provides a way to

create huge numbers of

messages for sending to

Components or asserting

that they are consumed

correctly

Direct / camel-core

direct:name

Synchronous call to another

endpoint

DNS / camel-dns

dns:operation

To lookup domain

information and run DNS

queries using DNSJava

EJB / camel-ejb

ejb:ejbName[?method=someMethod]

Uses the Bean Binding to

bind message exchanges to

EJBs. It works like the Bean

component but just for

accessing EJBs. Supports EJB

3.0 onwards.

Event / camel-spring

event://default

spring-event://default

Working with Spring

ApplicationEvents

EventAdmin / camel-eventadmin

eventadmin:topic

Receiving OSGi EventAdmin

events

Exec / camel-exec

exec://executable[?options]

For executing system

commands

File / camel-core

file://nameOfFileOrDirectory

Sending messages to a le

or polling a le or directory.

Camel 1.x use this link

File.

CHAPTER 4 - ARCHITECTURE 22

Flatpack / camel-atpack

flatpack:[fixed|delim]:configFile

Processing xed width or

delimited les or messages

using the FlatPack library

FreeMarker / camel-freemarker

freemarker:someTemplateResource

Generates a response using

a FreeMarker template

FTP / camel-ftp

ftp://host[:port]/fileName

Sending and receiving les

over FTP. Camel 1.x use

this link FTP.

FTPS / camel-ftp

ftps://host[:port]/fileName

Sending and receiving les

over FTP Secure (TLS and

SSL).

GAuth / camel-gae

gauth://name[?options]

Used by web applications to

implement an OAuth

consumer. See also Camel

Components for Google App

Engine.

GHttp / camel-gae

ghttp://hostname[:port][/path][?options]

ghttp:///path[?options]

Provides connectivity to the

URL fetch service of Google

App Engine but can also be

used to receive messages

from servlets. See also

Camel Components for

Google App Engine.

GLogin / camel-gae

glogin://hostname[:port][?options]

Used by Camel applications

outside Google App Engine

(GAE) for programmatic

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

• Spring Testing

• Testing

TESTING

Testing is a crucial activity in any piece of software development or

integration. Typically Camel Riders use various dierent technologies wired

together in a variety of patterns with dierent expression languages together

with dierent forms of Bean Integration and Dependency Injection so its very

easy for things to go wrong! . Testing is the crucial weapon to ensure that

things work as you would expect.

Camel is a Java library so you can easily wire up tests in whatever unit

testing framework you use (JUnit 3.x, 4.x or TestNG). However the Camel

project has tried to make the testing of Camel as easy and powerful as

possible so we have introduced the following features.

Testing mechanisms

The following mechanisms are supported

Name Description

COOKBOOK 76

time units

In the example above we use seconds as the time unit, but Camel

oers milliseconds, and minutes as well.

Camel

Test

is a library letting you easily create Camel test cases using a

single Java class for all your conguration and routing without

using Spring or Guice for Dependency Injection which does not

require an in depth knowledge of Spring+SpringTest or Guice

Spring

Testing

uses Spring Test together with either XML or Java Cong to

dependency inject your test classes

Guice uses Guice to dependency inject your test classes

In all approaches the test classes look pretty much the same in that they all

reuse the Camel binding and injection annotations.

Camel Test Example

Here is the Camel Test example.

public class FilterTest extends CamelTestSupport {

@EndpointInject(uri = "mock:result")

protected MockEndpoint resultEndpoint;

@Produce(uri = "direct:start")

protected ProducerTemplate template;

@Test

public void testSendMatchingMessage() throws Exception {

String expectedBody = "<matched/>";

resultEndpoint.expectedBodiesReceived(expectedBody);

template.sendBodyAndHeader(expectedBody, "foo","bar");

resultEndpoint.assertIsSatisfied();

}

@Test

public void testSendNotMatchingMessage() throws Exception {

resultEndpoint.expectedMessageCount(0);

template.sendBodyAndHeader("<notMatched/>","foo","notMatchedHeaderValue");

resultEndpoint.assertIsSatisfied();

77 COOKBOOK

}

@Override

protected RouteBuilder createRouteBuilder() {

return new RouteBuilder() {

public void configure() {

from("direct:start").filter(header("foo").isEqualTo("bar")).to("mock:result");

}

};

}

Notice how it derives from the Camel helper class CamelTestSupport but

has no Spring or Guice dependency injection conguration but instead

overrides the createRouteBuilder() method.

Spring Test with XML Cong Example

Here is the Spring Testing example using XML Cong.

@ContextConfiguration

public class FilterTest extends AbstractJUnit38SpringContextTests {

@EndpointInject(uri = "mock:result")

protected MockEndpoint resultEndpoint;

@Produce(uri = "direct:start")

protected ProducerTemplate template;

@DirtiesContext

public void testSendMatchingMessage() throws Exception {

String expectedBody = "<matched/>";

resultEndpoint.expectedBodiesReceived(expectedBody);

template.sendBodyAndHeader(expectedBody, "foo","bar");

resultEndpoint.assertIsSatisfied();

}

@DirtiesContext

public void testSendNotMatchingMessage() throws Exception {

resultEndpoint.expectedMessageCount(0);

template.sendBodyAndHeader("<notMatched/>","foo","notMatchedHeaderValue");

resultEndpoint.assertIsSatisfied();

}

COOKBOOK 78

Notice that we use @DirtiesContext on the test methods to force Spring

Testing to automatically reload the CamelContext after each test method -

this ensures that the tests don't clash with each other (e.g. one test method

sending to an endpoint that is then reused in another test method).

Also notice the use of @ContextConguration to indicate that by default

we should look for the FilterTest-context.xml on the classpath to congure

the test case which looks like this

<beans xmlns="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:context="http://www.springframework.org/schema/context"

xsi:schemaLocation="

http://www.springframework.org/schema/beans http://www.springframework.org/

schema/beans/spring-beans.xsd

http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/

camel-spring.xsd

<route>

</filter>

</route>

</camelContext>

</beans>

Spring Test with Java Cong Example

Here is the Spring Testing example using Java Cong. For more information

see Spring Java Cong.

@ContextConfiguration(

locations =

"org.apache.camel.spring.javaconfig.patterns.FilterTest$ContextConfig",

loader = JavaConfigContextLoader.class)

public class FilterTest extends AbstractJUnit4SpringContextTests {

@EndpointInject(uri = "mock:result")

protected MockEndpoint resultEndpoint;

@Produce(uri = "direct:start")

protected ProducerTemplate template;

@DirtiesContext

79 COOKBOOK

@Test

public void testSendMatchingMessage() throws Exception {

String expectedBody = "<matched/>";

resultEndpoint.expectedBodiesReceived(expectedBody);

template.sendBodyAndHeader(expectedBody, "foo","bar");

resultEndpoint.assertIsSatisfied();

}

@DirtiesContext

@Test

public void testSendNotMatchingMessage() throws Exception {

resultEndpoint.expectedMessageCount(0);

template.sendBodyAndHeader("<notMatched/>","foo","notMatchedHeaderValue");

resultEndpoint.assertIsSatisfied();

}

@Configuration

public static class ContextConfig extends SingleRouteCamelConfiguration {

@Bean

public RouteBuilder route() {

return new RouteBuilder() {

public void configure() {

from("direct:start").filter(header("foo").isEqualTo("bar")).to("mock:result");

}

};

}

This is similar to the XML Cong example above except that there is no XML

le and instead the nested ContextCong class does all of the

conguration; so your entire test case is contained in a single Java class. We

currently have to reference by class name this class in the

@ContextConguration which is a bit ugly. Please vote for SJC-238 to

address this and make Spring Test work more cleanly with Spring JavaCong.

Its totally optional but for the ContextCong implementation we derive

from SingleRouteCamelConguration which is a helper Spring Java Cong

class which will congure the CamelContext for us and then register the

RouteBuilder we create.

Testing endpoints

Camel provides a number of endpoints which can make testing easier.

COOKBOOK 80

Name Description

DataSet

For load & soak testing this endpoint provides a way to create

huge numbers of messages for sending to Components and

asserting that they are consumed correctly

Mock For testing routes and mediation rules using mocks and allowing

assertions to be added to an endpoint

Test

Creates a Mock endpoint which expects to receive all the

message bodies that could be polled from the given underlying

endpoint

The main endpoint is the Mock endpoint which allows expectations to be

added to dierent endpoints; you can then run your tests and assert that

your expectations are met at the end.

Stubbing out physical transport technologies

If you wish to test out a route but want to avoid actually using a real physical

transport (for example to unit test a transformation route rather than

performing a full integration test) then the following endpoints can be useful.

Name Description

Direct

Direct invocation of the consumer from the producer so that

single threaded (non-SEDA) in VM invocation is performed which

can be useful to mock out physical transports

SEDA

Delivers messages asynchonously to consumers via a

java.util.concurrent.BlockingQueue which is good for testing

asynchronous transports

Testing existing routes

Camel provides some features to aid during testing of existing routes where

you cannot or will not use Mock etc. For example you may have a production

ready route which you want to test with some 3rd party API which sends

messages into this route.

Name Description

NotifyBuilder

Allows you to be notied when a certain condition has

occurred. For example when the route has completed 5

messages. You can build complex expressions to match

your criteria when to be notied.

81 COOKBOOK

AdviceWith

Allows you to advice or enhance an existing route using a

RouteBuilder style. For example you can add interceptors

to intercept sending outgoing messages to assert those

messages are as expected.

CAMEL TEST

As a simple alternative to using Spring Testing or Guice the camel-test

module was introduced into the Camel 2.0 trunk so you can perform powerful

Testing of your Enterprise Integration Patterns easily.

Adding to your pom.xml

To get started using Camel Test you will need to add an entry to your

pom.xml

JUnit

<groupId>org.apache.camel</groupId>

<artifactId>camel-test</artifactId>

<version>${camel-version}</version>

</dependency>

TestNG

Available as of Camel 2.8

<groupId>org.apache.camel</groupId>

<artifactId>camel-testng</artifactId>

<version>${camel-version}</version>

</dependency>

You might also want to add slf4j and log4j to ensure nice logging messages

(and maybe adding a log4j.properties le into your src/test/resources

directory).

COOKBOOK 82

The camel-test JAR is using JUnit. There is an alternative camel-

testng JAR (Camel 2.8 onwards) using the TestNG test framework.

</dependency>

</dependency>

Writing your test

You rstly need to derive from the class CamelTestSupport and typically

you will need to override the createRouteBuilder() method to create routes

to be tested.

Here is an example.

public class FilterTest extends CamelTestSupport {

@EndpointInject(uri = "mock:result")

protected MockEndpoint resultEndpoint;

@Produce(uri = "direct:start")

protected ProducerTemplate template;

@Test

public void testSendMatchingMessage() throws Exception {

String expectedBody = "<matched/>";

resultEndpoint.expectedBodiesReceived(expectedBody);

template.sendBodyAndHeader(expectedBody, "foo","bar");

resultEndpoint.assertIsSatisfied();

}

@Test

public void testSendNotMatchingMessage() throws Exception {

resultEndpoint.expectedMessageCount(0);

template.sendBodyAndHeader("<notMatched/>","foo","notMatchedHeaderValue");

83 COOKBOOK

resultEndpoint.assertIsSatisfied();

}

@Override

protected RouteBuilder createRouteBuilder() {

return new RouteBuilder() {

public void configure() {

from("direct:start").filter(header("foo").isEqualTo("bar")).to("mock:result");

}

};

}

Notice how you can use the various Camel binding and injection annotations

to inject individual Endpoint objects - particularly the Mock endpoints which

are very useful for Testing. Also you can inject producer objects such as

ProducerTemplate or some application code interface for sending messages

or invoking services.

JNDI

Camel uses a Registry to allow you to congure Component or Endpoint

instances or Beans used in your routes. If you are not using Spring or [OSGi]

then JNDI is used as the default registry implementation.

So you will also need to create a jndi.properties le in your src/test/

resources directory so that there is a default registry available to initialise

the CamelContext.

Here is an example jndi.properties le

java.naming.factory.initial = org.apache.camel.util.jndi.CamelInitialContextFactory

Dynamically assigning ports

Available as of Camel 2.7

Tests that use port numbers will fail if that port is already on use.

AvailablePortFinder provides methods for nding unused port numbers at

runtime.

// Get the next available port number starting from the default starting port of 1024

int port1 = AvailablePortFinder.getNextAvailable();

* Get another port. Note that just getting a port number does not reserve it so

* we look starting one past the last port number we got.

COOKBOOK 84

int port2 = AvailablePortFinder.getNextAvailable(port1 + 1);

Setup CamelContext once per class, or per every test method

Available as of Camel 2.8

The Camel Test kit will by default setup and shutdown CamelContext per

every test method in your test class. So for example if you have 3 test

methods, then CamelContext is started and shutdown after each test, that is

3 times.

You may want to do this once, to share the CamelContext between test

methods, to speedup unit testing. This requires to use JUnit 4! In your unit

test method you have to extend the

org.apache.camel.test.junit4.CamelTestSupport or the

org.apache.camel.test.junit4.CamelSpringTestSupport test class and

override the isCreateCamelContextPerClass method and return true as

shown in the following example:

Listing 13. Setup CamelContext once per class

public class FilterCreateCamelContextPerClassTest extends CamelTestSupport {

@EndpointInject(uri = "mock:result")

protected MockEndpoint resultEndpoint;

@Produce(uri = "direct:start")

protected ProducerTemplate template;

@Override

public boolean isCreateCamelContextPerClass() {

// we override this method and return true, to tell Camel test-kit that

// it should only create CamelContext once (per class), so we will

// re-use the CamelContext between each test method in this class

return true;

}

@Test

public void testSendMatchingMessage() throws Exception {

String expectedBody = "<matched/>";

resultEndpoint.expectedBodiesReceived(expectedBody);

template.sendBodyAndHeader(expectedBody, "foo","bar");

resultEndpoint.assertIsSatisfied();

}

@Test

public void testSendNotMatchingMessage() throws Exception {

85 COOKBOOK

TestNG

This feature is also supported in camel-testng

Beware

When using this the CamelContext will keep state between tests, so

have that in mind. So if your unit tests start to fail for no apparent

reason, it could be due this fact. So use this feature with a bit of

care.

resultEndpoint.expectedMessageCount(0);

template.sendBodyAndHeader("<notMatched/>","foo","notMatchedHeaderValue");

resultEndpoint.assertIsSatisfied();

}

@Override

protected RouteBuilder createRouteBuilder() {

return new RouteBuilder() {

public void configure() {

from("direct:start").filter(header("foo").isEqualTo("bar")).to("mock:result");

}

};

}

See Also

• Testing

• Mock

• Test

SPRING TESTING

Testing is a crucial part of any development or integration work. The Spring

Framework oers a number of features that makes it easy to test while using

Spring for Inversion of Control which works with JUnit 3.x, JUnit 4.x or TestNG.

COOKBOOK 86

We can reuse Spring for IoC and the Camel Mock and Test endpoints to

create sophisticated integration tests that are easy to run and debug inside

your IDE.

For example here is a simple unit test

import org.apache.camel.CamelContext;

import org.apache.camel.component.mock.MockEndpoint;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.test.context.ContextConfiguration;

import org.springframework.test.context.junit38.AbstractJUnit38SpringContextTests;

@ContextConfiguration

public class MyCamelTest extends AbstractJUnit38SpringContextTests {

@Autowired

protected CamelContext camelContext;

public void testMocksAreValid() throws Exception {

MockEndpoint.assertIsSatisfied(camelContext);

}

This test will load a Spring XML conguration le called MyCamelTest-

context.xml from the classpath in the same package structure as the

MyCamelTest class and initialize it along with any Camel routes we dene

inside it, then inject the CamelContext instance into our test case.

For instance, like this maven folder layout:

src/main/java/com/mycompany/MyCamelTest.class

src/main/resources/com/mycompany/MyCamelTest-context.xml

You can overload the method createApplicationContext to provide the

Spring ApplicationContext that isn't following the above default. For instance:

protected AbstractXmlApplicationContext createApplicationContext() {

return new ClassPathXmlApplicationContext("/config/MySpringConfig.xml");

}

Then the test method will then run which invokes the

MockEndpoint.assertIsSatised(camelContext) method which asserts that all

of the Mock and Test endpoints have their expectations met.

xml}

Spring Test with Java Cong Example

You can completely avoid using an XML conguration le by using Spring

Java Cong.

87 COOKBOOK

Here is an example using Java Cong.

@ContextConfiguration(

locations =

"org.apache.camel.spring.javaconfig.patterns.FilterTest$ContextConfig",

loader = JavaConfigContextLoader.class)

public class FilterTest extends AbstractJUnit4SpringContextTests {

@EndpointInject(uri = "mock:result")

protected MockEndpoint resultEndpoint;

@Produce(uri = "direct:start")

protected ProducerTemplate template;

@DirtiesContext

@Test

public void testSendMatchingMessage() throws Exception {

String expectedBody = "<matched/>";

resultEndpoint.expectedBodiesReceived(expectedBody);

template.sendBodyAndHeader(expectedBody, "foo","bar");

resultEndpoint.assertIsSatisfied();

}

@DirtiesContext

@Test

public void testSendNotMatchingMessage() throws Exception {

resultEndpoint.expectedMessageCount(0);

template.sendBodyAndHeader("<notMatched/>","foo","notMatchedHeaderValue");

resultEndpoint.assertIsSatisfied();

}

@Configuration

public static class ContextConfig extends SingleRouteCamelConfiguration {

@Bean

public RouteBuilder route() {

return new RouteBuilder() {

public void configure() {

from("direct:start").filter(header("foo").isEqualTo("bar")).to("mock:result");

}

};

}

This is similar to the XML Cong example above except that there is no XML

le and instead the nested ContextCong class does all of the

conguration; so your entire test case is contained in a single Java class. We

currently have to reference by class name this class in the

COOKBOOK 88

@ContextConguration which is a bit ugly. Please vote for SJC-238 to

address this and make Spring Test work more cleanly with Spring JavaCong.

Adding more Mock expectations

If you wish to programmatically add any new assertions to your test you can

easily do so with the following. Notice how we use @EndpointInject to inject a

Camel endpoint into our code then the Mock API to add an expectation on a

specic message.

@ContextConfiguration

public class MyCamelTest extends AbstractJUnit38SpringContextTests {

@Autowired

protected CamelContext camelContext;

@EndpointInject(uri = "mock:foo")

protected MockEndpoint foo;

public void testMocksAreValid() throws Exception {

// lets add more expectations

foo.message(0).header("bar").isEqualTo("ABC");

MockEndpoint.assertIsSatisfied(camelContext);

}

Further processing the received messages

Sometimes once a Mock endpoint has received some messages you want to

then process them further to add further assertions that your test case

worked as you expect.

So you can then process the received message exchanges if you like...

@ContextConfiguration

public class MyCamelTest extends AbstractJUnit38SpringContextTests {

@Autowired

protected CamelContext camelContext;

@EndpointInject(uri = "mock:foo")

protected MockEndpoint foo;

public void testMocksAreValid() throws Exception {

// lets add more expectations...

MockEndpoint.assertIsSatisfied(camelContext);

89 COOKBOOK

// now lets do some further assertions

List<Exchange> list = foo.getReceivedExchanges();

for (Exchange exchange : list) {

Message in = exchange.getIn();

...

}

Sending and receiving messages

It might be that the Enterprise Integration Patterns you have dened in either

Spring XML or using the Java DSL do all of the sending and receiving and you

might just work with the Mock endpoints as described above. However

sometimes in a test case its useful to explicitly send or receive messages

directly.

To send or receive messages you should use the Bean Integration

mechanism. For example to send messages inject a ProducerTemplate using

the @EndpointInject annotation then call the various send methods on this

object to send a message to an endpoint. To consume messages use the

@MessageDriven annotation on a method to have the method invoked when

a message is received.

public class Foo {

@EndpointInject(uri="activemq:foo.bar")

ProducerTemplate producer;

public void doSomething() {

// lets send a message!

producer.sendBody("<hello>world!</hello>");

}

// lets consume messages from the 'cheese' queue

@MessageDriven(uri="activemq:cheese")

public void onCheese(String name) {

...

}

See Also

• a real example test case using Mock and Spring along with its Spring

XML

• Bean Integration

• Mock endpoint

• Test endpoint

COOKBOOK 90

CAMEL GUICE

As of 1.5 we now have support for Google Guice as a dependency injection

framework. To use it just be dependent on camel-guice.jar which also

depends on the following jars.

Dependency Injecting Camel with Guice

The GuiceCamelContext is designed to work nicely inside Guice. You then

need to bind it using some Guice Module.

The camel-guice library comes with a number of reusable Guice Modules

you can use if you wish - or you can bind the GuiceCamelContext yourself in

your own module.

• CamelModule is the base module which binds the

GuiceCamelContext but leaves it up you to bind the RouteBuilder

instances

• CamelModuleWithRouteTypes extends CamelModule so that in the

constructor of the module you specify the RouteBuilder classes or

instances to use

• CamelModuleWithMatchingRoutes extends CamelModule so that all

bound RouteBuilder instances will be injected into the CamelContext

or you can supply an optional Matcher to nd RouteBuilder instances

matching some kind of predicate.

So you can specify the exact RouteBuilder instances you want

Injector injector = Guice.createInjector(new

CamelModuleWithRouteTypes(MyRouteBuilder.class, AnotherRouteBuilder.class));

// if required you can lookup the CamelContext

CamelContext camelContext = injector.getInstance(CamelContext.class);

Or inject them all

Injector injector = Guice.createInjector(new CamelModuleWithRouteTypes());

// if required you can lookup the CamelContext

CamelContext camelContext = injector.getInstance(CamelContext.class);

You can then use Guice in the usual way to inject the route instances or any

other dependent objects.

Bootstrapping with JNDI

A common pattern used in J2EE is to bootstrap your application or root

objects by looking them up in JNDI. This has long been the approach when

91 COOKBOOK

working with JMS for example - looking up the JMS ConnectionFactory in JNDI

for example.

You can follow a similar pattern with Guice using the GuiceyFruit JNDI

Provider which lets you bootstrap Guice from a jndi.properties le which

can include the Guice Modules to create along with environment specic

properties you can inject into your modules and objects.

If the jndi.properties is conict with other component, you can specify

the jndi properties le name in the Guice Main with option -j or -jndiProperties

with the properties le location to let Guice Main to load right jndi properties

le.

Conguring Component, Endpoint or RouteBuilder instances

You can use Guice to dependency inject whatever objects you need to create,

be it an Endpoint, Component, RouteBuilder or arbitrary bean used within a

route.

The easiest way to do this is to create your own Guice Module class which

extends one of the above module classes and add a provider method for

each object you wish to create. A provider method is annotated with

@Provides as follows

public class MyModule extends CamelModuleWithMatchingRoutes {

@Provides

@JndiBind("jms")

JmsComponent jms(@Named("activemq.brokerURL")String brokerUrl) {

return JmsComponent.jmsComponent(new ActiveMQConnectionFactory(brokerUrl));

}

You can optionally annotate the method with @JndiBind to bind the object to

JNDI at some name if the object is a component, endpoint or bean you wish

to refer to by name in your routes.

You can inject any environment specic properties (such as URLs, machine

names, usernames/passwords and so forth) from the jndi.properties le

easily using the @Named annotation as shown above. This allows most of

your conguration to be in Java code which is typesafe and easily

refactorable - then leaving some properties to be environment specic (the

jndi.properties le) which you can then change based on development,

testing, production etc.

COOKBOOK 92

Creating multiple RouteBuilder instances per type

It is sometimes useful to create multiple instances of a particular

RouteBuilder with dierent congurations.

To do this just create multiple provider methods for each conguration; or

create a single provider method that returns a collection of RouteBuilder

instances.

For example

import org.apache.camel.guice.CamelModuleWithMatchingRoutes;

import com.google.common.collect.Lists;

public class MyModule extends CamelModuleWithMatchingRoutes {

@Provides

@JndiBind("foo")

Collection<RouteBuilder> foo(@Named("fooUrl")String fooUrl) {

return Lists.newArrayList(new MyRouteBuilder(fooUrl), new

MyRouteBuilder("activemq:CheeseQueue"));

}

See Also

• there are a number of Examples you can look at to see Guice and

Camel being used such as Guice JMS Example

• Guice Maven Plugin for running your Guice based routes via Maven

TEMPLATING

When you are testing distributed systems its a very common requirement to

have to stub out certain external systems with some stub so that you can

test other parts of the system until a specic system is available or written

etc.

A great way to do this is using some kind of Template system to generate

responses to requests generating a dynamic message using a mostly-static

body.

There are a number of templating components included in the Camel

distribution you could use

• FreeMarker

• StringTemplate

• Velocity

• XQuery

• XSLT

93 COOKBOOK

or the following external Camel components

• Scalate

Example

Here's a simple example showing how we can respond to InOut requests on

the My.Queue queue on ActiveMQ with a template generated response. The

reply would be sent back to the JMSReplyTo Destination.

from("activemq:My.Queue").

to("velocity:com/acme/MyResponse.vm");

If you want to use InOnly and consume the message and send it to another

destination you could use

from("activemq:My.Queue").

to("velocity:com/acme/MyResponse.vm").

to("activemq:Another.Queue");

See Also

• Mock for details of mock endpoint testing (as opposed to template

based stubs).

DATABASE

Camel can work with databases in a number of dierent ways. This

document tries to outline the most common approaches.

Database endpoints

Camel provides a number of dierent endpoints for working with databases

• JPA for working with hibernate, openjpa or toplink. When consuming

from the endpoints entity beans are read (and deleted/updated to

mark as processed) then when producing to the endpoints they are

written to the database (via insert/update).

• iBATIS similar to the above but using Apache iBATIS

• JDBC similar though using explicit SQL

Database pattern implementations

Various patterns can work with databases as follows

• Idempotent Consumer

COOKBOOK 94

• Aggregator

• BAM for business activity monitoring

PARALLEL PROCESSING AND ORDERING

It is a common requirement to want to use parallel processing of messages

for throughput and load balancing, while at the same time process certain

kinds of messages in order.

How to achieve parallel processing

You can send messages to a number of Camel Components to achieve

parallel processing and load balancing such as

• SEDA for in-JVM load balancing across a thread pool

• ActiveMQ or JMS for distributed load balancing and parallel

processing

• JPA for using the database as a poor mans message broker

When processing messages concurrently, you should consider ordering and

concurrency issues. These are described below

Concurrency issues

Note that there is no concurrency or locking issue when using ActiveMQ, JMS

or SEDA by design; they are designed for highly concurrent use. However

there are possible concurrency issues in the Processor of the messages i.e.

what the processor does with the message?

For example if a processor of a message transfers money from one

account to another account; you probably want to use a database with

pessimistic locking to ensure that operation takes place atomically.

Ordering issues

As soon as you send multiple messages to dierent threads or processes you

will end up with an unknown ordering across the entire message stream as

each thread is going to process messages concurrently.

For many use cases the order of messages is not too important. However

for some applications this can be crucial. e.g. if a customer submits a

purchase order version 1, then amends it and sends version 2; you don't

want to process the rst version last (so that you loose the update). Your

Processor might be clever enough to ignore old messages. If not you need to

preserve order.

95 COOKBOOK

Recommendations

This topic is large and diverse with lots of dierent requirements; but from a

high level here are our recommendations on parallel processing, ordering

and concurrency

• for distributed locking, use a database by default, they are very good

at it

• to preserve ordering across a JMS queue consider using Exclusive

Consumers in the ActiveMQ component

• even better are Message Groups which allows you to preserve

ordering across messages while still oering parallelisation via the

JMSXGrouopID header to determine what can be parallelized

• if you receive messages out of order you could use the Resequencer

to put them back together again

A good rule of thumb to help reduce ordering problems is to make sure each

single can be processed as an atomic unit in parallel (either without

concurrency issues or using say, database locking); or if it can't, use a

Message Group to relate the messages together which need to be processed

in order by a single thread.

Using Message Groups with Camel

To use a Message Group with Camel you just need to add a header to the

output JMS message based on some kind of Correlation Identier to correlate

messages which should be processed in order by a single thread - so that

things which don't correlate together can be processed concurrently.

For example the following code shows how to create a message group

using an XPath expression taking an invoice's product code as the Correlation

Identier

from("activemq:a").setHeader("JMSXGroupID", xpath("/invoice/

productCode")).to("activemq:b");

You can of course use the Xml Conguration if you prefer

ASYNCHRONOUS PROCESSING

Overview

Camel supports a more complex asynchronous processing model. The

asynchronous processors implement the AsyncProcessor interface which is

derived from the more synchronous Processor interface. There are

COOKBOOK 96

Supported versions

The information on this page applies for the Camel 1.x and Camel

2.4 onwards. In Camel 1.x the asynchronous processing is only

implemented for JBI where as in Camel 2.4 onwards we have

implemented it in many other areas. See more at Asynchronous

Routing Engine.

advantages and disadvantages when using asynchronous processing when

compared to using the standard synchronous processing model.

Advantages:

• Processing routes that are composed fully of asynchronous

processors do not use up threads waiting for processors to complete

on blocking calls. This can increase the scalability of your system by

reducing the number of threads needed to process the same

workload.

• Processing routes can be broken up into SEDA processing stages

where dierent thread pools can process the dierent stages. This

means that your routes can be processed concurrently.

Disadvantages:

• Implementing asynchronous processors is more complex than

implementing the synchronous versions.

When to Use

We recommend that processors and components be implemented the more

simple synchronous APIs unless you identify a performance of scalability

requirement that dictates otherwise. A Processor whose process() method

blocks for a long time would be good candidates for being converted into an

asynchronous processor.

Interface Details

public interface AsyncProcessor extends Processor {

boolean process(Exchange exchange, AsyncCallback callback);

}

The AsyncProcessor denes a single process() method which is very similar

to it's synchronous Processor.process() brethren. Here are the dierences:

• A non-null AsyncCallback MUST be supplied which will be notied

when the exchange processing is completed.

97 COOKBOOK

• It MUST not throw any exceptions that occurred while processing the

exchange. Any such exceptions must be stored on the exchange's

Exception property.

• It MUST know if it will complete the processing synchronously or

asynchronously. The method will return true if it does complete

synchronously, otherwise it returns false.

• When the processor has completed processing the exchange, it must

call the callback.done(boolean sync) method. The sync

parameter MUST match the value returned by the process()

method.

Implementing Processors that Use the AsyncProcessor API

All processors, even synchronous processors that do not implement the

AsyncProcessor interface, can be coerced to implement the AsyncProcessor

interface. This is usually done when you are implementing a Camel

component consumer that supports asynchronous completion of the

exchanges that it is pushing through the Camel routes. Consumers are

provided a Processor object when created. All Processor object can be

coerced to a AsyncProcessor using the following API:

Processor processor = ...

AsyncProcessor asyncProcessor = AsyncProcessorTypeConverter.convert(processor);

For a route to be fully asynchronous and reap the benets to lower Thread

usage, it must start with the consumer implementation making use of the

asynchronous processing API. If it called the synchronous process() method

instead, the consumer's thread would be forced to be blocked and in use for

the duration that it takes to process the exchange.

It is important to take note that just because you call the asynchronous

API, it does not mean that the processing will take place asynchronously. It

only allows the possibility that it can be done without tying up the caller's

thread. If the processing happens asynchronously is dependent on the

conguration of the Camel route.

Normally, the the process call is passed in an inline inner AsyncCallback

class instance which can reference the exchange object that was declared

nal. This allows it to nish up any post processing that is needed when the

called processor is done processing the exchange. See below for an example.

final Exchange exchange = ...

AsyncProcessor asyncProcessor = ...

asyncProcessor.process(exchange, new AsyncCallback() {

public void done(boolean sync) {

COOKBOOK 98

if (exchange.isFailed()) {

... // do failure processing.. perhaps rollback etc.

}else {

... // processing completed successfully, finish up

// perhaps commit etc.

}

});

Asynchronous Route Sequence Scenarios

Now that we have understood the interface contract of the AsyncProcessor,

and have seen how to make use of it when calling processors, lets looks a

what the thread model/sequence scenarios will look like for some sample

routes.

The Jetty component's consumers support async processing by using

continuations. Suce to say it can take a http request and pass it to a camel

route for async processing. If the processing is indeed async, it uses Jetty

continuation so that the http request is 'parked' and the thread is released.

Once the camel route nishes processing the request, the jetty component

uses the AsyncCallback to tell Jetty to 'un-park' the request. Jetty un-parks

the request, the http response returned using the result of the exchange

processing.

Notice that the jetty continuations feature is only used "If the processing is

indeed async". This is why AsyncProcessor.process() implementations MUST

accurately report if request is completed synchronously or not.

The jhc component's producer allows you to make HTTP requests and

implement the AsyncProcessor interface. A route that uses both the jetty

asynchronous consumer and the jhc asynchronous producer will be a fully

asynchronous route and has some nice attributes that can be seen if we take

a look at a sequence diagram of the processing route. For the route:

from("jetty:http://localhost:8080/service").to("jhc:http://localhost/service-impl");

The sequence diagram would look something like this:

99 COOKBOOK

The diagram simplies things by making it looks like processors implement

the AsyncCallback interface when in reality the AsyncCallback interfaces are

inline inner classes, but it illustrates the processing ow and shows how 2

separate threads are used to complete the processing of the original http

request. The rst thread is synchronous up until processing hits the jhc

producer which issues the http request. It then reports that the exchange

processing will complete async since it will use a NIO to complete getting the

response back. Once the jhc component has received a full response it uses

AsyncCallback.done() method to notify the caller. These callback

notications continue up until it reaches the original jetty consumer which

then un-parks the http request and completes it by providing the response.

Mixing Synchronous and Asynchronous Processors

It is totally possible and reasonable to mix the use of synchronous and

asynchronous processors/components. The pipeline processor is the

backbone of a Camel processing route. It glues all the processing steps

together. It is implemented as an AsyncProcessor and supports interleaving

synchronous and asynchronous processors as the processing steps in the

pipeline.

Lets say we have 2 custom processors, MyValidator and MyTransformation,

both of which are synchronous processors. Lets say we want to load le from

the data/in directory validate them with the MyValidator() processor,

Transform them into JPA java objects using MyTransformation and then insert

them into the database using the JPA component. Lets say that the

transformation process takes quite a bit of time and we want to allocate 20

threads to do parallel transformations of the input les. The solution is to

COOKBOOK 100

make use of the thread processor. The thread is AsyncProcessor that forces

subsequent processing in asynchronous thread from a thread pool.

The route might look like:

from("file:data/in").process(new MyValidator()).threads(20).process(new

MyTransformation()).to("jpa:PurchaseOrder");

The sequence diagram would look something like this:

You would actually have multiple threads executing the 2nd part of the

thread sequence.

Staying synchronous in an AsyncProcessor

Generally speaking you get better throughput processing when you process

things synchronously. This is due to the fact that starting up an asynchronous

thread and doing a context switch to it adds a little bit of of overhead. So it is

generally encouraged that AsyncProcessors do as much work as they can

synchronously. When they get to a step that would block for a long time, at

that point they should return from the process call and let the caller know

that it will be completing the call asynchronously.

101 COOKBOOK

IMPLEMENTING VIRTUAL TOPICS ON OTHER JMS

PROVIDERS

ActiveMQ supports Virtual Topics since durable topic subscriptions kinda suck

(see this page for more detail) mostly since they don't support Competing

Consumers.

Most folks want Queue semantics when consuming messages; so that you

can support Competing Consumers for load balancing along with things like

Message Groups and Exclusive Consumers to preserve ordering or partition

the queue across consumers.

However if you are using another JMS provider you can implement Virtual

Topics by switching to ActiveMQ or you can use the following Camel

pattern.

First here's the ActiveMQ approach.

• send to activemq:topic:VirtualTopic.Orders

• for consumer A consume from

activemq:Consumer.A.VirtualTopic.Orders

When using another message broker use the following pattern

• send to jms:Orders

• add this route with a to() for each logical durable topic subscriber

from("jms:Orders").to("jms:Consumer.A","jms:Consumer.B", ...);

• for consumer A consume from jms:Consumer.A

WHAT'S THE CAMEL TRANSPORT FOR CXF

In CXF you oer or consume a webservice by dening it´s address. The rst

part of the address species the protocol to use. For example

address="http://localhost:90000" in an endpoint conguration means your

service will be oered using the http protocol on port 9000 of localhost.

When you integrate Camel Tranport into CXF you get a new transport

"camel". So you can specify address="camel://direct:MyEndpointName" to

bind the CXF service address to a camel direct endpoint.

Technically speaking Camel transport for CXF is a component which

implements the CXF transport API with the Camel core library. This allows you

to use camel´s routing engine and integration patterns support smoothly

together with your CXF services.

COOKBOOK 102

INTEGRATE CAMEL INTO CXF TRANSPORT LAYER

To include the Camel Tranport into your CXF bus you use the

CamelTransportFactory. You can do this in Java as well as in Spring.

Setting up the Camel Transport in Spring

You can use the following snippet in your applicationcontext if you want to

congure anything special. If you only want to activate the camel transport

you do not have to do anything in your application context. As soon as you

include the camel-cxf jar in your app cxf will scan the jar and load a

CamelTransportFactory for you.

<!-- If checkException is true , CamelDestination will check the outMessage's

exception and set it into camel exchange. You can also override this value

in CamelDestination's configuration. The default value is false.

This option should be set true when you want to leverage the camel's error

handler to deal with fault message -->

<list>

<value>http://cxf.apache.org/transports/camel</value>

</list>

</property>

</bean>

Integrating the Camel Transport in a programmatic way

Camel transport provides a setContext method that you could use to set the

Camel context into the transport factory. If you want this factory take eect,

you need to register the factory into the CXF bus. Here is a full example for

you.

import org.apache.cxf.Bus;

import org.apache.cxf.BusFactory;

import org.apache.cxf.transport.ConduitInitiatorManager;

import org.apache.cxf.transport.DestinationFactoryManager;

...

BusFactory bf = BusFactory.newInstance();

Bus bus = bf.createBus();

CamelTransportFactory camelTransportFactory = new CamelTransportFactory();

camelTransportFactory.setCamelContext(context)

// register the conduit initiator

103 COOKBOOK

ConduitInitiatorManager cim = bus.getExtension(ConduitInitiatorManager.class);

cim.registerConduitInitiator(CamelTransportFactory.TRANSPORT_ID,

camelTransportFactory);

// register the destination factory

DestinationFactoryManager dfm = bus.getExtension(DestinationFactoryManager.class);

dfm.registerDestinationFactory(CamelTransportFactory.TRANSPORT_ID,

camelTransportFactory);

// set or bus as the default bus for cxf

BusFactory.setDefaultBus(bus);

CONFIGURE THE DESTINATION AND CONDUIT

Namespace

The elements used to congure an Camel transport endpoint are dened in

the namespace http://cxf.apache.org/transports/camel. It is commonly

referred to using the prex camel. In order to use the Camel transport

conguration elements you will need to add the lines shown below to the

beans element of your endpoint's conguration le. In addition, you will need

to add the conguration elements' namespace to the xsi:schemaLocation

attribute.

Listing 14. Adding the Conguration Namespace

<beans ...

xmlns:camel="http://cxf.apache.org/transports/camel

...

xsi:schemaLocation="...

http://cxf.apache.org/transports/camel

http://cxf.apache.org/transports/camel.xsd

...>

The destination element

You congure an Camel transport server endpoint using the

camel:destination element and its children. The camel:destination

element takes a single attribute, name, the species the WSDL port element

that corresponds to the endpoint. The value for the name attribute takes the

form portQName.camel-destination. The example below shows the

camel:destination element that would be used to add conguration for an

endpoint that was specied by the WSDL fragment <port

binding="widgetSOAPBinding" name="widgetSOAPPort> if the endpoint's

target namespace was http://widgets.widgetvendor.net.

Listing 15. camel:destination Element

COOKBOOK 104

...

<camel:destination name="{http://widgets/

widgetvendor.net}widgetSOAPPort.http-destination>

<route>

</route>

</camelContext>

</camel:destination>

...

The camel:destination element has a number of child elements that

specify conguration information. They are described below.

Element Description

camel-

spring:camelContext

You can specify the camel context in the camel

destination

camel:camelContextRef The camel context id which you want inject

into the camel destination

The conduit element

You congure an Camel transport client using the camel:conduit element

and its children. The camel:conduit element takes a single attribute, name,

that species the WSDL port element that corresponds to the endpoint. The

value for the name attribute takes the form portQName.camel-conduit. For

example, the code below shows the camel:conduit element that would be

used to add conguration for an endpoint that was specied by the WSDL

fragment <port binding="widgetSOAPBinding" name="widgetSOAPPort> if

the endpoint's target namespace was http://widgets.widgetvendor.net.

Listing 16. http-conf:conduit Element

...

<camelContext id="conduit_context" xmlns="http://activemq.apache.org/camel/schema/

spring">

<route>

</route>

</camelContext>

<camel:conduit name="{http://widgets/widgetvendor.net}widgetSOAPPort.camel-conduit">

<camel:camelContextRef>conduit_context</camel:camelContextRef>

</camel:conduit>

105 COOKBOOK

<camel:conduit name="*.camel-conduit">

<!-- you can also using the wild card to specify the camel-conduit that you want to

configure -->

...

</camel:conduit>

...

The camel:conduit element has a number of child elements that specify

conguration information. They are described below.

Element Description

camel-

spring:camelContext

You can specify the camel context in the camel

conduit

camel:camelContextRef The camel context id which you want inject

into the camel conduit

EXAMPLE USING CAMEL AS A LOAD BALANCER FOR CXF

This example show how to use the camel load balance feature in CXF, and

you need load the conguration le in CXF and publish the endpoints on the

address "camel://direct:EndpointA" and "camel://direct:EndpointB"

<beans xmlns="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:camel="http://cxf.apache.org/transports/camel"

xsi:schemaLocation="

http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans.xsd

http://cxf.apache.org/transports/camel http://cxf.apache.org/transports/

camel.xsd

http://camel.apache.org/schema/cxf http://camel.apache.org/schema/cxf/

cxfEndpoint.xsd

http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/

camel-spring.xsd

<bean id = "roundRobinRef"

class="org.apache.camel.processor.loadbalancer.RoundRobinLoadBalancer" />

<route>

</loadBalance>

</route>

COOKBOOK 106

</camelContext>

<camel:destination name="{http://apache.org/

hello_world_soap_http}CamelPort.camel-destination">

<camel:camelContextRef>dest_context</camel:camelContextRef>

</camel:destination>

</beans>

COMPLETE HOWTO AND EXAMPLE FOR ATTACHING

CAMEL TO CXF

Better JMS Transport for CXF Webservice using Apache Camel

Introduction

When sending an Exchange to an Endpoint you can either use a Route or a

ProducerTemplate. This works ne in many scenarios. However you may

need to guarantee that an exchange is delivered to the same endpoint that

you delivered a previous exchange on. For example in the case of delivering

a batch of exchanges to a MINA socket you may need to ensure that they are

all delivered through the same socket connection. Furthermore once the

batch of exchanges have been delivered the protocol requirements may be

such that you are responsible for closing the socket.

Using a Producer

To achieve ne grained control over sending exchanges you will need to

program directly to a Producer. Your code will look similar to:

CamelContext camelContext = ...

// Obtain an endpoint and create the producer we will be using.

Endpoint endpoint = camelContext.getEndpoint("someuri:etc");

Producer producer = endpoint.createProducer();

producer.start();

try {

107 INTRODUCTION

// For each message to send...

Object requestMessage = ...

Exchange exchangeToSend = producer.createExchange();

exchangeToSend().setBody(requestMessage);

producer.process(exchangeToSend);

...

}finally {

// Tidy the producer up.

producer.stop();

}

In the case of using Apache MINA the producer.stop() invocation will cause

the socket to be closed.

USING A PRODUCER 108

Tutorials

There now follows the documentation on camel tutorials

• OAuth Tutorial

This tutorial demonstrates how to implement OAuth for a web

application with Camel's gauth component. The sample application of

this tutorial is also online at http://gauthcloud.appspot.com/

• Tutorial for Camel on Google App Engine

This tutorial demonstrates the usage of the Camel Components for

Google App Engine. The sample application of this tutorial is also

online at http://camelcloud.appspot.com/

• Tutorial on Spring Remoting with JMS

This tutorial is focused on dierent techniques with Camel for Client-

Server communication.

• Report Incident - This tutorial introduces Camel steadily and is based

on a real life integration problem

This is a very long tutorial beginning from the start; its for entry level

to Camel. Its based on a real life integration, showing how Camel can

be introduced in an existing solution. We do this in baby steps. The

tutorial is currently work in progress, so check it out from time to

time. The tutorial explains some of the inner building blocks Camel

uses under the covers. This is good knowledge to have when you

start using Camel on a higher abstract level where it can do wonders

in a few lines of routing DSL.

• Using Camel with ServiceMix a tutorial on using Camel inside Apache

ServiceMix.

• Better JMS Transport for CXF Webservice using Apache Camel

Describes how to use the Camel Transport for CXF to attach a CXF

Webservice to a JMS Queue

• Tutorial how to use good old Axis 1.4 with Camel

This tutorial shows that Camel does work with the good old

frameworks such as AXIS that is/was widely used for WebService.

• Tutorial on using Camel in a Web Application

This tutorial gives an overview of how to use Camel inside Tomcat,

Jetty or any other servlet engine

• Tutorial on Camel 1.4 for Integration

Another real-life scenario. The company sells widgets, with a

somewhat unique business process (their customers periodically

report what they've purchased in order to get billed). However every

customer uses a dierent data format and protocol. This tutorial goes

109 TUTORIALS

through the process of integrating (and testing!) several customers

and their electronic reporting of the widgets they've bought, along

with the company's response.

• Tutorial how to build a Service Oriented Architecture using Camel

with OSGI - Updated 20/11/2009

The tutorial has been designed in two parts. The rst part introduces

basic concept to create a simple SOA solution using Camel and OSGI

and deploy it in a OSGI Server like Apache Felix Karaf and Spring DM

Server while the second extends the ReportIncident tutorial part 4 to

show How we can separate the dierent layers (domain, service, ...)

of an application and deploy them in separate bundles. The Web

Application has also be modied in order to communicate to the OSGI

bundles.

• Several of the vendors on the Commercial Camel Oerings page also

oer various tutorials, webinars, examples, etc.... that may be useful.

• Examples

While not actual tutorials you might nd working through the source

of the various Examples useful.

TUTORIAL ON SPRING REMOTING WITH JMS

PREFACE

This tutorial aims to guide the reader through the stages of creating a project

which uses Camel to facilitate the routing of messages from a JMS queue to a

Spring service. The route works in a synchronous fashion returning a

response to the client.

• Tutorial on Spring Remoting with JMS

• Preface

• Prerequisites

• Distribution

• About

• Create the Camel Project

• Update the POM with Dependencies

• Writing the Server

• Create the Spring Service

• Dene the Camel Routes

• Congure Spring

• AOP Enabled Server

• Run the Server

TUTORIALS 110

Thanks

This tutorial was kindly donated to Apache Camel by Martin Gilday.

• Writing The Clients

• Client Using The ProducerTemplate

• Client Using Spring Remoting

• Client Using Message Endpoint EIP Pattern

• Run the Clients

• Using the Camel Maven Plugin

• Using Camel JMX

• See Also

PREREQUISITES

This tutorial uses Maven to setup the Camel project and for dependencies for

artifacts.

DISTRIBUTION

This sample is distributed with the Camel distribution as examples/camel-

example-spring-jms.

ABOUT

This tutorial is a simple example that demonstrates more the fact how well

Camel is seamless integrated with Spring to leverage the best of both worlds.

This sample is client server solution using JMS messaging as the transport.

The sample has two avors of servers and also for clients demonstrating

dierent techniques for easy communication.

The Server is a JMS message broker that routes incoming messages to a

business service that does computations on the received message and

returns a response.

The EIP patterns used in this sample are:

Pattern Description

Message

Channel

We need a channel so the Clients can communicate with the

server.

Message The information is exchanged using the Camel Message

interface.

111 TUTORIALS

Message

Translator

This is where Camel shines as the message exchange

between the Server and the Clients are text based strings with

numbers. However our business service uses int for numbers.

So Camel can do the message translation automatically.

Message

Endpoint

It should be easy to send messages to the Server from the the

clients. This is archived with Camels powerful Endpoint

pattern that even can be more powerful combined with Spring

remoting. The tutorial have clients using each kind of

technique for this.

Point to

Point

Channel

We using JMS queues so there are only one receive of the

message exchange

Event

Driven

Consumer

Yes the JMS broker is of course event driven and only reacts

when the client sends a message to the server.

We use the following Camel components:

Component Description

ActiveMQ We use Apache ActiveMQ as the JMS broker on the Server

side

Bean

We use the bean binding to easily route the messages to

our business service. This is a very powerful component in

Camel.

File In the AOP enabled Server we store audit trails as les.

JMS Used for the JMS messaging

CREATE THE CAMEL PROJECT

mvn archetype:create -DgroupId=org.example -DartifactId=CamelWithJmsAndSpring

Update the POM with Dependencies

First we need to have dependencies for the core Camel jars, its spring, jms

components and nally ActiveMQ as the message broker.

TUTORIALS 112

For the purposes of the tutorial a single Maven project will be used

for both the client and server. Ideally you would break your

application down into the appropriate components.

<groupId>org.apache.camel</groupId>

<artifactId>camel-core</artifactId>

</dependency>

<groupId>org.apache.camel</groupId>

<artifactId>camel-jms</artifactId>

</dependency>

<groupId>org.apache.camel</groupId>

<artifactId>camel-spring</artifactId>

</dependency>

<groupId>org.apache.activemq</groupId>

<artifactId>activemq-camel</artifactId>

</dependency>

As we use spring xml conguration for the ActiveMQ JMS broker we need this

dependency:

<groupId>org.apache.xbean</groupId>

<artifactId>xbean-spring</artifactId>

</dependency>

And dependencies for the AOP enable server example. These dependencies

are of course only needed if you need full blown AOP stu using AspejctJ with

bytecode instrumentation.

<groupId>org.springframework</groupId>

<artifactId>spring-aop</artifactId>

<version>${spring-version}</version>

</dependency>

<groupId>org.aspectj</groupId>

<artifactId>aspectjrt</artifactId>

</dependency>

<groupId>org.aspectj</groupId>

113 TUTORIALS

<artifactId>aspectjweaver</artifactId>

</dependency>

<groupId>cglib</groupId>

<artifactId>cglib-nodep</artifactId>

</dependency>

WRITING THE SERVER

Create the Spring Service

For this example the Spring service (= our business service) on the server

will be a simple multiplier which trebles in the received value.

public interface Multiplier {

/**

* Multiplies the given number by a pre-defined constant.

* @param originalNumber The number to be multiplied

* @return The result of the multiplication

int multiply(int originalNumber);

}

And the implementation of this service is:

@Service(value = "multiplier")

public class Treble implements Multiplier {

public int multiply(final int originalNumber) {

return originalNumber * 3;

}

Notice that this class has been annotated with the @Service spring

annotation. This ensures that this class is registered as a bean in the registry

with the given name multiplier.

TUTORIALS 114

Dene the Camel Routes

public class ServerRoutes extends RouteBuilder {

@Override

public void configure() throws Exception {

// route from the numbers queue to our business that is a spring bean

registered with the id=multiplier

// Camel will introspect the multiplier bean and find the best candidate of

the method to invoke.

// You can add annotations etc to help Camel find the method to invoke.

// As our multiplier bean only have one method its easy for Camel to find the

method to use.

from("jms:queue:numbers").to("multiplier");

// Camel has several ways to configure the same routing, we have defined some

of them here below

// as above but with the bean: prefix

//from("jms:queue:numbers").to("bean:multiplier");

// beanRef is using explicity bean bindings to lookup the multiplier bean and

invoke the multiply method

//from("jms:queue:numbers").beanRef("multiplier","multiply");

// the same as above but expressed as a URI configuration

//from("activemq:queue:numbers").to("bean:multiplier?methodName=multiply");

}

This denes a Camel route from the JMS queue named numbers to the

Spring bean named multiplier. Camel will create a consumer to the JMS

queue which forwards all received messages onto the the Spring bean, using

the method named multiply.

Congure Spring

The Spring cong le is placed under META-INF/spring as this is the default

location used by the Camel Maven Plugin, which we will later use to run our

server.

First we need to do the standard scheme declarations in the top. In the

camel-server.xml we are using spring beans as the default bean: namespace

and springs context:. For conguring ActiveMQ we use broker: and for

Camel we of course have camel:. Notice that we don't use version numbers

for the camel-spring schema. At runtime the schema is resolved in the Camel

bundle. If we use a specic version number such as 1.4 then its IDE friendly

as it would be able to import it and provide smart completion etc. See Xml

Reference for further details.

115 TUTORIALS

<beans xmlns="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:context="http://www.springframework.org/schema/context"

xmlns:camel="http://camel.apache.org/schema/spring"

xmlns:broker="http://activemq.apache.org/schema/core"

xsi:schemaLocation="

http://www.springframework.org/schema/beans http://www.springframework.org/

schema/beans/spring-beans.xsd

http://www.springframework.org/schema/context http://www.springframework.org/

schema/context/spring-context.xsd

http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/

camel-spring.xsd

http://activemq.apache.org/schema/core http://activemq.apache.org/schema/

core/activemq-core-5.5.0.xsd">

We use Spring annotations for doing IoC dependencies and its component-

scan features comes to the rescue as it scans for spring annotations in the

given package name:

<context:component-scan base-package="org.apache.camel.example.server"/>

Camel will of course not be less than Spring in this regard so it supports a

similar feature for scanning of Routes. This is congured as shown below.

Notice that we also have enabled the JMXAgent so we will be able to

introspect the Camel Server with a JMX Console.

<!-- declare a camel context that scans for classes that is RouteBuilder

in the package org.apache.camel.example.server -->

<camel:camelContext id="camel-server">

<camel:package>org.apache.camel.example.server</camel:package>

<!-- Camel will log at INFO level the service URI to use for connecting with

jconsole -->

<camel:jmxAgent id="agent" createConnector="true"/>

</camel:camelContext>

The ActiveMQ JMS broker is also congured in this xml le. We set it up to

listen on TCP port 61610.

<broker:broker useJmx="true" persistent="false" brokerName="myBroker">

<broker:transportConnectors>

<broker:transportConnector name="tcp" uri="tcp://localhost:61610"/>

</broker:transportConnectors>

</broker:broker>

TUTORIALS 116

As this examples uses JMS then Camel needs a JMS component that is

connected with the ActiveMQ broker. This is congured as shown below:

</bean>

Notice: The JMS component is congured in standard Spring beans, but the

gem is that the bean id can be referenced from Camel routes - meaning we

can do routing using the JMS Component by just using jms: prex in the

route URI. What happens is that Camel will nd in the Spring Registry for a

bean with the id="jms". Since the bean id can have arbitrary name you could

have named it id="jmsbroker" and then referenced to it in the routing as

from="jmsbroker:queue:numbers).to("multiplier");

We use the vm protocol to connect to the ActiveMQ server as its embedded

in this application.

component-

scan

Denes the package to be scanned for Spring stereotype

annotations, in this case, to load the "multiplier" bean

camel-

context

Denes the package to be scanned for Camel routes. Will

nd the ServerRoutes class and create the routes

contained within it

jms bean Creates the Camel JMS component

AOP Enabled Server

The example has an enhanced Server example that uses fullblown AspejctJ

AOP for doing a audit tracking of invocations of the business service.

We leverage Spring AOP support in the {{camel-server-aop.xml}

conguration le. First we must declare the correct XML schema's to use:

<beans xmlns="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:aop="http://www.springframework.org/schema/aop"

xmlns:camel="http://camel.apache.org/schema/spring"

xmlns:context="http://www.springframework.org/schema/context"

xmlns:broker="http://activemq.apache.org/schema/core"

xsi:schemaLocation="

http://www.springframework.org/schema/beans http://www.springframework.org/

schema/beans/spring-beans.xsd

http://www.springframework.org/schema/aop http://www.springframework.org/

schema/aop/spring-aop.xsd

http://www.springframework.org/schema/context http://www.springframework.org/

schema/context/spring-context.xsd

117 TUTORIALS

http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/

camel-spring.xsd

http://activemq.apache.org/schema/core http://activemq.apache.org/schema/

core/activemq-core-5.5.0.xsd">

Then we include all the existing conguration from the normal server

example:

<context:component-scan base-package="org.apache.camel.example.server"/>

<broker:broker useJmx="true" persistent="false" brokerName="myBroker">

<broker:transportConnectors>

<broker:transportConnector name="tcp" uri="tcp://localhost:61610"/>

</broker:transportConnectors>

</broker:broker>

<!-- lets configure the Camel JMS consumer to use the ActiveMQ broker declared above

-->

</bean>

</property>

</bean>

Then we enable the AspejctJ AOP auto proxy feature of Spring that will scan

for classes annotated with the @Aspect annotation:

<!-- turn on AspejctJ AOP to weave all @Aspects beans declared in this spring xml

file -->

<aop:aspectj-autoproxy/>

Then we dene our Audit tracker bean that does the actual audit logging. It's

also the class that is annotated with the @Aspect so Spring will pick this up,

as the aspect.

</bean>

And the gem is that we inject the AuditTracker aspect bean with a Camel

endpoint that denes where the audit should be stored. Noticed how easy it

is to setup as we have just dened an endpoint URI that is le based,

TUTORIALS 118

meaning that we stored the audit tracks as les. We can change this tore to

any Camel components as we wish. To store it on a JMS queue simply change

the URI to jms:queue:audit.

<!-- declare a camel context that scans for classes that is RouteBuilder

in the package org.apache.camel.example.server -->

<camel:camelContext id="camel-server-aop">

<camel:package>org.apache.camel.example.server</camel:package>

<!-- Camel will log at INFO level the service URI to use for connecting with

jconsole -->

<camel:jmxAgent id="agent" createConnector="true"/>

<camel:endpoint id="AuditStore" uri="file://target/store"/>

</camel:camelContext>

And the full blown Aspejct for the audit tracker java code:

/**

* For audit tracking of all incoming invocations of our business (Multiplier)

@Aspect

public class AuditTracker {

// endpoint we use for backup store of audit tracks

private Endpoint store;

@Required

public void setStore(Endpoint store) {

this.store = store;

}

@Before("execution(int org.apache.camel.example.server.Multiplier.multiply(int))

&& args(originalNumber)")

public void audit(int originalNumber) throws Exception {

String msg = "Someone called us with this number " + originalNumber;

System.out.println(msg);

// now send the message to the backup store using the Camel Message Endpoint

pattern

Exchange exchange = store.createExchange();

exchange.getIn().setBody(msg);

store.createProducer().process(exchange);

}

119 TUTORIALS

Run the Server

The Server is started using the org.apache.camel.spring.Main class that

can start camel-spring application out-of-the-box. The Server can be started

in several avors:

▪ as a standard java main application - just start the

org.apache.camel.spring.Main class

▪ using maven jave:exec

▪ using camel:run

In this sample as there are two servers (with and without AOP) we have

prepared some proles in maven to start the Server of your choice.

The server is started with:

mvn compile exec:java -PCamelServer

Or for the AOP enabled Server example:

mvn compile exec:java -PCamelServerAOP

WRITING THE CLIENTS

This sample has three clients demonstrating dierent Camel techniques for

communication

▪ CamelClient using the ProducerTemplate for Spring template style

coding

▪ CamelRemoting using Spring Remoting

▪ CamelEndpoint using the Message Endpoint EIP pattern using a

neutral Camel API

Client Using The ProducerTemplate

We will initially create a client by directly using ProducerTemplate. We will

later create a client which uses Spring remoting to hide the fact that

messaging is being used.

<beans xmlns="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:camel="http://camel.apache.org/schema/spring"

xsi:schemaLocation="

http://www.springframework.org/schema/beans http://www.springframework.org/

schema/beans/spring-beans.xsd

http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/

camel-spring.xsd">

<camel:camelContext id="camel-client">

<camel:template id="camelTemplate"/>

</camel:camelContext>

TUTORIALS 120

</bean>

The client will not use the Camel Maven Plugin so the Spring XML has been

placed in src/main/resources to not conict with the server congs.

camelContext The Camel context is dened but does not contain any

routes

template The ProducerTemplate is used to place messages onto

the JMS queue

jms bean This initialises the Camel JMS component, allowing us to

place messages onto the queue

And the CamelClient source code:

public static void main(final String[] args) throws Exception {

System.out.println("Notice this client requires that the CamelServer is already

running!");

ApplicationContext context = new

ClassPathXmlApplicationContext("camel-client.xml");

// get the camel template for Spring template style sending of messages (=

producer)

ProducerTemplate camelTemplate = (ProducerTemplate)

context.getBean("camelTemplate");

System.out.println("Invoking the multiply with 22");

// as opposed to the CamelClientRemoting example we need to define the service

URI in this java code

int response = (Integer)camelTemplate.sendBody("jms:queue:numbers",

ExchangePattern.InOut, 22);

System.out.println("... the result is: " + response);

System.exit(0);

}

The ProducerTemplate is retrieved from a Spring ApplicationContext and

used to manually place a message on the "numbers" JMS queue. The

exchange pattern (ExchangePattern.InOut) states that the call should be

synchronous, and that we will receive a response.

Before running the client be sure that both the ActiveMQ broker and the

CamelServer are running.

121 TUTORIALS

Client Using Spring Remoting

Spring Remoting "eases the development of remote-enabled services". It

does this by allowing you to invoke remote services through your regular

Java interface, masking that a remote service is being called.

<camel:proxy

id="multiplierProxy"

serviceInterface="org.apache.camel.example.server.Multiplier"

serviceUrl="jms:queue:numbers"/>

The snippet above only illustrates the dierent and how Camel easily can

setup and use Spring Remoting in one line congurations.

The proxy will create a proxy service bean for you to use to make the

remote invocations. The serviceInterface property details which Java

interface is to be implemented by the proxy. serviceUrl denes where

messages sent to this proxy bean will be directed. Here we dene the JMS

endpoint with the "numbers" queue we used when working with Camel

template directly. The value of the id property is the name that will be the

given to the bean when it is exposed through the Spring

ApplicationContext. We will use this name to retrieve the service in our

client. I have named the bean multiplierProxy simply to highlight that it is not

the same multiplier bean as is being used by CamelServer. They are in

completely independent contexts and have no knowledge of each other. As

you are trying to mask the fact that remoting is being used in a real

application you would generally not include proxy in the name.

And the Java client source code:

public static void main(final String[] args) {

System.out.println("Notice this client requires that the CamelServer is already

running!");

ApplicationContext context = new

ClassPathXmlApplicationContext("camel-client-remoting.xml");

// just get the proxy to the service and we as the client can use the "proxy" as

it was

// a local object we are invoking. Camel will under the covers do the remote

communication

// to the remote ActiveMQ server and fetch the response.

Multiplier multiplier = (Multiplier)context.getBean("multiplierProxy");

System.out.println("Invoking the multiply with 33");

int response = multiplier.multiply(33);

System.out.println("... the result is: " + response);

System.exit(0);

}

TUTORIALS 122

Again, the client is similar to the original client, but with some important

dierences.

1. The Spring context is created with the new camel-client-remoting.xml

2. We retrieve the proxy bean instead of a ProducerTemplate. In a non-

trivial example you would have the bean injected as in the standard

Spring manner.

3. The multiply method is then called directly. In the client we are now

working to an interface. There is no mention of Camel or JMS inside

our Java code.

Client Using Message Endpoint EIP Pattern

This client uses the Message Endpoint EIP pattern to hide the complexity to

communicate to the Server. The Client uses the same simple API to get hold

of the endpoint, create an exchange that holds the message, set the payload

and create a producer that does the send and receive. All done using the

same neutral Camel API for all the components in Camel. So if the

communication was socket TCP based you just get hold of a dierent

endpoint and all the java code stays the same. That is really powerful.

Okay enough talk, show me the code!

public static void main(final String[] args) throws Exception {

System.out.println("Notice this client requires that the CamelServer is already

running!");

ApplicationContext context = new

ClassPathXmlApplicationContext("camel-client.xml");

CamelContext camel = (CamelContext) context.getBean("camel-client");

// get the endpoint from the camel context

Endpoint endpoint = camel.getEndpoint("jms:queue:numbers");

// create the exchange used for the communication

// we use the in out pattern for asynchronized exchange where we expect a

response

Exchange exchange = endpoint.createExchange(ExchangePattern.InOut);

// set the input on the in body

// must you correct type to match the expected type of an Integer object

exchange.getIn().setBody(11);

// to send the exchange we need an producer to do it for us

Producer producer = endpoint.createProducer();

// start the producer so it can operate

producer.start();

// let the producer process the exchange where it does all the work in this

oneline of code

System.out.println("Invoking the multiply with 11");

123 TUTORIALS

producer.process(exchange);

// get the response from the out body and cast it to an integer

int response = exchange.getOut().getBody(Integer.class);

System.out.println("... the result is: " + response);

// stop and exit the client

producer.stop();

System.exit(0);

}

Switching to a dierent component is just a matter of using the correct

endpoint. So if we had dened a TCP endpoint as:

"mina:tcp://localhost:61610" then its just a matter of getting hold of this

endpoint instead of the JMS and all the rest of the java code is exactly the

same.

Run the Clients

The Clients is started using their main class respectively.

▪ as a standard java main application - just start their main class

▪ using maven jave:exec

In this sample we start the clients using maven:

mvn compile exec:java -PCamelClient

mvn compile exec:java -PCamelClientRemoting

mvn compile exec:java -PCamelClientEndpoint

Also see the Maven pom.xml le how the proles for the clients is dened.

USING THE CAMEL MAVEN PLUGIN

The Camel Maven Plugin allows you to run your Camel routes directly from

Maven. This negates the need to create a host application, as we did with

Camel server, simply to start up the container. This can be very useful during

development to get Camel routes running quickly.

Listing 17. pom.xml

<build>

<groupId>org.apache.camel</groupId>

<artifactId>camel-maven-plugin</artifactId>

</plugin>

</plugins>

</build>

TUTORIALS 124

All that is required is a new plugin denition in your Maven POM. As we have

already placed our Camel cong in the default location (camel-server.xml has

been placed in META-INF/spring/) we do not need to tell the plugin where the

route denitions are located. Simply run mvn camel:run.

USING CAMEL JMX

Camel has extensive support for JMX and allows us to inspect the Camel

Server at runtime. As we have enabled the JMXAgent in our tutorial we can

re up the jconsole and connect to the following service URI:

service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi/camel. Notice

that Camel will log at INFO level the JMX Connector URI:

...

DefaultInstrumentationAgent INFO JMX connector thread started on

service:jmx:rmi:///jndi/rmi://claus-acer:1099/jmxrmi/camel

...

In the screenshot below we can see the route and its performance metrics:

See Also

▪ Tutorials

▪ Examples

TUTORIAL ON USING CAMEL IN A WEB APPLICATION

Camel has been designed to work great with the Spring framework; so if you

are already a Spring user you can think of Camel as just a framework for

adding to your Spring XML les.

So you can follow the usual Spring approach to working with web

applications; namely to add the standard Spring hook to load a /WEB-INF/

applicationContext.xml le. In that le you can include your usual Camel

XML conguration.

Step1: Edit your web.xml

To enable spring add a context loader listener to your /WEB-INF/web.xml

le

<?xml version="1.0" encoding="UTF-8"?>

<web-app xmlns="http://java.sun.com/xml/ns/javaee"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/

xml/ns/javaee/web-app_2_5.xsd"

version="2.5">

<listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>

</listener>

</web-app>

201 TUTORIALS

This will cause Spring to boot up and look for the /WEB-INF/

applicationContext.xml le.

Step 2: Create a /WEB-INF/applicationContext.xml le

Now you just need to create your Spring XML le and add your camel routes

or conguration.

For example

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:context="http://www.springframework.org/schema/context"

xsi:schemaLocation="

http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans-2.5.xsd

http://www.springframework.org/schema/context

http://www.springframework.org/schema/context/spring-context-2.5.xsd

http://camel.apache.org/schema/spring

http://camel.apache.org/schema/spring/camel-spring.xsd">

<route>

</route>

</camelContext>

</beans>

Then boot up your web application and you're good to go!

Hints and Tips

If you use Maven to build your application your directory tree will look like

this...

src/main/webapp/WEB-INF

web.xml

applicationContext.xml

You should update your Maven pom.xml to enable WAR packaging/naming

like this...

...

...

TUTORIALS 202

<build>

<finalName>[desired WAR file name]</finalName>

...

</build>

To enable more rapid development we highly recommend the jetty:run

maven plugin.

Please refer to the help for more information on using jetty:run - but briey

if you add the following to your pom.xml

<build>

<groupId>org.mortbay.jetty</groupId>

<artifactId>maven-jetty-plugin</artifactId>

</webAppConfig>

</configuration>

</plugin>

</plugins>

</build>

Then you can run your web application as follows

mvn jetty:run

Then Jetty will also monitor your target/classes directory and your src/main/

webapp directory so that if you modify your spring XML, your web.xml or

your java code the web application will be restarted, re-creating your Camel

routes.

If your unit tests take a while to run, you could miss them out when

running your web application via

mvn -Dtest=false jetty:run

TUTORIAL BUSINESS PARTNERS

203 TUTORIALS

Under Construction

This tutorial is a work in progress.

BACKGROUND AND INTRODUCTION

Business Background

So there's a company, which we'll call Acme. Acme sells widgets, in a fairly

unusual way. Their customers are responsible for telling Acme what they

purchased. The customer enters into their own systems (ERP or whatever)

which widgets they bought from Acme. Then at some point, their systems

emit a record of the sale which needs to go to Acme so Acme can bill them

for it. Obviously, everyone wants this to be as automated as possible, so

there needs to be integration between the customer's system and Acme.

Sadly, Acme's sales people are, technically speaking, doormats. They tell

all their prospects, "you can send us the data in whatever format, using

whatever protocols, whatever. You just can't change once it's up and

running."

The result is pretty much what you'd expect. Taking a random sample of 3

customers:

• Customer 1: XML over FTP

• Customer 2: CSV over HTTP

• Customer 3: Excel via e-mail

Now on the Acme side, all this has to be converted to a canonical XML format

and submitted to the Acme accounting system via JMS. Then the Acme

accounting system does its stu and sends an XML reply via JMS, with a

summary of what it processed (e.g. 3 line items accepted, line item #2 in

error, total invoice $123.45). Finally, that data needs to be formatted into an

e-mail, and sent to a contact at the customer in question ("Dear Joyce, we

received an invoice on 1/2/08. We accepted 3 line items totaling $123.45,

though there was an error with line items #2 [invalid quantity ordered].

Thank you for your business. Love, Acme.").

So it turns out Camel can handle all this:

• Listen for HTTP, e-mail, and FTP les

• Grab attachments from the e-mail messages

• Convert XML, XLS, and CSV les to a canonical XML format

• read and write JMS messages

• route based on company ID

• format e-mails using Velocity templates

• send outgoing e-mail messages

TUTORIALS 204

Tutorial Background

This tutorial will cover all that, plus setting up tests along the way.

Before starting, you should be familiar with:

• Camel concepts including the CamelContext, Routes, Components

and Endpoints, and Enterprise Integration Patterns

• Conguring Camel with the XML or Java DSL

You'll learn:

• How to set up a Maven build for a Camel project

• How to transform XML, CSV, and Excel data into a standard XML

format with Camel

◦ How to write POJOs (Plain Old Java Objects), Velocity

templates, and XSLT stylesheets that are invoked by Camel

routes for message transformation

• How to congure simple and complex Routes in Camel, using either

the XML or the Java DSL format

• How to set up unit tests that load a Camel conguration and test

Camel routes

• How to use Camel's Data Formats to automatically convert data

between Java objects and XML, CSV les, etc.

• How to send and receive e-mail from Camel

• How to send and receive JMS messages from Camel

• How to use Enterprise Integration Patterns including Message Router

and Pipes and Filters

◦ How to use various languages to express content-based

routing rules in Camel

• How to deal with Camel messages, headers, and attachments

You may choose to treat this as a hands-on tutorial, and work through

building the code and conguration les yourself. Each of the sections gives

detailed descriptions of the steps that need to be taken to get the

components and routes working in Camel, and takes you through tests to

make sure they are working as expected.

But each section also links to working copies of the source and

conguration les, so if you don't want the hands-on approach, you can

simply review and/or download the nished les.

High-Level Diagram

Here's more or less what the integration process looks like.

First, the input from the customers to Acme:

205 TUTORIALS

And then, the output from Acme to the customers:

Tutorial Tasks

To get through this scenario, we're going to break it down into smaller pieces,

implement and test those, and then try to assemble the big scenario and test

that.

Here's what we'll try to accomplish:

1. Create a Maven build for the project

2. Get sample les for the customer Excel, CSV, and XML input

3. Get a sample le for the canonical XML format that Acme's

accounting system uses

4. Create an XSD for the canonical XML format

5. Create JAXB POJOs corresponding to the canonical XSD

6. Create an XSLT stylesheet to convert the Customer 1 (XML over FTP)

messages to the canonical format

7. Create a unit test to ensure that a simple Camel route invoking the

XSLT stylesheet works

TUTORIALS 206

8. Create a POJO that converts a List<List<String>> to the above

JAXB POJOs

◦ Note that Camel can automatically convert CSV input to a

List of Lists of Strings representing the rows and columns of

the CSV, so we'll use this POJO to handle Customer 2 (CSV

over HTTP)

9. Create a unit test to ensure that a simple Camel route invoking the

CSV processing works

10. Create a POJO that converts a Customer 3 Excel le to the above

JAXB POJOs (using POI to read Excel)

11. Create a unit test to ensure that a simple Camel route invoking the

Excel processing works

12. Create a POJO that reads an input message, takes an attachment o

the message, and replaces the body of the message with the

attachment

◦ This is assuming for Customer 3 (Excel over e-mail) that the

e-mail contains a single Excel le as an attachment, and the

actual e-mail body is throwaway

13. Build a set of Camel routes to handle the entire input (Customer ->

Acme) side of the scenario.

14. Build unit tests for the Camel input.

15. TODO: Tasks for the output (Acme -> Customer) side of the scenario

LET'S GET STARTED!

Step 1: Initial Maven build

We'll use Maven for this project as there will eventually be quite a few

dependencies and it's nice to have Maven handle them for us. You should

have a current version of Maven (e.g. 2.0.9) installed.

You can start with a pretty empty project directory and a Maven POM le,

or use a simple JAR archetype to create one.

Here's a sample POM. We've added a dependency on camel-core, and set

the compile version to 1.5 (so we can use annotations):

Listing 18. pom.xml

<?xml version="1.0" encoding="UTF-8"?>

<groupId>org.apache.camel.tutorial</groupId>

<artifactId>business-partners</artifactId>

<version>1.0-SNAPSHOT</version>

<name>Camel Business Partners Tutorial</name>

207 TUTORIALS

<artifactId>camel-core</artifactId>

<groupId>org.apache.camel</groupId>

</dependency>

</dependencies>

<build>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-compiler-plugin</artifactId>

</configuration>

</plugin>

</plugins>

</build>

</project>

Step 2: Get Sample Files

You can make up your own if you like, but here are the "o the shelf" ones.

You can save yourself some time by downloading these to src/test/

resources in your Maven project.

• Customer 1 (XML): input-customer1.xml

• Customer 2 (CSV): input-customer2.csv

• Customer 3 (Excel): input-customer3.xls

• Canonical Acme XML Request: canonical-acme-request.xml

• Canonical Acme XML Response: TODO

If you look at these les, you'll see that the dierent input formats use

dierent eld names and/or ordering, because of course the sales guys were

totally OK with that. Sigh.

Step 3: XSD and JAXB Beans for the Canonical XML Format

Here's the sample of the canonical XML le:

<?xml version="1.0" encoding="UTF-8"?>

<partner-id>2</partner-id>

<date-received>9/12/2008</date-received>

<line-item>

<product-id>134</product-id>

<description>A widget</description>

TUTORIALS 208

<item-price>10.45</item-price>

<order-date>6/5/2008</order-date>

</line-item>

<order-total>218.82</order-total>

</invoice>

If you're ambitions, you can write your own XSD (XML Schema) for les that

look like this, and save it to src/main/xsd.

Solution: If not, you can download mine, and save that to save it to src/

main/xsd.

Generating JAXB Beans

Down the road we'll want to deal with the XML as Java POJOs. We'll take a

moment now to set up those XML binding POJOs. So we'll update the Maven

POM to generate JAXB beans from the XSD le.

We need a dependency:

<artifactId>camel-jaxb</artifactId>

<groupId>org.apache.camel</groupId>

</dependency>

And a plugin congured:

<groupId>org.codehaus.mojo</groupId>

<artifactId>jaxb2-maven-plugin</artifactId>

<goals>

</goals>

</execution>

</executions>

</plugin>

That should do it (it automatically looks for XML Schemas in src/main/xsd to

generate beans for). Run mvn install and it should emit the beans into

target/generated-sources/jaxb. Your IDE should see them there, though

you may need to update the project to reect the new settings in the Maven

POM.

209 TUTORIALS

Step 4: Initial Work on Customer 1 Input (XML over FTP)

To get a start on Customer 1, we'll create an XSLT template to convert the

Customer 1 sample le into the canonical XML format, write a small Camel

route to test it, and build that into a unit test. If we get through this, we can

be pretty sure that the XSLT template is valid and can be run safely in Camel.

Create an XSLT template

Start with the Customer 1 sample input. You want to create an XSLT template

to generate XML like the canonical XML sample above – an invoice element

with line-item elements (one per item in the original XML document). If

you're especially clever, you can populate the current date and order total

elements too.

Solution: My sample XSLT template isn't that smart, but it'll get you going

if you don't want to write one of your own.

Create a unit test

Here's where we get to some meaty Camel work. We need to:

• Set up a unit test

• That loads a Camel conguration

• That has a route invoking our XSLT

• Where the test sends a message to the route

• And ensures that some XML comes out the end of the route

The easiest way to do this is to set up a Spring context that denes the

Camel stu, and then use a base unit test class from Spring that knows how

to load a Spring context to run tests against. So, the procedure is:

Set Up a Skeletal Camel/Spring Unit Test

1. Add dependencies on Camel-Spring, and the Spring test JAR (which

will automatically bring in JUnit 3.8.x) to your POM:

<artifactId>camel-spring</artifactId>

<groupId>org.apache.camel</groupId>

</dependency>

<artifactId>spring-test</artifactId>

<groupId>org.springframework</groupId>

TUTORIALS 210

</dependency>

2. Create a new unit test class in src/test/java/your-package-here,

perhaps called XMLInputTest.java

3. Make the test extend Spring's AbstractJUnit38SpringContextTests

class, so it can load a Spring context for the test

4. Create a Spring context conguration le in src/test/resources,

perhaps called XMLInputTest-context.xml

5. In the unit test class, use the class-level @ContextConguration

annotation to indicate that a Spring context should be loaded

◦ By default, this looks for a Context conguration le called

TestClassName-context.xml in a subdirectory

corresponding to the package of the test class. For instance,

if your test class was

org.apache.camel.tutorial.XMLInputTest, it would look

for org/apache/camel/tutorial/XMLInputTest-

context.xml

◦ To override this default, use the locations attribute on the

@ContextConguration annotation to provide specic context

le locations (starting each path with a / if you don't want it

to be relative to the package directory). My solution does this

so I can put the context le directly in src/test/resources

instead of in a package directory under there.

6. Add a CamelContext instance variable to the test class, with the

@Autowired annotation. That way Spring will automatically pull the

CamelContext out of the Spring context and inject it into our test

class.

7. Add a ProducerTemplate instance variable and a setUp method that

instantiates it from the CamelContext. We'll use the

ProducerTemplate later to send messages to the route.

protected ProducerTemplate<Exchange> template;

protected void setUp() throws Exception {

super.setUp();

template = camelContext.createProducerTemplate();

}

8. Put in an empty test method just for the moment (so when we run

this we can see that "1 test succeeded")

9. Add the Spring <beans> element (including the Camel Namespace)

with an empty <camelContext> element to the Spring context, like

this:

211 TUTORIALS

<?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-2.5.xsd

http://activemq.apache.org/camel/schema/spring

http://activemq.apache.org/camel/schema/

spring/camel-spring-1.4.0.xsd">

<camelContext id="camel" xmlns="http://activemq.apache.org/camel/schema/

spring">

</camelContext>

</beans>

Test it by running mvn install and make sure there are no build errors. So far

it doesn't test much; just that your project and test and source les are all

organized correctly, and the one empty test method completes successfully.

Solution: Your test class might look something like this:

• src/test/java/org/apache/camel/tutorial/XMLInputTest.java

• src/test/resources/XMLInputTest-context.xml (same as just above)

Flesh Out the Unit Test

So now we're going to write a Camel route that applies the XSLT to the

sample Customer 1 input le, and makes sure that some XML output comes

out:

1. Save the input-customer1.xml le to src/test/resources

2. Save your XSLT le (created in the previous step) to src/main/

resources

3. Write a Camel Route, either right in the Spring XML, or using the Java

DSL (in another class under src/test/java somewhere). This route

should use the Pipes and Filters integration pattern to:

1. Start from the endpoint direct:start (which lets the test

conveniently pass messages into the route)

2. Call the endpoint xslt:YourXSLTFile.xsl (to transform the

message with the specied XSLT template)

3. Send the result to the endpoint mock:nish (which lets the

test verify the route output)

4. Add a test method to the unit test class that:

1. Get a reference to the Mock endpoint mock:finish using

code like this:

MockEndpoint finish = MockEndpoint.resolve(camelContext,

"mock:finish");

TUTORIALS 212

2. Set the expectedMessageCount on that endpoint to 1

3. Get a reference to the Customer 1 input le, using code like

this:

InputStream in =

XMLInputTest.class.getResourceAsStream("/input-partner1.xml");

assertNotNull(in);

4. Send that InputStream as a message to the direct:start

endpoint, using code like this:

template.sendBody("direct:start", in);

Note that we can send the sample le body in several

formats (File, InputStream, String, etc.) but in this case an

InputStream is pretty convenient.

5. Ensure that the message made it through the route to the

nal endpoint, by testing all congured Mock endpoints like

this:

MockEndpoint.assertIsSatisfied(camelContext);

6. If you like, inspect the nal message body using some code

like finish.getExchanges().get(0).getIn().getBody().

▪ If you do this, you'll need to know what format that

body is – String, byte array, InputStream, etc.

5. Run your test with mvn install and make sure the build completes

successfully.

Solution: Your nished test might look something like this:

• src/test/java/org/apache/camel/tutorial/XMLInputTest.java

• For XML Conguration:

◦ src/test/resources/XMLInputTest-context.xml

• Or, for Java DSL Conguration:

◦ src/test/resources/XMLInputTest-dsl-context.xml

◦ src/test/java/org/apache/camel/tutorial/

routes/XMLInputTestRoute.java

Step 5: Initial Work on Customer 2 Input (CSV over HTTP)

To get a start on Customer 2, we'll create a POJO to convert the Customer 2

sample CSV data into the JAXB POJOs representing the canonical XML format,

write a small Camel route to test it, and build that into a unit test. If we get

213 TUTORIALS

Test Base Class

Once your test class is working, you might want to extract things

like the @Autowired CamelContext, the ProducerTemplate, and the

setUp method to a custom base class that you extend with your

other tests.

through this, we can be pretty sure that the CSV conversion and JAXB

handling is valid and can be run safely in Camel.

Create a CSV-handling POJO

To begin with, CSV is a known data format in Camel. Camel can convert a

CSV le to a List (representing rows in the CSV) of Lists (representing cells in

the row) of Strings (the data for each cell). That means our POJO can just

assume the data coming in is of type List<List<String>>, and we can

declare a method with that as the argument.

Looking at the JAXB code in target/generated-sources/jaxb, it looks

like an Invoice object represents the whole document, with a nested list of

LineItemType objects for the line items. Therefore our POJO method will

return an Invoice (a document in the canonical XML format).

So to implement the CSV-to-JAXB POJO, we need to do something like this:

1. Create a new class under src/main/java, perhaps called

CSVConverterBean.

2. Add a method, with one argument of type List<List<String>> and

the return type Invoice

◦ You may annotate the argument with @Body to specically

designate it as the body of the incoming message

3. In the method, the logic should look roughly like this:

1. Create a new Invoice, using the method on the generated

ObjectFactory class

2. Loop through all the rows in the incoming CSV (the outer

List)

3. Skip the rst row, which contains headers (column names)

4. For the other rows:

1. Create a new LineItemType (using the

ObjectFactory again)

2. Pick out all the cell values (the Strings in the inner

List) and put them into the correct elds of the

LineItemType

TUTORIALS 214

▪ Not all of the values will actually go into the

line item in this example

▪ You may hardcode the column ordering based

on the sample data le, or else try to read it

dynamically from the headers in the rst line

▪ Note that you'll need to use a JAXB

DatatypeFactory to create the

XMLGregorianCalendar values that JAXB

uses for the date elds in the XML – which

probably means using a SimpleDateFormat

to parse the date and setting that date on a

GregorianCalendar

3. Add the line item to the invoice

5. Populate the partner ID, date of receipt, and order total on

the Invoice

6. Throw any exceptions out of the method, so Camel knows

something went wrong

7. Return the nished Invoice

Solution: Here's an example of what the CSVConverterBean might look like.

Create a unit test

Start with a simple test class and test Spring context like last time, perhaps

based on the name CSVInputTest:

Listing 19. CSVInputTest.java

/**

* A test class the ensure we can convert Partner 2 CSV input files to the

* canonical XML output format, using JAXB POJOs.

@ContextConfiguration(locations = "/CSVInputTest-context.xml")

public class CSVInputTest extends AbstractJUnit38SpringContextTests {

@Autowired

protected CamelContext camelContext;

protected ProducerTemplate<Exchange> template;

protected void setUp() throws Exception {

super.setUp();

template = camelContext.createProducerTemplate();

}

public void testCSVConversion() {

// TODO

}

Listing 20. CSVInputTest-context.xml

215 TUTORIALS

<?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-2.5.xsd

http://activemq.apache.org/camel/schema/spring

http://activemq.apache.org/camel/schema/spring/

camel-spring-1.4.0.xsd">

</camelContext>

</beans>

Now the meaty part is to esh out the test class and write the Camel routes.

1. Update the Maven POM to include CSV Data Format support:

<artifactId>camel-csv</artifactId>

<groupId>org.apache.camel</groupId>

</dependency>

2. Write the routes (right in the Spring XML context, or using the Java

DSL) for the CSV conversion process, again using the Pipes and

Filters pattern:

1. Start from the endpoint direct:CSVstart (which lets the test

conveniently pass messages into the route). We'll name this

dierently than the starting point for the previous test, in

case you use the Java DSL and put all your routes in the

same package (which would mean that each test would load

the DSL routes for several tests.)

2. This time, there's a little preparation to be done. Camel

doesn't know that the initial input is a CSV, so it won't be

able to convert it to the expected List<List<String>>

without a little hint. For that, we need an unmarshal

transformation in the route. The unmarshal method (in the

DSL) or element (in the XML) takes a child indicating the

format to unmarshal; in this case that should be csv.

3. Next invoke the POJO to transform the message with a

bean:CSVConverter endpoint

4. As before, send the result to the endpoint mock:nish (which

lets the test verify the route output)

5. Finally, we need a Spring <bean> element in the Spring

context XML le (but outside the <camelContext> element)

TUTORIALS 216

to dene the Spring bean that our route invokes. This Spring

bean should have a name attribute that matches the name

used in the bean endpoint (CSVConverter in the example

above), and a class attribute that points to the CSV-to-JAXB

POJO class you wrote above (such as,

org.apache.camel.tutorial.CSVConverterBean). When

Spring is in the picture, any bean endpoints look up Spring

beans with the specied name.

3. Write a test method in the test class, which should look very similar

to the previous test class:

1. Get the MockEndpoint for the nal endpoint, and tell it to

expect one message

2. Load the Partner 2 sample CSV le from the ClassPath, and

send it as the body of a message to the starting endpoint

3. Verify that the nal MockEndpoint is satised (that is, it

received one message) and examine the message body if

you like

▪ Note that we didn't marshal the JAXB POJOs to XML in

this test, so the nal message should contain an

Invoice as the body. You could write a simple line of

code to get the Exchange (and Message) from the

MockEndpoint to conrm that.

4. Run this new test with mvn install and make sure it passes and the

build completes successfully.

Solution: Your nished test might look something like this:

• src/test/java/org/apache/camel/tutorial/CSVInputTest.java

• For XML Conguration:

◦ src/test/resources/CSVInputTest-context.xml

• Or, for Java DSL Conguration:

◦ src/test/resources/CSVInputTest-dsl-context.xml

◦ src/test/java/org/apache/camel/tutorial/

routes/CSVInputTestRoute.java

Step 6: Initial Work on Customer 3 Input (Excel over e-mail)

To get a start on Customer 3, we'll create a POJO to convert the Customer 3

sample Excel data into the JAXB POJOs representing the canonical XML

format, write a small Camel route to test it, and build that into a unit test. If

we get through this, we can be pretty sure that the Excel conversion and

JAXB handling is valid and can be run safely in Camel.

217 TUTORIALS

Create an Excel-handling POJO

Camel does not have a data format handler for Excel by default. We have two

options – create an Excel DataFormat (so Camel can convert Excel

spreadsheets to something like the CSV List<List<String>> automatically),

or create a POJO that can translate Excel data manually. For now, the second

approach is easier (if we go the DataFormat route, we need code to both

read and write Excel les, whereas otherwise read-only will do).

So, we need a POJO with a method that takes something like an

InputStream or byte[] as an argument, and returns in Invoice as before.

The process should look something like this:

1. Update the Maven POM to include POI support:

<groupId>org.apache.poi</groupId>

<version>3.1-FINAL</version>

</dependency>

2. Create a new class under src/main/java, perhaps called

ExcelConverterBean.

3. Add a method, with one argument of type InputStream and the

return type Invoice

◦ You may annotate the argument with @Body to specically

designate it as the body of the incoming message

4. In the method, the logic should look roughly like this:

1. Create a new Invoice, using the method on the generated

ObjectFactory class

2. Create a new HSSFWorkbook from the InputStream, and get

the rst sheet from it

3. Loop through all the rows in the sheet

4. Skip the rst row, which contains headers (column names)

5. For the other rows:

1. Create a new LineItemType (using the

ObjectFactory again)

2. Pick out all the cell values and put them into the

correct elds of the LineItemType (you'll need some

data type conversion logic)

▪ Not all of the values will actually go into the

line item in this example

▪ You may hardcode the column ordering based

on the sample data le, or else try to read it

dynamically from the headers in the rst line

TUTORIALS 218

▪ Note that you'll need to use a JAXB

DatatypeFactory to create the

XMLGregorianCalendar values that JAXB

uses for the date elds in the XML – which

probably means setting the date from a date

cell on a GregorianCalendar

3. Add the line item to the invoice

6. Populate the partner ID, date of receipt, and order total on

the Invoice

7. Throw any exceptions out of the method, so Camel knows

something went wrong

8. Return the nished Invoice

Solution: Here's an example of what the ExcelConverterBean might look

like.

Create a unit test

The unit tests should be pretty familiar now. The test class and context for

the Excel bean should be quite similar to the CSV bean.

1. Create the basic test class and corresponding Spring Context XML

conguration le

2. The XML cong should look a lot like the CSV test, except:

◦ Remember to use a dierent start endpoint name if you're

using the Java DSL and not use separate packages per test

◦ You don't need the unmarshal step since the Excel POJO

takes the raw InputStream from the source endpoint

◦ You'll declare a <bean> and endpoint for the Excel bean

prepared above instead of the CSV bean

3. The test class should look a lot like the CSV test, except use the right

input le name and start endpoint name.

Solution: Your nished test might look something like this:

• src/test/java/org/apache/camel/tutorial/ExcelInputTest.java

• For XML Conguration:

◦ src/test/resources/ExcelInputTest-context.xml

• Or, for Java DSL Conguration:

◦ src/test/resources/ExcelInputTest-dsl-context.xml

◦ src/test/java/org/apache/camel/tutorial/

routes/ExcelInputTestRoute.java

219 TUTORIALS

Logging

You may notice that your tests emit a lot less output all of a sudden.

The dependency on POI brought in Log4J and congured commons-

logging to use it, so now we need a log4j.properties le to congure

log output. You can use the attached one (snarfed from ActiveMQ)

or write your own; either way save it to src/main/resources to

ensure you continue to see log output.

Step 7: Put this all together into Camel routes for the Customer

Input

With all the data type conversions working, the next step is to write the real

routes that listen for HTTP, FTP, or e-mail input, and write the nal XML

output to an ActiveMQ queue. Along the way these routes will use the data

conversions we've developed above.

So we'll create 3 routes to start with, as shown in the diagram back at the

beginning:

1. Accept XML orders over FTP from Customer 1 (we'll assume the FTP

server dumps les in a local directory on the Camel machine)

2. Accept CSV orders over HTTP from Customer 2

3. Accept Excel orders via e-mail from Customer 3 (we'll assume the

messages are sent to an account we can access via IMAP)

...

Step 8: Create a unit test for the Customer Input Routes

TUTORIALS 220

Languages Supported

Appendix

To support exible and powerful Enterprise Integration Patterns Camel

supports various Languages to create an Expression or Predicate within

either the Routing Domain Specic Language or the Xml Conguration. The

following languages are supported

BEAN LANGUAGE

The purpose of the Bean Language is to be able to implement an Expression

or Predicate using a simple method on a bean.

So the idea is you specify a bean name which will then be resolved in the

Registry such as the Spring ApplicationContext then a method is invoked to

evaluate the Expression or Predicate.

If no method name is provided then one is attempted to be chosen using

the rules for Bean Binding; using the type of the message body and using

any annotations on the bean methods.

The Bean Binding rules are used to bind the Message Exchange to the

method parameters; so you can annotate the bean to extract headers or

other expressions such as XPath or XQuery from the message.

Using Bean Expressions from the Java DSL

from("activemq:topic:OrdersTopic").

filter().method("myBean","isGoldCustomer").

to("activemq:BigSpendersQueue");

Using Bean Expressions from XML

<route>

</filter>

</route>

221 LANGUAGES SUPPORTED APPENDIX

Writing the expression bean

The bean in the above examples is just any old Java Bean with a method

called isGoldCustomer() that returns some object that is easily converted to a

boolean value in this case, as its used as a predicate.

So we could implement it like this...

public class MyBean {

public boolean isGoldCustomer(Exchange exchange) {

...

}

We can also use the Bean Integration annotations. For example you could

do...

public boolean isGoldCustomer(String body) {...}

public boolean isGoldCustomer(@Header(name = "foo")Integer fooHeader) {...}

So you can bind parameters of the method to the Exchange, the Message or

individual headers, properties, the body or other expressions.

Non registry beans

As of Camel 1.5 the Bean Language also supports invoking beans that isn't

registered in the Registry. This is usable for quickly to invoke a bean from

Java DSL where you don't need to register the bean in the Registry such as

the Spring ApplicationContext.

Camel can instantiate the bean and invoke the method if given a class or

invoke an already existing instance. This is illustrated from the example

below:

NOTE This bean DSL is supported since Camel 2.0-M2

from("activemq:topic:OrdersTopic").

filter().expression(BeanLanguage(MyBean.class, "isGoldCustomer")).

to("activemq:BigSpendersQueue");

The 2nd parameter isGoldCustomer is an optional parameter to explicit set

the method name to invoke. If not provided Camel will try to invoke the best

suited method. If case of ambiguity Camel will thrown an Exception. In these

situations the 2nd parameter can solve this problem. Also the code is more

LANGUAGES SUPPORTED APPENDIX 222

readable if the method name is provided. The 1st parameter can also be an

existing instance of a Bean such as:

private MyBean my;

from("activemq:topic:OrdersTopic").

filter().expression(BeanLanguage.bean(my, "isGoldCustomer")).

to("activemq:BigSpendersQueue");

In Camel 2.2 onwards you can avoid the BeanLanguage and have it just as:

private MyBean my;

from("activemq:topic:OrdersTopic").

filter().expression(bean(my, "isGoldCustomer")).

to("activemq:BigSpendersQueue");

Which also can be done in a bit shorter and nice way:

private MyBean my;

from("activemq:topic:OrdersTopic").

filter().method(my, "isGoldCustomer").

to("activemq:BigSpendersQueue");

Other examples

We have some test cases you can look at if it'll help

• MethodFilterTest is a JUnit test case showing the Java DSL use of the

bean expression being used in a lter

• aggregator.xml is a Spring XML test case for the Aggregator which

uses a bean method call to test for the completion of the

aggregation.

Dependencies

The Bean language is part of camel-core.

CONSTANT EXPRESSION LANGUAGE

The Constant Expression Language is really just a way to specify constant

strings as a type of expression.

Available as of Camel 1.5

223 LANGUAGES SUPPORTED APPENDIX

Example usage

The setHeader element of the Spring DSL can utilize a constant expression

like:

<route>

<constant>the value</constant>

</setHeader>

</route>

in this case, the Message coming from the seda:a Endpoint will have

'theHeader' header set to the constant value 'the value'.

And the same example using Java DSL:

from("seda:a").setHeader("theHeader", constant("the value")).to("mock:b");

Dependencies

The Constant language is part of camel-core.

Camel supports the unied JSP and JSF Expression Language via the JUEL to

allow an Expression or Predicate to be used in the DSL or Xml Conguration.

For example you could use EL inside a Message Filter in XML

<route>

<el>${in.headers.foo == 'bar'}</el>

</filter>

</route>

You could also use slightly dierent syntax, e.g. if the header name is not a

valid identier:

<route>

<el>${in.headers['My Header'] == 'bar'}</el>

LANGUAGES SUPPORTED APPENDIX 224

</filter>

</route>

You could use EL to create an Predicate in a Message Filter or as an

Expression for a Recipient List

Variables

Variable Type Description

exchange Exchange the Exchange object

in Message the exchange.in message

out Message the exchange.out message

Samples

You can use EL dot notation to invoke operations. If you for instance have a

body that contains a POJO that has a getFamiliyName method then you can

construct the syntax as follows:

"$in.body.familyName"

Dependencies

To use EL in your camel routes you need to add the a dependency on camel-

juel which implements the EL language.

If you use maven you could just add the following to your pom.xml,

substituting the version number for the latest & greatest release (see the

download page for the latest versions).

<groupId>org.apache.camel</groupId>

<artifactId>camel-juel</artifactId>

</dependency>

Otherwise you'll also need to include JUEL.

225 LANGUAGES SUPPORTED APPENDIX

HEADER EXPRESSION LANGUAGE

The Header Expression Language allows you to extract values of named

headers.

Available as of Camel 1.5

Example usage

The recipientList element of the Spring DSL can utilize a header expression

like:

<route>

<header>myHeader</header>

</recipientList>

</route>

In this case, the list of recipients are contained in the header 'myHeader'.

And the same example in Java DSL:

from("direct:a").recipientList(header("myHeader"));

And with a slightly dierent syntax where you use the builder to the fullest

(i.e. avoid using parameters but using stacked operations, notice that header

is not a parameter but a stacked method call)

from("direct:a").recipientList().header("myHeader");

Dependencies

The Header language is part of camel-core.

JXPATH

Camel supports JXPath to allow XPath expressions to be used on beans in an

Expression or Predicate to be used in the DSL or Xml Conguration. For

example you could use JXPath to create an Predicate in a Message Filter or as

an Expression for a Recipient List.

From 1.3 of Camel onwards you can use XPath expressions directly using

smart completion in your IDE as follows

LANGUAGES SUPPORTED APPENDIX 226

from("queue:foo").filter().

jxpath("/in/body/foo").

to("queue:bar")

Variables

Variable Type Description

this Exchange the Exchange object

in Message the exchange.in message

out Message the exchange.out message

Using XML conguration

If you prefer to congure your routes in your Spring XML le then you can

use JXPath expressions as follows

<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.0.xsd

http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/

camel-spring.xsd">

<route>

<jxpath>in/body/name = 'James'</xpath>

</filter>

</route>

</camelContext>

</beans>

Examples

Here is a simple example using a JXPath expression as a predicate in a

Message Filter

from("direct:start").

filter().jxpath("in/body/name='James'").

to("mock:result");

227 LANGUAGES SUPPORTED APPENDIX

JXPATH INJECTION

You can use Bean Integration to invoke a method on a bean and use various

languages such as JXPath to extract a value from the message and bind it to

a method parameter.

For example

public class Foo {

@MessageDriven(uri = "activemq:my.queue")

public void doSomething(@JXPath("in/body/foo")String correlationID, @Body String

body) {

// process the inbound message here

}

Dependencies

To use JXpath in your camel routes you need to add the a dependency on

camel-jxpath which implements the JXpath language.

If you use maven you could just add the following to your pom.xml,

substituting the version number for the latest & greatest release (see the

download page for the latest versions).

<groupId>org.apache.camel</groupId>

<artifactId>camel-jxpath</artifactId>

</dependency>

Otherwise, you'll also need Commons JXPath.

MVEL

Avialable in Camel 2.0

Camel allows Mvel to be used as an Expression or Predicate the DSL or

Xml Conguration.

You could use Mvel to create an Predicate in a Message Filter or as an

Expression for a Recipient List

You can use Mvel dot notation to invoke operations. If you for instance

have a body that contains a POJO that has a getFamiliyName method then

you can construct the syntax as follows:

LANGUAGES SUPPORTED APPENDIX 228

"request.body.familyName"

// or

"getRequest().getBody().getFamilyName()"

Variables

Variable Type Description

this Exchange the Exchange is the root object

exchange Exchange the Exchange object

exception Throwable the Exchange exception (if any)

exchangeId String the exchange id

fault Message the Fault message (if any)

request Message the exchange.in message

response Message the exchange.out message (if any)

properties Map the exchange properties

property(name) Object the property by the given name

property(name,

type) Type the property by the given name as the

given type

Samples

For example you could use Mvel inside a Message Filter in XML

<route>

<mvel>request.headers.foo == 'bar'</mvel>

</filter>

</route>

And the sample using Java DSL:

from("seda:foo").filter().mvel("request.headers.foo == 'bar'").to("seda:bar");

229 LANGUAGES SUPPORTED APPENDIX

Dependencies

To use Mvel in your camel routes you need to add the a dependency on

camel-mvel which implements the Mvel language.

If you use maven you could just add the following to your pom.xml,

substituting the version number for the latest & greatest release (see the

download page for the latest versions).

<groupId>org.apache.camel</groupId>

<artifactId>camel-mvel</artifactId>

</dependency>

Otherwise, you'll also need MVEL

OGNL

Camel allows OGNL to be used as an Expression or Predicate the DSL or Xml

Conguration.

You could use OGNL to create an Predicate in a Message Filter or as an

Expression for a Recipient List

You can use OGNL dot notation to invoke operations. If you for instance

have a body that contains a POJO that has a getFamiliyName method then

you can construct the syntax as follows:

"request.body.familyName"

// or

"getRequest().getBody().getFamilyName()"

Variables

Variable Type Description

this Exchange the Exchange is the root object

exchange Exchange the Exchange object

exception Throwable the Exchange exception (if any)

exchangeId String the exchange id

fault Message the Fault message (if any)

request Message the exchange.in message

LANGUAGES SUPPORTED APPENDIX 230

response Message the exchange.out message (if any)

properties Map the exchange properties

property(name) Object the property by the given name

property(name,

type) Type the property by the given name as the

given type

Samples

For example you could use OGNL inside a Message Filter in XML

<route>

<ognl>request.headers.foo == 'bar'</ognl>

</filter>

</route>

And the sample using Java DSL:

from("seda:foo").filter().ognl("request.headers.foo == 'bar'").to("seda:bar");

Dependencies

To use OGNL in your camel routes you need to add the a dependency on

camel-ognl which implements the OGNL language.

If you use maven you could just add the following to your pom.xml,

substituting the version number for the latest & greatest release (see the

download page for the latest versions).

<groupId>org.apache.camel</groupId>

<artifactId>camel-ognl</artifactId>

</dependency>

Otherwise, you'll also need OGNL

PROPERTY EXPRESSION LANGUAGE

The Property Expression Language allows you to extract values of named

exchange properties.

231 LANGUAGES SUPPORTED APPENDIX

Available as of Camel 2.0

Example usage

The recipientList element of the Spring DSL can utilize a property expression

like:

<route>

<property>myProperty</property>

</recipientList>

</route>

In this case, the list of recipients are contained in the property 'myProperty'.

And the same example in Java DSL:

from("direct:a").recipientList(property("myProperty"));

And with a slightly dierent syntax where you use the builder to the fullest

(i.e. avoid using parameters but using stacked operations, notice that

property is not a parameter but a stacked method call)

from("direct:a").recipientList().property("myProperty");

Dependencies

The Property language is part of camel-core.

SCRIPTING LANGUAGES

Camel supports a number of scripting languages which can be used to create

an Expression or Predicate via the standard JSR 223 which is a standard part

of Java 6.

The following scripting languages are integrated into the DSL:

Language DSL keyword

EL el

Groovy groovy

JavaScript javaScript

JoSQL sql

LANGUAGES SUPPORTED APPENDIX 232

JXPath jxpath

MVEL mvel

OGNL ognl

PHP php

Python python

Ruby ruby

XPath xpath

XQuery xquery

However any JSR 223 scripting language can be used using the generic DSL

methods.

ScriptContext

The JSR-223 scripting languages ScriptContext is pre congured with the

following attributes all set at ENGINE_SCOPE:

Attribute Type Value

context org.apache.camel.CamelContext The Camel

Context

exchange org.apache.camel.Exchange

The

current

Exchange

request org.apache.camel.Message The IN

message

response org.apache.camel.Message The OUT

message

233 LANGUAGES SUPPORTED APPENDIX

properties org.apache.camel.builder.script.PropertiesFunction

Camel

2.9:

Function

with a

resolve

method to

make it

easier to

use

Camels

Properties

component

from

scripts.

See further

below for

example.

Attributes

You can add your own attributes with the attribute(name, value) DSL

method, such as:

In the sample below we add an attribute user that is an object we already

have instantiated as myUser. This object has a getFirstName() method that

we want to set as header on the message. We use the groovy language to

concat the rst and last name into a single string that is returned.

from("direct:in").setHeader("name").groovy("'$user.firstName

$user.lastName'").attribute("user", myUser).to("seda:users");

Any scripting language

Camel can run any JSR-223 scripting languages using the script DSL

method such as:

from("direct:in").setHeader("firstName").script("jaskel",

"user.firstName").attribute("user", myUser).to("seda:users");

This is a bit dierent using the Spring DSL where you use the expression

element that doesn't support setting attributes (yet):

LANGUAGES SUPPORTED APPENDIX 234

<expression language="jaskel">user.firstName</expression>

</setHeader>

You can also use predicates e.g. in a Filter:

<language

language="beanshell">request.getHeaders().get("Foo").equals("Bar")</language>

</filter>

See Scripting Languages for the list of languages with explicit DSL support.

Some languages without specic DSL support but known to work with

these generic methods include:

Language Implementation language="..." value

BeanShell BeanShell 2.0b5 beanshell or bsh

Additional arguments to ScriptingEngine

Available as of Camel 2.8

You can provide additional arguments to the ScriptingEngine using a

header on the Camel message with the key CamelScriptArguments.

See this example:

public void testArgumentsExample() throws Exception {

if (!ScriptTestHelper.canRunTestOnThisPlatform()) {

return;

}

getMockEndpoint("mock:result").expectedMessageCount(0);

getMockEndpoint("mock:unmatched").expectedMessageCount(1);

// additional arguments to ScriptEngine

Map<String,Object> arguments = new HashMap<String,Object>();

arguments.put("foo","bar");

arguments.put("baz", 7);

// those additional arguments is provided as a header on the Camel Message

template.sendBodyAndHeader("direct:start","hello", ScriptBuilder.ARGUMENTS,

arguments);

assertMockEndpointsSatisfied();

}

235 LANGUAGES SUPPORTED APPENDIX

Using properties function

Available as of Camel 2.9

If you need to use the Properties component from a script to lookup

property placeholders, then its a bit cumbersome to do so.

For example to set a header name myHeader with a value from a property

placeholder, which key is provided in a header named "foo".

.setHeader("myHeader").groovy("context.resolvePropertyPlaceholders('{{' +

request.headers.get('foo') + '}}')")

From Camel 2.9 onwards you can now use the properties function and the

same example is simpler:

.setHeader("myHeader").groovy("properties.resolve(request.headers.get('foo'))")

Dependencies

To use scripting languages in your camel routes you need to add the a

dependency on camel-script which integrates the JSR-223 scripting engine.

If you use maven you could just add the following to your pom.xml,

substituting the version number for the latest & greatest release (see the

download page for the latest versions).

<groupId>org.apache.camel</groupId>

<artifactId>camel-script</artifactId>

</dependency>

See also

As the SOAP dataformat inherits from the JAXB dataformat most

settings apply here as well

The camel-soap DataFormat maps the content in the BeanInvocation to

elds in the SOAP header and body in accordance with the JAX-WS mapping

when the marshal() processor is invoked.

BeanInvocation beanInvocation = new BeanInvocation();

// Identify the target method

beanInvocation.setMethod(MultiPartCustomerService.class.getMethod("getCustomersByName",

GetCustomersByName.class, com.example.customerservice.multipart.Product.class));

// Populate the method arguments

GetCustomersByName getCustomersByName = new GetCustomersByName();

getCustomersByName.setName("Dr. Multipart");

Product product = new Product();

product.setName("Multiuse Product");

product.setDescription("Useful for lots of things.");

Object[] args = new Object[] {getCustomersByName, product};

// Add the arguments to the bean invocation

beanInvocation.setArgs(args);

// Set the bean invocation object as the message body

exchange.getIn().setBody(beanInvocation);

Multi-part Response

A multi-part soap response may include an element in the soap body and will

have one or more elements in the soap header. The camel-soap DataFormat

will unmarshall the element in the soap body (if it exists) and place it onto

the body of the out message in the exchange. Header elements will not be

marshaled into their JAXB mapped object types. Instead, these elements are

placed into the camel out message header

org.apache.camel.dataformat.soap.UNMARSHALLED_HEADER_LIST. The

elements will appear either as element instance values, or as JAXBElement

values, depending upon the setting for the ignoreJAXBElement property.

This property is inherited from camel-jaxb.

You can also have the camel-soap DataFormate ignore header content all-

together by setting the ignoreUnmarshalledHeaders value to true.

PROTOBUF - PROTOCOL BUFFERS 354

Holder Object mapping

JAX-WS species the use of a type-parameterized javax.xml.ws.Holder

object for In/Out and Out parameters. A Holder object may be used when

building the BeanInvocation, or you may use an instance of the

parameterized-type directly. The camel-soap DataFormat marshals Holder

values in accordance with the JAXB mapping for the class of the Holder's

value. No mapping is provided for Holder objects in an unmarshalled

response.

Examples

Webservice client

The following route supports marshalling the request and unmarshalling a

response or fault.

String WS_URI = "cxf://http://myserver/

customerservice?serviceClass=com.example.customerservice&dataFormat=MESSAGE";

SoapJaxbDataFormat soapDF = new SoapJaxbDataFormat("com.example.customerservice",new

ServiceInterfaceStrategy(CustomerService.class));

from("direct:customerServiceClient")

.onException(Exception.class)

.handled(true)

.unmarshal(soapDF)

.end()

.marshal(soapDF)

.to(WS_URI)

.unmarshal(soapDF);

The below snippet creates a proxy for the service interface and makes a

SOAP call to the above route.

import org.apache.camel.Endpoint;

import org.apache.camel.component.bean.ProxyHelper;

...

Endpoint startEndpoint = context.getEndpoint("direct:customerServiceClient");

ClassLoader classLoader = Thread.currentThread().getContextClassLoader();

// CustomerService below is the service endpoint interface, *not* the

javax.xml.ws.Service subclass

CustomerService proxy = ProxyHelper.createProxy(startEndpoint, classLoader,

CustomerService.class);

GetCustomersByNameResponse response = proxy.getCustomersByName(new

GetCustomersByName());

355 PROTOBUF - PROTOCOL BUFFERS

Webservice Server

Using the following route sets up a webservice server that listens on jms

queue customerServiceQueue and processes requests using the class

CustomerServiceImpl. The customerServiceImpl of course should implement

the interface CustomerService. Instead of directly instantiating the server

class it could be dened in a spring context as a regular bean.

SoapJaxbDataFormat soapDF = new SoapJaxbDataFormat("com.example.customerservice",new

ServiceInterfaceStrategy(CustomerService.class));

CustomerService serverBean = new CustomerServiceImpl();

from("jms://queue:customerServiceQueue")

.onException(Exception.class)

.handled(true)

.marshal(soapDF)

.end()

.unmarshal(soapDF)

.bean(serverBean)

.marshal(soapDF);

Dependencies

To use the SOAP dataformat in your camel routes you need to add the

following dependency to your pom.

<groupId>org.apache.camel</groupId>

<artifactId>camel-soap</artifactId>

</dependency>

CRYPTO

Available as of Camel 2.3

PGP Available as of Camel 2.9

The Crypto Data Format integrates the Java Cryptographic Extension into

Camel, allowing simple and exible encryption and decryption of messages

using Camel's familiar marshall and unmarshal formatting mechanism. It

assumes marshalling to mean encryption to cyphertext and unmarshalling

decryption back to the original plaintext.

Options

Name Type Default Description

PROTOBUF - PROTOCOL BUFFERS 356

algorithm String DES/CBC/

PKCS5Padding

The JCE algoorithm name indicating the cryptographic algorithm that

will be used.

algorithmParamterSpec AlgorithmParameterSpec null A JCE AlgorithmParameterSpec used to initialize the Cipher.

bufferSize Integer 2048 the size of the buer used in the signature process.

cryptoProvider String null The name of the JCE Security Provider that should be used.

initializationVector byte[] null A byte array containing the Initialization Vector that will be used to

initialize the Cipher.

inline boolean false Flag indicating that the congured IV should be inlined into the

encrypted data stream.

macAlgorithm String null The JCE algorithm name indicating the Message Authentication

algorithm.

shouldAppendHMAC boolean null Flag indicating that a Message Authentication Code should be

calculated and appended to the encrypted data.

Basic Usage

At its most basic all that is required to encrypt/decrypt an exchange is a

shared secret key. If one or more instances of the Crypto data format are

congured with this key the format can be used to encrypt the payload in

one route (or part of one) and decrypted in another. For example, using the

Java DSL as follows:

KeyGenerator generator = KeyGenerator.getInstance("DES");

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES", generator.generateKey());

from("direct:basic-encryption")

.marshal(cryptoFormat)

.to("mock:encrypted")

.unmarshal(cryptoFormat)

.to("mock:unencrypted");

In Spring the dataformat is congured rst and then used in routes

</dataFormats>

...

<route>

</route>

</camelContext>

357 PROTOBUF - PROTOCOL BUFFERS

Specifying the Encryption Algorithm.

Changing the algorithm is a matter of supplying the JCE algorithm name. If

you change the algorithm you will need to use a compatible key.

KeyGenerator generator = KeyGenerator.getInstance("DES");

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES", generator.generateKey());

cryptoFormat.setShouldAppendHMAC(true);

cryptoFormat.setMacAlgorithm("HmacMD5");

from("direct:hmac-algorithm")

.marshal(cryptoFormat)

.to("mock:encrypted")

.unmarshal(cryptoFormat)

.to("mock:unencrypted");

Specifying an Initialization Vector.

Some crypto algorhithms, particularly block algorithms, require conguration

with an initial block of data known as an Initialization Vector. In the JCE this is

passed as an AlgorithmParameterSpec when the Cipher is initialized. To use

such a vector with the CryptoDataFormat you can congure it with a byte[]

contianing the required data e.g.

KeyGenerator generator = KeyGenerator.getInstance("DES");

byte[] initializationVector = new byte[] {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06,

0x07};

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES/CBC/PKCS5Padding",

generator.generateKey());

cryptoFormat.setInitializationVector(initializationVector);

from("direct:init-vector")

.marshal(cryptoFormat)

.to("mock:encrypted")

.unmarshal(cryptoFormat)

.to("mock:unencrypted");

or with spring, suppling a reference to a byte[]

<crypto id="initvector" algorithm="DES/CBC/PKCS5Padding" keyRef="desKey"

initVectorRef="initializationVector" />

The same vector is required in both the encryption and decryption phases. As

it is not necessary to keep the IV a secret, the DataFormat allows for it to be

inlined into the encrypted data and subsequently read out in the decryption

phase to initialize the Cipher. To inline the IV set the /oinline ag.

PROTOBUF - PROTOCOL BUFFERS 358

KeyGenerator generator = KeyGenerator.getInstance("DES");

byte[] initializationVector = new byte[] {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06,

0x07};

SecretKey key = generator.generateKey();

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES/CBC/PKCS5Padding", key);

cryptoFormat.setInitializationVector(initializationVector);

cryptoFormat.setShouldInlineInitializationVector(true);

CryptoDataFormat decryptFormat = new CryptoDataFormat("DES/CBC/PKCS5Padding", key);

decryptFormat.setShouldInlineInitializationVector(true);

from("direct:inline")

.marshal(cryptoFormat)

.to("mock:encrypted")

.unmarshal(decryptFormat)

.to("mock:unencrypted");

or with spring.

<crypto id="inline" algorithm="DES/CBC/PKCS5Padding" keyRef="desKey"

initVectorRef="initializationVector"

inline="true" />

<crypto id="inline-decrypt" algorithm="DES/CBC/PKCS5Padding" keyRef="desKey"

inline="true" />

For more information of the use of Initialization Vectors, consult

• http://en.wikipedia.org/wiki/Initialization_vector

• http://www.herongyang.com/Cryptography/

• http://en.wikipedia.org/wiki/Block_cipher_modes_of_operation

Hashed Message Authentication Codes (HMAC)

To avoid attacks against the encrypted data while it is in transit the

CryptoDataFormat can also calculate a Message Authentication Code forthe

encrypted exchange contents based on a congurable MAC algorithm. The

calculated HMAC is appended to the stream after encryption. It is separated

from the stream in the decryption phase. The MAC is recalculated and

veried against the transmitted version to insure nothing was tampered with

in transit.For more information on Message Authentication Codes see

http://en.wikipedia.org/wiki/HMAC

KeyGenerator generator = KeyGenerator.getInstance("DES");

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES", generator.generateKey());

cryptoFormat.setShouldAppendHMAC(true);

from("direct:hmac")

359 PROTOBUF - PROTOCOL BUFFERS

.marshal(cryptoFormat)

.to("mock:encrypted")

.unmarshal(cryptoFormat)

.to("mock:unencrypted");

or with spring.

By default the HMAC is calculated using the HmacSHA1 mac algorithm

though this can be easily changed by supplying a dierent algorithm name.

See [here] for how to check what algorithms are available through the

congured security providers

KeyGenerator generator = KeyGenerator.getInstance("DES");

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES", generator.generateKey());

cryptoFormat.setShouldAppendHMAC(true);

cryptoFormat.setMacAlgorithm("HmacMD5");

from("direct:hmac-algorithm")

.marshal(cryptoFormat)

.to("mock:encrypted")

.unmarshal(cryptoFormat)

.to("mock:unencrypted");

or with spring.

<crypto id="hmac-algorithm" algorithm="DES" keyRef="desKey" macAlgorithm="HmacMD5"

shouldAppendHMAC="true" />

Supplying Keys dynamically.

When using a Recipient list or similar EIP the recipient of an exchange can

vary dynamically. Using the same key across all recipients may neither be

feasible or desirable. It would be useful to be able to specify keys

dynamically on a per exchange basis. The exchange could then be

dynamically enriched with the key of its target recipient before being

processed by the data format. To facilitate this the DataFormat allow for keys

to be supplied dynamically via the message headers below

•CryptoDataFormat.KEY "CamelCryptoKey"

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES",null);

/**

PROTOBUF - PROTOCOL BUFFERS 360

* Note: the header containing the key should be cleared after

* marshalling to stop it from leaking by accident and

* potentially being compromised. The processor version below is

* arguably better as the key is left in the header when you use

* the DSL leaks the fact that camel encryption was used.

from("direct:key-in-header-encrypt")

.marshal(cryptoFormat)

.removeHeader(CryptoDataFormat.KEY)

.to("mock:encrypted");

from("direct:key-in-header-decrypt").unmarshal(cryptoFormat).process(new Processor() {

public void process(Exchange exchange) throws Exception {

exchange.getIn().getHeaders().remove(CryptoDataFormat.KEY);

exchange.getOut().copyFrom(exchange.getIn());

}

}).to("mock:unencrypted");

or with spring.

PGPDataFormat Options

Name Type Default Description

keyUserid String null The userid of the key in the pgp keyring

password String null Password used when opening the private key (not used for encryption)

keyFileName String null Filename of the keyring, must be accessible as classpathresource

armored boolean false This option will cause pgp to base64 encode the encrypted text, making it available for copy/paste,

etc.

integrity boolean true add a integrity check/sign into the encryption le

Encrypting with PGPDataFormat

The following sample uses the popular PGP format for encrypting/decypting

les using the libraries from http://www.bouncycastle.org/java.html. For help

managing your keyring see the next section

// Public Key FileName

String keyFileName = "org/apache/camel/component/crypto/pubring.gpg";

// Private Key FileName

String keyFileNameSec = "org/apache/camel/component/crypto/secring.gpg";

// Keyring Userid Used to Encrypt

String keyUserid = "sdude@nowhere.net";

// Private key password

String keyPassword = "sdude";

361 PROTOBUF - PROTOCOL BUFFERS

from("direct:inline")

.marshal().pgp(keyFileName, keyUserid)

.to("mock:encrypted")

.unmarshal().pgp(keyFileNameSec, keyUserid, keyPassword)

.to("mock:unencrypted");

or using spring

<!-- will load the file from classpath by default, but you can prefix with file: to

load from file system -->

<pgp id="encrypt" keyFileName="org/apache/camel/component/crypto/pubring.gpg"

keyUserid="sdude@nowhere.net"/>

<pgp id="decrypt" keyFileName="org/apache/camel/component/crypto/secring.gpg"

keyUserid="sdude@nowhere.net" password="sdude"/>

</dataFormats>

<route>

</route>

To work with the previous example you need the

following

• A public keyring le which contains the public keys used to encrypt

the data

• A private keyring le which contains the keys used to decrypt the

data

• The keyring password

Managing your keyring

To manage the keyring, I use the command line tools, I nd this to be the

simplest approach in managing the keys. There are also Java libraries

available from http://www.bouncycastle.org/java.html if you would prefer to

do it that way.

1. Install the command line utilities on linux

apt-get install gnupg

2. Create your keyring, entering a secure password

PROTOBUF - PROTOCOL BUFFERS 362

gpg --gen-key

3. If you need to import someone elses public key so that you can

encrypt a le for them.

gpg --import <filename.key

4. The following les should now exist and can be used to run the

example

ls -l ~/.gnupg/pubring.gpg ~/.gnupg/secring.gpg

Dependencies

To use the Crypto dataformat in your camel routes you need to add the

following dependency to your pom.

<groupId>org.apache.camel</groupId>

<artifactId>camel-crypto</artifactId>

</dependency>

See Also

• Data Format

• Crypto (Digital Signatures)

• http://www.bouncycastle.org/java.html

SYSLOG DATAFORMAT

Available as of Camel 2.6

The syslog dataformat is used for working with RFC3164 messages.

This component supports the following:

▪ UDP consumption of syslog messages

▪ Agnostic data format using either plain String objects or

SyslogMessage model objects.

▪ Type Converter from/to SyslogMessage and String

▪ Integration with the camel-mina component.

▪ Integration with the camel-netty component.

363 PROTOBUF - PROTOCOL BUFFERS

Maven users will need to add the following dependency to their pom.xml for

this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-syslog</artifactId>

</dependency>

RFC3164 Syslog protocol

Syslog uses the user datagram protocol (UDP) [1] as its underlying transport

layer mechanism.

The UDP port that has been assigned to syslog is 514.

To expose a Syslog listener service we reuse the existing camel-mina

component or camel-netty where we just use the Rfc3164SyslogDataFormat

to marshal and unmarshal messages

Exposing a Syslog listener

In our Spring XML le, we congure an endpoint to listen for udp messages

on port 10514, note that in netty we disable the defaultCodec, this

will allow a fallback to a NettyTypeConverter and delivers the message as an

InputStream:

</dataFormats>

<route>

<from

uri="netty:udp://localhost:10514?sync=false&allowDefaultCodec=false"/>

</route>

</camelContext>

The same route using camel-mina

PROTOBUF - PROTOCOL BUFFERS 364

</dataFormats>

<route>

</route>

</camelContext>

Sending syslog messages to a remote destination

</dataFormats>

<route>

</route>

</camelContext>

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

365 PROTOBUF - PROTOCOL BUFFERS

CHAPTER 10

°°°°

Pattern Appendix

There now follows a breakdown of the various Enterprise Integration Patterns

that Camel supports

MESSAGING SYSTEMS

Message Channel

Camel supports the Message Channel from the EIP patterns. The Message

Channel is an internal implementation detail of the Endpoint interface and all

interactions with the Message Channel are via the Endpoint interfaces.

For more details see

• Message

• Message Endpoint

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Message

Camel supports the Message from the EIP patterns using the Message

interface.

CHAPTER 10 - PATTERN APPENDIX 366

To support various message exchange patterns like one way Event

Message and Request Reply messages Camel uses an Exchange interface

which has a pattern property which can be set to InOnly for an Event

Message which has a single inbound Message, or InOut for a Request Reply

where there is an inbound and outbound message.

Here is a basic example of sending a Message to a route in InOnly and

InOut modes

Requestor Code

//InOnly

getContext().createProducerTemplate().sendBody("direct:startInOnly","Hello World");

//InOut

String result = (String)

getContext().createProducerTemplate().requestBody("direct:startInOut","Hello World");

Route Using the Fluent Builders

from("direct:startInOnly").inOnly("bean:process");

from("direct:startInOut").inOut("bean:process");

Route Using the Spring XML Extensions

<route>

</route>

<route>

</route>

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

367 CHAPTER 10 - PATTERN APPENDIX

Pipes and Filters

Camel supports the Pipes and Filters from the EIP patterns in various ways.

With Camel you can split your processing across multiple independent

Endpoint instances which can then be chained together.

Using Routing Logic

You can create pipelines of logic using multiple Endpoint or Message

Translator instances as follows

from("direct:a").pipeline("direct:x","direct:y","direct:z","mock:result");

Though pipeline is the default mode of operation when you specify multiple

outputs in Camel. The opposite to pipeline is multicast; which res the same

message into each of its outputs. (See the example below).

In Spring XML you can use the <pipeline/> element as of 1.4.0 onwards

<route>

</pipeline>

</route>

In the above the pipeline element is actually unnecessary, you could use

this...

<route>

</route>

Its just a bit more explicit. However if you wish to use <multicast/> to avoid

a pipeline - to send the same message into multiple pipelines - then the

<pipeline/> element comes into its own.

CHAPTER 10 - PATTERN APPENDIX 368

<route>

</pipeline>

</pipeline>

</multicast>

</route>

In the above example we are routing from a single Endpoint to a list of

dierent endpoints specied using URIs. If you nd the above a bit confusing,

try reading about the Architecture or try the Examples

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Message Router

The Message Router from the EIP patterns allows you to consume from an

input destination, evaluate some predicate then choose the right output

destination.

The following example shows how to route a request from an input

queue:a endpoint to either queue:b,queue:c or queue:d depending on

the evaluation of various Predicate expressions

Using the Fluent Builders

RouteBuilder builder = new RouteBuilder() {

public void configure() {

369 CHAPTER 10 - PATTERN APPENDIX

errorHandler(deadLetterChannel("mock:error"));

from("seda:a")

.choice()

.when(header("foo").isEqualTo("bar"))

.to("seda:b")

.when(header("foo").isEqualTo("cheese"))

.to("seda:c")

.otherwise()

.to("seda:d");

}

};

Using the Spring XML Extensions

<camelContext errorHandlerRef="errorHandler" xmlns="http://camel.apache.org/schema/

spring">

<route>

<when>

</when>

<when>

<xpath>$foo = 'cheese'</xpath>

</when>

</otherwise>

</choice>

</route>

</camelContext>

Choice without otherwise

If you use a choice without adding an otherwise, any unmatched exchanges

will be dropped by default.

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

CHAPTER 10 - PATTERN APPENDIX 370

Message Translator

Camel supports the Message Translator from the EIP patterns by using an

arbitrary Processor in the routing logic, by using a bean to perform the

transformation, or by using transform() in the DSL. You can also use a Data

Format to marshal and unmarshal messages in dierent encodings.

Using the Fluent Builders

You can transform a message using Camel's Bean Integration to call any

method on a bean in your Registry such as your Spring XML conguration le

as follows

from("activemq:SomeQueue").

beanRef("myTransformerBean","myMethodName").

to("mqseries:AnotherQueue");

Where the "myTransformerBean" would be dened in a Spring XML le or

dened in JNDI etc. You can omit the method name parameter from

beanRef() and the Bean Integration will try to deduce the method to invoke

from the message exchange.

or you can add your own explicit Processor to do the transformation

from("direct:start").process(new Processor() {

public void process(Exchange exchange) {

Message in = exchange.getIn();

in.setBody(in.getBody(String.class) + " World!");

}

}).to("mock:result");

or you can use the DSL to explicitly congure the transformation

from("direct:start").transform(body().append(" World!")).to("mock:result");

Use Spring XML

You can also use Spring XML Extensions to do a transformation. Basically

any Expression language can be substituted inside the transform element as

shown below

<route>

371 CHAPTER 10 - PATTERN APPENDIX

<simple>${in.body} extra data!</simple>

</transform>

</route>

</camelContext>

Or you can use the Bean Integration to invoke a bean

<route>

</route>

You can also use Templating to consume a message from one destination,

transform it with something like Velocity or XQuery and then send it on to

another destination. For example using InOnly (one way messaging)

from("activemq:My.Queue").

to("velocity:com/acme/MyResponse.vm").

to("activemq:Another.Queue");

If you want to use InOut (request-reply) semantics to process requests on the

My.Queue queue on ActiveMQ with a template generated response, then

sending responses back to the JMSReplyTo Destination you could use this.

from("activemq:My.Queue").

to("velocity:com/acme/MyResponse.vm");

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

▪ Content Enricher

▪ Using getIn or getOut methods on Exchange

Message Endpoint

Camel supports the Message Endpoint from the EIP patterns using the

Endpoint interface.

CHAPTER 10 - PATTERN APPENDIX 372

When using the DSL to create Routes you typically refer to Message

Endpoints by their URIs rather than directly using the Endpoint interface. Its

then a responsibility of the CamelContext to create and activate the

necessary Endpoint instances using the available Component

implementations.

For more details see

• Message

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

MESSAGING CHANNELS

Point to Point Channel

Camel supports the Point to Point Channel from the EIP patterns using the

following components

• SEDA for in-VM seda based messaging

• JMS for working with JMS Queues for high performance, clustering

and load balancing

• JPA for using a database as a simple message queue

• XMPP for point-to-point communication over XMPP (Jabber)

• and others

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

373 CHAPTER 10 - PATTERN APPENDIX

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Publish Subscribe Channel

Camel supports the Publish Subscribe Channel from the EIP patterns using for

example the following components:

• JMS for working with JMS Topics for high performance, clustering and

load balancing

• XMPP when using rooms for group communication

• SEDA for working with SEDA in the same CamelContext which can

work in pub-sub, but allowing multiple consumers.

• VM as SEDA but for intra-JVM.

Using Routing Logic

Another option is to explicitly list the publish-subscribe relationship in your

routing logic; this keeps the producer and consumer decoupled but lets you

control the ne grained routing conguration using the DSL or Xml

Conguration.

Using the Fluent Builders

RouteBuilder builder = new RouteBuilder() {

public void configure() {

errorHandler(deadLetterChannel("mock:error"));

from("seda:a")

.multicast().to("seda:b","seda:c","seda:d");

}

};

Using the Spring XML Extensions

CHAPTER 10 - PATTERN APPENDIX 374

<camelContext errorHandlerRef="errorHandler" xmlns="http://camel.apache.org/schema/

spring">

<route>

</multicast>

</route>

</camelContext>

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

DEAD LETTER CHANNEL

Camel supports the Dead Letter Channel from the EIP patterns using the

DeadLetterChannel processor which is an Error Handler.

Redelivery

It is common for a temporary outage or database deadlock to cause a

message to fail to process; but the chances are if its tried a few more times

with some time delay then it will complete ne. So we typically wish to use

some kind of redelivery policy to decide how many times to try redeliver a

message and how long to wait before redelivery attempts.

The RedeliveryPolicy denes how the message is to be redelivered. You

can customize things like

375 CHAPTER 10 - PATTERN APPENDIX

Dierence between Dead Letter Channel and Default Error

Handler

The major dierence is that Dead Letter Channel has a dead letter

queue that whenever an Exchange could not be processed is

moved to. It will always moved failed exchanges to this queue.

Unlike the Default Error Handler that does not have a dead letter queue.

So whenever an Exchange could not be processed the error is propagated

back to the client.

Notice: You can adjust this behavior of whether the client should be

notied or not with the handled option.

• how many times a message is attempted to be redelivered before it

is considered a failure and sent to the dead letter channel

• the initial redelivery timeout

• whether or not exponential backo is used (i.e. the time between

retries increases using a backo multiplier)

• whether to use collision avoidance to add some randomness to the

timings

• delay pattern a new option in Camel 2.0, see below for details.

Once all attempts at redelivering the message fails then the message is

forwarded to the dead letter queue.

About moving Exchange to dead letter queue and using handled

Handled on Dead Letter Channel was introduced in Camel 2.0, this feature

does not exist in Camel 1.x

When all attempts of redelivery have failed the Exchange is moved to the

dead letter queue (the dead letter endpoint). The exchange is then complete

and from the client point of view it was processed. As such the Dead Letter

Channel have handled the Exchange.

For instance conguring the dead letter channel as:

Using the Fluent Builders

errorHandler(deadLetterChannel("jms:queue:dead")

.maximumRedeliveries(3).redeliveryDelay(5000));

Using the Spring XML Extensions

CHAPTER 10 - PATTERN APPENDIX 376

...

</route>

<bean id="myDeadLetterErrorHandler"

class="org.apache.camel.builder.DeadLetterChannelBuilder">

</bean>

<bean id="myRedeliveryPolicyConfig"

class="org.apache.camel.processor.RedeliveryPolicy">

</bean>

The Dead Letter Channel above will clear the caused exception

(setException(null)), by moving the caused exception to a property on the

Exchange, with the key Exchange.EXCEPTION_CAUGHT. Then the Exchange is

moved to the "jms:queue:dead" destination and the client will not notice

the failure.

About moving Exchange to dead letter queue and using the original

message

Available as of Camel 2.0

The option useOriginalMessage is used for routing the original input

message instead of the current message that potentially is modied during

routing.

For instance if you have this route:

from("jms:queue:order:input")

.to("bean:validateOrder")

.to("bean:transformOrder")

.to("bean:handleOrder");

The route listen for JMS messages and validates, transforms and handle it.

During this the Exchange payload is transformed/modied. So in case

something goes wrong and we want to move the message to another JMS

destination, then we can congure our Dead Letter Channel with the

useOriginalBody option. But when we move the Exchange to this

destination we do not know in which state the message is in. Did the error

happen in before the transformOrder or after? So to be sure we want to move

the original input message we received from jms:queue:order:input. So we

can do this by enabling the useOriginalMessage option as shown below:

377 CHAPTER 10 - PATTERN APPENDIX

// will use original body

errorHandler(deadLetterChannel("jms:queue:dead")

.useOriginalMessage().mamimumRedeliveries(5).redeliverDelay(5000);

Then the messages routed to the jms:queue:dead is the original input. If we

want to manually retry we can move the JMS message from the failed to the

input queue, with no problem as the message is the same as the original we

received.

OnRedelivery

Available in Camel 1.6.0 onwards

When Dead Letter Channel is doing redeliver its possible to congure a

Processor that is executed just before every redelivery attempt. This can be

used for the situations where you need to alter the message before its

redelivered. See below for sample.

Redelivery default values

In Camel 2.0 redelivery is disabled by default, as opposed to Camel 1.x in

which Dead Letter Channel is congured with maximumRedeliveries=5.

The default redeliver policy will use the following values:

• maximumRedeliveries=0 (in Camel 1.x the default value is 5)

• redeliverDelay=1000L (1 second, new as of Camel 2.0)

◦ use initialRedeliveryDelay for previous versions

• maximumRedeliveryDelay = 60 * 1000L (60 seconds)

• And the exponential backo and collision avoidance is turned o.

• The retriesExhaustedLogLevel are set to LoggingLevel.ERROR

• The retryAttemptedLogLevel are set to LoggingLevel.DEBUG

• Stack traces is logged for exhausted messages from Camel 2.2

onwards.

• Handled exceptions is not logged from Camel 2.3 onwards

The maximum redeliver delay ensures that a delay is never longer than the

value, default 1 minute. This can happen if you turn on the exponential

backo.

The maximum redeliveries is the number of re delivery attempts. By

default Camel will try to process the exchange 1 + 5 times. 1 time for the

normal attempt and then 5 attempts as redeliveries.

Setting the maximumRedeliveries to a negative value such as -1 will then

always redelivery (unlimited).

Setting the maximumRedeliveries to 0 will disable any re delivery attempt.

CHAPTER 10 - PATTERN APPENDIX 378

onException and onRedeliver

In Camel 2.0 we also added support for per onException to set a

onRedeliver. That means you can do special on redelivery for

dierent exceptions, as opposed to onRedelivery set on Dead Letter

Channel can be viewed as a global scope.

Camel will log delivery failures at the DEBUG logging level by default. You

can change this by specifying retriesExhaustedLogLevel and/or

retryAttemptedLogLevel. See ExceptionBuilderWithRetryLoggingLevelSetTest

for an example.

In Camel 2.0 you can turn logging of stack traces on/o. If turned o

Camel will still log the redelivery attempt. Its just much less verbose.

Redeliver Delay Pattern

Available as of Camel 2.0

Delay pattern is used as a single option to set a range pattern for delays. If

used then the following options does not apply: (delay, backOMultiplier,

useExponentialBackO, useCollisionAvoidance, maximumRedeliveryDelay).

The idea is to set groups of ranges using the following syntax:

limit:delay;limit 2:delay 2;limit 3:delay 3;...;limit N:delay N

Each group has two values separated with colon

▪ limit = upper limit

▪ delay = delay in millis

And the groups is again separated with semi colon.

The rule of thumb is that the next groups should have a higher limit

than the previous group.

Lets clarify this with an example:

delayPattern=5:1000;10:5000;20:20000

That gives us 3 groups:

▪ 5:1000

▪ 10:5000

▪ 20:20000

Resulting in these delays for redelivery attempt:

▪ Redelivery attempt number 1..4 = 0 millis (as the rst group start

with 5)

▪ Redelivery attempt number 5..9 = 1000 millis (the rst group)

▪ Redelivery attempt number 10..19 = 5000 millis (the second group)

▪ Redelivery attempt number 20.. = 20000 millis (the last group)

379 CHAPTER 10 - PATTERN APPENDIX

Note: The rst redelivery attempt is 1, so the rst group should start with 1

or higher.

You can start a group with limit 1 to eg have a starting delay:

delayPattern=1:1000;5:5000

▪ Redelivery attempt number 1..4 = 1000 millis (the rst group)

▪ Redelivery attempt number 5.. = 5000 millis (the last group)

There is no requirement that the next delay should be higher than the

previous. You can use any delay value you like. For example with

delayPattern=1:5000;3:1000 we start with 5 sec delay and then later

reduce that to 1 second.

Redelivery header

When a message is redelivered the DeadLetterChannel will append a

customizable header to the message to indicate how many times its been

redelivered.

In Camel 1.x: The header is org.apache.camel.redeliveryCount.

In Camel 2.0: The header is CamelRedeliveryCounter, which is also

dened on the Exchange.REDELIVERY_COUNTER.

In Camel 2.6: The header CamelRedeliveryMaxCounter, which is also

dened on the Exchange.REDELIVERY_MAX_COUNTER, contains the maximum

redelivery setting. This header is absent if you use retryWhile or have

unlimited maximum redelivery congured.

And a boolean ag whether it is being redelivered or not (rst attempt)

In Camel 1.x: The header org.apache.camel.Redelivered contains a

boolean if the message is redelivered or not.

In Camel 2.0: The header CamelRedelivered contains a boolean if the

message is redelivered or not, which is also dened on the

Exchange.REDELIVERED.

Dynamically calculated delay from the exchange

In Camel 2.9 and 2.8.2: The header is CamelRedeliveryDelay, which is also

dened on the Exchange.REDELIVERY_DELAY.

Is this header is absent, normal redelivery rules apply.

Which endpoint failed

Available as of Camel 2.1

When Camel routes messages it will decorate the Exchange with a

property that contains the last endpoint Camel send the Exchange to:

String lastEndpointUri = exchange.getProperty(Exchange.TO_ENDPOINT, String.class);

CHAPTER 10 - PATTERN APPENDIX 380

The Exchange.TO_ENDPOINT have the constant value CamelToEndpoint.

This information is updated when Camel sends a message to any

endpoint. So if it exists its the last endpoint which Camel send the Exchange

to.

When for example processing the Exchange at a given Endpoint and the

message is to be moved into the dead letter queue, then Camel also

decorates the Exchange with another property that contains that last

endpoint:

String failedEndpointUri = exchange.getProperty(Exchange.FAILURE_ENDPOINT,

String.class);

The Exchange.FAILURE_ENDPOINT have the constant value

CamelFailureEndpoint.

This allows for example you to fetch this information in your dead letter

queue and use that for error reporting.

This is useable if the Camel route is a bit dynamic such as the dynamic

Recipient List so you know which endpoints failed.

Notice: These information is kept on the Exchange even if the message

was successfully processed by a given endpoint, and then later fails for

example in a local Bean processing instead. So beware that this is a hint that

helps pinpoint errors.

from("activemq:queue:foo")

.to("http://someserver/somepath")

.beanRef("foo");

Now suppose the route above and a failure happens in the foo bean. Then

the Exchange.TO_ENDPOINT and Exchange.FAILURE_ENDPOINT will still

contain the value of http://someserver/somepath.

Samples

The following example shows how to congure the Dead Letter Channel

conguration using the DSL

RouteBuilder builder = new RouteBuilder() {

public void configure() {

// using dead letter channel with a seda queue for errors

errorHandler(deadLetterChannel("seda:errors"));

// here is our route

from("seda:a").to("seda:b");

381 CHAPTER 10 - PATTERN APPENDIX

}

};

You can also congure the RedeliveryPolicy as this example shows

RouteBuilder builder = new RouteBuilder() {

public void configure() {

// configures dead letter channel to use seda queue for errors and use at

most 2 redelveries

// and exponential backoff

errorHandler(deadLetterChannel("seda:errors").maximumRedeliveries(2).useExponentialBackOff());

// here is our route

from("seda:a").to("seda:b");

}

};

How can I modify the Exchange before redelivery?

In Camel 1.6.0 we added support directly in Dead Letter Channel to set a

Processor that is executed before each redelivery attempt.

When Dead Letter Channel is doing redeliver its possible to congure a

Processor that is executed just before every redelivery attempt. This can be

used for the situations where you need to alter the message before its

redelivered.

Here we congure the Dead Letter Channel to use our processor

MyRedeliveryProcessor to be executed before each redelivery.

// we configure our Dead Letter Channel to invoke

// MyRedeliveryProcessor before a redelivery is

// attempted. This allows us to alter the message before

errorHandler(deadLetterChannel("mock:error").maximumRedeliveries(5)

.onRedelivery(new MyRedeliverProcessor())

// setting delay to zero is just to make unit testing faster

.redeliveryDelay(0L));

And this is the processor MyRedeliveryProcessor where we alter the

message.

// This is our processor that is executed before every redelivery attempt

// here we can do what we want in the java code, such as altering the message

public class MyRedeliverProcessor implements Processor {

public void process(Exchange exchange) throws Exception {

// the message is being redelivered so we can alter it

CHAPTER 10 - PATTERN APPENDIX 382

// we just append the redelivery counter to the body

// you can of course do all kind of stuff instead

String body = exchange.getIn().getBody(String.class);

int count = exchange.getIn().getHeader(Exchange.REDELIVERY_COUNTER,

Integer.class);

exchange.getIn().setBody(body + count);

// the maximum redelivery was set to 5

int max = exchange.getIn().getHeader(Exchange.REDELIVERY_MAX_COUNTER,

Integer.class);

assertEquals(5, max);

}

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

▪ Error Handler

▪ Exception Clause

Guaranteed Delivery

Camel supports the Guaranteed Delivery from the EIP patterns using among

others the following components:

• File for using le systems as a persistent store of messages

• JMS when using persistent delivery (the default) for working with JMS

Queues and Topics for high performance, clustering and load

balancing

• JPA for using a database as a persistence layer, or use any of the

many other database component such as SQL, JDBC, iBATIS/MyBatis,

Hibernate

• HawtDB for a lightweight key-value persistent store

383 CHAPTER 10 - PATTERN APPENDIX

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Message Bus

Camel supports the Message Bus from the EIP patterns. You could view

Camel as a Message Bus itself as it allows producers and consumers to be

decoupled.

Folks often assume that a Message Bus is a JMS though so you may wish

to refer to the JMS component for traditional MOM support.

Also worthy of node is the XMPP component for supporting messaging over

XMPP (Jabber)

Of course there is also ESB product such as Apache ServiceMix which is a

full edge message bus.

You can interact with Apache ServiceMix from Camel in many ways, but in

particular you can use the NMR or JBI component to access the ServiceMix

message bus directly.

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

CHAPTER 10 - PATTERN APPENDIX 384

Message Construction

EVENT MESSAGE

Camel supports the Event Message from the EIP patterns by supporting the

Exchange Pattern on a Message which can be set to InOnly to indicate a

oneway event message. Camel Components then implement this pattern

using the underlying transport or protocols.

The default behaviour of many Components is InOnly such as for JMS, File

or SEDA

Explicitly specifying InOnly

If you are using a component which defaults to InOut you can override the

Exchange Pattern for an endpoint using the pattern property.

foo:bar?exchangePattern=InOnly

From 2.0 onwards on Camel you can specify the Exchange Pattern using the

dsl.

Using the Fluent Builders

from("mq:someQueue").

inOnly().

bean(Foo.class);

or you can invoke an endpoint with an explicit pattern

from("mq:someQueue").

inOnly("mq:anotherQueue");

Using the Spring XML Extensions

385 CHAPTER 10 - PATTERN APPENDIX

See the related Request Reply message.

<route>

</route>

<route>

</route>

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

REQUEST REPLY

Camel supports the Request Reply from the EIP patterns by supporting the

Exchange Pattern on a Message which can be set to InOut to indicate a

request/reply. Camel Components then implement this pattern using the

underlying transport or protocols.

For example when using JMS with InOut the component will by default

perform these actions

• create by default a temporary inbound queue

• set the JMSReplyTo destination on the request message

• set the JMSCorrelationID on the request message

• send the request message

CHAPTER 10 - PATTERN APPENDIX 386

• consume the response and associate the inbound message to the

request using the JMSCorrelationID (as you may be performing many

concurrent request/responses).

Explicitly specifying InOut

When consuming messages from JMS a Request-Reply is indicated by the

presence of the JMSReplyTo header.

You can explicitly force an endpoint to be in Request Reply mode by

setting the exchange pattern on the URI. e.g.

jms:MyQueue?exchangePattern=InOut

You can specify the exchange pattern in DSL rule or Spring conguration.

// Send to an endpoint using InOut

from("direct:testInOut").inOut("mock:result");

// Send to an endpoint using InOut

from("direct:testInOnly").inOnly("mock:result");

// Set the exchange pattern to InOut, then send it from direct:inOnly to mock:result

endpoint

from("direct:testSetToInOnlyThenTo")

.setExchangePattern(ExchangePattern.InOnly)

.to("mock:result");

from("direct:testSetToInOutThenTo")

.setExchangePattern(ExchangePattern.InOut)

.to("mock:result");

// Or we can pass the pattern as a parameter to the to() method

from("direct:testToWithInOnlyParam").to(ExchangePattern.InOnly, "mock:result");

from("direct:testToWithInOutParam").to(ExchangePattern.InOut, "mock:result");

from("direct:testToWithRobustInOnlyParam").to(ExchangePattern.RobustInOnly,

"mock:result");

// Set the exchange pattern to InOut, then send it on

from("direct:testSetExchangePatternInOnly")

.setExchangePattern(ExchangePattern.InOnly).to("mock:result");

<route>

</route>

387 CHAPTER 10 - PATTERN APPENDIX

See the related Event Message message

<route>

</route>

<route>

</route>

<route>

</route>

<route>

</route>

<route>

</route>

<route>

</route>

<route>

</route>

</camelContext>

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

CHAPTER 10 - PATTERN APPENDIX 388

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Correlation Identier

Camel supports the Correlation Identier from the EIP patterns by getting or

setting a header on a Message.

When working with the ActiveMQ or JMS components the correlation

identier header is called JMSCorrelationID. You can add your own

correlation identier to any message exchange to help correlate messages

together to a single conversation (or business process).

The use of a Correlation Identier is key to working with the Camel

Business Activity Monitoring Framework and can also be highly useful when

testing with simulation or canned data such as with the Mock testing

framework

Some EIP patterns will spin o a sub message, and in those cases, Camel

will add a correlation id on the Exchange as a property with they key

Exchange.CORRELATION_ID, which links back to the source Exchange. For

example the Splitter, Multicast, Recipient List, and Wire Tap EIP does this.

See Also

• BAM

RETURN ADDRESS

Camel supports the Return Address from the EIP patterns by using the

JMSReplyTo header.

389 CHAPTER 10 - PATTERN APPENDIX

For example when using JMS with InOut the component will by default

return to the address given in JMSReplyTo.

Requestor Code

getMockEndpoint("mock:bar").expectedBodiesReceived("Bye World");

template.sendBodyAndHeader("direct:start","World","JMSReplyTo","queue:bar");

Route Using the Fluent Builders

from("direct:start").to("activemq:queue:foo?preserveMessageQos=true");

from("activemq:queue:foo").transform(body().prepend("Bye "));

from("activemq:queue:bar?disableReplyTo=true").to("mock:bar");

Route Using the Spring XML Extensions

<route>

</route>

<route>

</transform>

</route>

<route>

</route>

For a complete example of this pattern, see this junit test case

CHAPTER 10 - PATTERN APPENDIX 390

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

MESSAGE ROUTING

Content Based Router

The Content Based Router from the EIP patterns allows you to route

messages to the correct destination based on the contents of the message

exchanges.

The following example shows how to route a request from an input seda:a

endpoint to either seda:b,seda:c or seda:d depending on the evaluation of

various Predicate expressions

Using the Fluent Builders

RouteBuilder builder = new RouteBuilder() {

public void configure() {

errorHandler(deadLetterChannel("mock:error"));

from("seda:a")

.choice()

.when(header("foo").isEqualTo("bar"))

.to("seda:b")

.when(header("foo").isEqualTo("cheese"))

.to("seda:c")

.otherwise()

.to("seda:d");

}

};

Using the Spring XML Extensions

<camelContext errorHandlerRef="errorHandler" xmlns="http://camel.apache.org/schema/

spring">

<route>

391 CHAPTER 10 - PATTERN APPENDIX

<when>

</when>

<when>

<xpath>$foo = 'cheese'</xpath>

</when>

</otherwise>

</choice>

</route>

</camelContext>

For further examples of this pattern in use you could look at the junit test

case

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Message Filter

The Message Filter from the EIP patterns allows you to lter messages

The following example shows how to create a Message Filter route

consuming messages from an endpoint called queue:a which if the

Predicate is true will be dispatched to queue:b

Using the Fluent Builders

RouteBuilder builder = new RouteBuilder() {

public void configure() {

errorHandler(deadLetterChannel("mock:error"));

from("seda:a")

.filter(header("foo").isEqualTo("bar"))

.to("seda:b");

CHAPTER 10 - PATTERN APPENDIX 392

}

};

You can of course use many dierent Predicate languages such as XPath,

XQuery, SQL or various Scripting Languages. Here is an XPath example

from("direct:start").

filter().xpath("/person[@name='James']").

to("mock:result");

Here is another example of using a bean to dene the lter behavior

from("direct:start")

.filter().method(MyBean.class, "isGoldCustomer").to("mock:result").end()

.to("mock:end");

public static class MyBean {

public boolean isGoldCustomer(@Header("level")String level) {

return level.equals("gold");

}

Using the Spring XML Extensions

<camelContext errorHandlerRef="errorHandler" xmlns="http://camel.apache.org/schema/

spring">

<route>

</filter>

</route>

</camelContext>

For further examples of this pattern in use you could look at the junit test

case

Using stop

Available as of Camel 2.0

Stop is a bit dierent than a message lter as it will lter out all messages

and end the route entirely (lter only applies to its child processor). Stop is

convenient to use in a Content Based Router when you for example need to

stop further processing in one of the predicates.

393 CHAPTER 10 - PATTERN APPENDIX

ltered endpoint required inside </lter> tag

make sure you put the endpoint you want to lter (<to

uri="seda:b"/>, etc.) before the closing </lter> tag or the lter

will not be applied (in 2.8+, omitting this will result in an error)

In the example below we do not want to route messages any further that

has the word Bye in the message body. Notice how we prevent this in the

when predicate by using the .stop().

from("direct:start")

.choice()

.when(body().contains("Hello")).to("mock:hello")

.when(body().contains("Bye")).to("mock:bye").stop()

.otherwise().to("mock:other")

.end()

.to("mock:result");

Knowing if Exchange was ltered or not

Available as of Camel 2.5

The Message Filter EIP will add a property on the Exchange which states if

it was ltered or not.

The property has the key Exchannge.FILTER_MATCHED which has the

String value of CamelFilterMatched. Its value is a boolean indicating true or

false. If the value is true then the Exchange was routed in the lter block.

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

DYNAMIC ROUTER

The Dynamic Router from the EIP patterns allows you to route messages

while avoiding the dependency of the router on all possible destinations

while maintaining its eciency.

CHAPTER 10 - PATTERN APPENDIX 394

In Camel 2.5 we introduced a dynamicRouter in the DSL which is like a

dynamic Routing Slip which evaluates the slip on-the-y.

Options

Name Default

Value Description

uriDelimiter , Delimiter used if the Expression returned multiple endpoints.

ignoreInvalidEndpoints false If an endpoint uri could not be resolved, should it be ignored. Otherwise Camel will thrown an

exception stating the endpoint uri is not valid.

Dynamic Router in Camel 2.5 onwards

From Camel 2.5 the Dynamic Router will set a property

(Exchange.SLIP_ENDPOINT) on the Exchange which contains the current

endpoint as it advanced though the slip. This allows you to know how far we

have processed in the slip. (It's a slip because the Dynamic Router

implementation is based on top of Routing Slip).

Java DSL

In Java DSL you can use the dynamicRouter as shown below:

from("direct:start")

// use a bean as the dynamic router

.dynamicRouter(bean(DynamicRouterTest.class, "slip"));

Which will leverage a Bean to compute the slip on-the-y, which could be

implemented as follows:

/**

* Use this method to compute dynamic where we should route next.

* @param body the message body

395 CHAPTER 10 - PATTERN APPENDIX

Beware

You must ensure the expression used for the dynamicRouter such

as a bean, will return null to indicate the end. Otherwise the

dynamicRouter will keep repeating endlessly.

* @return endpoints to go, or <tt>null</tt> to indicate the end

public String slip(String body) {

bodies.add(body);

invoked++;

if (invoked == 1) {

return "mock:a";

}else if (invoked == 2) {

return "mock:b,mock:c";

}else if (invoked == 3) {

return "direct:foo";

}else if (invoked == 4) {

return "mock:result";

}

// no more so return null

return null;

}

Mind that this example is only for show and tell. The current implementation

is not thread safe. You would have to store the state on the Exchange, to

ensure thread safety.

Spring XML

The same example in Spring XML would be:

<route>

</dynamicRouter>

</route>

<route>

CHAPTER 10 - PATTERN APPENDIX 396

<transform><constant>Bye World</constant></transform>

</route>

</camelContext>

@DynamicRouter annotation

You can also use the @DynamicRouter annotation, for example the Camel 2.4

example below could be written as follows. The route method would then be

invoked repeatedly as the message is processed dynamically. The idea is to

return the next endpoint uri where to go. Return null to indicate the end. You

can return multiple endpoints if you like, just as the Routing Slip, where each

endpoint is separated by a delimiter.

public class MyDynamicRouter {

@Consume(uri = "activemq:foo")

@DynamicRouter

public String route(@XPath("/customer/id")String customerId, @Header("Location")

String location, Document body) {

// query a database to find the best match of the endpoint based on the input

parameteres

// return the next endpoint uri, where to go. Return null to indicate the end.

}

Dynamic Router in Camel 2.4 or older

The simplest way to implement this is to use the RecipientList Annotation on

a Bean method to determine where to route the message.

public class MyDynamicRouter {

@Consume(uri = "activemq:foo")

@RecipientList

public List<String> route(@XPath("/customer/id")String customerId,

@Header("Location")String location, Document body) {

// query a database to find the best match of the endpoint based on the input

parameteres

...

}

397 CHAPTER 10 - PATTERN APPENDIX

In the above we can use the Parameter Binding Annotations to bind dierent

parts of the Message to method parameters or use an Expression such as

using XPath or XQuery.

The method can be invoked in a number of ways as described in the Bean

Integration such as

• POJO Producing

• Spring Remoting

• Bean component

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Recipient List

The Recipient List from the EIP patterns allows you to route messages to a

number of dynamically specied recipients.

The recipients will receive a copy of the same Exchange and Camel will

execute them sequentially.

Options

Name Default

Value Description

delimiter , Delimiter used if the Expression returned multiple endpoints.

strategyRef

Refers to an AggregationStrategy to be used to assemble the replies from the recipients, into a

single outgoing message from the Recipient List. By default Camel will use the last reply as the

outgoing message.

parallelProcessing false

Camel 2.2: If enables then sending messages to the recipients occurs concurrently. Note the

caller thread will still wait until all messages has been fully processed, before it continues. Its only

the sending and processing the replies from the recipients which happens concurrently.

executorServiceRef

Camel 2.2: Refers to a custom Thread Pool to be used for parallel processing. Notice if you set this

option, then parallel processing is automatic implied, and you do not have to enable that option as

well.

CHAPTER 10 - PATTERN APPENDIX 398

stopOnException false

Camel 2.2: Whether or not to stop continue processing immediately when an exception occurred.

If disable, then Camel will send the message to all recipients regardless if one of them failed. You

can deal with exceptions in the AggregationStrategy class where you have full control how to

handle that.

ignoreInvalidEndpoints false Camel 2.3: If an endpoint uri could not be resolved, should it be ignored. Otherwise Camel will

thrown an exception stating the endpoint uri is not valid.

streaming false Camel 2.5: If enabled then Camel will process replies out-of-order, eg in the order they come

back. If disabled, Camel will process replies in the same order as the Expression specied.

timeout

Camel 2.5: Sets a total timeout specied in millis. If the Recipient List hasn't been able to send

and process all replies within the given timeframe, then the timeout triggers and the Recipient List

breaks out and continues. Notice if you provide a TimeoutAwareAggregationStrategy then the

timeout method is invoked before breaking out.

onPrepareRef

Camel 2.8: Refers to a custom Processor to prepare the copy of the Exchange each recipient will

receive. This allows you to do any custom logic, such as deep-cloning the message payload if

that's needed etc.

shareUnitOfWork false Camel 2.8: Whether the unit of work should be shared. See the same option on Splitter for more

details.

Static Recipient List

The following example shows how to route a request from an input queue:a

endpoint to a static list of destinations

Using Annotations

You can use the RecipientList Annotation on a POJO to create a Dynamic

Recipient List. For more details see the Bean Integration.

Using the Fluent Builders

RouteBuilder builder = new RouteBuilder() {

public void configure() {

errorHandler(deadLetterChannel("mock:error"));

from("seda:a")

.multicast().to("seda:b","seda:c","seda:d");

}

};

Using the Spring XML Extensions

<camelContext errorHandlerRef="errorHandler" xmlns="http://camel.apache.org/schema/

spring">

<route>

</multicast>

</route>

</camelContext>

399 CHAPTER 10 - PATTERN APPENDIX

Dynamic Recipient List

Usually one of the main reasons for using the Recipient List pattern is that

the list of recipients is dynamic and calculated at runtime. The following

example demonstrates how to create a dynamic recipient list using an

Expression (which in this case it extracts a named header value dynamically)

to calculate the list of endpoints which are either of type Endpoint or are

converted to a String and then resolved using the endpoint URIs.

Using the Fluent Builders

RouteBuilder builder = new RouteBuilder() {

public void configure() {

errorHandler(deadLetterChannel("mock:error"));

from("seda:a")

.recipientList(header("foo"));

}

};

The above assumes that the header contains a list of endpoint URIs. The

following takes a single string header and tokenizes it

from("direct:a").recipientList(

header("recipientListHeader").tokenize(","));

Iteratable value

The dynamic list of recipients that are dened in the header must be

iteratable such as:

▪java.util.Collection

▪java.util.Iterator

▪ arrays

▪org.w3c.dom.NodeList

▪Camel 1.6.0: a single String with values separated with comma

▪ any other type will be regarded as a single value

Using the Spring XML Extensions

<camelContext errorHandlerRef="errorHandler" xmlns="http://camel.apache.org/schema/

spring">

<route>

</recipientList>

CHAPTER 10 - PATTERN APPENDIX 400

</route>

</camelContext>

For further examples of this pattern in use you could look at one of the junit

test case

Using delimiter in Spring XML

Available as of Camel 1.6.0

In Spring DSL you can set the delimiter attribute for setting a delimiter to

be used if the header value is a single String with multiple separated

endpoints. By default Camel uses comma as delimiter, but this option lets

you specify a customer delimiter to use instead.

<route>

<header>myHeader</header>

</recipientList>

</route>

So if myHeader contains a String with the value "activemq:queue:foo,

activemq:topic:hello , log:bar" then Camel will split the String using

the delimiter given in the XML that was comma, resulting into 3 endpoints to

send to. You can use spaces between the endpoints as Camel will trim the

value when it lookup the endpoint to send to.

Note: In Java DSL you use the tokenizer to archive the same. The route

above in Java DSL:

from("direct:a").recipientList(header("myHeader").tokenize(","));

In Camel 2.1 its a bit easier as you can pass in the delimiter as 2nd

parameter:

from("direct:a").recipientList(header("myHeader"), "#");

Sending to multiple recipients in parallel

Available as of Camel 2.2

The Recipient List now supports parallelProcessing that for example

Splitter also supports. You can use it to use a thread pool to have concurrent

tasks sending the Exchange to multiple recipients concurrently.

401 CHAPTER 10 - PATTERN APPENDIX

from("direct:a").recipientList(header("myHeader")).parallelProcessing();

And in Spring XML its an attribute on the recipient list tag.

<route>

<header>myHeader</header>

</recipientList>

</route>

Stop continuing in case one recipient failed

Available as of Camel 2.2

The Recipient List now supports stopOnException that for example

Splitter also supports. You can use it to stop sending to any further recipients

in case any recipient failed.

from("direct:a").recipientList(header("myHeader")).stopOnException();

And in Spring XML its an attribute on the recipient list tag.

<route>

<header>myHeader</header>

</recipientList>

</route>

Note: You can combine parallelProcessing and stopOnException and

have them both true.

Ignore invalid endpoints

Available as of Camel 2.3

The Recipient List now supports ignoreInvalidEndpoints which the

Routing Slip also supports. You can use it to skip endpoints which is invalid.

from("direct:a").recipientList(header("myHeader")).ignoreInvalidEndpoints();

And in Spring XML its an attribute on the recipient list tag.

CHAPTER 10 - PATTERN APPENDIX 402

<route>

<header>myHeader</header>

</recipientList>

</route>

Then lets say the myHeader contains the following two endpoints

direct:foo,xxx:bar. The rst endpoint is valid and works. However the 2nd

is invalid and will just be ignored. Camel logs at INFO level about, so you can

see why the endpoint was invalid.

Using custom AggregationStrategy

Available as of Camel 2.2

You can now use you own AggregationStrategy with the Recipient List.

However its not that often you need that. What its good for is that in case

you are using Request Reply messaging then the replies from the recipient

can be aggregated. By default Camel uses UseLatestAggregationStrategy

which just keeps that last received reply. What if you must remember all the

bodies that all the recipients send back, then you can use your own custom

aggregator that keeps those. Its the same principle as with the Aggregator

EIP so check it out for details.

from("direct:a")

.recipientList(header("myHeader")).aggregationStrategy(new

MyOwnAggregationStrategy())

.to("direct:b");

And in Spring XML its an attribute on the recipient list tag.

<route>

<header>myHeader</header>

</recipientList>

</route>

Using custom thread pool

Available as of Camel 2.2

403 CHAPTER 10 - PATTERN APPENDIX

A thread pool is only used for parallelProcessing. You supply your own

custom thread pool via the ExecutorServiceStrategy (see Camel's

Threading Model), the same way you would do it for the

aggregationStrategy. By default Camel uses a thread pool with 10 threads

(subject to change in a future version).

Using method call as recipient list

You can use a Bean to provide the recipients, for example:

from("activemq:queue:test").recipientList().method(MessageRouter.class, "routeTo");

And then MessageRouter:

public class MessageRouter {

public String routeTo() {

String queueName = "activemq:queue:test2";

return queueName;

}

When you use a Bean then do not also use the @RecipientList annotation

as this will in fact add yet another recipient list, so you end up having two.

Do not do like this.

public class MessageRouter {

@RecipientList

public String routeTo() {

String queueName = "activemq:queue:test2";

return queueName;

}

Well you should only do like that above (using @RecipientList) if you route

just route to a Bean which you then want to act as a recipient list.

So the original route can be changed to:

from("activemq:queue:test").bean(MessageRouter.class, "routeTo");

Which then would invoke the routeTo method and detect its annotated with

@RecipientList and then act accordingly as if it was a recipient list EIP.

CHAPTER 10 - PATTERN APPENDIX 404

Using timeout

Available as of Camel 2.5

If you use parallelProcessing then you can congure a total timeout

value in millis. Camel will then process the messages in parallel until the

timeout is hit. This allows you to continue processing if one message is slow.

For example you can set a timeout value of 20 sec.

For example in the unit test below you can see we multicast the message

to 3 destinations. We have a timeout of 2 seconds, which means only the last

two messages can be completed within the timeframe. This means we will

only aggregate the last two which yields a result aggregation which outputs

"BC".

from("direct:start")

.multicast(new AggregationStrategy() {

public Exchange aggregate(Exchange oldExchange, Exchange newExchange) {

if (oldExchange == null) {

return newExchange;

}

String body = oldExchange.getIn().getBody(String.class);

oldExchange.getIn().setBody(body +

newExchange.getIn().getBody(String.class));

return oldExchange;

}

})

.parallelProcessing().timeout(250).to("direct:a","direct:b","direct:c")

// use end to indicate end of multicast route

.end()

.to("mock:result");

from("direct:a").delay(1000).to("mock:A").setBody(constant("A"));

from("direct:b").to("mock:B").setBody(constant("B"));

from("direct:c").to("mock:C").setBody(constant("C"));

By default if a timeout occurs the AggregationStrategy is not invoked.

However you can implement a specialized version

public interface TimeoutAwareAggregationStrategy extends AggregationStrategy {

/**

* A timeout occurred

* @param oldExchange the oldest exchange (is <tt>null</tt> on first aggregation

as we only have the new exchange)

* @param index the index

* @param total the total

* @param timeout the timeout value in millis

405 CHAPTER 10 - PATTERN APPENDIX

Timeout in other EIPs

This timeout feature is also supported by Splitter and both

multicast and recipientList.

void timeout(Exchange oldExchange, int index, int total, long timeout);

This allows you to deal with the timeout in the AggregationStrategy if you

really need to.

Using onPrepare to execute custom logic when preparing messages

Available as of Camel 2.8

See details at Multicast

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Splitter

The Splitter from the EIP patterns allows you split a message into a number

of pieces and process them individually

As of Camel 2.0, you need to specify a Splitter as split(). In earlier

versions of Camel, you need to use splitter().

Options

Name Default

Value Description

CHAPTER 10 - PATTERN APPENDIX 406

Timeout is total

The timeout is total, which means that after X time, Camel will

aggregate the messages which has completed within the

timeframe. The remainders will be cancelled. Camel will also only

invoke the timeout method in the

TimeoutAwareAggregationStrategy once, for the rst index which

caused the timeout.

strategyRef

Refers to an AggregationStrategy to be used to assemble the replies from the sub-messages, into a

single outgoing message from the Splitter. See the section titled What does the splitter return below for

whats used by default.

parallelProcessing false If enables then processing the sub-messages occurs concurrently. Note the caller thread will still wait

until all sub-messages has been fully processed, before it continues.

executorServiceRef Refers to a custom Thread Pool to be used for parallel processing. Notice if you set this option, then

parallel processing is automatic implied, and you do not have to enable that option as well.

stopOnException false

Camel 2.2: Whether or not to stop continue processing immediately when an exception occurred. If

disable, then Camel continue splitting and process the sub-messages regardless if one of them failed.

You can deal with exceptions in the AggregationStrategy class where you have full control how to

handle that.

streaming false

If enabled then Camel will split in a streaming fashion, which means it will split the input message in

chunks. This reduces the memory overhead. For example if you split big messages its recommended to

enable streaming. If streaming is enabled then the sub-message replies will be aggregated out-of-order,

eg in the order they come back. If disabled, Camel will process sub-message replies in the same order

as they where splitted.

timeout

Camel 2.5: Sets a total timeout specied in millis. If the Recipient List hasn't been able to split and

process all replies within the given timeframe, then the timeout triggers and the Splitter breaks out and

continues. Notice if you provide a TimeoutAwareAggregationStrategy then the timeout method is

invoked before breaking out.

onPrepareRef

Camel 2.8: Refers to a custom Processor to prepare the sub-message of the Exchange, before its

processed. This allows you to do any custom logic, such as deep-cloning the message payload if that's

needed etc.

shareUnitOfWork false Camel 2.8: Whether the unit of work should be shared. See further below for more details.

Exchange properties

The following properties is set on each Exchange that are split:

header type description

CamelSplitIndex int

Camel 2.0: A split counter that increases

for each Exchange being split. The

counter starts from 0.

CamelSplitSize int

Camel 2.0: The total number of

Exchanges that was splitted. This header

is not applied for stream based splitting.

From Camel 2.9 onwards this header is

also set in stream based splitting, but

only on the completed Exchange.

CamelSplitComplete boolean Camel 2.4: Whether or not this

Exchange is the last.

407 CHAPTER 10 - PATTERN APPENDIX

Examples

The following example shows how to take a request from the queue:a

endpoint the split it into pieces using an Expression, then forward each piece

to queue:b

Using the Fluent Builders

RouteBuilder builder = new RouteBuilder() {

public void configure() {

errorHandler(deadLetterChannel("mock:error"));

from("seda:a")

.split(body(String.class).tokenize("\n"))

.to("seda:b");

}

};

The splitter can use any Expression language so you could use any of the

Languages Supported such as XPath, XQuery, SQL or one of the Scripting

Languages to perform the split. e.g.

from("activemq:my.queue").split(xpath("//foo/

bar")).convertBodyTo(String.class).to("file://some/directory")

Using the Spring XML Extensions

<camelContext errorHandlerRef="errorHandler" xmlns="http://camel.apache.org/schema/

spring">

<route>

<split>

<xpath>/invoice/lineItems</xpath>

</split>

</route>

</camelContext>

For further examples of this pattern in use you could look at one of the junit

test case

Using Tokenizer from Spring XML Extensions*

Avaiaible as of Camel 2.0

You can use the tokenizer expression in the Spring DSL to split bodies or

headers using a token. This is a common use-case, so we provided a special

tokenizer tag for this.

CHAPTER 10 - PATTERN APPENDIX 408

In the sample below we split the body using a @ as separator. You can of

course use comma or space or even a regex pattern, also set regex=true.

<route>

<split>

</split>

</route>

</camelContext>

Splitting the body in Spring XML is a bit harder as you need to use the Simple

language to dictate this

<split>

</split>

What does the splitter return?

Camel 2.2 or older:

The Splitter will by default return the last splitted message.

Camel 2.3 and newer

The Splitter will by default return the original input message.

For all versions

You can override this by suppling your own strategy as an

AggregationStrategy. There is a sample on this page (Split aggregate

request/reply sample). Notice its the same strategy as the Aggregator

supports. This Splitter can be viewed as having a build in light weight

Aggregator.

Parallel execution of distinct 'parts'

If you want to execute all parts in parallel you can use special notation of

split() with two arguments, where the second one is a boolean ag if

processing should be parallel. e.g.

XPathBuilder xPathBuilder = new XPathBuilder("//foo/bar");

from("activemq:my.queue").split(xPathBuilder, true).to("activemq:my.parts");

409 CHAPTER 10 - PATTERN APPENDIX

In Camel 2.0 the boolean option has been refactored into a builder method

parallelProcessing so its easier to understand what the route does when

we use a method instead of true|false.

XPathBuilder xPathBuilder = new XPathBuilder("//foo/bar");

from("activemq:my.queue").split(xPathBuilder).parallelProcessing().to("activemq:my.parts");

Stream based

You can split streams by enabling the streaming mode using the streaming

builder method.

from("direct:streaming").split(body().tokenize(",")).streaming().to("activemq:my.parts");

You can also supply your custom splitter to use with streaming like this:

import static org.apache.camel.builder.ExpressionBuilder.beanExpression;

from("direct:streaming")

.split(beanExpression(new MyCustomIteratorFactory(), "iterator"))

.streaming().to("activemq:my.parts")

Streaming big XML payloads using Tokenizer language

Available as of Camel 2.9

If you have a big XML payload, from a le source, and want to split it in

streaming mode, then you can use the Tokenizer language with start/end

tokens to do this with low memory footprint. For example you may have a

XML payload structured as follows

<order>

</order>

<order>

</order>

...

<order>

</order>

</orders>

CHAPTER 10 - PATTERN APPENDIX 410

Splitting big XML payloads

The XPath engine in Java and saxon will load the entire XML content

into memory. And thus they are not well suited for very big XML

payloads.

Instead you can use a custom Expression which will iterate the XML

payload in a streamed fashion. From Camel 2.9 onwards you can

use the Tokenizer language

which supports this when you supply the start and end tokens.

Now to split this big le using XPath would cause the entire content to be

loaded into memory. So instead we can use the Tokenizer language to do this

as follows:

from("file:inbox")

.split().tokenizeXML("order").streaming()

.to("activemq:queue:order");

In XML DSL the route would be as follows:

<route>

</split>

</route>

Notice the tokenizeXML method which will split the le using the tag name

of the child node, which mean it will grab the content between the <order>

and </order> tags (incl. the tokens). So for example a splitted message

would be as follows:

<order>

</order>

If you want to inherit namespaces from a root/parent tag, then you can do

this as well by providing the name of the root/parent tag:

<route>

411 CHAPTER 10 - PATTERN APPENDIX

</split>

</route>

And in Java DSL its as follows:

from("file:inbox")

.split().tokenizeXML("order","orders").streaming()

.to("activemq:queue:order");

Specifying a custom aggregation strategy

Available as of Camel 2.0

This is specied similar to the Aggregator.

Specifying a custom ThreadPoolExecutor

You can customize the underlying ThreadPoolExecutor used in the parallel

splitter. In the Java DSL try something like this:

XPathBuilder xPathBuilder = new XPathBuilder("//foo/bar");

ExecutorService pool = ...

from("activemq:my.queue")

.split(xPathBuilder).parallelProcessing().executorService(pool)

.to("activemq:my.parts");

Using a Pojo to do the splitting

As the Splitter can use any Expression to do the actual splitting we leverage

this fact and use a method expression to invoke a Bean to get the splitted

parts.

The Bean should return a value that is iterable such as:

java.util.Collection, java.util.Iterator or an array.

In the route we dene the Expression as a method call to invoke our Bean

that we have registered with the id mySplitterBean in the Registry.

from("direct:body")

// here we use a POJO bean mySplitterBean to do the split of the payload

.split().method("mySplitterBean","splitBody")

CHAPTER 10 - PATTERN APPENDIX 412

.to("mock:result");

from("direct:message")

// here we use a POJO bean mySplitterBean to do the split of the message

// with a certain header value

.split().method("mySplitterBean","splitMessage")

.to("mock:result");

And the logic for our Bean is as simple as. Notice we use Camel Bean Binding

to pass in the message body as a String object.

public class MySplitterBean {

/**

* The split body method returns something that is iteratable such as a

java.util.List.

* @param body the payload of the incoming message

* @return a list containing each part splitted

public List<String> splitBody(String body) {

// since this is based on an unit test you can of cause

// use different logic for splitting as Camel have out

// of the box support for splitting a String based on comma

// but this is for show and tell, since this is java code

// you have the full power how you like to split your messages

List<String> answer = new ArrayList<String>();

String[] parts = body.split(",");

for (String part : parts) {

answer.add(part);

}

return answer;

}

/**

* The split message method returns something that is iteratable such as a

java.util.List.

* @param header the header of the incoming message with the name user

* @param body the payload of the incoming message

* @return a list containing each part splitted

public List<Message> splitMessage(@Header(value = "user")String header, @Body

String body) {

// we can leverage the Parameter Binding Annotations

// http://camel.apache.org/parameter-binding-annotations.html

// to access the message header and body at same time,

// then create the message that we want, splitter will

// take care rest of them.

// *NOTE* this feature requires Camel version >= 1.6.1

List<Message> answer = new ArrayList<Message>();

String[] parts = header.split(",");

for (String part : parts) {

413 CHAPTER 10 - PATTERN APPENDIX

DefaultMessage message = new DefaultMessage();

message.setHeader("user", part);

message.setBody(body);

answer.add(message);

}

return answer;

}

Split aggregate request/reply sample

This sample shows how you can split an Exchange, process each splitted

message, aggregate and return a combined response to the original caller

using request/reply.

The route below illustrates this and how the split supports a

aggregationStrategy to hold the in progress processed messages:

// this routes starts from the direct:start endpoint

// the body is then splitted based on @ separator

// the splitter in Camel supports InOut as well and for that we need

// to be able to aggregate what response we need to send back, so we provide our

// own strategy with the class MyOrderStrategy.

from("direct:start")

.split(body().tokenize("@"), new MyOrderStrategy())

// each splitted message is then send to this bean where we can process it

.to("bean:MyOrderService?method=handleOrder")

// this is important to end the splitter route as we do not want to do more

routing

// on each splitted message

.end()

// after we have splitted and handled each message we want to send a single

combined

// response back to the original caller, so we let this bean build it for us

// this bean will receive the result of the aggregate strategy: MyOrderStrategy

.to("bean:MyOrderService?method=buildCombinedResponse")

And the OrderService bean is as follows:

public static class MyOrderService {

private static int counter;

/**

* We just handle the order by returning a id line for the order

public String handleOrder(String line) {

LOG.debug("HandleOrder: " + line);

return "(id=" + ++counter + ",item=" + line + ")";

CHAPTER 10 - PATTERN APPENDIX 414

}

/**

* We use the same bean for building the combined response to send

* back to the original caller

public String buildCombinedResponse(String line) {

LOG.debug("BuildCombinedResponse: " + line);

return "Response[" + line + "]";

}

And our custom aggregationStrategy that is responsible for holding the in

progress aggregated message that after the splitter is ended will be sent to

the buildCombinedResponse method for nal processing before the

combined response can be returned to the waiting caller.

/**

* This is our own order aggregation strategy where we can control

* how each splitted message should be combined. As we do not want to

* loos any message we copy from the new to the old to preserve the

* order lines as long we process them

public static class MyOrderStrategy implements AggregationStrategy {

public Exchange aggregate(Exchange oldExchange, Exchange newExchange) {

// put order together in old exchange by adding the order from new exchange

if (oldExchange == null) {

// the first time we aggregate we only have the new exchange,

// so we just return it

return newExchange;

}

String orders = oldExchange.getIn().getBody(String.class);

String newLine = newExchange.getIn().getBody(String.class);

LOG.debug("Aggregate old orders: " + orders);

LOG.debug("Aggregate new order: " + newLine);

// put orders together separating by semi colon

orders = orders + ";" + newLine;

// put combined order back on old to preserve it

oldExchange.getIn().setBody(orders);

// return old as this is the one that has all the orders gathered until now

return oldExchange;

}

415 CHAPTER 10 - PATTERN APPENDIX

So lets run the sample and see how it works.

We send an Exchange to the direct:start endpoint containing a IN body with

the String value: A@B@C. The ow is:

HandleOrder: A

HandleOrder: B

Aggregate old orders: (id=1,item=A)

Aggregate new order: (id=2,item=B)

HandleOrder: C

Aggregate old orders: (id=1,item=A);(id=2,item=B)

Aggregate new order: (id=3,item=C)

BuildCombinedResponse: (id=1,item=A);(id=2,item=B);(id=3,item=C)

Response to caller: Response[(id=1,item=A);(id=2,item=B);(id=3,item=C)]

Stop processing in case of exception

Available as of Camel 2.1

The Splitter will by default continue to process the entire Exchange even in

case of one of the splitted message will thrown an exception during routing.

For example if you have an Exchange with 1000 rows that you split and route

each sub message. During processing of these sub messages an exception is

thrown at the 17th. What Camel does by default is to process the remainder

983 messages. You have the chance to remedy or handle this in the

AggregationStrategy.

But sometimes you just want Camel to stop and let the exception be

propagated back, and let the Camel error handler handle it. You can do this in

Camel 2.1 by specifying that it should stop in case of an exception occurred.

This is done by the stopOnException option as shown below:

from("direct:start")

.split(body().tokenize(",")).stopOnException()

.process(new MyProcessor())

.to("mock:split");

And using XML DSL you specify it as follows:

<route>

</split>

</route>

CHAPTER 10 - PATTERN APPENDIX 416

Using onPrepare to execute custom logic when preparing messages

Available as of Camel 2.8

See details at Multicast

Sharing unit of work

Available as of Camel 2.8

The Splitter will by default not share unit of work between the parent

exchange and each splitted exchange. This means each sub exchange has its

own individual unit of work.

For example you may have an use case, where you want to split a big

message. And you want to regard that process as an atomic isolated

operation that either is a success or failure. In case of a failure you want that

big message to be moved into a dead letter queue. To support this use case,

you would have to share the unit of work on the Splitter.

Here is an example in Java DSL

errorHandler(deadLetterChannel("mock:dead").useOriginalMessage()

.maximumRedeliveries(3).redeliveryDelay(0));

from("direct:start")

.to("mock:a")

// share unit of work in the splitter, which tells Camel to propagate failures

from

// processing the splitted messages back to the result of the splitter, which

allows

// it to act as a combined unit of work

.split(body().tokenize(",")).shareUnitOfWork()

.to("mock:b")

.to("direct:line")

.end()

.to("mock:result");

from("direct:line")

.to("log:line")

.process(new MyProcessor())

.to("mock:line");

Now in this example what would happen is that in case there is a problem

processing each sub message, the error handler will kick in (yes error

handling still applies for the sub messages). But what doesn't happen is that

if a sub message fails all redelivery attempts (its exhausted), then its not

moved into that dead letter queue. The reason is that we have shared the

unit of work, so the sub message will report the error on the shared unit of

work. When the Splitter is done, it checks the state of the shared unit of work

and checks if any errors occurred. And if an error occurred it will set the

exception on the Exchange and mark it for rollback. The error handler will yet

417 CHAPTER 10 - PATTERN APPENDIX

again kick in, as the Exchange has been marked as rollback and it had an

exception as well. No redelivery attempts is performed (as it was marked for

rollback) and the Exchange will be moved into the dead letter queue.

Using this from XML DSL is just as easy as you just have to set the

shareUnitOfWork attribute to true:

<errorHandler id="dlc" type="DeadLetterChannel" deadLetterUri="mock:dead"

useOriginalMessage="true">

</errorHandler>

<route>

<!-- share unit of work in the splitter, which tells Camel to propagate failures

from

processing the splitted messages back to the result of the splitter, which

allows

it to act as a combined unit of work -->

</split>

</route>

<route>

</route>

</camelContext>

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

CHAPTER 10 - PATTERN APPENDIX 418

Implementation of shared unit of work in Camel 2.x

The Camel team had to introduce a SubUnitOfWork to keep API

compatible with the current UnitOfWork in Camel 2.x code base. So

in reality the unit of work is not shared as a single object instance.

Instead SubUnitOfWork is attached to their parent, and issues

callback to the parent about their status (commit or rollback). This

may be refactored in Camel 3.0 where larger API changes can be

done.

Aggregator

This applies for Camel version 2.3 or newer. If you use an older

version then use this Aggregator link instead.

The Aggregator from the EIP patterns allows you to combine a number of

messages together into a single message.

A correlation Expression is used to determine the messages which should

be aggregated together. If you want to aggregate all messages into a single

message, just use a constant expression. An AggregationStrategy is used to

combine all the message exchanges for a single correlation key into a single

message exchange.

Aggregator options

The aggregator supports the following options:

Option Default Description

correlationExpression

Mandatory Expression which evaluates the correlation key to use for aggregation. The

Exchange which has the same correlation key is aggregated together. If the correlation

key could not be evaluated an Exception is thrown. You can disable this by using the

ignoreBadCorrelationKeys option.

aggregationStrategy

Mandatory AggregationStrategy which is used to merge the incoming Exchange with

the existing already merged exchanges. At rst call the oldExchange parameter is null.

On subsequent invocations the oldExchange contains the merged exchanges and

newExchange is of course the new incoming Exchange.

strategyRef A reference to lookup the AggregationStrategy in the Registry.

completionSize

Number of messages aggregated before the aggregation is complete. This option can be

set as either a xed value or using an Expression which allows you to evaluate a size

dynamically - will use Integer as result. If both are set Camel will fallback to use the xed

value if the Expression result was null or 0.

419 CHAPTER 10 - PATTERN APPENDIX

completionTimeout

Time in millis that an aggregated exchange should be inactive before its complete. This

option can be set as either a xed value or using an Expression which allows you to

evaluate a timeout dynamically - will use Long as result. If both are set Camel will fallback

to use the xed value if the Expression result was null or 0. You cannot use this option

together with completionInterval, only one of the two can be used.

completionInterval

A repeating period in millis by which the aggregator will complete all current aggregated

exchanges. Camel has a background task which is triggered every period. You cannot use

this option together with completionTimeout, only one of them can be used.

completionPredicate A Predicate to indicate when an aggregated exchange is complete.

completionFromBatchConsumer false

This option is if the exchanges are coming from a Batch Consumer. Then when enabled

the Aggregator2 will use the batch size determined by the Batch Consumer in the

message header CamelBatchSize. See more details at Batch Consumer. This can be used

to aggregate all les consumed from a File endpoint in that given poll.

forceCompletionOnStop false Camel 2.9 Indicates to complete all current aggregated exchanges when the context is

stopped

eagerCheckCompletion false

Whether or not to eager check for completion when a new incoming Exchange has been

received. This option inuences the behavior of the completionPredicate option as the

Exchange being passed in changes accordingly. When false the Exchange passed in the

Predicate is the aggregated Exchange which means any information you may store on the

aggregated Exchange from the AggregationStrategy is available for the Predicate. When

true the Exchange passed in the Predicate is the incoming Exchange, which means you

can access data from the incoming Exchange.

groupExchanges false

If enabled then Camel will group all aggregated Exchanges into a single combined

org.apache.camel.impl.GroupedExchange holder class that holds all the aggregated

Exchanges. And as a result only one Exchange is being sent out from the aggregator. Can

be used to combine many incoming Exchanges into a single output Exchange without

coding a custom AggregationStrategy yourself.

ignoreInvalidCorrelationKeys false

Whether or not to ignore correlation keys which could not be evaluated to a value. By

default Camel will throw an Exception, but you can enable this option and ignore the

situation instead.

closeCorrelationKeyOnCompletion

Whether or not too late Exchanges should be accepted or not. You can enable this to

indicate that if a correlation key has already been completed, then any new exchanges

with the same correlation key be denied. Camel will then throw a

closedCorrelationKeyException exception. When using this option you pass in a

integer which is a number for a LRUCache which keeps that last X number of closed

correlation keys. You can pass in 0 or a negative value to indicate a unbounded cache. By

passing in a number you are ensured that cache won't grow too big if you use a log of

dierent correlation keys.

discardOnCompletionTimeout false

Camel 2.5: Whether or not exchanges which complete due to a timeout should be

discarded. If enabled then when a timeout occurs the aggregated message will not be

sent out but dropped (discarded).

aggregationRepository

Allows you to plugin you own implementation of

org.apache.camel.spi.AggregationRepository which keeps track of the current

inight aggregated exchanges. Camel uses by default a memory based implementation.

aggregationRepositoryRef Reference to lookup a aggregationRepository in the Registry.

parallelProcessing false

When aggregated are completed they are being send out of the aggregator. This option

indicates whether or not Camel should use a thread pool with multiple threads for

concurrency. If no custom thread pool has been specied then Camel creates a default

pool with 10 concurrent threads.

executorService

If using parallelProcessing you can specify a custom thread pool to be used. In fact

also if you are not using parallelProcessing this custom thread pool is used to send out

aggregated exchanges as well.

executorServiceRef Reference to lookup a executorService in the Registry

timeoutCheckerExecutorService

Camel 2.9: If using either of the completionTimeout,completionTimeoutExpression,

or completionInterval options a background thread is created to check for the

completion for every aggregator. Set this option to provide a custom thread pool to be

used rather than creating a new thread for every aggregator.

timeoutCheckerExecutorServiceRef Camel 2.9: Reference to lookup a timeoutCheckerExecutorService in the Registry

Exchange Properties

The following properties are set on each aggregated Exchange:

header type description

CamelAggregatedSize int The total number of Exchanges aggregated into this combined Exchange.

CamelAggregatedCompletedBy String Indicator how the aggregation was completed as a value of either: predicate,size,consumer,

timeout or interval.

CHAPTER 10 - PATTERN APPENDIX 420

About AggregationStrategy

The AggregationStrategy is used for aggregating the old (lookup by its

correlation id) and the new exchanges together into a single exchange.

Possible implementations include performing some kind of combining or

delta processing, such as adding line items together into an invoice or just

using the newest exchange and removing old exchanges such as for state

tracking or market data prices; where old values are of little use.

Notice the aggregation strategy is a mandatory option and must be

provided to the aggregator.

Here are a few example AggregationStrategy implementations that should

help you create your own custom strategy.

//simply combines Exchange String body values using '+' as a delimiter

class StringAggregationStrategy implements AggregationStrategy {

public Exchange aggregate(Exchange oldExchange, Exchange newExchange) {

if (oldExchange == null) {

return newExchange;

}

String oldBody = oldExchange.getIn().getBody(String.class);

String newBody = newExchange.getIn().getBody(String.class);

oldExchange.getIn().setBody(oldBody + "+" + newBody);

return oldExchange;

}

//simply combines Exchange body values into an ArrayList<Object>

class ArrayListAggregationStrategy implements AggregationStrategy {

public Exchange aggregate(Exchange oldExchange, Exchange newExchange) {

Object newBody = newExchange.getIn().getBody();

ArrayList<Object> list = null;

if (oldExchange == null) {

list = new ArrayList<Object>();

list.add(newBody);

newExchange.getIn().setBody(list);

return newExchange;

}else {

list = oldExchange.getIn().getBody(ArrayList.class);

list.add(newBody);

return oldExchange;

}

421 CHAPTER 10 - PATTERN APPENDIX

About completion

When aggregation Exchanges at some point you need to indicate that the

aggregated exchanges is complete, so they can be send out of the

aggregator. Camel allows you to indicate completion in various ways as

follows:

▪ completionTimeout - Is an inactivity timeout in which is triggered if

no new exchanges have been aggregated for that particular

correlation key within the period.

▪ completionInterval - Once every X period all the current aggregated

exchanges are completed.

▪ completionSize - Is a number indicating that after X aggregated

exchanges it's complete.

▪ completionPredicate - Runs a Predicate when a new exchange is

aggregated to determine if we are complete or not

▪ completionFromBatchConsumer - Special option for Batch Consumer

which allows you to complete when all the messages from the batch

has been aggregated.

▪ forceCompletionOnStop - Camel 2.9 Indicates to complete all

current aggregated exchanges when the context is stopped

Notice that all the completion ways are per correlation key. And you can

combine them in any way you like. It's basically the rst which triggers that

wins. So you can use a completion size together with a completion timeout.

Only completionTimeout and completionInterval cannot be used at the same

time.

Notice the completion is a mandatory option and must be provided to the

aggregator. If not provided Camel will thrown an Exception on startup.

Persistent AggregationRepository

The aggregator provides a pluggable repository which you can implement

your own org.apache.camel.spi.AggregationRepository.

If you need persistent repository then you can use either Camel HawtDB or

SQL Component components.

Examples

See some examples from the old Aggregator which is somewhat similar to

this new aggregator.

CHAPTER 10 - PATTERN APPENDIX 422

Setting options in Spring XML

Many of the options are congurable as attributes on the

<aggregate> tag when using Spring XML.

Using completionTimeout

In this example we want to aggregate all incoming messages and after 3

seconds of inactivity we want the aggregation to complete. This is done

using the completionTimeout option as shown:

from("direct:start")

// aggregate all exchanges correlated by the id header.

// Aggregate them using the BodyInAggregatingStrategy strategy which

// and after 3 seconds of inactivity them timeout and complete the aggregation

// and send it to mock:aggregated

.aggregate(header("id"), new BodyInAggregatingStrategy()).completionTimeout(3000)

.to("mock:aggregated");

And the same example using Spring XML:

<route>

<simple>header.id</simple>

</correlationExpression>

</aggregate>

</route>

</camelContext>

<bean id="aggregatorStrategy"

class="org.apache.camel.processor.BodyInAggregatingStrategy"/>

Using completionSize

In this example we want to aggregate all incoming messages and when we

have 3 messages aggregated (in the same correlation group) we want the

aggregation to complete. This is done using the completionSize option as

shown:

from("direct:start")

// aggregate all exchanges correlated by the id header.

423 CHAPTER 10 - PATTERN APPENDIX

// Aggregate them using the BodyInAggregatingStrategy strategy which

// and after 3 messages has been aggregated then complete the aggregation

// and send it to mock:aggregated

.aggregate(header("id"), new BodyInAggregatingStrategy()).completionSize(3)

.to("mock:aggregated");

And the same example using Spring XML:

<route>

<simple>header.id</simple>

</correlationExpression>

</aggregate>

</route>

</camelContext>

<bean id="aggregatorStrategy"

class="org.apache.camel.processor.BodyInAggregatingStrategy"/>

Using completionPredicate

In this example we want to aggregate all incoming messages and use a

Predicate to determine when we are complete. The Predicate can be

evaluated using either the aggregated exchange (default) or the incoming

exchange. We will so both situations as examples. We start with the default

situation as shown:

from("direct:start")

// aggregate all exchanges correlated by the id header.

// Aggregate them using the BodyInAggregatingStrategy strategy which

// and when the aggregated body contains A+B+C then complete the aggregation

// and send it to mock:aggregated

.aggregate(header("id"), new

BodyInAggregatingStrategy()).completionPredicate(body().contains("A+B+C"))

.to("mock:aggregated");

And the same example using Spring XML:

<route>

CHAPTER 10 - PATTERN APPENDIX 424

<simple>header.id</simple>

</correlationExpression>

<simple>${body} contains 'A+B+C'</simple>

</completionPredicate>

</aggregate>

</route>

</camelContext>

<bean id="aggregatorStrategy"

class="org.apache.camel.processor.BodyInAggregatingStrategy"/>

And the other situation where we use the eagerCheckCompletion option to

tell Camel to use the incoming Exchange. Notice how we can just test in the

completion predicate that the incoming message is the END message:

from("direct:start")

// aggregate all exchanges correlated by the id header.

// Aggregate them using the BodyInAggregatingStrategy strategy

// do eager checking which means the completion predicate will use the incoming

exchange

// which allows us to trigger completion when a certain exchange arrived which is

the

// END message

.aggregate(header("id"), new BodyInAggregatingStrategy())

.eagerCheckCompletion().completionPredicate(body().isEqualTo("END"))

.to("mock:aggregated");

And the same example using Spring XML:

<route>

<simple>header.id</simple>

</correlationExpression>

</completionPredicate>

</aggregate>

</route>

</camelContext>

<bean id="aggregatorStrategy"

class="org.apache.camel.processor.BodyInAggregatingStrategy"/>

425 CHAPTER 10 - PATTERN APPENDIX

Using dynamic completionTimeout

In this example we want to aggregate all incoming messages and after a

period of inactivity we want the aggregation to complete. The period should

be computed at runtime based on the timeout header in the incoming

messages. This is done using the completionTimeout option as shown:

from("direct:start")

// aggregate all exchanges correlated by the id header.

// Aggregate them using the BodyInAggregatingStrategy strategy which

// and the timeout header contains the timeout in millis of inactivity them

timeout and complete the aggregation

// and send it to mock:aggregated

.aggregate(header("id"), new

BodyInAggregatingStrategy()).completionTimeout(header("timeout"))

.to("mock:aggregated");

And the same example using Spring XML:

<route>

<simple>header.id</simple>

</correlationExpression>

<header>timeout</header>

</completionTimeout>

</aggregate>

</route>

</camelContext>

<bean id="aggregatorStrategy"

class="org.apache.camel.processor.BodyInAggregatingStrategy"/>

Note: You can also add a xed timeout value and Camel will fallback to use

this value if the dynamic value was null or 0.

Using dynamic completionSize

In this example we want to aggregate all incoming messages based on a

dynamic size per correlation key. The size is computed at runtime based on

the mySize header in the incoming messages. This is done using the

completionSize option as shown:

CHAPTER 10 - PATTERN APPENDIX 426

from("direct:start")

// aggregate all exchanges correlated by the id header.

// Aggregate them using the BodyInAggregatingStrategy strategy which

// and the header mySize determines the number of aggregated messages should

trigger the completion

// and send it to mock:aggregated

.aggregate(header("id"), new

BodyInAggregatingStrategy()).completionSize(header("mySize"))

.to("mock:aggregated");

And the same example using Spring XML:

<route>

<simple>header.id</simple>

</correlationExpression>

<header>mySize</header>

</completionSize>

</aggregate>

</route>

</camelContext>

<bean id="aggregatorStrategy"

class="org.apache.camel.processor.BodyInAggregatingStrategy"/>

Note: You can also add a xed size value and Camel will fallback to use this

value if the dynamic value was null or 0.

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Manually Force the Completion of All Aggregated

Exchanges Immediately

Available as of Camel 2.9

You can manually complete all current aggregated exchanges by sending in a

message containing the header

427 CHAPTER 10 - PATTERN APPENDIX

Exchange.AGGREGATION_COMPLETE_ALL_GROUPS set to true. The message

is considered a signal message only, the message headers/contents will not

be processed otherwise.

See also

▪ The Loan Broker Example which uses an aggregator

▪ Blog post by Torsten Mielke about using the aggregator correctly.

▪ The old Aggregator

▪ HawtDB or SQL Component for persistence support

▪ Aggregate Example for an example application

Resequencer

The Resequencer from the EIP patterns allows you to reorganise messages

based on some comparator. By default in Camel we use an Expression to

create the comparator; so that you can compare by a message header or the

body or a piece of a message etc.

Camel supports two resequencing algorithms:

•Batch resequencing collects messages into a batch, sorts the

messages and sends them to their output.

•Stream resequencing re-orders (continuous) message streams

based on the detection of gaps between messages.

By default the Resequencer does not support duplicate messages and will

only keep the last message, in case a message arrives with the same

message expression. However in the batch mode you can enable it to allow

duplicates.

Batch Resequencing

The following example shows how to use the batch-processing resequencer

so that messages are sorted in order of the body() expression. That is

messages are collected into a batch (either by a maximum number of

messages per batch or using a timeout) then they are sorted in order and

then sent out to their output.

Using the Fluent Builders

CHAPTER 10 - PATTERN APPENDIX 428

Change in Camel 2.7

The <batch-config> and <stream-config> tags in XML DSL in the

Resequencer EIP must now be congured in the top, and not in the

bottom. So if you use those, then move them up just below the

<resequence> EIP starts in the XML. If you are using Camel older

than 2.7, then those congs should be at the bottom.

from("direct:start")

.resequence().body()

.to("mock:result");

This is equvalent to

from("direct:start")

.resequence(body()).batch()

.to("mock:result");

The batch-processing resequencer can be further congured via the size()

and timeout() methods.

from("direct:start")

.resequence(body()).batch().size(300).timeout(4000L)

.to("mock:result")

This sets the batch size to 300 and the batch timeout to 4000 ms (by default,

the batch size is 100 and the timeout is 1000 ms). Alternatively, you can

provide a conguration object.

from("direct:start")

.resequence(body()).batch(new BatchResequencerConfig(300, 4000L))

.to("mock:result")

So the above example will reorder messages from endpoint direct:a in order

of their bodies, to the endpoint mock:result.

Typically you'd use a header rather than the body to order things; or maybe a

part of the body. So you could replace this expression with

resequencer(header("mySeqNo"))

for example to reorder messages using a custom sequence number in the

header mySeqNo.

429 CHAPTER 10 - PATTERN APPENDIX

You can of course use many dierent Expression languages such as XPath,

XQuery, SQL or various Scripting Languages.

Using the Spring XML Extensions

<route>

<!--

batch-config can be ommitted for default (batch) resequencer settings

-->

<batch-config batchSize="300" batchTimeout="4000" />

</resequence>

</route>

</camelContext>

Allow Duplicates

Available as of Camel 2.4

In the batch mode, you can now allow duplicates. In Java DSL there is a

allowDuplicates() method and in Spring XML there is an

allowDuplicates=true attribute on the <batch-config/> you can use to

enable it.

Reverse

Available as of Camel 2.4

In the batch mode, you can now reverse the expression ordering. By

default the order is based on 0..9,A..Z, which would let messages with low

numbers be ordered rst, and thus also also outgoing rst. In some cases

you want to reverse order, which is now possible.

In Java DSL there is a reverse() method and in Spring XML there is an

reverse=true attribute on the <batch-config/> you can use to enable it.

Resequence JMS messages based on JMSPriority

Available as of Camel 2.4

It's now much easier to use the Resequencer to resequence messages

from JMS queues based on JMSPriority. For that to work you need to use

the two new options allowDuplicates and reverse.

CHAPTER 10 - PATTERN APPENDIX 430

from("jms:queue:foo")

// sort by JMSPriority by allowing duplicates (message can have same JMSPriority)

// and use reverse ordering so 9 is first output (most important), and 0 is last

// use batch mode and fire every 3th second

.resequence(header("JMSPriority")).batch().timeout(3000).allowDuplicates().reverse()

.to("mock:result");

Notice this is only possible in the batch mode of the Resequencer.

Ignore invalid exchanges

Available as of Camel 2.9

The Resequencer EIP will from Camel 2.9 onwards throw a

CamelExchangeException if the incoming Exchange is not valid for the

resequencer - ie. the expression cannot be evaluated, such as a missing

header. You can use the option ignoreInvalidExchanges to ignore these

exceptions which means the Resequencer will then skip the invalid

Exchange.

from("direct:start")

.resequence(header("seqno")).batch().timeout(1000)

// ignore invalid exchanges (they are discarded)

.ignoreInvalidExchanges()

.to("mock:result");

This option is available for both batch and stream resequencer.

Stream Resequencing

The next example shows how to use the stream-processing resequencer.

Messages are re-ordered based on their sequence numbers given by a

seqnum header using gap detection and timeouts on the level of individual

messages.

Using the Fluent Builders

from("direct:start").resequence(header("seqnum")).stream().to("mock:result");

The stream-processing resequencer can be further congured via the

capacity() and timeout() methods.

431 CHAPTER 10 - PATTERN APPENDIX

from("direct:start")

.resequence(header("seqnum")).stream().capacity(5000).timeout(4000L)

.to("mock:result")

This sets the resequencer's capacity to 5000 and the timeout to 4000 ms (by

default, the capacity is 100 and the timeout is 1000 ms). Alternatively, you

can provide a conguration object.

from("direct:start")

.resequence(header("seqnum")).stream(new StreamResequencerConfig(5000, 4000L))

.to("mock:result")

The stream-processing resequencer algorithm is based on the detection of

gaps in a message stream rather than on a xed batch size. Gap detection in

combination with timeouts removes the constraint of having to know the

number of messages of a sequence (i.e. the batch size) in advance.

Messages must contain a unique sequence number for which a predecessor

and a successor is known. For example a message with the sequence

number 3 has a predecessor message with the sequence number 2 and a

successor message with the sequence number 4. The message sequence

2,3,5 has a gap because the sucessor of 3 is missing. The resequencer

therefore has to retain message 5 until message 4 arrives (or a timeout

occurs).

If the maximum time dierence between messages (with successor/

predecessor relationship with respect to the sequence number) in a message

stream is known, then the resequencer's timeout parameter should be set to

this value. In this case it is guaranteed that all messages of a stream are

delivered in correct order to the next processor. The lower the timeout value

is compared to the out-of-sequence time dierence the higher is the

probability for out-of-sequence messages delivered by this resequencer.

Large timeout values should be supported by suciently high capacity

values. The capacity parameter is used to prevent the resequencer from

running out of memory.

By default, the stream resequencer expects long sequence numbers but

other sequence numbers types can be supported as well by providing a

custom expression.

public class MyFileNameExpression implements Expression {

public String getFileName(Exchange exchange) {

return exchange.getIn().getBody(String.class);

}

public Object evaluate(Exchange exchange) {

CHAPTER 10 - PATTERN APPENDIX 432

// parser the file name with YYYYMMDD-DNNN pattern

String fileName = getFileName(exchange);

String[] files = fileName.split("-D");

Long answer = Long.parseLong(files[0]) * 1000 + Long.parseLong(files[1]);

return answer;

}

public <T> T evaluate(Exchange exchange, Class<T> type) {

Object result = evaluate(exchange);

return exchange.getContext().getTypeConverter().convertTo(type, result);

}

from("direct:start").resequence(new

MyFileNameExpression()).stream().timeout(100).to("mock:result");

or custom comparator via the comparator() method

ExpressionResultComparator<Exchange> comparator = new MyComparator();

from("direct:start")

.resequence(header("seqnum")).stream().comparator(comparator)

.to("mock:result");

or via a StreamResequencerConfig object.

ExpressionResultComparator<Exchange> comparator = new MyComparator();

StreamResequencerConfig config = new StreamResequencerConfig(100, 1000L, comparator);

from("direct:start")

.resequence(header("seqnum")).stream(config)

.to("mock:result");

Using the Spring XML Extensions

<route>

<simple>in.header.seqnum</simple>

<stream-config capacity="5000" timeout="4000"/>

</resequence>

</route>

</camelContext>

433 CHAPTER 10 - PATTERN APPENDIX

Further Examples

For further examples of this pattern in use you could look at the batch-

processing resequencer junit test case and the stream-processing

resequencer junit test case

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Composed Message Processor

The Composed Message Processor from the EIP patterns allows you to

process a composite message by splitting it up, routing the sub-messages to

appropriate destinations and the re-aggregating the responses back into a

single message.

Available in Camel 1.5.

Example

In this example we want to check that a multipart order can be lled. Each

part of the order requires a check at a dierent inventory.

// split up the order so individual OrderItems can be validated by the appropriate

bean

from("direct:start")

.split().body()

.choice()

.when().method("orderItemHelper","isWidget")

.to("bean:widgetInventory")

.otherwise()

.to("bean:gadgetInventory")

CHAPTER 10 - PATTERN APPENDIX 434

.end()

.to("seda:aggregate");

// collect and re-assemble the validated OrderItems into an order again

from("seda:aggregate")

.aggregate(new

MyOrderAggregationStrategy()).header("orderId").completionTimeout(1000L)

.to("mock:result");

Using the Spring XML Extensions

<route>

<split>

<when>

</when>

</otherwise>

</choice>

</split>

</route>

<route>

<simple>header.orderId</simple>

</correlationExpression>

</aggregate>

</route>

To do this we split up the order using a Splitter. The Splitter then sends

individual OrderItems to a Content Based Router which checks the item

type. Widget items get sent for checking in the widgetInventory bean and

gadgets get sent to the gadgetInventory bean. Once these OrderItems

have been validated by the appropriate bean, they are sent on to the

Aggregator which collects and re-assembles the validated OrderItems into

an order again.

When an order is sent it contains a header with the order id. We use this

fact when we aggregate, as we congure this .header("orderId") on the

aggregate DSL to instruct Camel to use the header with the key orderId as

correlation expression.

435 CHAPTER 10 - PATTERN APPENDIX

For full details, check the example source here:

camel-core/src/test/java/org/apache/camel/processor/

ComposedMessageProcessorTest.java

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Scatter-Gather

The Scatter-Gather from the EIP patterns allows you to route messages to a

number of dynamically specied recipients and re-aggregate the responses

back into a single message.

Available in Camel 1.5.

Dynamic Scatter-Gather Example

In this example we want to get the best quote for beer from several dierent

vendors. We use a dynamic Recipient List to get the request for a quote to all

vendors and an Aggregator to pick the best quote out of all the responses.

The routes for this are dened as:

<route>

<header>listOfVendors</header>

</recipientList>

</route>

<route>

CHAPTER 10 - PATTERN APPENDIX 436

<header>quoteRequestId</header>

</correlationExpression>

</aggregate>

</route>

</camelContext>

So in the rst route you see that the Recipient List is looking at the

listOfVendors header for the list of recipients. So, we need to send a

message like

Map<String,Object> headers = new HashMap<String,Object>();

headers.put("listOfVendors","bean:vendor1, bean:vendor2, bean:vendor3");

headers.put("quoteRequestId","quoteRequest-1");

template.sendBodyAndHeaders("direct:start","<quote_request item=\"beer\"/>",

headers);

This message will be distributed to the following Endpoints: bean:vendor1,

bean:vendor2, and bean:vendor3. These are all beans which look like

public class MyVendor {

private int beerPrice;

@Produce(uri = "seda:quoteAggregator")

private ProducerTemplate quoteAggregator;

public MyVendor(int beerPrice) {

this.beerPrice = beerPrice;

}

public void getQuote(@XPath("/quote_request/@item")String item, Exchange

exchange) throws Exception {

if ("beer".equals(item)) {

exchange.getIn().setBody(beerPrice);

quoteAggregator.send(exchange);

}else {

throw new Exception("No quote available for "+ item);

}

and are loaded up in Spring like

<bean id="aggregatorStrategy"

class="org.apache.camel.spring.processor.scattergather.LowestQuoteAggregationStrategy"/>

437 CHAPTER 10 - PATTERN APPENDIX

<constructor-arg>

</constructor-arg>

</bean>

<constructor-arg>

</constructor-arg>

</bean>

<constructor-arg>

</constructor-arg>

</bean>

Each bean is loaded with a dierent price for beer. When the message is sent

to each bean endpoint, it will arrive at the MyVendor.getQuote method. This

method does a simple check whether this quote request is for beer and then

sets the price of beer on the exchange for retrieval at a later step. The

message is forwarded on to the next step using POJO Producing (see the

@Produce annotation).

At the next step we want to take the beer quotes from all vendors and nd

out which one was the best (i.e. the lowest!). To do this we use an Aggregator

with a custom aggregation strategy. The Aggregator needs to be able to

compare only the messages from this particular quote; this is easily done by

specifying a correlationExpression equal to the value of the quoteRequestId

header. As shown above in the message sending snippet, we set this header

to quoteRequest-1. This correlation value should be unique or you may

include responses that are not part of this quote. To pick the lowest quote out

of the set, we use a custom aggregation strategy like

public class LowestQuoteAggregationStrategy implements AggregationStrategy {

public Exchange aggregate(Exchange oldExchange, Exchange newExchange) {

// the first time we only have the new exchange

if (oldExchange == null) {

return newExchange;

}

if (oldExchange.getIn().getBody(int.class) <

newExchange.getIn().getBody(int.class)) {

return oldExchange;

}else {

return newExchange;

}

CHAPTER 10 - PATTERN APPENDIX 438

Finally, we expect to get the lowest quote of $1 out of $1, $2, and $3.

result.expectedBodiesReceived(1); // expect the lowest quote

You can nd the full example source here:

camel-spring/src/test/java/org/apache/camel/spring/processor/

scattergather/

camel-spring/src/test/resources/org/apache/camel/spring/processor/

scattergather/scatter-gather.xml

Static Scatter-Gather Example

You can lock down which recipients are used in the Scatter-Gather by using a

static Recipient List. It looks something like this

from("direct:start").multicast().to("seda:vendor1","seda:vendor2","seda:vendor3");

from("seda:vendor1").to("bean:vendor1").to("seda:quoteAggregator");

from("seda:vendor2").to("bean:vendor2").to("seda:quoteAggregator");

from("seda:vendor3").to("bean:vendor3").to("seda:quoteAggregator");

from("seda:quoteAggregator")

.aggregate(header("quoteRequestId"), new

LowestQuoteAggregationStrategy()).to("mock:result")

A full example of the static Scatter-Gather conguration can be found in the

Loan Broker Example.

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Routing Slip

The Routing Slip from the EIP patterns allows you to route a message

consecutively through a series of processing steps where the sequence of

steps is not known at design time and can vary for each message.

439 CHAPTER 10 - PATTERN APPENDIX

Options

Name Default

Value Description

uriDelimiter , Delimiter used if the Expression returned multiple endpoints.

ignoreInvalidEndpoints false If an endpoint uri could not be resolved, should it be ignored. Otherwise Camel will thrown an

exception stating the endpoint uri is not valid.

Example

The following route will take any messages sent to the Apache ActiveMQ

queue SomeQueue and pass them into the Routing Slip pattern.

from("activemq:SomeQueue").routingSlip("headerName");

Messages will be checked for the existance of the "headerName" header. The

value of this header should be a comma-delimited list of endpoint URIs you

wish the message to be routed to. The Message will be routed in a pipeline

fashion (i.e. one after the other).

Note: In Camel 1.x the default header name routingSlipHeader has

been @deprecated and is removed in Camel 2.0. We feel that the DSL

needed to express, the header it uses to locate the destinations, directly in

the DSL to not confuse readers. So the header name must be provided.

From Camel 2.5 the Routing Slip will set a property

(Exchange.SLIP_ENDPOINT) on the Exchange which contains the current

endpoint as it advanced though the slip. This allows you to know how far we

have processed in the slip.

The Routing Slip will compute the slip beforehand which means, the slip

is only computed once. If you need to compute the slip on-the-y then use

the Dynamic Router pattern instead.

CHAPTER 10 - PATTERN APPENDIX 440

Conguration options

Here we set the header name and the URI delimiter to something dierent.

Using the Fluent Builders

from("direct:c").routingSlip(header("aRoutingSlipHeader"), "#");

Using the Spring XML Extensions

<camelContext id="buildRoutingSlip" xmlns="http://activemq.apache.org/camel/schema/

spring">

<route>

</route>

</camelContext>

Ignore invalid endpoints

Available as of Camel 2.3

The Routing Slip now supports ignoreInvalidEndpoints which the

Recipient List also supports. You can use it to skip endpoints which is invalid.

from("direct:a").routingSlip("myHeader").ignoreInvalidEndpoints();

And in Spring XML its an attribute on the recipient list tag.

<route>

</route>

Then lets say the myHeader contains the following two endpoints

direct:foo,xxx:bar. The rst endpoint is valid and works. However the 2nd

is invalid and will just be ignored. Camel logs at INFO level about, so you can

see why the endpoint was invalid.

Expression supporting

Available as of Camel 2.4

The Routing Slip now supports to take the expression parameter as the

Recipient List does. You can tell the camel the expression that you want to

use to get the routing slip.

441 CHAPTER 10 - PATTERN APPENDIX

from("direct:a").routingSlip(header("myHeader")).ignoreInvalidEndpoints();

And in Spring XML its an attribute on the recipient list tag.

<route>

<!--NOTE from Camel 2.4.0, you need to specify the expression element inside

of the routingSlip element -->

<header>myHeader</header>

</routingSlip>

</route>

Further Examples

For further examples of this pattern in use you could look at the routing slip

test cases.

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Throttler

The Throttler Pattern allows you to ensure that a specic endpoint does not

get overloaded, or that we don't exceed an agreed SLA with some external

service.

Options

Name Default

Value Description

maximumRequestsPerPeriod

Maximum number of requests per period to throttle. This option must be provided and a positive

number. Notice, in the XML DSL, from Camel 2.8 onwards this option is congured using an

Expression instead of an attribute.

timePeriodMillis 1000 The time period in millis, in which the throttler will allow at most maximumRequestsPerPeriod

number of messages.

asyncDelayed false Camel 2.4: If enabled then any messages which is delayed happens asynchronously using a

scheduled thread pool.

executorServiceRef Camel 2.4: Refers to a custom Thread Pool to be used if asyncDelay has been enabled.

callerRunsWhenRejected true Camel 2.4: Is used if asyncDelayed was enabled. This controls if the caller thread should

execute the task if the thread pool rejected the task.

CHAPTER 10 - PATTERN APPENDIX 442

Examples

Using the Fluent Builders

from("seda:a").throttle(3).timePeriodMillis(10000).to("log:result","mock:result");

So the above example will throttle messages all messages received on

seda:a before being sent to mock:result ensuring that a maximum of 3

messages are sent in any 10 second window. Note that typically you would

often use the default time period of a second. So to throttle requests at 100

requests per second between two endpoints it would look more like this...

from("seda:a").throttle(100).to("seda:b");

For further examples of this pattern in use you could look at the junit test

case

Using the Spring XML Extensions

Camel 2.7.x or older

<route>

</throttle>

</route>

Camel 2.8 onwards

In Camel 2.8 onwards you must set the maximum period as an Expression as

shown below where we use a Constant expression:

<route>

</throttle>

</route>

443 CHAPTER 10 - PATTERN APPENDIX

Dynamically changing maximum requests per period

Available os of Camel 2.8

Since we use an Expression you can adjust this value at runtime, for example

you can provide a header with the value. At runtime Camel evaluates the

expression and converts the result to a java.lang.Long type. In the example

below we use a header from the message to determine the maximum

requests per period. If the header is absent, then the Throttler uses the old

value. So that allows you to only provide a header if the value is to be

changed:

<route>

<header>throttleValue</header>

</throttle>

</route>

Asynchronous delaying

Available as of Camel 2.4

You can let the Throttler use non blocking asynchronous delaying, which

means Camel will use a scheduler to schedule a task to be executed in the

future. The task will then continue routing. This allows the caller thread to

not block and be able to service other messages etc.

from("seda:a").throttle(100).asyncDelayed().to("seda:b");

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

SAMPLING THROTTLER

Available as of Camel 2.1

A sampling throttler allows you to extract a sample of the exchanges from

the trac through a route.

CHAPTER 10 - PATTERN APPENDIX 444

It is congured with a sampling period during which only a single exchange is

allowed to pass through. All other exchanges will be stopped.

Will by default use a sample period of 1 seconds.

Options

Name Default Value Description

messageFrequency Samples the message every N'th message. You can only use either frequency or period.

samplePeriod 1 Samples the message every N'th period. You can only use either frequency or period.

units SECOND Time unit as an enum of java.util.concurrent.TimeUnit from the JDK.

Samples

You use this EIP with the sample DSL as show in these samples.

Using the Fluent Builders

These samples also show how you can use the dierent syntax to congure

the sampling period:

from("direct:sample")

.sample()

.to("mock:result");

from("direct:sample-configured")

.sample(1, TimeUnit.SECONDS)

.to("mock:result");

from("direct:sample-configured-via-dsl")

.sample().samplePeriod(1).timeUnits(TimeUnit.SECONDS)

.to("mock:result");

from("direct:sample-messageFrequency")

.sample(10)

.to("mock:result");

from("direct:sample-messageFrequency-via-dsl")

.sample().sampleMessageFrequency(5)

.to("mock:result");

Using the Spring XML Extensions

And the same example in Spring XML is:

<route>

</sample>

</route>

445 CHAPTER 10 - PATTERN APPENDIX

<route>

</sample>

</route>

<route>

</sample>

</route>

And since it uses a default of 1 second you can omit this conguration in

case you also want to use 1 second

<route>

</sample>

</route>

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

See Also

▪ Throttler

▪ Aggregator

Delayer

The Delayer Pattern allows you to delay the delivery of messages to some

destination.

Options

Name Default

Value Description

CHAPTER 10 - PATTERN APPENDIX 446

The Delayer in Camel 1.x works a bit dierently than Camel 2.0

onwards.

In Camel 1.x the expression is used to calculate an absolute time in millis.

So if you want to wait 3 sec from now and want to use the expression for

that you have to set the absolute time as currentTimeInMillis() +

3000.

In Camel 2.0 the expression is a value in millis to wait from the current

time, so the expression should just be 3000.

However in both Camel 1.x and 2.0 you can use a long value for a xed

value to indicate the delay in millis.

See the Spring DSL samples for Delayer in Camel 1.x vs. Camel 2.0.

Using Delayer in Java DSL

See this ticket: https://issues.apache.org/jira/browse/CAMEL-2654

asyncDelayed false Camel 2.4: If enabled then delayed messages happens asynchronously using a scheduled

thread pool.

executorServiceRef Camel 2.4: Refers to a custom Thread Pool to be used if asyncDelay has been enabled.

callerRunsWhenRejected true Camel 2.4: Is used if asyncDelayed was enabled. This controls if the caller thread should

execute the task if the thread pool rejected the task.

Using the Fluent Builders

from("seda:b").delay(1000).to("mock:result");

So the above example will delay all messages received on seda:b 1 second

before sending them to mock:result.

You can of course use many dierent Expression languages such as XPath,

XQuery, SQL or various Scripting Languages. You can just delay things a xed

amount of time from the point at which the delayer receives the message.

For example to delay things 2 seconds

delayer(2000)

The above assume that the delivery order is maintained and that the

messages are delivered in delay order. If you want to reorder the messages

based on delivery time, you can use the Resequencer with this pattern. For

example

447 CHAPTER 10 - PATTERN APPENDIX

from("activemq:someQueue").resequencer(header("MyDeliveryTime")).delay("MyRedeliveryTime").to("activemq:aDelayedQueue");

Camel 2.0 - Spring DSL

The sample below demonstrates the delay in Spring DSL:

<route>

<delay>

<header>MyDelay</header>

</delay>

</route>

<route>

<delay>

</delay>

</route>

</camelContext>

Camel 1.x - Spring DSL

The delayer is using slightly dierent names in Camel 1.x:

</expression>

</delayer>

The empty tag </expression> is needed to fulll the XSD validation as its an

optional element and we use JAXB annotations to generated the XSD in

Camel and some combinations is hard to auto generate with optional

elements.

For further examples of this pattern in use you could look at the junit test

case

Asynchronous delaying

Available as of Camel 2.4

CHAPTER 10 - PATTERN APPENDIX 448

You can let the Delayer use non blocking asynchronous delaying, which

means Camel will use a scheduler to schedule a task to be executed in the

future. The task will then continue routing. This allows the caller thread to

not block and be able to service other messages etc.

From Java DSL

You use the asyncDelayed() to enable the async behavior.

from("activemq:queue:foo").delay(1000).asyncDelayed().to("activemq:aDelayedQueue");

From Spring XML

You use the asyncDelayed="true" attribute to enable the async behavior.

<route>

</delay>

</route>

Creating a custom delay

You can use an expression to determine when to send a message using

something like this

from("activemq:foo").

delay().method("someBean","computeDelay").

to("activemq:bar");

then the bean would look like this...

public class SomeBean {

public long computeDelay() {

long delay = 0;

// use java code to compute a delay value in millis

return delay;

}

449 CHAPTER 10 - PATTERN APPENDIX

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

See Also

• Delay Interceptor

Load Balancer

The Load Balancer Pattern allows you to delegate to one of a number of

endpoints using a variety of dierent load balancing policies.

Build in load balancing policies

Camel has out of the box the following policies:

Policy Description

Round

Robin

The exchanges is selected in a round robin fashion. This is a

well known and classic policy. This spreads the load even.

Random A random endpoint is selected for each exchange

Sticky

Sticky load balancing using an Expression to calculate a

correlation key to perform the sticky load balancing; rather like

jsessionid in the web or JMSXGroupID in JMS.

Topic Topic which sends to all destinations (rather like JMS Topics)

Failover Camel 2.0: In case of failures the exchange is tried on the

next endpoint.

Weighted

Round-

Robin

Camel 2.5: The weighted load balancing policy allows you to

specify a processing load distribution ratio for each server with

respect to others.In addition to the weight, endpoint selection

is then further rened using round-robin distribution based

on weight.

Weighted

Random

Camel 2.5: The weighted load balancing policy allows you to

specify a processing load distribution ratio for each server with

respect to others.In addition to the weight, endpoint selection

is then further rened using random distribution based on

weight.

CHAPTER 10 - PATTERN APPENDIX 450

Custom

Camel 2.8: From Camel 2.8 onwards the preferred way of

using a custom Load Balancer is to use this policy, instead of

using the @deprecated ref attribute.

Round Robin

Camel 1.x behavior

The round robin load balancer can actually be used to failover with Camel

1.x. This is no longer possible in Camel 2.x as the underlying Error Handler

foundation has been signicantly overhauled in Camel 2.x. Frankly the round

robin load balancer in Camel 1.x was not thought to be used in a failover

scenario.

Camel 2.x behavior

The round robin load balancer is not meant to work with failover, for that you

should use the dedicated failover load balancer. The round robin load

balancer will only change to next endpoint per message.

The round robin load balancer is statefull as it keeps state which endpoint

to use next time.

Using the Fluent Builders

from("direct:start").loadBalance().

roundRobin().to("mock:x","mock:y","mock:z");

Using the Spring conguration

<route>

</loadBalance>

</route>

</camelContext>

So the above example will load balance requests from direct:start to one of

the available mock endpoint instances, in this case using a round robbin

policy.

For further examples of this pattern in use you could look at the junit test

case

451 CHAPTER 10 - PATTERN APPENDIX

Failover

Available as of Camel 2.0

The failover load balancer is capable of trying the next processor in case

an Exchange failed with an exception during processing.

You can congure the failover with a list of specic exception to only

failover. If you do not specify any exceptions it will failover over any

exceptions. It uses the same strategy for matching exceptions as the

Exception Clause does for the onException.

It has the following options:

Option Type Default Description

inheritErrorHandler boolean true

Camel 2.3: Whether or

not the Error Handler

congured on the route

should be used or not.

You can disable it if you

want the failover to

trigger immediately and

failover to the next

endpoint. On the other

hand if you have this

option enabled, then

Camel will rst let the

Error Handler try to

process the message.

The Error Handler may

have been congured to

redelivery and use

delays between

attempts. If you have

enabled a number of

redeliveries then Camel

will try to redeliver to

the same endpoint, and

only failover to the next

endpoint, when the Error

Handler is exhausted.

CHAPTER 10 - PATTERN APPENDIX 452

Enable stream caching if using streams

If you use streaming then you should enable Stream caching when

using the failover load balancer. This is needed so the stream can

be re-read when failing over.

maximumFailoverAttempts int -1

Camel 2.3: A value to

indicate after X failver

attempts we should

exhaust (give up). Use -1

to indicate newer give

up and always try to

failover. Use 0 to newer

failover. And use e.g. 3

to failover at most 3

times before giving up.

This option can be used

whether or not round

robin is enabled or not.

roundRobin boolean false

Camel 2.3: Whether or

not the failover load

balancer should operate

in round robin mode or

not. If not, then it will

always start from the

rst endpoint when a

new message is to be

processed. In other

words it restart from the

top for every message. If

round robin is enabled,

then it keeps state and

will continue with the

next endpoint in a round

robin fashion. When

using round robin it will

not stick to last known

good endpoint, it will

always pick the next

endpoint to use.

453 CHAPTER 10 - PATTERN APPENDIX

Camel 2.2 or older behavior

The current implement of failover load balancer is a simple logic which

always tries the rst endpoint, and in case of an exception being thrown it

tries the next in the list, and so forth. It has no state, and the next message

will thus always start with the rst endpoint.

Camel 2.3 onwards behavior

The failover load balancer now supports round robin mode, which allows

you to failover in a round robin fashion. See the roundRobin option.

Here is a sample to failover only if a IOException related exception was

thrown:

from("direct:start")

// here we will load balance if IOException was thrown

// any other kind of exception will result in the Exchange as failed

// to failover over any kind of exception we can just omit the exception

// in the failOver DSL

.loadBalance().failover(IOException.class)

.to("direct:x","direct:y","direct:z");

You can specify multiple exceptions to failover as the option is varargs, for

instance:

// enable redelivery so failover can react

errorHandler(defaultErrorHandler().maximumRedeliveries(5));

from("direct:foo").

loadBalance().failover(IOException.class, MyOtherException.class)

.to("direct:a","direct:b");

Using failover in Spring DSL

Failover can also be used from Spring DSL and you congure it as:

<exception>java.io.IOException</exception>

<exception>com.mycompany.MyOtherException</exception>

</failover>

</loadBalance>

</route>

CHAPTER 10 - PATTERN APPENDIX 454

Redelivery must be enabled

In Camel 2.2 or older the failover load balancer requires you have

enabled Camel Error Handler to use redelivery. In Camel 2.3

onwards this is not required as such, as you can mix and match.

See the inheritErrorHandler option.

Using failover in round robin mode

An example using Java DSL:

from("direct:start")

// Use failover load balancer in stateful round robin mode

// which mean it will failover immediately in case of an exception

// as it does NOT inherit error handler. It will also keep retrying as

// its configured to newer exhaust.

.loadBalance().failover(-1, false,true).

to("direct:bad","direct:bad2","direct:good","direct:good2");

And the same example using Spring XML:

<route>

<!-- failover using stateful round robin,

which will keep retrying forever those 4 endpoints until success.

You can set the maximumFailoverAttempt to break out after X attempts -->

</loadBalance>

</route>

Weighted Round-Robin and Random Load Balancing

Available as of Camel 2.5

In many enterprise environments where server nodes of unequal

processing power & performance characteristics are utilized to host services

and processing endpoints, it is frequently necessary to distribute processing

load based on their individual server capabilities so that some endpoints are

not unfairly burdened with requests. Obviously simple round-robin or random

load balancing do not alleviate problems of this nature. A Weighted Round-

455 CHAPTER 10 - PATTERN APPENDIX

Disabled inheritErrorHandler

You can congure inheritErrorHandler=false if you want to

failover to the next endpoint as fast as possible. By disabling the

Error Handler you ensure it does not intervene which allows the

failover load balancer to handle failover asap. By also enabling

roundRobin mode, then it will keep retrying until it success. You can

then congure the maximumFailoverAttempts option to a high

value to let it eventually exhaust (give up) and fail.

Robin and/or Weighted Random load balancer can be used to address this

problem.

The weighted load balancing policy allows you to specify a processing load

distribution ratio for each server with respect to others. You can specify this

as a positive processing weight for each server. A larger number indicates

that the server can handle a larger load. The weight is utilized to determine

the payload distribution ratio to dierent processing endpoints with respect

to others.

The parameters that can be used are

In Camel 2.5

Option Type Default Description

roundRobin boolean false

The default value for round-

robin is false. In the absence

of this setting or parameter

the load balancing algorithm

used is random.

distributionRatio List<Integer> none

The distributionRatio is a list

consisting on integer weights

passed in as a parameter.

The distributionRatio must

match the number of

endpoints and/or processors

specied in the load balancer

list. In Camel 2.5 if endpoints

do not match ratios, then a

best eort distribution is

attempted.

Available In Camel 2.6

Option Type Default Description

CHAPTER 10 - PATTERN APPENDIX 456

Disabled inheritErrorHandler

As of Camel 2.6, the Weighted Load balancer usage has been

further simplied, there is no need to send in distributionRatio as a

List<Integer>. It can be simply sent as a delimited String of integer

weights separated by a delimiter of choice.

roundRobin boolean false

The default value for

round-robin is false. In the

absence of this setting or

parameter the load

balancing algorithm used

is random.

distributionRatio String none

The distributionRatio is a

delimited String

consisting on integer

weights separated by

delimiters for example

"2,3,5". The

distributionRatio must

match the number of

endpoints and/or

processors specied in

the load balancer list.

distributionRatioDelimiter String ,

The

distributionRatioDelimiter

is the delimiter used to

specify the

distributionRatio. If this

attribute is not specied a

default delimiter "," is

expected as the delimiter

used for specifying the

distributionRatio.

Using Weighted round-robin & random load balancing

In Camel 2.5

An example using Java DSL:

457 CHAPTER 10 - PATTERN APPENDIX

ArrayList<integer> distributionRatio = new ArrayList<integer>();

distributionRatio.add(4);

distributionRatio.add(2);

distributionRatio.add(1);

// round-robin

from("direct:start")

.loadBalance().weighted(true, distributionRatio)

.to("mock:x","mock:y","mock:z");

//random

from("direct:start")

.loadBalance().weighted(false, distributionRatio)

.to("mock:x","mock:y","mock:z");

And the same example using Spring XML:

<route>

</loadBalance>

</route>

Available In Camel 2.6

An example using Java DSL:

// round-robin

from("direct:start")

.loadBalance().weighted(true,"4:2:1" distributionRatioDelimiter=":")

.to("mock:x","mock:y","mock:z");

//random

from("direct:start")

.loadBalance().weighted(false,"4,2,1")

.to("mock:x","mock:y","mock:z");

And the same example using Spring XML:

<route>

<weighted roundRobin="false" distributionRatio="4-2-1"

distributionRatioDelimiter="-" />

CHAPTER 10 - PATTERN APPENDIX 458

</loadBalance>

</route>

Custom Load Balancer

You can use a custom load balancer (eg your own implementation) also.

An example using Java DSL:

from("direct:start")

// using our custom load balancer

.loadBalance(new MyLoadBalancer())

.to("mock:x","mock:y","mock:z");

And the same example using XML DSL:

<bean id="myBalancer"

class="org.apache.camel.processor.CustomLoadBalanceTest$MyLoadBalancer"/>

<route>

</loadBalance>

</route>

</camelContext>

Notice in the XML DSL above we use <custom> which is only available in

Camel 2.8 onwards. In older releases you would have to do as follows

instead:

</loadBalance>

To implement a custom load balancer you can extend some support classes

such as LoadBalancerSupport and SimpleLoadBalancerSupport. The

459 CHAPTER 10 - PATTERN APPENDIX

former supports the asynchronous routing engine, and the latter does not.

Here is an example:

Listing 56. Custom load balancer implementation

public static class MyLoadBalancer extends LoadBalancerSupport {

public boolean process(Exchange exchange, AsyncCallback callback) {

String body = exchange.getIn().getBody(String.class);

try {

if ("x".equals(body)) {

getProcessors().get(0).process(exchange);

}else if ("y".equals(body)) {

getProcessors().get(1).process(exchange);

}else {

getProcessors().get(2).process(exchange);

}

}catch (Throwable e) {

exchange.setException(e);

}

callback.done(true);

return true;

}

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Multicast

The Multicast allows to route the same message to a number of endpoints

and process them in a dierent way. The main dierence between the

Multicast and Splitter is that Splitter will split the message into several pieces

but the Multicast will not modify the request message.

Options

Name Default

Value Description

strategyRef Refers to an AggregationStrategy to be used to assemble the replies from the multicasts, into a single

outgoing message from the Multicast. By default Camel will use the last reply as the outgoing message.

parallelProcessing false

If enables then sending messages to the multicasts occurs concurrently. Note the caller thread will still

wait until all messages has been fully processed, before it continues. Its only the sending and

processing the replies from the multicasts which happens concurrently.

CHAPTER 10 - PATTERN APPENDIX 460

executorServiceRef Refers to a custom Thread Pool to be used for parallel processing. Notice if you set this option, then

parallel processing is automatic implied, and you do not have to enable that option as well.

stopOnException false

Camel 2.2: Whether or not to stop continue processing immediately when an exception occurred. If

disable, then Camel will send the message to all multicasts regardless if one of them failed. You can

deal with exceptions in the AggregationStrategy class where you have full control how to handle that.

streaming false If enabled then Camel will process replies out-of-order, eg in the order they come back. If disabled,

Camel will process replies in the same order as multicasted.

timeout

Camel 2.5: Sets a total timeout specied in millis. If the Multicast hasn't been able to send and process

all replies within the given timeframe, then the timeout triggers and the Multicast breaks out and

continues. Notice if you provide a TimeoutAwareAggregationStrategy then the timeout method is

invoked before breaking out.

onPrepareRef

Camel 2.8: Refers to a custom Processor to prepare the copy of the Exchange each multicast will

receive. This allows you to do any custom logic, such as deep-cloning the message payload if that's

needed etc.

shareUnitOfWork false Camel 2.8: Whether the unit of work should be shared. See the same option on Splitter for more

details.

Example

The following example shows how to take a request from the direct:a

endpoint , then multicast these request to direct:x,direct:y,direct:z.

Using the Fluent Builders

from("direct:a").multicast().to("direct:x","direct:y","direct:z");

By default Multicast invokes each endpoint sequentially. If parallel processing

is desired, simply use

from("direct:a").multicast().parallelProcessing().to("direct:x","direct:y",

"direct:z");

In case of using InOut MEP, an AggregationStrategy is used for aggregating

all reply messages. The default is to only use the latest reply message and

discard any earlier replies. The aggregation strategy is congurable:

from("direct:start")

.multicast(new MyAggregationStrategy())

.parallelProcessing().timeout(500).to("direct:a","direct:b","direct:c")

.end()

.to("mock:result");

Stop processing in case of exception

Available as of Camel 2.1

The Multicast will by default continue to process the entire Exchange even

in case one of the multicasted messages will thrown an exception during

routing.

For example if you want to multicast to 3 destinations and the 2nd

461 CHAPTER 10 - PATTERN APPENDIX

destination fails by an exception. What Camel does by default is to process

the remainder destinations. You have the chance to remedy or handle this in

the AggregationStrategy.

But sometimes you just want Camel to stop and let the exception be

propagated back, and let the Camel error handler handle it. You can do this in

Camel 2.1 by specifying that it should stop in case of an exception occurred.

This is done by the stopOnException option as shown below:

from("direct:start")

.multicast()

.stopOnException().to("direct:foo","direct:bar","direct:baz")

.end()

.to("mock:result");

from("direct:foo").to("mock:foo");

from("direct:bar").process(new MyProcessor()).to("mock:bar");

from("direct:baz").to("mock:baz");

And using XML DSL you specify it as follows:

<route>

</multicast>

</route>

<route>

</route>

<route>

</route>

<route>

</route>

CHAPTER 10 - PATTERN APPENDIX 462

Using onPrepare to execute custom logic when preparing messages

Available as of Camel 2.8

The Multicast will copy the source Exchange and multicast each copy.

However the copy is a shallow copy, so in case you have mutateable

message bodies, then any changes will be visible by the other copied

messages. If you want to use a deep clone copy then you need to use a

custom onPrepare which allows you to do this using the Processor interface.

Notice the onPrepare can be used for any kind of custom logic which you

would like to execute before the Exchange is being multicasted.

For example if you have a mutable message body as this Animal class:

Listing 57. Animal

public class Animal implements Serializable {

private int id;

private String name;

public Animal() {

}

public Animal(int id, String name) {

this.id = id;

this.name = name;

}

public Animal deepClone() {

Animal clone = new Animal();

clone.setId(getId());

clone.setName(getName());

return clone;

}

public int getId() {

return id;

}

public void setId(int id) {

this.id = id;

}

public String getName() {

return name;

}

public void setName(String name) {

this.name = name;

}

@Override

public String toString() {

return id + " " + name;

463 CHAPTER 10 - PATTERN APPENDIX

Design for immutable

Its best practice to design for immutable objects.

}

Then we can create a deep clone processor which clones the message body:

Listing 58. AnimalDeepClonePrepare

public class AnimalDeepClonePrepare implements Processor {

public void process(Exchange exchange) throws Exception {

Animal body = exchange.getIn().getBody(Animal.class);

// do a deep clone of the body which wont affect when doing multicasting

Animal clone = body.deepClone();

exchange.getIn().setBody(clone);

}

Then we can use the AnimalDeepClonePrepare class in the Multicast route

using the onPrepare option as shown:

Listing 59. Multicast using onPrepare

from("direct:start")

.multicast().onPrepare(new

AnimalDeepClonePrepare()).to("direct:a").to("direct:b");

And the same example in XML DSL

Listing 60. Multicast using onPrepare

<route>

</multicast>

</route>

<route>

</route>

CHAPTER 10 - PATTERN APPENDIX 464

<route>

</route>

</camelContext>

<bean id="animalDeepClonePrepare"

class="org.apache.camel.processor.AnimalDeepClonePrepare"/>

<bean id="processorA"

class="org.apache.camel.processor.MulticastOnPrepareTest$ProcessorA"/>

<bean id="processorB"

class="org.apache.camel.processor.MulticastOnPrepareTest$ProcessorB"/>

Notice the onPrepare option is also available on other EIPs such as Splitter,

Recipient List, and Wire Tap.

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

LOOP

The Loop allows to process the a message a number of times and possibly

process them in a dierent way. Useful mostly for testing.

Options

Name Default

Value Description

copy false

Camel 2.8: Whether or not copy mode is used. If

false then the same Exchange is being used

throughout the looping. So the result from the previous

iteration will be visible for the next iteration. Instead

you can enable copy mode, and then each iteration is

restarting with a fresh copy of the input Exchange.

465 CHAPTER 10 - PATTERN APPENDIX

Default mode

Notice by default the loop uses the same exchange throughout the

looping. So the result from the previous iteration is used for the

next (eg Pipes and Filters). From Camel 2.8 onwards you can

enable copy mode instead. See the options table for more details.

Exchange properties

For each iteration two properties are set on the Exchange that could be used

by processors down the pipeline to process the Message in dierent ways.

Property Description

CamelIterationCount Camel 1.x: Total number of iterations to be run

CamelIterationIndex Camel 1.x: Index of the current iteration (0

based)

CamelLoopSize Camel 2.0: Total number of loops

CamelLoopIndex Camel 2.0: Index of the current iteration (0

based)

that could be used by processors down the pipeline to process the Message

in dierent ways.

Examples

The following example shows how to take a request from the direct:x

endpoint , then send the message repetitively to mock:result. The number

of times the message is sent is either passed as an argument to loop(), or

determined at runtime by evaluating an expression. The expression must

evaluate to an int, otherwise a RuntimeCamelException is thrown.

Using the Fluent Builders

Pass loop count as an argument

from("direct:a").loop(8).to("mock:result");

Use expression to determine loop count

from("direct:b").loop(header("loop")).to("mock:result");

Use expression to determine loop count

CHAPTER 10 - PATTERN APPENDIX 466

from("direct:c").loop().xpath("/hello/@times").to("mock:result");

Using the Spring XML Extensions

Pass loop count as an argument

<route>

<loop>

</loop>

</route>

Use expression to determine loop count

<route>

<loop>

</loop>

</route>

For further examples of this pattern in use you could look at one of the junit

test case

Using copy mode

Available as of Camel 2.8

Now suppose we send a message to "direct:start" endpoint containing the

letter A.

The output of processing this route will be that, each "mock:loop" endpoint

will receive "AB" as message.

from("direct:start")

// instruct loop to use copy mode, which mean it will use a copy of the input

exchange

// for each loop iteration, instead of keep using the same exchange all over

.loop(3).copy()

.transform(body().append("B"))

.to("mock:loop")

.end()

.to("mock:result");

However if we do not enable copy mode then "mock:loop" will receive "AB",

"ABB", "ABBB" messages.

467 CHAPTER 10 - PATTERN APPENDIX

from("direct:start")

// by default loop will keep using the same exchange so on the 2nd and 3rd

iteration its

// the same exchange that was previous used that are being looped all over

.loop(3)

.transform(body().append("B"))

.to("mock:loop")

.end()

.to("mock:result");

The equivalent example in XML DSL in copy mode is as follows:

<route>

</transform>

</loop>

</route>

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

MESSAGE TRANSFORMATION

Content Enricher

Camel supports the Content Enricher from the EIP patterns using a Message

Translator, an artibrary Processor in the routing logic or using the enrich DSL

element to enrich the message.

CHAPTER 10 - PATTERN APPENDIX 468

Content enrichment using a Message Translator or a

Processor

Using the Fluent Builders

You can use Templating to consume a message from one destination,

transform it with something like Velocity or XQuery and then send it on to

another destination. For example using InOnly (one way messaging)

from("activemq:My.Queue").

to("velocity:com/acme/MyResponse.vm").

to("activemq:Another.Queue");

If you want to use InOut (request-reply) semantics to process requests on the

My.Queue queue on ActiveMQ with a template generated response, then

sending responses back to the JMSReplyTo Destination you could use this.

from("activemq:My.Queue").

to("velocity:com/acme/MyResponse.vm");

Here is a simple example using the DSL directly to transform the message

body

from("direct:start").setBody(body().append(" World!")).to("mock:result");

In this example we add our own Processor using explicit Java code

from("direct:start").process(new Processor() {

public void process(Exchange exchange) {

Message in = exchange.getIn();

in.setBody(in.getBody(String.class) + " World!");

}

}).to("mock:result");

Finally we can use Bean Integration to use any Java method on any bean to

act as the transformer

469 CHAPTER 10 - PATTERN APPENDIX

from("activemq:My.Queue").

beanRef("myBeanName","myMethodName").

to("activemq:Another.Queue");

For further examples of this pattern in use you could look at one of the JUnit

tests

• TransformTest

• TransformViaDSLTest

Using Spring XML

<route>

</route>

Content enrichment using the enrich DSL element

Camel comes with two avors of content enricher in the DSL

▪enrich

▪pollEnrich

enrich is using a Producer to obtain the additional data. It is usually used

for Request Reply messaging, for instance to invoke an external web service.

pollEnrich on the other hand is using a Polling Consumer to obtain the

additional data. It is usually used for Event Message messaging, for instance

to read a le or download a FTP le.

This feature is available since Camel 2.0

Enrich Options

Name Default

Value Description

uri The endpoint uri for the external servie to enrich from. You must use either uri or ref.

ref Refers to the endpoint for the external servie to enrich from. You must use either uri or ref.

strategyRef Refers to an AggregationStrategy to be used to merge the reply from the external service, into a single outgoing

message. By default Camel will use the reply from the external service as outgoing message.

Using the Fluent Builders

AggregationStrategy aggregationStrategy = ...

from("direct:start")

.enrich("direct:resource", aggregationStrategy)

.to("direct:result");

CHAPTER 10 - PATTERN APPENDIX 470

from("direct:resource")

...

The content enricher (enrich) retrieves additional data from a resource

endpoint in order to enrich an incoming message (contained in the orginal

exchange). An aggregation strategy is used to combine the original exchange

and the resource exchange. The rst parameter of the

AggregationStrategy.aggregate(Exchange, Exchange) method

corresponds to the the original exchange, the second parameter the resource

exchange. The results from the resource endpoint are stored in the resource

exchange's out-message. Here's an example template for implementing an

aggregation strategy.

public class ExampleAggregationStrategy implements AggregationStrategy {

public Exchange aggregate(Exchange original, Exchange resource) {

Object originalBody = original.getIn().getBody();

Object resourceResponse = resource.getOut().getBody();

Object mergeResult = ... // combine original body and resource response

if (original.getPattern().isOutCapable()) {

original.getOut().setBody(mergeResult);

}else {

original.getIn().setBody(mergeResult);

}

return original;

}

Using this template the original exchange can be of any pattern. The

resource exchange created by the enricher is always an in-out exchange.

Using Spring XML

The same example in the Spring DSL

<route>

</route>

<route>

...

</route>

</camelContext>

471 CHAPTER 10 - PATTERN APPENDIX

Aggregation strategy is optional

The aggregation strategy is optional. If you do not provide it Camel will by

default just use the body obtained from the resource.

from("direct:start")

.enrich("direct:resource")

.to("direct:result");

In the route above the message send to the direct:result endpoint will

contain the output from the direct:resource as we do not use any custom

aggregation.

And in Spring DSL you just omit the strategyRef attribute:

<route>

</route>

Content enrich using pollEnrich

The pollEnrich works just as the enrich however as it uses a Polling

Consumer we have 3 methods when polling

▪ receive

▪ receiveNoWait

▪ receive(timeout)

PollEnrich Options

Name Default

Value Description

uri The endpoint uri for the external servie to enrich from. You must use either uri or ref.

ref Refers to the endpoint for the external servie to enrich from. You must use either uri or ref.

strategyRef Refers to an AggregationStrategy to be used to merge the reply from the external service, into a single outgoing

message. By default Camel will use the reply from the external service as outgoing message.

timeout 0 Timeout in millis to use when polling from the external service. See below for important details about the

timeout.

By default Camel will use the receiveNoWait.

If there is no data then the newExchange in the aggregation strategy is null.

You can pass in a timeout value that determines which method to use

▪ timeout is -1 or negative then receive is selected

▪ timeout is 0 then receiveNoWait is selected

▪ otherwise receive(timeout) is selected

The timeout values is in millis.

CHAPTER 10 - PATTERN APPENDIX 472

Data from current Exchange not used

pollEnrich does not access any data from the current Exchange

which means when polling it cannot use any of the existing headers

you may have set on the Exchange. For example you cannot set a

lename in the Exchange.FILE_NAME header and use pollEnrich

to consume only that le. For that you must set the lename in the

endpoint URI.

Example

In this example we enrich the message by loading the content from the le

named inbox/data.txt.

from("direct:start")

.pollEnrich("file:inbox?fileName=data.txt")

.to("direct:result");

And in XML DSL you do:

<route>

</route>

If there is no le then the message is empty. We can use a timeout to either

wait (potential forever) until a le exists, or use a timeout to wait a period.

For example to wait up til 5 seconds you can do:

<route>

</route>

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

473 CHAPTER 10 - PATTERN APPENDIX

Content Filter

Camel supports the Content Filter from the EIP patterns using one of the

following mechanisms in the routing logic to transform content from the

inbound message.

• Message Translator

• invoking a Java bean

• Processor object

A common way to lter messages is to use an Expression in the DSL like

XQuery, SQL or one of the supported Scripting Languages.

Using the Fluent Builders

Here is a simple example using the DSL directly

from("direct:start").setBody(body().append(" World!")).to("mock:result");

In this example we add our own Processor

from("direct:start").process(new Processor() {

public void process(Exchange exchange) {

Message in = exchange.getIn();

in.setBody(in.getBody(String.class) + " World!");

}

}).to("mock:result");

For further examples of this pattern in use you could look at one of the JUnit

tests

• TransformTest

• TransformViaDSLTest

Using Spring XML

<route>

</route>

You can also use XPath to lter out part of the message you are interested in:

<route>

CHAPTER 10 - PATTERN APPENDIX 474

</route>

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Claim Check

The Claim Check from the EIP patterns allows you to replace message

content with a claim check (a unique key), which can be used to retrieve the

message content at a later time. The message content is stored temporarily

in a persistent store like a database or le system. This pattern is very useful

when message content is very large (thus it would be expensive to send

around) and not all components require all information.

It can also be useful in situations where you cannot trust the information

with an outside party; in this case, you can use the Claim Check to hide the

sensitive portions of data.

Available in Camel 1.5.

Example

In this example we want to replace a message body with a claim check, and

restore the body at a later step.

Using the Fluent Builders

475 CHAPTER 10 - PATTERN APPENDIX

from("direct:start").to("bean:checkLuggage","mock:testCheckpoint",

"bean:dataEnricher","mock:result");

Using the Spring XML Extensions

<route>

</pipeline>

</route>

The example route is pretty simple - its just a Pipeline. In a real application

you would have some other steps where the mock:testCheckpoint endpoint

is in the example.

The message is rst sent to the checkLuggage bean which looks like

public static final class CheckLuggageBean {

public void checkLuggage(Exchange exchange, @Body String body, @XPath("/order/

@custId")String custId) {

// store the message body into the data store, using the custId as the claim

check

dataStore.put(custId, body);

// add the claim check as a header

exchange.getIn().setHeader("claimCheck", custId);

// remove the body from the message

exchange.getIn().setBody(null);

}

This bean stores the message body into the data store, using the custId as

the claim check. In this example, we're just using a HashMap to store the

message body; in a real application you would use a database or le system,

etc. Next the claim check is added as a message header for use later. Finally

we remove the body from the message and pass it down the pipeline.

The next step in the pipeline is the mock:testCheckpoint endpoint which

is just used to check that the message body is removed, claim check added,

etc.

To add the message body back into the message, we use the

dataEnricher bean which looks like

CHAPTER 10 - PATTERN APPENDIX 476

public static final class DataEnricherBean {

public void addDataBackIn(Exchange exchange, @Header("claimCheck")String

claimCheck) {

// query the data store using the claim check as the key and add the data

// back into the message body

exchange.getIn().setBody(dataStore.get(claimCheck));

// remove the message data from the data store

dataStore.remove(claimCheck);

// remove the claim check header

exchange.getIn().removeHeader("claimCheck");

}

This bean queries the data store using the claim check as the key and then

adds the data back into the message. The message body is then removed

from the data store and nally the claim check is removed. Now the message

is back to what we started with!

For full details, check the example source here:

camel-core/src/test/java/org/apache/camel/processor/ClaimCheckTest.java

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Normalizer

Camel supports the Normalizer from the EIP patterns by using a Message

Router in front of a number of Message Translator instances.

477 CHAPTER 10 - PATTERN APPENDIX

Example

This example shows a Message Normalizer that converts two types of XML

messages into a common format. Messages in this common format are then

ltered.

Using the Fluent Builders

// we need to normalize two types of incoming messages

from("direct:start")

.choice()

.when().xpath("/employee").to("bean:normalizer?method=employeeToPerson")

.when().xpath("/customer").to("bean:normalizer?method=customerToPerson")

.end()

.to("mock:result");

In this case we're using a Java bean as the normalizer. The class looks like

this

public class MyNormalizer {

public void employeeToPerson(Exchange exchange, @XPath("/employee/name/text()")

String name) {

exchange.getOut().setBody(createPerson(name));

}

public void customerToPerson(Exchange exchange, @XPath("/customer/@name")String

name) {

exchange.getOut().setBody(createPerson(name));

}

private String createPerson(String name) {

return "<person name=\"" + name + "\"/>";

}

Using the Spring XML Extensions

The same example in the Spring DSL

<route>

<when>

<xpath>/employee</xpath>

</when>

<when>

<xpath>/customer</xpath>

</when>

</choice>

CHAPTER 10 - PATTERN APPENDIX 478

</route>

</camelContext>

See Also

• Message Router

• Content Based Router

• Message Translator

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

SORT

Available as of Camel 2.0

Sort can be used to sort a message. Imagine you consume text les and

before processing each le you want to be sure the content is sorted.

Sort will by default sort the body using a default comparator that handles

numeric values or uses the string representation. You can provide your own

comparator, and even an expression to return the value to be sorted. Sort

requires the value returned from the expression evaluation is convertible to

java.util.List as this is required by the JDK sort operation.

Options

Name Default

Value Description

comparatorRef Refers to a custom java.util.Comparator to use for sorting the message body. Camel will by default use

a comparator which does a A..Z sorting.

Using from Java DSL

In the route below it will read the le content and tokenize by line breaks so

each line can be sorted.

479 CHAPTER 10 - PATTERN APPENDIX

from("file://inbox").sort(body().tokenize("\n")).to("bean:MyServiceBean.processLine");

You can pass in your own comparator as a 2nd argument:

from("file://inbox").sort(body().tokenize("\n"), new

MyReverseComparator()).to("bean:MyServiceBean.processLine");

Using from Spring DSL

In the route below it will read the le content and tokenize by line breaks so

each line can be sorted.

Listing 61. Camel 2.7 or better

<route>

<sort>

</sort>

</route>

Listing 62. Camel 2.6 or older

<route>

<sort>

</expression>

</sort>

</route>

And to use our own comparator we can refer to it as a spring bean:

Listing 63. Camel 2.7 or better

<route>

</sort>

</route>

Listing 64. Camel 2.6 or older

CHAPTER 10 - PATTERN APPENDIX 480

<route>

</expression>

</sort>

</route>

Besides <simple>, you can supply an expression using any language you

like, so long as it returns a list.

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

MESSAGING ENDPOINTS

Messaging Mapper

Camel supports the Messaging Mapper from the EIP patterns by using either

Message Translator pattern or the Type Converter module.

See also

• Message Translator

• Type Converter

• CXF for JAX-WS support for binding business logic to messaging &

web services

• Pojo

• Bean

481 CHAPTER 10 - PATTERN APPENDIX

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Event Driven Consumer

Camel supports the Event Driven Consumer from the EIP patterns. The

default consumer model is event based (i.e. asynchronous) as this means

that the Camel container can then manage pooling, threading and

concurrency for you in a declarative manner.

The Event Driven Consumer is implemented by consumers implementing

the Processor interface which is invoked by the Message Endpoint when a

Message is available for processing.

For more details see

• Message

• Message Endpoint

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Polling Consumer

Camel supports implementing the Polling Consumer from the EIP patterns

using the PollingConsumer interface which can be created via the

Endpoint.createPollingConsumer() method.

So in your Java code you can do

CHAPTER 10 - PATTERN APPENDIX 482

Endpoint endpoint = context.getEndpoint("activemq:my.queue");

PollingConsumer consumer = endpoint.createPollingConsumer();

Exchange exchange = consumer.receive();

Notice in Camel 2.0 we have introduced the ConsumerTemplate.

There are 3 main polling methods on PollingConsumer

Method name Description

receive() Waits until a message is available and then returns it;

potentially blocking forever

receive(long)

Attempts to receive a message exchange, waiting up to

the given timeout and returning null if no message

exchange could be received within the time available

receiveNoWait()

Attempts to receive a message exchange immediately

without waiting and returning null if a message

exchange is not available yet

ConsumerTemplate

Available as of Camel 2.0

The ConsumerTemplate is a template much like Spring's JmsTemplate or

JdbcTemplate supporting the Polling Consumer EIP. With the template you can

consume Exchanges from an Endpoint.

The template supports the 3 operations above, but also including

convenient methods for returning the body, etc consumeBody.

The example from above using ConsumerTemplate is:

Exchange exchange = consumerTemplate.receive("activemq:my.queue");

Or to extract and get the body you can do:

Object body = consumerTemplate.receiveBody("activemq:my.queue");

And you can provide the body type as a parameter and have it returned as

the type:

String body = consumerTemplate.receiveBody("activemq:my.queue",String.class);

You get hold of a ConsumerTemplate from the CamelContext with the

createConsumerTemplate operation:

483 CHAPTER 10 - PATTERN APPENDIX

ConsumerTemplate consumer = context.createConsumerTemplate();

Using ConsumerTemplate with Spring DSL

With the Spring DSL we can declare the consumer in the CamelContext with

the consumerTemplate tag, just like the ProducerTemplate. The example

below illustrates this:

<route>

</route>

</camelContext>

Then we can get leverage Spring to inject the ConsumerTemplate in our java

class. The code below is part of an unit test but it shows how the consumer

and producer can work together.

@ContextConfiguration

public class SpringConsumerTemplateTest extends AbstractJUnit38SpringContextTests {

@Autowired

private ProducerTemplate producer;

@Autowired

private ConsumerTemplate consumer;

@EndpointInject(ref = "result")

private MockEndpoint mock;

public void testConsumeTemplate() throws Exception {

// we expect Hello World received in our mock endpoint

mock.expectedBodiesReceived("Hello World");

// we use the producer template to send a message to the seda:start endpoint

producer.sendBody("seda:start","Hello World");

// we consume the body from seda:start

String body = consumer.receiveBody("seda:start",String.class);

assertEquals("Hello World", body);

// and then we send the body again to seda:foo so it will be routed to the

CHAPTER 10 - PATTERN APPENDIX 484

mock

// endpoint so our unit test can complete

producer.sendBody("seda:foo", body);

// assert mock received the body

mock.assertIsSatisfied();

}

Timer based polling consumer

In this sample we use a Timer to schedule a route to be started every 5th

second and invoke our bean MyCoolBean where we implement the business

logic for the Polling Consumer. Here we want to consume all messages from

a JMS queue, process the message and send them to the next queue.

First we setup our route as:

MyCoolBean cool = new MyCoolBean();

cool.setProducer(template);

cool.setConsumer(consumer);

from("timer://foo?period=5000").bean(cool, "someBusinessLogic");

from("activemq:queue.foo").to("mock:result");

And then we have out logic in our bean:

public static class MyCoolBean {

private int count;

private ConsumerTemplate consumer;

private ProducerTemplate producer;

public void setConsumer(ConsumerTemplate consumer) {

this.consumer = consumer;

}

public void setProducer(ProducerTemplate producer) {

this.producer = producer;

}

public void someBusinessLogic() {

// loop to empty queue

while (true) {

// receive the message from the queue, wait at most 3 sec

String msg = consumer.receiveBody("activemq:queue.inbox", 3000,

String.class);

485 CHAPTER 10 - PATTERN APPENDIX

if (msg == null) {

// no more messages in queue

break;

}

// do something with body

msg = "Hello " + msg;

// send it to the next queue

producer.sendBodyAndHeader("activemq:queue.foo", msg, "number", count++);

}

Scheduled Poll Components

Quite a few inbound Camel endpoints use a scheduled poll pattern to receive

messages and push them through the Camel processing routes. That is to

say externally from the client the endpoint appears to use an Event Driven

Consumer but internally a scheduled poll is used to monitor some kind of

state or resource and then re message exchanges.

Since this a such a common pattern, polling components can extend the

ScheduledPollConsumer base class which makes it simpler to implement this

pattern.

There is also the Quartz Component which provides scheduled delivery of

messages using the Quartz enterprise scheduler.

For more details see:

• PollingConsumer

• Scheduled Polling Components

◦ ScheduledPollConsumer

◦ Atom

◦ File

◦ FTP

◦ iBATIS

◦ JPA

◦ Mail

◦ Quartz

◦ SNMP

◦ AWS-SQS

ScheduledPollConsumer Options

The ScheduledPollConsumer supports the following options:

CHAPTER 10 - PATTERN APPENDIX 486

Option Default Description

pollStrategy ▪

Camel 2.0: A pluggable

org.apache.camel.PollingConsumerPollStrategy

allowing you to provide your custom

implementation to control error handling usually

occurred during the poll operation before an

Exchange have been created and being routed in

Camel. In other words the error occurred while the

polling was gathering information, for instance

access to a le network failed so Camel cannot

access it to scan for les. The default

implementation will log the caused exception at

WARN level and ignore it.

sendEmptyMessageWhenIdle false

Camel 2.9: If the polling consumer did not poll any

les, you can enable this option to send an empty

message (no body) instead.

About error handling and scheduled polling consumers

ScheduledPollConsumer is scheduled based and its run method is invoked

periodically based on schedule settings. But errors can also occur when a poll

being executed. For instance if Camel should poll a le network, and this

network resource is not available then a java.io.IOException could occur.

As this error happens before any Exchange has been created and prepared

for routing, then the regular Error handling in Camel does not apply. So what

does the consumer do then? Well the exception is propagated back to the

run method where its handled. Camel will by default log the exception at

WARN level and then ignore it. At next schedule the error could have been

resolved and thus being able to poll the endpoint successfully.

Controlling the error handling using

PollingConsumerPollStrategy

Available as of Camel 2.0

org.apache.camel.PollingConsumerPollStrategy is a pluggable strategy

that you can congure on the ScheduledPollConsumer. The default

implementation

org.apache.camel.impl.DefaultPollingConsumerPollStrategy will log

the caused exception at WARN level and then ignore this issue.

The strategy interface provides the following 3 methods

▪ begin

487 CHAPTER 10 - PATTERN APPENDIX

▪void begin(Consumer consumer, Endpoint endpoint)

▪ begin (Camel 2.3)

▪boolean begin(Consumer consumer, Endpoint endpoint)

▪ commit

▪void commit(Consumer consumer, Endpoint endpoint)

▪ commit (Camel 2.6)

▪void commit(Consumer consumer, Endpoint endpoint,

int polledMessages)

▪ rollback

▪boolean rollback(Consumer consumer, Endpoint

endpoint, int retryCounter, Exception e) throws

Exception

In Camel 2.3 onwards the begin method returns a boolean which indicates

whether or not to skipping polling. So you can implement your custom logic

and return false if you do not want to poll this time.

In Camel 2.6 onwards the commit method has an additional parameter

containing the number of message that was actually polled. For example if

there was no messages polled, the value would be zero, and you can react

accordingly.

The most interesting is the rollback as it allows you do handle the caused

exception and decide what to do.

For instance if we want to provide a retry feature to a scheduled consumer

we can implement the PollingConsumerPollStrategy method and put the

retry logic in the rollback method. Lets just retry up till 3 times:

public boolean rollback(Consumer consumer, Endpoint endpoint, int retryCounter,

Exception e) throws Exception {

if (retryCounter < 3) {

// return true to tell Camel that it should retry the poll immediately

return true;

}

// okay we give up do not retry anymore

return false;

}

Notice that we are given the Consumer as a parameter. We could use this to

restart the consumer as we can invoke stop and start:

// error occurred lets restart the consumer, that could maybe resolve the issue

consumer.stop();

consumer.start();

Notice: If you implement the begin operation make sure to avoid throwing

exceptions as in such a case the poll operation is not invoked and Camel will

invoke the rollback directly.

CHAPTER 10 - PATTERN APPENDIX 488

Conguring an Endpoint to use

PollingConsumerPollStrategy

To congure an Endpoint to use a custom PollingConsumerPollStrategy

you use the option pollStrategy. For example in the le consumer below we

want to use our custom strategy dened in the Registry with the bean id

myPoll:

from("file://inbox/?pollStrategy=#myPoll").to("activemq:queue:inbox")

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

See Also

▪ POJO Consuming

▪ Batch Consumer

Competing Consumers

Camel supports the Competing Consumers from the EIP patterns using a few

dierent components.

You can use the following components to implement competing

consumers:-

489 CHAPTER 10 - PATTERN APPENDIX

• SEDA for SEDA based concurrent processing using a thread pool

• JMS for distributed SEDA based concurrent processing with queues

which support reliable load balancing, failover and clustering.

Enabling Competing Consumers with JMS

To enable Competing Consumers you just need to set the

concurrentConsumers property on the JMS endpoint.

For example

from("jms:MyQueue?concurrentConsumers=5").bean(SomeBean.class);

or in Spring DSL

<route>

</route>

Or just run multiple JVMs of any ActiveMQ or JMS route

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Message Dispatcher

Camel supports the Message Dispatcher from the EIP patterns using various

approaches.

CHAPTER 10 - PATTERN APPENDIX 490

You can use a component like JMS with selectors to implement a Selective

Consumer as the Message Dispatcher implementation. Or you can use an

Endpoint as the Message Dispatcher itself and then use a Content Based

Router as the Message Dispatcher.

See Also

• JMS

• Selective Consumer

• Content Based Router

• Endpoint

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Selective Consumer

The Selective Consumer from the EIP patterns can be implemented in two

ways

491 CHAPTER 10 - PATTERN APPENDIX

The rst solution is to provide a Message Selector to the underlying URIs

when creating your consumer. For example when using JMS you can specify a

selector parameter so that the message broker will only deliver messages

matching your criteria.

The other approach is to use a Message Filter which is applied; then if the

lter matches the message your consumer is invoked as shown in the

following example

Using the Fluent Builders

RouteBuilder builder = new RouteBuilder() {

public void configure() {

errorHandler(deadLetterChannel("mock:error"));

from("seda:a")

.filter(header("foo").isEqualTo("bar"))

.process(myProcessor);

}

};

Using the Spring XML Extensions

<camelContext errorHandlerRef="errorHandler" xmlns="http://camel.apache.org/schema/

spring">

<route>

</filter>

</route>

</camelContext>

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Durable Subscriber

Camel supports the Durable Subscriber from the EIP patterns using the JMS

component which supports publish & subscribe using Topics with support for

non-durable and durable subscribers.

CHAPTER 10 - PATTERN APPENDIX 492

Another alternative is to combine the Message Dispatcher or Content

Based Router with File or JPA components for durable subscribers then

something like SEDA for non-durable.

Here is a simple example of creating durable subscribers to a JMS topic

Using the Fluent Builders

from("direct:start").to("activemq:topic:foo");

from("activemq:topic:foo?clientId=1&durableSubscriptionName=bar1").to("mock:result1");

from("activemq:topic:foo?clientId=2&durableSubscriptionName=bar2").to("mock:result2");

Using the Spring XML Extensions

<route>

</route>

<route>

</route>

<route>

</route>

Here is another example of JMS durable subscribers, but this time using

virtual topics (recommended by AMQ over durable subscriptions)

Using the Fluent Builders

from("direct:start").to("activemq:topic:VirtualTopic.foo");

from("activemq:queue:Consumer.1.VirtualTopic.foo").to("mock:result1");

493 CHAPTER 10 - PATTERN APPENDIX

from("activemq:queue:Consumer.2.VirtualTopic.foo").to("mock:result2");

Using the Spring XML Extensions

<route>

</route>

<route>

</route>

<route>

</route>

See Also

• JMS

• File

• JPA

• Message Dispatcher

• Selective Consumer

• Content Based Router

• Endpoint

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Idempotent Consumer

The Idempotent Consumer from the EIP patterns is used to lter out

duplicate messages.

This pattern is implemented using the IdempotentConsumer class. This

uses an Expression to calculate a unique message ID string for a given

message exchange; this ID can then be looked up in the

CHAPTER 10 - PATTERN APPENDIX 494

IdempotentRepository to see if it has been seen before; if it has the message

is consumed; if its not then the message is processed and the ID is added to

the repository.

The Idempotent Consumer essentially acts like a Message Filter to lter

out duplicates.

Camel will add the message id eagerly to the repository to detect

duplication also for Exchanges currently in progress.

On completion Camel will remove the message id from the repository if the

Exchange failed, otherwise it stays there.

Camel provides the following Idempotent Consumer implementations:

▪ MemoryIdempotentRepository

▪ FileIdempotentRepository

▪ HazelcastIdempotentRepository (Available as of Camel 2.8)

▪ JdbcMessageIdRepository (Available as of Camel 2.7)

▪ JpaMessageIdRepository

Options

The Idempotent Consumer has the following options:

Option Default Description

eager true

Camel 2.0: Eager controls whether

Camel adds the message to the

repository before or after the

exchange has been processed. If

enabled before then Camel will be

able to detect duplicate messages

even when messages are currently in

progress. By disabling Camel will only

detect duplicates when a message

has successfully been processed.

messageIdRepositoryRef null

A reference to a

IdempotentRepository to lookup in

the registry. This option is mandatory

when using XML DSL.

495 CHAPTER 10 - PATTERN APPENDIX

skipDuplicate true

Camel 2.8: Sets whether to skip

duplicate messages. If set to false

then the message will be continued.

However the Exchange has been

marked as a duplicate by having the

Exchange.DUPLICATE_MESSAG

exchange property set to a

Boolean.TRUE value.

removeOnFailure true Camel 2.9: Sets whether to remove

the id of an Exchange that failed.

Using the Fluent Builders

The following example will use the header myMessageId to lter out

duplicates

RouteBuilder builder = new RouteBuilder() {

public void configure() {

errorHandler(deadLetterChannel("mock:error"));

from("seda:a")

.idempotentConsumer(header("myMessageId"),

MemoryIdempotentRepository.memoryIdempotentRepository(200))

.to("seda:b");

}

};

The above example will use an in-memory based MessageIdRepository which

can easily run out of memory and doesn't work in a clustered environment.

So you might prefer to use the JPA based implementation which uses a

database to store the message IDs which have been processed

from("direct:start").idempotentConsumer(

header("messageId"),

jpaMessageIdRepository(lookup(JpaTemplate.class), PROCESSOR_NAME)

).to("mock:result");

In the above example we are using the header messageId to lter out

duplicates and using the collection myProcessorName to indicate the

Message ID Repository to use. This name is important as you could process

the same message by many dierent processors; so each may require its

own logical Message ID Repository.

For further examples of this pattern in use you could look at the junit test

case

CHAPTER 10 - PATTERN APPENDIX 496

Spring XML example

The following example will use the header myMessageId to lter out

duplicates

<bean id="myRepo"

class="org.apache.camel.processor.idempotent.MemoryIdempotentRepository"/>

<route>

<!-- use the messageId header as key for identifying duplicate messages

-->

<header>messageId</header>

</idempotentConsumer>

</route>

</camelContext>

How to handle duplicate messages in the route

Available as of Camel 2.8

You can now set the skipDuplicate option to false which instructs the

idempotent consumer to route duplicate messages as well. However the

duplicate message has been marked as duplicate by having a property on

the Exchange set to true. We can leverage this fact by using a Content Based

Router or Message Filter to detect this and handle duplicate messages.

For example in the following example we use the Message Filter to send

the message to a duplicate endpoint, and then stop continue routing that

message.

Listing 65. Filter duplicate messages

from("direct:start")

// instruct idempotent consumer to not skip duplicates as we will filter then our

self

.idempotentConsumer(header("messageId")).messageIdRepository(repo).skipDuplicate(false)

.filter(property(Exchange.DUPLICATE_MESSAGE).isEqualTo(true))

// filter out duplicate messages by sending them to someplace else and then

stop

.to("mock:duplicate")

.stop()

.end()

// and here we process only new messages (no duplicates)

.to("mock:result");

497 CHAPTER 10 - PATTERN APPENDIX

The sample example in XML DSL would be:

Listing 66. Filter duplicate messages

<bean id="myRepo"

class="org.apache.camel.processor.idempotent.MemoryIdempotentRepository"/>

<route>

<!-- use the messageId header as key for identifying duplicate messages

-->

<header>messageId</header>

<!-- the filter will only react on duplicate messages, if this

property is set on the Exchange -->

<property>CamelDuplicateMessage</property>

<!-- and send the message to this mock, due its part of an unit test

-->

<stop/>

</filter>

</idempotentConsumer>

</route>

</camelContext>

How to handle duplicate message in a clustered environment with a

data grid

Available as of Camel 2.8

If you have running Camel in a clustered environment, a in memory

idempotent repository doesn't work (see above). You can setup either a

central database or use the idempotent consumer implementation based on

the Hazelcast data grid. Hazelcast nds the nodes over multicast (which is

default - congure Hazelcast for tcp-ip) and creates automatically a map

based repository:

HazelcastIdempotentRepository idempotentRepo = new

HazelcastIdempotentRepository("myrepo");

from("direct:in").idempotentConsumer(header("messageId"),

idempotentRepo).to("mock:out");

CHAPTER 10 - PATTERN APPENDIX 498

You have to dene how long the repository should hold each message id

(default is to delete it never). To avoid that you run out of memory you

should create an eviction strategy based on the Hazelcast conguration. For

additional information see camel-hazelcast.

See this little tutorial, how setup such an idempotent repository on two

cluster nodes using Apache Karaf.

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Transactional Client

Camel recommends supporting the Transactional Client from the EIP patterns

using spring transactions.

Transaction Oriented Endpoints (Camel Toes) like JMS support using a

transaction for both inbound and outbound message exchanges. Endpoints

that support transactions will participate in the current transaction context

that they are called from.

You should use the SpringRouteBuilder to setup the routes since you will

need to setup the spring context with the TransactionTemplates that will

dene the transaction manager conguration and policies.

For inbound endpoint to be transacted, they normally need to be

congured to use a Spring PlatformTransactionManager. In the case of the

JMS component, this can be done by looking it up in the spring context.

You rst dene needed object in the spring conguration.

<bean id="jmsTransactionManager"

class="org.springframework.jms.connection.JmsTransactionManager">

</bean>

<bean id="jmsConnectionFactory"

class="org.apache.activemq.ActiveMQConnectionFactory">

499 CHAPTER 10 - PATTERN APPENDIX

Convention over conguration

In Camel 2.0 onwards we have improved the default conguration

reducing the number of Spring XML gobble you need to congure.

In this wiki page we provide the Camel 1.x examples and the same

2.0 example that requires less XML setup.

Conguration of Redelivery

The redelivery in transacted mode is not handled by Camel but by

the backing system (the transaction manager). In such cases you

should resort to the backing system how to congure the redelivery.

</bean>

Then you look them up and use them to create the JmsComponent.

PlatformTransactionManager transactionManager = (PlatformTransactionManager)

spring.getBean("jmsTransactionManager");

ConnectionFactory connectionFactory = (ConnectionFactory)

spring.getBean("jmsConnectionFactory");

JmsComponent component = JmsComponent.jmsComponentTransacted(connectionFactory,

transactionManager);

component.getConfiguration().setConcurrentConsumers(1);

ctx.addComponent("activemq", component);

Transaction Policies

Outbound endpoints will automatically enlist in the current transaction

context. But what if you do not want your outbound endpoint to enlist in the

same transaction as your inbound endpoint? The solution is to add a

Transaction Policy to the processing route. You rst have to dene transaction

policies that you will be using. The policies use a spring TransactionTemplate

under the covers for declaring the transaction demarcation to use. So you

will need to add something like the following to your spring xml:

<bean id="PROPAGATION_REQUIRED"

class="org.apache.camel.spring.spi.SpringTransactionPolicy">

CHAPTER 10 - PATTERN APPENDIX 500

</bean>

<bean id="PROPAGATION_REQUIRES_NEW"

class="org.apache.camel.spring.spi.SpringTransactionPolicy">

</bean>

Then in your SpringRouteBuilder, you just need to create new

SpringTransactionPolicy objects for each of the templates.

public void configure() {

...

Policy requried = bean(SpringTransactionPolicy.class, "PROPAGATION_REQUIRED"));

Policy requirenew = bean(SpringTransactionPolicy.class,

"PROPAGATION_REQUIRES_NEW"));

...

}

Once created, you can use the Policy objects in your processing routes:

// Send to bar in a new transaction

from("activemq:queue:foo").policy(requirenew).to("activemq:queue:bar");

// Send to bar without a transaction.

from("activemq:queue:foo").policy(notsupported ).to("activemq:queue:bar");

OSGi Blueprint

If you are using OSGi Blueprint then you most likely have to explicit declare a

policy and refer to the policy from the transacted in the route.

</bean>

And then refer to "required" from the route:

<route>

</route>

501 CHAPTER 10 - PATTERN APPENDIX

Camel 1.x - Database Sample

In this sample we want to ensure that two endpoints is under transaction

control. These two endpoints inserts data into a database.

The sample is in its full as a unit test.

First of all we setup the usual spring stu in its conguration le. Here we

have dened a DataSource to the HSQLDB and a most importantly

the Spring DataSoruce TransactionManager that is doing the heavy lifting of

ensuring our transactional policies. You are of course free to use any

of the Spring based TransactionMananger, eg. if you are in a full blown J2EE

container you could use JTA or the WebLogic or WebSphere specic

managers.

We use the required transaction policy that we dene as the

PROPOGATION_REQUIRED spring bean. And as last we have our book service

bean that does the business logic

and inserts data in the database as our core business logic.

<bean id="dataSource"

class="org.springframework.jdbc.datasource.DriverManagerDataSource">

</bean>

<bean id="txManager"

class="org.springframework.jdbc.datasource.DataSourceTransactionManager">

</bean>

<bean id="PROPAGATION_REQUIRED"

class="org.apache.camel.spring.spi.SpringTransactionPolicy">

</bean>

</bean>

In our Camel route that is Java DSL based we setup the transactional policy,

wrapped as a Policy.

// Notice that we use the SpringRouteBuilder that has a few more features than

// the standard RouteBuilder

CHAPTER 10 - PATTERN APPENDIX 502

return new SpringRouteBuilder() {

public void configure() throws Exception {

// lookup the transaction policy

SpringTransactionPolicy required = lookup("PROPAGATION_REQUIRED",

SpringTransactionPolicy.class);

// use this error handler instead of DeadLetterChannel that is the default

// Notice: transactionErrorHandler is in SpringRouteBuilder

if (isUseTransactionErrorHandler()) {

// useTransactionErrorHandler is only used for unit testing to reuse code

// for doing a 2nd test without this transaction error handler, so ignore

// this. For spring based transaction, end users are encouraged to use the

// transaction error handler instead of the default DeadLetterChannel.

errorHandler(transactionErrorHandler(required));

}

Then we are ready to dene our Camel routes. We have two routes: 1 for

success conditions, and 1 for a forced rollback condition.

This is after all based on a unit test.

// set the required policy for this route

from("direct:okay").policy(required).

setBody(constant("Tiger in Action")).beanRef("bookService").

setBody(constant("Elephant in Action")).beanRef("bookService");

// set the required policy for this route

from("direct:fail").policy(required).

setBody(constant("Tiger in Action")).beanRef("bookService").

setBody(constant("Donkey in Action")).beanRef("bookService");

As its a unit test we need to setup the database and this is easily done with

Spring JdbcTemplate

Error formatting macro: snippet: java.lang.IndexOutOfBoundsException:

Index: 20, Size: 20

And our core business service, the book service, will accept any books except

the Donkeys.

public class BookService {

private SimpleJdbcTemplate jdbc;

public BookService() {

}

public void setDataSource(DataSource ds) {

jdbc = new SimpleJdbcTemplate(ds);

}

public void orderBook(String title) throws Exception {

503 CHAPTER 10 - PATTERN APPENDIX

if (title.startsWith("Donkey")) {

throw new IllegalArgumentException("We don't have Donkeys, only Camels");

}

// create new local datasource to store in DB

jdbc.update("insert into books (title) values (?)", title);

}

Then we are ready to re the tests. First to commit condition:

public void testTransactionSuccess() throws Exception {

template.sendBody("direct:okay","Hello World");

int count = jdbc.queryForInt("select count(*) from books");

assertEquals("Number of books", 3, count);

}

And lastly the rollback condition since the 2nd book is a Donkey book:

public void testTransactionRollback() throws Exception {

try {

template.sendBody("direct:fail","Hello World");

}catch (RuntimeCamelException e) {

// expected as we fail

assertIsInstanceOf(RuntimeCamelException.class, e.getCause());

assertTrue(e.getCause().getCause() instanceof IllegalArgumentException);

assertEquals("We don't have Donkeys, only Camels",

e.getCause().getCause().getMessage());

}

int count = jdbc.queryForInt("select count(*) from books");

assertEquals("Number of books", 1, count);

}

Camel 1.x - JMS Sample

In this sample we want to listen for messages on a queue and process the

messages with our business logic java code and send them along. Since its

based on a unit test the destination is a mock endpoint.

This time we want to setup the camel context and routes using the Spring

XML syntax.

<camel:camelContext id="myroutes">

<camel:route errorHandlerRef="errorHandler">

CHAPTER 10 - PATTERN APPENDIX 504

<camel:from uri="activemq:queue:okay"/>

<camel:transacted ref="PROPAGATION_REQUIRED"/>

<camel:process ref="myProcessor"/>

<camel:to uri="mock:result"/>

</camel:route>

</camel:camelContext>

<bean id="myProcessor"

class="org.apache.camel.component.jms.tx.JMSTransactionalClientTest$MyProcessor"/>

Since the rest is standard XML stu its nothing fancy now for the reader:

<bean id="errorHandler"

class="org.apache.camel.spring.spi.TransactionErrorHandlerBuilder">

</bean>

<bean id="poolConnectionFactory"

class="org.apache.activemq.pool.PooledConnectionFactory">

</bean>

<property name="brokerURL"

value="vm://localhost?broker.persistent=false&broker.useJmx=false"/>

</bean>

<bean id="jmsTransactionManager"

class="org.springframework.jms.connection.JmsTransactionManager">

</bean>

</bean>

</bean>

<bean id="PROPAGATION_REQUIRED"

class="org.apache.camel.spring.spi.SpringTransactionPolicy">

505 CHAPTER 10 - PATTERN APPENDIX

</bean>

Our business logic is set to handle the incomming messages and fail the rst

two times. When its a success it responds with a Bye World message.

public static class MyProcessor implements Processor {

private int count;

public void process(Exchange exchange) throws Exception {

if (++count <= 2) {

throw new IllegalArgumentException("Forced Exception number " + count +

", please retry");

}

exchange.getIn().setBody("Bye World");

exchange.getIn().setHeader("count", count);

}

And our unit test is tested with this java code. Notice that we expect the Bye

World message to be delivered at the 3rd attempt.

MockEndpoint mock = getMockEndpoint("mock:result");

mock.expectedMessageCount(1);

mock.expectedBodiesReceived("Bye World");

// success at 3rd attempt

mock.message(0).header("count").isEqualTo(3);

template.sendBody("activemq:queue:okay","Hello World");

mock.assertIsSatisfied();

Camel 1.x - Spring based conguration

In Camel 1.4 we have introduced the concept of conguration of the error

handlers using spring XML conguration. The sample below demonstrates

that you can congure transaction error handlers in Spring XML as spring

beans. These can then be set as global, per route based or per policy based

error handler. The latter has been demonstrated in the samples above. This

sample is the database sample congured in Spring XML.

Notice that we have dened two error handler, one per route. The rst

route uses the transaction error handler, and the 2nd uses no error handler

at all.

CHAPTER 10 - PATTERN APPENDIX 506

<camel:camelContext id="myroutes">

<!-- here we refer to our transaction error handler we define in this Spring XML

file -->

<camel:route errorHandlerRef="transactionErrorHandler">

<camel:from uri="activemq:queue:okay"/>

<camel:transacted ref="required"/>

<camel:process ref="myProcessor"/>

<camel:to uri="mock:result"/>

</camel:route>

<!-- this route doens't use error handler, in fact the spring bean with id

noErrorHandler -->

<camel:route errorHandlerRef="noErrorHandler">

<camel:from uri="activemq:queue:bad"/>

<camel:to uri="log:bad"/>

</camel:route>

</camel:camelContext>

The following snippet is the Spring XML conguration to setup the error

handlers in pure spring XML:

</bean>

<bean id="PROPAGATION_REQUIRED"

class="org.springframework.transaction.support.TransactionTemplate">

</bean>

<bean id="transactionErrorHandler"

class="org.apache.camel.spring.spi.TransactionErrorHandlerBuilder">

</bean>

507 CHAPTER 10 - PATTERN APPENDIX

DelayPolicy (@deprecated)

DelayPolicy is a new policy introduced in Camel 1.5, to replaces the

RedeliveryPolicy used in Camel 1.4. Notice the transactionErrorHandler

can be congured with a DelayPolicy to set a xed delay in millis between

each redelivery attempt. Camel does this by sleeping the delay until

transaction is marked for rollback and the caused exception is rethrown.

This allows a simple redelivery interval that can be congured for

development mode or light production to avoid a rapid redelivery strategy

that can exhaust a system that constantly fails.

The DelayPolicy is @deprecated and removed in Camel 2.0. All redelivery

conguration should be congured on the back system.

We strongly recommend that you congure the backing system

for correct redelivery policy in your environment.

Camel 2.0 - Database Sample

In this sample we want to ensure that two endpoints is under transaction

control. These two endpoints inserts data into a database.

The sample is in its full as a unit test.

First of all we setup the usual spring stu in its conguration le. Here we

have dened a DataSource to the HSQLDB and a most importantly

the Spring DataSoruce TransactionManager that is doing the heavy lifting of

ensuring our transactional policies. You are of course free to use any

of the Spring based TransactionMananger, eg. if you are in a full blown J2EE

container you could use JTA or the WebLogic or WebSphere specic

managers.

As we use the new convention over conguration we do not need to

congure a transaction policy bean, so we do not have any

PROPAGATION_REQUIRED beans.

All the beans needed to be congured is standard Spring beans only, eg.

there are no Camel specic conguration at all.

<bean id="dataSource"

class="org.springframework.jdbc.datasource.DriverManagerDataSource">

</bean>

<bean id="txManager"

CHAPTER 10 - PATTERN APPENDIX 508

class="org.springframework.jdbc.datasource.DataSourceTransactionManager">

</bean>

</bean>

Then we are ready to dene our Camel routes. We have two routes: 1 for

success conditions, and 1 for a forced rollback condition.

This is after all based on a unit test. Notice that we mark each route as

transacted using the transacted tag.

<route>

<!-- we mark this route as transacted. Camel will lookup the spring

transaction manager

and use it by default. We can optimally pass in arguments to specify a

policy to use

that is configured with a spring transaction manager of choice. However

Camel supports

convention over configuration as we can just use the defaults out of the

box and Camel

that suites in most situations -->

<constant>Tiger in Action</constant>

</setBody>

<constant>Elephant in Action</constant>

</setBody>

</route>

<route>

<constant>Tiger in Action</constant>

</setBody>

<constant>Donkey in Action</constant>

</setBody>

</route>

</camelContext>

509 CHAPTER 10 - PATTERN APPENDIX

That is all that is needed to congure a Camel route as being transacted. Just

remember to use the transacted DSL. The rest is standard Spring XML to

setup the transaction manager.

Camel 2.0 - JMS Sample

In this sample we want to listen for messages on a queue and process the

messages with our business logic java code and send them along. Since its

based on a unit test the destination is a mock endpoint.

First we congure the standard Spring XML to declare a JMS connection

factory, a JMS transaction manager and our ActiveMQ component that we use

in our routing.

<bean id="poolConnectionFactory"

class="org.apache.activemq.pool.PooledConnectionFactory">

</bean>

<property name="brokerURL"

value="vm://localhost?broker.persistent=false&broker.useJmx=false"/>

</bean>

<bean id="jmsTransactionManager"

class="org.springframework.jms.connection.JmsTransactionManager">

</bean>

<!-- if not provided then Camel will automatic use a JmsTransactionManager,

however if you

for instance use a JTA transaction manager then you must configure it -->

</bean>

And then we congure our routes. Notice that all we have to do is mark the

route as transacted using the transacted tag.

CHAPTER 10 - PATTERN APPENDIX 510

<route>

</route>

</camelContext>

<bean id="myProcessor"

class="org.apache.camel.component.jms.tx.JMSTransactionalClientTest$MyProcessor"/>

USING MULTIPLE ROUTES WITH DIFFERENT PROPAGATION

BEHAVIORS

Available as of Camel 2.2

Suppose you want to route a message through two routes and by which the

2nd route should run in its own transaction. How do you do that? You use

propagation behaviors for that where you congure it as follows:

▪ The rst route use PROPAGATION_REQUIRED

▪ The second route use PROPAGATION_REQUIRES_NEW

This is congured in the Spring XML le:

<bean id="PROPAGATION_REQUIRED"

class="org.apache.camel.spring.spi.SpringTransactionPolicy">

</bean>

<bean id="PROPAGATION_REQUIRES_NEW"

class="org.apache.camel.spring.spi.SpringTransactionPolicy">

</bean>

Then in the routes you use transacted DSL to indicate which of these two

propagations it uses.

from("direct:mixed")

// using required

.transacted("PROPAGATION_REQUIRED")

// all these steps will be okay

.setBody(constant("Tiger in Action")).beanRef("bookService")

511 CHAPTER 10 - PATTERN APPENDIX

Transaction error handler

When a route is marked as transacted using transacted Camel will

automatic use the TransactionErrorHandler as Error Handler. It

supports basically the same feature set as the DefaultErrorHandler,

so you can for instance use Exception Clause as well.

.setBody(constant("Elephant in Action")).beanRef("bookService")

// continue on route 2

.to("direct:mixed2");

from("direct:mixed2")

// tell Camel that if this route fails then only rollback this last route

// by using (rollback only *last*)

.onException(Exception.class).markRollbackOnlyLast().end()

// using a different propagation which is requires new

.transacted("PROPAGATION_REQUIRES_NEW")

// this step will be okay

.setBody(constant("Lion in Action")).beanRef("bookService")

// this step will fail with donkey

.setBody(constant("Donkey in Action")).beanRef("bookService");

Notice how we have congured the onException in the 2nd route to indicate

in case of any exceptions we should handle it and just rollback this

transaction.

This is done using the markRollbackOnlyLast which tells Camel to only do it

for the current transaction and not globally.

See Also

• Error handling in Camel

• TransactionErrorHandler

• Error Handler

• JMS

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

CHAPTER 10 - PATTERN APPENDIX 512

Messaging Gateway

Camel has several endpoint components that support the Messaging

Gateway from the EIP patterns.

Components like Bean and CXF provide a a way to bind a Java interface to

the message exchange.

However you may want to read the Using CamelProxy documentation as a

true Messaging Gateway EIP solution.

Another approach is to use @Produce which you can read about in POJO

Producing which also can be used as a Messaging Gateway EIP solution.

See Also

• Bean

• CXF

• Using CamelProxy

• POJO Producing

• Spring Remoting

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Service Activator

Camel has several endpoint components that support the Service Activator

from the EIP patterns.

513 CHAPTER 10 - PATTERN APPENDIX

Components like Bean, CXF and Pojo provide a a way to bind the message

exchange to a Java interface/service where the route denes the endpoints

and wires it up to the bean.

In addition you can use the Bean Integration to wire messages to a bean

using annotation.

Here is a simple example of using a Direct endpoint to create a messaging

interface to a Pojo Bean service.

Using the Fluent Builders

from("direct:invokeMyService").to("bean:myService");

Using the Spring XML Extensions

<route>

</route>

See Also

• Bean

• Pojo

• CXF

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

CHAPTER 10 - PATTERN APPENDIX 514

SYSTEM MANAGEMENT

Detour

The Detour from the EIP patterns allows you to send messages through

additional steps if a control condition is met. It can be useful for turning on

extra validation, testing, debugging code when needed.

Available in Camel 1.5.

Example

In this example we essentially have a route like

from("direct:start").to("mock:result") with a conditional detour to the

mock:detour endpoint in the middle of the route..

from("direct:start").choice()

.when().method("controlBean","isDetour").to("mock:detour").end()

.to("mock:result");

Using the Spring XML Extensions

<route>

<when>

</when>

</choice>

</split>

</route>

whether the detour is turned on or o is decided by the ControlBean. So,

when the detour is on the message is routed to mock:detour and then

mock:result. When the detour is o, the message is routed to mock:result.

For full details, check the example source here:

515 CHAPTER 10 - PATTERN APPENDIX

camel-core/src/test/java/org/apache/camel/processor/DetourTest.java

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

Wire Tap

The Wire Tap from the EIP patterns allows you to route messages to a

separate tap location while it is forwarded to the ultimate destination.

Options

Name Default

Value Description

uri The endpoint uri where to send the wire tapped message. You should use either uri or ref.

ref Refers to the endpoint where to send the wire tapped message. You should use either uri or ref.

executorServiceRef Refers to a custom Thread Pool to be used when processing the wire tapped messages. If not set then

Camel uses a default thread pool.

processorRef Refers to a custom Processor to be used for creating a new message (eg the send a new message

mode). See below.

copy true Camel 2.3: Should a copy of the Exchange to used when wire tapping the message.

onPrepareRef Camel 2.8: Refers to a custom Processor to prepare the copy of the Exchange to be wire tapped. This

allows you to do any custom logic, such as deep-cloning the message payload if that's needed etc.

WireTap thread pool

The Wire Tap uses a thread pool to process the tapped messages. The thread

pool will by default use the default settings. You can read more details at

Threading Model.

The default settings will when the thread pool exhaust (the worker queue is

lled up, and no idle threads), will use the current caller thread as well. This

means the wire tap will not be asynchronous at that incident. To remedy this

you can congure an explicit thread pool on the Wire Tap having either a

CHAPTER 10 - PATTERN APPENDIX 516

Streams

If you Wire Tap a stream message body then you should consider

enable Stream caching to ensure the message body can be re-read.

See more details at Stream caching

dierent rejection policy, or a larger worker queue, or more worker threads

etc.

WireTap node

Available as of Camel 2.0

In Camel 2.0 we have introduced a new wireTap node for properly doing

wire taps. Camel will copy the original Exchange and set its Exchange Pattern

to InOnly as we want the tapped Exchange to be sent as a re and forget

style. The tapped Exchange is then send in a separate thread so it can run in

parallel with the original

We have extended the wireTap to support two avors when tapping an

Exchange

▪ send a copy of the original Exchange (the traditional wire tap)

▪ send a new Exchange, allowing you to populate the Exchange

beforehand

Sending a copy (traditional wire tap)

Using the Fluent Builders

from("direct:start")

.to("log:foo")

.wireTap("direct:tap")

.to("mock:result");

Using the Spring XML Extensions

<route>

</route>

517 CHAPTER 10 - PATTERN APPENDIX

Sending a new Exchange

Using the Fluent Builders

Camel supports either a processor or an Expression to populate the new

Exchange. Using processor gives you full power how the Exchange is

populated as you can set properties, headers etc. The Expression can only be

used to set the IN body.

From Camel 2.3 onwards the Expression or Processor is pre populated

with a copy of the original Exchange which allows you to access the original

message when you prepare the new Exchange to be sent. You can use the

copy option to indicate if you want this or not (default is enabled). If your

turn copy=false then it works as in Camel 2.2 or older, where the Exchange

always will be empty.

Below is the processor variation shown. This example is from Camel 2.3,

where we disable copy by passing in false. This will create a new empty

Exchange.

from("direct:start")

.wireTap("direct:foo",false,new Processor() {

public void process(Exchange exchange) throws Exception {

exchange.getIn().setBody("Bye World");

exchange.getIn().setHeader("foo","bar");

}

}).to("mock:result");

from("direct:foo").to("mock:foo");

And the Expression variation. This example is from Camel 2.3, where we

disable copy by passing in false. This will create a new empty Exchange.

from("direct:start")

.wireTap("direct:foo",false, constant("Bye World"))

.to("mock:result");

from("direct:foo").to("mock:foo");

Using the Spring XML Extensions

The processor variation, notice we use a processorRef attribute to refer to a

spring bean with this id:

<route>

</route>

CHAPTER 10 - PATTERN APPENDIX 518

And the Expression variation, where the expression is dened in the body

tag:

<route>

<body><constant>Bye World</constant></body>

</wireTap>

</route>

And this variation accesses the body of the original message and creates a

new Exchange which is based on the Expression.

It will create a new Exchange and have the body contain "Bye ORIGINAL

BODY MESSAGE HERE"

<route>

</wireTap>

</route>

Camel 1.x

The following example shows how to route a request from an input queue:a

endpoint to the wire tap location queue:tap it is received by queue:b

Using the Fluent Builders

RouteBuilder builder = new RouteBuilder() {

public void configure() {

errorHandler(deadLetterChannel("mock:error"));

from("seda:a")

.multicast().to("seda:tap","seda:b");

}

};

Using the Spring XML Extensions

<camelContext errorHandlerRef="errorHandler" xmlns="http://camel.apache.org/schema/

spring">

<route>

519 CHAPTER 10 - PATTERN APPENDIX

</multicast>

</route>

</camelContext>

Further Example

For another example of this pattern in use you could look at the wire tap test

case.

Sending a new Exchange and set headers in DSL

Available as of Camel 2.8

If you send a new messages using the Wire Tap then you could only set the

message body using an Expression from the DSL. If you also need to set new

headers you would have to use a Processor for that. So in Camel 2.8 onwards

we have improved this situation so you can now set headers as well in the

DSL.

The following example sends a new message which has

▪ "Bye World" as message body

▪ a header with key "id" with the value 123

▪ a header with key "date" which has current date as value

Java DSL

from("direct:start")

// tap a new message and send it to direct:tap

// the new message should be Bye World with 2 headers

.wireTap("direct:tap")

// create the new tap message body and headers

.newExchangeBody(constant("Bye World"))

.newExchangeHeader("id", constant(123))

.newExchangeHeader("date", simple("${date:now:yyyyMMdd}"))

.end()

// here we continue routing the original messages

.to("mock:result");

// this is the tapped route

from("direct:tap")

.to("mock:tap");

CHAPTER 10 - PATTERN APPENDIX 520

XML DSL

The XML DSL is slightly dierent than Java DSL as how you congure the

message body and headers. In XML you use <body> and <setHeader> as

shown:

<route>

<body><constant>Bye World</constant></body>

<setHeader headerName="date"><simple>${date:now:yyyyMMdd}</simple></setHeader>

</wireTap>

</route>

Using onPrepare to execute custom logic when preparing messages

Available as of Camel 2.8

See details at Multicast

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

LOG

How can I log processing a Message?

Camel provides many ways to log processing a message. Here is just some

examples:

▪ You can use the Log component which logs the Message content.

▪ You can use the Tracer which trace logs message ow.

▪ You can also use a Processor or Bean and log from Java code.

▪ You can use the log DSL.

521 CHAPTER 10 - PATTERN APPENDIX

Using log DSL

And in Camel 2.2 you can use the log DSL which allows you to use Simple

language to construct a dynamic message which gets logged.

For example you can do

from("direct:start").log("Processing ${id}").to("bean:foo");

Which will construct a String message at runtime using the Simple language.

The log message will by logged at INFO level using the route id as the log

name. By default a route is named route-1,route-2 etc. But you can use

the routeId("myCoolRoute") to set a route name of choice.

The log DSL have overloaded methods to set the logging level and/or name

as well.

from("direct:start").log(LoggingLevel.DEBUG, "Processing ${id}").to("bean:foo");

For example you can use this to log the le name being processed if you

consume les.

from("file://target/files").log(LoggingLevel.DEBUG, "Processing file

${file:name}").to("bean:foo");

Using log DSL from Spring

In Spring DSL its also easy to use log DSL as shown below:

</route>

The log tag has attributes to set the message,loggingLevel and logName.

For example:

</route>

CHAPTER 10 - PATTERN APPENDIX 522

Dierence between log in the DSL and Log component

The log DSL is much lighter and meant for logging human logs

such as Starting to do ... etc. It can only log a message based

on the Simple language. On the other hand Log component is a full

edged component which involves using endpoints and etc. The

Log component is meant for logging the Message itself and you

have many URI options to control what you would like to be logged.

Using This Pattern

If you would like to use this EIP Pattern then please read the Getting Started,

you may also nd the Architecture useful particularly the description of

Endpoint and URIs. Then you could try out some of the Examples rst before

trying this pattern out.

523 CHAPTER 10 - PATTERN APPENDIX

CHAPTER 11

°°°°

Component Appendix

There now follows the documentation on each Camel component.

ACTIVEMQ COMPONENT

The ActiveMQ component allows messages to be sent to a JMS Queue or

Topic or messages to be consumed from a JMS Queue or Topic using Apache

ActiveMQ.

This component is based on JMS Component and uses Spring's JMS support

for declarative transactions, using Spring's JmsTemplate for sending and a

MessageListenerContainer for consuming. All the options from the JMS

component also applies for this component.

To use this component make sure you have the activemq.jar or

activemq-core.jar on your classpath along with any Camel dependencies

such as camel-core.jar,camel-spring.jar and camel-jms.jar.

URI format

activemq:[queue:|topic:]destinationName

Where destinationName is an ActiveMQ queue or topic name. By default,

the destinationName is interpreted as a queue name. For example, to

connect to the queue, FOO.BAR, use:

activemq:FOO.BAR

You can include the optional queue: prex, if you prefer:

activemq:queue:FOO.BAR

To connect to a topic, you must include the topic: prex. For example, to

connect to the topic, Stocks.Prices, use:

CHAPTER 11 - COMPONENT APPENDIX 524

Transacted and caching

See section Transactions and Cache Levels below on JMS page if

you are using transactions with JMS as it can impact performance.

activemq:topic:Stocks.Prices

Options

See Options on the JMS component as all these options also apply for this

component.

Conguring the Connection Factory

This test case shows how to add an ActiveMQComponent to the

CamelContext using the activeMQComponent() method while specifying the

brokerURL used to connect to ActiveMQ.

camelContext.addComponent("activemq",

activeMQComponent("vm://localhost?broker.persistent=false"));

Conguring the Connection Factory using Spring XML

You can congure the ActiveMQ broker URL on the ActiveMQComponent as

follows

<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.0.xsd

http://camel.apache.org/schema/spring

http://camel.apache.org/schema/spring/camel-spring.xsd">

</camelContext>

<bean id="activemq"

class="org.apache.activemq.camel.component.ActiveMQComponent">

</bean>

</beans>

525 CHAPTER 11 - COMPONENT APPENDIX

Using connection pooling

When sending to an ActiveMQ broker using Camel it's recommended to use a

pooled connection factory to eciently handle pooling of JMS connections,

sessions and producers. This is documented on the ActiveMQ Spring Support

page.

You can grab ActiveMQ's

org.apache.activemq.pool.PooledConnectionFactory with Maven:

<groupId>org.apache.activemq</groupId>

<artifactId>activemq-pool</artifactId>

</dependency>

And then setup the activemq Camel component as follows:

<bean id="jmsConnectionFactory"

class="org.apache.activemq.ActiveMQConnectionFactory">

</bean>

<bean id="pooledConnectionFactory"

class="org.apache.activemq.pool.PooledConnectionFactory">

</bean>

<bean id="jmsConfig"

class="org.apache.camel.component.jms.JmsConfiguration">

</bean>

<bean id="activemq"

class="org.apache.activemq.camel.component.ActiveMQComponent">

</bean>

Invoking MessageListener POJOs in a Camel route

The ActiveMQ component also provides a helper Type Converter from a JMS

MessageListener to a Processor. This means that the Bean component is

capable of invoking any JMS MessageListener bean directly inside any route.

So for example you can create a MessageListener in JMS like this:

CHAPTER 11 - COMPONENT APPENDIX 526

public class MyListener implements MessageListener {

public void onMessage(Message jmsMessage) {

// ...

}

Then use it in your Camel route as follows

from("file://foo/bar").

bean(MyListener.class);

That is, you can reuse any of the Camel Components and easily integrate

them into your JMS MessageListener POJO!

Using ActiveMQ Destination Options

Available as of ActiveMQ 5.6

You can congure the Destination Options in the endpoint uri, using the

"destination." prex. For example to mark a consumer as exclusive, and set

its prefetch size to 50, you can do as follows:

<route>

</route>

<route>

<!-- use consumer.exclusive ActiveMQ destination option, notice we have to prefix

with destination. -->

<from

uri="activemq:foo?destination.consumer.exclusive=true&destination.consumer.prefetchSize=50"/>

</route>

</camelContext>

Consuming Advisory Messages

ActiveMQ can generate Advisory messages which are put in topics that you

can consume. Such messages can help you send alerts in case you detect

slow consumers or to build statistics (number of messages/produced per day,

etc.) The following Spring DSL example shows you how to read messages

from a topic.

The below route starts by reading the topic ActiveMQ.Advisory.Connection.

To watch another topic, simply change the name according to the name

provided in ActiveMQ Advisory Messages documentation. The parameter

527 CHAPTER 11 - COMPONENT APPENDIX

mapJmsMessage=false allows for converting the

org.apache.activemq.command.ActiveMqMessage object from the jms queue.

Next, the body received is converted into a String for the purposes of this

example and a carriage return is added. Finally, the string is added to a le

<route>

</transform>

<to uri="file://data/activemq/

?fileExist=Append&fileName=advisoryConnection-${date:now:yyyyMMdd}.txt" />

</route>

If you consume a message on a queue, you should see the following les

under the data/activemq folder :

advisoryConnection-20100312.txt

advisoryProducer-20100312.txt

and containing string:

ActiveMQMessage {commandId = 0, responseRequired = false,

messageId = ID:dell-charles-3258-1268399815140

-1:0:0:0:221, originalDestination = null, originalTransactionId = null,

producerId = ID:dell-charles-3258-1268399815140-1:0:0:0,

destination = topic://ActiveMQ.Advisory.Connection, transactionId = null,

expiration = 0, timestamp = 0, arrival = 0, brokerInTime = 1268403383468,

brokerOutTime = 1268403383468, correlationId = null, replyTo = null,

persistent = false, type = Advisory, priority = 0, groupID = null, groupSequence = 0,

targetConsumerId = null, compressed = false, userID = null, content = null,

marshalledProperties = org.apache.activemq.util.ByteSequence@17e2705,

dataStructure = ConnectionInfo {commandId = 1, responseRequired = true,

connectionId = ID:dell-charles-3258-1268399815140-2:50,

clientId = ID:dell-charles-3258-1268399815140-14:0, userName = , password = *****,

brokerPath = null, brokerMasterConnector = false, manageable = true,

clientMaster = true}, redeliveryCounter = 0, size = 0, properties =

{originBrokerName=master, originBrokerId=ID:dell-charles-3258-1268399815140-0:0,

originBrokerURL=vm://master}, readOnlyProperties = true, readOnlyBody = true,

droppable = false}

Getting Component JAR

You will need these dependencies

▪camel-jms

▪activemq-camel

CHAPTER 11 - COMPONENT APPENDIX 528

camel-jms

You must have the camel-jms as dependency as ActiveMQ is an extension to

the JMS component.

<groupId>org.apache.camel</groupId>

<artifactId>camel-jms</artifactId>

</dependency>

The ActiveMQ Camel component is released with the ActiveMQ project itself.

For Maven 2 users you simply just need to add the following dependency to

your project.

ActiveMQ 5.2 or later

<groupId>org.apache.activemq</groupId>

<artifactId>activemq-camel</artifactId>

</dependency>

ActiveMQ 5.1.0

For 5.1.0 its in the activemq-core library

<groupId>org.apache.activemq</groupId>

<artifactId>activemq-core</artifactId>

</dependency>

Alternatively you can download the component jar directly from the Maven

repository:

• activemq-camel-5.2.0.jar

• activemq-core-5.1.0.jar

ActiveMQ 4.x

For this version you must use the JMS component instead. Please be careful

to use a pooling connection factory as described in the JmsTemplate Gotchas

529 CHAPTER 11 - COMPONENT APPENDIX

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

ACTIVEMQ JOURNAL COMPONENT

The ActiveMQ Journal Component allows messages to be stored in a rolling

log le and then consumed from that log le. The journal aggregates and

batches up concurrent writes so that the overhead of writing and waiting for

the disk sync is relatively constant regardless of how many concurrent writes

are being done. Therefore, this component supports and encourages you to

use multiple concurrent producers to the same journal endpoint.

Each journal endpoint uses a dierent log le and therefore write batching

(and the associated performance boost) does not occur between multiple

endpoints.

This component only supports one active consumer on the endpoint. After

the message is processed by the consumer's processor, the log le is marked

and only subsequent messages in the log le will get delivered to consumers.

URI format

activemq.journal:directoryName[?options]

So for example, to send to the journal located in the /tmp/data directory you

would use the following URI:

activemq.journal:/tmp/data

Options

Name Default

Value Description

syncConsume false If set to true, when the journal is marked after a message is consumed, wait till the Operating System has

veried the mark update is safely stored on disk.

syncProduce true If set to true, wait till the Operating System has veried the message is safely stored on disk.

You can append query options to the URI in the following format,

?option=value&option=value&...

CHAPTER 11 - COMPONENT APPENDIX 530

Expected Exchange Data Types

The consumer of a Journal endpoint generates DefaultExchange objects with

the in message :

• header "journal" : set to the endpoint uri of the journal the message

came from

• header "location" : set to a Location which identies where the

recored was stored on disk

• body : set to ByteSequence which contains the byte array data of the

stored message

The producer to a Journal endpoint expects an Exchange with an In message

where the body can be converted to a ByteSequence or a byte[].

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

AMQP

The amqp: component supports the AMQP protocol using the Client API of

the Qpid project.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-amqp</artifactId>

<version>${camel.version}</version> <!-- use the same version as your Camel core

version -->

</dependency>

URI format

amqp:[queue:|topic:]destinationName[?options]

You can specify all of the various conguration options of the JMS component

after the destination name.

531 CHAPTER 11 - COMPONENT APPENDIX

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

SQS COMPONENT

Available as of Camel 2.6

The sqs component supports sending and receiving messages to Amazon's

SQS service.

URI Format

aws-sqs://queue-name[?options]

The queue will be created if they don't already exists.

You can append query options to the URI in the following format,

?options=value&option2=value&...

URI Options

Name Default

Value Context Description

amazonSQSClient null Shared Reference to a com.amazonaws.services.sqs.AmazonSQSClient in

the Registry.

accessKey null Shared Amazon AWS Access Key

secretKey null Shared Amazon AWS Secret Key

amazonSQSEndpoint null Shared The region with which the AWS-SQS client wants to work with.

attributeNames null Consumer A list of attributes to set in the

com.amazonaws.services.sqs.model.ReceiveMessageRequest.

defaultVisibilityTimeout null Shared The visibility timeout (in seconds) to set in the

com.amazonaws.services.sqs.model.CreateQueueRequest.

deleteAfterRead true Consumer Delete message from SQS after it has been read

maxMessagesPerPoll null Consumer

The maximum number of messages which can be received in one poll

to set in the

com.amazonaws.services.sqs.model.ReceiveMessageRequest.

CHAPTER 11 - COMPONENT APPENDIX 532

Prerequisites

You must have a valid Amazon Web Services developer account,

and be signed up to use Amazon SQS. More information are

available at Amazon SQS.

visibilityTimeout null Shared

The duration (in seconds) that the received messages are hidden

from subsequent retrieve requests after being retrieved by a

ReceiveMessage request to set in the

com.amazonaws.services.sqs.model.SetQueueAttributesRequest.

This only make sense if its dierent from

defaultVisibilityTimeout. It changes the queue visibility timeout

attribute permanently.

messageVisibilityTimeout null Consumer

Camel 2.8: The duration (in seconds) that the received messages

are hidden from subsequent retrieve requests after being retrieved by

a ReceiveMessage request to set in the

com.amazonaws.services.sqs.model.ReceiveMessageRequest. It

does NOT change the queue visibility timeout attribute permanently.

maximumMessageSize null Shared

Camel 2.8: The maximumMessageSize (in bytes) an SQS message

can contain for this queue, to set in the

com.amazonaws.services.sqs.model.SetQueueAttributesRequest.

messageRetentionPeriod null Shared

Camel 2.8: The messageRetentionPeriod (in seconds) a message will

be retained by SQS for this queue, to set in the

com.amazonaws.services.sqs.model.SetQueueAttributesRequest.

policy null Shared Camel 2.8: The policy for this queue to set in the

com.amazonaws.services.sqs.model.SetQueueAttributesRequest.

Batch Consumer

This component implements the Batch Consumer.

This allows you for instance to know how many messages exists in this

batch and for instance let the Aggregator aggregate this number of

messages.

533 CHAPTER 11 - COMPONENT APPENDIX

Required SQS component options

You have to provide the amazonSQSClient in the Registry or your

accessKey and secretKey to access the Amazon's SQS.

Usage

Message headers set by the SQS producer

Header Type Description

CamelAwsSqsMD5OfBody String The MD5 checksum of the Amazon SQS message.

CamelAwsSqsMessageId String The Amazon SQS message ID.

Message headers set by the SQS consumer

Header Type Description

CamelAwsSqsMD5OfBody String The MD5 checksum of the Amazon SQS message.

CamelAwsSqsMessageId String The Amazon SQS message ID.

CamelAwsSqsReceiptHandle String The Amazon SQS message receipt handle.

CamelAwsSqsAttributes Map<String, String> The Amazon SQS message attributes.

Advanced AmazonSQSClient conguration

If your Camel Application is running behind a rewall or if you need to have

more control over the AmazonSQSClient conguration, you can create your

own instance:

AWSCredentials awsCredentials = new BasicAWSCredentials("myAccessKey","mySecretKey");

ClientConfiguration clientConfiguration = new ClientConfiguration();

clientConfiguration.setProxyHost("http://myProxyHost");

clientConfiguration.setProxyPort(8080);

AmazonSQSClient client = new AmazonSQSClient(awsCredentials, clientConfiguration);

and refer to it in your Camel aws-sqs component conguration:

from("aws-sqs://MyQueue?amazonSQSClient=#amazonSQSClient&delay=5000&maxMessagesPerPoll=5")

.to("mock:result");

CHAPTER 11 - COMPONENT APPENDIX 534

Dependencies

Maven users will need to add the following dependency to their pom.xml.

Listing 67. pom.xml

<groupId>org.apache.camel</groupId>

<artifactId>camel-aws</artifactId>

<version>${camel-version}</version>

</dependency>

where ${camel-version} must be replaced by the actual version of Camel

(2.6 or higher).

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ AWS Component

ATOM COMPONENT

The atom: component is used for polling Atom feeds.

Camel will poll the feed every 60 seconds by default.

Note: The component currently only supports polling (consuming) feeds.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-atom</artifactId>

</dependency>

URI format

atom://atomUri[?options]

Where atomUri is the URI to the Atom feed to poll.

535 CHAPTER 11 - COMPONENT APPENDIX

Options

Property Default Description

splitEntries true

If true Camel will poll the feed and for the subsequent polls return each entry poll by poll. If the

feed contains 7 entries then Camel will return the rst entry on the rst poll, the 2nd entry on the

next poll, until no more entries where as Camel will do a new update on the feed. If false then

Camel will poll a fresh feed on every invocation.

filter true

Is only used by the split entries to lter the entries to return. Camel will default use the

UpdateDateFilter that only return new entries from the feed. So the client consuming from the

feed never receives the same entry more than once. The lter will return the entries ordered by

the newest last.

lastUpdate null

Is only used by the lter, as the starting timestamp for selection never entries (uses the

entry.updated timestamp). Syntax format is: yyyy-MM-ddTHH:MM:ss. Example:

2007-12-24T17:45:59.

throttleEntries true

Camel 2.5: Sets whether all entries identied in a single feed poll should be delivered

immediately. If true, only one entry is processed per consumer.delay. Only applicable when

splitEntries is set to true.

feedHeader true Sets whether to add the Abdera Feed object as a header.

sortEntries false If splitEntries is true, this sets whether to sort those entries by updated date.

consumer.delay 60000 Delay in millis between each poll.

consumer.initialDelay 1000 Millis before polling starts.

consumer.userFixedDelay false If true, use xed delay between pools, otherwise xed rate is used. See

ScheduledExecutorService in JDK for details.

You can append query options to the URI in the following format,

?option=value&option=value&...

Exchange data format

Camel will set the In body on the returned Exchange with the entries.

Depending on the splitEntries ag Camel will either return one Entry or a

List<Entry>.

Option Value Behavior

splitEntries true Only a single entry from the currently being processed feed is set: exchange.in.body(Entry)

splitEntries false The entire list of entries from the feed is set: exchange.in.body(List<Entry>)

Camel can set the Feed object on the In header (see feedHeader option to

disable this):

Message Headers

Camel atom uses these headers.

Header Description

org.apache.camel.component.atom.feed Camel 1.x: When consuming the org.apache.abdera.model.Feed object is set to this header.

CamelAtomFeed Camel 2.0: When consuming the org.apache.abdera.model.Feed object is set to this header.

Samples

In this sample we poll James Strachan's blog.

from("atom://http://macstrac.blogspot.com/feeds/posts/default").to("seda:feeds");

CHAPTER 11 - COMPONENT APPENDIX 536

In this sample we want to lter only good blogs we like to a SEDA queue. The

sample also shows how to setup Camel standalone, not running in any

Container or using Spring.

// This is the CamelContext that is the heart of Camel

private CamelContext context;

protected CamelContext createCamelContext() throws Exception {

// First we register a blog service in our bean registry

SimpleRegistry registry = new SimpleRegistry();

registry.put("blogService",new BlogService());

// Then we create the camel context with our bean registry

context = new DefaultCamelContext(registry);

// Then we add all the routes we need using the route builder DSL syntax

context.addRoutes(createMyRoutes());

return context;

}

/**

* This is the route builder where we create our routes using the Camel DSL

protected RouteBuilder createMyRoutes() throws Exception {

return new RouteBuilder() {

public void configure() throws Exception {

// We pool the atom feeds from the source for further processing in the

seda queue

// we set the delay to 1 second for each pool as this is a unit test also

and we can

// not wait the default poll interval of 60 seconds.

// Using splitEntries=true will during polling only fetch one Atom Entry

at any given time.

// As the feed.atom file contains 7 entries, using this will require 7

polls to fetch the entire

// content. When Camel have reach the end of entries it will refresh the

atom feed from URI source

// and restart - but as Camel by default uses the UpdatedDateFilter it

will only deliver new

// blog entries to "seda:feeds". So only when James Straham updates his

blog with a new entry

// Camel will create an exchange for the seda:feeds.

from("atom:file:src/test/data/

feed.atom?splitEntries=true&consumer.delay=1000").to("seda:feeds");

// From the feeds we filter each blot entry by using our blog service

class

from("seda:feeds").filter().method("blogService",

"isGoodBlog").to("seda:goodBlogs");

// And the good blogs is moved to a mock queue as this sample is also

used for unit testing

537 CHAPTER 11 - COMPONENT APPENDIX

// this is one of the strengths in Camel that you can also use the mock

endpoint for your

// unit tests

from("seda:goodBlogs").to("mock:result");

}

};

}

/**

* This is the actual junit test method that does the assertion that our routes is

working as expected

@Test

public void testFiltering() throws Exception {

// create and start Camel

context = createCamelContext();

context.start();

// Get the mock endpoint

MockEndpoint mock = context.getEndpoint("mock:result", MockEndpoint.class);

// There should be at least two good blog entries from the feed

mock.expectedMinimumMessageCount(2);

// Asserts that the above expectations is true, will throw assertions exception

if it failed

// Camel will default wait max 20 seconds for the assertions to be true,if the

conditions

// is true sooner Camel will continue

mock.assertIsSatisfied();

// stop Camel after use

context.stop();

}

/**

* Services for blogs

public class BlogService {

/**

* Tests the blogs if its a good blog entry or not

public boolean isGoodBlog(Exchange exchange) {

Entry entry = exchange.getIn().getBody(Entry.class);

String title = entry.getTitle();

// We like blogs about Camel

boolean good = title.toLowerCase().contains("camel");

return good;

}

CHAPTER 11 - COMPONENT APPENDIX 538

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ RSS

BEAN COMPONENT

The bean: component binds beans to Camel message exchanges.

URI format

bean:beanID[?options]

Where beanID can be any string which is used to look up the bean in the

Registry

Options

Name Type Default Description

method String null

The method name from the bean that will be invoked. If not provided, Camel will try to

determine the method itself. In case of ambiguity an exception will be thrown. See Bean

Binding for more details. From Camel 2.8 onwards you can specify type qualiers to pin-

point exact method to use for overloaded methods. From Camel 2.9 onwards you can

specify parameter values directly in the method syntax. See more details at Bean Binding.

cache boolean false If enabled, Camel will cache the result of the rst Registry look-up. Cache can be enabled

if the bean in the Registry is dened as a singleton scope.

multiParameterArray boolean false Camel 1.5: How to treat the parameters which are passed from the message body; if it is

true, the In message body should be an array of parameters.

You can append query options to the URI in the following format,

?option=value&option=value&...

Using

The object instance that is used to consume messages must be explicitly

registered with the Registry. For example, if you are using Spring you must

dene the bean in the Spring conguration, spring.xml; or if you don't use

Spring, by registering the bean in JNDI.

// lets populate the context with the services we need

// note that we could just use a spring.xml file to avoid this step

JndiContext context = new JndiContext();

context.bind("bye",new SayService("Good Bye!"));

539 CHAPTER 11 - COMPONENT APPENDIX

CamelContext camelContext = new DefaultCamelContext(context);

Once an endpoint has been registered, you can build Camel routes that use it

to process exchanges.

// lets add simple route

camelContext.addRoutes(new RouteBuilder() {

public void configure() {

from("direct:hello").to("bean:bye");

}

});

Abean: endpoint cannot be dened as the input to the route; i.e. you cannot

consume from it, you can only route from some inbound message Endpoint

to the bean endpoint as output. So consider using a direct: or queue:

endpoint as the input.

You can use the createProxy() methods on ProxyHelper to create a proxy

that will generate BeanExchanges and send them to any endpoint:

Endpoint endpoint = camelContext.getEndpoint("direct:hello");

ISay proxy = ProxyHelper.createProxy(endpoint, ISay.class);

String rc = proxy.say();

assertEquals("Good Bye!", rc);

And the same route using Spring DSL:

<route>

</route>

Bean as endpoint

Camel also supports invoking Bean as an Endpoint. In the route below:

<route>

</route>

</camelContext>

CHAPTER 11 - COMPONENT APPENDIX 540

What happens is that when the exchange is routed to the myBean Camel will

use the Bean Binding to invoke the bean.

The source for the bean is just a plain POJO:

public class ExampleBean {

public String sayHello(String name) {

return "Hello " + name + "!";

}

Camel will use Bean Binding to invoke the sayHello method, by converting

the Exchange's In body to the String type and storing the output of the

method on the Exchange Out body.

Bean Binding

How bean methods to be invoked are chosen (if they are not specied

explicitly through the method parameter) and how parameter values are

constructed from the Message are all dened by the Bean Binding

mechanism which is used throughout all of the various Bean Integration

mechanisms in Camel.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

• Class component

• Bean Binding

• Bean Integration

BEAN VALIDATION COMPONENT

Available as of Camel 2.3

The Validation component performs bean validation of the message body

using the Java Bean Validation API (JSR 303). Camel uses the reference

implementation, which is Hibernate Validator.

Maven users will need to add the following dependency to their pom.xml

for this component:

541 CHAPTER 11 - COMPONENT APPENDIX

<groupId>org.apache.camel</groupId>

<artifactId>camel-bean-validator</artifactId>

</dependency>

URI format

bean-validator:something[?options]

bean-validator://something[?options]

Where something must be present to provide a valid url

You can append query options to the URI in the following format,

?option=value&option=value&...

URI Options

Option Default Description

group javax.validation.groups.Default The custom validation group to use.

messageInterpolator org.hibernate.validator.engine.

ResourceBundleMessageInterpolator

Reference to a custom

javax.validation.MessageInterpolator in the Registry.

traversableResolver org.hibernate.validator.engine.resolver.

DefaultTraversableResolver

Reference to a custom

javax.validation.TraversableResolver in the Registry.

constraintValidatorFactory org.hibernate.validator.engine.

ConstraintValidatorFactoryImpl

Reference to a custom

javax.validation.ConstraintValidatorFactory in the

Registry.

ServiceMix4/OSGi Deployment.

The bean-validator when deployed in an OSGi environment requires a little

help to accommodate the resource loading specied in JSR303, this was xed

in Servicemix-Specs 1.6-SNAPSHOT.

Example

Assumed we have a java bean with the following annotations

Listing 68. Car.java

public class Car {

CHAPTER 11 - COMPONENT APPENDIX 542

@NotNull

private String manufacturer;

@NotNull

@Size(min = 5, max = 14, groups = OptionalChecks.class)

private String licensePlate;

// getter and setter

}

and an interface denition for our custom validation group

Listing 69. OptionalChecks.java

public interface OptionalChecks {

}

with the following Camel route, only the @NotNull constraints on the

attributes manufacturer and licensePlate will be validated (Camel uses the

default group javax.validation.groups.Default).

from("direct:start")

.to("bean-validator://x")

.to("mock:end")

If you want to check the constraints from the group OptionalChecks, you

have to dene the route like this

from("direct:start")

.to("bean-validator://x?group=OptionalChecks")

.to("mock:end")

If you want to check the constraints from both groups, you have to dene a

new interface rst

Listing 70. AllChecks.java

@GroupSequence({Default.class, OptionalChecks.class})

public interface AllChecks {

}

and then your route denition should looks like this

from("direct:start")

.to("bean-validator://x?group=AllChecks")

.to("mock:end")

543 CHAPTER 11 - COMPONENT APPENDIX

And if you have to provide your own message interpolator, traversable

resolver and constraint validator factory, you have to write a route like this

from("direct:start")

.to("bean-validator://x?group=AllChecks&messageInterpolator=#myMessageInterpolator

&traversableResolver=#myTraversableResolver&constraintValidatorFactory=#myConstraintValidatorFactory")

.to("mock:end")

It's also possible to describe your constraints as XML and not as Java

annotations. In this case, you have to provide the le META-INF/

validation.xml which could looks like this

Listing 71. validation.xml

<?xml version="1.0" encoding="UTF-8"?>

<validation-config

xmlns="http://jboss.org/xml/ns/javax/validation/configuration"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/configuration">

<default-provider>org.hibernate.validator.HibernateValidator</default-provider>

<message-interpolator>org.hibernate.validator.engine.ResourceBundleMessageInterpolator</message-interpolator>

<traversable-resolver>org.hibernate.validator.engine.resolver.DefaultTraversableResolver</traversable-resolver>

<constraint-validator-factory>org.hibernate.validator.engine.ConstraintValidatorFactoryImpl</constraint-validator-factory>

<constraint-mapping>/constraints-car.xml</constraint-mapping>

</validation-config>

and the constraints-car.xml le

Listing 72. constraints-car.xml

<?xml version="1.0" encoding="UTF-8"?>

<constraint-mappings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/mapping

validation-mapping-1.0.xsd"

xmlns="http://jboss.org/xml/ns/javax/validation/mapping">

<default-package>org.apache.camel.component.bean.validator</default-package>

<constraint annotation="javax.validation.constraints.NotNull"

</field>

CHAPTER 11 - COMPONENT APPENDIX 544

<constraint annotation="javax.validation.constraints.NotNull"

<value>org.apache.camel.component.bean.validator.OptionalChecks</value>

</groups>

</constraint>

</field>

</bean>

</constraint-mappings>

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

BROWSE COMPONENT

Available as of Camel 2.0

The Browse component provides a simple BrowsableEndpoint which can

be useful for testing, visualisation tools or debugging. The exchanges sent to

the endpoint are all available to be browsed.

URI format

browse:someName

Where someName can be any string to uniquely identify the endpoint.

Sample

In the route below, we insert a browse: component to be able to browse the

Exchanges that are passing through:

from("activemq:order.in").to("browse:orderReceived").to("bean:processOrder");

We can now inspect the received exchanges from within the Java code:

545 CHAPTER 11 - COMPONENT APPENDIX

private CamelContext context;

public void inspectRecievedOrders() {

BrowsableEndpoint browse = context.getEndpoint("browse:orderReceived",

BrowsableEndpoint.class);

List<Exchange> exchanges = browse.getExchanges();

...

// then we can inspect the list of received exchanges from Java

for (Exchange exchange : exchanges) {

String payload = exchange.getIn().getBody();

...

}

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

CACHE COMPONENT

Available as of Camel 2.1

The cache component enables you to perform caching operations using

EHCache as the Cache Implementation. The cache itself is created on

demand or if a cache of that name already exists then it is simply utilized

with its original settings.

This component supports producer and event based consumer endpoints.

The Cache consumer is an event based consumer and can be used to

listen and respond to specic cache activities. If you need to perform

selections from a pre-existing cache, used the processors dened for the

cache component.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-cache</artifactId>

</dependency>

CHAPTER 11 - COMPONENT APPENDIX 546

URI format

cache://cacheName[?options]

You can append query options to the URI in the following format,

?option=value&option=#beanRef&...

Options

Name Default Value Description

maxElementsInMemory 1000 The numer of elements that may be stored in the dened cache

memoryStoreEvictionPolicy MemoryStoreEvictionPolicy.LFU

The number of elements that may be stored in the dened cache.

Options include

▪ MemoryStoreEvictionPolicy.LFU - Least frequently

used

▪ MemoryStoreEvictionPolicy.LRU - Least recently used

▪ MemoryStoreEvictionPolicy.FIFO - rst in rst out,

the oldest element by creation time

overflowToDisk true Species whether cache may overow to disk

eternal false

Sets whether elements are eternal. If eternal, timeouts are ignored

and the

element is never expired.

timeToLiveSeconds 300

The maximum time between creation time and when an element

expires.

Is only used if the element is not eternal

timeToIdleSeconds 300 The maximum amount of time between accesses before an

element expires

diskPersistent true

Whether the disk store persists between restarts of the Virtual

Machine.

The default value is false.

diskExpiryThreadIntervalSeconds 120

The number of seconds between runs of the disk expiry thread. The

default value

is 120 seconds

cacheManagerFactory null

Camel 2.8: If you want to use a custom factory which instantiates

and creates the EHCache net.sf.ehcache.CacheManager.

Type: abstract

org.apache.camel.component.cache.CacheManagerFactory

eventListenerRegistry null

Camel 2.8: Sets a list of EHCache

net.sf.ehcache.event.CacheEventListener for all new caches-

no need to dene it per cache in EHCache xml cong anymore.

Type:

org.apache.camel.component.cache.CacheEventListenerRegistry

cacheLoaderRegistry null

Camel 2.8: Sets a list of

org.apache.camel.component.cache.CacheLoaderWrapper that

extends EHCache net.sf.ehcache.loader.CacheLoader for all

new caches- no need to dene it per cache in EHCache xml cong

anymore.

Type: org.apache.camel.component.cache.CacheLoaderRegistry

Sending/Receiving Messages to/from the cache

Message Headers up to Camel 2.7

Header Description

547 CHAPTER 11 - COMPONENT APPENDIX

CACHE_OPERATION

The operation to be performed on the cache. The valid options are

▪ GET

▪ CHECK

▪ ADD

▪ UPDATE

▪ DELETE

▪ DELETEALL

The GET and CHECK requires Camel 2.3 onwards.

CACHE_KEY The cache key used to store the Message in the cache. The cache key is optional if the CACHE_OPERATION is DELETEALL

Message Headers Camel 2.8+

Header Description

CamelCacheOperation

The operation to be performed on the cache. The valid options are

▪ CamelCacheGet

▪ CamelCacheCheck

▪ CamelCacheAdd

▪ CamelCacheUpdate

▪ CamelCacheDelete

▪ CamelCacheDeleteAll

CamelCacheKey The cache key used to store the Message in the cache. The cache key is optional if the CamelCacheOperation is

CamelCacheDeleteAll

Cache Producer

Sending data to the cache involves the ability to direct payloads in

exchanges to be stored in a pre-existing or created-on-demand cache. The

mechanics of doing this involve

▪ setting the Message Exchange Headers shown above.

▪ ensuring that the Message Exchange Body contains the message

directed to the cache

Cache Consumer

Receiving data from the cache involves the ability of the CacheConsumer to

listen on a pre-existing or created-on-demand Cache using an event Listener

and receive automatic notications when any cache activity take place (i.e

CamelCacheGet/CamelCacheUpdate/CamelCacheDelete/

CamelCacheDeleteAll). Upon such an activity taking place

▪ an exchange containing Message Exchange Headers and a Message

Exchange Body containing the just added/updated payload is placed

and sent.

▪ in case of a CamelCacheDeleteAll operation, the Message Exchange

Header CamelCacheKey and the Message Exchange Body are not

populated.

CHAPTER 11 - COMPONENT APPENDIX 548

Header changes in Camel 2.8

The header names and supported values have changed to be

prexed with 'CamelCache' and use mixed case. This makes them

easier to identify and keep separate from other headers. The

CacheConstants variable names remain unchanged, just their

values have been changed. Also, these headers are now being

removed from the exchange after the cache operation is performed.

Cache Processors

There are a set of nice processors with the ability to perform cache lookups

and selectively replace payload content at the

▪ body

▪ token

▪ xpath level

Cache Usage Samples

Example 1: Conguring the cache

from("cache://MyApplicationCache" +

"?maxElementsInMemory=1000" +

"&memoryStoreEvictionPolicy=" +

"MemoryStoreEvictionPolicy.LFU" +

"&overflowToDisk=true"+

"&eternal=true"+

"&timeToLiveSeconds=300" +

"&timeToIdleSeconds=true"+

"&diskPersistent=true"+

"&diskExpiryThreadIntervalSeconds=300")

Example 2: Adding keys to the cache

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from("direct:start")

.setHeader(CacheConstants.CACHE_OPERATION,

constant(CacheConstants.CACHE_OPERATION_ADD))

.setHeader(CacheConstants.CACHE_KEY, constant("Ralph_Waldo_Emerson"))

.to("cache://TestCache1")

549 CHAPTER 11 - COMPONENT APPENDIX

}

};

Example 2: Updating existing keys in a cache

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from("direct:start")

.setHeader(CacheConstants.CACHE_OPERATION,

constant(CacheConstants.CACHE_OPERATION_UPDATE))

.setHeader(CacheConstants.CACHE_KEY, constant("Ralph_Waldo_Emerson"))

.to("cache://TestCache1")

}

};

Example 3: Deleting existing keys in a cache

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from("direct:start")

.setHeader(CacheConstants.CACHE_OPERATION, constant(CacheConstants.CACHE_DELETE))

.setHeader(CacheConstants.CACHE_KEY", constant("Ralph_Waldo_Emerson"))

.to("cache://TestCache1")

}

};

Example 4: Deleting all existing keys in a cache

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from("direct:start")

.setHeader(CacheConstants.CACHE_OPERATION,

constant(CacheConstants.CACHE_DELETEALL))

.to("cache://TestCache1");

}

};

CHAPTER 11 - COMPONENT APPENDIX 550

Example 5: Notifying any changes registering in a Cache

to Processors and other Producers

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from("cache://TestCache1")

.process(new Processor() {

public void process(Exchange exchange)

throws Exception {

String operation = (String)

exchange.getIn().getHeader(CacheConstants.CACHE_OPERATION);

String key = (String) exchange.getIn().getHeader(CacheConstants.CACHE_KEY);

Object body = exchange.getIn().getBody();

// Do something

}

})

}

};

Example 6: Using Processors to selectively replace

payload with cache values

RouteBuilder builder = new RouteBuilder() {

public void configure() {

//Message Body Replacer

from("cache://TestCache1")

.filter(header(CacheConstants.CACHE_KEY).isEqualTo("greeting"))

.process(new CacheBasedMessageBodyReplacer("cache://TestCache1","farewell"))

.to("direct:next");

//Message Token replacer

from("cache://TestCache1")

.filter(header(CacheConstants.CACHE_KEY).isEqualTo("quote"))

.process(new CacheBasedTokenReplacer("cache://TestCache1","novel","#novel#"))

.process(new CacheBasedTokenReplacer("cache://TestCache1","author","#author#"))

.process(new CacheBasedTokenReplacer("cache://TestCache1","number","#number#"))

.to("direct:next");

//Message XPath replacer

from("cache://TestCache1").

.filter(header(CacheConstants.CACHE_KEY).isEqualTo("XML_FRAGMENT"))

.process(new CacheBasedXPathReplacer("cache://TestCache1","book1","/books/book1"))

.process (new CacheBasedXPathReplacer("cache://TestCache1","book2","/books/

book2"))

.to("direct:next");

}

};

551 CHAPTER 11 - COMPONENT APPENDIX

Example 7: Getting an entry from the Cache

from("direct:start")

// Prepare headers

.setHeader(CacheConstants.CACHE_OPERATION,

constant(CacheConstants.CACHE_OPERATION_GET))

.setHeader(CacheConstants.CACHE_KEY, constant("Ralph_Waldo_Emerson")).

.to("cache://TestCache1").

// Check if entry was not found

.choice().when(header(CacheConstants.CACHE_ELEMENT_WAS_FOUND).isNull()).

// If not found, get the payload and put it to cache

.to("cxf:bean:someHeavyweightOperation").

.setHeader(CacheConstants.CACHE_OPERATION,

constant(CacheConstants.CACHE_OPERATION_ADD))

.setHeader(CacheConstants.CACHE_KEY, constant("Ralph_Waldo_Emerson"))

.to("cache://TestCache1")

.end()

.to("direct:nextPhase");

Example 8: Checking for an entry in the Cache

Note: CHECK command tests existence of the entry in the cache but doesn't

place message to the body.

from("direct:start")

// Prepare headers

.setHeader(CacheConstants.CACHE_OPERATION,

constant(CacheConstants.CACHE_OPERATION_CHECK))

.setHeader(CacheConstants.CACHE_KEY, constant("Ralph_Waldo_Emerson")).

.to("cache://TestCache1").

// Check if entry was not found

.choice().when(header(CacheConstants.CACHE_ELEMENT_WAS_FOUND).isNull()).

// If not found, get the payload and put it to cache

.to("cxf:bean:someHeavyweightOperation").

.setHeader(CacheConstants.CACHE_OPERATION,

constant(CacheConstants.CACHE_OPERATION_ADD))

.setHeader(CacheConstants.CACHE_KEY, constant("Ralph_Waldo_Emerson"))

.to("cache://TestCache1")

.end();

Management of EHCache

EHCache has its own statistics and management from JMX.

Here's a snippet on how to expose them via JMX in a Spring application

context:

CHAPTER 11 - COMPONENT APPENDIX 552

<bean id="ehCacheManagementService"

class="net.sf.ehcache.management.ManagementService" init-method="init"

lazy-init="false">

<constructor-arg>

</constructor-arg>

<constructor-arg>

<bean class="org.springframework.jmx.support.JmxUtils"

factory-method="locateMBeanServer"/>

</constructor-arg>

<constructor-arg value="true"/>

</bean>

Of course you can do the same thing in straight Java:

ManagementService.registerMBeans(CacheManager.getInstance(), mbeanServer, true,true,

true,true);

You can get cache hits, misses, in-memory hits, disk hits, size stats this way.

You can also change CacheConguration parameters on the y.

Cache replication Camel 2.8+

Camel Cache component is able to distribute cache across server nodes

using several dierent replication mechanisms like: RMI, JGroups, JMS and

Cache Server.

There are two dierent ways To make it work:

1. you need to congure ehcache.xml manually

2. you have to take care about these three options:

▪ cacheManagerFactory

▪ eventListenerRegistry

▪ cacheLoaderRegistry

Conguring Camel Cache replication using 1st option- the ehcache.xml le is

a bit hard work as you have to congure all caches separately. So in a

situation when the all names of caches are not know, using ehcache.xml is

not a good idea.

The second option is much better when you want to use many dierent

caches as you do not need to dene options per cache. This is because

replication options are set per CacheManager and per CacheEndpoint. Also it

is the only way when cache names are not know at the development phase.

553 CHAPTER 11 - COMPONENT APPENDIX

It might be useful to read EHCache manual to get better

understanding of Camel Cache replication mechanism.

Example: JMS cache replication

JMS replication is the most powerful and secured way. Used altogether with

Camel Cache replication options is also the most easy way.

This example is available on separated page.

CLASS COMPONENT

Available as of Camel 2.4

The class: component binds beans to Camel message exchanges. It works

in the same way as the Bean component but instead of looking up beans

from a Registry it creates the bean based on the class name.

URI format

class:className[?options]

Where className is the fully qualied class name to create and use as

bean.

Options

Name Type Default Description

method String null

The method name that bean will be invoked. If not provided, Camel will try to pick the

method itself. In case of ambiguity an exception is thrown. See Bean Binding for more

details.

multiParameterArray boolean false How to treat the parameters which are passed from the message body; if it is true, the In

message body should be an array of parameters.

You can append query options to the URI in the following format,

?option=value&option=value&...

Using

You simply use the class component just as the Bean component but by

specifying the fully qualied classname instead.

For example to use the MyFooBean you have to do as follows:

CHAPTER 11 - COMPONENT APPENDIX 554

from("direct:start").to("class:org.apache.camel.component.bean.MyFooBean").to("mock:result");

You can also specify which method to invoke on the MyFooBean, for example

hello:

from("direct:start").to("class:org.apache.camel.component.bean.MyFooBean?method=hello").to("mock:result");

SETTING PROPERTIES ON THE CREATED INSTANCE

In the endpoint uri you can specify properties to set on the created instance,

for example if it has a setPrefix method:

from("direct:start")

.to("class:org.apache.camel.component.bean.MyPrefixBean?prefix=Bye")

.to("mock:result");

And you can also use the #syntax to refer to properties to be looked up in

the Registry.

from("direct:start")

.to("class:org.apache.camel.component.bean.MyPrefixBean?cool=#foo")

.to("mock:result");

Which will lookup a bean from the Registry with the id foo and invoke the

setCool method on the created instance of the MyPrefixBean class.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

• Bean

• Bean Binding

• Bean Integration

COMETD COMPONENT

The cometd: component is a transport for working with the jetty

implementation of the cometd/bayeux protocol.

555 CHAPTER 11 - COMPONENT APPENDIX

See more details at the Bean component as the class component

works in much the same way.

Using this component in combination with the dojo toolkit library it's possible

to push Camel messages directly into the browser using an AJAX based

mechanism.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-cometd</artifactId>

</dependency>

URI format

cometd://host:port/channelName[?options]

The channelName represents a topic that can be subscribed to by the

Camel endpoints.

Examples

cometd://localhost:8080/service/mychannel

cometds://localhost:8443/service/mychannel

where cometds: represents an SSL congured endpoint.

See this blog entry by David Greco who contributed this component to

Apache Camel, for a full sample.

Options

Name Default

Value Description

resourceBase

The root directory for the web resources or classpath. Use the protocol le: or classpath: depending if

you want that the component loads the resource from le system or classpath. Classpath is required for

OSGI deployment where the resources are packaged in the jar. Notice this option has been renamed to

baseResource from Camel 2.7 onwards.

CHAPTER 11 - COMPONENT APPENDIX 556

baseResource

Camel 2.7: The root directory for the web resources or classpath. Use the protocol le: or classpath:

depending if you want that the component loads the resource from le system or classpath. Classpath

is required for OSGI deployment where the resources are packaged in the jar

timeout 240000 The server side poll timeout in milliseconds. This is how long the server will hold a reconnect request

before responding.

interval 0 The client side poll timeout in milliseconds. How long a client will wait between reconnects

maxInterval 30000 The max client side poll timeout in milliseconds. A client will be removed if a connection is not received

in this time.

multiFrameInterval 1500 The client side poll timeout, if multiple connections are detected from the same browser.

jsonCommented true If true, the server will accept JSON wrapped in a comment and will generate JSON wrapped in a

comment. This is a defence against Ajax Hijacking.

logLevel 1 0=none, 1=info, 2=debug.

You can append query options to the URI in the following format,

?option=value&option=value&...

Here is some examples on How to pass the parameters

For le (for webapp resources located in the Web Application directory -->

cometd://localhost:8080?resourceBase=le./webapp

For classpath (when by example the web resources are packaged inside the

webapp folder --> cometd://localhost:8080?resourceBase=classpath:webapp

Authentication

Available as of Camel 2.8

You can congure custom SecurityPolicy and Extension's to the

CometdComponent which allows you to use authentication as documented

here

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

CONTEXT COMPONENT

Available as of Camel 2.7

The context component allows you to create new Camel Components

from a CamelContext with a number of routes which is then treated as a

black box, allowing you to refer to the local endpoints within the component

from other CamelContexts.

It is similar to the Routebox component in idea, though the Context

component tries to be really simple for end users; just a simple convention

over conguration approach to refer to local endpoints inside the

CamelContext Component.

557 CHAPTER 11 - COMPONENT APPENDIX

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-context</artifactId>

</dependency>

URI format

context:camelContextId:localEndpointName[?options]

Or you can omit the "context:" prex.

camelContextId:localEndpointName[?options]

•camelContextId is the ID you used to register the CamelContext

into the Registry.

•localEndpointName can be a valid Camel URI evaluated within the

black box CamelContext. Or it can be a logical name which is

mapped to any local endpoints. For example if you locally have

endpoints like direct:invoices and seda:purchaseOrders inside a

CamelContext of id supplyChain, then you can just use the URIs

supplyChain:invoices or supplyChain:purchaseOrders to omit

the physical endpoint kind and use pure logical URIs.

You can append query options to the URI in the following format,

?option=value&option=value&...

Example

In this example we'll create a black box context, then we'll use it from

another CamelContext.

Dening the context component

First you need to create a CamelContext, add some routes in it, start it and

then register the CamelContext into the Registry (JNDI, Spring, Guice or OSGi

etc).

This can be done in the usual Camel way from this test case (see the

createRegistry() method); this example shows Java and JNDI being used...

CHAPTER 11 - COMPONENT APPENDIX 558

// lets create our black box as a camel context and a set of routes

DefaultCamelContext blackBox = new DefaultCamelContext(registry);

blackBox.setName("blackBox");

blackBox.addRoutes(new RouteBuilder() {

@Override

public void configure() throws Exception {

// receive purchase orders, lets process it in some way then send an invoice

// to our invoice endpoint

from("direct:purchaseOrder").

setHeader("received").constant("true").

to("direct:invoice");

}

});

blackBox.start();

registry.bind("accounts", blackBox);

Notice in the above route we are using pure local endpoints (direct and

seda). Also note we expose this CamelContext using the accounts ID. We

can do the same thing in Spring via

<route>

...

</route>

</camelContext>

Using the context component

Then in another CamelContext we can then refer to this "accounts black box"

by just sending to accounts:purchaseOrder and consuming from

accounts:invoice.

If you prefer to be more verbose and explicit you could use

context:accounts:purchaseOrder or even

context:accounts:direct://purchaseOrder if you prefer. But using logical

endpoint URIs is preferred as it hides the implementation detail and provides

a simple logical naming scheme.

For example if we wish to then expose this accounts black box on some

middleware (outside of the black box) we can do things like...

<route>

559 CHAPTER 11 - COMPONENT APPENDIX

</route>

<route>

</route>

</camelContext>

Naming endpoints

A context component instance can have many public input and output

endpoints that can be accessed from outside it's CamelContext. When there

are many it is recommended that you use logical names for them to hide the

middleware as shown above.

However when there is only one input, output or error/dead letter endpoint

in a component we recommend using the common posix shell names in,out

and err

CRYPTO COMPONENT FOR DIGITAL SIGNATURES

Available as of Camel 2.3

Using Camel cryptographic endpoints and Java's Cryptographic extension

it is easy to create Digital Signatures for Exchanges. Camel provides a pair of

exible endpoints which get used in concert to create a signature for an

exchange in one part of the exchange's workow and then verify the

signature in a later part of the workow.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-crypto</artifactId>

</dependency>

Introduction

Digital signatures make use Asymmetric Cryptographic techniques to sign

messages. From a (very) high level, the algorithms use pairs of

CHAPTER 11 - COMPONENT APPENDIX 560

complimentary keys with the special property that data encrypted with one

key can only be decrypted with the other. One, the private key, is closely

guarded and used to 'sign' the message while the other, public key, is shared

around to anyone interested in verifying your messages. Messages are

signed by encrypting a digest of the message with the private key. This

encrypted digest is transmitted along with the message. On the other side

the verier recalculates the message digest and uses the public key to

decrypt the the digest in the signature. If both digest match the verier

knows only the holder of the private key could have created the signature.

Camel uses the Signature service from the Java Cryptographic Extension

to do all the heavy cryptographic lifting required to create exchange

signatures. The following are some excellent sources for explaining the

mechanics of Cryptography, Message digests and Digital Signatures and how

to leverage them with the JCE.

▪ Bruce Schneier's Applied Cryptography

▪ Beginning Cryptography with Java by David Hook

▪ The ever insightful, Wikipedia Digital_signatures

URI format

As mentioned Camel provides a pair of crypto endpoints to create and verify

signatures

crypto:sign:name[?options]

crypto:verify:name[?options]

•crypto:sign creates the signature and stores it in the Header keyed

by the constant Exchange.SIGNATURE, i.e.

"CamelDigitalSignature".

•crypto:verify will read in the contents of this header and do the

verication calculation.

In order to correctly function, sign and verify need to share a pair of keys,

sign requiring a PrivateKey and verify a PublicKey (or a Certificate

containing one). Using the JCE is is very simple to generate these key pairs

but it is usually most secure to use a KeyStore to house and share your keys.

The DSL is very exible about how keys are supplied and provides a number

of mechanisms.

Note a crypto:sign endpoint is typically dened in one route and the

complimentary crypto:verify in another, though for simplicity in the

examples they appear one after the other. It goes without saying that both

sign and verify should be congured identically.

561 CHAPTER 11 - COMPONENT APPENDIX

Options

Name Type Default Description

algorithm String DSA The name of the JCE Signature algorithm that will be used.

alias String null An alias name that will be used to select a key from the keystore.

bufferSize Integer 2048 the size of the buer used in the signature process.

certificate Certificate null A Certicate used to verify the signature of the exchange's payload. Either this or a Public Key

is required.

keystore KeyStore null A reference to a JCE Keystore that stores keys and certicates used to sign and verify.

provider String null The name of the JCE Security Provider that should be used.

privateKey PrivatKey null The private key used to sign the exchange's payload.

publicKey PublicKey null The public key used to verify the signature of the exchange's payload.

secureRandom secureRandom null A reference to a SecureRandom object that wil lbe used to initialize the Signature service.

password char[] null The password for the keystore.

Using

1) Raw keys

The most basic way to way to sign an verify an exchange is with a KeyPair as

follows.

from("direct:keypair").to("crypto:sign://basic?privateKey=#myPrivateKey",

"crypto:verify://basic?publicKey=#myPublicKey", "mock:result");

The same can be achieved with the Spring XML Extensions using references

to keys

<route>

</route>

2) KeyStores and Aliases.

The JCE provides a very versatile KeyStore for housing pairs of PrivateKeys

and Certicates keeping them encrypted and password protected. They can

be retrieved from it by applying an alias to the retrieval apis. There are a

number of ways to get keys and Certicates into a keystore most often this is

done with the external 'keytool' application. This is a good example of using

keytool to create a KeyStore with a self signed Cert and Private key.

CHAPTER 11 - COMPONENT APPENDIX 562

The examples use a Keystore with a key and cert aliased by 'bob'. The

password for the keystore and the key is 'letmein'

The following shows how to use a Keystore via the Fluent builders, it also

shows how to load and initialize the keystore.

from("direct:keystore").to("crypto:sign://keystore?keystore=#keystore&alias=bob&password=letmein",

"crypto:verify://keystore?keystore=#keystore&alias=bob", "mock:result");

Again in Spring a ref is used to lookup an actual keystore instance.

<route>

<to

uri="crypto:sign://keystore?keystore=#keystore&alias=bob&password=letmein" />

</route>

3) Changing JCE Provider and Algorithm

Changing the Signature algorithm or the Security provider is a simple matter

of specifying their names. You will need to also use Keys that are compatible

with the algorithm you choose.

KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSA");

keyGen.initialize(512, new SecureRandom());

keyPair = keyGen.generateKeyPair();

PrivateKey privateKey = keyPair.getPrivate();

PublicKey publicKey = keyPair.getPublic();

// we can set the keys explicitly on the endpoint instances.

context.getEndpoint("crypto:sign://rsa?algorithm=MD5withRSA",

DigitalSignatureEndpoint.class).setPrivateKey(privateKey);

context.getEndpoint("crypto:verify://rsa?algorithm=MD5withRSA",

DigitalSignatureEndpoint.class).setPublicKey(publicKey);

from("direct:algorithm").to("crypto:sign://rsa?algorithm=MD5withRSA",

"crypto:verify://rsa?algorithm=MD5withRSA", "mock:result");

from("direct:provider").to("crypto:sign://provider?privateKey=#myPrivateKey&provider=SUN",

"crypto:verify://provider?publicKey=#myPublicKey&provider=SUN", "mock:result");

<route>

563 CHAPTER 11 - COMPONENT APPENDIX

</route>

<route>

</route>

4) Changing the Signature Mesasge Header

It may be desirable to change the message header used to store the

signature. A dierent header name can be specied in the route denition as

follows

from("direct:signature-header").to("crypto:sign://another?privateKey=#myPrivateKey&signatureHeader=AnotherDigitalSignature",

"crypto:verify://another?publicKey=#myPublicKey&signatureHeader=AnotherDigitalSignature",

"mock:result");

<route>

<to

uri="crypto:sign://another?privateKey=#myPrivateKey&signatureHeader=AnotherDigitalSignature"

<to

uri="crypto:verify://another?publicKey=#myPublicKey&signatureHeader=AnotherDigitalSignature"

</route>

5) Changing the buersize

In case you need to update the size of the buer...

from("direct:buffersize").to("crypto:sign://buffer?privateKey=#myPrivateKey&buffersize=1024",

"crypto:verify://buffer?publicKey=#myPublicKey&buffersize=1024", "mock:result");

CHAPTER 11 - COMPONENT APPENDIX 564

<route>

</route>

6) Supplying Keys dynamically.

When using a Recipient list or similar EIP the recipient of an exchange can

vary dynamically. Using the same key across all recipients may neither be

feasible or desirable. It would be useful to be able to specify the signature

keys dynamically on a per exchange basis. The exchange could then be

dynamically enriched with the key of its target recipient prior to signing. To

facilitate this the signature mechanisms allow for keys to be supplied

dynamically via the message headers below

•Exchange.SIGNATURE_PRIVATE_KEY,"CamelSignaturePrivateKey"

•Exchange.SIGNATURE_PUBLIC_KEY_OR_CERT,

"CamelSignaturePublicKeyOrCert"

from("direct:headerkey-sign").to("crypto:sign://alias");

from("direct:headerkey-verify").to("crypto:verify://alias", "mock:result");

<route>

</route>

<route>

</route>

Better again would be to dynamically supply a keystore alias. Again the alias

can be supplied in a message header

•Exchange.KEYSTORE_ALIAS,"CamelSignatureKeyStoreAlias"

from("direct:alias-sign").to("crypto:sign://alias?keystore=#keystore");

from("direct:alias-verify").to("crypto:verify://alias?keystore=#keystore",

"mock:result");

565 CHAPTER 11 - COMPONENT APPENDIX

<route>

</route>

<route>

</route>

The header would be set as follows

Exchange unsigned = getMandatoryEndpoint("direct:alias-sign").createExchange();

unsigned.getIn().setBody(payload);

unsigned.getIn().setHeader(DigitalSignatureConstants.KEYSTORE_ALIAS, "bob");

unsigned.getIn().setHeader(DigitalSignatureConstants.KEYSTORE_PASSWORD,

"letmein".toCharArray());

template.send("direct:alias-sign", unsigned);

Exchange signed = getMandatoryEndpoint("direct:alias-sign").createExchange();

signed.getIn().copyFrom(unsigned.getOut());

signed.getIn().setHeader(KEYSTORE_ALIAS, "bob");

template.send("direct:alias-verify", signed);

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

• Crypto Crypto is also available as a Data Format

CXF COMPONENT

The cxf: component provides integration with Apache CXF for connecting to

JAX-WS services hosted in CXF.

• CXF Component

• URI format

• Options

• The descriptions of the dataformats

• How to enable CXF's LoggingOutInterceptor in MESSAGE mode

• Description of relayHeaders option

• Available in Release 1.6.1 and after (only in POJO mode)

• Changes since Release 2.0

• Congure the CXF endpoints with Spring

• Conguring the CXF Endpoints with Apache Aries Blueprint.

CHAPTER 11 - COMPONENT APPENDIX 566

When using CXF as a consumer, the CXF Bean Component allows

you to factor out how message payloads are received from their

processing as a RESTful or SOAP web service. This has the potential

of using a multitude of transports to consume web services. The

bean component's conguration is also simpler and provides the

fastest method to implement web services using Camel and CXF.

• How to make the camel-cxf component use log4j instead of

java.util.logging

• How to let camel-cxf response message with xml start document

• How to consume a message from a camel-cxf endpoint in POJO data

format

• How to prepare the message for the camel-cxf endpoint in POJO data

format

• How to deal with the message for a camel-cxf endpoint in PAYLOAD

data format

• How to get and set SOAP headers in POJO mode

• How to get and set SOAP headers in PAYLOAD mode

• SOAP headers are not available in MESSAGE mode

• How to throw a SOAP Fault from Camel

• How to propagate a camel-cxf endpoint's request and response

context

• Attachment Support

• Streaming Support in PAYLOAD mode

• See Also

Maven users will need to add the following dependency to their pom.xml for

this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-cxf</artifactId>

</dependency>

URI format

cxf:bean:cxfEndpoint[?options]

567 CHAPTER 11 - COMPONENT APPENDIX

CXF dependencies

If you want to learn about CXF dependencies you can checkout the

WHICH-JARS text le.

Where cxfEndpoint represents a bean ID that references a bean in the

Spring bean registry. With this URI format, most of the endpoint details are

specied in the bean denition.

cxf://someAddress[?options]

Where someAddress species the CXF endpoint's address. With this URI

format, most of the endpoint details are specied using options.

For either style above, you can append options to the URI as follows:

cxf:bean:cxfEndpoint?wsdlURL=wsdl/hello_world.wsdl&dataFormat=PAYLOAD

Options

Name Required Description

wsdlURL No

The location of the WSDL. It is obtained from endpoint address by default.

Example: le://local/wsdl/hello.wsdl or wsdl/hello.wsdl

serviceClass Yes

The name of the SEI (Service Endpoint Interface) class. This class can have, but does not

require, JSR181 annotations.

Since 2.0, this option is only required by POJO mode. If the wsdlURL option is provided,

serviceClass is not required for PAYLOAD and MESSAGE mode. When wsdlURL option is used

without serviceClass, the serviceName and portName (endpointName for Spring

conguration) options MUST be provided. It is possible to use #notation to reference a

serviceClass object instance from the registry. E.g. serviceClass=#beanName.

Since 2.8, it is possible to omit both wsdlURL and serviceClass options for PAYLOAD and

MESSAGE mode. When they are omitted, arbitrary XML elements can be put in CxfPayload's

body in PAYLOAD mode to facilitate CXF Dispatch Mode.

Please be advised that the referenced object cannot be a Proxy (Spring AOP Proxy is

OK) as it relies on Object.getClass().getName() method for non Spring AOP Proxy.

Example:org.apache.camel.Hello

serviceClassInstance No

Use either serviceClass or serviceClassInstance.

Deprecated in 2.x. In 1.6.x serviceClassInstance works like serviceClass=#beanName,

which looks up a serviceObject instance from the registry.

Example:serviceClassInstance=beanName

serviceName No

The service name this service is implementing, it maps to the wsdl:service@name.

Required for camel-cxf consumer since camel-2.2.0 or if more than one serviceName is

present in WSDL.

Example: {http://org.apache.camel}ServiceName

portName No

The port name this service is implementing, it maps to the wsdl:port@name.

Required for camel-cxf consumer since camel-2.2.0 or if more than one portName is

present under serviceName.

Example: {http://org.apache.camel}PortName

CHAPTER 11 - COMPONENT APPENDIX 568

dataFormat No

The data type messages supported by the CXF endpoint.

Default:POJO

Example:POJO,PAYLOAD,MESSAGE

relayHeaders No

Available since 1.6.1. Please see the Description of relayHeaders option section for this

option in 2.0. Should a CXF endpoint relay headers along the route. Currently only available

when dataFormat=POJO

Default:true

Example:true,false

wrapped No

Which kind of operation that CXF endpoint producer will invoke

Default:false

Example:true,false

wrappedStyle No

New in 2.5.0 The WSDL style that describes how parameters are represented in the SOAP

body. If the value is false, CXF will chose the document-literal unwrapped style, If the value

is true, CXF will chose the document-literal wrapped style

Default:Null

Example:true,false

setDefaultBus No

Will set the default bus when CXF endpoint create a bus by itself

Default:false

Example:true,false

bus No

New in 2.0.0. A default bus created by CXF Bus Factory. Use #notation to reference a bus

object from the registry. The referenced object must be an instance of org.apache.cxf.Bus.

Example:bus=#busName

cxfBinding No

New in 2.0. Use #notation to reference a CXF binding object from the registry. The

referenced object must be an instance of org.apache.camel.component.cxf.CxfBinding

(use an instance of org.apache.camel.component.cxf.DefaultCxfBinding).

Example:cxfBinding=#bindingName

headerFilterStrategy No

New in 2.0. Use #notation to reference a header lter strategy object from the registry. The

referenced object must be an instance of org.apache.camel.spi.HeaderFilterStrategy

(use an instance of org.apache.camel.component.cxf.CxfHeaderFilterStrategy).

Example:headerFilterStrategy=#strategyName

loggingFeatureEnabled No

New in 2.3. This option enables CXF Logging Feature which writes inbound and outbound

SOAP messages to log.

Default:false

Example:loggingFeatureEnabled=true

defaultOperationName No

New in 2.4, this option will set the default operationName that will be used by the

CxfProducer which invokes the remote service.

Default:null

Example:defaultOperationName=greetMe

defaultOperationNamespace No

New in 2.4. This option will set the default operationNamespace that will be used by the

CxfProducer which invokes the remote service.

Default:null

Example:defaultOperationNamespace=http://apache.org/hello_world_soap_http

synchronous No

New in 2.5. This option will let cxf endpoint decide to use sync or async API to do the

underlying work. The default value is false which means camel-cxf endpoint will try to use

async API by default.

Default:false

Example: synchronous=true

publishedEndpointUrl No

New in 2.5. This option can override the endpointUrl that published from the WSDL which

can be accessed with service address url plus ?wsdl.

Default:null

Example: publshedEndpointUrl=http://example.com/service

properties.XXX No Camel 2.8: Allows to set custom properties to CXF in the endpoint uri. For example setting

properties.mtom-enabled=true to enable MTOM.

allowStreaming No

New in 2.8.2. This option controls whether the CXF component, when running in PAYLOAD

mode (see below), will DOM parse the incoming messages into DOM Elements or keep the

payload as a javax.xml.transform.Source object that would allow streaming in some cases.

The serviceName and portName are QNames, so if you provide them be sure

to prex them with their {namespace} as shown in the examples above.

569 CHAPTER 11 - COMPONENT APPENDIX

NOTE From CAMEL 1.5.1 , the serviceClass for a CXF producer (that is,

the to endpoint) should be a Java interface.

The descriptions of the dataformats

DataFormat Description

POJO POJOs (Plain old Java objects) are the Java parameters to the method being invoked on the target server. Both Protocol

and Logical JAX-WS handlers are supported.

PAYLOAD PAYLOAD is the message payload (the contents of the soap:body) after message conguration in the CXF endpoint is

applied. Only Protocol JAX-WS handler is supported. Logical JAX-WS handler is not supported.

MESSAGE MESSAGE is the raw message that is received from the transport layer. It is not suppose to touch or change Stream, so

you can't see any soap headers after the camel-cxf consumer and JAX-WS handler is not supported.

You can determine the data format mode of an exchange by retrieving the

exchange property, CamelCXFDataFormat. The exchange key constant is

dened in

org.apache.camel.component.cxf.CxfConstants.DATA_FORMAT_PROPERTY.

How to enable CXF's LoggingOutInterceptor in MESSAGE mode

CXF's LoggingOutInterceptor outputs outbound message that goes on the

wire to logging system (Java Util Logging). Since the

LoggingOutInterceptor is in PRE_STREAM phase (but PRE_STREAM phase is

removed in MESSAGE mode), you have to congure LoggingOutInterceptor

to be run during the WRITE phase. The following is an example.

<bean id="loggingOutInterceptor"

class="org.apache.cxf.interceptor.LoggingOutInterceptor">

<!-- it really should have been user-prestream but CXF does have such phase!

-->

<constructor-arg value="write"/>

</bean>

<cxf:cxfEndpoint id="serviceEndpoint"

address="http://localhost:${CXFTestSupport.port2}/LoggingInterceptorInMessageModeTest/

helloworld"

serviceClass="org.apache.camel.component.cxf.HelloService">

<cxf:outInterceptors>

</cxf:outInterceptors>

<cxf:properties>

</cxf:properties>

</cxf:cxfEndpoint>

CHAPTER 11 - COMPONENT APPENDIX 570

Description of relayHeaders option

There are in-band and out-of-band on-the-wire headers from the perspective

of a JAXWS WSDL-rst developer.

The in-band headers are headers that are explicitly dened as part of the

WSDL binding contract for an endpoint such as SOAP headers.

The out-of-band headers are headers that are serialized over the wire, but

are not explicitly part of the WSDL binding contract.

Headers relaying/ltering is bi-directional.

When a route has a CXF endpoint and the developer needs to have on-the-

wire headers, such as SOAP headers, be relayed along the route to be

consumed say by another JAXWS endpoint, then relayHeaders should be set

to true, which is the default value.

Available in Release 1.6.1 and after (only in POJO mode)

The relayHeaders=true express an intent to relay the headers. The actual

decision on whether a given header is relayed is delegated to a pluggable

instance that implements the MessageHeadersRelay interface. A concrete

implementation of MessageHeadersRelay will be consulted to decide if a

header needs to be relayed or not. There is already an implementation of

SoapMessageHeadersRelay which binds itself to well-known SOAP name

spaces. Currently only out-of-band headers are ltered, and in-band headers

will always be relayed when relayHeaders=true. If there is a header on the

wire, whose name space is unknown to the runtime, then a fall back

DefaultMessageHeadersRelay will be used, which simply allows all headers

to be relayed.

The relayHeaders=false setting asserts that all headers in-band and out-

of-band will be dropped.

You can plugin your own MessageHeadersRelay implementations

overriding or adding additional ones to the list of relays. In order to override

a preloaded relay instance just make sure that your MessageHeadersRelay

implementation services the same name spaces as the one you looking to

override. Also note, that the overriding relay has to service all of the name

spaces as the one you looking to override, or else a runtime exception on

route start up will be thrown as this would introduce an ambiguity in name

spaces to relay instance mappings.

<cxf:cxfEndpoint ...>

<cxf:properties>

<list>

571 CHAPTER 11 - COMPONENT APPENDIX

</list>

</entry>

</cxf:properties>

</cxf:cxfEndpoint>

<bean id="customHeadersRelay"

class="org.apache.camel.component.cxf.soap.headers.CustomHeadersRelay"/>

Take a look at the tests that show how you'd be able to relay/drop headers

here:

https://svn.apache.org/repos/asf/camel/branches/camel-1.x/components/

camel-cxf/src/test/java/org/apache/camel/component/cxf/soap/headers/

CxfMessageHeadersRelayTest.java

Changes since Release 2.0

•POJO and PAYLOAD modes are supported. In POJO mode, only out-of-

band message headers are available for ltering as the in-band

headers have been processed and removed from header list by CXF.

The in-band headers are incorporated into the MessageContentList

in POJO mode. The camel-cxf component does make any attempt to

remove the in-band headers from the MessageContentList as it

does in 1.6.1. If ltering of in-band headers is required, please use

PAYLOAD mode or plug in a (pretty straightforward) CXF interceptor/

JAXWS Handler to the CXF endpoint.

• The Message Header Relay mechanism has been merged into

CxfHeaderFilterStrategy. The relayHeaders option, its semantics,

and default value remain the same, but it is a property of

CxfHeaderFilterStrategy.

Here is an example of conguring it.

<bean id="dropAllMessageHeadersStrategy"

class="org.apache.camel.component.cxf.common.header.CxfHeaderFilterStrategy">

</bean>

Then, your endpoint can reference the CxfHeaderFilterStrategy.

<route>

<from

uri="cxf:bean:routerNoRelayEndpoint?headerFilterStrategy=#dropAllMessageHeadersStrategy"/>

<to

CHAPTER 11 - COMPONENT APPENDIX 572

uri="cxf:bean:serviceNoRelayEndpoint?headerFilterStrategy=#dropAllMessageHeadersStrategy"/>

</route>

• The MessageHeadersRelay interface has changed slightly and has

been renamed to MessageHeaderFilter. It is a property of

CxfHeaderFilterStrategy. Here is an example of conguring user

dened Message Header Filters:

<bean id="customMessageFilterStrategy"

class="org.apache.camel.component.cxf.common.header.CxfHeaderFilterStrategy">

<list>

<!-- SoapMessageHeaderFilter is the built in filter. It can be

removed by omitting it. -->

<bean

class="org.apache.camel.component.cxf.common.header.SoapMessageHeaderFilter"/>

<bean

class="org.apache.camel.component.cxf.soap.headers.CustomHeaderFilter"/>

</list>

</property>

</bean>

• Other than relayHeaders, there are new properties that can be

congured in CxfHeaderFilterStrategy.

Name Required Description

relayHeaders No

All message headers will be processed by Message Header Filters

Type:boolean

Default:true (1.6.1 behavior)

relayAllMessageHeaders No

All message headers will be propagated (without processing by Message

Header Filters)

Type:boolean

Default:false (1.6.1 behavior)

allowFilterNamespaceClash No

If two lters overlap in activation namespace, the property control how it

should be handled. If the value is true, last one wins. If the value is false, it

will throw an exception

Type:boolean

Default:false (1.6.1 behavior)

Congure the CXF endpoints with Spring

You can congure the CXF endpoint with the Spring conguration le

shown below, and you can also embed the endpoint into the

camelContext tags. When you are invoking the service endpoint, you

can set the operationName and operationNameSpace headers to

explicitly state which operation you are calling.

573 CHAPTER 11 - COMPONENT APPENDIX

<beans xmlns="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:cxf="http://activemq.apache.org/camel/schema/cxfEndpoint"

xsi:schemaLocation="

http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans-2.0.xsd

http://activemq.apache.org/camel/schema/cxfEndpoint

http://activemq.apache.org/camel/schema/cxf/camel-cxf-1.6.0.xsd

http://activemq.apache.org/camel/schema/spring

http://activemq.apache.org/camel/schema/spring/camel-spring.xsd ">

<cxf:cxfEndpoint id="routerEndpoint" address="http://localhost:9003/

CamelContext/RouterPort"

serviceClass="org.apache.hello_world_soap_http.GreeterImpl"/>

<cxf:cxfEndpoint id="serviceEndpoint" address="http://localhost:9000/

SoapContext/SoapPort"

wsdlURL="testutils/hello_world.wsdl"

serviceClass="org.apache.hello_world_soap_http.Greeter"

endpointName="s:SoapPort"

serviceName="s:SOAPService"

xmlns:s="http://apache.org/hello_world_soap_http" />

<camelContext id="camel" xmlns="http://activemq.apache.org/camel/schema/

spring">

<route>

</route>

</camelContext>

</beans>

NOTE In Camel 2.x we change to use {{http://camel.apache.org/

schema/cxf}} as the CXF endpoint's target namespace.

<beans xmlns="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:cxf="http://camel.apache.org/schema/cxf"

xsi:schemaLocation="

http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans-2.0.xsd

http://camel.apache.org/schema/cxf http://camel.apache.org/schema/

cxf/camel-cxf.xsd

http://camel.apache.org/schema/spring http://camel.apache.org/schema/

spring/camel-spring.xsd ">

...

Be sure to include the JAX-WS schemaLocation attribute specied on

the root beans element. This allows CXF to validate the le and is

required. Also note the namespace declarations at the end of the

<cxf:cxfEndpoint/> tag--these are required because the combined

{namespace}localName syntax is presently not supported for this

tag's attribute values.

CHAPTER 11 - COMPONENT APPENDIX 574

The cxf:cxfEndpoint element supports many additional

attributes:

Name Value

PortName The endpoint name this service is implementing, it maps to the wsdl:port@name. In the format of ns:PORT_NAME

where ns is a namespace prex valid at this scope.

serviceName The service name this service is implementing, it maps to the wsdl:service@name. In the format of

ns:SERVICE_NAME where ns is a namespace prex valid at this scope.

wsdlURL The location of the WSDL. Can be on the classpath, le system, or be hosted remotely.

bindingId The bindingId for the service model to use.

address The service publish address.

bus The bus name that will be used in the JAX-WS endpoint.

serviceClass The class name of the SEI (Service Endpoint Interface) class which could have JSR181 annotation or not.

It also supports many child elements:

Name Value

cxf:inInterceptors The incoming interceptors for this endpoint. A list of <bean> or <ref>.

cxf:inFaultInterceptors The incoming fault interceptors for this endpoint. A list of <bean> or <ref>.

cxf:outInterceptors The outgoing interceptors for this endpoint. A list of <bean> or <ref>.

cxf:outFaultInterceptors The outgoing fault interceptors for this endpoint. A list of <bean> or <ref>.

cxf:properties A properties map which should be supplied to the JAX-WS endpoint. See below.

cxf:handlers A JAX-WS handler list which should be supplied to the JAX-WS endpoint. See below.

cxf:dataBinding You can specify the which DataBinding will be use in the endpoint. This can be supplied using the

Spring <bean class="MyDataBinding"/> syntax.

cxf:binding You can specify the BindingFactory for this endpoint to use. This can be supplied using the

Spring <bean class="MyBindingFactory"/> syntax.

cxf:features The features that hold the interceptors for this endpoint. A list of {{<bean>}}s or {{<ref>}}s

cxf:schemaLocations The schema locations for endpoint to use. A list of {{<schemaLocation>}}s

cxf:serviceFactory The service factory for this endpoint to use. This can be supplied using the Spring <bean

class="MyServiceFactory"/> syntax

You can nd more advanced examples which show how to provide

interceptors , properties and handlers here:

http://cwiki.apache.org/CXF20DOC/jax-ws-conguration.html

NOTE

You can use cxf:properties to set the camel-cxf endpoint's dataFormat and

setDefaultBus properties from spring conguration le.

<cxf:cxfEndpoint id="testEndpoint" address="http://localhost:9000/router"

serviceClass="org.apache.camel.component.cxf.HelloService"

endpointName="s:PortName"

serviceName="s:ServiceName"

xmlns:s="http://www.example.com/test">

<cxf:properties>

</cxf:properties>

</cxf:cxfEndpoint>

575 CHAPTER 11 - COMPONENT APPENDIX

Conguring the CXF Endpoints with Apache Aries Blueprint.

Since camel 2.8 there is support for utilizing aries blueprint dependency

injection for your CXF endpoints.

The schema utilized is very similar to the spring schema so the transition is

fairly transparent.

Example

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0"

xmlns:camel-cxf="http://camel.apache.org/schema/blueprint/cxf"

xmlns:cxfcore="http://cxf.apache.org/blueprint/core"

xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0

http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd">

<camel-cxf:cxfEndpoint id="routerEndpoint"

address="http://localhost:9001/router"

serviceClass="org.apache.servicemix.examples.cxf.HelloWorld">

<camel-cxf:properties>

</camel-cxf:properties>

</camel-cxf:cxfEndpoint>

<camel-cxf:cxfEndpoint id="serviceEndpoint"

address="http://localhost:9000/SoapContext/SoapPort"

serviceClass="org.apache.servicemix.examples.cxf.HelloWorld">

</camel-cxf:cxfEndpoint>

<route>

</route>

</camelContext>

</blueprint>

Currently the endpoint element is the rst supported CXF namespacehandler.

You can also use the bean references just as in spring

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0"

xmlns:jaxws="http://cxf.apache.org/blueprint/jaxws"

xmlns:cxf="http://cxf.apache.org/blueprint/core"

xmlns:camel="http://camel.apache.org/schema/blueprint"

xmlns:camelcxf="http://camel.apache.org/schema/blueprint/cxf"

CHAPTER 11 - COMPONENT APPENDIX 576

xsi:schemaLocation="

http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/

blueprint/v1.0.0/blueprint.xsd

http://cxf.apache.org/blueprint/jaxws http://cxf.apache.org/schemas/

blueprint/jaxws.xsd

http://cxf.apache.org/blueprint/core http://cxf.apache.org/schemas/

blueprint/core.xsd

<camelcxf:cxfEndpoint id="reportIncident"

address="/camel-example-cxf-blueprint/webservices/incident"

wsdlURL="META-INF/wsdl/report_incident.wsdl"

serviceClass="org.apache.camel.example.reportincident.ReportIncidentEndpoint">

</camelcxf:cxfEndpoint>

<bean id="reportIncidentRoutes"

class="org.apache.camel.example.reportincident.ReportIncidentRoutes" />

</camelContext>

</blueprint>

How to make the camel-cxf component use log4j instead of

java.util.logging

CXF's default logger is java.util.logging. If you want to change it to log4j,

proceed as follows. Create a le, in the classpath, named META-INF/cxf/

org.apache.cxf.logger. This le should contain the fully-qualied name of

the class, org.apache.cxf.common.logging.Log4jLogger, with no

comments, on a single line.

How to let camel-cxf response message with xml start document

If you are using some soap client such as PHP, you will get this kind of error,

because CXF doesn't add the XML start document "<?xml version="1.0"

encoding="utf-8"?>"

Error:sendSms: SoapFault exception: [Client] looks like we got no XML document in

[...]

To resolved this issue, you just need to tell StaxOutInterceptor to write the

XML start document for you.

577 CHAPTER 11 - COMPONENT APPENDIX

public class WriteXmlDeclarationInterceptor extends

AbstractPhaseInterceptor<SoapMessage> {

public WriteXmlDeclarationInterceptor() {

super(Phase.PRE_STREAM);

addBefore(StaxOutInterceptor.class.getName());

}

public void handleMessage(SoapMessage message) throws Fault {

message.put("org.apache.cxf.stax.force-start-document", Boolean.TRUE);

}

You can add a customer interceptor like this and congure it into you camel-

cxf endpont

<cxf:cxfEndpoint id="routerEndpoint"

address="http://localhost:${CXFTestSupport.port2}/CXFGreeterRouterTest/CamelContext/

RouterPort"

serviceClass="org.apache.hello_world_soap_http.GreeterImpl">

<cxf:outInterceptors>

<!-- This interceptor will force the CXF server send the XML start document

to client -->

</cxf:outInterceptors>

<cxf:properties>

<!-- Set the publishedEndpointUrl which could override the service address

from generated WSDL as you want -->

<entry key="publishedEndpointUrl" value="http://www.simple.com/services/

test" />

</cxf:properties>

</cxf:cxfEndpoint>

Or adding a message header for it like this if you are using Camel 2.4.

// set up the response context which force start document

Map<String,Object> map = new HashMap<String,Object>();

map.put("org.apache.cxf.stax.force-start-document",Boolean.TRUE);

exchange.getOut().setHeader(Client.RESPONSE_CONTEXT, map);

How to consume a message from a camel-cxf endpoint in POJO data

format

The camel-cxf endpoint consumer POJO data format is based on the cxf

invoker, so the message header has a property with the name of

CxfConstants.OPERATION_NAME and the message body is a list of the SEI

method parameters.

CHAPTER 11 - COMPONENT APPENDIX 578

public class PersonProcessor implements Processor {

private static final transient Logger LOG =

LoggerFactory.getLogger(PersonProcessor.class);

@SuppressWarnings("unchecked")

public void process(Exchange exchange) throws Exception {

LOG.info("processing exchange in camel");

BindingOperationInfo boi =

(BindingOperationInfo)exchange.getProperty(BindingOperationInfo.class.toString());

if (boi != null) {

LOG.info("boi.isUnwrapped" + boi.isUnwrapped());

}

// Get the parameters list which element is the holder.

MessageContentsList msgList = (MessageContentsList)exchange.getIn().getBody();

Holder<String> personId = (Holder<String>)msgList.get(0);

Holder<String> ssn = (Holder<String>)msgList.get(1);

Holder<String> name = (Holder<String>)msgList.get(2);

if (personId.value == null || personId.value.length() == 0) {

LOG.info("person id 123, so throwing exception");

// Try to throw out the soap fault message

org.apache.camel.wsdl_first.types.UnknownPersonFault personFault =

new org.apache.camel.wsdl_first.types.UnknownPersonFault();

personFault.setPersonId("");

org.apache.camel.wsdl_first.UnknownPersonFault fault =

new org.apache.camel.wsdl_first.UnknownPersonFault("Get the null

value of person name", personFault);

// Since camel has its own exception handler framework, we can't throw

the exception to trigger it

// We just set the fault message in the exchange for camel-cxf component

handling and return

exchange.getOut().setFault(true);

exchange.getOut().setBody(fault);

return;

}

name.value = "Bonjour";

ssn.value = "123";

LOG.info("setting Bonjour as the response");

// Set the response message, first element is the return value of the

operation,

// the others are the holders of method parameters

exchange.getOut().setBody(new Object[] {null, personId, ssn, name});

}

579 CHAPTER 11 - COMPONENT APPENDIX

How to prepare the message for the camel-cxf endpoint in POJO

data format

The camel-cxf endpoint producer is based on the cxf client API. First you

need to specify the operation name in the message header, then add the

method parameters to a list, and initialize the message with this parameter

list. The response message's body is a messageContentsList, you can get the

result from that list.

NOTE After Camel 1.5 , we change the message body from object array to

message content list. If you still want to get the object array from the

message body, you can get the body using

message.getbody(Object[].class), as follows:

Exchange senderExchange = new DefaultExchange(context, ExchangePattern.InOut);

final List<String> params = new ArrayList<String>();

// Prepare the request message for the camel-cxf procedure

params.add(TEST_MESSAGE);

senderExchange.getIn().setBody(params);

senderExchange.getIn().setHeader(CxfConstants.OPERATION_NAME, ECHO_OPERATION);

Exchange exchange = template.send("direct:EndpointA", senderExchange);

org.apache.camel.Message out = exchange.getOut();

// The response message's body is an MessageContentsList which first element is the

return value of the operation,

// If there are some holder parameters, the holder parameter will be filled in the

reset of List.

// The result will be extract from the MessageContentsList with the String class type

MessageContentsList result = (MessageContentsList)out.getBody();

LOG.info("Received output text: " + result.get(0));

Map<String,Object> responseContext =

CastUtils.cast((Map)out.getHeader(Client.RESPONSE_CONTEXT));

assertNotNull(responseContext);

assertEquals("We should get the response context here","UTF-8",

responseContext.get(org.apache.cxf.message.Message.ENCODING));

assertEquals("Reply body on Camel is wrong","echo " + TEST_MESSAGE, result.get(0));

How to deal with the message for a camel-cxf endpoint in PAYLOAD

data format

PAYLOAD means that you process the payload message from the SOAP

envelope. You can use the Header.HEADER_LIST as the key to set or get the

SOAP headers and use the List<Element> to set or get SOAP body elements.

Camel 1.x branch, you can get the List<Element> and header from the CXF

Message, but if you want to set the response message, you need to create

the CXF message using the CXF API.

CHAPTER 11 - COMPONENT APPENDIX 580

protected RouteBuilder createRouteBuilder() {

return new RouteBuilder() {

public void configure() {

from(SIMPLE_ENDPOINT_URI +

"&dataFormat=PAYLOAD").to("log:info").process(new Processor() {

public void process(final Exchange exchange) throws Exception {

Message inMessage = exchange.getIn();

if (inMessage instanceof CxfMessage) {

CxfMessage cxfInMessage = (CxfMessage) inMessage;

CxfMessage cxfOutMessage = (CxfMessage) exchange.getOut();

List<Element> inElements =

cxfInMessage.getMessage().get(List.class);

List<Element> outElements = new ArrayList<Element>();

XmlConverter converter = new XmlConverter();

String documentString = ECHO_RESPONSE;

if (inElements.get(0).getLocalName().equals("echoBoolean")) {

documentString = ECHO_BOOLEAN_RESPONSE;

}

org.apache.cxf.message.Exchange ex =

((CxfExchange)exchange).getExchange();

Endpoint ep = ex.get(Endpoint.class);

org.apache.cxf.message.Message response =

ep.getBinding().createMessage();

Document outDocument =

converter.toDOMDocument(documentString);

outElements.add(outDocument.getDocumentElement());

response.put(List.class, outElements);

cxfOutMessage.setMessage(response);

}

});

}

};

}

Change in 2.0, There is no more CxfMessage, we just use the common

Camel DefaultMessageImpl under layer. Message.getBody() will return an

org.apache.camel.component.cxf.CxfPayload object, which has getters

for SOAP message headers and Body elements. This change enables

decoupling the native CXF message from the Camel message.

protected RouteBuilder createRouteBuilder() {

return new RouteBuilder() {

public void configure() {

from(simpleEndpointURI +

"&dataFormat=PAYLOAD").to("log:info").process(new Processor() {

@SuppressWarnings("unchecked")

public void process(final Exchange exchange) throws Exception {

CxfPayload<SoapHeader> requestPayload =

exchange.getIn().getBody(CxfPayload.class);

581 CHAPTER 11 - COMPONENT APPENDIX

List<Source> inElements = requestPayload.getBodySources();

List<Source> outElements = new ArrayList<Source>();

// You can use a customer toStringConverter to turn a CxfPayLoad

message into String as you want

String request = exchange.getIn().getBody(String.class);

XmlConverter converter = new XmlConverter();

String documentString = ECHO_RESPONSE;

Element in = new XmlConverter().toDOMElement(inElements.get(0));

// Just check the element namespace

if (!in.getNamespaceURI().equals(ELEMENT_NAMESPACE)) {

throw new IllegalArgumentException("Wrong element namespace");

}

if (in.getLocalName().equals("echoBoolean")) {

documentString = ECHO_BOOLEAN_RESPONSE;

checkRequest("ECHO_BOOLEAN_REQUEST", request);

}else {

documentString = ECHO_RESPONSE;

checkRequest("ECHO_REQUEST", request);

}

Document outDocument = converter.toDOMDocument(documentString);

outElements.add(new DOMSource(outDocument.getDocumentElement()));

// set the payload header with null

CxfPayload<SoapHeader> responsePayload = new

CxfPayload<SoapHeader>(null, outElements, null);

exchange.getOut().setBody(responsePayload);

}

});

}

};

}

How to get and set SOAP headers in POJO mode

POJO means that the data format is a "list of Java objects" when the Camel-

cxf endpoint produces or consumes Camel exchanges. Even though Camel

expose message body as POJOs in this mode, Camel-cxf still provides access

to read and write SOAP headers. However, since CXF interceptors remove in-

band SOAP headers from Header list after they have been processed, only

out-of-band SOAP headers are available to Camel-cxf in POJO mode.

The following example illustrate how to get/set SOAP headers. Suppose we

have a route that forwards from one Camel-cxf endpoint to another. That is,

SOAP Client -> Camel -> CXF service. We can attach two processors to

obtain/insert SOAP headers at (1) before request goes out to the CXF service

and (2) before response comes back to the SOAP Client. Processor (1) and (2)

in this example are InsertRequestOutHeaderProcessor and

InsertResponseOutHeaderProcessor. Our route looks like this:

CHAPTER 11 - COMPONENT APPENDIX 582

<route>

</route>

In 2.x SOAP headers are propagated to and from Camel Message headers.

The Camel message header name is "org.apache.cxf.headers.Header.list"

which is a constant dened in CXF

(org.apache.cxf.headers.Header.HEADER_LIST). The header value is a List of

CXF SoapHeader objects (org.apache.cxf.binding.soap.SoapHeader). The

following snippet is the InsertResponseOutHeaderProcessor (that insert a

new SOAP header in the response message). The way to access SOAP

headers in both InsertResponseOutHeaderProcessor and

InsertRequestOutHeaderProcessor are actually the same. The only dierence

between the two processors is setting the direction of the inserted SOAP

header.

public static class InsertResponseOutHeaderProcessor implements Processor {

@SuppressWarnings("unchecked")

public void process(Exchange exchange) throws Exception {

List<SoapHeader> soapHeaders =

(List)exchange.getIn().getHeader(Header.HEADER_LIST);

// Insert a new header

String xml = "<?xml version=\"1.0\" encoding=\"utf-8\"?><outofbandHeader "

+"xmlns=\"http://cxf.apache.org/outofband/Header\"

hdrAttribute=\"testHdrAttribute\" "

+"xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"

soap:mustUnderstand=\"1\">"

"<name>New_testOobHeader</name><value>New_testOobHeaderValue</value></outofbandHeader>";

SoapHeader newHeader = new SoapHeader(soapHeaders.get(0).getName(),

DOMUtils.readXml(new StringReader(xml)).getDocumentElement());

// make sure direction is OUT since it is a response message.

newHeader.setDirection(Direction.DIRECTION_OUT);

//newHeader.setMustUnderstand(false);

soapHeaders.add(newHeader);

}

In 1.x SOAP headers are not propagated to and from Camel Message

headers. Users have to go deeper into CXF APIs to access SOAP headers.

Also, accessing the SOAP headers in a request message is slight dierent

583 CHAPTER 11 - COMPONENT APPENDIX

than in a response message. The InsertRequestOutHeaderProcessor and

InsertResponseOutHeaderProcessor are as follow.

public static class InsertRequestOutHeaderProcessor implements Processor {

public void process(Exchange exchange) throws Exception {

CxfMessage message = exchange.getIn().getBody(CxfMessage.class);

Message cxf = message.getMessage();

List<SoapHeader> soapHeaders = (List)cxf.get(Header.HEADER_LIST);

// Insert a new header

String xml = "<?xml version=\"1.0\" encoding=\"utf-8\"?><outofbandHeader "

+"xmlns=\"http://cxf.apache.org/outofband/Header\"

hdrAttribute=\"testHdrAttribute\" "

+"xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"

soap:mustUnderstand=\"1\">"

"<name>New_testOobHeader</name><value>New_testOobHeaderValue</value></outofbandHeader>";

SoapHeader newHeader = new SoapHeader(soapHeaders.get(0).getName(),

DOMUtils.readXml(new

StringReader(xml)).getDocumentElement());

// make sure direction is IN since it is a request message.

newHeader.setDirection(Direction.DIRECTION_IN);

//newHeader.setMustUnderstand(false);

soapHeaders.add(newHeader);

}

public static class InsertResponseOutHeaderProcessor implements Processor {

public void process(Exchange exchange) throws Exception {

CxfMessage message = exchange.getIn().getBody(CxfMessage.class);

Map responseContext = (Map)message.getMessage().get(Client.RESPONSE_CONTEXT);

List<SoapHeader> soapHeaders = (List)responseContext.get(Header.HEADER_LIST);

// Insert a new header

String xml = "<?xml version=\"1.0\" encoding=\"utf-8\"?><outofbandHeader "

+"xmlns=\"http://cxf.apache.org/outofband/Header\"

hdrAttribute=\"testHdrAttribute\" "

+"xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\"

soap:mustUnderstand=\"1\">"

"<name>New_testOobHeader</name><value>New_testOobHeaderValue</value></outofbandHeader>";

SoapHeader newHeader = new SoapHeader(soapHeaders.get(0).getName(),

DOMUtils.readXml(new StringReader(xml)).getDocumentElement());

// make sure direction is OUT since it is a response message.

newHeader.setDirection(Direction.DIRECTION_OUT);

//newHeader.setMustUnderstand(false);

soapHeaders.add(newHeader);

}

CHAPTER 11 - COMPONENT APPENDIX 584

How to get and set SOAP headers in PAYLOAD mode

We've already shown how to access SOAP message (CxfPayload object) in

PAYLOAD mode (See "How to deal with the message for a camel-cxf endpoint

in PAYLOAD data format").

In 2.x Once you obtain a CxfPayload object, you can invoke the

CxfPayload.getHeaders() method that returns a List of DOM Elements (SOAP

headers).

from(getRouterEndpointURI()).process(new Processor() {

@SuppressWarnings("unchecked")

public void process(Exchange exchange) throws Exception {

CxfPayload<SoapHeader> payload = exchange.getIn().getBody(CxfPayload.class);

List<Source> elements = payload.getBodySources();

assertNotNull("We should get the elements here", elements);

assertEquals("Get the wrong elements size", 1, elements.size());

Element el = new XmlConverter().toDOMElement(elements.get(0));

elements.set(0, new DOMSource(el));

assertEquals("Get the wrong namespace URI","http://camel.apache.org/pizza/

types",

el.getNamespaceURI());

List<SoapHeader> headers = payload.getHeaders();

assertNotNull("We should get the headers here", headers);

assertEquals("Get the wrong headers size", headers.size(), 1);

assertEquals("Get the wrong namespace URI",

((Element)(headers.get(0).getObject())).getNamespaceURI(),

"http://camel.apache.org/pizza/types");

}

})

.to(getServiceEndpointURI());

*In 1.x" You can get/set to the CXF Message by the key

"org.apache.cxf.headers.Header.list" which is a constant dened in CXF

(org.apache.cxf.headers.Header.HEADER_LIST).

from(routerEndpointURI).process(new Processor() {

@SuppressWarnings("unchecked")

public void process(Exchange exchange) throws Exception {

Message inMessage = exchange.getIn();

CxfMessage message = (CxfMessage) inMessage;

List<Element> elements = message.getMessage().get(List.class);

assertNotNull("We should get the payload elements here" , elements);

assertEquals("Get the wrong elements size" , elements.size(), 1);

assertEquals("Get the wrong namespace URI" ,

elements.get(0).getNamespaceURI(), "http://camel.apache.org/pizza/types");

List<SoapHeader> headers =

CastUtils.cast((List<?>)message.getMessage().get(Header.HEADER_LIST));

585 CHAPTER 11 - COMPONENT APPENDIX

assertNotNull("We should get the headers here", headers);

assertEquals("Get the wrong headers size", headers.size(), 1);

assertEquals("Get the wrong namespace URI" ,

((Element)(headers.get(0).getObject())).getNamespaceURI(), "http://camel.apache.org/

pizza/types");

}

})

.to(serviceEndpointURI);

SOAP headers are not available in MESSAGE mode

SOAP headers are not available in MESSAGE mode as SOAP processing is

skipped.

How to throw a SOAP Fault from Camel

If you are using a camel-cxf endpoint to consume the SOAP request, you

may need to throw the SOAP Fault from the camel context.

Basically, you can use the throwFault DSL to do that; it works for POJO,

PAYLOAD and MESSAGE data format.

You can dene the soap fault like this

SOAP_FAULT = new SoapFault(EXCEPTION_MESSAGE, SoapFault.FAULT_CODE_CLIENT);

Element detail = SOAP_FAULT.getOrCreateDetail();

Document doc = detail.getOwnerDocument();

Text tn = doc.createTextNode(DETAIL_TEXT);

detail.appendChild(tn);

Then throw it as you like

from(routerEndpointURI).setFaultBody(constant(SOAP_FAULT));

If your CXF endpoint is working in the MESSAGE data format, you could set the

the SOAP Fault message in the message body and set the response code in

the message header.

from(routerEndpointURI).process(new Processor() {

public void process(Exchange exchange) throws Exception {

Message out = exchange.getOut();

// Set the message body with the

out.setBody(this.getClass().getResourceAsStream("SoapFaultMessage.xml"));

// Set the response code here

CHAPTER 11 - COMPONENT APPENDIX 586

out.setHeader(org.apache.cxf.message.Message.RESPONSE_CODE, new Integer(500));

}

});

NOTE the response code setting only works in Camel's version >= 1.5.1

Same for using POJO data format. You can set the SOAPFault on the out

body and also indicate it's a fault by calling Message.setFault(true):

from("direct:start").onException(SoapFault.class).maximumRedeliveries(0).handled(true)

.process(new Processor() {

public void process(Exchange exchange) throws Exception {

SoapFault fault = exchange

.getProperty(Exchange.EXCEPTION_CAUGHT, SoapFault.class);

exchange.getOut().setFault(true);

exchange.getOut().setBody(fault);

}

}).end().to(serviceURI);

How to propagate a camel-cxf endpoint's request and response

context

cxf client API provides a way to invoke the operation with request and

response context. If you are using a camel-cxf endpoint producer to invoke

the outside web service, you can set the request context and get response

context with the following code:

CxfExchange exchange = (CxfExchange)template.send(getJaxwsEndpointUri(), new

Processor() {

public void process(final Exchange exchange) {

final List<String> params = new ArrayList<String>();

params.add(TEST_MESSAGE);

// Set the request context to the inMessage

Map<String,Object> requestContext = new HashMap<String,Object>();

requestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,

JAXWS_SERVER_ADDRESS);

exchange.getIn().setBody(params);

exchange.getIn().setHeader(Client.REQUEST_CONTEXT , requestContext);

exchange.getIn().setHeader(CxfConstants.OPERATION_NAME,

GREET_ME_OPERATION);

}

});

org.apache.camel.Message out = exchange.getOut();

// The output is an object array, the first element of the array is the

return value

Object\[\] output = out.getBody(Object\[\].class);

LOG.info("Received output text: " + output\[0\]);

587 CHAPTER 11 - COMPONENT APPENDIX

// Get the response context form outMessage

Map<String,Object> responseContext =

CastUtils.cast((Map)out.getHeader(Client.RESPONSE_CONTEXT));

assertNotNull(responseContext);

assertEquals("Get the wrong wsdl opertion name","{http://apache.org/

hello_world_soap_http}greetMe",

responseContext.get("javax.xml.ws.wsdl.operation").toString());

Attachment Support

POJO Mode: Both SOAP with Attachment and MTOM are supported (see

example in Payload Mode for enabling MTOM). However, SOAP with

Attachment is not tested. Since attachments are marshalled and

unmarshalled into POJOs, users typically do not need to deal with the

attachment themself. Attachments are propagated to Camel message's

attachments since 2.1. So, it is possible to retreive attachments by Camel

Message API

DataHandler Message.getAttachment(String id)

Payload Mode: MTOM is supported since 2.1. Attachments can be

retrieved by Camel Message APIs mentioned above. SOAP with Attachment

(SwA) is supported and attachments can be retrieved since 2.5. SwA is the

default (same as setting the CXF endpoint property "mtom_enabled" to

false).

To enable MTOM, set the CXF endpoint property "mtom_enabled" to true. (I

believe you can only do it with Spring.)

<cxf:cxfEndpoint id="routerEndpoint"

address="http://localhost:${CXFTestSupport.port1}/CxfMtomRouterPayloadModeTest/

jaxws-mtom/hello"

wsdlURL="mtom.wsdl"

serviceName="ns:HelloService"

endpointName="ns:HelloPort"

xmlns:ns="http://apache.org/camel/cxf/mtom_feature">

<cxf:properties>

</cxf:properties>

CHAPTER 11 - COMPONENT APPENDIX 588

You can produce a Camel message with attachment to send to a CXF

endpoint in Payload mode.

Exchange exchange = context.createProducerTemplate().send("direct:testEndpoint",new

Processor() {

public void process(Exchange exchange) throws Exception {

exchange.setPattern(ExchangePattern.InOut);

List<Source> elements = new ArrayList<Source>();

elements.add(new DOMSource(DOMUtils.readXml(new

StringReader(MtomTestHelper.REQ_MESSAGE)).getDocumentElement()));

CxfPayload<SoapHeader> body = new CxfPayload<SoapHeader>(new

ArrayList<SoapHeader>(),

elements, null);

exchange.getIn().setBody(body);

exchange.getIn().addAttachment(MtomTestHelper.REQ_PHOTO_CID,

new DataHandler(new ByteArrayDataSource(MtomTestHelper.REQ_PHOTO_DATA,

"application/octet-stream")));

exchange.getIn().addAttachment(MtomTestHelper.REQ_IMAGE_CID,

new DataHandler(new ByteArrayDataSource(MtomTestHelper.requestJpeg,

"image/jpeg")));

}

});

// process response

CxfPayload<SoapHeader> out = exchange.getOut().getBody(CxfPayload.class);

Assert.assertEquals(1, out.getBody().size());

Map<String,String> ns = new HashMap<String,String>();

ns.put("ns", MtomTestHelper.SERVICE_TYPES_NS);

ns.put("xop", MtomTestHelper.XOP_NS);

XPathUtils xu = new XPathUtils(ns);

Element oute = new XmlConverter().toDOMElement(out.getBody().get(0));

Element ele = (Element)xu.getValue("//ns:DetailResponse/ns:photo/xop:Include", oute,

XPathConstants.NODE);

String photoId = ele.getAttribute("href").substring(4); // skip "cid:"

ele = (Element)xu.getValue("//ns:DetailResponse/ns:image/xop:Include", oute,

XPathConstants.NODE);

String imageId = ele.getAttribute("href").substring(4); // skip "cid:"

DataHandler dr = exchange.getOut().getAttachment(photoId);

Assert.assertEquals("application/octet-stream", dr.getContentType());

MtomTestHelper.assertEquals(MtomTestHelper.RESP_PHOTO_DATA,

IOUtils.readBytesFromStream(dr.getInputStream()));

dr = exchange.getOut().getAttachment(imageId);

Assert.assertEquals("image/jpeg", dr.getContentType());

589 CHAPTER 11 - COMPONENT APPENDIX

BufferedImage image = ImageIO.read(dr.getInputStream());

Assert.assertEquals(560, image.getWidth());

Assert.assertEquals(300, image.getHeight());

You can also consume a Camel message received from a CXF endpoint in

Payload mode.

public static class MyProcessor implements Processor {

@SuppressWarnings("unchecked")

public void process(Exchange exchange) throws Exception {

CxfPayload<SoapHeader> in = exchange.getIn().getBody(CxfPayload.class);

// verify request

Assert.assertEquals(1, in.getBody().size());

Map<String,String> ns = new HashMap<String,String>();

ns.put("ns", MtomTestHelper.SERVICE_TYPES_NS);

ns.put("xop", MtomTestHelper.XOP_NS);

XPathUtils xu = new XPathUtils(ns);

Element body = new XmlConverter().toDOMElement(in.getBody().get(0));

Element ele = (Element)xu.getValue("//ns:Detail/ns:photo/xop:Include", body,

XPathConstants.NODE);

String photoId = ele.getAttribute("href").substring(4); // skip "cid:"

Assert.assertEquals(MtomTestHelper.REQ_PHOTO_CID, photoId);

ele = (Element)xu.getValue("//ns:Detail/ns:image/xop:Include", body,

XPathConstants.NODE);

String imageId = ele.getAttribute("href").substring(4); // skip "cid:"

Assert.assertEquals(MtomTestHelper.REQ_IMAGE_CID, imageId);

DataHandler dr = exchange.getIn().getAttachment(photoId);

Assert.assertEquals("application/octet-stream", dr.getContentType());

MtomTestHelper.assertEquals(MtomTestHelper.REQ_PHOTO_DATA,

IOUtils.readBytesFromStream(dr.getInputStream()));

dr = exchange.getIn().getAttachment(imageId);

Assert.assertEquals("image/jpeg", dr.getContentType());

MtomTestHelper.assertEquals(MtomTestHelper.requestJpeg,

IOUtils.readBytesFromStream(dr.getInputStream()));

// create response

List<Source> elements = new ArrayList<Source>();

elements.add(new DOMSource(DOMUtils.readXml(new

StringReader(MtomTestHelper.RESP_MESSAGE)).getDocumentElement()));

CxfPayload<SoapHeader> sbody = new CxfPayload<SoapHeader>(new

ArrayList<SoapHeader>(),

elements, null);

exchange.getOut().setBody(sbody);

exchange.getOut().addAttachment(MtomTestHelper.RESP_PHOTO_CID,

CHAPTER 11 - COMPONENT APPENDIX 590

new DataHandler(new ByteArrayDataSource(MtomTestHelper.RESP_PHOTO_DATA,

"application/octet-stream")));

exchange.getOut().addAttachment(MtomTestHelper.RESP_IMAGE_CID,

new DataHandler(new ByteArrayDataSource(MtomTestHelper.responseJpeg,

"image/jpeg")));

}

Message Mode: Attachments are not supported as it does not process the

message at all.

Streaming Support in PAYLOAD mode

In 2.8.2, the camel-cxf component now supports streaming of incoming

messages when using PAYLOAD mode. Previously, the incoming messages

would have been completely DOM parsed. For large messages, this is time

consuming and uses a signicant amount of memory. Starting in 2.8.2, the

incoming messages can remain as a javax.xml.transform.Source while being

routed and, if nothing modies the payload, can then be directly streamed

out to the target destination. For common "simple proxy" use cases

(example: from("cxf:...").to("cxf:...")), this can provide very signicant

performance increases as well as signicantly lowered memory

requirements.

However, there are cases where streaming may not be appropriate or

desired. Due to the streaming nature, invalid incoming XML may not be

caught until later in the processing chain. Also, certain actions may require

the message to be DOM parsed anyway (like WS-Security or message tracing

and such) in which case the advantages of the streaming is limited. At this

point, there are two ways to control the streaming:

• Endpoint property: you can add "allowStreaming=false" as an

endpoint property to turn the streaming on/o.

• Component property: the CxfComponent object also has an

allowStreaming property that can set the default for endpoints

created from that component.

• Global system property: you can add a system property of

"org.apache.camel.component.cxf.streaming" to "false" to turn if o.

That sets the global default, but setting the endpoint property above

will override this value for that endpoint.

See Also

• Conguring Camel

591 CHAPTER 11 - COMPONENT APPENDIX

• Component

• Endpoint

• Getting Started

CXF BEAN COMPONENT (2.0 OR LATER)

The cxfbean: component allows other Camel endpoints to send exchange

and invoke Web service bean objects. (Currently, it only supports JAXRS,

JAXWS(new to camel2.1) annotated service bean.)

URI format

cxfbean:serviceBeanRef

Where serviceBeanRef is a registry key to look up the service bean object.

If serviceBeanRef references a List object, elements of the List are the

service bean objects accepted by the endpoint.

Options

Name Description Example Required? Default Value

cxfBeanBinding

CXF bean binding specied by the #notation. The referenced

object must be an instance of

org.apache.camel.component.cxf.cxfbean.CxfBeanBinding.

cxfBinding=#bindingName No DefaultCxfBeanBinding

bus CXF bus reference specied by the #notation. The referenced

object must be an instance of org.apache.cxf.Bus.bus=#busName No Default bus created by CXF

Bus Factory

headerFilterStrategy

Header lter strategy specied by the #notation. The

referenced object must be an instance of

org.apache.camel.spi.HeaderFilterStrategy.

headerFilterStrategy=#strategyName No CxfHeaderFilterStrategy

setDefaultBus Will set the default bus when CXF endpoint create a bus by

itself. true,false No false

populateFromClass

Since 2.3, the wsdlLocation annotated in the POJO is ignored

(by default) unless this option is set to false. Prior to 2.3, the

wsdlLocation annotated in the POJO is always honored and it is

not possible to ignore.

true,false No true

providers Since 2.5, setting the providers for the CXFRS endpoint. providers=#providerRef1,#providerRef2 No null

Headers

Name Description Type Required? Default

Value

In/

Out Examples

CamelHttpCharacterEncoding

(before 2.0-m2:

CamelCxfBeanCharacterEncoding)

Character encoding String No None In ISO-8859-1

CamelContentType (before 2.0-m2:

CamelCxfBeanContentType)Content type String No */* In text/xml

CHAPTER 11 - COMPONENT APPENDIX 592

CxfBeanEndpoint is a ProcessorEndpoint so it has no consumers.

It works similarly to a Bean component.

CamelHttpBaseUri

(2.0-m3 and before:

CamelCxfBeanRequestBasePath)

The value of this

header will be set in

the CXF message as

the

Message.BASE_PATH

property. It is needed

by CXF JAX-RS

processing. Basically, it

is the scheme, host

and port portion of the

request URI.

String Yes

The Endpoint

URI of the

source

endpoint in

the Camel

exchange

In http://localhost:9000

CamelHttpPath (before 2.0-m2:

CamelCxfBeanRequestPath) Request URI's path String Yes None In consumer/123

CamelHttpMethod (before 2.0-m2:

CamelCxfBeanVerb)RESTful request verb String Yes None In GET,PUT,POST,

DELETE

CamelHttpResponseCode HTTP response code Integer No None Out 200

A Working Sample

This sample shows how to create a route that starts a Jetty HTTP server. The

route sends requests to a CXF Bean and invokes a JAXRS annotated service.

First, create a route as follows. The from endpoint is a Jetty HTTP endpoint

that is listening on port 9000. Notice that the matchOnUriPrefix option must

be set to true because RESTful request URI will not match the endpoint's URI

http://localhost:9000 exactly.

<route>

</route>

The to endpoint is a CXF Bean with bean name customerServiceBean. The

name will be looked up from the registry. Next, we make sure our service

bean is available in Spring registry. We create a bean denition in the Spring

conguration. In this example, we create a List of service beans (of one

element). We could have created just a single bean without a List.

<util:list id="customerServiceBean">

</util:list>

That's it. Once the route is started, the web service is ready for business. A

HTTP client can make a request and receive response.

593 CHAPTER 11 - COMPONENT APPENDIX

Currently, CXF Bean component has (only) been tested with Jetty

HTTP component it can understand headers from Jetty HTTP

component without requiring conversion.

CXFRS COMPONENT

The cxfrs: component provides integration with Apache CXF for connecting

to JAX-RS services hosted in CXF.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-cxf</artifactId>

</dependency>

URI format

cxfrs://address?options

Where address represents the CXF endpoint's address

cxfrs:bean:rsEndpoint

Where rsEndpoint represents the spring bean's name which presents the

CXFRS client or server

For either style above, you can append options to the URI as follows:

cxfrs:bean:cxfEndpoint?resourceClass=org.apache.camel.rs.Example

Options

Name Description Example Required? default

value

resourceClasses

The resource classes which

you want to export as REST

service

resourceClasses

=org.apache.camel.rs.Example1,org.apache.camel.rs.Exchange2 No None

CHAPTER 11 - COMPONENT APPENDIX 594

When using CXF as a consumer, the CXF Bean Component allows

you to factor out how message payloads are received from their

processing as a RESTful or SOAP web service. This has the potential

of using a multitude of transports to consume web services. The

bean component's conguration is also simpler and provides the

fastest method to implement web services using Camel and CXF.

httpClientAPI

new to Camel 2.1 If it is

true, the CxfRsProducer will

use the HttpClientAPI to

invoke the service

If it is false, the

CxfRsProducer will use the

ProxyClientAPI to invoke the

service

httpClientAPI=true No true

synchronous

New in 2.5, this option will

let CxfRsConsumer decide to

use sync or async API to do

the underlying work. The

default value is false which

means it will try to use async

API by default.

synchronous=true No false

throwExceptionOnFailure

New in 2.6, this option tells

the CxfRsProducer to inspect

return codes and will

generate an Exception if the

return code is larger than

207.

throwExceptionOnFailure=true No true

maxClientCacheSize

New in 2.6, you can set a IN

message header

CamelDestinationOverrideUrl

to dynamically override the

target destination Web

Service or REST Service

dened in your routes. The

implementation caches CXF

clients or ClientFactoryBean

in CxfProvider and

CxfRsProvider. This option

allows you to congure the

maximum size of the cache.

maxClientCacheSize=5 No 10

setDefaultBus

New in 2.9.0. Will set the

default bus when CXF

endpoint create a bus by

itself

setDefaultBus=true No false

bus

New in 2.9.0. A default bus

created by CXF Bus Factory.

Use #notation to reference a

bus object from the registry.

The referenced object must

be an instance of

org.apache.cxf.Bus.

bus=#busName No None

You can also congure the CXF REST endpoint through the spring

conguration. Since there are lots of dierence between the CXF REST client

and CXF REST Server, we provides dierent conguration for them.

Please check out the schema le and CXF REST user guide for more

information.

595 CHAPTER 11 - COMPONENT APPENDIX

How to congure the REST endpoint in Camel

In camel-cxf schema le, there are two elements for the REST endpoint

denition. cxf:rsServer for REST consumer, cxf:rsClient for REST producer.

You can nd an camel REST service route conguration example here.

<beans xmlns="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:cxf="http://camel.apache.org/schema/cxf"

xmlns:jaxrs="http://cxf.apache.org/jaxrs"

xsi:schemaLocation="

http://www.springframework.org/schema/beans http://www.springframework.org/

schema/beans/spring-beans.xsd

http://camel.apache.org/schema/cxf http://camel.apache.org/schema/cxf/

camel-cxf.xsd

http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd

http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/

camel-spring.xsd

<bean

class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/>

<jaxrs:server id="restService"

address="http://localhost:${CXFTestSupport.port2}/

CxfRsRouterTest/rest"

staticSubresourceResolution="true">

<jaxrs:serviceBeans>

</jaxrs:serviceBeans>

</jaxrs:server>

<bean id="customerService"

class="org.apache.camel.component.cxf.jaxrs.testbean.CustomerService" />

<cxf:rsServer id="rsServer" address="http://localhost:${CXFTestSupport.port1}/

CxfRsRouterTest/route"

serviceClass="org.apache.camel.component.cxf.jaxrs.testbean.CustomerService"

loggingFeatureEnabled="true" loggingSizeLimit="20"/>

<cxf:rsClient id="rsClient" address="http://localhost:${CXFTestSupport.port2}/

CxfRsRouterTest/rest"

serviceClass="org.apache.camel.component.cxf.jaxrs.testbean.CustomerService"

loggingFeatureEnabled="true" />

<route>

CHAPTER 11 - COMPONENT APPENDIX 596

<!-- We can remove this configure as the CXFRS producer is using the HttpAPI

by default -->

</setHeader>

</route>

</camelContext>

</beans>

How to consume the REST request in Camel

CXF JAXRS front end implements the JAXRS(JSR311) API, so we can export the

resources classes as a REST service. And we leverage the CXF Invoker API to

turn a REST request into a normal Java object method invocation.

Unlike the camel-restlet, you don't need to specify the URI template within

your restlet endpoint, CXF take care of the REST request URI to resource

class method mapping according to the JSR311 specication. All you need to

do in Camel is delegate this method request to a right processor or endpoint.

Here is an example of a CXFRS route...

private static final String CXF_RS_ENDPOINT_URI = "cxfrs://http://localhost:" + CXT +

"/rest?resourceClasses=org.apache.camel.component.cxf.jaxrs.testbean.CustomerServiceResource";

protected RouteBuilder createRouteBuilder() throws Exception {

return new RouteBuilder() {

public void configure() {

errorHandler(new NoErrorHandlerBuilder());

from(CXF_RS_ENDPOINT_URI).process(new Processor() {

public void process(Exchange exchange) throws Exception {

Message inMessage = exchange.getIn();

// Get the operation name from in message

String operationName =

inMessage.getHeader(CxfConstants.OPERATION_NAME, String.class);

if ("getCustomer".equals(operationName)) {

String httpMethod = inMessage.getHeader(Exchange.HTTP_METHOD,

String.class);

assertEquals("Get a wrong http method","GET", httpMethod);

String path = inMessage.getHeader(Exchange.HTTP_PATH,

String.class);

// The parameter of the invocation is stored in the body of

in message

String id = (String) inMessage.getBody(String.class);

if ("/customerservice/customers/126".equals(path))

{

Customer customer = new Customer();

customer.setId(Long.parseLong(id));

597 CHAPTER 11 - COMPONENT APPENDIX

customer.setName("Willem");

// We just put the response Object into the out message

body

exchange.getOut().setBody(customer);

}else {

if ("/customerservice/customers/123".equals(path)) {

// send a customer response back

Response r = Response.status(200).entity("customer

response back!").build();

exchange.getOut().setBody(r);

return;

}

if ("/customerservice/customers/456".equals(path)) {

Response r = Response.status(404).entity("Can't found

the customer with uri " + path).build();

throw new WebApplicationException(r);

}else {

throw new RuntimeCamelException("Can't found the

customer with uri " + path);

}

if ("updateCustomer".equals(operationName)) {

assertEquals("Get a wrong customer message header",

"header1;header2", inMessage.getHeader("test"));

String httpMethod = inMessage.getHeader(Exchange.HTTP_METHOD,

String.class);

assertEquals("Get a wrong http method","PUT", httpMethod);

Customer customer = inMessage.getBody(Customer.class);

assertNotNull("The customer should not be null.", customer);

// Now you can do what you want on the customer object

assertEquals("Get a wrong customer name.","Mary",

customer.getName());

// set the response back

exchange.getOut().setBody(Response.ok().build());

}

});

}

};

}

And the corresponding resource class used to congure the endpoint...

@Path("/customerservice/")

public class CustomerServiceResource {

public CustomerServiceResource() {

}

@GET

CHAPTER 11 - COMPONENT APPENDIX 598

note about the resource class

This class is used to congure the JAXRS properties ONLY. The

methods will NOT be executed during the routing of messages to

the endpoint, the route itself is responsible for ALL processing

instead.

@Path("/customers/{id}/")

public Customer getCustomer(@PathParam("id")String id) {

return null;

}

@PUT

@Path("/customers/")

public Response updateCustomer(Customer customer) {

return null;

}

How to invoke the REST service through camel-cxfrs producer

CXF JAXRS front end implements a proxy based client API, with this API you

can invoke the remote REST service through a proxy.

camel-cxfrs producer is based on this proxy API.

So, you just need to specify the operation name in the message header and

prepare the parameter in the message body, camel-cxfrs producer will

generate right REST request for you.

Here is an example

Exchange exchange = template.send("direct://proxy",new Processor() {

public void process(Exchange exchange) throws Exception {

exchange.setPattern(ExchangePattern.InOut);

Message inMessage = exchange.getIn();

setupDestinationURL(inMessage);

// set the operation name

inMessage.setHeader(CxfConstants.OPERATION_NAME, "getCustomer");

// using the proxy client API

inMessage.setHeader(CxfConstants.CAMEL_CXF_RS_USING_HTTP_API, Boolean.FALSE);

// set the parameters , if you just have one parameter

// camel will put this object into an Object[] itself

inMessage.setBody("123");

}

});

// get the response message

Customer response = (Customer) exchange.getOut().getBody();

599 CHAPTER 11 - COMPONENT APPENDIX

assertNotNull("The response should not be null ", response);

assertEquals("Get a wrong customer id ",String.valueOf(response.getId()), "123");

assertEquals("Get a wrong customer name", response.getName(), "John");

assertEquals("Get a wrong response code", 200,

exchange.getOut().getHeader(Exchange.HTTP_RESPONSE_CODE));

CXF JAXRS front end also provides a http centric client API, You can also

invoke this API from camel-cxfrs producer. You need to specify the

HTTP_PATH and Http method and let the the producer know to use the http

centric client by using the URI option httpClientAPI or set the message

header with CxfConstants.CAMEL_CXF_RS_USING_HTTP_API. You can turn the

response object to the type class that you specify with

CxfConstants.CAMEL_CXF_RS_RESPONSE_CLASS.

Exchange exchange = template.send("direct://http",new Processor() {

public void process(Exchange exchange) throws Exception {

exchange.setPattern(ExchangePattern.InOut);

Message inMessage = exchange.getIn();

setupDestinationURL(inMessage);

// using the http central client API

inMessage.setHeader(CxfConstants.CAMEL_CXF_RS_USING_HTTP_API, Boolean.TRUE);

// set the Http method

inMessage.setHeader(Exchange.HTTP_METHOD, "GET");

// set the relative path

inMessage.setHeader(Exchange.HTTP_PATH, "/customerservice/customers/

123");

// Specify the response class , cxfrs will use InputStream as the response

object type

inMessage.setHeader(CxfConstants.CAMEL_CXF_RS_RESPONSE_CLASS, Customer.class);

// since we use the Get method, so we don't need to set the message body

inMessage.setBody(null);

}

});

// get the response message

Customer response = (Customer) exchange.getOut().getBody();

assertNotNull("The response should not be null ", response);

assertEquals("Get a wrong customer id ",String.valueOf(response.getId()), "123");

assertEquals("Get a wrong customer name", response.getName(), "John");

assertEquals("Get a wrong response code", 200,

exchange.getOut().getHeader(Exchange.HTTP_RESPONSE_CODE));

From Camel 2.1, we also support to specify the query parameters from cxfrs

URI for the CXFRS http centric client.

Exchange exchange = template.send("cxfrs://http://localhost:" + getPort2() + "/" +

getClass().getSimpleName() + "/testQuery?httpClientAPI=true&q1=12&q2=13"

CHAPTER 11 - COMPONENT APPENDIX 600

To support the Dynamical routing, you can override the URI's query

parameters by using the CxfConstants.CAMEL_CXF_RS_QUERY_MAP header to

set the parameter map for it.To support the Dynamical routing, you can

override the URI's query parameters by using the

CxfConstants.CAMEL_CXF_RS_QUERY_MAP header to set the parameter map

for it.

Map<String,String> queryMap = new LinkedHashMap<String,

String>();

queryMap.put("q1","new");

queryMap.put("q2","world");

inMessage.setHeader(CxfConstants.CAMEL_CXF_RS_QUERY_MAP, queryMap);

DATASET COMPONENT

Testing of distributed and asynchronous processing is notoriously dicult.

The Mock, Test and DataSet endpoints work great with the Camel Testing

Framework to simplify your unit and integration testing using Enterprise

Integration Patterns and Camel's large range of Components together with

the powerful Bean Integration.

The DataSet component (available since 1.3.0) provides a mechanism to

easily perform load & soak testing of your system. It works by allowing you to

create DataSet instances both as a source of messages and as a way to

assert that the data set is received.

Camel will use the throughput logger when sending dataset's.

URI format

dataset:name[?options]

Where name is used to nd the DataSet instance in the Registry

Camel ships with a support implementation of

org.apache.camel.component.dataset.DataSet, the

org.apache.camel.component.dataset.DataSetSupport class, that can be

used as a base for implementing your own DataSet. Camel also ships with a

default implementation, the

org.apache.camel.component.dataset.SimpleDataSet that can be used

for testing.

601 CHAPTER 11 - COMPONENT APPENDIX

Options

Option Default Description

produceDelay 3Allows a delay in ms to be specied, which causes producers to pause in order to simulate slow producers.

Uses a minimum of 3 ms delay unless you set this option to -1 to force no delay at all.

consumeDelay 0 Allows a delay in ms to be specied, which causes consumers to pause in order to simulate slow consumers.

preloadSize 0 Sets how many messages should be preloaded (sent) before the route completes its initialization.

initialDelay 1000 Camel 2.1: Time period in millis to wait before starting sending messages.

minRate 0 Wait until the DataSet contains at least this number of messages

You can append query options to the URI in the following format,

?option=value&option=value&...

Conguring DataSet

Camel will lookup in the Registry for a bean implementing the DataSet

interface. So you can register your own DataSet as:

</bean>

Example

For example, to test that a set of messages are sent to a queue and then

consumed from the queue without losing any messages:

// send the dataset to a queue

from("dataset:foo").to("activemq:SomeQueue");

// now lets test that the messages are consumed correctly

from("activemq:SomeQueue").to("dataset:foo");

The above would look in the Registry to nd the foo DataSet instance which

is used to create the messages.

Then you create a DataSet implementation, such as using the

SimpleDataSet as described below, conguring things like how big the data

set is and what the messages look like etc.

Properties on SimpleDataSet

Property Type Description

defaultBody Object Species the default message body. For SimpleDataSet it is a constant payload; though if you want to create

custom payloads per message, create your own derivation of DataSetSupport.

reportGroup long Species the number of messages to be received before reporting progress. Useful for showing progress of a

large load test.

size long Species how many messages to send/consume.

CHAPTER 11 - COMPONENT APPENDIX 602

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

• Spring Testing

DB4O COMPONENT

Available as of Camel 2.5

The db4o: component allows you to work with db4o NoSQL database. The

camel-db4o library is provided by the Camel Extra project which hosts all

*GPL related components for Camel.

Sending to the endpoint

Sending POJO object to the db4o endpoint adds and saves object into the

database. The body of the message is assumed to be a POJO that has to be

saved into the db40 database store.

Consuming from the endpoint

Consuming messages removes (or updates) POJO objects in the database.

This allows you to use a Db4o datastore as a logical queue; consumers take

messages from the queue and then delete them to logically remove them

from the queue.

If you do not wish to delete the object when it has been processed, you

can specify consumeDelete=false on the URI. This will result in the POJO

being processed each poll.

URI format

db4o:className[?options]

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Default

Value Description

603 CHAPTER 11 - COMPONENT APPENDIX

consumeDelete true Option for Db4oConsumer only. Species whether or not the entity is deleted after it is consumed.

consumer.delay 500 Option for HibernateConsumer only. Delay in millis between each poll.

consumer.initialDelay 1000 Option for HibernateConsumer only. Millis before polling starts.

consumer.userFixedDelay false Option for HibernateConsumer only. Set to true to use xed delay between polls, otherwise xed

rate is used. See ScheduledExecutorService in JDK for details.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

DIRECT COMPONENT

The direct: component provides direct, synchronous invocation of any

consumers when a producer sends a message exchange.

This endpoint can be used to connect existing routes in the same camel

context.

URI format

direct:someName[?options]

Where someName can be any string to uniquely identify the endpoint

Options

Name Default

Value Description

allowMultipleConsumers true

@deprecated If set to false, then when a second consumer is started on the endpoint, an

IllegalStateException is thrown. Will be removed in Camel 2.1: Direct endpoint does not

support multiple consumers.

You can append query options to the URI in the following format,

?option=value&option=value&...

Samples

In the route below we use the direct component to link the two routes

together:

from("activemq:queue:order.in")

.to("bean:orderServer?method=validate")

CHAPTER 11 - COMPONENT APPENDIX 604

Asynchronous

The SEDA component provides asynchronous invocation of any

consumers when a producer sends a message exchange.

Connection to other camel contexts

The VM component provides connections between Camel contexts

as long they run in the same JVM.

.to("direct:processOrder");

from("direct:processOrder")

.to("bean:orderService?method=process")

.to("activemq:queue:order.out");

And the sample using spring DSL:

<route>

</route>

<route>

</route>

See also samples from the SEDA component, how they can be used together.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ SEDA

▪ VM

605 CHAPTER 11 - COMPONENT APPENDIX

DNS

Available as of Camel 2.7

This is an additional component for Camel to run DNS queries, using

DNSJava. The component is a thin layer on top of DNSJava.

The component oers the following operations:

▪ ip, to resolve a domain by its ip

▪ lookup, to lookup information about the domain

▪ dig, to run DNS queries

Maven users will need to add the following dependency to their pom.xml for

this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-dns</artifactId>

</dependency>

URI format

The URI scheme for a DNS component is as follows

dns://operation

This component only supports producers.

Options

None.

Headers

Header Type Operations Description

dns.domain String ip The domain name. Mandatory.

dns.name String lookup The name to lookup. Mandatory.

dns.type ▪ lookup, dig The type of the lookup. Should match the values of org.xbill.dns.Type. Optional.

dns.class ▪ lookup, dig he DNS class of the lookup. Should match the values of org.xbill.dns.DClass.

Optional.

dns.query String dig The query itself. Mandatory.

dns.server String dig The server in particular for the query. If none is given, the default one specied by the

OS will be used. Optional.

CHAPTER 11 - COMPONENT APPENDIX 606

Examples

IP lookup

</route>

This looks up a domain's IP. For example, www.example.com resolves to

192.0.32.10.

The IP address to lookup must be provided in the header with key

"dns.domain".

DNS lookup

</route>

This returns a set of DNS records associated with a domain.

The name to lookup must be provided in the header with key "dns.name".

DNS Dig

Dig is a Unix command-line utility to run DNS queries.

</route>

The query must be provided in the header with key "dns.query".

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

607 CHAPTER 11 - COMPONENT APPENDIX

EJB COMPONENT

Available as of Camel 2.4

The ejb: component binds EJBs to Camel message exchanges.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-ejb</artifactId>

</dependency>

URI format

ejb:ejbName[?options]

Where ejbName can be any string which is used to look up the EJB in the

Application Server JNDI Registry

Options

Name Type Default Description

method String null

The method name that bean will be invoked. If not provided, Camel will try to pick the

method itself. In case of ambiguity an exception is thrown. See Bean Binding for more

details.

multiParameterArray boolean false How to treat the parameters which are passed from the message body; if it is true, the In

message body should be an array of parameters.

You can append query options to the URI in the following format,

?option=value&option=value&...

The EJB component extends the Bean component in which most of the

details from the Bean component applies to this component as well.

Bean Binding

How bean methods to be invoked are chosen (if they are not specied

explicitly through the method parameter) and how parameter values are

constructed from the Message are all dened by the Bean Binding

mechanism which is used throughout all of the various Bean Integration

mechanisms in Camel.

CHAPTER 11 - COMPONENT APPENDIX 608

Examples

In the following examples we use the Greater EJB which is dened as follows:

Listing 73. GreaterLocal.java

public interface GreaterLocal {

String hello(String name);

String bye(String name);

}

And the implementation

Listing 74. GreaterImpl.java

@Stateless

public class GreaterImpl implements GreaterLocal {

public String hello(String name) {

return "Hello " + name;

}

public String bye(String name) {

return "Bye " + name;

}

Using Java DSL

In this example we want to invoke the hello method on the EJB. Since this

example is based on an unit test using Apache OpenEJB we have to set a

JndiContext on the EJB component with the OpenEJB settings.

@Override

protected CamelContext createCamelContext() throws Exception {

CamelContext answer = new DefaultCamelContext();

// enlist EJB component using the JndiContext

EjbComponent ejb = answer.getComponent("ejb", EjbComponent.class);

ejb.setContext(createEjbContext());

return answer;

}

private static Context createEjbContext() throws NamingException {

// here we need to define our context factory to use OpenEJB for our testing

Properties properties = new Properties();

609 CHAPTER 11 - COMPONENT APPENDIX

properties.setProperty(Context.INITIAL_CONTEXT_FACTORY,

"org.apache.openejb.client.LocalInitialContextFactory");

return new InitialContext(properties);

}

Then we are ready to use the EJB in the Camel route:

from("direct:start")

// invoke the greeter EJB using the local interface and invoke the hello method

.to("ejb:GreaterImplLocal?method=hello")

.to("mock:result");

Using Spring XML

And this is the same example using Spring XML instead:

Again since this is based on an unit test we need to setup the EJB

component:

</bean>

<p:properties id="jndiProperties">

<prop

key="java.naming.factory.initial">org.apache.openejb.client.LocalInitialContextFactory</prop>

</p:properties>

Before we are ready to use EJB in the Camel routes:

<route>

</route>

</camelContext>

See Also

• Conguring Camel

• Component

• Endpoint

CHAPTER 11 - COMPONENT APPENDIX 610

In a real application server

In a real application server you most likely do not have to setup a

JndiContext on the EJB component as it will create a default

JndiContext on the same JVM as the application server, which

usually allows it to access the JNDI registry and lookup the EJBs.

However if you need to access a application server on a remote JVM

or the likes, you have to prepare the properties beforehand.

• Getting Started

• Bean

• Bean Binding

• Bean Integration

ESPER

The Esper component supports the Esper Library for Event Stream

Processing. The camel-esper library is provided by the Camel Extra project

which hosts all *GPL related components for Camel.

URI format

esper:name[?options]

When consuming from an Esper endpoint you must specify a pattern or eql

statement to query the event stream.

For example

from("esper://cheese?pattern=every event=MyEvent(bar=5)").

to("activemq:Foo");

Options

Name Default Value Description

pattern The Esper Pattern expression as a String to lter events

eql The Esper EQL expression as a String to lter events

You can append query options to the URI in the following format,

?option=value&option=value&...

611 CHAPTER 11 - COMPONENT APPENDIX

Demo

There is a demo which shows how to work with ActiveMQ, Camel and Esper in

the Camel Extra project

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

• Esper Camel Demo

EVENT COMPONENT

The event: component provides access to the Spring ApplicationEvent

objects. This allows you to publish ApplicationEvent objects to a Spring

ApplicationContext or to consume them. You can then use Enterprise

Integration Patterns to process them such as Message Filter.

URI format

spring-event://default

If you use Camel 1.x then you may need to remove the // to get it working

with the Spring event notication

spring-event:default

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

FILE COMPONENT - CAMEL 2.0 ONWARDS

The File component provides access to le systems, allowing les to be

processed by any other Camel Components or messages from other

components to be saved to disk.

CHAPTER 11 - COMPONENT APPENDIX 612

Using Camel 1.x

This documentation is only for Camel 2.0 or newer. If you are using

Camel 1.x then see this link instead.

URI format

file:directoryName[?options]

file://directoryName[?options]

Where directoryName represents the underlying le directory.

You can append query options to the URI in the following format,

?option=value&option=value&...

URI Options

Common

Name Default

Value Description

autoCreate true

Automatically create missing directories in the le's pathname. For the le consumer, that

means creating the starting directory. For the le producer, it means the directory the les

should be written to.

bufferSize 128kb Write buer sized in bytes.

fileName null

Use Expression such as File Language to dynamically set the lename. For consumers, it's used

as a lename lter. For producers, it's used to evaluate the lename to write. If an expression is

set, it take precedence over the CamelFileName header. (Note: The header itself can also be

an Expression). The expression options support both String and Expression types. If the

expression is a String type, it is always evaluated using the File Language. If the expression is

an Expression type, the specied Expression type is used - this allows you, for instance, to

use OGNL expressions. For the consumer, you can use it to lter lenames, so you can for

instance consume today's le using the File Language syntax: mydata-

${date:now:yyyyMMdd}.txt.

flatten false

Flatten is used to atten the le name path to strip any leading paths, so it's just the le name.

This allows you to consume recursively into sub-directories, but when you eg write the les to

another directory they will be written in a single directory. Setting this to true on the producer

enforces that any le name recived in CamelFileName header will be stripped for any leading

paths.

charset null Camel 2.5: this option is used to specify the encoding of the le, and camel will set the

Exchange property with Exchange.CHARSET_NAME with the value of this option.

copyAndDeleteOnRenameFail true Camel 2.9: whether to fallback and do a copy and delete le, in case the le could not be

renamed directly. This option is not available for the FTP component.

613 CHAPTER 11 - COMPONENT APPENDIX

Only directories

Camel 2.0 only support endpoints congured with a starting

directory. So the directoryName must be a directory.

If you want to consume a single le only, you can use the leName

option, e.g. by setting fileName=thefilename.

Also, the starting directory must not contain dynamic expressions

with ${ } placeholders. Again use the fileName option to specify

the dynamic part of the lename.

In Camel 1.x you could also congure a le and this caused more harm

than good as it could lead to confusing situations.

Avoid reading les currently being written by another

application

Beware the JDK File IO API is a bit limited in detecting whether

another application is currently writing/copying a le. And the

implementation can be dierent depending on OS platform as well.

This could lead to that Camel thinks the le is not locked by another

process and start consuming it. Therefore you have to do you own

investigation what suites your environment. To help with this Camel

provides dierent readLock options and doneFileOption option

that you can use. See also the section Consuming les from folders

where others drop les directly.

Consumer

Name Default

Value Description

initialDelay 1000 Milliseconds before polling the le/directory starts.

delay 500 Milliseconds before the next poll of the le/directory.

useFixedDelay

Controls if xed delay or xed rate is used. See ScheduledExecutorService in JDK for

details. In Camel 2.7.x or older the default value is false. From Camel 2.8 onwards

the default value is true.

runLoggingLevel TRACE Camel 2.8: The consumer logs a start/complete log line when it polls. This option

allows you to congure the logging level for that.

recursive false If a directory, will look for les in all the sub-directories as well.

delete false If true, the le will be deleted after it is processed

noop false

If true, the le is not moved or deleted in any way. This option is good for readonly

data, or for ETL type requirements. If noop=true, Camel will set idempotent=true as

well, to avoid consuming the same les over and over again.

preMove null

Expression (such as File Language) used to dynamically set the lename when moving

it before processing. For example to move in-progress les into the order directory set

this value to order.

move .camel Expression (such as File Language) used to dynamically set the lename when moving

it after processing. To move les into a .done subdirectory just enter .done.

CHAPTER 11 - COMPONENT APPENDIX 614

moveFailed null

Expression (such as File Language) used to dynamically set a dierent target directory

when moving les after processing (congured via move dened above) failed. For

example, to move les into a .error subdirectory use: .error. Note: When moving the

les to the “fail” location Camel will handle the error and will not pick up the le again.

include null Is used to include les, if lename matches the regex pattern.

exclude null Is used to exclude les, if lename matches the regex pattern.

idempotent false

Option to use the Idempotent Consumer EIP pattern to let Camel skip already processed

les. Will by default use a memory based LRUCache that holds 1000 entries. If

noop=true then idempotent will be enabled as well to avoid consuming the same les

over and over again.

idempotentRepository null

Pluggable repository as a org.apache.camel.processor.idempotent.MessageIdRepository

class. Will by default use MemoryMessageIdRepository if none is specied and

idempotent is true.

inProgressRepository memory

Pluggable in-progress repository as a

org.apache.camel.processor.idempotent.MessageIdRepository class. The in-progress

repository is used to account the current in progress les being consumed. By default a

memory based repository is used.

filter null

Pluggable lter as a org.apache.camel.component.file.GenericFileFilter class.

Will skip les if lter returns false in its accept() method. Camel also ships with an

ANT path matcher lter in the camel-spring component. More details in section

below.

sorter null Pluggable sorter as a

java.util.Comparator<org.apache.camel.component.le.GenericFile> class.

sortBy null

Built-in sort using the File Language. Supports nested sorts, so you can have a sort by

le name and as a 2nd group sort by modied date. See sorting section below for

details.

readLock markerFile

Used by consumer, to only poll the les if it has exclusive read-lock on the le (i.e. the

le is not in-progress or being written). Camel will wait until the le lock is granted.

This option provides the build in strategies:

markerFile is the behaviour from Camel 1.x, where Camel will create a marker le and

hold a lock on the marker le. This option is not avail for the FTP component.

changed is using le length/modication timestamp to detect whether the le is

currently being copied or not. Will at least use 1 sec. to determine this, so this option

cannot consume les as fast as the others, but can be more reliable as the JDK IO API

cannot always determine whether a le is currently being used by another process. This

option is only avail for the FTP component from Camel 2.8 onwards.

fileLock is for using java.nio.channels.FileLock. This option is not avail for the

FTP component.

rename is for using a try to rename the le as a test if we can get exclusive read-lock.

none is for no read locks at all.

readLockTimeout ▪

Optional timeout in millis for the read-lock, if supported by the read-lock. If the read-

lock could not be granted and the timeout triggered, then Camel will skip the le. At

next poll Camel, will try the le again, and this time maybe the read-lock could be

granted. Use a value of 0 or lower to indicate forever. In Camel 2.0 the default value is

0. In Camel 2.1 the default value is 10000. Currently fileLock,changed and rename

support the timeout. For FTP the default readLockTimeout value is 20000.

readLockCheckInterval 1000

Camel 2.6: Interval in millis for the read-lock, if supported by the read lock. This

interval is used for sleeping between attempts to acquire the read lock. For example

when using the changed read lock, you can set a higher interval period to cater for slow

writes. The default of 1 sec. may be too fast if the producer is very slow writing the le.

For FTP the default readLockCheckInterval is 5000.

directoryMustExist false Camel 2.5: Similar to startingDirectoryMustExist but this applies during polling

recursive sub directories.

doneFileName null

Camel 2.6: If provided, Camel will only consume les if a done le exists. This option

congures what le name to use. Either you can specify a xed name. Or you can use

dynamic placeholders. The done le is always expected in the same folder as the

original le. See using done le and writing done le sections for examples.

exclusiveReadLockStrategy null

Pluggable read-lock as a

org.apache.camel.component.file.GenericFileExclusiveReadLockStrategy

implementation.

maxMessagesPerPoll 0

An integer to dene a maximum messages to gather per poll. By default no maximum

is set. Can be used to set a limit of e.g. 1000 to avoid when starting up the server that

there are thousands of les. Set a value of 0 or negative to disabled it. See more details

at Batch Consumer.

minDepth 0

Camel 2.8: The minimum depth to start processing when recursively processing a

directory. Using minDepth=1 means the base directory. Using minDepth=2 means the

rst sub directory. This option is supported by FTP consumer from Camel 2.8.2, 2.9

onwards.

maxDepth Integer.MAX_VALUE Camel 2.8: The maximum depth to traverse when recursively processing a directory.

This option is supported by FTP consumer from Camel 2.8.2, 2.9 onwards.

615 CHAPTER 11 - COMPONENT APPENDIX

processStrategy null

A pluggable org.apache.camel.component.file.GenericFileProcessStrategy

allowing you to implement your own readLock option or similar. Can also be used when

special conditions must be met before a le can be consumed, such as a special ready

le exists. If this option is set then the readLock option does not apply.

startingDirectoryMustExist false

Camel 2.5: Whether the starting directory must exist. Mind that the autoCreate option

is default enabled, which means the starting directory is normally auto created if it

doesn't exist. You can disable autoCreate and enable this to ensure the starting

directory must exist. Will thrown an exception if the directory doesn't exist.

pollStrategy null

Camel 2.0: A pluggable org.apache.camel.PollingConsumerPollStrategy allowing

you to provide your custom implementation to control error handling usually occurred

during the poll operation before an Exchange have been created and being routed in

Camel. In other words the error occurred while the polling was gathering information,

for instance access to a le network failed so Camel cannot access it to scan for les.

The default implementation will log the caused exception at WARN level and ignore it.

sendEmptyMessageWhenIdle false Camel 2.9: If the polling consumer did not poll any les, you can enable this option to

send an empty message (no body) instead.

Default behavior for le consumer

• By default the le is locked for the duration of the processing.

• After the route has completed, les are moved into the .camel

subdirectory, so that they appear to be deleted.

• The File Consumer will always skip any le whose name starts with a

dot, such as .,.camel,.m2 or .groovy.

• Only les (not directories) are matched for valid lename, if options

such as: include or exclude are used.

Producer

Name Default

Value Description

fileExist Override

What to do if a le already exists with the same name. The following values can be specied:

Override,Append,Fail and Ignore.Override, which is the default, replaces the existing le.

Append adds content to the existing le. Fail throws a GenericFileOperationException,

indicating that there is already an existing le. Ignore silently ignores the problem and does not

override the existing le, but assumes everything is okay.

tempPrefix null

This option is used to write the le using a temporary name and then, after the write is complete,

rename it to the real name. Can be used to identify les being written and also avoid consumers

(not using exclusive read locks) reading in progress les. Is often used by FTP when uploading big

les.

tempFileName null Camel 2.1: The same as tempPrefix option but oering a more ne grained control on the naming

of the temporary lename as it uses the File Language.

keepLastModified false

Camel 2.2: Will keep the last modied timestamp from the source le (if any). Will use the

Exchange.FILE_LAST_MODIFIED header to located the timestamp. This header can contain either a

java.util.Date or long with the timestamp. If the timestamp exists and the option is enabled it

will set this timestamp on the written le. Note: This option only applies to the le producer. You

cannot use this option with any of the ftp producers.

eagerDeleteTargetFile true

Camel 2.3: Whether or not to eagerly delete any existing target le. This option only applies when

you use fileExists=Override and the tempFileName option as well. You can use this to disable

(set it to false) deleting the target le before the temp le is written. For example you may write big

les and want the target le to exists during the temp le is being written. This ensure the target

le is only deleted until the very last moment, just before the temp le is being renamed to the

target lename.

doneFileName null

Camel 2.6: If provided, then Camel will write a 2nd done le when the original le has been

written. The done le will be empty. This option congures what le name to use. Either you can

specify a xed name. Or you can use dynamic placeholders. The done le will always be written in

the same folder as the original le. See writing done le section for examples.

CHAPTER 11 - COMPONENT APPENDIX 616

Default behavior for le producer

• By default it will override any existing le, if one exist with the same

name.

Move and Delete operations

Any move or delete operations is executed after (post command) the routing

has completed; so during processing of the Exchange the le is still located in

the inbox folder.

Lets illustrate this with an example:

from("file://inbox?move=.done").to("bean:handleOrder");

When a le is dropped in the inbox folder, the le consumer notices this and

creates a new FileExchange that is routed to the handleOrder bean. The

bean then processes the File object. At this point in time the le is still

located in the inbox folder. After the bean completes, and thus the route is

completed, the le consumer will perform the move operation and move the

le to the .done sub-folder.

The move and preMove options should be a directory name, which can

be either relative or absolute. If relative, the directory is created as a sub-

folder from within the folder where the le was consumed.

By default, Camel will move consumed les to the .camel sub-folder

relative to the directory where the le was consumed.

If you want to delete the le after processing, the route should be:

from("file://inobox?delete=true").to("bean:handleOrder");

We have introduced a pre move operation to move les before they are

processed. This allows you to mark which les have been scanned as they

are moved to this sub folder before being processed.

from("file://inbox?preMove=inprogress").to("bean:handleOrder");

You can combine the pre move and the regular move:

from("file://inbox?preMove=inprogress&move=.done").to("bean:handleOrder");

So in this situation, the le is in the inprogress folder when being processed

and after it's processed, it's moved to the .done folder.

617 CHAPTER 11 - COMPONENT APPENDIX

Override is now default

In Camel 1.x the Append is the default for the le producer. We have

changed this to Override in Camel 2.0 as this is also the default le

operation using java.io.File.

And also the default for the FTP library we use in the camel-ftp

component.

Fine grained control over Move and PreMove option

The move and preMove option is Expression-based, so we have the full

power of the File Language to do advanced conguration of the directory and

name pattern.

Camel will, in fact, internally convert the directory name you enter into a File

Language expression. So when we enter move=.done Camel will convert this

into: ${file:parent}/.done/${file:onlyname}. This is only done if Camel

detects that you have not provided a ${ } in the option value yourself. So

when you enter a ${ } Camel will not convert it and thus you have the full

power.

So if we want to move the le into a backup folder with today's date as the

pattern, we can do:

move=backup/${date:now:yyyyMMdd}/${file:name}

About moveFailed

The moveFailed option allows you to move les that could not be processed

succesfully to another location such as a error folder of your choice. For

example to move the les in an error folder with a timestamp you can use

moveFailed=/error/${file:name.noext}-

${date:now:yyyyMMddHHmmssSSS}.${file:ext}.

See more examples at File Language

Message Headers

The following headers are supported by this component:

File producer only

Header Description

CHAPTER 11 - COMPONENT APPENDIX 618

CamelFileName

Species the name of the le to write (relative to the endpoint directory). The name can be a String; a String with

a File Language or Simple expression; or an Expression object. If it's null then Camel will auto-generate a lename

based on the message unique ID.

CamelFileNameProduced The actual absolute lepath (path + name) for the output le that was written. This header is set by Camel and its

purpose is providing end-users with the name of the le that was written.

File consumer only

Header Description

CamelFileName Name of the consumed le as a relative le path with oset from the starting directory congured on the endpoint.

CamelFileNameOnly Only the le name (the name with no leading paths).

CamelFileAbsolute

Aboolean option specifying whether the consumed le denotes an absolute path or not. Should normally be false

for relative paths. Absolute paths should normally not be used but we added to the move option to allow moving

les to absolute paths. But can be used elsewhere as well.

CamelFileAbsolutePath The absolute path to the le. For relative les this path holds the relative path instead.

CamelFilePath The le path. For relative les this is the starting directory + the relative lename. For absolute les this is the

absolute path.

CamelFileRelativePath The relative path.

CamelFileParent The parent path.

CamelFileLength Along value containing the le size.

CamelFileLastModified ADate value containing the last modied timestamp of the le.

Batch Consumer

This component implements the Batch Consumer.

Exchange Properties, le consumer only

As the le consumer is BatchConsumer it supports batching the les it polls.

By batching it means that Camel will add some properties to the Exchange so

you know the number of les polled the current index in that order.

Property Description

CamelBatchSize The total number of les that was polled in this batch.

CamelBatchIndex The current index of the batch. Starts from 0.

CamelBatchComplete Aboolean value indicating the last Exchange in the batch. Is only true for the last entry.

This allows you for instance to know how many les exists in this batch and

for instance let the Aggregator2 aggregate this number of les.

Common gotchas with folder and lenames

When Camel is producing les (writing les) there are a few gotchas aecting

how to set a lename of your choice. By default, Camel will use the message

ID as the lename, and since the message ID is normally a unique generated

ID, you will end up with lenames such as: ID-

MACHINENAME-2443-1211718892437-1-0. If such a lename is not desired,

619 CHAPTER 11 - COMPONENT APPENDIX

then you must provide a lename in the CamelFileName message header.

The constant, Exchange.FILE_NAME, can also be used.

The sample code below produces les using the message ID as the

lename:

from("direct:report").to("file:target/reports");

To use report.txt as the lename you have to do:

from("direct:report").setHeader(Exchange.FILE_NAME, constant("report.txt")).to(

"file:target/reports");

... the same as above, but with CamelFileName:

from("direct:report").setHeader("CamelFileName", constant("report.txt")).to(

"file:target/reports");

And a syntax where we set the lename on the endpoint with the leName

URI option.

from("direct:report").to("file:target/reports/?fileName=report.txt");

Filename Expression

Filename can be set either using the expression option or as a string-based

File Language expression in the CamelFileName header. See the File

Language for syntax and samples.

Consuming les from folders where others drop les directly

Beware if you consume les from a folder where other applications write les

directly. Take a look at the dierent readLock options to see what suits your

use cases. The best approach is however to write to another folder and after

the write move the le in the drop folder. However if you write les directly to

the drop folder then the option changed could better detect whether a le is

currently being written/copied as it uses a le changed algorithm to see

whether the le size / modication changes over a period of time. The other

read lock options rely on Java File API that sadly is not always very good at

detecting this. You may also want to look at the doneFileName option, which

uses a marker le (done) to signal when a le is done and ready to be

consumed.

CHAPTER 11 - COMPONENT APPENDIX 620

Using done les

Available as of Camel 2.6

See also section writing done les below.

If you want only to consume les when a done le exists, then you can use

the doneFileName option on the endpoint.

from("file:bar?doneFileName=done");

Will only consume les from the bar folder, if a le name done exists in the

same directory as the target les. Camel will automatically delete the done

le when it's done consuming the les.

However its more common to have one done le per target le. This

means there is a 1:1 correlation. To do this you must use dynamic

placeholders in the doneFileName option. Currently Camel supports the

following two dynamic tokens: file:name and file:name.noext which must

be enclosed in ${ }. The consumer only supports the static part of the done

le name as either prex or sux (not both).

from("file:bar?doneFileName=${file:name}.done");

In this example only les will be polled if there exists a done le with the

name le name.done. For example

▪hello.txt - is the le to be consumed

▪hello.txt.done - is the associated done le

You can also use a prex for the done le, such as:

from("file:bar?doneFileName=ready-${file:name}");

▪hello.txt - is the le to be consumed

▪ready-hello.txt - is the associated done le

Writing done les

Available as of Camel 2.6

After you have written af le you may want to write an additional done le

as a kinda of marker, to indicate to others that the le is nished and has

been written. To do that you can use the doneFileName option on the le

producer endpoint.

.to("file:bar?doneFileName=done");

Will simply create a le named done in the same directory as the target le.

621 CHAPTER 11 - COMPONENT APPENDIX

However its more common to have one done le per target le. This

means there is a 1:1 correlation. To do this you must use dynamic

placeholders in the doneFileName option. Currently Camel supports the

following two dynamic tokens: file:name and file:name.noext which must

be enclosed in ${ }.

.to("file:bar?doneFileName=done-${file:name}");

Will for example create a le named done-foo.txt if the target le was

foo.txt in the same directory as the target le.

.to("file:bar?doneFileName=${file:name}.done");

Will for example create a le named foo.txt.done if the target le was

foo.txt in the same directory as the target le.

.to("file:bar?doneFileName=${file:name.noext}.done");

Will for example create a le named foo.done if the target le was foo.txt

in the same directory as the target le.

Samples

Read from a directory and write to another directory

from("file://inputdir/?delete=true").to("file://outputdir")

Listen on a directory and create a message for each le dropped there. Copy

the contents to the outputdir and delete the le in the inputdir.

Reading recursively from a directory and writing to

another

from("file://inputdir/?recursive=true&delete=true").to("file://outputdir")

Listen on a directory and create a message for each le dropped there. Copy

the contents to the outputdir and delete the le in the inputdir. Will scan

recursively into sub-directories. Will lay out the les in the same directory

structure in the outputdir as the inputdir, including any sub-directories.

CHAPTER 11 - COMPONENT APPENDIX 622

inputdir/foo.txt

inputdir/sub/bar.txt

Will result in the following output layout:

outputdir/foo.txt

outputdir/sub/bar.txt

Using atten

If you want to store the les in the outputdir directory in the same directory,

disregarding the source directory layout (e.g. to atten out the path), you

just add the flatten=true option on the le producer side:

from("file://inputdir/

?recursive=true&delete=true").to("file://outputdir?flatten=true")

Will result in the following output layout:

outputdir/foo.txt

outputdir/bar.txt

Reading from a directory and the default move operation

Camel will by default move any processed le into a .camel subdirectory in

the directory the le was consumed from.

from("file://inputdir/?recursive=true&delete=true").to("file://outputdir")

Aects the layout as follows:

before

inputdir/foo.txt

inputdir/sub/bar.txt

after

inputdir/.camel/foo.txt

inputdir/sub/.camel/bar.txt

outputdir/foo.txt

outputdir/sub/bar.txt

623 CHAPTER 11 - COMPONENT APPENDIX

Read from a directory and process the message in java

from("file://inputdir/").process(new Processor() {

public void process(Exchange exchange) throws Exception {

Object body = exchange.getIn().getBody();

// do some business logic with the input body

}

});

The body will be a File object that points to the le that was just dropped

into the inputdir directory.

Read les from a directory and send the content to a jms

queue

from("file://inputdir/").convertBodyTo(String.class).to("jms:test.queue")

By default the le endpoint sends a FileMessage which contains a File

object as the body. If you send this directly to the JMS component the JMS

message will only contain the File object but not the content. By converting

the File to a String, the message will contain the le content which is

probably what you want.

The route above using Spring DSL:

<route>

</route>

Writing to les

Camel is of course also able to write les, i.e. produce les. In the sample

below we receive some reports on the SEDA queue that we process before

they are written to a directory.

public void testToFile() throws Exception {

MockEndpoint mock = getMockEndpoint("mock:result");

mock.expectedMessageCount(1);

mock.expectedFileExists("target/test-reports/report.txt");

template.sendBody("direct:reports","This is a great report");

CHAPTER 11 - COMPONENT APPENDIX 624

assertMockEndpointsSatisfied();

}

protected JndiRegistry createRegistry() throws Exception {

// bind our processor in the registry with the given id

JndiRegistry reg = super.createRegistry();

reg.bind("processReport",new ProcessReport());

return reg;

}

protected RouteBuilder createRouteBuilder() throws Exception {

return new RouteBuilder() {

public void configure() throws Exception {

// the reports from the seda queue is processed by our processor

// before they are written to files in the target/reports directory

from("direct:reports").processRef("processReport").to("file://target/

test-reports", "mock:result");

}

};

}

private static class ProcessReport implements Processor {

public void process(Exchange exchange) throws Exception {

String body = exchange.getIn().getBody(String.class);

// do some business logic here

// set the output to the file

exchange.getOut().setBody(body);

// set the output filename using java code logic, notice that this is done by

setting

// a special header property of the out exchange

exchange.getOut().setHeader(Exchange.FILE_NAME, "report.txt");

}

Write to subdirectory using Exchange.FILE_NAME

Using a single route, it is possible to write a le to any number of

subdirectories. If you have a route setup as such:

<route>

</route>

You can have myBean set the header Exchange.FILE_NAME to values such as:

625 CHAPTER 11 - COMPONENT APPENDIX

Exchange.FILE_NAME = hello.txt => /rootDirectory/hello.txt

Exchange.FILE_NAME = foo/bye.txt => /rootDirectory/foo/bye.txt

This allows you to have a single route to write les to multiple destinations.

Using expression for lenames

In this sample we want to move consumed les to a backup folder using

today's date as a sub-folder name:

from("file://inbox?move=backup/${date:now:yyyyMMdd}/${file:name}").to("...");

See File Language for more samples.

Avoiding reading the same le more than once (idempotent

consumer)

Camel supports Idempotent Consumer directly within the component so it

will skip already processed les. This feature can be enabled by setting the

idempotent=true option.

from("file://inbox?idempotent=true").to("...");

By default Camel uses a in memory based store for keeping track of

consumed les, it uses a least recently used cache holding up to 1000

entries. You can plugin your own implementation of this store by using the

idempotentRepository option using the #sign in the value to indicate it's a

referring to a bean in the Registry with the specied id.

<route>

</route>

Camel will log at DEBUG level if it skips a le because it has been consumed

before:

DEBUG FileConsumer is idempotent and the file has been consumed before. Will skip

this file: target\idempotent\report.txt

CHAPTER 11 - COMPONENT APPENDIX 626

Using a le based idempotent repository

In this section we will use the le based idempotent repository

org.apache.camel.processor.idempotent.FileIdempotentRepository

instead of the in-memory based that is used as default.

This repository uses a 1st level cache to avoid reading the le repository. It

will only use the le repository to store the content of the 1st level cache.

Thereby the repository can survive server restarts. It will load the content of

the le into the 1st level cache upon startup. The le structure is very simple

as it stores the key in separate lines in the le. By default, the le store has a

size limit of 1mb. When the le grows larger Camel will truncate the le

store, rebuilding the content by ushing the 1st level cache into a fresh

empty le.

We congure our repository using Spring XML creating our le idempotent

repository and dene our le consumer to use our repository with the

idempotentRepository using #sign to indicate Registry lookup:

<!-- this is our file based idempotent store configured to use the .filestore.dat as

file -->

<bean id="fileStore"

class="org.apache.camel.processor.idempotent.FileIdempotentRepository">

<!-- the max filesize in bytes for the file. Camel will trunk and flush the cache

if the file gets bigger -->

</bean>

<route>

<from uri="file://target/fileidempotent/

?idempotent=true&idempotentRepository=#fileStore&move=done/${file:name}"/>

</route>

</camelContext>

Using a JPA based idempotent repository

In this section we will use the JPA based idempotent repository instead of the

in-memory based that is used as default.

First we need a persistence-unit in META-INF/persistence.xml where we

need to use the class

org.apache.camel.processor.idempotent.jpa.MessageProcessed as

model.

627 CHAPTER 11 - COMPONENT APPENDIX

<persistence-unit name="idempotentDb" transaction-type="RESOURCE_LOCAL">

<class>org.apache.camel.processor.idempotent.jpa.MessageProcessed</class>

<property name="openjpa.ConnectionURL" value="jdbc:derby:target/

idempotentTest;create=true"/>

<property name="openjpa.ConnectionDriverName"

value="org.apache.derby.jdbc.EmbeddedDriver"/>

</properties>

</persistence-unit>

Then we need to setup a Spring jpaTemplate in the spring XML le:

</bean>

<bean id="entityManagerFactory"

class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean">

<!-- we use idempotentDB as the persitence unit name defined in the

persistence.xml file -->

</bean>

And nally we can create our JPA idempotent repository in the spring XML le

as well:

<!-- we define our jpa based idempotent repository we want to use in the file

consumer -->

<bean id="jpaStore"

class="org.apache.camel.processor.idempotent.jpa.JpaMessageIdRepository">

<constructor-arg index="0" ref="jpaTemplate"/>

<!-- This 2nd parameter is the name (= a cateogry name).

You can have different repositories with different names -->

<constructor-arg index="1" value="FileConsumer"/>

</bean>

And yes then we just need to refer to the jpaStore bean in the le consumer

endpoint using the [[idempotentRepository}} using the #syntax option:

<route>

</route>

CHAPTER 11 - COMPONENT APPENDIX 628

Filter using org.apache.camel.component.le.GenericFileFilter

Camel supports pluggable ltering strategies. You can then congure the

endpoint with such a lter to skip certain les being processed.

In the sample we have built our own lter that skips les starting with

skip in the lename:

public class MyFileFilter implements GenericFileFilter {

public boolean accept(GenericFile pathname) {

// we dont accept any files starting with skip in the name

return !pathname.getFileName().startsWith("skip");

}

And then we can congure our route using the lter attribute to reference

our lter (using #notation) that we have dened in the spring XML le:

<route>

</route>

Filtering using ANT path matcher

The ANT path matcher is shipped out-of-the-box in the camel-spring jar. So

you need to depend on camel-spring if you are using Maven.

The reasons is that we leverage Spring's AntPathMatcher to do the actual

matching.

The le paths is matched with the following rules:

▪?matches one character

▪*matches zero or more characters

▪** matches zero or more directories in a path

The sample below demonstrates how to use it:

<!-- use myFilter as filter to allow setting ANT paths for which files to scan

for -->

<endpoint id="myFileEndpoint" uri="file://target/

antpathmatcher?recursive=true&filter=#myAntFilter"/>

<route>

629 CHAPTER 11 - COMPONENT APPENDIX

</route>

</camelContext>

<bean id="myAntFilter"

class="org.apache.camel.component.file.AntPathMatcherGenericFileFilter">

<!-- exclude all files with bad in name or .xml files. Use comma to seperate

multiple excludes -->

</bean>

Sorting using Comparator

Camel supports pluggable sorting strategies. This strategy it to use the build

in java.util.Comparator in Java. You can then congure the endpoint with

such a comparator and have Camel sort the les before being processed.

In the sample we have built our own comparator that just sorts by le

name:

public class MyFileSorter implements Comparator<GenericFile> {

public int compare(GenericFile o1, GenericFile o2) {

return o1.getFileName().compareToIgnoreCase(o2.getFileName());

}

And then we can congure our route using the sorter option to reference to

our sorter (mySorter) we have dened in the spring XML le:

<route>

</route>

Sorting using sortBy

Camel supports pluggable sorting strategies. This strategy it to use the File

Language to congure the sorting. The sortBy option is congured as

follows:

CHAPTER 11 - COMPONENT APPENDIX 630

URI options can reference beans using the # syntax

In the Spring DSL route about notice that we can refer to beans in

the Registry by prexing the id with #. So writing

sorter=#mySorter, will instruct Camel to go look in the Registry for

a bean with the ID, mySorter.

sortBy=group 1;group 2;group 3;...

Where each group is separated with semi colon. In the simple situations you

just use one group, so a simple example could be:

sortBy=file:name

This will sort by le name, you can reverse the order by prexing reverse:

to the group, so the sorting is now Z..A:

sortBy=reverse:file:name

As we have the full power of File Language we can use some of the other

parameters, so if we want to sort by le size we do:

sortBy=file:length

You can congure to ignore the case, using ignoreCase: for string

comparison, so if you want to use le name sorting but to ignore the case

then we do:

sortBy=ignoreCase:file:name

You can combine ignore case and reverse, however reverse must be specied

rst:

sortBy=reverse:ignoreCase:file:name

In the sample below we want to sort by last modied le, so we do:

sortBy=file:modifed

And then we want to group by name as a 2nd option so les with same

modifcation is sorted by name:

631 CHAPTER 11 - COMPONENT APPENDIX

sortBy=file:modifed;file:name

Now there is an issue here, can you spot it? Well the modied timestamp of

the le is too ne as it will be in milliseconds, but what if we want to sort by

date only and then subgroup by name?

Well as we have the true power of File Language we can use the its date

command that supports patterns. So this can be solved as:

sortBy=date:file:yyyyMMdd;file:name

Yeah, that is pretty powerful, oh by the way you can also use reverse per

group, so we could reverse the le names:

sortBy=date:file:yyyyMMdd;reverse:file:name

Using GenericFileProcessStrategy

The option processStrategy can be used to use a custom

GenericFileProcessStrategy that allows you to implement your own begin,

commit and rollback logic.

For instance lets assume a system writes a le in a folder you should

consume. But you should not start consuming the le before another ready

le has been written as well.

So by implementing our own GenericFileProcessStrategy we can

implement this as:

▪ In the begin() method we can test whether the special ready le

exists. The begin method returns a boolean to indicate if we can

consume the le or not.

▪ in the commit() method we can move the actual le and also delete

the ready le.

Debug logging

This component has log level TRACE that can be helpful if you have

problems.

See Also

• Conguring Camel

• Component

• Endpoint

CHAPTER 11 - COMPONENT APPENDIX 632

• Getting Started

▪ File Language

▪ FTP2

▪ Polling Consumer

FLATPACK COMPONENT

The Flatpack component supports xed width and delimited le parsing via

the FlatPack library.

Notice: This component only supports consuming from atpack les to

Object model. You can not (yet) write from Object model to atpack format.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-flatpack</artifactId>

</dependency>

URI format

flatpack:[delim|fixed]:flatPackConfig.pzmap.xml[?options]

Or for a delimited le handler with no conguration le just use

flatpack:someName[?options]

You can append query options to the URI in the following format,

?option=value&option=value&...

URI Options

Name Default

Value Description

delimiter , The default character delimiter for delimited les.

textQualifier " The text qualier for delimited les.

ignoreFirstRecord true Whether the rst line is ignored for delimited les (for the column headers).

splitRows true As of Camel 1.5, the component can either process each row one by one or the entire content

at once.

633 CHAPTER 11 - COMPONENT APPENDIX

Examples

•flatpack:fixed:foo.pzmap.xml creates a xed-width endpoint

using the foo.pzmap.xml le conguration.

•flatpack:delim:bar.pzmap.xml creates a delimited endpoint using

the bar.pzmap.xml le conguration.

•flatpack:foo creates a delimited endpoint called foo with no le

conguration.

Message Headers

Camel will store the following headers on the IN message:

Header Description

camelFlatpackCounter The current row index. For splitRows=false the counter is the total number of rows.

Message Body

The component delivers the data in the IN message as a

org.apache.camel.component.flatpack.DataSetList object that has

converters for java.util.Map or java.util.List.

Usually you want the Map if you process one row at a time (splitRows=true).

Use List for the entire content (splitRows=false), where each element in

the list is a Map.

Each Map contains the key for the column name and its corresponding value.

For example to get the rstname from the sample below:

Map row = exchange.getIn().getBody(Map.class);

String firstName = row.get("FIRSTNAME");

However, you can also always get it as a List (even for splitRows=true).

The same example:

List data = exchange.getIn().getBody(List.class);

Map row = (Map)data.get(0);

String firstName = row.get("FIRSTNAME");

Header and Trailer records

In Camel 1.5 onwards the header and trailer notions in Flatpack are

supported. However, you must use xed record IDs:

•header for the header record (must be lowercase)

•trailer for the trailer record (must be lowercase)

CHAPTER 11 - COMPONENT APPENDIX 634

The example below illustrates this fact that we have a header and a trailer.

You can omit one or both of them if not needed.

</RECORD>

</RECORD>

Using the endpoint

A common use case is sending a le to this endpoint for further processing in

a separate route. For example:

<route>

</route>

<route>

...

</route>

</camelContext>

You can also convert the payload of each message created to a Map for easy

Bean Integration

FLATPACK DATAFORMAT

The Flatpack component ships with the Flatpack data format that can be

used to format between xed width or delimited text messages to a List of

rows as Map.

▪ marshal = from List<Map<String, Object>> to OutputStream (can

be converted to String)

635 CHAPTER 11 - COMPONENT APPENDIX

▪ unmarshal = from java.io.InputStream (such as a File or String)

to a java.util.List as an

org.apache.camel.component.flatpack.DataSetList instance.

The result of the operation will contain all the data. If you need to

process each row one by one you can split the exchange, using

Splitter.

Notice: The Flatpack library does currently not support header and trailers

for the marshal operation.

Options

The data format has the following options:

Option Default Description

definition null

The atpack pzmap conguration le.

Can be omitted in simpler situations, but

its preferred to use the pzmap.

fixed false Delimited or xed.

ignoreFirstRecord true Whether the rst line is ignored for

delimited les (for the column headers).

textQualifier " If the text is qualied with a char such as

delimiter , The delimiter char (could be ;,or

similar)

parserFactory null Uses the default Flatpack parser factory.

Usage

To use the data format, simply instantiate an instance and invoke the

marhsal or unmarshal operation in the route builder:

FlatpackDataFormat fp = new FlatpackDataFormat();

fp.setDefinition(new ClassPathResource("INVENTORY-Delimited.pzmap.xml"));

...

from("file:order/in").unmarshal(df).to("seda:queue:neworder");

The sample above will read les from the order/in folder and unmarshal the

input using the Flatpack conguration le INVENTORY-Delimited.pzmap.xml

that congures the structure of the les. The result is a DataSetList object

we store on the SEDA queue.

CHAPTER 11 - COMPONENT APPENDIX 636

FlatpackDataFormat df = new FlatpackDataFormat();

df.setDefinition(new ClassPathResource("PEOPLE-FixedLength.pzmap.xml"));

df.setFixed(true);

df.setIgnoreFirstRecord(false);

from("seda:people").marshal(df).convertBodyTo(String.class).to("jms:queue:people");

In the code above we marshal the data from a Object representation as a

List of rows as Maps. The rows as Map contains the column name as the key,

and the the corresponding value. This structure can be created in Java code

from e.g. a processor. We marshal the data according to the Flatpack format

and convert the result as a String object and store it on a JMS queue.

Dependencies

To use Flatpack in your camel routes you need to add the a dependency on

camel-atpack which implements this data format.

If you use maven you could just add the following to your pom.xml,

substituting the version number for the latest & greatest release (see the

download page for the latest versions).

<groupId>org.apache.camel</groupId>

<artifactId>camel-flatpack</artifactId>

</dependency>

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

FREEMARKER

Available as of Camel 1.6

The freemarker: component allows you to process a message using a

FreeMarker template. This can be ideal when using Templating to generate

responses for requests.

Maven users will need to add the following dependency to their pom.xml

for this component:

637 CHAPTER 11 - COMPONENT APPENDIX

<groupId>org.apache.camel</groupId>

<artifactId>camel-freemarker</artifactId>

</dependency>

URI format

freemarker:templateName[?options]

Where templateName is the classpath-local URI of the template to invoke;

or the complete URL of the remote template (eg: le://folder/myle.ftl).

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Option Default Description

contentCache true Cache for the resource content when its loaded.

encoding null Character encoding of the resource content.

Headers

Headers set during the FreeMarker evaluation are returned to the message

and added as headers. Then its kinda possible to return values from

FreeMarker to the Message.

An example: Set the header value of fruit in the FreeMarker template:

${request.setHeader('fruit', 'Apple')}

The header, fruit, is now accessible from the message.out.headers.

FreeMarker Context

Camel will provide exchange information in the FreeMarker context (just a

Map). The Exchange is transfered as:

key value

exchange The Exchange itself.

exchange.properties The Exchange properties.

headers The headers of the In message.

camelContext The Camel Context.

request The In message.

CHAPTER 11 - COMPONENT APPENDIX 638

body The In message body.

response The Out message (only for InOut message exchange pattern).

Hot reloading

The FreeMarker template resource is by default not hot reloadable for both

le and classpath resources (expanded jar). If you set contentCache=false,

then Camel will not cache the resource and hot reloading is thus enabled.

This scenario can be used in development.

Dynamic templates

Camel provides two headers by which you can dene a dierent resource

location for a template or the template content itself. If any of these headers

is set then Camel uses this over the endpoint congured resource. This

allows you to provide a dynamic template at runtime.

Header Type Description Support

Version

FreemarkerConstants.FREEMARKER_RESOURCE org.springframework.core.io.Resource The template resource <= 1.6.2, <=

2.1

FreemarkerConstants.FREEMARKER_RESOURCE_URI String

A URI for the template resource

to use instead of the endpoint

congured.

>= 2.1

FreemarkerConstants.FREEMARKER_TEMPLATE String The template to use instead of

the endpoint congured. >= 2.1

Samples

For example you could use something like:

from("activemq:My.Queue").

to("freemarker:com/acme/MyResponse.ftl");

To use a FreeMarker template to formulate a response for a message for

InOut message exchanges (where there is a JMSReplyTo header).

If you want to use InOnly and consume the message and send it to

another destination you could use:

from("activemq:My.Queue").

to("freemarker:com/acme/MyResponse.ftl").

to("activemq:Another.Queue");

And to disable the content cache, e.g. for development usage where the

.ftl template should be hot reloaded:

639 CHAPTER 11 - COMPONENT APPENDIX

from("activemq:My.Queue").

to("freemarker:com/acme/MyResponse.ftl?contentCache=false").

to("activemq:Another.Queue");

And a le-based resource:

from("activemq:My.Queue").

to("freemarker:file://myfolder/MyResponse.ftl?contentCache=false").

to("activemq:Another.Queue");

In Camel 2.1 it's possible to specify what template the component should

use dynamically via a header, so for example:

from("direct:in").

setHeader(FreemarkerConstants.FREEMARKER_RESOURCE_URI).constant("path/to/my/

template.ftl").

to("freemarker:dummy");

The Email Sample

In this sample we want to use FreeMarker templating for an order

conrmation email. The email template is laid out in FreeMarker as:

Dear ${headers.lastName}, ${headers.firstName}

Thanks for the order of ${headers.item}.

Regards Camel Riders Bookstore

${body}

And the java code:

private Exchange createLetter() {

Exchange exchange = context.getEndpoint("direct:a").createExchange();

Message msg = exchange.getIn();

msg.setHeader("firstName","Claus");

msg.setHeader("lastName","Ibsen");

msg.setHeader("item","Camel in Action");

msg.setBody("PS: Next beer is on me, James");

return exchange;

}

@Test

public void testFreemarkerLetter() throws Exception {

MockEndpoint mock = getMockEndpoint("mock:result");

CHAPTER 11 - COMPONENT APPENDIX 640

mock.expectedMessageCount(1);

mock.expectedBodiesReceived("Dear Ibsen, Claus\n\nThanks for the order of Camel

in Action."

+"\n\nRegards Camel Riders Bookstore\nPS: Next beer is on me, James");

template.send("direct:a", createLetter());

mock.assertIsSatisfied();

}

protected RouteBuilder createRouteBuilder() throws Exception {

return new RouteBuilder() {

public void configure() throws Exception {

from("direct:a")

.to("freemarker:org/apache/camel/component/freemarker/letter.ftl")

.to("mock:result");

}

};

}

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

FTP/SFTP/FTPS COMPONENT - CAMEL 2.0 ONWARDS

This component provides access to remote le systems over the FTP and

SFTP protocols.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-ftp</artifactId>

</dependency>

641 CHAPTER 11 - COMPONENT APPENDIX

Using Camel 1.x

If you are using Camel 1.x then see this link for documentation.

This page is only for Camel 2.0 or newer.

More options

See File2 for more options as all the options from File2 is inherited.

Consuming from remote FTP server

Make sure you read the section titled Default when consuming les

further below for details related to consuming les.

URI format

ftp://[username@]hostname[:port]/directoryname[?options]

sftp://[username@]hostname[:port]/directoryname[?options]

ftps://[username@]hostname[:port]/directoryname[?options]

Where directoryname represents the underlying directory. Can contain

nested folders.

If no username is provided, then anonymous login is attempted using no

password.

If no port number is provided, Camel will provide default values according to

the protocol (ftp = 21, sftp = 22, ftps = 2222).

You can append query options to the URI in the following format,

?option=value&option=value&...

This component uses two dierent libraries for the actual FTP work. FTP

and FTPS uses Apache Commons Net while SFTP uses JCraft JSCH.

The FTPS component is only available in Camel 2.2 or newer.

FTPS (also known as FTP Secure) is an extension to FTP that adds support for

the Transport Layer Security (TLS) and the Secure Sockets Layer (SSL)

cryptographic protocols.

URI Options

The options below are exclusive for the FTP2 component.

CHAPTER 11 - COMPONENT APPENDIX 642

More options

See File2 for more options as all the options from File2 is inherited.

Name Default

Value Description

username null Species the username to use to log in to the remote le systen.

password null Species the password to use to log in to the remote le system.

binary false Species the le transfer mode, BINARY or ASCII. Default is ASCII (false).

disconnect false

Camel 2.2: Whether or not to disconnect from remote FTP server right after use. Can

be used for both consumer and producer. Disconnect will only disconnect the current

connection to the FTP server. If you have a consumer which you want to stop, then you

need to stop the consumer/route instead.

localWorkDirectory null

When consuming, a local work directory can be used to store the remote le content

directly in local les, to avoid loading the content into memory. This is benecial, if you

consume a very big remote le and thus can conserve memory. See below for more

details.

passiveMode false FTP and FTPS only: Species whether to use passive mode connections. Default is

active mode (false).

securityProtocol TLS

FTPS only: Sets the underlying security protocol. The following values are dened:

TLS: Transport Layer Security

SSL: Secure Sockets Layer

disableSecureDataChannelDefaults false

Camel 2.4: FTPS only: Whether or not to disable using default values for execPbsz

and execProt when using secure data transfer. You can set this option to true if you

want to be in absolute full control what the options execPbsz and execProt should be

used.

execProt null

Camel 2.4: FTPS only: Will by default use option Pif secure data channel defaults

hasn't been disabled. Possible values are:

C: Clear

S: Safe (SSL protocol only)

E: Condential (SSL protocol only)

P: Private

execPbsz null

Camel 2.4: FTPS only: This option species the buer size of the secure data

channel. If option useSecureDataChannel has been enabled and this option has not

been explicit set, then value 0is used.

isImplicit false FTPS only: Sets the security mode(implicit/explicit). Default is explicit (false).

knownHostsFile null SFTP only: Sets the known_hosts le, so that the SFTP endpoint can do host key

verication.

privateKeyFile null SFTP only: Set the private key le to that the SFTP endpoint can do private key

verication.

privateKeyFilePassphrase null SFTP only: Set the private key le passphrase to that the SFTP endpoint can do

private key verication.

ciphers null

Camel 2.8.2, 2.9: SFTP only Set a comma separated list of ciphers that will be used

in order of preference. Possible cipher names are dened by JCraft JSCH. Some

examples include: aes128-ctr,aes128-cbc,3des-ctr,3des-cbc,blowsh-

cbc,aes192-cbc,aes256-cbc. If not specied the default list from JSCH will be used.

fastExistsCheck false

Camel 2.8.2, 2.9: If set this option to be true, camel-ftp will use the list le directly to

check if the le exists. Since some FTP server may not support to list the le directly, if

the option is false, camel-ftp will use the old way to list the directory and check if the

le exists.

strictHostKeyChecking no

SFTP only: Camel 2.2: Sets whether to use strict host key checking. Possible values

are: no,yes and ask.ask does not make sense to use as Camel cannot answer the

question for you as its meant for human intervention. Note: The default in Camel 2.1

and below was ask.

maximumReconnectAttempts 3 Species the maximum reconnect attempts Camel performs when it tries to connect to

the remote FTP server. Use 0 to disable this behavior.

reconnectDelay 1000 Delay in millis Camel will wait before performing a reconnect attempt.

connectTimeout 10000

Camel 2.4: Is the connect timeout in millis. This corresponds to using

ftpClient.connectTimeout for the FTP/FTPS. For SFTP this option is also used when

attempting to connect.

soTimeout null FTP and FTPS Only: Camel 2.4: Is the SocketOptions.SO_TIMEOUT value in millis.

Note SFTP will automatic use the connectTimeout as the soTimeout.

643 CHAPTER 11 - COMPONENT APPENDIX

timeout 30000 FTP and FTPS Only: Camel 2.4: Is the data timeout in millis. This corresponds to

using ftpClient.dataTimeout for the FTP/FTPS. For SFTP there is no data timeout.

throwExceptionOnConnectFailed false

Camel 2.5: Whether or not to thrown an exception if a successful connection and

exception, for example to stop the consumer or the likes.

siteCommand null

FTP and FTPS Only: Camel 2.5: To execute site commands after successful login.

Multiple site commands can be separated using a new line character (\n). Use help

site to see which site commands your FTP server supports.

stepwise true

Camel 2.6: Whether or not stepwise traversing directories should be used or not.

Stepwise means that it will CD one directory at a time. See more details below. You can

disable this in case you can't use this approach.

separator Auto

Camel 2.6: Dictates what path separator char to use when uploading les. Auto =

Use the path provided without altering it. UNIX = Use unix style path separators.

Windows = Use Windows style path separators.

chmod null SFTP Producer Only: Camel 2.9: Allows you to set chmod on the stored le. For

example chmod=640.

compression 0

SFTP Only: Camel 2.9: To use compression. Specify a level from 1 to 10. Important:

You must manually add the needed JSCH zlib JAR to the classpath for compression

support.

ftpClient null FTP and FTPS Only: Camel 2.1: Allows you to use a custom

org.apache.commons.net.ftp.FTPClient instance.

ftpClientConfig null FTP and FTPS Only: Camel 2.1: Allows you to use a custom

org.apache.commons.net.ftp.FTPClientConfig instance.

serverAliveInterval 0 SFTP Only: Camel 2.8 Allows you to set the serverAliveInterval of the sftp session

serverAliveCountMax 1 SFTP Only: Camel 2.8 Allows you to set the serverAliveCountMax of the sftp session

ftpClient.trustStore.file null FTPS Only: Sets the trust store le, so that the FTPS client can look up for trusted

certicates.

ftpClient.trustStore.type JKS FTPS Only: Sets the trust store type.

ftpClient.trustStore.algorithm SunX509 FTPS Only: Sets the trust store algorithm.

ftpClient.trustStore.password null FTPS Only: Sets the trust store password.

ftpClient.keyStore.file null FTPS Only: Sets the key store le, so that the FTPS client can look up for the private

certicate.

ftpClient.keyStore.type JKS FTPS Only: Sets the key store type.

ftpClient.keyStore.algorithm SunX509 FTPS Only: Sets the key store algorithm.

ftpClient.keyStore.password null FTPS Only: Sets the key store password.

ftpClient.keyStore.keyPassword null FTPS Only: Sets the private key password.

You can congure additional options on the ftpClient and ftpClientConfig

from the URI directly by using the ftpClient. or ftpClientConfig. prex.

For example to set the setDataTimeout on the FTPClient to 30 seconds

you can do:

from("ftp://foo@myserver?password=secret&ftpClient.dataTimeout=30000").to("bean:foo");

You can mix and match and have use both prexes, for example to congure

date format or timezones.

from("ftp://foo@myserver?password=secret&ftpClient.dataTimeout=30000&ftpClientConfig.serverLanguageCode=fr").to("bean:foo");

You can have as many of these options as you like.

See the documentation of the Apache Commons FTP FTPClientCong for

possible options and more details.

And as well for Apache Commons FTP FTPClient.

CHAPTER 11 - COMPONENT APPENDIX 644

FTPS component default trust store

By default, the FTPS component trust store accept all certicates. If

you only want trust selective certicates, you have to congure the

trust store with the ftpClient.trustStore.xxx options or by

conguring a custom ftpClient.

If you do not like having many and long conguration in the url you can

refer to the ftpClient or ftpClientConfig to use by letting Camel lookup in

the Registry for it.

For example:

</bean>

And then let Camel lookup this bean when you use the # notation in the url.

from("ftp://foo@myserver?password=secret&ftpClientConfig=#myConfig").to("bean:foo");

More URI options

Examples

ftp://someone@someftpserver.com/public/upload/images/

holiday2008?password=secret&binary=true

ftp://someoneelse@someotherftpserver.co.uk:12049/reports/2008/

password=secret&binary=false

ftp://publicftpserver.com/download

Default when consuming les

The FTP consumer will by default leave the consumed les untouched on the

remote FTP server. You have to congure it explicitly if you want it to delete

the les or move them to another location. For example you can use

delete=true to delete the les, or use move=.done to move the les into a

hidden done sub directory.

The regular File consumer is dierent as it will by default move les to a

.camel sub directory. The reason Camel does not do this by default for the

645 CHAPTER 11 - COMPONENT APPENDIX

See File2 as all the options there also applies for this component.

FTP Consumer does not support concurrency

The FTP consumer (with the same endpoint) does not support

concurrency (the backing FTP client is not thread safe).

You can use multiple FTP consumers to poll from dierent

endpoints. It is only a single endpoint that does not support

concurrent consumers.

The FTP producer does not have this issue, it supports concurrency.

More information

This component is an extension of the File2 component. So there

are more samples and details on the File2 component page.

FTP consumer is that it may lack permissions by default to be able to move

or delete les.

limitations

The option readLock can be used to force Camel not to consume les that

is currently in the progress of being written. However, this option is turned o

by default, as it requires that the user has write access. See the options table

at File2 for more details about read locks.

There are other solutions to avoid consuming les that are currently being

written over FTP; for instance, you can write to a temporary destination and

move the le after it has been written.

When moving les using move or preMove option the les are restricted to

the FTP_ROOT folder. That prevents you from moving les outside the FTP

area. If you want to move les to another area you can use soft links and

move les into a soft linked folder.

Message Headers

The following message headers can be used to aect the behavior of the

component

CHAPTER 11 - COMPONENT APPENDIX 646

Header Description

CamelFileName

Species the output le name (relative to the endpoint directory) to be used for the output message when sending

to the endpoint. If this is not present and no expression either, then a generated message ID is used as the

lename instead.

CamelFileNameProduced The actual absolute lepath (path + name) for the output le that was written. This header is set by Camel and its

purpose is providing end-users the name of the le that was written.

CamelFileBatchIndex Current index out of total number of les being consumed in this batch.

CamelFileBatchSize Total number of les being consumed in this batch.

CamelFileHost The remote hostname.

CamelFileLocalWorkPath Path to the local work le, if local work directory is used.

About timeouts

The two set of libraries (see top) has dierent API for setting timeout. You can

use the connectTimeout option for both of them to set a timeout in millis to

establish a network connection. An individual soTimeout can also be set on

the FTP/FTPS, which corresponds to using ftpClient.soTimeout. Notice

SFTP will automatically use connectTimeout as its soTimeout. The timeout

option only applies for FTP/FTSP as the data timeout, which corresponds to

the ftpClient.dataTimeout value. All timeout values are in millis.

Using Local Work Directory

Camel supports consuming from remote FTP servers and downloading the

les directly into a local work directory. This avoids reading the entire remote

le content into memory as it is streamed directly into the local le using

FileOutputStream.

Camel will store to a local le with the same name as the remote le,

though with .inprogress as extension while the le is being downloaded.

Afterwards, the le is renamed to remove the .inprogress sux. And nally,

when the Exchange is complete the local le is deleted.

So if you want to download les from a remote FTP server and store it as

les then you need to route to a le endpoint such as:

from("ftp://someone@someserver.com?password=secret&localWorkDirectory=/

tmp").to("file://inbox");

Stepwise changing directories

Camel FTP can operate in two modes in terms of traversing directories when

consuming les (eg downloading) or producing les (eg uploading)

▪ stepwise

▪ not stepwise

647 CHAPTER 11 - COMPONENT APPENDIX

Optimization by renaming work le

The route above is ultra ecient as it avoids reading the entire le

content into memory. It will download the remote le directly to a

local le stream. The java.io.File handle is then used as the

Exchange body. The le producer leverages this fact and can work

directly on the work le java.io.File handle and perform a

java.io.File.rename to the target lename. As Camel knows it's a

local work le, it can optimize and use a rename instead of a le

copy, as the work le is meant to be deleted anyway.

You may want to pick either one depending on your situation and security

issues. Some Camel end users can only download les if they use stepwise,

while others can only download if they do not. At least you have the choice to

pick (from Camel 2.6 onwards).

In Came 2.0 - 2.5 there is only one mode and it is:

▪ 2.0 to 2.4 not stepwise

▪ 2.5 stepwise

From Camel 2.6 onwards there is now an option stepwise you can use to

control the behavior.

Note that stepwise changing of directory will in most cases only work

when the user is conned to it's home directory and when the home

directory is reported as "/".

The dierence between the two of them is best illustrated with an

example. Suppose we have the following directory structure on the remote

FTP server we need to traverse and download les:

/one

/one/two

/one/two/sub-a

/one/two/sub-b

And that we have a le in each of sub-a (a.txt) and sub-b (b.txt) folder.

Using stepwise=true (default mode)

TYPE A

200 Type set to A

PWD

257 "/" is current directory.

CHAPTER 11 - COMPONENT APPENDIX 648

CWD one

250 CWD successful. "/one" is current directory.

CWD two

250 CWD successful. "/one/two" is current directory.

SYST

215 UNIX emulated by FileZilla

PORT 127,0,0,1,17,94

200 Port command successful

LIST

150 Opening data channel for directory list.

226 Transfer OK

CWD sub-a

250 CWD successful. "/one/two/sub-a" is current directory.

PORT 127,0,0,1,17,95

200 Port command successful

LIST

150 Opening data channel for directory list.

226 Transfer OK

CDUP

200 CDUP successful. "/one/two" is current directory.

CWD sub-b

250 CWD successful. "/one/two/sub-b" is current directory.

PORT 127,0,0,1,17,96

200 Port command successful

LIST

150 Opening data channel for directory list.

226 Transfer OK

CDUP

200 CDUP successful. "/one/two" is current directory.

CWD /

250 CWD successful. "/" is current directory.

PWD

257 "/" is current directory.

CWD one

250 CWD successful. "/one" is current directory.

CWD two

250 CWD successful. "/one/two" is current directory.

PORT 127,0,0,1,17,97

200 Port command successful

RETR foo.txt

150 Opening data channel for file transfer.

226 Transfer OK

CWD /

250 CWD successful. "/" is current directory.

PWD

257 "/" is current directory.

CWD one

250 CWD successful. "/one" is current directory.

CWD two

250 CWD successful. "/one/two" is current directory.

CWD sub-a

250 CWD successful. "/one/two/sub-a" is current directory.

PORT 127,0,0,1,17,98

200 Port command successful

649 CHAPTER 11 - COMPONENT APPENDIX

RETR a.txt

150 Opening data channel for file transfer.

226 Transfer OK

CWD /

250 CWD successful. "/" is current directory.

PWD

257 "/" is current directory.

CWD one

250 CWD successful. "/one" is current directory.

CWD two

250 CWD successful. "/one/two" is current directory.

CWD sub-b

250 CWD successful. "/one/two/sub-b" is current directory.

PORT 127,0,0,1,17,99

200 Port command successful

RETR b.txt

150 Opening data channel for file transfer.

226 Transfer OK

CWD /

250 CWD successful. "/" is current directory.

QUIT

221 Goodbye

disconnected.

As you can see when stepwise is enabled, it will traverse the directory

structure using CD xxx.

Using stepwise=false

230 Logged on

TYPE A

200 Type set to A

SYST

215 UNIX emulated by FileZilla

PORT 127,0,0,1,4,122

200 Port command successful

LIST one/two

150 Opening data channel for directory list

226 Transfer OK

PORT 127,0,0,1,4,123

200 Port command successful

LIST one/two/sub-a

150 Opening data channel for directory list

226 Transfer OK

PORT 127,0,0,1,4,124

200 Port command successful

LIST one/two/sub-b

150 Opening data channel for directory list

226 Transfer OK

PORT 127,0,0,1,4,125

CHAPTER 11 - COMPONENT APPENDIX 650

200 Port command successful

RETR one/two/foo.txt

150 Opening data channel for file transfer.

226 Transfer OK

PORT 127,0,0,1,4,126

200 Port command successful

RETR one/two/sub-a/a.txt

150 Opening data channel for file transfer.

226 Transfer OK

PORT 127,0,0,1,4,127

200 Port command successful

RETR one/two/sub-b/b.txt

150 Opening data channel for file transfer.

226 Transfer OK

QUIT

221 Goodbye

disconnected.

As you can see when not using stepwise, there are no CD operation invoked

at all.

Samples

In the sample below we set up Camel to download all the reports from the

FTP server once every hour (60 min) as BINARY content and store it as les

on the local le system.

protected RouteBuilder createRouteBuilder() throws Exception {

return new RouteBuilder() {

public void configure() throws Exception {

// we use a delay of 60 minutes (eg. once pr. hour we poll the FTP server

long delay = 60 * 60 * 1000L;

// from the given FTP server we poll (= download) all the files

// from the public/reports folder as BINARY types and store this as files

// in a local directory. Camel will use the filenames from the FTPServer

// notice that the FTPConsumer properties must be prefixed with

"consumer." in the URL

// the delay parameter is from the FileConsumer component so we should

use consumer.delay as

// the URI parameter name. The FTP Component is an extension of the File

Component.

from("ftp://tiger:scott@localhost/public/reports?binary=true&consumer.delay=" +

delay).

to("file://target/test-reports");

}

};

}

651 CHAPTER 11 - COMPONENT APPENDIX

And the route using Spring DSL:

<route>

<from uri="ftp://scott@localhost/public/

reports?password=tiger&binary=true&delay=60000"/>

</route>

Consuming a remote FTPS server (implicit SSL) and

client authentication

from("ftps://admin@localhost:2222/public/camel?password=admin&securityProtocol=SSL&isImplicit=true

&ftpClient.keyStore.file=./src/test/resources/server.jks

&ftpClient.keyStore.password=password&ftpClient.keyStore.keyPassword=password")

.to("bean:foo");

Consuming a remote FTPS server (explicit TLS) and a

custom trust store conguration

from("ftps://admin@localhost:2222/public/camel?password=admin&ftpClient.trustStore.file=./

src/test/resources/server.jks&ftpClient.trustStore.password=password")

.to("bean:foo");

Filter using org.apache.camel.component.file.GenericFileFilter

Camel supports pluggable ltering strategies. This strategy it to use the build

in org.apache.camel.component.file.GenericFileFilter in Java. You can

then congure the endpoint with such a lter to skip certain lters before

being processed.

In the sample we have built our own lter that only accepts les starting

with report in the lename.

public class MyFileFilter implements GenericFileFilter {

public boolean accept(GenericFile file) {

// we only want report files

return file.getFileName().startsWith("report");

}

CHAPTER 11 - COMPONENT APPENDIX 652

And then we can congure our route using the lter attribute to reference

our lter (using #notation) that we have dened in the spring XML le:

<route>

<from

uri="ftp://someuser@someftpserver.com?password=secret&filter=#myFilter"/>

</route>

Filtering using ANT path matcher

The ANT path matcher is a lter that is shipped out-of-the-box in the camel-

spring jar. So you need to depend on camel-spring if you are using Maven.

The reason is that we leverage Spring's AntPathMatcher to do the actual

matching.

The le paths are matched with the following rules:

▪?matches one character

▪*matches zero or more characters

▪** matches zero or more directories in a path

The sample below demonstrates how to use it:

<!-- use myFilter as filter to allow setting ANT paths for which files to scan

for -->

<endpoint id="myFTPEndpoint" uri="ftp://admin@localhost:20123/

antpath?password=admin&recursive=true&delay=10000&initialDelay=2000&filter=#myAntFilter"/>

<route>

</route>

</camelContext>

<!-- we use the AntPathMatcherRemoteFileFilter to use ant paths for includes and

exlucde -->

<bean id="myAntFilter"

class="org.apache.camel.component.file.AntPathMatcherGenericFileFilter">

<!-- exclude all files with bad in name or .xml files. Use comma to seperate

multiple excludes -->

</bean>

653 CHAPTER 11 - COMPONENT APPENDIX

Debug logging

This component has log level TRACE that can be helpful if you have

problems.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ File2

CAMEL COMPONENTS FOR GOOGLE APP ENGINE

The Camel components for Google App Engine (GAE) are part of the camel-

gae project and provide connectivity to GAE's cloud computing services. They

make the GAE cloud computing environment accessible to applications via

Camel interfaces. Following this pattern for other cloud computing

environments could make it easier to port Camel applications from one cloud

computing provider to another. The following table lists the cloud computing

services provided by Google and the supporting Camel components. The

documentation of each component can be found by following the link in the

Camel Component column.

GAE

service

Camel

component Component description

URL fetch

service ghttp Provides connectivity to the GAE URL fetch service but can also be used to receive messages from

servlets.

Task

queueing

service

gtask Supports asynchronous message processing on GAE by using the task queueing service as message

queue.

Mail service gmail Supports sending of emails via the GAE mail service. Receiving mails is not supported yet but will be

added later.

Memcache

service Not supported yet.

XMPP service Not supported yet.

Images

service Not supported yet.

Datastore

service Not supported yet.

Accounts

service

gauth

glogin

These components interact with the Google Accounts API for authentication and authorization. Google

Accounts is not specic to Google App Engine but is often used by GAE applications for implementing

security. The gauth component is used by web applications to implement a Google-specic OAuth

consumer. This component can also be used to OAuth-enable non-GAE web applications. The glogin

component is used by Java clients (outside GAE) for programmatic login to GAE applications. For

instructions how to protect GAE applications against unauthorized access refer to the Security for Camel

GAE applications page.

CHAPTER 11 - COMPONENT APPENDIX 654

Tutorials

• A good starting point for using Camel on GAE is the Tutorial

for Camel on Google App Engine

• The OAuth tutorial demonstrates how to implement OAuth

in web applications.

Camel context

Setting up a SpringCamelContext on Google App Engine diers between

Camel 2.1 and higher versions. The problem is that usage of the Camel-

specic Spring conguration XML schema from the

http://camel.apache.org/schema/spring namespace requires JAXB and

Camel 2.1 depends on a Google App Engine SDK version that doesn't support

JAXB yet. This limitation has been removed since Camel 2.2.

JMX must be disabled in any case because the javax.management package

isn't on the App Engine JRE whitelist.

Camel 2.1

camel-gae 2.1 comes with the following CamelContext implementations.

•org.apache.camel.component.gae.context.GaeDefaultCamelContext

(extends org.apache.camel.impl.DefaultCamelContext)

•org.apache.camel.component.gae.context.GaeSpringCamelContext

(extends org.apache.camel.spring.SpringCamelContext)

Both disable JMX before startup. The GaeSpringCamelContext additionally

provides setter methods adding route builders as shown in the next example.

Listing 75. appctx.xml

<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">

<bean id="camelContext"

class="org.apache.camel.component.gae.context.GaeSpringCamelContext">

</bean>

<bean id="myRouteBuilder"

class="org.example.MyRouteBuilder">

</bean>

</beans>

655 CHAPTER 11 - COMPONENT APPENDIX

Alternatively, use the routeBuilders property of the

GaeSpringCamelContext for setting a list of route builders. Using this

approach, a SpringCamelContext can be congured on GAE without the

need for JAXB.

Camel 2.2 or higher

With Camel 2.2 or higher, applications can use the

http://camel.apache.org/schema/spring namespace for conguring a

SpringCamelContext but still need to disable JMX. Here's an example.

Listing 76. appctx.xml

<beans xmlns="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:camel="http://camel.apache.org/schema/spring"

xsi:schemaLocation="

http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans-2.5.xsd

http://camel.apache.org/schema/spring

http://camel.apache.org/schema/spring/camel-spring.xsd">

<camel:camelContext id="camelContext">

<camel:jmxAgent id="agent" disabled="true" />

<camel:routeBuilder ref="myRouteBuilder"/>

</camel:camelContext>

<bean id="myRouteBuilder"

class="org.example.MyRouteBuilder">

</bean>

</beans>

The web.xml

Running Camel on GAE requires usage of the CamelHttpTransportServlet

from camel-servlet. The following example shows how to congure this

servlet together with a Spring application context XML le.

Listing 77. web.xml

<web-app

xmlns="http://java.sun.com/xml/ns/javaee"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"

xsi:schemaLocation="

http://java.sun.com/xml/ns/javaee

http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" version="2.5">

CHAPTER 11 - COMPONENT APPENDIX 656

<servlet-name>CamelServlet</servlet-name>

<servlet-class>org.apache.camel.component.servlet.CamelHttpTransportServlet</servlet-class>

<init-param>

<param-name>contextConfigLocation</param-name>

<param-value>appctx.xml</param-value>

</init-param>

</servlet>

<!--

Mapping used for external requests

-->

<servlet-mapping>

<servlet-name>CamelServlet</servlet-name>

<url-pattern>/camel/*</url-pattern>

</servlet-mapping>

<!--

Mapping used for web hooks accessed by task queueing service.

-->

<servlet-mapping>

<servlet-name>CamelServlet</servlet-name>

<url-pattern>/worker/*</url-pattern>

</servlet-mapping>

</web-app>

The location of the Spring application context XML le is given by the

contextConfigLocation init parameter. The appctx.xml le must be on the

classpath. The servlet mapping makes the Camel application accessible

under http://<appname>.appspot.com/camel/... when deployed to

Google App Engine where <appname> must be replaced by a real GAE

application name. The second servlet mapping is used internally by the task

queueing service for background processing via web hooks. This mapping is

relevant for the gtask component and is explained there in more detail.

HAZELCAST COMPONENT

Available as of Camel 2.7

The hazelcast: component allows you to work with the Hazelcast

distributed data grid / cache. Hazelcast is a in memory data grid, entirely

written in Java (single jar). It oers a great palette of dierent data stores like

map, multi map (same key, n values), queue, list and atomic number. The

main reason to use Hazelcast is its simple cluster support. If you have

enabled multicast on your network you can run a cluster with hundred nodes

with no extra conguration. Hazelcast can simply congured to add

additional features like n copies between nodes (default is 1), cache

657 CHAPTER 11 - COMPONENT APPENDIX

persistence, network conguration (if needed), near cache, enviction and so

on. For more information consult the Hazelcast documentation on

http://www.hazelcast.com/documentation.jsp.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-hazelcast</artifactId>

</dependency>

URI format

instance]:cachename[?options]

Sections

1. Usage of map

2. Usage of multimap

3. Usage of queue

4. Usage of list

5. Usage of seda

6. Usage of atomic number

7. Usage of cluster support (instance)

Usage of Map

map cache producer - to("hazelcast:map:foo")

If you want to store a value in a map you can use the map cache producer.

The map cache producer provides 5 operations (put, get, update, delete,

query). For the rst 4 you have to provide the operation inside the

"hazelcast.operation.type" header variable. In Java DSL you can use the

constants from

org.apache.camel.component.hazelcast.HazelcastConstants.

Header Variables for the request message:

Name Type Description

CHAPTER 11 - COMPONENT APPENDIX 658

You have to use the second prex to dene which type of data store

you want to use.

hazelcast.operation.type String valid values are: put, delete, get,

update, query

hazelcast.objectId String

the object id to store / nd your

object inside the cache (not

needed for the query operation)

Name Type Description

CamelHazelcastOperationType String

valid values are: put, delete,

get, update, query [Version

2.8]

CamelHazelcastObjectId String

the object id to store / nd

your object inside the cache

(not needed for the query

operation) [Version 2.8]

You can call the samples with:

template.sendBodyAndHeader("direct:[put|get|update|delete|query]","my-foo",

HazelcastConstants.OBJECT_ID, "4711");

Sample for put:

Java DSL:

from("direct:put")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.PUT_OPERATION))

.toF("hazelcast:%sfoo", HazelcastConstants.MAP_PREFIX);

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

</setHeader>

659 CHAPTER 11 - COMPONENT APPENDIX

Header variables have changed in Camel 2.8

</route>

Sample for get:

Java DSL:

from("direct:get")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.GET_OPERATION))

.toF("hazelcast:%sfoo", HazelcastConstants.MAP_PREFIX)

.to("seda:out");

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

</setHeader>

</route>

Sample for update:

Java DSL:

from("direct:update")

.setHeader(HazelcastConstants.OPERATION,

constant(HazelcastConstants.UPDATE_OPERATION))

.toF("hazelcast:%sfoo", HazelcastConstants.MAP_PREFIX);

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

CHAPTER 11 - COMPONENT APPENDIX 660

<constant>update</constant>

</setHeader>

</route>

Sample for delete:

Java DSL:

from("direct:delete")

.setHeader(HazelcastConstants.OPERATION,

constant(HazelcastConstants.DELETE_OPERATION))

.toF("hazelcast:%sfoo", HazelcastConstants.MAP_PREFIX);

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

<constant>delete</constant>

</setHeader>

</route>

Sample for query

Java DSL:

from("direct:query")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.QUERY_OPERATION))

.toF("hazelcast:%sfoo", HazelcastConstants.MAP_PREFIX)

.to("seda:out");

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

<constant>query</constant>

</setHeader>

661 CHAPTER 11 - COMPONENT APPENDIX

</route>

For the query operation Hazelcast oers a SQL like syntax to query your

distributed map.

String q1 = "bar > 1000";

template.sendBodyAndHeader("direct:query",null, HazelcastConstants.QUERY, q1);

map cache consumer - from("hazelcast:map:foo")

Hazelcast provides event listeners on their data grid. If you want to be

notied if a cache will be manipulated, you can use the map consumer.

There're 4 events: put,update,delete and envict. The event type will be

stored in the "hazelcast.listener.action" header variable. The map

consumer provides some additional information inside these variables:

Header Variables inside the response message:

Name Type Description

hazelcast.listener.time Long time of the event in millis

hazelcast.listener.type String the map consumer sets here

"cachelistener"

hazelcast.listener.action String

type of event - here added,

updated,envicted and

removed

hazelcast.objectId String the oid of the object

hazelcast.cache.name String the name of the cache - e.g.

"foo"

hazelcast.cache.type String the type of the cache - here map

Name Type Description

CamelHazelcastListenerTime Long time of the event in millis

[Version 2.8]

CamelHazelcastListenerType String

the map consumer sets here

"cachelistener" [Version

2.8]

CHAPTER 11 - COMPONENT APPENDIX 662

Header variables have changed in Camel 2.8

CamelHazelcastListenerAction String

type of event - here added,

updated,envicted and

removed.[Version 2.8]

CamelHazelcastObjectId String the oid of the object

[Version 2.8]

CamelHazelcastCacheName String the name of the cache - e.g.

"foo" [Version 2.8]

CamelHazelcastCacheType String the type of the cache - here

map [Version 2.8]

The object value will be stored within put and update actions inside the

message body.

Here's a sample:

fromF("hazelcast:%sfoo", HazelcastConstants.MAP_PREFIX)

.log("object...")

.choice()

.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ADDED))

.log("...added")

.to("mock:added")

.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ENVICTED))

.log("...envicted")

.to("mock:envicted")

.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.UPDATED))

.log("...updated")

.to("mock:updated")

.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.REMOVED))

.log("...removed")

.to("mock:removed")

.otherwise()

.log("fail!");

663 CHAPTER 11 - COMPONENT APPENDIX

Usage of Multi Map

multimap cache producer - to("hazelcast:multimap:foo")

A multimap is a cache where you can store n values to one key. The

multimap producer provides 4 operations (put, get, removevalue, delete).

Header Variables for the request message:

Name Type Description

hazelcast.operation.type String valid values are: put, get,

removevalue, delete

hazelcast.objectId String the object id to store / nd your

object inside the cache

Name Type Description

CamelHazelcastOperationType String

valid values are: put, delete,

get, update, query Available

as of Camel 2.8

CamelHazelcastObjectId String

the object id to store / nd

your object inside the cache

(not needed for the query

operation) [Version 2.8]

You can call the samples with:

template.sendBodyAndHeader("direct:[put|get|update|delete|query]","my-foo",

HazelcastConstants.OBJECT_ID, "4711");

Sample for put:

Java DSL:

from("direct:put")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.PUT_OPERATION))

.toF("hazelcast:%sfoo", HazelcastConstants.MAP_PREFIX);

Spring DSL:

<route>

CHAPTER 11 - COMPONENT APPENDIX 664

Header variables have changed in Camel 2.8

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

</setHeader>

</route>

Sample for get:

Java DSL:

from("direct:get")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.GET_OPERATION))

.toF("hazelcast:%sfoo", HazelcastConstants.MAP_PREFIX)

.to("seda:out");

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

</setHeader>

</route>

Sample for update:

Java DSL:

from("direct:update")

.setHeader(HazelcastConstants.OPERATION,

constant(HazelcastConstants.UPDATE_OPERATION))

.toF("hazelcast:%sfoo", HazelcastConstants.MAP_PREFIX);

Spring DSL:

665 CHAPTER 11 - COMPONENT APPENDIX

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

<constant>update</constant>

</setHeader>

</route>

Sample for delete:

Java DSL:

from("direct:delete")

.setHeader(HazelcastConstants.OPERATION,

constant(HazelcastConstants.DELETE_OPERATION))

.toF("hazelcast:%sfoo", HazelcastConstants.MAP_PREFIX);

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

<constant>delete</constant>

</setHeader>

</route>

Sample for query

Java DSL:

from("direct:query")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.QUERY_OPERATION))

.toF("hazelcast:%sfoo", HazelcastConstants.MAP_PREFIX)

.to("seda:out");

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

CHAPTER 11 - COMPONENT APPENDIX 666

<constant>query</constant>

</setHeader>

</route>

For the query operation Hazelcast oers a SQL like syntax to query your

distributed map.

String q1 = "bar > 1000";

template.sendBodyAndHeader("direct:query",null, HazelcastConstants.QUERY, q1);

map cache consumer - from("hazelcast:map:foo")

Hazelcast provides event listeners on their data grid. If you want to be

notied if a cache will be manipulated, you can use the map consumer.

There're 4 events: put,update,delete and envict. The event type will be

stored in the "hazelcast.listener.action" header variable. The map

consumer provides some additional information inside these variables:

Header Variables inside the response message:

Name Type Description

hazelcast.listener.time Long time of the event in millis

hazelcast.listener.type String the map consumer sets here

"cachelistener"

hazelcast.listener.action String

type of event - here added,

updated,envicted and

removed

hazelcast.objectId String the oid of the object

hazelcast.cache.name String the name of the cache - e.g.

"foo"

hazelcast.cache.type String the type of the cache - here map

Name Type Description

CamelHazelcastListenerTime Long time of the event in millis

[Version 2.8]

CamelHazelcastListenerType String

the map consumer sets here

"cachelistener" [Version

2.8]

667 CHAPTER 11 - COMPONENT APPENDIX

Header variables have changed in Camel 2.8

CamelHazelcastListenerAction String

type of event - here added,

updated,envicted and

removed.[Version 2.8]

CamelHazelcastObjectId String the oid of the object

[Version 2.8]

CamelHazelcastCacheName String the name of the cache - e.g.

"foo" [Version 2.8]

CamelHazelcastCacheType String the type of the cache - here

map [Version 2.8]

The object value will be stored within put and update actions inside the

message body.

Here's a sample:

fromF("hazelcast:%sfoo", HazelcastConstants.MAP_PREFIX)

.log("object...")

.choice()

.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ADDED))

.log("...added")

.to("mock:added")

.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ENVICTED))

.log("...envicted")

.to("mock:envicted")

.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.UPDATED))

.log("...updated")

.to("mock:updated")

.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.REMOVED))

.log("...removed")

.to("mock:removed")

.otherwise()

.log("fail!");

CHAPTER 11 - COMPONENT APPENDIX 668

Usage of Multi Map

multimap cache producer - to("hazelcast:multimap:foo")

A multimap is a cache where you can store n values to one key. The

multimap producer provides 4 operations (put, get, removevalue, delete).

Header Variables for the request message:

Name Type Description

hazelcast.operation.type String valid values are: put, get,

removevalue, delete

hazelcast.objectId String the object id to store / nd your

object inside the cache

Name Type Description

CamelHazelcastOperationType String

valid values are: put, get,

removevalue, delete [Version

2.8]

CamelHazelcastObjectId String

the object id to store / nd

your object inside the cache

[Version 2.8]

Sample for put:

Java DSL:

from("direct:put")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.PUT_OPERATION))

.to(String.format("hazelcast:%sbar", HazelcastConstants.MULTIMAP_PREFIX));

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

</setHeader>

</route>

669 CHAPTER 11 - COMPONENT APPENDIX

Header variables have changed in Camel 2.8

Sample for removevalue:

Java DSL:

from("direct:removevalue")

.setHeader(HazelcastConstants.OPERATION,

constant(HazelcastConstants.REMOVEVALUE_OPERATION))

.toF("hazelcast:%sbar", HazelcastConstants.MULTIMAP_PREFIX);

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

<constant>removevalue</constant>

</setHeader>

</route>

To remove a value you have to provide the value you want to remove inside

the message body. If you have a multimap object {key: "4711" values: {

"my-foo", "my-bar"}} you have to put "my-foo" inside the message body

to remove the "my-foo" value.

Sample for get:

Java DSL:

from("direct:get")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.GET_OPERATION))

.toF("hazelcast:%sbar", HazelcastConstants.MULTIMAP_PREFIX)

.to("seda:out");

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

CHAPTER 11 - COMPONENT APPENDIX 670

</setHeader>

</route>

Sample for delete:

Java DSL:

from("direct:delete")

.setHeader(HazelcastConstants.OPERATION,

constant(HazelcastConstants.DELETE_OPERATION))

.toF("hazelcast:%sbar", HazelcastConstants.MULTIMAP_PREFIX);

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

<constant>delete</constant>

</setHeader>

</route>

you can call them in your test class with:

template.sendBodyAndHeader("direct:[put|get|removevalue|delete]","my-foo",

HazelcastConstants.OBJECT_ID, "4711");

multimap cache consumer -

from("hazelcast:multimap:foo")

For the multimap cache this component provides the same listeners /

variables as for the map cache consumer (except the update and enviction

listener). The only dierence is the multimap prex inside the URI. Here is a

sample:

671 CHAPTER 11 - COMPONENT APPENDIX

fromF("hazelcast:%sbar", HazelcastConstants.MULTIMAP_PREFIX)

.log("object...")

.choice()

.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ADDED))

.log("...added")

.to("mock:added")

//.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ENVICTED))

// .log("...envicted")

// .to("mock:envicted")

.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.REMOVED))

.log("...removed")

.to("mock:removed")

.otherwise()

.log("fail!");

Header Variables inside the response message:

Name Type Description

hazelcast.listener.time Long time of the event in millis

hazelcast.listener.type String the map consumer sets here

"cachelistener"

hazelcast.listener.action String type of event - here added and

removed (and soon envicted)

hazelcast.objectId String the oid of the object

hazelcast.cache.name String the name of the cache - e.g.

"foo"

hazelcast.cache.type String the type of the cache - here

multimap

Eviction will be added as feature, soon (this is a Hazelcast issue).

Name Type Description

CamelHazelcastListenerTime Long time of the event in millis

[Version 2.8]

CamelHazelcastListenerType String

the map consumer sets here

"cachelistener" [Version

2.8]

CamelHazelcastListenerAction String

type of event - here added

and removed (and soon

envicted)[Version 2.8]

CHAPTER 11 - COMPONENT APPENDIX 672

Header variables have changed in Camel 2.8

CamelHazelcastObjectId String the oid of the object

[Version 2.8]

CamelHazelcastCacheName String the name of the cache - e.g.

"foo" [Version 2.8]

CamelHazelcastCacheType String the type of the cache - here

multimap [Version 2.8]

Usage of Queue

Queue producer – to(“hazelcast:queue:foo”)

The queue producer provides 6 operations (add, put, poll, peek, oer,

removevalue).

Sample for add:

from("direct:add")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.ADD_OPERATION))

.toF("hazelcast:%sbar", HazelcastConstants.QUEUE_PREFIX);

Sample for put:

from("direct:put")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.PUT_OPERATION))

.toF("hazelcast:%sbar", HazelcastConstants.QUEUE_PREFIX);

Sample for poll:

from("direct:poll")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.POLL_OPERATION))

.toF("hazelcast:%sbar", HazelcastConstants.QUEUE_PREFIX);

673 CHAPTER 11 - COMPONENT APPENDIX

Sample for peek:

from("direct:peek")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.PEEK_OPERATION))

.toF("hazelcast:%sbar", HazelcastConstants.QUEUE_PREFIX);

Sample for oer:

from("direct:offer")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.OFFER_OPERATION))

.toF("hazelcast:%sbar", HazelcastConstants.QUEUE_PREFIX);

Sample for removevalue:

from("direct:removevalue")

.setHeader(HazelcastConstants.OPERATION,

constant(HazelcastConstants.REMOVEVALUE_OPERATION))

.toF("hazelcast:%sbar", HazelcastConstants.QUEUE_PREFIX);

Queue consumer – from(“hazelcast:queue:foo”)

The queue consumer provides 2 operations (add, remove).

fromF("hazelcast:%smm", HazelcastConstants.QUEUE_PREFIX)

.log("object...")

.choice()

.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ADDED))

.log("...added")

.to("mock:added")

.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.REMOVED))

.log("...removed")

.to("mock:removed")

.otherwise()

.log("fail!");

CHAPTER 11 - COMPONENT APPENDIX 674

Usage of List

List producer – to(“hazelcast:list:foo”)

The list producer provides 4 operations (add, set, get, removevalue).

Sample for add:

from("direct:add")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.ADD_OPERATION))

.toF("hazelcast:%sbar", HazelcastConstants.LIST_PREFIX);

Sample for get:

from("direct:get")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.GET_OPERATION))

.toF("hazelcast:%sbar", HazelcastConstants.LIST_PREFIX)

.to("seda:out");

Sample for setvalue:

from("direct:set")

.setHeader(HazelcastConstants.OPERATION,

constant(HazelcastConstants.SETVALUE_OPERATION))

.toF("hazelcast:%sbar", HazelcastConstants.LIST_PREFIX);

Sample for removevalue:

from("direct:removevalue")

.setHeader(HazelcastConstants.OPERATION,

constant(HazelcastConstants.REMOVEVALUE_OPERATION))

.toF("hazelcast:%sbar", HazelcastConstants.LIST_PREFIX);

List consumer – from(“hazelcast:list:foo”)

The list consumer provides 2 operations (add, remove).

675 CHAPTER 11 - COMPONENT APPENDIX

Please note that set,get and removevalue and not yet supported by

hazelcast, will be added in the future..

fromF("hazelcast:%smm", HazelcastConstants.LIST_PREFIX)

.log("object...")

.choice()

.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ADDED))

.log("...added")

.to("mock:added")

.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.REMOVED))

.log("...removed")

.to("mock:removed")

.otherwise()

.log("fail!");

Usage of SEDA

SEDA component diers from the rest components provided. It implements a

work-queue in order to support asynchronous SEDA architectures, similar to

the core "SEDA" component.

SEDA producer – to(“hazelcast:seda:foo”)

The SEDA producer provides no operations. You only send data to the

specied queue.

Name default

value Description

transferExchange false

Camel 2.8.0: if set to true the whole

Exchange will be transfered. If header or

body contains not serializable objects, they

will be skipped.

Java DSL :

from("direct:foo")

.to("hazelcast:seda:foo");

Spring DSL :

CHAPTER 11 - COMPONENT APPENDIX 676

<route>

</route>

SEDA consumer – from(“hazelcast:seda:foo”)

The SEDA consumer provides no operations. You only retrieve data from the

specied queue.

Java DSL :

from("hazelcast:seda:foo")

.to("mock:result");

Spring DSL:

<route>

</route>

Usage of Atomic Number

atomic number producer -

to("hazelcast:atomicnumber:foo")

An atomic number is an object that simply provides a grid wide number

(long). The operations for this producer are setvalue (set the number with a

given value), get, increase (+1), decrease (-1) and destroy.

Header Variables for the request message:

Name Type Description

hazelcast.operation.type String valid values are: setvalue, get,

increase, decrease, destroy

Name Type Description

CamelHazelcastOperationType String

valid values are: setvalue, get,

increase, decrease, destroy

Available as of Camel

version 2.8

677 CHAPTER 11 - COMPONENT APPENDIX

There is no consumer for this endpoint!

Header variables have changed in Camel 2.8

Sample for set:

Java DSL:

from("direct:set")

.setHeader(HazelcastConstants.OPERATION,

constant(HazelcastConstants.SETVALUE_OPERATION))

.toF("hazelcast:%sfoo", HazelcastConstants.ATOMICNUMBER_PREFIX);

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

<constant>setvalue</constant>

</setHeader>

</route>

Provide the value to set inside the message body (here the value is 10):

template.sendBody("direct:set", 10);

Sample for get:

Java DSL:

from("direct:get")

.setHeader(HazelcastConstants.OPERATION, constant(HazelcastConstants.GET_OPERATION))

.toF("hazelcast:%sfoo", HazelcastConstants.ATOMICNUMBER_PREFIX);

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

CHAPTER 11 - COMPONENT APPENDIX 678

</setHeader>

</route>

You can get the number with long body =

template.requestBody("direct:get", null, Long.class);.

Sample for increment:

Java DSL:

from("direct:increment")

.setHeader(HazelcastConstants.OPERATION,

constant(HazelcastConstants.INCREMENT_OPERATION))

.toF("hazelcast:%sfoo", HazelcastConstants.ATOMICNUMBER_PREFIX);

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

<constant>increment</constant>

</setHeader>

</route>

The actual value (after increment) will be provided inside the message body.

Sample for decrement:

Java DSL:

from("direct:decrement")

.setHeader(HazelcastConstants.OPERATION,

constant(HazelcastConstants.DECREMENT_OPERATION))

.toF("hazelcast:%sfoo", HazelcastConstants.ATOMICNUMBER_PREFIX);

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

679 CHAPTER 11 - COMPONENT APPENDIX

"CamelHazelcastOperationType" -->

<constant>decrement</constant>

</setHeader>

</route>

The actual value (after decrement) will be provided inside the message body.

Sample for destroy

Java DSL:

from("direct:destroy")

.setHeader(HazelcastConstants.OPERATION,

constant(HazelcastConstants.DESTROY_OPERATION))

.toF("hazelcast:%sfoo", HazelcastConstants.ATOMICNUMBER_PREFIX);

Spring DSL:

<route>

<!-- If using version 2.8 and above set headerName to

"CamelHazelcastOperationType" -->

<constant>destroy</constant>

</setHeader>

</route>

cluster support

instance consumer - from("hazelcast:instance:foo")

Hazelcast makes sense in one single "server node", but it's extremly

powerful in a clustered environment. The instance consumer res if a new

cache instance will join or leave the cluster.

Here's a sample:

fromF("hazelcast:%sfoo", HazelcastConstants.INSTANCE_PREFIX)

.log("instance...")

.choice()

.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ADDED))

.log("...added")

CHAPTER 11 - COMPONENT APPENDIX 680

There's a bug inside Hazelcast. So this feature may not work

properly. Will be xed in 1.9.3.

This endpoint provides no producer!

.to("mock:added")

.otherwise()

.log("...removed")

.to("mock:removed");

Each event provides the following information inside the message header:

Header Variables inside the response message:

Name Type Description

hazelcast.listener.time Long time of the event in millis

hazelcast.listener.type String the map consumer sets here

"instancelistener"

hazelcast.listener.action String type of event - here added or

removed

hazelcast.instance.host String host name of the instance

hazelcast.instance.port Integer port number of the instance

Name Type Description

CamelHazelcastListenerTime Long time of the event in millis

[Version 2.8]

CamelHazelcastListenerType String

the map consumer sets

here "instancelistener"

[Version 2.8]

CamelHazelcastListenerActionn String

type of event - here added

or removed.[Version

2.8]

CamelHazelcastInstanceHost String host name of the instance

[Version 2.8]

681 CHAPTER 11 - COMPONENT APPENDIX

Header variables have changed in Camel 2.8

CamelHazelcastInstancePort Integer port number of the

instance [Version 2.8]

HDFS COMPONENT

Available as of Camel 2.8

The hdfs component enables you to read and write messages from/to an

HDFS le system. HDFS is the distributed le system at the heart of Hadoop.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-hadoop</artifactId>

</dependency>

URI format

hdfs://hostname[:port][/path][?options]

You can append query options to the URI in the following format,

?option=value&option=value&...

The path is treated in the following way:

1. as a consumer, if it's a le, it just reads the le, otherwise if it

represents a directory it scans all the le under the path satisfying

the congured pattern. All the les under that directory must be of

the same type.

2. as a producer, if at least one split strategy is dened, the path is

considered a directory and under that directory the producer creates

a dierent le per split named seg0, seg1, seg2, etc.

Options

Name Default

Value Description

CHAPTER 11 - COMPONENT APPENDIX 682

overwrite true The le can be overwritten

bufferSize 4096 The buer size used by HDFS

replication 3 The HDFS replication factor

blockSize 67108864 The size of the HDFS blocks

fileType NORMAL_FILE It can be SEQUENCE_FILE, MAP_FILE, ARRAY_FILE, or BLOOMMAP_FILE, see Hadoop

fileSystemType HDFS It can be LOCAL for local lesystem

keyType NULL The type for the key in case of sequence or map les. See below.

valueType TEXT The type for the key in case of sequence or map les. See below.

splitStrategy A string describing the strategy on how to split the le based on dierent criteria. See below.

openedSuffix opened When a le is opened for reading/writing the le is renamed with this sux to avoid to read it during

the writing phase.

readSuffix read Once the le has been read is renamed with this sux to avoid to read it again.

initialDelay 0 For the consumer, how much to wait (milliseconds) before to start scanning the directory.

delay 0 The interval (milliseconds) between the directory scans.

pattern * The pattern used for scanning the directory

chunkSize 4096 When reading a normal le, this is split into chunks producing a message per chunk.

KeyType and ValueType

• NULL it means that the key or the value is absent

• BYTE for writing a byte, the java Byte class is mapped into a BYTE

• BYTES for writing a sequence of bytes. It maps the java ByteBuer

class

• INT for writing java integer

• FLOAT for writing java oat

• LONG for writing java long

• DOUBLE for writing java double

• TEXT for writing java strings

BYTES is also used with everything else, for example, in Camel a le is sent

around as an InputStream, int this case is written in a sequence le or a map

le as a sequence of bytes.

Splitting Strategy

In the current version of Hadoop opening a le in append mode is disabled

since it's not enough reliable. So, for the moment, it's only possible to create

new les. The Camel HDFS endpoint tries to solve this problem in this way:

• If the split strategy option has been dened, the actual le name will

become a directory name and a <le name>/seg0 will be initially

created.

• Every time a splitting condition is met a new le is created with name

<original le name>/segN where N is 1, 2, 3, etc.

The splitStrategy option is dened as a string with the following

syntax:

splitStrategy=<ST>:<value>,<ST>:<value>,*

683 CHAPTER 11 - COMPONENT APPENDIX

where <ST> can be:

• BYTES a new le is created, and the old is closed when the number of

written bytes is more than <value>

• MESSAGES a new le is created, and the old is closed when the

number of written messages is more than <value>

• IDLE a new le is created, and the old is closed when no writing

happened in the last <value> milliseconds

for example:

hdfs://localhost/tmp/simple-file?splitStrategy=IDLE:1000,BYTES:5

it means: a new le is created either when it has been idle for more than 1

second or if more than 5 bytes have been written. So, running hadoop fs -

ls /tmp/simple-file you'll nd the following les seg0, seg1, seg2, etc

Using this component in OSGi

This component is fully functional in an OSGi environment however, it

requires some actions from the user. Hadoop uses the thread context class

loader in order to load resources. Usually, the thread context classloader will

be the bundle class loader of the bundle that contains the routes. So, the

default conguration les need to be visible from the bundle class loader. A

typical way to deal with it is to keep a copy of core-default.xml in your bundle

root. That le can be found in the hadoop-common.jar.

HIBERNATE COMPONENT

The hibernate: component allows you to work with databases using

Hibernate as the object relational mapping technology to map POJOs to

database tables. The camel-hibernate library is provided by the Camel

Extra project which hosts all *GPL related components for Camel.

Sending to the endpoint

Sending POJOs to the hibernate endpoint inserts entities into the database.

The body of the message is assumed to be an entity bean that you have

mapped to a relational table using the hibernate .hbm.xml les.

If the body does not contain an entity bean, use a Message Translator in

front of the endpoint to perform the necessary conversion rst.

CHAPTER 11 - COMPONENT APPENDIX 684

Note that Camel also ships with a JPA component. The JPA

component abstracts from the underlying persistence provider and

allows you to work with Hibernate, OpenJPA or EclipseLink.

Consuming from the endpoint

Consuming messages removes (or updates) entities in the database. This

allows you to use a database table as a logical queue; consumers take

messages from the queue and then delete/update them to logically remove

them from the queue.

If you do not wish to delete the entity when it has been processed, you

can specify consumeDelete=false on the URI. This will result in the entity

being processed each poll.

If you would rather perform some update on the entity to mark it as

processed (such as to exclude it from a future query) then you can annotate

a method with @Consumed which will be invoked on your entity bean when

the entity bean is consumed.

URI format

hibernate:[entityClassName][?options]

For sending to the endpoint, the entityClassName is optional. If specied it

is used to help use the [Type Conversion] to ensure the body is of the correct

type.

For consuming the entityClassName is mandatory.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Default

Value Description

entityType entityClassName Is the provided entityClassName from the URI.

consumeDelete true Option for HibernateConsumer only. Species whether or not the entity is deleted after it is

consumed.

consumeLockEntity true Option for HibernateConsumer only. Species whether or not to use exclusive locking of each

entity while processing the results from the pooling.

flushOnSend true Option for HibernateProducer only. Flushes the EntityManager after the entity bean has been

persisted.

maximumResults -1 Option for HibernateConsumer only. Set the maximum number of results to retrieve on the

Query.

consumer.delay 500 Option for HibernateConsumer only. Delay in millis between each poll.

685 CHAPTER 11 - COMPONENT APPENDIX

consumer.initialDelay 1000 Option for HibernateConsumer only. Millis before polling starts.

consumer.userFixedDelay false Option for HibernateConsumer only. Set to true to use xed delay between polls, otherwise

xed rate is used. See ScheduledExecutorService in JDK for details.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

HL7 COMPONENT

The hl7 component is used for working with the HL7 MLLP protocol and the

HL7 model using the HAPI library.

This component supports the following:

▪ HL7 MLLP codec for Mina

▪ Agnostic data format using either plain String objects or HAPI HL7

model objects.

▪ Type Converter from/to HAPI and String

▪ HL7 DataFormat using HAPI library

▪ Even more easy-of-use as its integrated well with the camel-mina

component.

Maven users will need to add the following dependency to their pom.xml for

this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-hl7</artifactId>

</dependency>

HL7 MLLP protocol

HL7 is often used with the HL7 MLLP protocol that is a text based TCP socket

based protocol. This component ships with a Mina Codec that conforms to

the MLLP protocol so you can easily expose a HL7 listener that accepts HL7

requests over the TCP transport.

To expose a HL7 listener service we reuse the existing camel-mina

component where we just use the HL7MLLPCodec as codec.

The HL7 MLLP codec has the following options:

CHAPTER 11 - COMPONENT APPENDIX 686

Name Default

Value Description

startByte 0x0b The start byte spanning the HL7 payload. Is the HL7 default value of 0x0b (11 decimal).

endByte1 0x1c The rst end byte spanning the HL7 payload. Is the HL7 default value of 0x1c (28 decimal).

endByte2 0x0d The 2nd end byte spanning the HL7 payload. Is the HL7 default value of 0x0d (13 decimal).

charset JVM Default The encoding (is a charset name) to use for the codec. If not provided, Camel will use the JVM default

Charset.

convertLFtoCR true Will convert \n to \r (0x0d, 13 decimal) as HL7 usually uses \r as segment terminators. The HAPI

library requires the use of \r.

validate true Camel 2.0: Whether HAPI Parser should validate or not.

Exposing a HL7 listener

In our Spring XML le, we congure an endpoint to listen for HL7 requests

using TCP:

<endpoint id="hl7listener"

uri="mina:tcp://localhost:8888?sync=true&codec=#hl7codec"/>

Notice we congure it to use camel-mina with TCP on the localhost on port

8888. We use sync=true to indicate that this listener is synchronous and

therefore will return a HL7 response to the caller. Then we setup mina to use

our HL7 codec with codec=#hl7codec. Notice that hl7codec is just a Spring

bean ID, so we could have named it mygreatcodecforhl7 or whatever. The

codec is also set up in the Spring XML le:

</bean>

And here we congure the charset encoding to use, and iso-8859-1 is

commonly used.

The endpoint hl7listener can then be used in a route as a consumer, as

this java DSL example illustrates:

from("hl7socket").to("patientLookupService");

This is a very simple route that will listen for HL7 and route it to a service

named patientLookupService that is also a Spring bean ID we have

congured in the Spring XML as:

<bean id="patientLookupService"

class="com.mycompany.healtcare.service.PatientLookupService"/>

687 CHAPTER 11 - COMPONENT APPENDIX

And another powerful feature of Camel is that we can have our busines logic

in POJO classes that is not at all tied to Camel as shown here:

public class PatientLookupService {

public Message lookupPatient(Message input) throws HL7Exception {

QRD qrd = (QRD)input.get("QRD");

String patientId = qrd.getWhoSubjectFilter(0).getIDNumber().getValue();

// find patient data based on the patient id and create a HL7 model object

with the response

Message response = ... create and set response data

return response

}

Notice that this class is just using imports from the HAPI library and none

from Camel.

HL7 Model using java.lang.String

The HL7MLLP codec uses plain String as data format. And Camel uses Type

Converter to convert from/to strings to the HAPI HL7 model objects. However,

you can use the plain String objects if you prefer, for instance if you need to

parse the data yourself.

See samples for such an example.

HL7 Model using HAPI

The HL7 model is Java objects from the HAPI library. Using this library, we can

encode and decode from the EDI format (ER7) that is mostly used with HL7.

With this model you can code with Java objects instead of the EDI based HL7

format that can be hard for humans to read and understand.

The ER7 sample below is a request to lookup a patient with the patient ID,

0101701234.

MSH|^~\\&|MYSENDER|MYRECEIVER|MYAPPLICATION||200612211200||QRY^A19|1234|P|2.4

QRD|200612211200|R|I|GetPatient|||1^RD|0101701234|DEM||

Using the HL7 model we can work with the data as a

ca.uhn.hl7v2.model.Message.Message object.

To retrieve the patient ID for the patient in the ER7 above, you can do this in

java code:

Message msg = exchange.getIn().getBody(Message.class);

QRD qrd = (QRD)msg.get("QRD");

String patientId = qrd.getWhoSubjectFilter(0).getIDNumber().getValue();

CHAPTER 11 - COMPONENT APPENDIX 688

Camel has built-in type converters, so when this operation is invoked:

Message msg = exchange.getIn().getBody(Message.class);

Camel will convert the received HL7 data from String to Message. This is

powerful when combined with the HL7 listener, then you as the end-user

don't have to work with byte[],String or any other simple object formats.

You can just use the HAPI HL7 model objects.

HL7 DataFormat

The HL7 component ships with a HL7 data format that can be used to format

between String and HL7 model objects.

▪marshal = from Message to byte stream (can be used when

returning as response using the HL7 MLLP codec)

▪unmarshal = from byte stream to Message (can be used when

receiving streamed data from the HL7 MLLP

To use the data format, simply instantiate an instance and invoke the

marhsal or unmarshl operation in the route builder:

DataFormat hl7 = new HL7DataFormat();

...

from("direct:hl7in").marshal(hl7).to("jms:queue:hl7out");

In the sample above, the HL7 is marshalled from a HAPI Message object to a

byte stream and put on a JMS queue.

The next example is the opposite:

DataFormat hl7 = new HL7DataFormat();

...

from("jms:queue:hl7out").unmarshal(hl7).to("patientLookupService");

Here we unmarshal the byte stream into a HAPI Message object that is

passed to our patient lookup service.

Notice there is a shorthand syntax in Camel for well-known data formats

that is commonly used.

Then you don't need to create an instance of the HL7DataFormat object:

from("direct:hl7in").marshal().hl7().to("jms:queue:hl7out");

from("jms:queue:hl7out").unmarshal().hl7().to("patientLookupService");

689 CHAPTER 11 - COMPONENT APPENDIX

Message Headers

The unmarshal operation adds these MSH elds as headers on the Camel

message:

Camel 1.x

Key MSH eld Example

hl7.msh.sendingApplication MSH-3 MYSERVER

hl7.msh.sendingFacility MSH-4 MYSERVERAPP

hl7.msh.receivingApplication MSH-5 MYCLIENT

hl7.msh.receivingFacility MSH-6 MYCLIENTAPP

hl7.msh.timestamp MSH-7 20071231235900

hl7.msh.security MSH-8 null

hl7.msh.messageType MSH-9-1 ADT

hl7.msh.triggerEvent MSH-9-2 A01

hl7.msh.messageControl MSH-10 1234

hl7.msh.processingId MSH-11 P

hl7.msh.versionId MSH-12 2.4

Camel 2.0

Key MSH eld Example

CamelHL7SendingApplication MSH-3 MYSERVER

CamelHL7SendingFacility MSH-4 MYSERVERAPP

CamelHL7ReceivingApplication MSH-5 MYCLIENT

CamelHL7ReceivingFacility MSH-6 MYCLIENTAPP

CamelHL7Timestamp MSH-7 20071231235900

CamelHL7Security MSH-8 null

CamelHL7MessageType MSH-9-1 ADT

CamelHL7TriggerEvent MSH-9-2 A01

CamelHL7MessageControl MSH-10 1234

CamelHL7ProcessingId MSH-11 P

CamelHL7VersionId MSH-12 2.4

All headers are String types. If a header value is missing, its value is null.

Options

The HL7 Data Format supports the following options:

Option Default Description

validate true Camel 2.0: Whether the HAPI Parser should validate.

CHAPTER 11 - COMPONENT APPENDIX 690

Dependencies

To use HL7 in your camel routes you need to add a dependency on camel-

hl7, which implements this data format.

If you use Maven, you could just add the following to your pom.xml,

substituting the version number for the latest & greatest release (see the

download page for the latest versions).

<groupId>org.apache.camel</groupId>

<artifactId>camel-hl7</artifactId>

</dependency>

Since HAPI 0.6, the library has been split into a base library and several

structures libraries, one for each HL7v2 message version:

• v2.1 structures library

• v2.2 structures library

• v2.3 structures library

• v2.3.1 structures library

• v2.4 structures library

• v2.5 structures library

• v2.5.1 structures library

• v2.6 structures library

By default camel-hl7 only references the HAPI base library. Applications are

responsible for including structures libraries themselves. For example, if a

application works with HL7v2 message versions 2.4 and 2.5 then the

following dependencies must be added:

<artifactId>hapi-structures-v24</artifactId>

</dependency>

<artifactId>hapi-structures-v25</artifactId>

</dependency>

OSGi

An OSGi bundle containing the base library, all structures libraries and

required dependencies (on the bundle classpath) can be downloaded from

the HAPI Maven repository as well.

691 CHAPTER 11 - COMPONENT APPENDIX

</dependency>

Samples

In the following example we send a HL7 request to a HL7 listener and

retrieves a response. We use plain String types in this example:

String line1 =

"MSH|^~\\&|MYSENDER|MYRECEIVER|MYAPPLICATION||200612211200||QRY^A19|1234|P|2.4";

String line2 = "QRD|200612211200|R|I|GetPatient|||1^RD|0101701234|DEM||";

StringBuilder in = new StringBuilder();

in.append(line1);

in.append("\n");

in.append(line2);

String out =

(String)template.requestBody("mina:tcp://127.0.0.1:8888?sync=true&codec=#hl7codec",

in.toString());

In the next sample, we want to route HL7 requests from our HL7 listener to

our business logic. We have our business logic in a plain POJO that we have

registered in the registry as hl7service = for instance using Spring and

letting the bean id = hl7service.

Our business logic is a plain POJO only using the HAPI library so we have

these operations dened:

public class MyHL7BusinessLogic {

// This is a plain POJO that has NO imports whatsoever on Apache Camel.

// its a plain POJO only importing the HAPI library so we can much easier work

with the HL7 format.

public Message handleA19(Message msg) throws Exception {

// here you can have your business logic for A19 messages

assertTrue(msg instanceof QRY_A19);

// just return the same dummy response

return createADR19Message();

}

public Message handleA01(Message msg) throws Exception {

// here you can have your business logic for A01 messages

assertTrue(msg instanceof ADT_A01);

// just return the same dummy response

CHAPTER 11 - COMPONENT APPENDIX 692

return createADT01Message();

}

Then we set up the Camel routes using the RouteBuilder as follows:

DataFormat hl7 = new HL7DataFormat();

// we setup or HL7 listener on port 8888 (using the hl7codec) and in sync mode so we

can return a response

from("mina:tcp://127.0.0.1:8888?sync=true&codec=#hl7codec")

// we use the HL7 data format to unmarshal from HL7 stream to the HAPI Message

model

// this ensures that the camel message has been enriched with hl7 specific

headers to

// make the routing much easier (see below)

.unmarshal(hl7)

// using choice as the content base router

.choice()

// where we choose that A19 queries invoke the handleA19 method on our

hl7service bean

.when(header("CamelHL7TriggerEvent").isEqualTo("A19"))

.beanRef("hl7service","handleA19")

.to("mock:a19")

// and A01 should invoke the handleA01 method on our hl7service bean

.when(header("CamelHL7TriggerEvent").isEqualTo("A01")).to("mock:a01")

.beanRef("hl7service","handleA01")

.to("mock:a19")

// other types should go to mock:unknown

.otherwise()

.to("mock:unknown")

// end choice block

.end()

// marhsal response back

.marshal(hl7);

Notice that we use the HL7 DataFormat to enrich our Camel Message with

the MSH elds precongued on the Camel Message. This lets us much more

easily dene our routes using the uent builders.

If we do not use the HL7 DataFormat, then we do not gains these headers

and we must resort to a dierent technique for computing the MSH trigger

event (= what kind of HL7 message it is). This is a big advantage of the HL7

DataFormat over the plain HL7 type converters.

Sample using plain String objects

In this sample we use plain String objects as the data format, that we send,

process and receive. As the sample is part of a unit test, there is some code

for assertions, but you should be able to understand what happens. First we

693 CHAPTER 11 - COMPONENT APPENDIX

send the plain string, Hello World, to the HL7MLLPCodec and receive the

response as a plain string, Bye World.

MockEndpoint mock = getMockEndpoint("mock:result");

mock.expectedBodiesReceived("Bye World");

// send plain hello world as String

Object out =

template.requestBody("mina:tcp://127.0.0.1:8888?sync=true&codec=#hl7codec", "Hello

World");

assertMockEndpointsSatisfied();

// and the response is also just plain String

assertEquals("Bye World", out);

Here we process the incoming data as plain String and send the response

also as plain String:

from("mina:tcp://127.0.0.1:8888?sync=true&codec=#hl7codec")

.process(new Processor() {

public void process(Exchange exchange) throws Exception {

// use plain String as message format

String body = exchange.getIn().getBody(String.class);

assertEquals("Hello World", body);

// return the response as plain string

exchange.getOut().setBody("Bye World");

}

})

.to("mock:result");

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

HTTP COMPONENT

The http: component provides HTTP based endpoints for consuming external

HTTP resources (as a client to call external servers using HTTP).

Maven users will need to add the following dependency to their pom.xml

for this component:

CHAPTER 11 - COMPONENT APPENDIX 694

<groupId>org.apache.camel</groupId>

<artifactId>camel-http</artifactId>

</dependency>

URI format

http:hostname[:port][/resourceUri][?options]

Will by default use port 80 for HTTP and 443 for HTTPS.

You can append query options to the URI in the following format,

?option=value&option=value&...

HttpEndpoint Options

Name Default

Value Description

throwExceptionOnFailure true

Camel 2.0: Option to disable throwing the HttpOperationFailedException in case of failed

responses from the remote server. This allows you to get all responses regardles of the HTTP

status code.

bridgeEndpoint false

Camel 2.1: If the option is true , HttpProducer will ignore the Exchange.HTTP_URI header, and

use the endpoint's URI for request. You may also set the throwExcpetionOnFailure to be false

to let the HttpProducer send all the fault response back.

Camel 2.3: If the option is true, HttpProducer and CamelServlet will skip the gzip processing if

the content-encoding is "gzip".

disableStreamCache false

Camel 2.3: DefaultHttpBinding will copy the request input stream into a stream cache and put it

into message body if this option is false to support read it twice, otherwise DefaultHttpBinding

will set the request input stream direct into the message body.

httpBindingRef null Reference to a org.apache.camel.component.http.HttpBinding in the Registry. From Camel

2.3 onwards prefer to use the httpBinding option.

httpBinding null Camel 2.3: Reference to a org.apache.camel.component.http.HttpBinding in the Registry.

httpClientConfigurerRef null Reference to a org.apache.camel.component.http.HttpClientConfigurer in the Registry.

From Camel 2.3 onwards prefer to use the httpClientConfigurer option.

httpClientConfigurer null Camel 2.3: Reference to a org.apache.camel.component.http.HttpClientConfigurer in the

Registry.

httpClient.XXX null Setting options on the HttpClientParams. For instance httpClient.soTimeout=5000 will set the

SO_TIMEOUT to 5 seconds.

clientConnectionManager null Camel 2.3: To use a custom org.apache.http.conn.ClientConnectionManager.

transferException false

Camel 2.6: If enabled and an Exchange failed processing on the consumer side, and if the

caused Exception was send back serialized in the response as a application/x-java-

serialized-object content type (for example using Jetty or SERVLET Camel components). On

the producer side the exception will be deserialized and thrown as is, instead of the

HttpOperationFailedException. The caused exception is required to be serialized.

The following authentication options can also be set on the HttpEndpoint:

695 CHAPTER 11 - COMPONENT APPENDIX

camel-http vs camel-jetty

You can only produce to endpoints generated by the HTTP

component. Therefore it should never be used as input into your

camel Routes. To bind/expose an HTTP endpoint via a HTTP server

as input to a camel route, you can use the Jetty Component

Camel 2.2 or older: Setting Authentication and Proxy

Name Default

Value Description

username null Username for authentication.

password null Password for authentication.

domain null Camel 2.1: Domain for NTML Authentication. This option must be used to force NTML

authentication.

proxyHost null Camel 1.6.2: The proxy host name

proxyPort null Camel 1.6.2: The proxy port number

proxyUsername null Camel 1.6.2: Username for proxy authentication

proxyPassword null Camel 1.6.2: Password for proxy authentication

Camel 2.3 or newer: HttpConguration - Setting

Authentication and Proxy

Name Default

Value Description

authMethod null Authentication method, either as Basic,Digest or NTLM.

authMethodPriority null Priority of authentication methods. Is a list separated with comma. For example: Basic,Digest

to exclude NTLM.

authUsername null Username for authentication

authPassword null Password for authentication

authDomain null Domain for NTML authentication

authHost null Optional host for NTML authentication

proxyHost null The proxy host name

proxyPort null The proxy port number

proxyAuthMethod null Authentication method for proxy, either as Basic,Digest or NTLM.

proxyAuthUsername null Username for proxy authentication

proxyAuthPassword null Password for proxy authentication

proxyAuthDomain null Domain for proxy NTML authentication

proxyAuthHost null Optional host for proxy NTML authentication

When using authentication you must provide the choice of method for the

authMethod or authProxyMethod options.

You can congure the proxy and authentication details on either the

HttpComponent or the HttpEndoint. Values provided on the HttpEndpoint

will take precedence over HttpComponent. Its most likely best to congure

this on the HttpComponent which allows you to do this once.

CHAPTER 11 - COMPONENT APPENDIX 696

The HTTP component uses convention over conguration which means

that if you have not explicit set a authMethodPriority then it will fallback

and use the select(ed) authMethod as priority as well. So if you use

authMethod.Basic then the auhtMethodPriority will be Basic only.

HttpComponent Options

Name Default Value Description

httpBinding null To use a custom org.apache.camel.component.http.HttpBinding.

httpClientConfigurer null To use a custom org.apache.camel.component.http.HttpClientConfigurer.

httpConnectionManager null To use a custom org.apache.commons.httpclient.HttpConnectionManager.

httpConfiguration null Camel 2.3: To use a custom org.apache.camel.component.http.HttpConfiguration

HttpConfiguration contains all the options listed in the table above under

the section HttpConguration - Setting Authentication and Proxy.

Message Headers

Camel 1.x

Name Type Description

HttpProducer.HTTP_URI String Camel 1.6.0: URI to call. Will override existing URI set directly on the endpoint. Is set on the

In message.

HttpProducer.HTTP_RESPONSE_CODE int The HTTP response code from the external server. Is 200 for OK. Is set on the Out message.

HttpProducer.QUERY String URI parameters. Will override existing URI parameters set directly on the endpoint. Is set on

the In message.

Camel 2.x

Name Type Description

Exchange.HTTP_URI String URI to call. Will override existing URI set directly on the endpoint.

Exchange.HTTP_PATH String

Request URI's path, the header will be used to build the request URI with the

HTTP_URI. Camel 2.3.0: If the path is start with "/", http producer will try to

nd the relative path based on the Exchange.HTTP_BASE_URI header or the

exchange.getFromEndpoint().getEndpointUri();

Exchange.HTTP_QUERY String URI parameters. Will override existing URI parameters set directly on the

endpoint.

Exchange.HTTP_RESPONSE_CODE int The HTTP response code from the external server. Is 200 for OK.

Exchange.HTTP_CHARACTER_ENCODING String Character encoding.

Exchange.CONTENT_TYPE String The HTTP content type. Is set on both the IN and OUT message to provide a

content type, such as text/html.

Exchange.CONTENT_ENCODING String The HTTP content encoding. Is set on both the IN and OUT message to provide

a content encoding, such as gzip.

Exchange.HTTP_SERVLET_REQUEST HttpServletRequest Camel 2.3: The HttpServletRequest object.

Exchange.HTTP_SERVLET_RESPONSE HttpServletResponse Camel 2.3: The HttpServletResponse object.

Exchange.HTTP_PROTOCOL_VERSION String

Camel 2.5: You can set the http protocol version with this header, eg. "HTTP/

1.0". If you didn't specify the header, HttpProducer will use the default value

"HTTP/1.1"

697 CHAPTER 11 - COMPONENT APPENDIX

Message Body

Camel will store the HTTP response from the external server on the OUT

body. All headers from the IN message will be copied to the OUT message, so

headers are preserved during routing. Additionally Camel will add the HTTP

response headers as well to the OUT message headers.

Response code

Camel will handle according to the HTTP response code:

▪ Response code is in the range 100..299, Camel regards it as a

success response.

▪ Response code is in the range 300..399, Camel regards it as a

redirection response and will throw a

HttpOperationFailedException with the information.

▪ Response code is 400+, Camel regards it as an external server failure

and will throw a HttpOperationFailedException with the

information.

HttpOperationFailedException

This exception contains the following information:

▪ The HTTP status code

▪ The HTTP status line (text of the status code)

▪ Redirect location, if server returned a redirect

▪ Response body as a java.lang.String, if server provided a body as

response

Calling using GET or POST

In Camel 1.5 the following algorithm is used to determine if either GET or

POST HTTP method should be used:

1. Use method provided in header.

2. GET if query string is provided in header.

3. GET if endpoint is congured with a query string.

4. POST if there is data to send (body is not null).

5. GET otherwise.

How to get access to HttpServletRequest and HttpServletResponse

Available as of Camel 2.0

You can get access to these two using the Camel type converter system

using

CHAPTER 11 - COMPONENT APPENDIX 698

throwExceptionOnFailure

The option, throwExceptionOnFailure, can be set to false to

prevent the HttpOperationFailedException from being thrown for

failed response codes. This allows you to get any response from the

remote server.

There is a sample below demonstrating this.

NOTE from Camel 2.3.0 you can get the request and response not just from

the processor after the camel-jetty or camel-cxf endpoint.

HttpServletRequest request = exchange.getIn().getBody(HttpServletRequest.class);

HttpServletRequest response = exchange.getIn().getBody(HttpServletResponse.class);

Conguring URI to call

You can set the HTTP producer's URI directly form the endpoint URI. In the

route below, Camel will call out to the external server, oldhost, using HTTP.

from("direct:start")

.to("http://oldhost");

And the equivalent Spring sample:

<route>

</route>

</camelContext>

In Camel 1.5.1 you can override the HTTP endpoint URI by adding a header

with the key, HttpProducer.HTTP_URI, on the message.

from("direct:start")

.setHeader(org.apache.camel.component.http.HttpProducer.HTTP_URI,

constant("http://newhost"))

.to("http://oldhost");

In the sample above Camel will call the http://newhost despite the endpoint

is congured with http://oldhost.

And the same code in Camel 2.0:

699 CHAPTER 11 - COMPONENT APPENDIX

from("direct:start")

.setHeader(HttpConstants.HTTP_URI, constant("http://newhost"))

.to("http://oldhost");

Where Constants is the class,

org.apache.camel.component.http.Constants.

Conguring URI Parameters

Camel 1.x

The http producer supports URI parameters to be sent to the HTTP server.

The URI parameters can either be set directly on the endpoint URI or as a

header with the key HttpProducer.QUERY on the message.

from("direct:start")

.to("http://oldhost?order=123&detail=short");

Or options provided in a header:

from("direct:start")

.setHeader(HttpConstants.HTTP_QUERY, constant("order=123&detail=short"))

.to("http://oldhost");

Camel 2.x

The http producer supports URI parameters to be sent to the HTTP server.

The URI parameters can either be set directly on the endpoint URI or as a

header with the key Exchange.HTTP_QUERY on the message.

from("direct:start")

.to("http://oldhost?order=123&detail=short");

Or options provided in a header:

from("direct:start")

.setHeader(Exchange.HTTP_QUERY, constant("order=123&detail=short"))

.to("http://oldhost");

How to set the http method (GET/POST/PUT/DELETE/HEAD/OPTIONS/

TRACE) to the HTTP producer

The HTTP component provides a way to set the HTTP request method by

setting the message header. Here is an example;

Camel 1.x

CHAPTER 11 - COMPONENT APPENDIX 700

from("direct:start")

.setHeader(HttpConstants.HTTP_METHOD,

constant(org.apache.camel.component.http.HttpMethods.POST))

.to("http://www.google.com")

.to("mock:results");

Camel 2.x

from("direct:start")

.setHeader(Exchange.HTTP_METHOD,

constant(org.apache.camel.component.http.HttpMethods.POST))

.to("http://www.google.com")

.to("mock:results");

The method can be written a bit shorter using the string constants:

.setHeader("CamelHttpMethod", constant("POST"))

And the equivalent Spring sample:

<route>

</setHeader>

</route>

</camelContext>

Using client tineout - SO_TIMEOUT

See the unit test in this link

Conguring a Proxy

Only for >= Camel 1.6.2

The HTTP component provides a way to congure a proxy.

from("direct:start")

.to("http://oldhost?proxyHost=www.myproxy.com&proxyPort=80");

There is also support for proxy authentication via the proxyUsername and

proxyPassword options.

701 CHAPTER 11 - COMPONENT APPENDIX

Using proxy settings outside of URI

*Only for >= Camel 1.6.2 and < Camel 2.2.0 *

The HTTP component will detect Java System Properties for http.proxyHost

and http.proxyPort and use them if provided.

See more at SUN http proxy documentation.

To avoid the System properties conicts, from Camel 2.2.0 you can only

set the proxy congure from CameContext or URI.

Java DSL :

context.getProperties().put("http.proxyHost","172.168.18.9");

context.getProperties().put("http.proxyPort" "8080");

Spring XML

</properties>

</camelContext>

Camel will rst set the settings from Java System or CamelContext Properties

and then the endpoint proxy options if provided.

So you can override the system properties with the endpoint options.

Conguring charset

If you are using POST to send data you can congure the charset using the

Exchange property:

exchange.setProperty(Exchange.CHARSET_NAME, "iso-8859-1");

Sample with scheduled poll

The sample polls the Google homepage every 10 seconds and write the page

to the le message.html:

from("timer://foo?fixedRate=true&delay=0&period=10000")

.to("http://www.google.com")

.setHeader(FileComponent.HEADER_FILE_NAME, "message.html").to("file:target/

google");

CHAPTER 11 - COMPONENT APPENDIX 702

URI Parameters from the endpoint URI

In this sample we have the complete URI endpoint that is just what you

would have typed in a web browser. Multiple URI parameters can of course

be set using the &character as separator, just as you would in the web

browser. Camel does no tricks here.

// we query for Camel at the Google page

template.sendBody("http://www.google.com/search?q=Camel",null);

URI Parameters from the Message

Map headers = new HashMap();

headers.put(HttpProducer.QUERY, "q=Camel&lr=lang_en");

// we query for Camel and English language at Google

template.sendBody("http://www.google.com/search",null, headers);

In the header value above notice that it should not be prexed with ?and

you can separate parameters as usual with the &char.

Getting the Response Code

You can get the HTTP response code from the HTTP component by getting

the value from the Out message header with

HttpProducer.HTTP_RESPONSE_CODE.

Exchange exchange = template.send("http://www.google.com/search",new Processor() {

public void process(Exchange exchange) throws Exception {

exchange.getIn().setHeader(HttpProducer.QUERY,

constant("hl=en&q=activemq"));

}

});

Message out = exchange.getOut();

int responseCode = out.getHeader(HttpProducer.HTTP_RESPONSE_CODE, Integer.class);

Using throwExceptionOnFailure=false to get any response back

Available as of Camel 2.0

In the route below we want to route a message that we enrich with data

returned from a remote HTTP call. As we want any response from the remote

server, we set the throwExceptionOnFailure option to false so we get any

response in the AggregationStrategy. As the code is based on a unit test

that simulates a HTTP status code 404, there is some assertion code etc.

703 CHAPTER 11 - COMPONENT APPENDIX

// We set throwExceptionOnFailure to false to let Camel return any response from the

remove HTTP server without thrown

// HttpOperationFailedException in case of failures.

// This allows us to handle all responses in the aggregation strategy where we can

check the HTTP response code

// and decide what to do. As this is based on an unit test we assert the code is 404

from("direct:start").enrich("http://localhost:{{port}}/

myserver?throwExceptionOnFailure=false&user=Camel",new AggregationStrategy() {

public Exchange aggregate(Exchange original, Exchange resource) {

// get the response code

Integer code = resource.getIn().getHeader(Exchange.HTTP_RESPONSE_CODE,

Integer.class);

assertEquals(404, code.intValue());

return resource;

}

}).to("mock:result");

// this is our jetty server where we simulate the 404

from("jetty://http://localhost:{{port}}/myserver")

.process(new Processor() {

public void process(Exchange exchange) throws Exception {

exchange.getOut().setBody("Page not found");

exchange.getOut().setHeader(Exchange.HTTP_RESPONSE_CODE, 404);

}

});

Disabling Cookies

To disable cookies you can set the HTTP Client to ignore cookies by adding

this URI option:

httpClient.cookiePolicy=ignoreCookies

Advanced Usage

If you need more control over the HTTP producer you should use the

HttpComponent where you can set various classes to give you custom

behavior.

Setting MaxConnectionsPerHost

The HTTP Component has a

org.apache.commons.httpclient.HttpConnectionManager where you can

congure various global conguration for the given component.

By global, we mean that any endpoint the component creates has the same

shared HttpConnectionManager. So, if we want to set a dierent value for

the max connection per host, we need to dene it on the HTTP component

and not on the endpoint URI that we usually use. So here comes:

CHAPTER 11 - COMPONENT APPENDIX 704

First, we dene the http component in Spring XML. Yes, we use the same

scheme name, http, because otherwise Camel will auto-discover and create

the component with default settings. What we need is to overrule this so we

can set our options. In the sample below we set the max connection to 5

instead of the default of 2.

</bean>

<bean id="myHttpConnectionManager"

class="org.apache.commons.httpclient.MultiThreadedHttpConnectionManager">

</bean>

<bean id="myHttpConnectionManagerParams"

class="org.apache.commons.httpclient.params.HttpConnectionManagerParams">

</bean>

And then we can just use it as we normally do in our routes:

<route>

</route>

</camelContext>

Using HTTPS to authenticate gotchas

An end user reported that he had problem with authenticating with HTTPS.

The problem was eventually resolved when he discovered the HTTPS server

did not return a HTTP code 401 Authorization Required. The solution was to

set the following URI option: httpClient.authenticationPreemptive=true

Accepting self signed certications from remote server

See this link from a mailing list discussion with some code to outline how to

do this with the Apache Commons HTTP API.

705 CHAPTER 11 - COMPONENT APPENDIX

Setting up SSL for HTTP Client

Using the JSSE Conguration Utility

As of Camel 2.8, the HTTP4 component supports SSL/TLS conguration

through the Camel JSSE Conguration Utility. This utility greatly decreases

the amount of component specic code you need to write and is congurable

at the endpoint and component levels. The following examples demonstrate

how to use the utility with the HTTP4 component.

The version of the Apache HTTP client used in this component resolves

SSL/TLS information from a global "protocol" registry. This component

provides an implementation,

org.apache.camel.component.http.SSLContextParametersSecureProtocolSocketFactory,

of the HTTP client's protocol socket factory in order to support the use of the

Camel JSSE Conguration utility. The following example demonstrates how to

congure the protocol registry and use the registered protocol information in

a route.

KeyStoreParameters ksp = new KeyStoreParameters();

ksp.setResource("/users/home/server/keystore.jks");

ksp.setPassword("keystorePassword");

KeyManagersParameters kmp = new KeyManagersParameters();

kmp.setKeyStore(ksp);

kmp.setKeyPassword("keyPassword");

SSLContextParameters scp = new SSLContextParameters();

scp.setKeyManagers(kmp);

ProtocolSocketFactory factory =

new SSLContextParametersSecureProtocolSocketFactory(scp);

Protocol.registerProtocol("https",

new Protocol(

"https",

factory,

443));

from("direct:start")

.to("https://mail.google.com/mail/").to("mock:results");

Conguring Apache HTTP Client Directly

Basically camel-http component is built on the top of Apache HTTP client,

and you can implement a custom

org.apache.camel.component.http.HttpClientConfigurer to do some

conguration on the http client if you need full control of it.

CHAPTER 11 - COMPONENT APPENDIX 706

However if you just want to specify the keystore and truststore you can do

this with Apache HTTP HttpClientConfigurer, for example:

Protocol authhttps = new Protocol("https",new AuthSSLProtocolSocketFactory(

new URL("file:my.keystore"), "mypassword",

new URL("file:my.truststore"), "mypassword"), 443);

Protocol.registerProtocol("https", authhttps);

And then you need to create a class that implements

HttpClientConfigurer, and registers https protocol providing a keystore or

truststore per example above. Then, from your camel route builder class you

can hook it up like so:

HttpComponent httpComponent = getContext().getComponent("http", HttpComponent.class);

httpComponent.setHttpClientConfigurer(new MyHttpClientConfigurer());

If you are doing this using the Spring DSL, you can specify your

HttpClientConfigurer using the URI. For example:

<bean id="myHttpClientConfigurer"

class="my.https.HttpClientConfigurer">

</bean>

<to uri="https://myhostname.com:443/

myURL?httpClientConfigurerRef=myHttpClientConfigurer"/>

As long as you implement the HttpClientCongurer and congure your

keystore and truststore as described above, it will work ne.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ Jetty

IBATIS

The ibatis: component allows you to query, poll, insert, update and delete

data in a relational database using Apache iBATIS.

Maven users will need to add the following dependency to their pom.xml

for this component:

707 CHAPTER 11 - COMPONENT APPENDIX

<groupId>org.apache.camel</groupId>

<artifactId>camel-ibatis</artifactId>

</dependency>

URI format

ibatis:statementName[?options]

Where statementName is the name in the iBATIS XML conguration le

which maps to the query, insert, update or delete operation you wish to

evaluate.

You can append query options to the URI in the following format,

?option=value&option=value&...

This component will by default load the iBatis SqlMapCong le from the

root of the classpath and expected named as SqlMapConfig.xml.

It uses Spring resource loading so you can dene it using classpath,file or

http as prex to load resources with those schemes.

In Camel 2.2 you can congure this on the iBatisComponent with the

setSqlMapConfig(String) method.

Options

Option Type Default Description

consumer.onConsume String null

Statements to run after consuming. Can be used, for

example, to update rows after they have been

consumed and processed in Camel. See sample later.

Multiple statements can be separated with comma.

consumer.useIterator boolean true

If true each row returned when polling will be

processed individually. If false the entire List of data

is set as the IN body.

consumer.routeEmptyResultSet boolean false

Camel 2.0: Sets whether empty result set should be

routed or not. By default, empty result sets are not

routed.

statementType StatementType null

Camel 1.6.1/2.0: Mandatory to specify for

IbatisProducer to control which iBatis SqlMapClient

method to invoke. The enum values are:

QueryForObject,QueryForList,Insert,Update,

Delete.

maxMessagesPerPoll int 0

Camel 2.0: An integer to dene a maximum messages

to gather per poll. By default, no maximum is set. Can

be used to set a limit of e.g. 1000 to avoid when

starting up the server that there are thousands of les.

Set a value of 0 or negative to disabled it.

CHAPTER 11 - COMPONENT APPENDIX 708

isolation String TRANSACTION_REPEATABLE_READ

Camel 2.9: A String the denes the transaction

isolation level of the will be used. Allowed values are

TRANSACTION_NONE,

TRANSACTION_READ_UNCOMMITTED,

TRANSACTION_READ_COMMITTED,

TRANSACTION_REPEATABLE_READ,

TRANSACTION_SERIALIZABLE

isolation String TRANSACTION_REPEATABLE_READ

Camel 2.9: A String the denes the transaction isolation level of the will be used.

Allowed values are TRANSACTION_NONE, TRANSACTION_READ_UNCOMMITTED,

TRANSACTION_READ_COMMITTED, TRANSACTION_REPEATABLE_READ,

TRANSACTION_SERIALIZABLE

Message Headers

Camel will populate the result message, either IN or OUT with a header with

the operationName used:

Header Type Description

org.apache.camel.ibatis.queryName String Camel 1.x: The statementName used (for example: insertAccount).

CamelIBatisStatementName String Camel 2.0: The statementName used (for example: insertAccount).

CamelIBatisResult Object Camel 1.6.2/2.0: The response returned from iBatis in any of the operations. For instance

an INSERT could return the auto-generated key, or number of rows etc.

Message Body

Camel 1.6.1: The response from iBatis will be set as OUT body

Camel 1.6.2/2.0: The response from iBatis will only be set as body if it's a

SELECT statement. That means, for example, for INSERT statements Camel

will not replace the body. This allows you to continue routing and keep the

original body. The response from iBatis is always stored in the header with

the key CamelIBatisResult.

Samples

For example if you wish to consume beans from a JMS queue and insert them

into a database you could do the following:

from("activemq:queue:newAccount").

to("ibatis:insertAccount?statementType=Insert");

Notice we have to specify the statementType, as we need to instruct Camel

which SqlMapClient operation to invoke.

Where insertAccount is the iBatis ID in the SQL map le:

insert into ACCOUNT (

ACC_ID,

ACC_FIRST_NAME,

709 CHAPTER 11 - COMPONENT APPENDIX

ACC_LAST_NAME,

ACC_EMAIL

)

values (

#id#, #firstName#, #lastName#, #emailAddress#

)

</insert>

Using StatementType for better control of IBatis

Available as of Camel 1.6.1/2.0

When routing to an iBatis endpoint you want more ne grained control so you

can control whether the SQL statement to be executed is a SELEECT,UPDATE,

DELETE or INSERT etc. This is now possible in Camel 1.6.1/2.0. So for instance

if we want to route to an iBatis endpoint in which the IN body contains

parameters to a SELECT statement we can do:

from("direct:start")

.to("ibatis:selectAccountById?statementType=QueryForObject")

.to("mock:result");

In the code above we can invoke the iBatis statement selectAccountById

and the IN body should contain the account id we want to retrieve, such as

an Integer type.

We can do the same for some of the other operations, such as

QueryForList:

from("direct:start")

.to("ibatis:selectAllAccounts?statementType=QueryForList")

.to("mock:result");

And the same for UPDATE, where we can send an Account object as IN body

to iBatis:

from("direct:start")

.to("ibatis:updateAccount?statementType=Update")

.to("mock:result");

Scheduled polling example

Since this component does not support scheduled polling, you need to use

another mechanism for triggering the scheduled polls, such as the Timer or

Quartz components.

CHAPTER 11 - COMPONENT APPENDIX 710

In the sample below we poll the database, every 30 seconds using the

Timer component and send the data to the JMS queue:

from("timer://pollTheDatabase?delay=30000").to("ibatis:selectAllAccounts?statementType=QueryForList").to("activemq:queue:allAccounts");

And the iBatis SQL map le used:

select * from ACCOUNT

</select>

Using onConsume

This component supports executing statements after data have been

consumed and processed by Camel. This allows you to do post updates in the

database. Notice all statements must be UPDATE statements. Camel supports

executing multiple statements whose name should be separated by comma.

The route below illustrates we execute the consumeAccount statement

data is processed. This allows us to change the status of the row in the

database to processed, so we avoid consuming it twice or more.

from("ibatis:selectUnprocessedAccounts?consumer.onConsume=consumeAccount").to("mock:results");

And the statements in the sqlmap le:

select * from ACCOUNT where PROCESSED = false

</select>

update ACCOUNT set PROCESSED = true where ACC_ID = #id#

</update>

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

711 CHAPTER 11 - COMPONENT APPENDIX

IRC COMPONENT

The irc component implements an IRC (Internet Relay Chat) transport.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-irc</artifactId>

</dependency>

URI format

irc:nick@host[:port]/#room[?options]

In Camel 2.0, you can also use the following format:

irc:nick@host[:port]?channels=#channel1,#channel2,#channel3[?options]

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Description Example Default

Value

channels Camel 2.0: Comma separated list of IRC channels to

join. channels=#channel1,#channel2 null

nickname The nickname used in chat. irc:MyNick@irc.server.org#channel or

irc:irc.server.org#channel?nickname=MyUser null

username The IRC server user name. irc:MyUser@irc.server.org#channel or

irc:irc.server.org#channel?username=MyUser

Same as

nickname.

password The IRC server password. password=somepass None

realname The IRC user's actual name. realname=MyName None

colors Whether or not the server supports color codes. true, false true

onReply Whether or not to handle general responses to

commands or informational messages. true, false false

onNick Handle nickname change events. true, false true

onQuit Handle user quit events. true, false true

onJoin Handle user join events. true, false true

onKick Handle kick events. true, false true

onMode Handle mode change events. true, false true

onPart Handle user part events. true, false true

onTopic Handle topic change events. true, false true

onPrivmsg Handle message events. true, false true

CHAPTER 11 - COMPONENT APPENDIX 712

trustManager Camel 2.0: The trust manager used to verify the SSL

server's certicate. trustManager=#referenceToTrustManagerBean

The default trust

manager, which

accepts all

certicates, will

be used.

keys

Camel 2.2: Comma separated list of IRC channel

keys. Important to be listed in same order as channels.

When joining multiple channels with only some

needing keys just insert an empty value for that

channel.

irc:MyNick@irc.server.org/

#channel?keys=chankey null

SSL Support

As of Camel 2.0, you can also connect to an SSL enabled IRC server, as

follows:

ircs:host[:port]/#room?username=user&password=pass

By default, the IRC transport uses SSLDefaultTrustManager. If you need to

provide your own custom trust manager, use the trustManager parameter

as follows:

ircs:host[:port]/

#room?username=user&password=pass&trustManager=#referenceToMyTrustManagerBean

Using keys

Available as of Camel 2.2

Some irc rooms requires you to provide a key to be able to join that

channel. The key is just a secret word.

For example we join 3 channels where as only channel 1 and 3 uses a key.

irc:nick@irc.server.org?channels=#chan1,#chan2,#chan3&keys=chan1Key,,chan3key

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

JASYPT COMPONENT

Available as of Camel 2.5

713 CHAPTER 11 - COMPONENT APPENDIX

Jasypt is a simplied encryption library which makes encryption and

decryption easy. Camel integrates with Jasypt to allow sensitive information

in Properties les to be encrypted. By dropping camel-jasypt on the

classpath those encrypted values will automatic be decrypted on-the-y by

Camel. This ensures that human eyes can't easily spot sensitive information

such as usernames and passwords.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-jasypt</artifactId>

</dependency>

Tooling

The Jasypt component provides a little command line tooling to encrypt or

decrypt values.

The console output the syntax and which options it provides:

Apache Camel Jasypt takes the following options

-h or -help = Displays the help screen

-c or -command <command> = Command either encrypt or decrypt

-p or -password <password> = Password to use

-i or -input <input> = Text to encrypt or decrypt

-a or -algorithm <algorithm> = Optional algorithm to use

For example to encrypt the value tiger you run with the following

parameters. In the apache camel kit, you cd into the lib folder and run the

following java cmd, where <CAMEL_HOME> is where you have downloaded

and extract the Camel distribution.

$ cd <CAMEL_HOME>/lib

$ java -jar camel-jasypt-2.5.0.jar -c encrypt -p secret -i tiger

Which outputs the following result

Encrypted text: qaEEacuW7BUti8LcMgyjKw==

This means the encrypted representation qaEEacuW7BUti8LcMgyjKw== can

be decrypted back to tiger if you know the master password which was

secret.

CHAPTER 11 - COMPONENT APPENDIX 714

If you run the tool again then the encrypted value will return a dierent

result. But decrypting the value will always return the correct original value.

So you can test it by running the tooling using the following parameters:

$ cd <CAMEL_HOME>/lib

$ java -jar camel-jasypt-2.5.0.jar -c decrypt -p secret -i qaEEacuW7BUti8LcMgyjKw==

Which outputs the following result:

Decrypted text: tiger

The idea is then to use those encrypted values in your Properties les. Notice

how the password value is encrypted and the value has the tokens

surrounding ENC(value here)

# refer to a mock endpoint name by that encrypted password

cool.result=mock:{{cool.password}}

# here is a password which is encrypted

cool.password=ENC(bsW9uV37gQ0QHFu7KO03Ww==)

Tooling dependencies for Camel 2.5 and 2.6

The tooling requires the following JARs in the classpath, which has been

enlisted in the MANIFEST.MF le of camel-jasypt with optional/ as prex.

Hence why the java cmd above can pickup the needed JARs from the Apache

Distribution in the optional directory.

jasypt-1.6.jar commons-lang-2.4.jar commons-codec-1.4.jar icu4j-4.0.1.jar

Tooling dependencies for Camel 2.7 or better

Jasypt 1.7 onwards is now fully standalone so no additional JARs is needed.

URI Options

The options below are exclusive for the Jasypt component.

Name Default

Value Type Description

password null String Species the master password to use for decrypting. This option is mandatory. See below for

more details.

algorithm null String Name of an optional algorithm to use.

715 CHAPTER 11 - COMPONENT APPENDIX

Java 1.5 users

The icu4j-4.0.1.jar is only needed when running on JDK 1.5.

This JAR is not distributed by Apache Camel and you have to download it

manually and copy it to the lib/optional directory of the Camel

distribution.

You can download it from Apache Central Maven repo.

Protecting the master password

The master password used by Jasypt must be provided, so its capable of

decrypting the values. However having this master password out in the

opening may not be an ideal solution. Therefore you could for example

provided it as a JVM system property or as a OS environment setting. If you

decide to do so then the password option supports prexes which dictates

this. sysenv: means to lookup the OS system environment with the given

key. sys: means to lookup a JVM system property.

For example you could provided the password before you start the

application

$ export CAMEL_ENCRYPTION_PASSWORD=secret

Then start the application, such as running the start script.

When the application is up and running you can unset the environment

$ unset CAMEL_ENCRYPTION_PASSWORD

The password option is then a matter of dening as follows:

password=sysenv:CAMEL_ENCRYPTION_PASSWORD.

Example with Java DSL

In Java DSL you need to congure Jasypt as a JasyptPropertiesParser

instance and set it on the Properties component as show below:

// create the jasypt properties parser

JasyptPropertiesParser jasypt = new JasyptPropertiesParser();

// and set the master password

jasypt.setPassword("secret");

// create the properties component

PropertiesComponent pc = new PropertiesComponent();

pc.setLocation("classpath:org/apache/camel/component/jasypt/myproperties.properties");

CHAPTER 11 - COMPONENT APPENDIX 716

// and use the jasypt properties parser so we can decrypt values

pc.setPropertiesParser(jasypt);

// add properties component to camel context

context.addComponent("properties", pc);

The properties le myproperties.properties then contain the encrypted

value, such as shown below. Notice how the password value is encrypted and

the value has the tokens surrounding ENC(value here)

# refer to a mock endpoint name by that encrypted password

cool.result=mock:{{cool.password}}

# here is a password which is encrypted

cool.password=ENC(bsW9uV37gQ0QHFu7KO03Ww==)

Example with Spring XML

In Spring XML you need to congure the JasyptPropertiesParser which is

shown below. Then the Camel Properties component is told to use jasypt as

the properties parser, which means Jasypt have its chance to decrypt values

looked up in the properties.

</bean>

<bean id="properties"

class="org.apache.camel.component.properties.PropertiesComponent">

<property name="location" value="classpath:org/apache/camel/component/jasypt/

myproperties.properties"/>

</bean>

The Properties component can also be inlined inside the <camelContext> tag

which is shown below. Notice how we use the propertiesParserRef

attribute to refer to Jasypt.

<!-- password is mandatory, you can prefix it with sysenv: or sys: to indicate it

should use

717 CHAPTER 11 - COMPONENT APPENDIX

an OS environment or JVM system property value, so you dont have the master

password defined here -->

</bean>

<propertyPlaceholder id="properties"

location="classpath:org/apache/camel/component/jasypt/

myproperties.properties"

propertiesParserRef="jasypt"/>

<route>

</route>

</camelContext>

See Also

▪ Security

▪ Properties

▪ Encrypted passwords in ActiveMQ - ActiveMQ has a similar feature as

this camel-jasypt component

JAVASPACE COMPONENT

Available as of Camel 2.1

The javaspace component is a transport for working with any JavaSpace

compliant implementation and this component has been tested with both the

Blitz implementation and the GigaSpace implementation .

This component can be used for sending and receiving any object inheriting

from the Jini net.jini.core.entry.Entry class. It is also possible to pass

the bean ID of a template that can be used for reading/taking the entries

from the space.

This component can be used for sending/receiving any serializable object

acting as a sort of generic transport. The JavaSpace component contains a

special optimization for dealing with the BeanExchange. It can be used to

invoke a POJO remotely, using a JavaSpace as a transport.

This latter feature can provide a simple implementation of the master/worker

pattern, where a POJO provides the business logic for the worker.

Look at the test cases for examples of various use cases for this component.

Maven users will need to add the following dependency to their pom.xml

for this component:

CHAPTER 11 - COMPONENT APPENDIX 718

<groupId>org.apache.camel</groupId>

<artifactId>camel-javaspace</artifactId>

</dependency>

URI format

javaspace:jini://host[?options]

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Default

Value Description

spaceName null Species the JavaSpace name.

verb take Species the verb for getting JavaSpace entries. The values can be: take or read.

transactional false If true, sending and receiving entries is performed within a transaction.

transactionalTimeout Long.MAX_VALUE Species the transaction timeout.

concurrentConsumers 1 Species the number of concurrent consumers getting entries from the JavaSpace.

templateId null If present, this option species the Spring bean ID of the template to use for reading/taking

entries.

Examples

Sending and Receiving Entries

// sending route

from("direct:input")

.to("javaspace:jini://localhost?spaceName=mySpace");

// receiving Route

from("javaspace:jini://localhost?spaceName=mySpace&templateId=template&verb=take&concurrentConsumers=1")

.to("mock:foo");

In this case the payload can be any object that inherits from the Jini Entry

type.

719 CHAPTER 11 - COMPONENT APPENDIX

Sending and receiving serializable objects

Using the preceding routes, it is also possible to send and receive any

serializable object. The JavaSpace component detects that the payload is not

a Jini Entry and then it automatically wraps the payload with a Camel Jini

Entry. In this way, a JavaSpace can be used as a generic transport

mechanism.

Using JavaSpace as a remote invocation transport

The JavaSpace component has been tailored to work in combination with the

Camel bean component. It is therefore possible to call a remote POJO using

JavaSpace as the transport:

// client side

from("direct:input")

.to("javaspace:jini://localhost?spaceName=mySpace");

// server side

from("javaspace:jini://localhost?concurrentConsumers=10&spaceName=mySpace")

.to("mock:foo");

In the code there are two test cases showing how to use a POJO to realize the

master/worker pattern. The idea is to use the POJO to provide the business

logic and rely on Camel for sending/receiving requests/replies with the proper

correlation.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

JBI COMPONENT

The jbi component is implemented by the ServiceMix Camel module and

provides integration with a JBI Normalized Message Router, such as the one

provided by Apache ServiceMix.

The following code:

from("jbi:endpoint:http://foo.bar.org/MyService/MyEndpoint")

CHAPTER 11 - COMPONENT APPENDIX 720

See below for information about how to use StreamSource types

from ServiceMix in Camel.

Automatically exposes a new endpoint to the bus, where the service QName

is {http://foo.bar.org}MyService and the endpoint name is MyEndpoint

(see URI-format).

When a JBI endpoint appears at the end of a route, for example:

to("jbi:endpoint:http://foo.bar.org/MyService/MyEndpoint")

The messages sent by this producer endpoint are sent to the already

deployed JBI endpoint.

URI format

jbi:service:serviceNamespace[sep]serviceName[?options]

jbi:endpoint:serviceNamespace[sep]serviceName[sep]endpointName[?options]

jbi:name:endpointName[?options]

The separator that should be used in the endpoint URL is:

•/(forward slash), if serviceNamespace starts with http://, or

•:(colon), if serviceNamespace starts with urn:foo:bar.

For more details of valid JBI URIs see the ServiceMix URI Guide.

Using the jbi:service: or jbi:endpoint: URI formats sets the service

QName on the JBI endpoint to the one specied. Otherwise, the default

Camel JBI Service QName is used, which is:

{http://activemq.apache.org/camel/schema/jbi}endpoint

You can append query options to the URI in the following format,

?option=value&option=value&...

Examples

jbi:service:http://foo.bar.org/MyService

jbi:endpoint:urn:foo:bar:MyService:MyEndpoint

jbi:endpoint:http://foo.bar.org/MyService/MyEndpoint

jbi:name:cheese

721 CHAPTER 11 - COMPONENT APPENDIX

URI options

Name Default value Description

mep

MEP of the

Camel

Exchange

Allows users to override the MEP

set on the Exchange object. Valid

values for this option are in-only,

in-out,robust-in-out and in-

optional-out.

operation

Value of the

jbi.operation

header

property

Species the JBI operation for the

MessageExchange. If no value is

supplied, the JBI binding will use

the value of the jbi.operation

header property.

serialization basic

Default value (basic) will check if

headers are serializable by looking

at the type, setting this option to

strict will detect objects that can

not be serialized although they

implement the Serializable

interface. Set to nocheck to disable

this check altogether, note that this

should only be used for in-memory

transports like SEDAFlow,

otherwise you can expect to get

NotSerializableException

thrown at runtime.

convertException false

false: send any exceptions thrown

from the Camel route back

unmodied

true: convert all exceptions to a JBI

FaultException (can be used to

avoid non-serializable exceptions

or to implement generic error

handling

Examples

jbi:service:http://foo.bar.org/MyService?mep=in-out (override the MEP, use

InOut JBI MessageExchanges)

jbi:endpoint:urn:foo:bar:MyService:MyEndpoint?mep=in (override the MEP, use

CHAPTER 11 - COMPONENT APPENDIX 722

InOnly JBI MessageExchanges)

jbi:endpoint:urn:foo:bar:MyService:MyEndpoint?operation={http://www.mycompany.org}AddNumbers

(overide the operation for the JBI Exchange to {http://www.mycompany.org}AddNumbers)

Using Stream bodies

If you are using a stream type as the message body, you should be aware

that a stream is only capable of being read once. So if you enable DEBUG

logging, the body is usually logged and thus read. To deal with this, Camel

has a streamCaching option that can cache the stream, enabling you to read

it multiple times.

from("jbi:endpoint:http://foo.bar.org/MyService/

MyEndpoint").streamCaching().to("xslt:transform.xsl", "bean:doSomething");

From Camel 1.5 onwards, the stream caching is default enabled, so it is not

necessary to set the streamCaching() option.

In Camel 2.0 we store big input streams (by default, over 64K) in a temp le

using CachedOutputStream. When you close the input stream, the temp le

will be deleted.

Creating a JBI Service Unit

If you have some Camel routes that you want to deploy inside JBI as a

Service Unit, you can use the JBI Service Unit Archetype to create a new

Maven project for the Service Unit.

If you have an existing Maven project that you need to convert into a JBI

Service Unit, you may want to consult ServiceMix Maven JBI Plugins for

further help. The key steps are as follows:

• Create a Spring XML le at src/main/resources/camel-

context.xml to bootstrap your routes inside the JBI Service Unit.

• Change the POM le's packaging to jbi-service-unit.

Your pom.xml should look something like this to enable the jbi-service-

unit packaging:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/

XMLSchema-instance"

xsi:schemaLocation="http://maven.apache.org/POM/4.0.0

http://maven.apache.org/maven-v4_0_0.xsd">

<groupId>myGroupId</groupId>

723 CHAPTER 11 - COMPONENT APPENDIX

<artifactId>myArtifactId</artifactId>

<packaging>jbi-service-unit</packaging>

<version>1.0-SNAPSHOT</version>

<name>A Camel based JBI Service Unit</name>

<url>http://www.myorganization.org</url>

<camel-version>1.0.0</camel-version>

<servicemix-version>3.3</servicemix-version>

</properties>

<groupId>org.apache.servicemix</groupId>

<artifactId>servicemix-camel</artifactId>

<version>${servicemix-version}</version>

</dependency>

<groupId>org.apache.servicemix</groupId>

<artifactId>servicemix-core</artifactId>

<version>${servicemix-version}</version>

<scope>provided</scope>

</dependency>

</dependencies>

<build>

<defaultGoal>install</defaultGoal>

<groupId>org.apache.maven.plugins</groupId>

<artifactId>maven-compiler-plugin</artifactId>

</configuration>

</plugin>

<groupId>org.apache.servicemix.tooling</groupId>

<artifactId>jbi-maven-plugin</artifactId>

<version>${servicemix-version}</version>

</plugin>

</plugins>

</build>

</project>

CHAPTER 11 - COMPONENT APPENDIX 724

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

• ServiceMix Camel module

• Using Camel with ServiceMix

• Cookbook on using Camel with ServiceMix

JCR COMPONENT

The jcr component allows you to add nodes to a JCR compliant content

repository (for example, Apache Jackrabbit).

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-jcr</artifactId>

</dependency>

URI format

jcr://user:password@repository/path/to/node

Usage

The repository element of the URI is used to look up the JCR Repository

object in the Camel context registry.

If a message is sent to a JCR producer endpoint:

• A new node is created in the content repository,

• All the message properties of the IN message are transformed to JCR

Value instances and added to the new node,

• The node's UUID is returned in the OUT message.

725 CHAPTER 11 - COMPONENT APPENDIX

Message properties

All message properties are converted to node properties, except for the

CamelJcrNodeName property (you can refer to JcrConstants.NODE_NAME in

your code), which is used to determine the node name.

Example

The snippet below creates a node named node under the /home/test node in

the content repository. One additional attribute is added to the node as well:

my.contents.property which will contain the body of the message being

sent.

from("direct:a").setProperty(JcrConstants.JCR_NODE_NAME, constant("node"))

.setProperty("my.contents.property", body()).to("jcr://user:pass@repository/home/

test");

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

JDBC COMPONENT

The jdbc component enables you to access databases through JDBC, where

SQL queries and operations are sent in the message body. This component

uses the standard JDBC API, unlike the SQL Component component, which

uses spring-jdbc.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-jdbc</artifactId>

</dependency>

CHAPTER 11 - COMPONENT APPENDIX 726

This component can only be used to dene producer endpoints,

which means that you cannot use the JDBC component in a from()

statement.

This component can not be used as a Transactional Client. If you

need transaction support in your route, you should use the SQL

component instead.

URI format

jdbc:dataSourceName[?options]

This component only supports producer endpoints.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Default

Value Description

readSize 0 /2000

The default maximum

number of rows that can

be read by a polling

query. The default value

is 2000 for Camel 1.5.0

or older. In newer

releases the default

value is 0.

727 CHAPTER 11 - COMPONENT APPENDIX

statement.<xxx> null

Camel 2.1: Sets

additional options on

the

java.sql.Statement

that is used behind the

scenes to execute the

queries. For instance,

statement.maxRows=10.

For detailed

documentation, see the

java.sql.Statement

javadoc documentation.

useJDBC4ColumnNameAndLabelSemantics true

Camel 1.6.3/2.2: Sets

whether to use JDBC 4/3

column label/name

semantics. You can use

this option to turn it

false in case you have

issues with your JDBC

driver to select data.

This only applies when

using SQL SELECT using

aliases (e.g. SQL

SELECT id as

identifier, name as

given_name from

persons).

CHAPTER 11 - COMPONENT APPENDIX 728

resetAutoCommit true

Camel 2.9: Camel will

set the autoCommit on

the JDBC connection to

be false, commit the

change after executed

the statement and reset

the autoCommit ag of

the connection at the

end, if the

resetAutoCommit is

true. If the JDBC

connection doesn't

support to reset the

autoCommit ag, you

can set the

resetAutoCommit ag to

be false, and Camel will

not try to reset the

autoCommit ag.

Result

The result is returned in the OUT body as an ArrayList<HashMap<String,

Object>>. The List object contains the list of rows and the Map objects

contain each row with the String key as the column name.

Note: This component fetches ResultSetMetaData to be able to return

the column name as the key in the Map.

Message Headers

Header Description

CamelJdbcRowCount If the query is a SELECT, query the row count is

returned in this OUT header.

CamelJdbcUpdateCount If the query is an UPDATE, query the update

count is returned in this OUT header.

Samples

In the following example, we fetch the rows from the customer table.

First we register our datasource in the Camel registry as testdb:

729 CHAPTER 11 - COMPONENT APPENDIX

JndiRegistry reg = super.createRegistry();

reg.bind("testdb", ds);

return reg;

Then we congure a route that routes to the JDBC component, so the SQL will

be executed. Note how we refer to the testdb datasource that was bound in

the previous step:

// lets add simple route

public void configure() throws Exception {

from("direct:hello").to("jdbc:testdb?readSize=100");

}

Or you can create a DataSource in Spring like this:

<route>

<constant>select * from customer</constant>

</setBody>

</route>

</camelContext>

</bean>

We create an endpoint, add the SQL query to the body of the IN message,

and then send the exchange. The result of the query is returned in the OUT

body:

// first we create our exchange using the endpoint

Endpoint endpoint = context.getEndpoint("direct:hello");

Exchange exchange = endpoint.createExchange();

// then we set the SQL on the in body

exchange.getIn().setBody("select * from customer order by ID");

// now we send the exchange to the endpoint, and receives the response from Camel

Exchange out = template.send(endpoint, exchange);

// assertions of the response

assertNotNull(out);

CHAPTER 11 - COMPONENT APPENDIX 730

assertNotNull(out.getOut());

ArrayList<HashMap<String,Object>> data = out.getOut().getBody(ArrayList.class);

assertNotNull("out body could not be converted to an ArrayList - was: "

+ out.getOut().getBody(), data);

assertEquals(2, data.size());

HashMap<String,Object> row = data.get(0);

assertEquals("cust1", row.get("ID"));

assertEquals("jstrachan", row.get("NAME"));

row = data.get(1);

assertEquals("cust2", row.get("ID"));

assertEquals("nsandhu", row.get("NAME"));

If you want to work on the rows one by one instead of the entire ResultSet at

once you need to use the Splitter EIP such as:

from("direct:hello")

// here we split the data from the testdb into new messages one by one

// so the mock endpoint will receive a message per row in the table

.to("jdbc:testdb").split(body()).to("mock:result");

Sample - Polling the database every minute

If we want to poll a database using the JDBC component, we need to combine

it with a polling scheduler such as the Timer or Quartz etc. In the following

example, we retrieve data from the database every 60 seconds:

from("timer://foo?period=60000").setBody(constant("select * from

customer")).to("jdbc:testdb").to("activemq:queue:customers");

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ SQL

JETTY COMPONENT

The jetty component provides HTTP-based endpoints for consuming HTTP

requests. That is, the Jetty component behaves as a simple Web server.

Jetty can also be used as a http client which mean you can also use it with

Camel as a [Producer].

731 CHAPTER 11 - COMPONENT APPENDIX

Upgrading from Jetty 6 to 7

You can read more about upgrading Jetty here

Stream

Jetty is stream based, which means the input it receives is

submitted to Camel as a stream. That means you will only be able

to read the content of the stream once.

If you nd a situation where the message body appears to be

empty or you need to access the data multiple times (eg: doing

multicasting, or redelivery error handling)

you should use Stream caching or convert the message body to a

String which is safe to be re-read multiple times.

URI format

jetty:http://hostname[:port][/resourceUri][?options]

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Default

Value Description

sessionSupport false Species whether to enable the session manager on the server side of Jetty.

httpClient.XXX null Camel 1.6.0/2.0: Conguration of Jetty's HttpClient. For example, setting

httpClient.idleTimeout=30000 sets the idle timeout to 30 seconds.

httpBindingRef null Camel 1.6.0/2.0: Reference to an org.apache.camel.component.http.HttpBinding in the

Registry. HttpBinding can be used to customize how a response should be written.

jettyHttpBindingRef null Camel 2.6.0+: Reference to an org.apache.camel.component.jetty.JettyHttpBinding in the

Registry. JettyHttpBinding can be used to customize how a response should be written.

matchOnUriPrefix false Camel 2.0: Whether or not the CamelServlet should try to nd a target consumer by matching

the URI prex if no exact match is found. See here How do I let Jetty match wildcards.

handlers null

Camel 1.6.1/2.0: Species a comma-delimited set of org.mortbay.jetty.Handler instances in

your Registry (such as your Spring ApplicationContext). These handlers are added to the Jetty

servlet context (for example, to add security).

chunked true Camel 2.2: If this option is false Jetty servlet will disable the HTTP streaming and set the content-

length header on the response

enableJmx false Camel 2.3: If this option is true, Jetty JMX support will be enabled for this endpoint. See Jetty JMX

support for more details.

CHAPTER 11 - COMPONENT APPENDIX 732

disableStreamCache false

Camel 2.3: Determines whether or not the raw input stream from Jetty is cached or not (Camel

will read the stream into a in memory/overow to le, Stream caching) cache. By default Camel

will cache the Jetty input stream to support reading it multiple times to ensure it Camel can

retrieve all data from the stream. However you can set this option to true when you for example

need to access the raw stream, such as streaming it directly to a le or other persistent store.

DefaultHttpBinding will copy the request input stream into a stream cache and put it into

message body if this option is false to support reading the stream multiple times. If you use Jetty

to bridge/proxy an endpoint then consider enabling this option to improve performance, in case

you do not need to read the message payload multiple times.

bridgeEndpoint false

Camel 2.1: If the option is true , HttpProducer will ignore the Exchange.HTTP_URI header, and

use the endpoint's URI for request. You may also set the throwExceptionOnFailure to be false

to let the HttpProducer send all the fault response back.

Camel 2.3: If the option is true, HttpProducer and CamelServlet will skip the gzip processing if

the content-encoding is "gzip". Also consider setting disableStreamCache to true to optimize

when bridging.

enableMultipartFilter true

Camel 2.5: Whether Jetty org.eclipse.jetty.servlets.MultiPartFilter is enabled or not.

You should set this value to false when bridging endpoints, to ensure multipart requests is

proxied/bridged as well.

multipartFilterRef null Camel 2.6: Allows using a custom multipart lter. Note: setting multipartFilterRef forces the

value of enableMultipartFilter to true.

FiltersRef null Camel 2.9: Allows using a custom lters which is putted into a list and can be nd in the Registry

continuationTimeout null

Camel 2.6: Allows to set a timeout in millis when using Jetty as consumer (server). By default

Jetty uses 30000. You can use a value of <= 0 to never expire. If a timeout occurs then the

request will be expired and Jetty will return back a http error 503 to the client. This option is only

in use when using Jetty with the Asynchronous Routing Engine.

useContinuation true Camel 2.6: Whether or not to use Jetty continuations for the Jetty Server.

sslContextParametersRef null

Camel 2.8: Reference to a org.apache.camel.util.jsse.SSLContextParameters in the

Registry. This reference overrides any congured SSLContextParameters at the component

level. See Using the JSSE Conguration Utility.

Message Headers

Camel uses the same message headers as the HTTP component.

From Camel 2.2, it also uses (Exchange.HTTP_CHUNKED,CamelHttpChunked)

header to turn on or turn o the chuched encoding on the camel-jetty

consumer.

Camel also populates all request.parameter and request.headers. For

example, given a client request with the URL, http://myserver/

myserver?orderid=123, the exchange will contain a header named orderid

with the value 123. This feature was introduced in Camel 1.5.

From Camel 1.6.3 and Camel 2.2.0, you can get the request.parameter

from the message header not only from Get Method, but also other HTTP

method.

Usage

The Jetty component only supports consumer endpoints. Therefore a Jetty

endpoint URI should be used only as the input for a Camel route (in a

from() DSL call). To issue HTTP requests against other HTTP endpoints, use

the HTTP Component

Component Options

The JettyHttpComponent provides the following options:

733 CHAPTER 11 - COMPONENT APPENDIX

Name Default

Value Description

enableJmx false Camel 2.3: If this option is true, Jetty JMX support will be enabled for this endpoint. See

Jetty JMX support for more details.

sslKeyPassword null Consumer only: The password for the keystore when using SSL.

sslPassword null Consumer only: The password when using SSL.

sslKeystore null Consumer only: The path to the keystore.

minThreads null Camel 2.5 Consumer only: To set a value for minimum number of threads in server

thread pool.

maxThreads null Camel 2.5 Consumer only: To set a value for maximum number of threads in server

thread pool.

threadPool null Camel 2.5 Consumer only: To use a custom thread pool for the server.

sslSocketConnectors null Camel 2.3 Consumer only: A map which contains per port number specic SSL

connectors. See section SSL support for more details.

socketConnectors null

Camel 2.5 Consumer only: A map which contains per port number specic HTTP

connectors. Uses the same principle as sslSocketConnectors and therefore see section

SSL support for more details.

sslSocketConnectorProperties null Camel 2.5 Consumer only. A map which contains general SSL connector properties. See

section SSL support for more details.

socketConnectorProperties null

Camel 2.5 Consumer only. A map which contains general HTTP connector properties.

Uses the same principle as sslSocketConnectorProperties and therefore see section SSL

support for more details.

httpClient null Producer only: To use a custom HttpClient with the jetty producer.

httpClientMinThreads null Producer only: To set a value for minimum number of threads in HttpClient thread pool.

httpClientMaxThreads null Producer only: To set a value for maximum number of threads in HttpClient thread pool.

httpClientThreadPool null Producer only: To use a custom thread pool for the client.

sslContextParameters null Camel 2.8: To congure a custom SSL/TLS conguration options at the component level.

See Using the JSSE Conguration Utility for more details.

Sample

In this sample we dene a route that exposes a HTTP service at

http://localhost:8080/myapp/myservice:

from("jetty:http://localhost:{{port}}/myapp/myservice").process(new MyBookService());

Our business logic is implemented in the MyBookService class, which

accesses the HTTP request contents and then returns a response.

Note: The assert call appears in this example, because the code is part of

an unit test.

public class MyBookService implements Processor {

public void process(Exchange exchange) throws Exception {

// just get the body as a string

String body = exchange.getIn().getBody(String.class);

// we have access to the HttpServletRequest here and we can grab it if we

need it

HttpServletRequest req = exchange.getIn().getBody(HttpServletRequest.class);

assertNotNull(req);

// for unit testing

CHAPTER 11 - COMPONENT APPENDIX 734

Usage of localhost

When you specify localhost in a URL, Camel exposes the endpoint

only on the local TCP/IP network interface, so it cannot be accessed

from outside the machine it operates on.

If you need to expose a Jetty endpoint on a specic network interface, the

numerical IP address of this interface should be used as the host. If you

need to expose a Jetty endpoint on all network interfaces, the 0.0.0.0

address should be used.

assertEquals("bookid=123", body);

// send a html response

exchange.getOut().setBody("<html><body>Book 123 is Camel in

Action</body></html>");

}

The following sample shows a content-based route that routes all requests

containing the URI parameter, one, to the endpoint, mock:one, and all others

to mock:other.

from("jetty:" + serverUri)

.choice()

.when().simple("${header.one}").to("mock:one")

.otherwise()

.to("mock:other");

So if a client sends the HTTP request, http://serverUri?one=hello, the

Jetty component will copy the HTTP request parameter, one to the

exchange's in.header. We can then use the simple language to route

exchanges that contain this header to a specic endpoint and all others to

another. If we used a language more powerful than Simple--such as EL or

OGNL--we could also test for the parameter value and do routing based on

the header value as well.

Session Support

The session support option, sessionSupport, can be used to enable a

HttpSession object and access the session object while processing the

exchange. For example, the following route enables sessions:

735 CHAPTER 11 - COMPONENT APPENDIX

<route>

<route>

The myCode Processor can be instantiated by a Spring bean element:

Where the processor implementation can access the HttpSession as follows:

public void process(Exchange exchange) throws Exception {

HttpSession session = exchange.getIn(HttpMessage.class).getRequest().getSession();

...

}

SSL Support (HTTPS)

Using the JSSE Conguration Utility

As of Camel 2.8, the Jetty component supports SSL/TLS conguration through

the Camel JSSE Conguration Utility. This utility greatly decreases the

amount of component specic code you need to write and is congurable at

the endpoint and component levels. The following examples demonstrate

how to use the utility with the Jetty component.

Programmatic conguration of the component

KeyStoreParameters ksp = new KeyStoreParameters();

ksp.setResource("/users/home/server/keystore.jks");

ksp.setPassword("keystorePassword");

KeyManagersParameters kmp = new KeyManagersParameters();

kmp.setKeyStore(ksp);

kmp.setKeyPassword("keyPassword");

SSLContextParameters scp = new SSLContextParameters();

scp.setKeyManagers(kmp);

JettyComponent jettyComponent = getContext().getComponent("jetty",

JettyComponent.class);

jettyComponent.setSslContextParameters(scp);

CHAPTER 11 - COMPONENT APPENDIX 736

Spring DSL based conguration of endpoint

...

<camel:sslContextParameters

id="sslContextParameters">

<camel:keyManagers

keyPassword="keyPassword">

<camel:keyStore

resource="/users/home/server/keystore.jks"

password="keystorePassword"/>

</camel:keyManagers>

</camel:sslContextParameters>...

...

<to uri="jetty:https://127.0.0.1/mail/

?sslContextParametersRef=sslContextParameters"/>

...

Conguring Jetty Directly

Jetty provides SSL support out of the box. To enable Jetty to run in SSL mode,

simply format the URI with the https:// prex---for example:

Jetty also needs to know where to load your keystore from and what

passwords to use in order to load the correct SSL certicate. Set the following

JVM System Properties:

until Camel 2.2

•jetty.ssl.keystore species the location of the Java keystore le,

which contains the Jetty server's own X.509 certicate in a key entry.

A key entry stores the X.509 certicate (eectively, the public key)

and also its associated private key.

•jetty.ssl.password the store password, which is required to access

the keystore le (this is the same password that is supplied to the

keystore command's -storepass option).

•jetty.ssl.keypassword the key password, which is used to access

the certicate's key entry in the keystore (this is the same password

that is supplied to the keystore command's -keypass option).

from Camel 2.3 onwards

•org.eclipse.jetty.ssl.keystore species the location of the Java

keystore le, which contains the Jetty server's own X.509 certicate

in a key entry. A key entry stores the X.509 certicate (eectively,

the public key) and also its associated private key.

737 CHAPTER 11 - COMPONENT APPENDIX

•org.eclipse.jetty.ssl.password the store password, which is

required to access the keystore le (this is the same password that is

supplied to the keystore command's -storepass option).

•org.eclipse.jetty.ssl.keypassword the key password, which is

used to access the certicate's key entry in the keystore (this is the

same password that is supplied to the keystore command's -

keypass option).

For details of how to congure SSL on a Jetty endpoint, read the following

documentation at the Jetty Site: http://docs.codehaus.org/display/JETTY/

How+to+congure+SSL

Some SSL properties aren't exposed directly by Camel, however Camel

does expose the underlying SslSocketConnector, which will allow you to set

properties like needClientAuth for mutual authentication requiring a client

certicate or wantClientAuth for mutual authentication where a client doesn't

need a certicate but can have one. There's a slight dierence between

Camel 1.6.x and 2.x:

Camel 1.x

</bean>

</property>

</bean>

until Camel 2.2

<map>

</bean>

</entry>

</map>

</property>

</bean>

CHAPTER 11 - COMPONENT APPENDIX 738

Camel 2.3, 2.4

<map>

</bean>

</entry>

</map>

</property>

</bean>

*From Camel 2.5 we switch to use SslSelectChannelConnector *

<map>

</bean>

</entry>

</map>

</property>

</bean>

The value you use as keys in the above map is the port you congure Jetty to

listen on.

Conguring general SSL properties

Available as of Camel 2.5

Instead of a per port number specic SSL socket connector (as shown

above) you can now congure general properties which applies for all SSL

socket connectors (which is not explicit congured as above with the port

number as entry).

739 CHAPTER 11 - COMPONENT APPENDIX

</properties>

</property>

</bean>

How to obtain reference to the X509Certicate

Jetty stores a reference to the certicate in the HttpServletRequest which you

can access from code as follows:

HttpServletRequest req = exchange.getIn().getBody(HttpServletRequest.class);

X509Certificate cert = (X509Certificate)

req.getAttribute("javax.servlet.request.X509Certificate")

Conguring general HTTP properties

Available as of Camel 2.5

Instead of a per port number specic HTTP socket connector (as shown

above) you can now congure general properties which applies for all HTTP

socket connectors (which is not explicit congured as above with the port

number as entry).

</properties>

</property>

</bean>

Default behavior for returning HTTP status codes

The default behavior of HTTP status codes is dened by the

org.apache.camel.component.http.DefaultHttpBinding class, which

handles how a response is written and also sets the HTTP status code.

CHAPTER 11 - COMPONENT APPENDIX 740

If the exchange was processed successfully, the 200 HTTP status code is

returned.

If the exchange failed with an exception, the 500 HTTP status code is

returned, and the stacktrace is returned in the body. If you want to specify

which HTTP status code to return, set the code in the

HttpProducer.HTTP_RESPONSE_CODE header of the OUT message.

Customizing HttpBinding

Available as of Camel 1.5.1/2.0

By default, Camel uses the

org.apache.camel.component.http.DefaultHttpBinding to handle how a

response is written. If you like, you can customize this behavior either by

implementing your own HttpBinding class or by extending

DefaultHttpBinding and overriding the appropriate methods.

The following example shows how to customize the DefaultHttpBinding

in order to change how exceptions are returned:

public class MyJettyHttpBinding extends DefaultJettyHttpBinding {

@Override

protected void populateResponse(Exchange exchange, JettyContentExchange

httpExchange, Message in,

HeaderFilterStrategy strategy, int responseCode)

throws IOException {

Message answer = exchange.getOut();

answer.setHeaders(in.getHeaders());

answer.setHeader(Exchange.HTTP_RESPONSE_CODE, responseCode);

answer.setBody("Not exactly the message the server returned.");

}

We can then create an instance of our binding and register it in the Spring

registry as follows:

And then we can reference this binding when we dene the route:

<route><from uri="jetty:http://0.0.0.0:8080/myapp/

myservice?httpBindingRef=mybinding"/><to uri="bean:doSomething"/></route>

741 CHAPTER 11 - COMPONENT APPENDIX

Jetty handlers and security conguration

Available as of Camel 1.6.1/2.0: You can congure a list of Jetty handlers

on the endpoint, which can be useful for enabling advanced Jetty security

features. These handlers are congured in Spring XML as follows:

<-- Jetty Security handling -->

</bean>

</bean>

</bean>

</bean>

And from Camel 2.3 onwards you can congure a list of Jetty handlers as

follows:

<-- Jetty Security handling -->

</bean>

</bean>

<bean id="securityHandler"

class="org.eclipse.jetty.security.ConstraintSecurityHandler">

</property>

<list>

</list>

CHAPTER 11 - COMPONENT APPENDIX 742

</property>

</bean>

You can then dene the endpoint as:

from("jetty:http://0.0.0.0:9080/myservice?handlers=securityHandler")

If you need more handlers, set the handlers option equal to a comma-

separated list of bean IDs.

How to return a custom HTTP 500 reply message

You may want to return a custom reply message when something goes

wrong, instead of the default reply message Camel Jetty replies with.

You could use a custom HttpBinding to be in control of the message

mapping, but often it may be easier to use Camel's Exception Clause to

construct the custom reply message. For example as show here, where we

return Dude something went wrong with HTTP error code 500:

from("jetty://http://localhost:{{port}}/myserver")

// use onException to catch all exceptions and return a custom reply message

.onException(Exception.class)

.handled(true)

// create a custom failure response

.transform(constant("Dude something went wrong"))

// we must remember to set error code 500 as handled(true)

// otherwise would let Camel thing its a OK response (200)

.setHeader(Exchange.HTTP_RESPONSE_CODE, constant(500))

.end()

// now just force an exception immediately

.throwException(new IllegalArgumentException("I cannot do this"));

Multi-part Form support

From Camel 2.3.0, camel-jetty support to multipart form post out of box. The

submitted form-data are mapped into the message header. Camel-jetty

creates an attachment for each uploaded le. The le name is mapped to the

name of the attachment. The content type is set as the content type of the

attachment le name. You can nd the example here.

Listing 78. Note: getName() functions as shown below in versions 2.5 and higher.

In earlier versions you receive the temporary le name for the attachment instead

// Set the jetty temp directory which store the file for multi part form

// camel-jetty will clean up the file after it handled the request.

743 CHAPTER 11 - COMPONENT APPENDIX

// The option works rightly from Camel 2.4.0

getContext().getProperties().put("CamelJettyTempDir","target");

from("jetty://http://localhost:{{port}}/test").process(new Processor() {

public void process(Exchange exchange) throws Exception {

Message in = exchange.getIn();

assertEquals("Get a wrong attachement size", 1, in.getAttachments().size());

// The file name is attachment id

DataHandler data = in.getAttachment("NOTICE.txt");

assertNotNull("Should get the DataHandle NOTICE.txt", data);

// This assert is wrong, but the correct content-type (application/

octet-stream)

// will not be returned until Jetty makes it available - currently the

content-type

// returned is just the default for FileDataHandler (for the implentation

being used)

//assertEquals("Get a wrong content type","text/plain",

data.getContentType());

assertEquals("Got the wrong name","NOTICE.txt", data.getName());

assertTrue("We should get the data from the DataHandle", data.getDataSource()

.getInputStream().available() > 0);

// The other form date can be get from the message header

exchange.getOut().setBody(in.getHeader("comment"));

}

});

Jetty JMX support

From Camel 2.3.0, camel-jetty supports the enabling of Jetty's JMX

capabilities at the component and endpoint level with the endpoint

conguration taking priority. Note that JMX must be enabled within the Camel

context in order to enable JMX support in this component as the component

provides Jetty with a reference to the MBeanServer registered with the Camel

context. Because the camel-jetty component caches and reuses Jetty

resources for a given protocol/host/port pairing, this conguration option will

only be evaluated during the creation of the rst endpoint to use a protocol/

host/port pairing. For example, given two routes created from the following

XML fragments, JMX support would remain enabled for all endpoints listening

on "https://0.0.0.0".

CHAPTER 11 - COMPONENT APPENDIX 744

The camel-jetty component also provides for direct conguration of the Jetty

MBeanContainer. Jetty creates MBean names dynamically. If you are running

another instance of Jetty outside of the Camel context and sharing the same

MBeanServer between the instances, you can provide both instances with a

reference to the same MBeanContainer in order to avoid name collisions

when registering Jetty MBeans.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ HTTP

JING COMPONENT

The Jing component uses the Jing Library to perform XML validation of the

message body using either

• RelaxNG XML Syntax

• RelaxNG Compact Syntax

Maven users will need to add the following dependency to their pom.xml for

this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-jing</artifactId>

</dependency>

Note that the MSV component can also support RelaxNG XML syntax.

URI format

rng:someLocalOrRemoteResource

rnc:someLocalOrRemoteResource

Where rng means use the RelaxNG XML Syntax whereas rnc means use

RelaxNG Compact Syntax. The following examples show possible URI values

745 CHAPTER 11 - COMPONENT APPENDIX

Example Description

rng:foo/bar.rng References the XML le foo/bar.rng on the classpath

rnc:

http://foo.com/

bar.rnc

References the RelaxNG Compact Syntax le from the

URL, http://foo.com/bar.rnc

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Option Default Description

useDom false

Camel 2.0: Species whether DOMSource/DOMResult

or SaxSource/SaxResult should be used by the

validator.

Example

The following example shows how to congure a route from the endpoint

direct:start which then goes to one of two endpoints, either mock:valid or

mock:invalid based on whether or not the XML matches the given RelaxNG

Compact Syntax schema (which is supplied on the classpath).

<route>

<doTry>

<exception>org.apache.camel.ValidationException</exception>

</doCatch>

</doFinally>

</doTry>

</route>

</camelContext>

See Also

• Conguring Camel

CHAPTER 11 - COMPONENT APPENDIX 746

• Component

• Endpoint

• Getting Started

JMS COMPONENT

The JMS component allows messages to be sent to (or consumed from) a JMS

Queue or Topic. The implementation of the JMS Component uses Spring's JMS

support for declarative transactions, using Spring's JmsTemplate for sending

and a MessageListenerContainer for consuming.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-jms</artifactId>

</dependency>

URI format

jms:[queue:|topic:]destinationName[?options]

Where destinationName is a JMS queue or topic name. By default, the

destinationName is interpreted as a queue name. For example, to connect

to the queue, FOO.BAR use:

jms:FOO.BAR

You can include the optional queue: prex, if you prefer:

jms:queue:FOO.BAR

To connect to a topic, you must include the topic: prex. For example, to

connect to the topic, Stocks.Prices, use:

jms:topic:Stocks.Prices

You append query options to the URI using the following format,

?option=value&option=value&...

747 CHAPTER 11 - COMPONENT APPENDIX

Using ActiveMQ

If you are using Apache ActiveMQ, you should prefer the ActiveMQ

component as it has been optimized for ActiveMQ. All of the options

and samples on this page are also valid for the ActiveMQ

component.

Transacted and caching

See section Transactions and Cache Levels below if you are using

transactions with JMS as it can impact performance.

Notes

Using ActiveMQ

The JMS component reuses Spring 2's JmsTemplate for sending messages.

This is not ideal for use in a non-J2EE container and typically requires some

caching in the JMS provider to avoid poor performance.

If you intend to use Apache ActiveMQ as your Message Broker - which is a

good choice as ActiveMQ rocks , then we recommend that you either:

• Use the ActiveMQ component, which is already optimized to use

ActiveMQ eciently

• Use the PoolingConnectionFactory in ActiveMQ.

Transactions and Cache Levels

If you are consuming messages and using transactions (transacted=true)

then the default settings for cache level can impact performance.

If you are using XA transactions then you cannot cache as it can cause the

XA transaction not to work properly.

If you are not using XA, then you should consider caching as it speedup

performance, such as setting cacheLevelName=CACHE_CONSUMER.

Through Camel 2.7.x, the default setting for cacheLevelName is

CACHE_CONSUMER. You will need to explicitly set

cacheLevelName=CACHE_NONE.

In Camel 2.8 onwards, the default setting for cacheLevelName is CACHE_AUTO.

This default auto detects the mode and sets the cache level accordingly to:

CHAPTER 11 - COMPONENT APPENDIX 748

▪ CACHE_CONSUMER = if transacted=false

▪ CACHE_NONE = if transacted=true

So you can say the default setting is conservative. Consider using

cacheLevelName=CACHE_CONSUMER if you are using non-XA transactions.

Durable Subscriptions

If you wish to use durable topic subscriptions, you need to specify both

clientId and durableSubscriptionName. The value of the clientId must

be unique and can only be used by a single JMS connection instance in your

entire network. You may prefer to use Virtual Topics instead to avoid this

limitation. More background on durable messaging here.

Message Header Mapping

When using message headers, the JMS specication states that header

names must be valid Java identiers. So, by default, Camel ignores any

headers that do not match this rule. So try to name your headers as if they

are valid Java identiers. One benet of doing this is that you can then use

your headers inside a JMS Selector (whose SQL92 syntax mandates Java

identier syntax for headers).

From Camel 1.4 onwards, a simple strategy for mapping header names is

used by default. The strategy is to replace any dots in the header name with

the underscore character and to reverse the replacement when the header

name is restored from a JMS message sent over the wire. What does this

mean? No more losing method names to invoke on a bean component, no

more losing the lename header for the File Component, and so on.

The current header name strategy for accepting header names in Camel is

as follows:

▪ Replace all dots with underscores (for example,

org.apache.camel.MethodName becomes

org_apache_camel_MethodName).

▪ Test if the name is a valid java identier using the JDK core classes.

▪ If the test success, the header is added and sent over the wire;

otherwise it is dropped (and logged at DEBUG level).

In Camel 2.0 this strategy has been change a bit to use the following

replacement strategy:

▪ Dots are replaced by _DOT_ and the replacement is reversed when

Camel consume the message

▪ Hyphen is replaced by _HYPHEN_ and the replacement is reversed

when Camel consumes the message

749 CHAPTER 11 - COMPONENT APPENDIX

Options

You can congure many dierent properties on the JMS endpoint which map

to properties on the JMSConguration POJO.

The options are divided into two tables, the rst one with the most common

options used. The latter contains the rest.

Most commonly used options

Option Default

Value Description

clientId null

Sets the JMS client ID to use. Note that this value, if specied, must be unique and can only be

used by a single JMS connection instance. It is typically only required for durable topic

subscriptions. You may prefer to use Virtual Topics instead.

concurrentConsumers 1 Species the default number of concurrent consumers.

disableReplyTo false

If true, a producer will behave like a InOnly exchange with the exception that JMSReplyTo header

is sent out and not be suppressed like in the case of InOnly. Like InOnly the producer will not

wait for a reply. A consumer with this ag will behave like InOnly. This feature can be used to

bridge InOut requests to another queue so that a route on the other queue will send it´s

response directly back to the original JMSReplyTo.

durableSubscriptionName null The durable subscriber name for specifying durable topic subscriptions. The clientId option

must be congured as well.

maxConcurrentConsumers 1 Species the maximum number of concurrent consumers.

preserveMessageQos false

Camel 2.0: Set to true, if you want to send message using the QoS settings specied on the

message, instead of the QoS settings on the JMS endpoint. The following three headers are

considered JMSPriority,JMSDeliveryMode, and JMSExpiration. You can provide all or only

some of them. If not provided, Camel will fall back to use the values from the endpoint instead.

So, when using this option, the headers override the values from the endpoint. The

explicitQosEnabled option, by contrast, will only use options set on the endpoint, and not

values from the message header.

replyTo null

Provides an explicit ReplyTo destination, which overrides any incoming value of

Message.getJMSReplyTo(). If you do Request Reply over JMS then read the section further below

for more details.

replyToType null

Camel 2.9: Allows to explicit specify which kind of strategy to use for replyTo queues when doing

request/reply over JMS. Possible values are: Temporary,Shared, or Exclusive. By default Camel

will use temporary queues. However if replyTo has been congured, then Shared is used by

default. This option allows you to use exclusive instead of shared queues. See further below for

more details, and especially the notes about the implications if running in a clustered

environment.

requestTimeout 20000 Producer only: The timeout for waiting for a reply when using the InOut Exchange Pattern (in

milliseconds). The default is 20 seconds. See below in section About time to live for more details.

selector null

Sets the JMS Selector, which is an SQL 92 predicate that is used to lter messages within the

broker. You may have to encode special characters such as = as %3D Before Camel 2.3.0, we

don't support this option in CamelConsumerTemplate

timeToLive null When sending messages, species the time-to-live of the message (in milliseconds). See below in

section About time to live for more details.

transacted false Species whether to use transacted mode for sending/receiving messages using the InOnly

Exchange Pattern.

testConnectionOnStartup false

Camel 2.1: Species whether to test the connection on startup. This ensures that when Camel

starts that all the JMS consumers have a valid connection to the JMS broker. If a connection

cannot be granted then Camel throws an exception on startup. This ensure that Camel is not

started with failed connections. From Camel 2.8 onwards also the JMS producers is tested as

well.

All the other options

Option Default Value Description

autoStartup true Species whether the consumer container should auto-startup.

CHAPTER 11 - COMPONENT APPENDIX 750

Mapping to Spring JMS

Many of these properties map to properties on Spring JMS, which

Camel uses for sending and receiving messages. So you can get

more information about these properties by consulting the relevant

Spring documentation.

acceptMessagesWhileStopping false Species whether the consumer accept messages while it is stopping.

acknowledgementModeName AUTO_ACKNOWLEDGE The JMS acknowledgement name, which is one of: TRANSACTED,

CLIENT_ACKNOWLEDGE,AUTO_ACKNOWLEDGE,DUPS_OK_ACKNOWLEDGE

acknowledgementMode -1

The JMS acknowledgement mode dened as an Integer. Allows you to set

vendor-specic extensions to the acknowledgment mode. For the regular

modes, it is preferable to use the acknowledgementModeName instead.

alwaysCopyMessage false

If true, Camel will always make a JMS message copy of the message when it

is passed to the producer for sending. Copying the message is needed in

some situations, such as when a replyToDestinationSelectorName is set

(incidentally, Camel will set the alwaysCopyMessage option to true, if a

replyToDestinationSelectorName is set)

asyncConsumer false

Camel 2.9: Whether the JmsConsumer processes the Exchange

asynchronously. If enabled then the JmsConsumer may pickup the next

message from the JMS queue, while the previous message is being

processed asynchronously (by the Asynchronous Routing Engine). This

means that messages may be processed not 100% strictly in order. If

disabled (as default) then the Exchange is fully processed before the

JmsConsumer will pickup the next message from the JMS queue. Note if

transacted has been enabled, then asyncConsumer=true does not run

asynchronously, as transactions must be executed synchronously (Camel 3.0

may support async transactions).

cacheLevelName ▪

Sets the cache level by name for the underlying JMS resources. Possible

values are: CACHE_AUTO,CACHE_CONNECTION,CACHE_CONSUMER,CACHE_NONE,

and CACHE_SESSION. The default setting for Camel 2.8 and newer is

CACHE_AUTO. For Camel 2.7.1 and older the default is CACHE_CONSUMER. See

the Spring documentation and Transactions Cache Levels for more

information.

cacheLevel ▪Sets the cache level by ID for the underlying JMS resources. See

cacheLevelName option for more details.

consumerType Default

The consumer type to use, which can be one of: Simple or Default. The

consumer type determines which Spring JMS listener to use. Default will use

org.springframework.jms.listener.DefaultMessageListenerContainer,

Simple will use

org.springframework.jms.listener.SimpleMessageListenerContainer.

This option was temporary removed in Camel 2.7 and 2.8. But has been

added back from Camel 2.9 onwards.

connectionFactory null

The default JMS connection factory to use for the

listenerConnectionFactory and templateConnectionFactory, if neither

is specied.

deliveryPersistent true Species whether persistent delivery is used by default.

destination null Camel 2.0: Species the JMS Destination object to use on this endpoint.

destinationName null Camel 2.0: Species the JMS destination name to use on this endpoint.

destinationResolver null

A pluggable

org.springframework.jms.support.destination.DestinationResolver

that allows you to use your own resolver (for example, to lookup the real

destination in a JNDI registry).

disableTimeToLive false

Camel 2.8: Use this option to force disabling time to live. For example when

you do request/reply over JMS, then Camel will by default use the

requestTimeout value as time to live on the message being send. The

problem is that the sender and receiver systems have to have their clocks

synchronized, so they are in sync. This is not always so easy to archive. So

you can use disableTimeToLive=true to not set a time to live value on the

send message. Then the message will not expire on the receiver system. See

below in section About time to live for more details.

751 CHAPTER 11 - COMPONENT APPENDIX

eagerLoadingOfProperties false

Enables eager loading of JMS properties as soon as a message is received,

which is generally inecient, because the JMS properties might not be

required. But this feature can sometimes catch early any issues with the

underlying JMS provider and the use of JMS properties. This feature can also

be used for testing purposes, to ensure JMS properties can be understood

and handled correctly.

exceptionListener null Species the JMS Exception Listener that is to be notied of any underlying

JMS exceptions.

errorHandler null

Camel 2.8.2, 2.9: Species a org.springframework.util.ErrorHandler

to be invoked in case of any uncaught exceptions thrown while processing a

Message. By default these exceptions will be logged at the ERROR level.

explicitQosEnabled false

Set if the deliveryMode,priority or timeToLive qualities of service should

be used when sending messages. This option is based on Spring's

JmsTemplate. The deliveryMode,priority and timeToLive options are

applied to the current endpoint. This contrasts with the preserveMessageQos

option, which operates at message granularity, reading QoS properties

exclusively from the Camel In message headers.

exposeListenerSession true Species whether the listener session should be exposed when consuming

messages.

forceSendOriginalMessage false

Camel 2.7: When using mapJmsMessage=false Camel will create a new JMS

message to send to a new JMS destination if you touch the headers (get or

set) during the route. Set this option to true to force Camel to send the

original JMS message that was received.

idleTaskExecutionLimit 1

Species the limit for idle executions of a receive task, not having received

any message within its execution. If this limit is reached, the task will shut

down and leave receiving to other executing tasks (in the case of dynamic

scheduling; see the maxConcurrentConsumers setting).

idleConsumerLimit 1 Camel 2.8.2, 2.9: Specify the limit for the number of consumers that are

allowed to be idle at any given time.

jmsMessageType null

Camel 2.0: Allows you to force the use of a specic javax.jms.Message

implementation for sending JMS messages. Possible values are: Bytes,Map,

Object,Stream,Text. By default, Camel would determine which JMS

message type to use from the In body type. This option allows you to specify

it.

jmsKeyFormatStrategy default

Camel 2.0: Pluggable strategy for encoding and decoding JMS keys so they

can be compliant with the JMS specication. Camel provides two

implementations out of the box: default and passthrough. The default

strategy will safely marshal dots and hyphens (.and -). The passthrough

strategy leaves the key as is. Can be used for JMS brokers which do not care

whether JMS header keys contain illegal characters. You can provide your

own implementation of the

org.apache.camel.component.jms.JmsKeyFormatStrategy and refer to it

using the #notation.

jmsOperations null

Allows you to use your own implementation of the

org.springframework.jms.core.JmsOperations interface. Camel uses

JmsTemplate as default. Can be used for testing purpose, but not used much

as stated in the spring API docs.

lazyCreateTransactionManager true Camel 2.0: If true, Camel will create a JmsTransactionManager, if there is

no transactionManager injected when option transacted=true.

listenerConnectionFactory null The JMS connection factory used for consuming messages.

mapJmsMessage true

Camel 1.6.2/2.0: Species whether Camel should auto map the received

JMS message to an appropiate payload type, such as

javax.jms.TextMessage to a String etc. See section about how mapping

works below for more details.

maxMessagesPerTask -1 The number of messages per task. -1 is unlimited.

maximumBrowseSize -1 Limits the number of messages fetched at most, when browsing endpoints

using Browse or JMX API.

messageConverter null

Camel 1.6.2/2.0: To use a custom Spring

org.springframework.jms.support.converter.MessageConverter so you

can be 100% in control how to map to/from a javax.jms.Message.

messageIdEnabled true When sending, species whether message IDs should be added.

messageTimestampEnabled true Species whether timestamps should be enabled by default on sending

messages.

password null The password for the connector factory.

priority 4

Values greater than 1 specify the message priority when sending (where 0 is

the lowest priority and 9 is the highest). The explicitQosEnabled option

must also be enabled in order for this option to have any eect.

pubSubNoLocal false Species whether to inhibit the delivery of messages published by its own

connection.

CHAPTER 11 - COMPONENT APPENDIX 752

receiveTimeout None The timeout for receiving messages (in milliseconds).

recoveryInterval 5000 Species the interval between recovery attempts, i.e. when a connection is

being refreshed, in milliseconds. The default is 5000 ms, that is, 5 seconds.

replyToDestinationSelectorName null

Sets the JMS Selector using the xed name to be used so you can lter out

your own replies from the others when using a shared queue (that is, if you

are not using a temporary reply queue).

replyToDeliveryPersistent true Species whether to use persistent delivery by default for replies.

subscriptionDurable false @deprecated: Enabled by default, if you specify a durableSubscriberName

and a clientId.

taskExecutor null Allows you to specify a custom task executor for consuming messages.

taskExecutorSpring2 null Camel 2.6: To use when using Spring 2.x with Camel. Allows you to specify

a custom task executor for consuming messages.

templateConnectionFactory null The JMS connection factory used for sending messages.

transactedInOut false

@deprecated: Species whether to use transacted mode for sending

messages using the InOut Exchange Pattern. Applies only to producer

endpoints. See section Enabling Transacted Consumption for more details.

transactionManager null The Spring transaction manager to use.

transactionName "JmsConsumer[destinationName]" The name of the transaction to use.

transactionTimeout null The timeout value of the transaction, if using transacted mode.

transferException false

Camel 2.0: If enabled and you are using Request Reply messaging (InOut)

and an Exchange failed on the consumer side, then the caused Exception

will be send back in response as a javax.jms.ObjectMessage. If the client is

Camel, the returned Exception is rethrown. This allows you to use Camel

JMS as a bridge in your routing - for example, using persistent queues to

enable robust routing. Notice that if you also have transferExchange

enabled, this option takes precedence. The caught exception is required to

be serializable. The original Exception on the consumer side can be

wrapped in an outer exception such as

org.apache.camel.RuntimeCamelException when returned to the producer.

transferExchange false

Camel 2.0: You can transfer the exchange over the wire instead of just the

body and headers. The following elds are transferred: In body, Out body,

Fault body, In headers, Out headers, Fault headers, exchange properties,

exchange exception. This requires that the objects are serializable. Camel

will exclude any non-serializable objects and log it at WARN level.

username null The username for the connector factory.

useMessageIDAsCorrelationID false Species whether JMSMessageID should always be used as

JMSCorrelationID for InOut messages.

useVersion102 false @deprecated (removed from Camel 2.5 onwards): Species whether

the old JMS API should be used.

Message Mapping between JMS and Camel

Camel automatically maps messages between javax.jms.Message and

org.apache.camel.Message.

When sending a JMS message, Camel converts the message body to the

following JMS message types:

Body Type JMS Message Comment

String javax.jms.TextMessage

org.w3c.dom.Node javax.jms.TextMessage The DOM will be converted to String.

Map javax.jms.MapMessage

java.io.Serializable javax.jms.ObjectMessage

byte[] javax.jms.BytesMessage

java.io.File javax.jms.BytesMessage

java.io.Reader javax.jms.BytesMessage

java.io.InputStream javax.jms.BytesMessage

java.nio.ByteBuffer javax.jms.BytesMessage

753 CHAPTER 11 - COMPONENT APPENDIX

When receiving a JMS message, Camel converts the JMS message to the

following body type:

JMS Message Body Type

javax.jms.TextMessage String

javax.jms.BytesMessage byte[]

javax.jms.MapMessage Map<String, Object>

javax.jms.ObjectMessage Object

Disabling auto-mapping of JMS messages

Available as of Camel 1.6.2/2.0

You can use the mapJmsMessage option to disable the auto-mapping above.

If disabled, Camel will not try to map the received JMS message, but instead

uses it directly as the payload. This allows you to avoid the overhead of

mapping and let Camel just pass through the JMS message. For instance, it

even allows you to route javax.jms.ObjectMessage JMS messages with

classes you do not have on the classpath.

Using a custom MessageConverter

Available as of Camel 1.6.2/2.0

You can use the messageConverter option to do the mapping yourself in a

Spring org.springframework.jms.support.converter.MessageConverter

class.

For example, in the route below we use a custom message converter when

sending a message to the JMS order queue:

from("file://inbox/

order").to("jms:queue:order?messageConverter=#myMessageConverter");

You can also use a custom message converter when consuming from a JMS

destination.

Controlling the mapping strategy selected

Available as of Camel 2.0

You can use the jmsMessageType option on the endpoint URL to force a

specic message type for all messages.

In the route below, we poll les from a folder and send them as

javax.jms.TextMessage as we have forced the JMS producer endpoint to

use text messages:

CHAPTER 11 - COMPONENT APPENDIX 754

from("file://inbox/order").to("jms:queue:order?jmsMessageType=Text");

You can also specify the message type to use for each messabe by setting

the header with the key CamelJmsMessageType. For example:

from("file://inbox/order").setHeader("CamelJmsMessageType",

JmsMessageType.Text).to("jms:queue:order");

The possible values are dened in the enum class,

org.apache.camel.jms.JmsMessageType.

Message format when sending

The exchange that is sent over the JMS wire must conform to the JMS

Message spec.

For the exchange.in.header the following rules apply for the header

keys:

▪ Keys starting with JMS or JMSX are reserved.

▪exchange.in.headers keys must be literals and all be valid Java

identiers (do not use dots in the key name).

▪ From Camel 1.4 until Camel 1.6.x, Camel automatically replaces all

dots with underscores in key names. This replacement is reversed

when Camel consumes JMS messages.

▪ From Camel 2.0 onwards, Camel replaces dots & hyphens and the

reverse when when consuming JMS messages:

.is replaced by _DOT_ and the reverse replacement when Camel

consumes the message.

-is replaced by _HYPHEN_ and the reverse replacement when Camel

consumes the message.

▪ See also the option jmsKeyFormatStrategy introduced in Camel

2.0, which allows you to use your own custom strategy for formatting

keys.

For the exchange.in.header, the following rules apply for the header

values:

▪ The values must be primitives or their counter objects (such as

Integer,Long,Character). The types, String,CharSequence,Date,

BigDecimal and BigInteger are all converted to their toString()

representation. All other types are dropped.

Camel will log with category

org.apache.camel.component.jms.JmsBinding at DEBUG level if it drops a

given header value. For example:

755 CHAPTER 11 - COMPONENT APPENDIX

2008-07-09 06:43:04,046 [main ] DEBUG JmsBinding

- Ignoring non primitive header: order of class:

org.apache.camel.component.jms.issues.DummyOrder with value: DummyOrder{orderId=333,

itemId=4444, quantity=2}

Message format when receiving

Camel adds the following properties to the Exchange when it receives a

message:

Property Type Description

org.apache.camel.jms.replyDestination javax.jms.Destination The reply destination.

Camel adds the following JMS properties to the In message headers when it

receives a JMS message:

Header Type Description

JMSCorrelationID String The JMS correlation ID.

JMSDeliveryMode int The JMS delivery mode.

JMSDestination javax.jms.Destination The JMS destination.

JMSExpiration long The JMS expiration.

JMSMessageID String The JMS unique message ID.

JMSPriority int The JMS priority (with 0 as the lowest priority and 9 as the highest).

JMSRedelivered boolean Is the JMS message redelivered.

JMSReplyTo javax.jms.Destination The JMS reply-to destination.

JMSTimestamp long The JMS timestamp.

JMSType String The JMS type.

JMSXGroupID String The JMS group ID.

As all the above information is standard JMS you can check the JMS

documentation for further details.

About using Camel to send and receive messages and JMSReplyTo

The JMS component is complex and you have to pay close attention to how it

works in some cases. So this is a short summary of some of the areas/pitfalls

to look for.

When Camel sends a message using its JMSProducer, it checks the

following conditions:

▪ The message exchange pattern,

▪ Whether a JMSReplyTo was set in the endpoint or in the message

headers,

▪ Whether any of the following options have been set on the JMS

endpoint: disableReplyTo,preserveMessageQos,

explicitQosEnabled.

All this can be a tad complex to understand and congure to support your

use case.

CHAPTER 11 - COMPONENT APPENDIX 756

JmsProducer

The JmsProducer behaves as follows, depending on conguration:

Exchange

Pattern

Other

options Description

InOut -Camel will expect a reply, set a temporary JMSReplyTo, and after sending the message, it will start to

listen for the reply message on the temporary queue.

InOut JMSReplyTo is

set

Camel will expect a reply and, after sending the message, it will start to listen for the reply message on the

specied JMSReplyTo queue.

InOnly - Camel will send the message and not expect a reply.

InOnly JMSReplyTo is

set

By default, Camel discards the JMSReplyTo destination and clears the JMSReplyTo header before sending

the message. Camel then sends the message and does not expect a reply. Camel logs this in the log at

WARN level (changed to DEBUG level from Camel 2.6 onwards. You can use preserveMessageQuo=true to

instruct Camel to keep the JMSReplyTo. In all situations the JmsProducer does not expect any reply and

thus continue after sending the message.

JmsConsumer

The JmsConsumer behaves as follows, depending on conguration:

Exchange Pattern Other options Description

InOut - Camel will send the reply back to the JMSReplyTo queue.

InOnly - Camel will not send a reply back, as the pattern is InOnly.

-disableReplyTo=true This option suppresses replies.

So pay attention to the message exchange pattern set on your exchanges.

If you send a message to a JMS destination in the middle of your route you

can specify the exchange pattern to use, see more at Request Reply.

This is useful if you want to send an InOnly message to a JMS topic:

from("activemq:queue:in")

.to("bean:validateOrder")

.to(ExchangePattern.InOnly, "activemq:topic:order")

.to("bean:handleOrder");

Reuse endpoint and send to dierent destinations computed at

runtime

Available as of Camel 1.6.2/2.0

If you need to send messages to a lot of dierent JMS destinations, it makes

sense to reuse a JMS endpoint and specify the real destination in a message

header. This allows Camel to reuse the same endpoint, but send to dierent

destinations. This greatly reduces the number of endpoints created and

economizes on memory and thread resources.

You can specify the destination in the following headers:

Header Type Description

CamelJmsDestination javax.jms.Destination Camel 2.0: A destination object.

CamelJmsDestinationName String Camel 1.6.2/2.0: The destination name.

757 CHAPTER 11 - COMPONENT APPENDIX

For example, the following route shows how you can compute a destination

at run time and use it to override the destination appearing in the JMS URL:

from("file://inbox")

.to("bean:computeDestination")

.to("activemq:queue:dummy");

The queue name, dummy, is just a placeholder. It must be provided as part of

the JMS endpoint URL, but it will be ignored in this example.

In the computeDestination bean, specify the real destination by setting

the CamelJmsDestinationName header as follows:

public void setJmsHeader(Exchange exchange) {

String id = ....

exchange.getIn().setHeader("CamelJmsDestinationName","order:" + id");

}

Then Camel will read this header and use it as the destination instead of the

one congured on the endpoint. So, in this example Camel sends the

message to activemq:queue:order:2, assuming the id value was 2.

If both the CamelJmsDestination and the CamelJmsDestinationName

headers are set, CamelJmsDestination takes priority.

Conguring dierent JMS providers

You can congure your JMS provider in Spring XML as follows:

</camelContext>

<property name="brokerURL"

value="vm://localhost?broker.persistent=false&broker.useJmx=false"/>

</bean>

</property>

</bean>

Basically, you can congure as many JMS component instances as you wish

and give them a unique name using the id attribute. The preceding

example congures an activemq component. You could do the same to

congure MQSeries, TibCo, BEA, Sonic and so on.

Once you have a named JMS component, you can then refer to endpoints

within that component using URIs. For example for the component name,

CHAPTER 11 - COMPONENT APPENDIX 758

activemq, you can then refer to destinations using the URI format,

activemq:[queue:|topic:]destinationName. You can use the same

approach for all other JMS providers.

This works by the SpringCamelContext lazily fetching components from

the spring context for the scheme name you use for Endpoint URIs and

having the Component resolve the endpoint URIs.

Using JNDI to nd the ConnectionFactory

If you are using a J2EE container, you might need to look up JNDI to nd the

JMS ConnectionFactory rather than use the usual <bean> mechanism in

Spring. You can do this using Spring's factory bean or the new Spring XML

namespace. For example:

</bean>

<jee:jndi-lookup id="myConnectionFactory" jndi-name="jms/connectionFactory"/>

See The jee schema in the Spring reference documentation for more details

about JNDI lookup.

Concurrent Consuming

A common requirement with JMS is to consume messages concurrently in

multiple threads in order to make an application more responsive. You can

set the concurrentConsumers option to specify the number of threads

servicing the JMS endpoint, as follows:

from("jms:SomeQueue?concurrentConsumers=20").

bean(MyClass.class);

You can congure this option in one of the following ways:

• On the JmsComponent,

• On the endpoint URI or,

• By invoking setConcurrentConsumers() directly on the

JmsEndpoint.

Request-reply over JMS

Camel supports Request Reply over JMS. In essence the MEP of the Exchange

should be InOut when you send a message to a JMS queue.

The JmsProducer detects the InOut and provides a JMSReplyTo header with

759 CHAPTER 11 - COMPONENT APPENDIX

the reply destination to be used. By default Camel uses a temporary queue,

but you can use the replyTo option on the endpoint to specify a xed reply

queue (see more below about xed reply queue).

Camel will automatic setup a consumer which listen on the reply queue, so

you should not do anything.

This consumer is a Spring DefaultMessageListenerContainer which listen

for replies. However it's xed to 1 concurrent consumer.

That means replies will be processed in sequence as there are only 1 thread

to process the replies. If you want to process replies faster, then we need to

use concurrency. But not using the concurrentConsumer option. We should

use the threads from the Camel DSL instead, as shown in the route below:

from(xxx)

.inOut().to("activemq:queue:foo")

.threads(5)

.to(yyy)

.to(zzz);

In this route we instruct Camel to route replies asynchronously using a thread

pool with 5 threads.

Request-reply over JMS and using a shared xed reply

queue

If you use a xed reply queue when doing Request Reply over JMS as shown

in the example below, then pay attention.

from(xxx)

.inOut().to("activemq:queue:foo?replyTo=bar")

.to(yyy)

In this example the xed reply queue named "bar" is used. By default Camel

assumes the queue is shared when using xed reply queues, and therefore it

uses a JMSSelector to only pickup the expected reply messages (eg based

on the JMSCorrelationID). See next section for exclusive xed reply queues.

That means its not as fast as temporary queues. You can speedup how often

Camel will pull for reply messages using the receiveTimeout option. By

default its 1000 millis. So to make it faster you can set it to 250 millis to pull

4 times per second as shown:

from(xxx)

.inOut().to("activemq:queue:foo?replyTo=bar&receiveTimeout=250")

.to(yyy)

CHAPTER 11 - COMPONENT APPENDIX 760

Notice this will cause the Camel to send pull requests to the message broker

more frequent, and thus require more network trac.

It is generally recommended to use temporary queues if possible.

Request-reply over JMS and using an exclusive xed

reply queue

Available as of Camel 2.9

In the previous example, Camel would anticipate the xed reply queue

named "bar" was shared, and thus it uses a JMSSelector to only consume

reply messages which it expects. However there is a drawback doing this as

JMS selectos is slower. Also the consumer on the reply queue is slower to

update with new JMS selector ids. In fact it only updates when the

receiveTimeout option times out, which by default is 1 second. So in theory

the reply messages could take up till about 1 sec to be detected. On the

other hand if the xed reply queue is exclusive to the Camel reply consumer,

then we can avoid using the JMS selectors, and thus be more performant. In

fact as fast as using temporary queues. So in Camel 2.9 onwards we

introduced the ReplyToType option which you can congure to Exclusive

to tell Camel that the reply queue is exclusive as shown in the example

below:

from(xxx)

.inOut().to("activemq:queue:foo?replyTo=bar?replyToType=Exclusive")

.to(yyy)

Mind that the queue must be exclusive to each and every endpoint. So if you

have two routes, then they each need an unique reply queue as shown in the

next example:

from(xxx)

.inOut().to("activemq:queue:foo?replyTo=bar?replyToType=Exclusive")

.to(yyy)

from(aaa)

.inOut().to("activemq:queue:order?replyTo=order.reply?replyToType=Exclusive")

.to(bbb)

The same applies if you run in a clustered environment. Then each node in

the cluster must use an unique reply queue name. As otherwise each node in

the cluster may pickup messages which was intended as a reply on another

node. For clustered environments its recommended to use shared reply

queues instead.

761 CHAPTER 11 - COMPONENT APPENDIX

Synchronizing clocks between senders and receivers

When doing messaging between systems, its desirable that the systems

have synchronized clocks. For example when sending a JMS message, then

you can set a time to live value on the message. Then the receiver can

inspect this value, and determine if the message is already expired, and thus

drop the message instead of consume and process it. However this requires

that both sender and receiver have synchronized clocks. If you are using

ActiveMQ then you can use the timestamp plugin to synchronize clocks.

About time to live

Read rst above about synchronized clocks.

When you do request/reply (InOut) over JMS with Camel then Camel uses a

timeout on the sender side, which is default 20 seconds from the

requestTimeout option. You can control this by setting a higher/lower value.

However the time to live value is still set on the JMS message being send. So

that requires the clocks to be synchronized between the systems. If they are

not, then you may want to disable the time to live value being set. This is

now possible using the disableTimeToLive option from Camel 2.8 onwards.

So if you set this option to disableTimeToLive=true, then Camel does not

set any time to live value when sending JMS messages. But the request

timeout is still active. So for example if you do request/reply over JMS and

have disabled time to live, then Camel will still use a timeout by 20 seconds

(the requestTimeout option). That option can of course also be congured.

So the two options requestTimeout and disableTimeToLive gives you ne

grained control when doing request/reply.

When you do re and forget (InOut) over JMS with Camel then Camel by

default does not set any time to live value on the message. You can

congure a value by using the timeToLive option. For example to indicate a

5 sec., you set timeToLive=5000. The option disableTimeToLive can be

used to force disabling the time to live, also for InOnly messaging. The

requestTimeout option is not being used for InOnly messaging.

Enabling Transacted Consumption

A common requirement is to consume from a queue in a transaction and

then process the message using the Camel route. To do this, just ensure that

you set the following properties on the component/endpoint:

•transacted = true

•transactionManager = a Transsaction Manager - typically the

JmsTransactionManager

See the Transactional Client EIP pattern for further details.

CHAPTER 11 - COMPONENT APPENDIX 762

Transactions and Request Reply over JMS

When using Request Reply over JMS you cannot use a single

transaction; JMS will not send any messages until a commit is

performed, so the server side won't receive anything at all until the

transaction commits. Therefore to use Request Reply you must

commit a transaction after sending the request and then use a

separate transaction for receiving the response.

To address this issue the JMS component uses dierent properties to

specify transaction use for oneway messaging and request reply

messaging:

The transacted property applies only to the InOnly message Exchange

Pattern (MEP).

The transactedInOut property applies to the InOut(Request Reply)

message Exchange Pattern (MEP).

If you want to use transactions for Request Reply(InOut MEP), you must

set transactedInOut=true.

Using JMSReplyTo for late replies

Avaiable as of Camel 2.0

When using Camel as a JMS listener, it sets an Exchange property with the

value of the ReplyTo javax.jms.Destination object, having the key

ReplyTo. You can obtain this Destination as follows:

Destination replyDestination =

exchange.getIn().getHeader(JmsConstants.JMS_REPLY_DESTINATION, Destination.class);

And then later use it to send a reply using regular JMS or Camel.

// we need to pass in the JMS component, and in this sample we use ActiveMQ

JmsEndpoint endpoint = JmsEndpoint.newInstance(replyDestination,

activeMQComponent);

// now we have the endpoint we can use regular Camel API to send a message to it

template.sendBody(endpoint, "Here is the late reply.");

A dierent solution to sending a reply is to provide the replyDestination

object in the same Exchange property when sending. Camel will then pick up

this property and use it for the real destination. The endpoint URI must

include a dummy destination, however. For example:

763 CHAPTER 11 - COMPONENT APPENDIX

// we pretend to send it to some non existing dummy queue

template.send("activemq:queue:dummy, new Processor() {

public void process(Exchange exchange) throws Exception {

// and here we override the destination with the ReplyTo destination

object so the message is sent to there instead of dummy

exchange.getIn().setHeader(JmsConstants.JMS_DESTINATION,

replyDestination);

exchange.getIn().setBody("Here is the late reply.");

}

Using a request timeout

In the sample below we send a Request Reply style message Exchange (we

use the requestBody method = InOut) to the slow queue for further

processing in Camel and we wait for a return reply:

// send a in-out with a timeout for 5 sec

Object out = template.requestBody("activemq:queue:slow?requestTimeout=5000","Hello

World");

Samples

JMS is used in many examples for other components as well. But we provide

a few samples below to get started.

Receiving from JMS

In the following sample we congure a route that receives JMS messages and

routes the message to a POJO:

from("jms:queue:foo").

to("bean:myBusinessLogic");

You can of course use any of the EIP patterns so the route can be context

based. For example, here's how to lter an order topic for the big spenders:

from("jms:topic:OrdersTopic").

filter().method("myBean","isGoldCustomer").

to("jms:queue:BigSpendersQueue");

CHAPTER 11 - COMPONENT APPENDIX 764

Sending to a JMS

In the sample below we poll a le folder and send the le content to a JMS

topic. As we want the content of the le as a TextMessage instead of a

BytesMessage, we need to convert the body to a String:

from("file://orders").

convertBodyTo(String.class).

to("jms:topic:OrdersTopic");

Using Annotations

Camel also has annotations so you can use POJO Consuming and POJO

Producing.

Spring DSL sample

The preceding examples use the Java DSL. Camel also supports Spring XML

DSL. Here is the big spender sample using Spring DSL:

<route>

</filter>

</route>

Other samples

JMS appears in many of the examples for other components and EIP patterns,

as well in this Camel documentation. So feel free to browse the

documentation. If you have time, check out the this tutorial that uses JMS but

focuses on how well Spring Remoting and Camel works together Tutorial-

JmsRemoting.

Using JMS as a Dead Letter Queue storing Exchange

Available as of Camel 2.0

Normally, when using JMS as the transport, it only transfers the body and

headers as the payload. If you want to use JMS with a Dead Letter Channel,

using a JMS queue as the Dead Letter Queue, then normally the caused

765 CHAPTER 11 - COMPONENT APPENDIX

Exception is not stored in the JMS message. You can, however, use the

transferExchange option on the JMS dead letter queue to instruct Camel to

store the entire Exchange in the queue as a javax.jms.ObjectMessage that

holds a org.apache.camel.impl.DefaultExchangeHolder. This allows you

to consume from the Dead Letter Queue and retrieve the caused exception

from the Exchange property with the key Exchange.EXCEPTION_CAUGHT. The

demo below illustrates this:

// setup error handler to use JMS as queue and store the entire Exchange

errorHandler(deadLetterChannel("jms:queue:dead?transferExchange=true"));

Then you can consume from the JMS queue and analyze the problem:

from("jms:queue:dead").to("bean:myErrorAnalyzer");

// and in our bean

String body = exchange.getIn().getBody();

Exception cause = exchange.getProperty(Exchange.EXCEPTION_CAUGHT, Exception.class);

// the cause message is

String problem = cause.getMessage();

Using JMS as a Dead Letter Channel storing error only

You can use JMS to store the cause error message or to store a custom body,

which you can initialize yourself. The following example uses the Message

Translator EIP to do a transformation on the failed exchange before it is

moved to the JMS dead letter queue:

// we sent it to a seda dead queue first

errorHandler(deadLetterChannel("seda:dead"));

// and on the seda dead queue we can do the custom transformation before its sent to

the JMS queue

from("seda:dead").transform(exceptionMessage()).to("jms:queue:dead");

Here we only store the original cause error message in the transform. You

can, however, use any Expression to send whatever you like. For example,

you can invoke a method on a Bean or use a custom processor.

Sending an InOnly message and keeping the JMSReplyTo header

When sending to a JMS destination using camel-jms the producer will use

the MEP to detect if its InOnly or InOut messaging. However there can be

times where you want to send an InOnly message but keeping the

CHAPTER 11 - COMPONENT APPENDIX 766

JMSReplyTo header. To do so you have to instruct Camel to keep it, otherwise

the JMSReplyTo header will be dropped.

For example to send an InOnly message to the foo queue, but with a

JMSReplyTo with bar queue you can do as follows:

template.send("activemq:queue:foo?preserveMessageQos=true",new Processor() {

public void process(Exchange exchange) throws Exception {

exchange.getIn().setBody("World");

exchange.getIn().setHeader("JMSReplyTo","bar");

}

});

Notice we use preserveMessageQos=true to instruct Camel to keep the

JMSReplyTo header.

Setting JMS provider options on the destination

Some JMS providers, like IBM's WebSphere MQ need options to be set on the

JMS destination. For example, you may need to specify the targetClient

option. Since targetClient is a WebSphere MQ option and not a Camel URI

option, you need to set that on the JMS destination name like so:

...

.setHeader("CamelJmsDestinationName", constant("queue:///MY_QUEUE?targetClient=1"))

.to("wmq:queue:MY_QUEUE?useMessageIDAsCorrelationID=true");

Some versions of WMQ won't accept this option on the destination name and

you will get an exception like:

com.ibm.msg.client.jms.DetailedJMSException: JMSCC0005: The

specied value 'MY_QUEUE?targetClient=1' is not allowed for

'XMSC_DESTINATION_NAME'

A workaround is to use a custom DestinationResolver:

JmsComponent wmq = new JmsComponent(connectionFactory);

wmq.setDestinationResolver(new DestinationResolver(){

public Destination resolveDestinationName(Session session, String

destinationName, boolean pubSubDomain) throws JMSException {

MQQueueSession wmqSession = (MQQueueSession) session;

return wmqSession.createQueue("queue:///" + destinationName +

"?targetClient=1");

}

});

767 CHAPTER 11 - COMPONENT APPENDIX

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ Transactional Client

▪ Bean Integration

▪ Tutorial-JmsRemoting

▪ JMSTemplate gotchas

JMX COMPONENT

Available as of Camel 2.6

Standard JMX Consumer Conguration

Component allows consumers to subscribe to an mbean's Notications. The

component supports passing the Notication object directly through the

Exchange or serializing it to XML according to the schema provided within

this project. This is a consumer only component. Exceptions are thrown if you

attempt to create a producer for it.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-jmx</artifactId>

</dependency>

URI Format

The component can connect to the local platform mbean server with the

following URI:

jmx://platform?options

A remote mbean server url can be provided following the initial JMX scheme

like so:

CHAPTER 11 - COMPONENT APPENDIX 768

jmx:service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi?options

You can append query options to the URI in the following format,

?options=value&option2=value&...

URI Options

Property Required Default Description

format xml Format for the message body. Either "xml" or "raw". If xml, the notication is serialized to

xml. If raw, then the raw java object is set as the body.

user Credentials for making a remote connection.

password Credentials for making a remote connection.

objectDomain yes The domain for the mbean you're connecting to.

objectName The name key for the mbean you're connecting to. This value is mutually exclusive with

the object properties that get passed. (see below)

noticationFilter Reference to a bean that implements the NotificationFilter. The #ref syntax should

be used to reference the bean via the Registry.

handback Value to handback to the listener when a notication is received. This value will be put in

the message header with the key "jmx.handback"

ObjectName Construction

The URI must always have the objectDomain property. In addition, the URI

must contain either objectName or one or more properties that start with

"key."

Domain with Name property

When the objectName property is provided, the following constructor is used

to build the ObjectName? for the mbean:

ObjectName(String domain, String key, String value)

The key value in the above will be "name" and the value will be the value of

the objectName property.

Domain with Hashtable

ObjectName(String domain, Hashtable<String,String> table)

The Hashtable is constructed by extracting properties that start with "key."

The properties will have the "key." prexed stripped prior to building the

769 CHAPTER 11 - COMPONENT APPENDIX

Hashtable. This allows the URI to contain a variable number of properties to

identify the mbean.

Example

from("jmx:platform?objectDomain=jmxExample&key.name=simpleBean").

to("log:jmxEvent");

Full example

Monitor Type Consumer

Available as of Camel 2.8

One popular use case for JMX is creating a monitor bean to monitor an

attribute on a deployed bean. This requires writing a few lines of Java code to

create the JMX monitor and deploy it. As shown below:

CounterMonitor monitor = new CounterMonitor();

monitor.addObservedObject(makeObjectName("simpleBean"));

monitor.setObservedAttribute("MonitorNumber");

monitor.setNotify(true);

monitor.setInitThreshold(1);

monitor.setGranularityPeriod(500);

registerBean(monitor, makeObjectName("counter"));

monitor.start();

The 2.8 version introduces a new type of consumer that automatically

creates and registers a monitor bean for the specied objectName and

attribute. Additional endpoint attributes allow the user to specify the

attribute to monitor, type of monitor to create, and any other required

properties. The code snippet above is condensed into a set of endpoint

properties. The consumer uses these properties to create the

CounterMonitor, register it, and then subscribe to its changes. All of the JMX

monitor types are supported.

Example

from("jmx:platform?objectDomain=myDomain&objectName=simpleBean&" +

"monitorType=counter&observedAttribute=MonitorNumber&initThreshold=1&" +

"granularityPeriod=500").to("mock:sink");

The example above will cause a new Monitor Bean to be created and

depoyed to the local mbean server that monitors the "MonitorNumber"

CHAPTER 11 - COMPONENT APPENDIX 770

attribute on the "simpleBean." Additional types of monitor beans and options

are detailed below. The newly deployed monitor bean is automatically

undeployed when the consumer is stopped.

URI Options for Monitor Type

property type applies

to description

monitorType enum all one of counter, guage, string

observedAttribute string all the attribute being observed

granualityPeriod long all

granularity period (in millis) for

the attribute being observed. As

per JMX, default is 10 seconds

initThreshold number counter initial threshold value

oset number counter oset value

modulus number counter modulus value

dierenceMode boolean counter,

gauge

true if dierence should be

reported, false for actual value

notifyHigh boolean gauge high notication on/o switch

notifyLow boolean gauge low notication on/o switch

highThreshold number gauge threshold for reporting high

notication

lowThreshold number gauge threshold for reporting low

noticaton

notifyDier boolean string true to re notication when

string diers

notifyMatch boolean string true to re notication when

string matches

stringToCompare string string string to compare against the

attribute value

The monitor style consumer is only supported for the local mbean server. JMX

does not currently support remote deployment of mbeans without either

having the classes already remotely deployed or an adapter library on both

the client and server to facilitate a proxy deployment.

771 CHAPTER 11 - COMPONENT APPENDIX

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ Camel JMX

JPA COMPONENT

The jpa component enables you to store and retrieve Java objects from

persistent storage using EJB 3's Java Persistence Architecture (JPA), which is a

standard interface layer that wraps Object/Relational Mapping (ORM)

products such as OpenJPA, Hibernate, TopLink, and so on.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-jpa</artifactId>

</dependency>

Sending to the endpoint

You can store a Java entity bean in a database by sending it to a JPA producer

endpoint. The body of the In message is assumed to be an entity bean (that

is, a POJO with an @Entity annotation on it) or a collection or array of entity

beans.

If the body does not contain one of the previous listed types, put a

Message Translator in front of the endpoint to perform the necessary

conversion rst.

Consuming from the endpoint

Consuming messages from a JPA consumer endpoint removes (or updates)

entity beans in the database. This allows you to use a database table as a

logical queue: consumers take messages from the queue and then delete/

update them to logically remove them from the queue.

If you do not wish to delete the entity bean when it has been processed,

you can specify consumeDelete=false on the URI. This will result in the

entity being processed each poll.

CHAPTER 11 - COMPONENT APPENDIX 772

If you would rather perform some update on the entity to mark it as

processed (such as to exclude it from a future query) then you can annotate

a method with @Consumed which will be invoked on your entity bean when

the entity bean is consumed.

URI format

jpa:[entityClassName][?options]

For sending to the endpoint, the entityClassName is optional. If specied, it

helps the Type Converter to ensure the body is of the correct type.

For consuming, the entityClassName is mandatory.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Default

Value Description

entityType entityClassName Overrides the entityClassName from the URI.

persistenceUnit camel The JPA persistence unit used by default.

consumeDelete true JPA consumer only: If true, the entity is deleted after it is consumed; if false, the entity is

not deleted.

consumeLockEntity true JPA consumer only: Species whether or not to set an exclusive lock on each entity bean

while processing the results from polling.

flushOnSend true JPA producer only: Flushes the EntityManager after the entity bean has been persisted.

maximumResults -1 JPA consumer only: Set the maximum number of results to retrieve on the Query.

transactionManager null

Camel 1.6.1/2.0: Species the transaction manager to use. If none provided, Camel will use a

JpaTransactionManager by default. Can be used to set a JTA transaction manager (for

integration with an EJB container).

consumer.delay 500 JPA consumer only: Delay in milliseconds between each poll.

consumer.initialDelay 1000 JPA consumer only: Milliseconds before polling starts.

consumer.useFixedDelay false JPA consumer only: Set to true to use xed delay between polls, otherwise xed rate is used.

See ScheduledExecutorService in JDK for details.

maxMessagesPerPoll 0

Camel 2.0: JPA consumer only: An integer value to dene the maximum number of

messages to gather per poll. By default, no maximum is set. Can be used to avoid polling many

thousands of messages when starting up the server. Set a value of 0 or negative to disable.

consumer.query JPA consumer only: To use a custom query when consuming data.

consumer.namedQuery JPA consumer only: To use a named query when consuming data.

consumer.nativeQuery JPA consumer only: To use a custom native query when consuming data.

consumer.resultClass

Camel 2.7: JPA consumer only: Denes the type of the returned payload (we will call

entityManager.createNativeQuery(nativeQuery, resultClass) instead of

entityManager.createNativeQuery(nativeQuery)). Without this option, we will return an

object array. Only has an aect when using in conjunction with native query when consuming

data.

usePersist false

Camel 2.5: JPA producer only: Indicates to use entityManager.persist(entity) instead of

entityManager.merge(entity). Note: entityManager.persist(entity) doesn't work for

detached entities (where the EntityManager has to execute an UPDATE instead of an INSERT

query)!

773 CHAPTER 11 - COMPONENT APPENDIX

Message Headers

Camel adds the following message headers to the exchange:

Header Type Description

CamelJpaTemplate JpaTemplate Camel 2.0: The JpaTemplate object that is used to access the entity bean. You need this object in some

situations, for instance in a type converter or when you are doing some custom processing.

Conguring EntityManagerFactory

Its strongly advised to congure the JPA component to use a specic

EntityManagerFactory instance. If failed to do so each JpaEndpoint will

auto create their own instance of EntityManagerFactory which most often is

not what you want.

For example, you can instantiate a JPA component that references the

myEMFactory entity manager factory, as follows:

</bean>

In Camel 2.3 the JpaComponent will auto lookup the EntityManagerFactory

from the Registry which means you do not need to congure this on the

JpaComponent as shown above. You only need to do so if there is ambiguity,

in which case Camel will log a WARN.

Conguring TransactionManager

Its strongly advised to congure the TransactionManager instance used by

the JPA component. If failed to do so each JpaEndpoint will auto create their

own instance of TransactionManager which most often is not what you

want.

For example, you can instantiate a JPA component that references the

myTransactionManager transaction manager, as follows:

</bean>

In Camel 2.3 the JpaComponent will auto lookup the TransactionManager

from the Registry which means you do not need to congure this on the

JpaComponent as shown above. You only need to do so if there is ambiguity,

in which case Camel will log a WARN.

CHAPTER 11 - COMPONENT APPENDIX 774

Using a consumer with a named query

For consuming only selected entities, you can use the consumer.namedQuery

URI query option. First, you have to dene the named query in the JPA Entity

class:

@Entity

@NamedQuery(name = "step1", query = "select x from MultiSteps x where x.step = 1")

public class MultiSteps {

...

}

After that you can dene a consumer uri like this one:

from("jpa://org.apache.camel.examples.MultiSteps?consumer.namedQuery=step1")

.to("bean:myBusinessLogic");

Using a consumer with a query

For consuming only selected entities, you can use the consumer.query URI

query option. You only have to dene the query option:

from("jpa://org.apache.camel.examples.MultiSteps?consumer.query=select o from

org.apache.camel.examples.MultiSteps o where o.step = 1")

.to("bean:myBusinessLogic");

Using a consumer with a native query

For consuming only selected entities, you can use the

consumer.nativeQuery URI query option. You only have to dene the native

query option:

from("jpa://org.apache.camel.examples.MultiSteps?consumer.nativeQuery=select * from

MultiSteps where step = 1")

.to("bean:myBusinessLogic");

If you use the native query option, you will receive an object array in the

message body.

Example

See Tracer Example for an example using JPA to store traced messages into a

database.

775 CHAPTER 11 - COMPONENT APPENDIX

Using the JPA based idempotent repository

In this section we will use the JPA based idempotent repository.

First we need to setup a persistence-unit in the persistence.xml le:

<persistence-unit name="idempotentDb" transaction-type="RESOURCE_LOCAL">

<class>org.apache.camel.processor.idempotent.jpa.MessageProcessed</class>

<property name="openjpa.ConnectionURL" value="jdbc:derby:target/

idempotentTest;create=true"/>

<property name="openjpa.ConnectionDriverName"

value="org.apache.derby.jdbc.EmbeddedDriver"/>

</properties>

</persistence-unit>

Second we have to setup a org.springframework.orm.jpa.JpaTemplate

which is used by the

org.apache.camel.processor.idempotent.jpa.JpaMessageIdRepository:

</bean>

<bean id="entityManagerFactory"

class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean">

<!-- we use idempotentDB as the persitence unit name defined in the

persistence.xml file -->

</bean>

Afterwards we can congure our

org.apache.camel.processor.idempotent.jpa.JpaMessageIdRepository:

<!-- we define our jpa based idempotent repository we want to use in the file

consumer -->

<bean id="jpaStore"

class="org.apache.camel.processor.idempotent.jpa.JpaMessageIdRepository">

<constructor-arg index="0" ref="jpaTemplate"/>

<!-- This 2nd parameter is the name (= a cateogry name).

You can have different repositories with different names -->

<constructor-arg index="1" value="FileConsumer"/>

</bean>

And nally we can create our JPA idempotent repository in the spring XML le

as well:

CHAPTER 11 - COMPONENT APPENDIX 776

<camel:camelContext>

<camel:route id="JpaMessageIdRepositoryTest">

<camel:from uri="direct:start" />

<camel:idempotentConsumer messageIdRepositoryRef="jpaStore">

<camel:header>messageId</camel:header>

<camel:to uri="mock:result" />

</camel:idempotentConsumer>

</camel:route>

</camel:camelContext>

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ Tracer Example

JT/400 COMPONENT

The jt400 component allows you to exchanges messages with an AS/400

system using data queues.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-jt400</artifactId>

</dependency>

URI format

jt400://user:password@system/QSYS.LIB/LIBRARY.LIB/QUEUE.DTAQ[?options]

To call remote program (Camel 2.7)

jt400://user:password@system/QSYS.LIB/LIBRARY.LIB/program.PGM[?options]

You can append query options to the URI in the following format,

?option=value&option=value&...

777 CHAPTER 11 - COMPONENT APPENDIX

URI options

For the data queue message exchange:

Name Default

value Description

ccsid default system

CCSID Species the CCSID to use for the connection with the AS/400 system.

format text Species the data format for sending messages

valid options are: text (represented by String) and binary (represented by byte[])

consumer.delay 500 Delay in milliseconds between each poll.

consumer.initialDelay 1000 Milliseconds before polling starts.

consumer.userFixedDelay false true to use xed delay between polls, otherwise xed rate is used. See

ScheduledExecutorService in JDK for details.

guiAvailable false Camel 2.8: Species whether AS/400 prompting is enabled in the environment running

Camel.

For the remote program call (Camel 2.7)

Name Default value Description

outputFieldsIdx Species which elds (program parameters) are output parameters.

fieldsLength Species the elds (program parameters) length as in the AS/400 program denition.

Usage

When congured as a consumer endpoint, the endpoint will poll a data queue

on a remote system. For every entry on the data queue, a new Exchange is

sent with the entry's data in the In message's body, formatted either as a

String or a byte[], depending on the format. For a provider endpoint, the In

message body contents will be put on the data queue as either raw bytes or

text.

Remote program call (Camel 2.7)

This endpoint expects the input to be a String array and handles all the

CCSID handling trough the native jt400 library mechanisms. After the

program execution the endpoint returns a String array with the values as

they were returned by the program (the input only parameters will contain

the same data as the beginning of the invocation)

This endpoint does not implement a provider endpoint!

Example

In the snippet below, the data for an exchange sent to the direct:george

endpoint will be put in the data queue PENNYLANE in library BEATLES on a

system named LIVERPOOL.

Another user connects to the same data queue to receive the information

from the data queue and forward it to the mock:ringo endpoint.

CHAPTER 11 - COMPONENT APPENDIX 778

public class Jt400RouteBuilder extends RouteBuilder {

@Override

public void configure() throws Exception {

from("direct:george").to("jt400://GEORGE:EGROEG@LIVERPOOL/QSYS.LIB/BEATLES.LIB/

PENNYLANE.DTAQ");

from("jt400://RINGO:OGNIR@LIVERPOOL/QSYS.LIB/BEATLES.LIB/

PENNYLANE.DTAQ").to("mock:ringo");

}

Remote program call example (Camel 2.7)

In the snippet below, the data Exchange sent to the direct:work endpoint will

contain three string that will be used as the arguments for the program

“compute” in the library “assets”. This program will write the output values

in the 2nd and 3rd parameters. All the parameters will be sent to the

direct:play endpoint.

public class Jt400RouteBuilder extends RouteBuilder {

@Override

public void configure() throws Exception {

from("direct:work").to("jt400://GRUPO:ATWORK@server/QSYS.LIB/assets.LIB/

compute.PGM?fieldsLength=10,10,512&ouputFieldsIdx=2,3").to(“direct:play”);

}

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

LANGUAGE

Available as of Camel 2.5

The language component allows you to send Exchange to an endpoint

which executes a script by any of the supported Languages in Camel.

By having a component to execute language scripts, it allows more dynamic

routing capabilities. For example by using the Routing Slip or Dynamic Router

EIPs you can send messages to language endpoints where the script is

dynamic dened as well.

779 CHAPTER 11 - COMPONENT APPENDIX

This component is provided out of the box in camel-core and hence no

additional JARs is needed. You only have to include additional Camel

components if the language of choice mandates it, such as using Groovy or

JavaScript languages.

URI format

language://languageName[:script][?options]

URI Options

The component supports the following options.

Name Default

Value Type Description

languageName null String The name of the Language to use, such as simple,groovy,javascript etc. This option is

mandatory.

script null String The script to execute.

transform true boolean Whether or not the result of the script should be used as the new message body. By setting to

false the script is executed but the result of the script is discarded.

contentCache true boolean Camel 2.9: Whether to cache the script if loaded from a resource.

Message Headers

The following message headers can be used to aect the behavior of the

component

Header Description

CamelLanguageScript The script to execute provided in the header. Takes precedence over script congured on the endpoint.

Examples

For example you can use the Simple language to Message Translator a

message:

String script = URLEncoder.encode("Hello ${body}","UTF-8");

from("direct:start").to("language:simple:" + script).to("mock:result");

In case you want to convert the message body type you can do this as well:

String script = URLEncoder.encode("${mandatoryBodyAs(String)}","UTF-8");

from("direct:start").to("language:simple:" + script).to("mock:result");

You can also use the Groovy language, such as this example where the input

message will by multiplied with 2:

CHAPTER 11 - COMPONENT APPENDIX 780

String script = URLEncoder.encode("request.body * 2","UTF-8");

from("direct:start").to("language:groovy:" + script).to("mock:result");

You can also provide the script as a header as shown below. Here we use

XPath language to extract the text from the <foo> tag.

Object out = producer.requestBodyAndHeader("language:xpath","<foo>Hello

World</foo>", Exchange.LANGUAGE_SCRIPT, "/foo/text()");

assertEquals("Hello World", out);

Loading scripts from resources

Available as of Camel 2.9

You can specify a resource uri for a script to load in either the endpoint uri,

or in the Exchange.LANGUAGE_SCRIPT header.

The uri must start with one of the following schemes: le:, classpath:, or http:

For example to load a script from the classpath:

from("direct:start")

// load the script from the classpath

.to("language:simple:classpath:org/apache/camel/component/language/

mysimplescript.txt")

.to("mock:result");

By default the script is loaded once and cached. However you can disable the

contentCache option and have the script loaded on each evaluation.

For example if the le myscript.txt is changed on disk, then the updated

script is used:

from("direct:start")

// the script will be loaded on each message, as we disabled cache

.to("language:simple:file:target/script/myscript.txt?contentCache=false")

.to("mock:result");

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ Languages

▪ Routing Slip

▪ Dynamic Router

781 CHAPTER 11 - COMPONENT APPENDIX

LDAP COMPONENT

The ldap component allows you to perform searches in LDAP servers using

lters as the message payload.

This component uses standard JNDI (javax.naming package) to access the

server.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-ldap</artifactId>

</dependency>

URI format

ldap:ldapServerBean[?options]

The ldapServerBean portion of the URI refers to a DirContext bean in the

registry. The LDAP component only supports producer endpoints, which

means that an ldap URI cannot appear in the from at the start of a route.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Default

Value Description

base ou=system The base DN for searches.

scope subtree Species how deeply to search the tree of entries, starting at the base DN. Value can be object,

onelevel, or subtree.

pageSize no paging

used

Camel 2.6: When specied the ldap module uses paging to retrieve all results (most LDAP Servers throw

an exception when trying to retrieve more than 1000 entries in one query). To be able to use this a

LdapContext (subclass of DirContext) has to be passed in as ldapServerBean (otherwise an exception is

thrown)

returnedAttributes

depends on

LDAP Server

(could be all

or none)

Camel 2.6: Comma-separated list of attributes that should be set in each entry of the result

Result

The result is returned in the Out body as a

ArrayList<javax.naming.directory.SearchResult> object.

CHAPTER 11 - COMPONENT APPENDIX 782

DirContext

The URI, ldap:ldapserver, references a Spring bean with the ID,

ldapserver. The ldapserver bean may be dened as follows:

<bean id="ldapserver" class="javax.naming.directory.InitialDirContext"

scope="prototype">

<constructor-arg>

<props>

<prop key="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</prop>

<prop key="java.naming.provider.url">ldap://localhost:10389</prop>

</props>

</constructor-arg>

</bean>

The preceding example declares a regular Sun based LDAP DirContext that

connects anonymously to a locally hosted LDAP server.

Samples

Following on from the Spring conguration above, the code sample below

sends an LDAP request to lter search a group for a member. The Common

Name is then extracted from the response.

ProducerTemplate<Exchange> template = exchange

.getContext().createProducerTemplate();

Collection<?> results = (Collection<?>) (template

.sendBody(

"ldap:ldapserver?base=ou=mygroup,ou=groups,ou=system",

"(member=uid=huntc,ou=users,ou=system)"));

if (results.size() > 0) {

// Extract what we need from the device's profile

Iterator<?> resultIter = results.iterator();

SearchResult searchResult = (SearchResult) resultIter

.next();

Attributes attributes = searchResult

.getAttributes();

Attribute deviceCNAttr = attributes.get("cn");

String deviceCN = (String) deviceCNAttr.get();

...

If no specic lter is required - for example, you just need to look up a single

entry - specify a wildcard lter expression. For example, if the LDAP entry has

a Common Name, use a lter expression like:

783 CHAPTER 11 - COMPONENT APPENDIX

DirContext objects are not required to support concurrency by

contract. It is therefore important that the directory context is

declared with the setting, scope="prototype", in the bean

denition or that the context supports concurrency. In the Spring

framework, prototype scoped objects are instantiated each time

they are looked up.

Camel 1.6.1 and Camel 2.0 include a x to support concurrency for

LDAP producers. ldapServerBean contexts are now looked up each

time a request is sent to the LDAP server. In addition, the contexts

are released as soon as the producer completes.

(cn=*)

Binding using credentials

A Camel end user donated this sample code he used to bind to the ldap

server using credentials.

Properties props = new Properties();

props.setProperty(Context.INITIAL_CONTEXT_FACTORY,

"com.sun.jndi.ldap.LdapCtxFactory");

props.setProperty(Context.PROVIDER_URL, "ldap://localhost:389");

props.setProperty(Context.URL_PKG_PREFIXES, "com.sun.jndi.url");

props.setProperty(Context.REFERRAL, "ignore");

props.setProperty(Context.SECURITY_AUTHENTICATION, "simple");

props.setProperty(Context.SECURITY_PRINCIPAL, "cn=Manager");

props.setProperty(Context.SECURITY_CREDENTIALS, "secret");

SimpleRegistry reg = new SimpleRegistry();

reg.put("myldap",new InitialLdapContext(props, null));

CamelContext context = new DefaultCamelContext(reg);

context.addRoutes(

new RouteBuilder() {

public void configure() throws Exception {

from("direct:start").to("ldap:myldap?base=ou=test");

}

);

context.start();

CHAPTER 11 - COMPONENT APPENDIX 784

ProducerTemplate template = context.createProducerTemplate();

Endpoint endpoint = context.getEndpoint("direct:start");

Exchange exchange = endpoint.createExchange();

exchange.getIn().setBody("(uid=test)");

Exchange out = template.send(endpoint, exchange);

Collection<SearchResult> data = out.getOut().getBody(Collection.class);

assert data != null;

assert !data.isEmpty();

System.out.println(out.getOut().getBody());

context.stop();

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

LOG COMPONENT

The log: component logs message exchanges to the underlying logging

mechanism.

Camel 2.7 or better uses s4j which allows you to congure logging via,

among others:

• Log4j

• Logback

• JDK Util Logging logging

Camel 2.6 or lower uses commons-logging which allows you to congure

logging via, among others:

• Log4j

• JDK Util Logging logging

• SimpleLog - a simple provider in commons-logging

Refer to the commons-logging user guide for a more complete overview of

how to use and congure commons-logging.

URI format

log:loggingCategory[?options]

785 CHAPTER 11 - COMPONENT APPENDIX

Where loggingCategory is the name of the logging category to use. You can

append query options to the URI in the following format,

?option=value&option=value&...

For example, a log endpoint typically species the logging level using the

level option, as follows:

log:org.apache.camel.example?level=DEBUG

The default logger logs every exchange (regular logging). But Camel also

ships with the Throughput logger, which is used whenever the groupSize

option is specied.

Options

Option Default Type Description

level INFO String Logging level to use. Possible values: FATAL,ERROR,WARN,INFO,DEBUG,TRACE,OFF

Throughput logging options. By default regular logging is used.

groupSize null Integer An integer that species a group size for throughput logging.

groupInterval null Integer Camel 2.6: If specied will group message stats by this time interval (in millis)

groupDelay 0 Integer Camel 2.6: Set the initial delay for stats (in millis)

groupActiveOnly true boolean Camel 2.6: If true, will hide stats when no new messages have been received for a time

interval, if false, show stats regardless of message trac

note: groupDelay and groupActiveOnly are only applicable when using

groupInterval

Formatting

The log formats the execution of exchanges to log lines.

By default, the log uses LogFormatter to format the log output, where

LogFormatter has the following options:

Option Default Description

showAll false Quick option for turning all options on. (multiline, maxChars has to be manually set if to be used)

showExchangeId false Show the unique exchange ID.

showExchangePattern true Camel 2.3: Shows the Message Exchange Pattern (or MEP for short).

showProperties false Show the exchange properties.

showHeaders false Show the In message headers.

showBodyType true Show the In body Java type.

showBody true Show the In body.

showOut false If the exchange has an Out message, show the Out message.

showException false Camel 2.0: If the exchange has an exception, show the exception message (no stack trace).

showCaughtException false

Camel 2.0: If the exchange has a caught exception, show the exception message (no stack trace). A

caught exception is stored as a property on the exchange (using the key

Exchange.EXCEPTION_CAUGHT) and for instance a doCatch can catch exceptions. See Try Catch Finally.

showStackTrace false Camel 2.0: Show the stack trace, if an exchange has an exception. Only eective if one of showAll,

showException or showCaughtException are enabled.

showFiles false Camel 2.9: Whether Camel should show le bodies or not (eg such as java.io.File).

CHAPTER 11 - COMPONENT APPENDIX 786

Also a log in the DSL

In Camel 2.2 onwards there is a log directly in the DSL, but it has

a dierent purpose. Its meant for lightweight and human logs. See

more details at LogEIP.

showFuture false Camel 2.1: Whether Camel should show java.util.concurrent.Future bodies or not. If enabled

Camel could potentially wait until the Future task is done. Will by default not wait.

showStreams false

Camel 2.8: Whether Camel should show stream bodies or not (eg such as java.io.InputStream).

Beware if you enable this option then you may not be able later to access the message body as the

stream have already been read by this logger. To remedy this you have to use Stream caching.

multiline false If true, each piece of information is logged on a new line.

maxChars Camel 2.0: Limits the number of characters logged per line.

Regular logger sample

In the route below we log the incoming orders at DEBUG level before the order

is processed:

from("activemq:orders").to("log:com.mycompany.order?level=DEBUG").to("bean:processOrder");

Or using Spring XML to dene the route:

<route>

</route>

Regular logger with formatter sample

In the route below we log the incoming orders at INFO level before the order

is processed.

from("activemq:orders").

to("log:com.mycompany.order?showAll=true&multiline=true").to("bean:processOrder");

Throughput logger with groupSize sample

In the route below we log the throughput of the incoming orders at DEBUG

level grouped by 10 messages.

787 CHAPTER 11 - COMPONENT APPENDIX

Logging stream bodies

Camel will by default not log stream or les bodies. You can force

Camel to log those by setting the property on the CamelContext

properties

camelContext.getProperties().put(Exchange.LOG_DEBUG_BODY_STREAMS, true);

from("activemq:orders").

to("log:com.mycompany.order?level=DEBUG?groupSize=10").to("bean:processOrder");

Throughput logger with groupInterval sample

This route will result in message stats logged every 10s, with an initial 60s

delay and stats should be displayed even if there isn't any message trac.

from("activemq:orders").

to("log:com.mycompany.order?level=DEBUG?groupInterval=10000&groupDelay=60000&groupActiveOnly=false").to("bean:processOrder");

The following will be logged:

"Received: 1000 new messages, with total 2000 so far. Last group took: 10000 millis

which is: 100 messages per second. average: 100"

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

• Tracer

• How do I use log4j

• How do I use Java 1.4 logging

• LogEIP for using log directly in the DSL for human logs.

LUCENE (INDEXER AND SEARCH) COMPONENT

Available as of Camel 2.2

CHAPTER 11 - COMPONENT APPENDIX 788

The lucene component is based on the Apache Lucene project. Apache

Lucene is a powerful high-performance, full-featured text search engine

library written entirely in Java. For more details about Lucene, please see the

following links

• http://lucene.apache.org/java/docs/

• http://lucene.apache.org/java/docs/features.html

The lucene component in camel facilitates integration and utilization of

Lucene endpoints in enterprise integration patterns and scenarios. The

lucene component does the following

• builds a searchable index of documents when payloads are sent to

the Lucene Endpoint

• facilitates performing of indexed searches in Camel

This component only supports producer endpoints.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-lucene</artifactId>

</dependency>

URI format

lucene:searcherName:insert[?options]

lucene:searcherName:query[?options]

You can append query options to the URI in the following format,

?option=value&option=value&...

Insert Options

Name Default

Value Description

analyzer StandardAnalyzer

An Analyzer builds TokenStreams, which analyze text. It thus represents a policy for extracting index terms

from text. The value for analyzer can be any class that extends the abstract class

org.apache.lucene.analysis.Analyzer. Lucene also oers a rich set of analyzers out of the box

indexDir ./indexDirectory A le system directory in which index les are created upon analysis of the document by the specied

analyzer

srcDir null An optional directory containing les to be used to be analyzed and added to the index at producer startup.

789 CHAPTER 11 - COMPONENT APPENDIX

Query Options

Name Default

Value Description

analyzer StandardAnalyzer

An Analyzer builds TokenStreams, which analyze text. It thus represents a policy for extracting index terms

from text. The value for analyzer can be any class that extends the abstract class

org.apache.lucene.analysis.Analyzer. Lucene also oers a rich set of analyzers out of the box

indexDir ./indexDirectory A le system directory in which index les are created upon analysis of the document by the specied

analyzer

maxHits 10 An integer value that limits the result set of the search operation

Sending/Receiving Messages to/from the cache

Message Headers

Header Description

QUERY The Lucene Query to performed on the index. The query may include wildcards and phrases

Lucene Producers

This component supports 2 producer endpoints.

•insert - The insert producer builds a searchable index by analyzing

the body in incoming exchanges and associating it with a token

("content").

•query - The query producer performs searches on a pre-created

index. The query uses the searchable index to perform score &

relevance based searches. Queries are sent via the incoming

exchange contains a header property name called 'QUERY'. The value

of the header property 'QUERY' is a Lucene Query. For more details

on how to create Lucene Queries check out http://lucene.apache.org/

java/3_0_0/queryparsersyntax.html

Lucene Processor

There is a processor called LuceneQueryProcessor available to perform

queries against lucene without the need to create a producer.

CHAPTER 11 - COMPONENT APPENDIX 790

Lucene Usage Samples

Example 1: Creating a Lucene index

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from("direct:start").

to("lucene:whitespaceQuotesIndex:insert?

analyzer=#whitespaceAnalyzer&indexDir=#whitespace&srcDir=#load_dir").

to("mock:result");

}

};

Example 2: Loading properties into the JNDI registry in

the Camel Context

@Override

protected JndiRegistry createRegistry() throws Exception {

JndiRegistry registry =

new JndiRegistry(createJndiContext());

registry.bind("whitespace",new File("./whitespaceIndexDir"));

registry.bind("load_dir",

new File("src/test/resources/sources"));

registry.bind("whitespaceAnalyzer",

new WhitespaceAnalyzer());

return registry;

}

...

CamelContext context = new DefaultCamelContext(createRegistry());

Example 2: Performing searches using a Query Producer

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from("direct:start").

setHeader("QUERY", constant("Seinfeld")).

to("lucene:searchIndex:query?

analyzer=#whitespaceAnalyzer&indexDir=#whitespace&maxHits=20").

to("direct:next");

from("direct:next").process(new Processor() {

public void process(Exchange exchange) throws Exception {

Hits hits = exchange.getIn().getBody(Hits.class);

printResults(hits);

791 CHAPTER 11 - COMPONENT APPENDIX

}

private void printResults(Hits hits) {

LOG.debug("Number of hits: " + hits.getNumberOfHits());

for (int i = 0; i < hits.getNumberOfHits(); i++) {

LOG.debug("Hit " + i + " Index Location:" +

hits.getHit().get(i).getHitLocation());

LOG.debug("Hit " + i + " Score:" + hits.getHit().get(i).getScore());

LOG.debug("Hit " + i + " Data:" + hits.getHit().get(i).getData());

}

}).to("mock:searchResult");

}

};

Example 3: Performing searches using a Query Processor

RouteBuilder builder = new RouteBuilder() {

public void configure() {

try {

from("direct:start").

setHeader("QUERY", constant("Rodney Dangerfield")).

process(new LuceneQueryProcessor("target/stdindexDir", analyzer,

null, 20)).

to("direct:next");

}catch (Exception e) {

e.printStackTrace();

}

from("direct:next").process(new Processor() {

public void process(Exchange exchange) throws Exception {

Hits hits = exchange.getIn().getBody(Hits.class);

printResults(hits);

}

private void printResults(Hits hits) {

LOG.debug("Number of hits: " + hits.getNumberOfHits());

for (int i = 0; i < hits.getNumberOfHits(); i++) {

LOG.debug("Hit " + i + " Index Location:" +

hits.getHit().get(i).getHitLocation());

LOG.debug("Hit " + i + " Score:" +

hits.getHit().get(i).getScore());

LOG.debug("Hit " + i + " Data:" + hits.getHit().get(i).getData());

}

}).to("mock:searchResult");

}

};

CHAPTER 11 - COMPONENT APPENDIX 792

MAIL COMPONENT

The mail component provides access to Email via Spring's Mail support and

the underlying JavaMail system.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-mail</artifactId>

</dependency>

URI format

Mail endpoints can have one of the following URI formats (for the protocols,

SMTP, POP3, or IMAP, respectively):

smtp://[username@]host[:port][?options]

pop3://[username@]host[:port][?options]

imap://[username@]host[:port][?options]

The mail component also supports secure variants of these protocols

(layered over SSL). You can enable the secure protocols by adding sto the

scheme:

smtps://[username@]host[:port][?options]

pop3s://[username@]host[:port][?options]

imaps://[username@]host[:port][?options]

You can append query options to the URI in the following format,

?option=value&option=value&...

Sample endpoints

Typically, you specify a URI with login credentials as follows (taking SMTP as

an example):

smtp://[username@]host[:port][?password=somepwd]

Alternatively, it is possible to specify both the user name and the password

as query options:

793 CHAPTER 11 - COMPONENT APPENDIX

Geronimo mail .jar

We have discovered that the geronimo mail .jar (v1.6) has a bug

when polling mails with attachments. It cannot correctly identify the

Content-Type. So, if you attach a .jpeg le to a mail and you poll

it, the Content-Type is resolved as text/plain and not as image/

jpeg. For that reason, we have added an

org.apache.camel.component.ContentTypeResolver SPI

interface which enables you to provide your own implementation

and x this bug by returning the correct Mime type based on the

le name. So if the le name ends with jpeg/jpg, you can return

image/jpeg.

You can set your custom resolver on the MailComponent instance or on the

MailEndpoint instance. This feature is added in Camel 1.6.2/2.0.

POP3 or IMAP

POP3 has some limitations and end users are encouraged to use

IMAP if possible.

Using mock-mail for testing

You can use a mock framework for unit testing, which allows you to

test without the need for a real mail server. However you should

remember to not include the mock-mail when you go into

production or other environments where you need to send mails to

a real mail server. Just the presence of the mock-javamail.jar on the

classpath means that it will kick in and avoid sending the mails.

smtp://host[:port]?password=somepwd&username=someuser

For example:

smtp://mycompany.mailserver:30?password=tiger&username=scott

CHAPTER 11 - COMPONENT APPENDIX 794

Default ports

As of Camel 1.4, default port numbers are supported. If the port number is

omitted, Camel determines the port number to use based on the protocol.

Protocol Default Port Number

SMTP 25

SMTPS 465

POP3 110

POP3S 995

IMAP 143

IMAPS 993

Options

Property Default Description

host The host name or IP address to connect to.

port See DefaultPorts The TCP port number to connect on.

username The user name on the email server.

password null The password on the email server.

ignoreUriScheme false If false, Camel uses the scheme to determine the transport protocol (POP,

IMAP, SMTP etc.)

defaultEncoding null The default encoding to use for Mime Messages.

contentType text/plain New option in Camel 1.5. The mail message content type. Use text/html for

HTML mails.

folderName INBOX The folder to poll.

destination username@host @deprecated Use the to option instead. The TO recipients (receivers of the

email).

to username@host As of Camel 1.4, the TO recipients (the receivers of the mail). Separate multiple

email addresses with a comma.

CC null As of Camel 1.4, the CC recipients (the receivers of the mail). Separate multiple

email addresses with a comma.

BCC null As of Camel 1.4, the BCC recipients (the receivers of the mail). Separate

multiple email addresses with a comma.

from camel@localhost The FROM email address.

subject As of Camel 2.3, the Subject of the message being sent. Note: Setting the

subject in the header takes precedence over this option.

deleteProcessedMessages true/false

Deletes the messages after they have been processed. This is done by setting

the DELETED ag on the mail message. If false, the SEEN ag is set instead. As

of Camel 1.5, the default setting is false. This option is named delete in

Camel 2.0 onwards.

delete false

Camel 2.0: Deletes the messages after they have been processed. This is done

by setting the DELETED ag on the mail message. If false, the SEEN ag is set

instead.

processOnlyUnseenMessages false/true

As of Camel 1.4, it is possible to congure a consumer endpoint so that it

processes only unseen messages (that is, new messages) or all messages. Note

that Camel always skips deleted messages. Setting this option to true will lter

to only unseen messages. As of Camel 1.5, the default setting is true. POP3

does not support the SEEN ag, so this option is not supported in POP3; use IMAP

instead. This option is named unseen in Camel 2.0 onwards.

unseen true Camel 2.0: Is used to fetch only unseen messages (that is, new messages).

Note that POP3 does not support the SEEN ag; use IMAP instead.

fetchSize -1

As of Camel 1.4, this option sets the maximum number of messages to

consume during a poll. This can be used to avoid overloading a mail server, if a

mailbox folder contains a lot of messages. Default value of -1 means no fetch

size and all messages will be consumed. Setting the value to 0 is a special

corner case, where Camel will not consume any messages at all.

795 CHAPTER 11 - COMPONENT APPENDIX

alternateBodyHeader mail_alternateBody

Camel 1.6.1: Species the key to an IN message header that contains an

alternative email body. For example, if you send emails in text/html format and

want to provide an alternative mail body for non-HTML email clients, set the

alternative mail body with this key as a header. In Camel 2.0, this option has

been renamed to alternativeBodyHeader.

alternativeBodyHeader CamelMailAlternativeBody

Camel 2.0: Species the key to an IN message header that contains an

alternative email body. For example, if you send emails in text/html format and

want to provide an alternative mail body for non-HTML email clients, set the

alternative mail body with this key as a header.

debugMode false

As of Camel 1.4, it is possible to enable debug mode on the underlying mail

framework. The SUN Mail framework logs the debug messages to System.out by

default.

connectionTimeout 30000 As of Camel 1.4, the connection timeout can be congured in milliseconds.

Default is 30 seconds.

consumer.initialDelay 1000 Milliseconds before the polling starts.

consumer.delay 60000

As of Camel 1.4, the default consumer delay is now 60 seconds. Camel will

therefore only poll the mailbox once a minute to avoid overloading the mail

server. The default value in Camel 1.3 is 500 milliseconds.

consumer.useFixedDelay false Set to true to use a xed delay between polls, otherwise xed rate is used. See

ScheduledExecutorService in JDK for details.

disconnect false Camel 2.9: Whether the consumer should disconnect after polling. If enabled

this forces Camel to connect on each poll.

mail.XXX null

As of Camel 2.0, you can set any additional java mail properties. For instance if

you want to set a special property when using POP3 you can now provide the

option directly in the URI such as: mail.pop3.forgettopheaders=true. You can

set multiple such options, for example:

mail.pop3.forgettopheaders=true&mail.mime.encodefilename=true.

mapMailMessage true

Camel 2.8: Species whether Camel should map the received mail message to

Camel body/headers. If set to true, the body of the mail message is mapped to

the body of the Camel IN message and the mail headers are mapped to IN

headers. If this option is set to false then the IN message contains a raw

javax.mail.Message. You can retrieve this raw message by calling

exchange.getIn().getBody(javax.mail.Message.class).

maxMessagesPerPoll 0

Camel 2.0: Species the maximum number of messages to gather per poll. By

default, no maximum is set. Can be used to set a limit of e.g. 1000 to avoid

downloading thousands of les when the server starts up. Set a value of 0 or

negative to disable this option.

javaMailSender null

Camel 2.0: Species a pluggable

org.springframework.mail.javamail.JavaMailSender instance in order to

use a custom email implementation. If none provided, Camel uses the default

org.springframework.mail.javamail.JavaMailSenderImpl.

ignoreUnsupportedCharset false

Camel 2.0: Option to let Camel ignore unsupported charset in the local JVM

when sending mails. If the charset is unsupported then charset=XXX (where XXX

represents the unsupported charset) is removed from the content-type and it

relies on the platform default instead.

SSL support

The underlying mail framework is responsible for providing SSL support.

Camel uses SUN JavaMail, which only trusts certicates issued by well known

Certicate Authorities. So if you issue your own certicate, you have to

import it into the local Java keystore le (see SSLNOTES.txt in JavaMail for

details).

Defaults changed in Camel 1.4

As of Camel 1.4 the default consumer delay is now 60 seconds. Camel will

therefore only poll the mailbox once a minute to avoid overloading the mail

server. The default value in Camel 1.3 is 500 milliseconds.

CHAPTER 11 - COMPONENT APPENDIX 796

Defaults changed in Camel 1.5

In Camel 1.5 the following default options have changed:

▪deleteProcessedMessages is now false, as we felt Camel should not

delete mails on the mail server by default.

▪processOnlyUnseenMessages is now true, as we felt Camel should

only poll new mails by default.

Mail Message Content

Camel uses the message exchange's IN body as the MimeMessage text

content. The body is converted to String.class.

Camel copies all of the exchange's IN headers to the MimeMessage

headers.

The subject of the MimeMessage can be congured using a header

property on the IN message. The code below demonstrates this:

from("direct:a").setHeader("subject",

constant(subject)).to("smtp://james2@localhost");

The same applies for other MimeMessage headers such as recipients, so you

can use a header property as To:

Map<String,Object> map = new HashMap<String,Object>();

map.put("To","davsclaus@apache.org");

map.put("From","jstrachan@apache.org");

map.put("Subject","Camel rocks");

String body = "Hello Claus.\nYes it does.\n\nRegards James.";

template.sendBodyAndHeaders("smtp://davsclaus@apache.org", body, map);

Headers take precedence over pre-congured recipients

From Camel 1.5 onwards, the recipients specied in the message headers

always take precedence over recipients pre-congured in the endpoint URI.

The idea is that if you provide any recipients in the message headers, that is

what you get. The recipients pre-congured in the endpoint URI are treated

as a fallback.

In the sample code below, the email message is sent to

davsclaus@apache.org, because it takes precedence over the pre-

congured recipient, info@mycompany.com. Any CC and BCC settings in the

endpoint URI are also ignored and those recipients will not receive any mail.

The choice between headers and pre-congured settings is all or nothing: the

mail component either takes the recipients exclusively from the headers or

797 CHAPTER 11 - COMPONENT APPENDIX

exclusively from the pre-congured settings. It is not possible to mix and

match headers and pre-congured settings.

Map<String,Object> headers = new HashMap<String,Object>();

headers.put("to","davsclaus@apache.org");

template.sendBodyAndHeaders("smtp://admin@localhost?to=info@mycompany.com",

"Hello World", headers);

Multiple recipients for easier conguration

As of Camel 1.5, it is possible to set multiple recipients using a comma-

separated or a semicolon-separated list. This applies both to header settings

and to settings in an endpoint URI. For example:

Map<String,Object> headers = new HashMap<String,Object>();

headers.put("to","davsclaus@apache.org ; jstrachan@apache.org ;

ningjiang@apache.org");

The preceding example uses a semicolon, ;, as the separator character.

Setting sender name and email

You can specify recipients in the format, name <email>, to include both the

name and the email address of the recipient.

For example, you dene the following headers on the a Message:

Map headers = new HashMap();

map.put("To","Claus Ibsen <davsclaus@apache.org>");

map.put("From","James Strachan <jstrachan@apache.org>");

map.put("Subject","Camel is cool");

SUN JavaMail

SUN JavaMail is used under the hood for consuming and producing mails.

We encourage end-users to consult these references when using either POP3

or IMAP protocol. Note particularly that POP3 has a much more limited set of

features than IMAP.

▪ SUN POP3 API

▪ SUN IMAP API

▪ And generally about the MAIL Flags

CHAPTER 11 - COMPONENT APPENDIX 798

Samples

We start with a simple route that sends the messages received from a JMS

queue as emails. The email account is the admin account on

mymailserver.com.

from("jms://queue:subscription").to("smtp://admin@mymailserver.com?password=secret");

In the next sample, we poll a mailbox for new emails once every minute.

Notice that we use the special consumer option for setting the poll interval,

consumer.delay, as 60000 milliseconds = 60 seconds.

from("imap://admin@mymailserver.com

password=secret&unseen=true&consumer.delay=60000")

.to("seda://mails");

In this sample we want to send a mail to multiple recipients. This feature was

introduced in camel 1.4:

// all the recipients of this mail are:

// To: camel@riders.org , easy@riders.org

// CC: me@you.org

// BCC: someone@somewhere.org

String recipients =

"&To=camel@riders.org,easy@riders.org&CC=me@you.org&BCC=someone@somewhere.org";

from("direct:a").to("smtp://you@mymailserver.com?password=secret&From=you@apache.org"

+ recipients);

Sending mail with attachment sample

The mail component supports attachments, which is a feature that was

introduced in Camel 1.4. In the sample below, we send a mail message

containing a plain text message with a logo le attachment.

// create an exchange with a normal body and attachment to be produced as email

Endpoint endpoint =

context.getEndpoint("smtp://james@mymailserver.com?password=secret");

// create the exchange with the mail message that is multipart with a file and a

Hello World text/plain message.

Exchange exchange = endpoint.createExchange();

Message in = exchange.getIn();

in.setBody("Hello World");

in.addAttachment("logo.jpeg",new DataHandler(new FileDataSource("src/test/data/

logo.jpeg")));

799 CHAPTER 11 - COMPONENT APPENDIX

Attachments are not support by all Camel components

The Attachments API is based on the Java Activation Framework and

is generally only used by the Mail API. Since many of the other

Camel components do not support attachments, the attachments

could potentially be lost as they propagate along the route. The rule

of thumb, therefore, is to add attachments just before sending a

message to the mail endpoint.

// create a producer that can produce the exchange (= send the mail)

Producer producer = endpoint.createProducer();

// start the producer

producer.start();

// and let it go (processes the exchange by sending the email)

producer.process(exchange);

SSL sample

In this sample, we want to poll our Google mail inbox for mails. To download

mail onto a local mail client, Google mail requires you to enable and

congure SSL. This is done by logging into your Google mail account and

changing your settings to allow IMAP access. Google have extensive

documentation on how to do this.

from("imaps://imap.gmail.com?username=YOUR_USERNAME@gmail.com&password=YOUR_PASSWORD"

+"&delete=false&unseen=true&consumer.delay=60000").to("log:newmail");

The preceding route polls the Google mail inbox for new mails once every

minute and logs the received messages to the newmail logger category.

Running the sample with DEBUG logging enabled, we can monitor the

progress in the logs:

2008-05-08 06:32:09,640 DEBUG MailConsumer - Connecting to MailStore

imaps//imap.gmail.com:993 (SSL enabled), folder=INBOX

2008-05-08 06:32:11,203 DEBUG MailConsumer - Polling mailfolder:

imaps//imap.gmail.com:993 (SSL enabled), folder=INBOX

2008-05-08 06:32:11,640 DEBUG MailConsumer - Fetching 1 messages. Total 1 messages.

2008-05-08 06:32:12,171 DEBUG MailConsumer - Processing message: messageNumber=[332],

from=[James Bond <007@mi5.co.uk>], to=YOUR_USERNAME@gmail.com], subject=[...

2008-05-08 06:32:12,187 INFO newmail - Exchange[MailMessage: messageNumber=[332],

from=[James Bond <007@mi5.co.uk>], to=YOUR_USERNAME@gmail.com], subject=[...

CHAPTER 11 - COMPONENT APPENDIX 800

Consuming mails with attachment sample

In this sample we poll a mailbox and store all attachments from the mails as

les. First, we dene a route to poll the mailbox. As this sample is based on

google mail, it uses the same route as shown in the SSL sample:

from("imaps://imap.gmail.com?username=YOUR_USERNAME@gmail.com&password=YOUR_PASSWORD"

+"&delete=false&unseen=true&consumer.delay=60000").process(new

MyMailProcessor());

Instead of logging the mail we use a processor where we can process the

mail from java code:

public void process(Exchange exchange) throws Exception {

// the API is a bit clunky so we need to loop

Map<String, DataHandler> attachments = exchange.getIn().getAttachments();

if (attachments.size() > 0) {

for (String name : attachments.keySet()) {

DataHandler dh = attachments.get(name);

// get the file name

String filename = dh.getName();

// get the content and convert it to byte[]

byte[] data = exchange.getContext().getTypeConverter()

.convertTo(byte[].class, dh.getInputStream());

// write the data to a file

FileOutputStream out = new FileOutputStream(filename);

out.write(data);

out.flush();

out.close();

}

As you can see the API to handle attachments is a bit clunky but it's there so

you can get the javax.activation.DataHandler so you can handle the

attachments using standard API.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

801 CHAPTER 11 - COMPONENT APPENDIX

MINA COMPONENT

The mina: component is a transport for working with Apache MINA

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-mina</artifactId>

</dependency>

URI format

mina:tcp://hostname[:port][?options]

mina:udp://hostname[:port][?options]

mina:vm://hostname[:port][?options]

From Camel 1.3 onwards you can specify a codec in the Registry using the

codec option. If you are using TCP and no codec is specied then the

textline ag is used to determine if text line based codec or object

serialization should be used instead. By default the object serialization is

used.

For UDP if no codec is specied the default uses a basic ByteBuffer based

codec.

The VM protocol is used as a direct forwarding mechanism in the same

JVM. See the MINA VM-Pipe API documentation for details.

A Mina producer has a default timeout value of 30 seconds, while it waits

for a response from the remote server.

In normal use, camel-mina only supports marshalling the body

content—message headers and exchange properties are not sent.

However, the option, transferExchange, does allow you to transfer the

exchange itself over the wire. See options below.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Option Default

Value Description

codec null As of 1.3, you can refer to a named ProtocolCodecFactory instance in your Registry such as your

Spring ApplicationContext, which is then used for the marshalling.

CHAPTER 11 - COMPONENT APPENDIX 802

codec null Camel 2.0: You must use the #notation to look up your codec in the Registry. For example, use

#myCodec to look up a bean with the id value, myCodec.

disconnect false Camel 2.3: Whether or not to disconnect(close) from Mina session right after use. Can be used for

both consumer and producer.

textline false Only used for TCP. If no codec is specied, you can use this ag in 1.3 or later to indicate a text line

based codec; if not specied or the value is false, then Object Serialization is assumed over TCP.

textlineDelimiter DEFAULT

Camel 1.6.0/2.0 Only used for TCP and if textline=true. Sets the text line delimiter to use. Possible

values are: DEFAULT,AUTO,WINDOWS,UNIX or MAC. If none provided, Camel will use DEFAULT. This

delimiter is used to mark the end of text.

sync false/true

As of 1.3, you can congure the exchange pattern to be either InOnly (default) or InOut. Setting

sync=true means a synchronous exchange (InOut), where the client can read the response from

MINA (the exchange Out message). The default value has changed in Camel 1.5 to true. In older

releases, the default value is false.

lazySessionCreation See

description

As of 1.3, sessions can be lazily created to avoid exceptions, if the remote server is not up and

running when the Camel producer is started. From Camel 2.0 onwards, the default is true. In Camel

1.x, the default is false.

timeout 30000

As of 1.3, you can congure the timeout that species how long to wait for a response from a remote

server. The timeout unit is in milliseconds, so 60000 is 60 seconds. The timeout is only used for Mina

producer.

encoding JVM Default As of 1.3, you can congure the encoding (a charset name) to use for the TCP textline codec and the

UDP protocol. If not provided, Camel will use the JVM default Charset.

transferExchange false

Only used for TCP. As of 1.3, you can transfer the exchange over the wire instead of just the body.

The following elds are transferred: In body, Out body, fault body, In headers, Out headers, fault

headers, exchange properties, exchange exception. This requires that the objects are serializable.

Camel will exclude any non-serializable objects and log it at WARN level.

minaLogger false As of 1.3, you can enable the Apache MINA logging lter. Apache MINA uses slf4j logging at INFO

level to log all input and output.

filters null

As of 2.0, you can set a list of Mina IoFilters to register. The filters value must be one of the

following:

•Camel 2.2: comma-separated list of bean references (e.g.

#filterBean1,#filterBean2) where each bean must be of type

org.apache.mina.common.IoFilter.

•Camel 2.0: a reference to a bean of type

List<org.apache.mina.common.IoFilter>.

encoderMaxLineLength -1 As of 2.1, you can set the textline protocol encoder max line length. By default the default value of

Mina itself is used which are Integer.MAX_VALUE.

decoderMaxLineLength -1 As of 2.1, you can set the textline protocol decoder max line length. By default the default value of

Mina itself is used which are 1024.

producerPoolSize 16

1.6.2 (only in 1.6.x): The TCP producer is now thread safe and supports concurrency much better.

This option allows you to congure the number of threads in its thread pool for concurrent producers.

Note: Camel 2.0 have a pooled service which ensured it was already thread safe and supported

concurrency already. So this is a special patch for 1.6.x.

allowDefaultCodec true

The mina component installs a default codec if both, codec is null and textline is false. Setting

allowDefaultCodec to false prevents the mina component from installing a default codec as the

rst element in the lter chain. This is useful in scenarios where another lter must be the rst in the

lter chain, like the SSL lter.

disconnectOnNoReply true Camel 2.3: If sync is enabled then this option dictates MinaConsumer if it should disconnect where

there is no reply to send back.

noReplyLogLevel WARN Camel 2.3: If sync is enabled this option dictates MinaConsumer which logging level to use when

logging a there is no reply to send back. Values are: FATAL, ERROR, INFO, DEBUG, OFF.

Default behavior changed

In Camel 2.0 the codec option must use #notation for lookup of the codec

bean in the Registry.

In Camel 2.0 the lazySessionCreation option now defaults to true.

In Camel 1.5 the sync option has changed its default value from false to

true, as we felt it was confusing for end-users when they used MINA to call

remote servers and Camel wouldn't wait for the response.

In Camel 1.4 or later codec=textline is no longer supported. Use the

textline=true option instead.

803 CHAPTER 11 - COMPONENT APPENDIX

Using a custom codec

See the Mina documentation how to write your own codec. To use your

custom codec with camel-mina, you should register your codec in the

Registry; for example, by creating a bean in the Spring XML le. Then use the

codec option to specify the bean ID of your codec. See HL7 that has a

custom codec.

Sample with sync=false

In this sample, Camel exposes a service that listens for TCP connections on

port 6200. We use the textline codec. In our route, we create a Mina

consumer endpoint that listens on port 6200:

from("mina:tcp://localhost:" + port1 + "?textline=true&sync=false").to("mock:result");

As the sample is part of a unit test, we test it by sending some data to it on

port 6200.

MockEndpoint mock = getMockEndpoint("mock:result");

mock.expectedBodiesReceived("Hello World");

template.sendBody("mina:tcp://localhost:" + port1 + "?textline=true&sync=false",

"Hello World");

assertMockEndpointsSatisfied();

Sample with sync=true

In the next sample, we have a more common use case where we expose a

TCP service on port 6201 also use the textline codec. However, this time we

want to return a response, so we set the sync option to true on the

consumer.

from("mina:tcp://localhost:" + port2 + "?textline=true&sync=true").process(new

Processor() {

public void process(Exchange exchange) throws Exception {

String body = exchange.getIn().getBody(String.class);

exchange.getOut().setBody("Bye " + body);

}

});

Then we test the sample by sending some data and retrieving the response

using the template.requestBody() method. As we know the response is a

String, we cast it to String and can assert that the response is, in fact,

something we have dynamically set in our processor code logic.

CHAPTER 11 - COMPONENT APPENDIX 804

String response = (String)template.requestBody("mina:tcp://localhost:" + port2 +

"?textline=true&sync=true", "World");

assertEquals("Bye World", response);

Sample with Spring DSL

Spring DSL can, of course, also be used for MINA. In the sample below we

expose a TCP server on port 5555:

<route>

</route>

In the route above, we expose a TCP server on port 5555 using the textline

codec. We let the Spring bean with ID, myTCPOrderHandler, handle the

request and return a reply. For instance, the handler bean could be

implemented as follows:

public String handleOrder(String payload) {

...

return "Order: OK"

}

Conguring Mina endpoints using Spring bean style

Available as of Camel 2.0

Conguration of Mina endpoints is now possible using regular Spring bean

style conguration in the Spring DSL.

However, in the underlying Apache Mina toolkit, it is relatively dicult to

set up the acceptor and the connector, because you can not use simple

setters. To resolve this diculty, we leverage the MinaComponent as a Spring

factory bean to congure this for us. If you really need to congure this

yourself, there are setters on the MinaEndpoint to set these when needed.

The sample below shows the factory approach:

<!-- Creating mina endpoints is a bit complex so we reuse MinaComponnet

as a factory bean to create our endpoint, this is the easiest to do -->

<constructor-arg index="0" ref="myCamel"/>

</bean>

805 CHAPTER 11 - COMPONENT APPENDIX

<!-- This is our mina endpoint configured with spring, we will use the factory above

to create it for us. The goal is to invoke the createEndpoint method with the

mina configuration parameter we defined using the constructor-arg option -->

<bean id="myMinaEndpoint"

factory-bean="myMinaFactory"

factory-method="createEndpoint">

<constructor-arg index="0" ref="myMinaConfig"/>

</bean>

</bean>

And then we can refer to our endpoint directly in the route, as follows:

<route>

</route>

Closing Session When Complete

Available as of Camel 1.6.1

When acting as a server you sometimes want to close the session when,

for example, a client conversion is nished. To instruct Camel to close the

session, you should add a header with the key

CamelMinaCloseSessionWhenComplete set to a boolean true value.

For instance, the example below will close the session after it has written

the bye message back to the client:

from("mina:tcp://localhost:8080?sync=true&textline=true").process(new

Processor() {

public void process(Exchange exchange) throws Exception {

String body = exchange.getIn().getBody(String.class);

exchange.getOut().setBody("Bye " + body);

exchange.getOut().setHeader(MinaConstants.MINA_CLOSE_SESSION_WHEN_COMPLETE, true);

}

});

CHAPTER 11 - COMPONENT APPENDIX 806

Get the IoSession for message

Available since Camel 2.1

You can get the IoSession from the message header with this key

MinaEndpoint.HEADER_MINA_IOSESSION, and also get the local host address

with the key MinaEndpoint.HEADER_LOCAL_ADDRESS and remote host

address with the key MinaEndpoint.HEADER_REMOTE_ADDRESS.

Conguring Mina lters

Available since Camel 2.0

Filters permit you to use some Mina Filters, such as SslFilter. You can

also implement some customized lters. Please note that codec and logger

are also implemented as Mina lters of type, IoFilter. Any lters you may

dene are appended to the end of the lter chain; that is, after codec and

logger.

For instance, the example below will send a keep-alive message after 10

seconds of inactivity:

public class KeepAliveFilter extends IoFilterAdapter {

@Override

public void sessionCreated(NextFilter nextFilter, IoSession session)

throws Exception {

session.setIdleTime(IdleStatus.BOTH_IDLE, 10);

nextFilter.sessionCreated(session);

}

@Override

public void sessionIdle(NextFilter nextFilter, IoSession session,

IdleStatus status) throws Exception {

session.write("NOOP"); // NOOP is a FTP command for keep alive

nextFilter.sessionIdle(session, status);

}

As Camel Mina may use a request-reply scheme, the endpoint as a client

would like to drop some message, such as greeting when the connection is

established. For example, when you connect to an FTP server, you will get a

220 message with a greeting (220 Welcome to Pure-FTPd). If you don't drop

the message, your request-reply scheme will be broken.

public class DropGreetingFilter extends IoFilterAdapter {

@Override

public void messageReceived(NextFilter nextFilter, IoSession session,

Object message) throws Exception {

807 CHAPTER 11 - COMPONENT APPENDIX

if (message instanceof String) {

String ftpMessage = (String) message;

// "220" is given as greeting. "200 Zzz" is given as a response to "NOOP"

(keep alive)

if (ftpMessage.startsWith("220") || or ftpMessage.startsWith("200 Zzz")) {

// Dropping greeting

return;

}

nextFilter.messageReceived(session, message);

}

Then, you can congure your endpoint using Spring DSL:

<constructor-arg index="0" ref="camelContext" />

</bean>

<bean id="myMinaEndpoint"

factory-bean="myMinaFactory"

factory-method="createEndpoint">

<constructor-arg index="0" ref="myMinaConfig"/>

</bean>

</bean>

<constructor-arg>

</list>

</constructor-arg>

</bean>

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ Camel Netty

CHAPTER 11 - COMPONENT APPENDIX 808

MOCK COMPONENT

Testing of distributed and asynchronous processing is notoriously dicult.

The Mock, Test and DataSet endpoints work great with the Camel Testing

Framework to simplify your unit and integration testing using Enterprise

Integration Patterns and Camel's large range of Components together with

the powerful Bean Integration.

The Mock component provides a powerful declarative testing mechanism,

which is similar to jMock in that it allows declarative expectations to be

created on any Mock endpoint before a test begins. Then the test is run,

which typically res messages to one or more endpoints, and nally the

expectations can be asserted in a test case to ensure the system worked as

expected.

This allows you to test various things like:

• The correct number of messages are received on each endpoint,

• The correct payloads are received, in the right order,

• Messages arrive on an endpoint in order, using some Expression to

create an order testing function,

• Messages arrive match some kind of Predicate such as that specic

headers have certain values, or that parts of the messages match

some predicate, such as by evaluating an XPath or XQuery

Expression.

Note that there is also the Test endpoint which is a Mock endpoint, but which

uses a second endpoint to provide the list of expected message bodies and

automatically sets up the Mock endpoint assertions. In other words, it's a

Mock endpoint that automatically sets up its assertions from some sample

messages in a File or database, for example.

URI format

mock:someName[?options]

Where someName can be any string that uniquely identies the endpoint.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Option Default Description

reportGroup null A size to use a throughput logger for reporting

809 CHAPTER 11 - COMPONENT APPENDIX

Simple Example

Here's a simple example of Mock endpoint in use. First, the endpoint is

resolved on the context. Then we set an expectation, and then, after the test

has run, we assert that our expectations have been met.

MockEndpoint resultEndpoint = context.resolveEndpoint("mock:foo", MockEndpoint.class);

resultEndpoint.expectedMessageCount(2);

// send some messages

...

// now lets assert that the mock:foo endpoint received 2 messages

resultEndpoint.assertIsSatisfied();

You typically always call the assertIsSatised() method to test that the

expectations were met after running a test.

Camel will by default wait 10 seconds when the assertIsSatisfied() is

invoked. This can be congured by setting the setResultWaitTime(millis)

method.

When the assertion is satised then Camel will stop waiting and continue

from the assertIsSatisfied method. That means if a new message arrives

on the mock endpoint, just a bit later, that arrival will not aect the outcome

of the assertion. Suppose you do want to test that no new messages arrives

after a period thereafter, then you can do that by setting the

setAssertPeriod method.

Using assertPeriod

Available as of Camel 2.7

When the assertion is satised then Camel will stop waiting and continue

from the assertIsSatisfied method. That means if a new message arrives

on the mock endpoint, just a bit later, that arrival will not aect the outcome

of the assertion. Suppose you do want to test that no new messages arrives

after a period thereafter, then you can do that by setting the

setAssertPeriod method, for example:

MockEndpoint resultEndpoint = context.resolveEndpoint("mock:foo", MockEndpoint.class);

resultEndpoint.setAssertPeriod(5000);

resultEndpoint.expectedMessageCount(2);

// send some messages

...

CHAPTER 11 - COMPONENT APPENDIX 810

// now lets assert that the mock:foo endpoint received 2 messages

resultEndpoint.assertIsSatisfied();

Setting expectations

You can see from the javadoc of MockEndpoint the various helper methods

you can use to set expectations. The main methods are as follows:

Method Description

expectedMessageCount(int) To dene the expected message count on the endpoint.

expectedMinimumMessageCount(int) To dene the minimum number of expected messages on the endpoint.

expectedBodiesReceived(...) To dene the expected bodies that should be received (in order).

expectedHeaderReceived(...) To dene the expected header that should be received

expectsAscending(Expression) To add an expectation that messages are received in order, using the given Expression to compare

messages.

expectsDescending(Expression) To add an expectation that messages are received in order, using the given Expression to compare

messages.

expectsNoDuplicates(Expression)

To add an expectation that no duplicate messages are received; using an Expression to calculate a

unique identier for each message. This could be something like the JMSMessageID if using JMS, or some

unique reference number within the message.

Here's another example:

resultEndpoint.expectedBodiesReceived("firstMessageBody","secondMessageBody",

"thirdMessageBody");

Adding expectations to specic messages

In addition, you can use the message(int messageIndex) method to add

assertions about a specic message that is received.

For example, to add expectations of the headers or body of the rst

message (using zero-based indexing like java.util.List), you can use the

following code:

resultEndpoint.message(0).header("foo").isEqualTo("bar");

There are some examples of the Mock endpoint in use in the camel-core

processor tests.

Mocking existing endpoints

Available as of Camel 2.7

Camel now allows you to automatic mock existing endpoints in your Camel

routes.

Suppose you have the given route below:

811 CHAPTER 11 - COMPONENT APPENDIX

How it works

Important: The endpoints are still in action, what happens is that a

Mock endpoint is injected and receives the message rst, it then

delegate the message to the target endpoint. You can view this as a

kind of intercept and delegate or endpoint listener.

Listing 79. Route

@Override

protected RouteBuilder createRouteBuilder() throws Exception {

return new RouteBuilder() {

@Override

public void configure() throws Exception {

from("direct:start").to("direct:foo").to("log:foo").to("mock:result");

from("direct:foo").transform(constant("Bye World"));

}

};

}

You can then use the adviceWith feature in Camel to mock all the endpoints

in a given route from your unit test, as shown below:

Listing 80. adviceWith mocking all endpoints

public void testAdvisedMockEndpoints() throws Exception {

// advice the first route using the inlined AdviceWith route builder

// which has extended capabilities than the regular route builder

context.getRouteDefinitions().get(0).adviceWith(context, new

AdviceWithRouteBuilder() {

@Override

public void configure() throws Exception {

// mock all endpoints

mockEndpoints();

}

});

getMockEndpoint("mock:direct:start").expectedBodiesReceived("Hello World");

getMockEndpoint("mock:direct:foo").expectedBodiesReceived("Hello World");

getMockEndpoint("mock:log:foo").expectedBodiesReceived("Bye World");

getMockEndpoint("mock:result").expectedBodiesReceived("Bye World");

template.sendBody("direct:start","Hello World");

assertMockEndpointsSatisfied();

// additional test to ensure correct endpoints in registry

assertNotNull(context.hasEndpoint("direct:start"));

assertNotNull(context.hasEndpoint("direct:foo"));

assertNotNull(context.hasEndpoint("log:foo"));

CHAPTER 11 - COMPONENT APPENDIX 812

assertNotNull(context.hasEndpoint("mock:result"));

// all the endpoints was mocked

assertNotNull(context.hasEndpoint("mock:direct:start"));

assertNotNull(context.hasEndpoint("mock:direct:foo"));

assertNotNull(context.hasEndpoint("mock:log:foo"));

}

Notice that the mock endpoints is given the uri mock:<endpoint>, for

example mock:direct:foo. Camel logs at INFO level the endpoints being

mocked:

INFO Adviced endpoint [direct://foo] with mock endpoint [mock:direct:foo]

Its also possible to only mock certain endpoints using a pattern. For example

to mock all log endpoints you do as shown:

Listing 81. adviceWith mocking only log endpoints using a pattern

public void testAdvisedMockEndpointsWithPattern() throws Exception {

// advice the first route using the inlined AdviceWith route builder

// which has extended capabilities than the regular route builder

context.getRouteDefinitions().get(0).adviceWith(context, new

AdviceWithRouteBuilder() {

@Override

public void configure() throws Exception {

// mock only log endpoints

mockEndpoints("log*");

}

});

// now we can refer to log:foo as a mock and set our expectations

getMockEndpoint("mock:log:foo").expectedBodiesReceived("Bye World");

getMockEndpoint("mock:result").expectedBodiesReceived("Bye World");

template.sendBody("direct:start","Hello World");

assertMockEndpointsSatisfied();

// additional test to ensure correct endpoints in registry

assertNotNull(context.hasEndpoint("direct:start"));

assertNotNull(context.hasEndpoint("direct:foo"));

assertNotNull(context.hasEndpoint("log:foo"));

assertNotNull(context.hasEndpoint("mock:result"));

// only the log:foo endpoint was mocked

assertNotNull(context.hasEndpoint("mock:log:foo"));

assertNull(context.hasEndpoint("mock:direct:start"));

assertNull(context.hasEndpoint("mock:direct:foo"));

}

813 CHAPTER 11 - COMPONENT APPENDIX

Mocked endpoints are without parameters

Endpoints which are mocked will have their parameters stripped o.

For example the endpoint "log:foo?showAll=true" will be mocked to

the following endpoint "mock:log:foo". Notice the parameters has

been removed.

The pattern supported can be a wildcard or a regular expression. See more

details about this at Intercept as its the same matching function used by

Camel.

Mocking existing endpoints using the camel-test

component

Instead of using the adviceWith to instruct Camel to mock endpoints, you

can easily enable this behavior when using the camel-test Test Kit.

The same route can be tested as follows. Notice that we return "*" from the

isMockEndpoints method, which tells Camel to mock all endpoints.

If you only want to mock all log endpoints you can return "log*" instead.

Listing 82. isMockEndpoints using camel-test kit

public class IsMockEndpointsJUnit4Test extends CamelTestSupport {

@Override

public String isMockEndpoints() {

// override this method and return the pattern for which endpoints to mock.

// use * to indicate all

return "*";

}

@Test

public void testMockAllEndpoints() throws Exception {

// notice we have automatic mocked all endpoints and the name of the

endpoints is "mock:uri"

getMockEndpoint("mock:direct:start").expectedBodiesReceived("Hello World");

getMockEndpoint("mock:direct:foo").expectedBodiesReceived("Hello World");

getMockEndpoint("mock:log:foo").expectedBodiesReceived("Bye World");

getMockEndpoint("mock:result").expectedBodiesReceived("Bye World");

template.sendBody("direct:start","Hello World");

assertMockEndpointsSatisfied();

// additional test to ensure correct endpoints in registry

assertNotNull(context.hasEndpoint("direct:start"));

assertNotNull(context.hasEndpoint("direct:foo"));

CHAPTER 11 - COMPONENT APPENDIX 814

Mind that mocking endpoints causes the messages to be copied

when they arrive on the mock.

That means Camel will use more memory. This may not be suitable

when you send in a lot of messages.

assertNotNull(context.hasEndpoint("log:foo"));

assertNotNull(context.hasEndpoint("mock:result"));

// all the endpoints was mocked

assertNotNull(context.hasEndpoint("mock:direct:start"));

assertNotNull(context.hasEndpoint("mock:direct:foo"));

assertNotNull(context.hasEndpoint("mock:log:foo"));

}

@Override

protected RouteBuilder createRouteBuilder() throws Exception {

return new RouteBuilder() {

@Override

public void configure() throws Exception {

from("direct:start").to("direct:foo").to("log:foo").to("mock:result");

from("direct:foo").transform(constant("Bye World"));

}

};

}

Mocking existing endpoints with XML DSL

If you do not use the camel-test component for unit testing (as shown

above) you can use a dierent approach when using XML les for routes.

The solution is to create a new XML le used by the unit test and then

include the intended XML le which has the route you want to test.

Suppose we have the route in the camel-route.xml le:

Listing 83. camel-route.xml

<route>

</route>

815 CHAPTER 11 - COMPONENT APPENDIX

<route>

<constant>Bye World</constant>

</transform>

</route>

</camelContext>

Then we create a new XML le as follows, where we include the camel-

route.xml le and dene a spring bean with the class

org.apache.camel.impl.InterceptSendToMockEndpointStrategy which

tells Camel to mock all endpoints:

Listing 84. test-camel-route.xml

<bean id="mockAllEndpoints"

class="org.apache.camel.impl.InterceptSendToMockEndpointStrategy"/>

Then in your unit test you load the new XML le (test-camel-route.xml)

instead of camel-route.xml.

To only mock all Log endpoints you can dene the pattern in the

constructor for the bean:

<bean id="mockAllEndpoints"

class="org.apache.camel.impl.InterceptSendToMockEndpointStrategy">

<constructor-arg index="0" value="log*"/>

</bean>

Testing with arrival times

Available as of Camel 2.7

The Mock endpoint stores the arrival time of the message as a property on

the Exchange.

Date time = exchange.getProperty(Exchange.RECEIVED_TIMESTAMP, Date.class);

You can use this information to know when the message arrived on the mock.

But it also provides foundation to know the time interval between the

previous and next message arrived on the mock. You can use this to set

expectations using the arrives DSL on the Mock endpoint.

CHAPTER 11 - COMPONENT APPENDIX 816

For example to say that the rst message should arrive between 0-2

seconds before the next you can do:

mock.message(0).arrives().noLaterThan(2).seconds().beforeNext();

You can also dene this as that 2nd message (0 index based) should arrive

no later than 0-2 seconds after the previous:

mock.message(1).arrives().noLaterThan(2).seconds().afterPrevious();

You can also use between to set a lower bound. For example suppose that it

should be between 1-4 seconds:

mock.message(1).arrives().between(1, 4).seconds().afterPrevious();

You can also set the expectation on all messages, for example to say that the

gap between them should be at most 1 second:

mock.allMessages().arrives().noLaterThan(1).seconds().beforeNext();

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

• Spring Testing

• Testing

MSV COMPONENT

The MSV component performs XML validation of the message body using the

MSV Library and any of the supported XML schema languages, such as XML

Schema or RelaxNG XML Syntax.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-msv</artifactId>

817 CHAPTER 11 - COMPONENT APPENDIX

time units

In the example above we use seconds as the time unit, but Camel

oers milliseconds, and minutes as well.

</dependency>

Note that the Jing component also supports RelaxNG Compact Syntax

URI format

msv:someLocalOrRemoteResource[?options]

Where someLocalOrRemoteResource is some URL to a local resource on

the classpath or a full URL to a remote resource or resource on the le

system. For example

msv:org/foo/bar.rng

msv:file:../foo/bar.rng

msv:http://acme.com/cheese.rng

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Option Default Description

useDom true Camel 2.0: Whether DOMSource/DOMResult or SaxSource/SaxResult should be used by the validator. Note:

DOM must be used by the MSV component.

Example

The following example shows how to congure a route from endpoint

direct:start which then goes to one of two endpoints, either mock:valid or

mock:invalid based on whether or not the XML matches the given RelaxNG

XML Schema (which is supplied on the classpath).

<route>

CHAPTER 11 - COMPONENT APPENDIX 818

<doTry>

<exception>org.apache.camel.ValidationException</exception>

</doCatch>

</doFinally>

</doTry>

</route>

</camelContext>

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

MYBATIS

Available as of Camel 2.7

The mybatis: component allows you to query, poll, insert, update and

delete data in a relational database using MyBatis.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-mybatis</artifactId>

</dependency>

URI format

mybatis:statementName[?options]

819 CHAPTER 11 - COMPONENT APPENDIX

Where statementName is the statement name in the MyBatis XML mapping

le which maps to the query, insert, update or delete operation you wish to

evaluate.

You can append query options to the URI in the following format,

?option=value&option=value&...

This component will by default load the MyBatis SqlMapCong le from the

root of the classpath and expected named as SqlMapConfig.xml.

If the le is located in another location, you would have to congure the

configurationUri option on the MyBatisComponent component.

Options

Option Type Default Description

consumer.onConsume String null

Statements to run after consuming. Can be used, for example, to update

rows after they have been consumed and processed in Camel. See

sample later. Multiple statements can be separated with comma.

consumer.useIterator boolean true If true each row returned when polling will be processed individually. If

false the entire List of data is set as the IN body.

consumer.routeEmptyResultSet boolean false Sets whether empty result set should be routed or not. By default, empty

result sets are not routed.

statementType StatementType null

Mandatory to specify for producer to control which kind of operation to

invoke. The enum values are: SelectOne,SelectList,Insert,Update,

Delete.

maxMessagesPerPoll int 0

An integer to dene a maximum messages to gather per poll. By default,

no maximum is set. Can be used to set a limit of e.g. 1000 to avoid when

starting up the server that there are thousands of les. Set a value of 0 or

negative to disabled it.

Message Headers

Camel will populate the result message, either IN or OUT with a header with

the statement used:

Header Type Description

CamelMyBatisStatementName String The statementName used (for example: insertAccount).

CamelMyBatisResult Object The response returned from MtBatis in any of the operations. For instance an INSERT could return

the auto-generated key, or number of rows etc.

Message Body

The response from MyBatis will only be set as body if it's a SELECT

statement. That means, for example, for INSERT statements Camel will not

replace the body. This allows you to continue routing and keep the original

body. The response from MyBatis is always stored in the header with the key

CamelMyBatisResult.

CHAPTER 11 - COMPONENT APPENDIX 820

Samples

For example if you wish to consume beans from a JMS queue and insert them

into a database you could do the following:

from("activemq:queue:newAccount").

to("mybatis:insertAccount?statementType=Insert");

Notice we have to specify the statementType, as we need to instruct Camel

which kind of operation to invoke.

Where insertAccount is the MyBatis ID in the SQL mapping le:

insert into ACCOUNT (

ACC_ID,

ACC_FIRST_NAME,

ACC_LAST_NAME,

ACC_EMAIL

)

values (

#{id}, #{firstName}, #{lastName}, #{emailAddress}

)

</insert>

Using StatementType for better control of MyBatis

When routing to an MyBatis endpoint you want more ne grained control so

you can control whether the SQL statement to be executed is a SELEECT,

UPDATE,DELETE or INSERT etc. So for instance if we want to route to an

MyBatis endpoint in which the IN body contains parameters to a SELECT

statement we can do:

from("direct:start")

.to("mybatis:selectAccountById?statementType=SelectOne")

.to("mock:result");

In the code above we can invoke the MyBatis statement selectAccountById

and the IN body should contain the account id we want to retrieve, such as

an Integer type.

We can do the same for some of the other operations, such as

SelectList:

821 CHAPTER 11 - COMPONENT APPENDIX

from("direct:start")

.to("mybatis:selectAllAccounts?statementType=SelectList")

.to("mock:result");

And the same for UPDATE, where we can send an Account object as IN body

to MyBatis:

from("direct:start")

.to("mybatis:updateAccount?statementType=Update")

.to("mock:result");

Scheduled polling example

Since this component does not support scheduled polling, you need to use

another mechanism for triggering the scheduled polls, such as the Timer or

Quartz components.

In the sample below we poll the database, every 30 seconds using the

Timer component and send the data to the JMS queue:

from("timer://pollTheDatabase?delay=30000").to("mbatis:selectAllAccounts").to("activemq:queue:allAccounts");

And the MyBatis SQL mapping le used:

select * from ACCOUNT

</select>

Using onConsume

This component supports executing statements after data have been

consumed and processed by Camel. This allows you to do post updates in the

database. Notice all statements must be UPDATE statements. Camel supports

executing multiple statements whose name should be separated by comma.

The route below illustrates we execute the consumeAccount statement

data is processed. This allows us to change the status of the row in the

database to processed, so we avoid consuming it twice or more.

from("mybatis:selectUnprocessedAccounts?consumer.onConsume=consumeAccount").to("mock:results");

And the statements in the sqlmap le:

CHAPTER 11 - COMPONENT APPENDIX 822

select * from ACCOUNT where PROCESSED = false

</select>

update ACCOUNT set PROCESSED = true where ACC_ID = #{id}

</update>

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

NAGIOS

Available as of Camel 2.3

The Nagios component allows you to send passive checks to Nagios.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-nagios</artifactId>

</dependency>

URI format

nagios://host[:port][?Options]

Camel provides two abilities with the Nagios component. You can send

passive check messages by sending a message to its endpoint.

Camel also provides a EventNotifer which allows you to send notications to

Nagios.

823 CHAPTER 11 - COMPONENT APPENDIX

Options

Name Default

Value Description

host none This is the address of the Nagios host where checks should be send.

port The port number of the host.

password Password to be authenticated when sending checks to Nagios.

connectionTimeout 5000 Connection timeout in millis.

timeout 5000 Sending timeout in millis.

nagiosSettings To use an already congured com.googlecode.jsendnsca.core.NagiosSettings object. Then any of

the other options are not in use, if using this.

sendSync true Whether or not to use synchronous when sending a passive check. Setting it to false will allow Camel to

continue routing the message and the passive check message will be send asynchronously.

encryptionMethod No Camel 2.9: To specify an encryption method. Possible values: No,Xor, or TripleDes.

Headers

Name Description

CamelNagiosHostName This is the address of the Nagios host where checks should be send. This header will override any existing

hostname congured on the endpoint.

CamelNagiosLevel This is the severity level. You can use values CRITICAL, WARNING, OK. Camel will by default use OK.

CamelNagiosServiceName The servie name. Will default use the CamelContext name.

Sending message examples

You can send a message to Nagios where the message payload contains the

message. By default it will be OK level and use the CamelContext name as

the service name. You can overrule these values using headers as shown

above.

For example we send the Hello Nagios message to Nagios as follows:

template.sendBody("direct:start","Hello Nagios");

from("direct:start").to("nagios:127.0.0.1:5667?password=secret").to("mock:result");

To send a CRITICAL message you can send the headers such as:

Map headers = new HashMap();

headers.put(NagiosConstants.LEVEL, "CRITICAL");

headers.put(NagiosConstants.HOST_NAME, "myHost");

headers.put(NagiosConstants.SERVICE_NAME, "myService");

template.sendBodyAndHeaders("direct:start","Hello Nagios", headers);

CHAPTER 11 - COMPONENT APPENDIX 824

Using NagiosEventNotifer

The Nagios component also provides an EventNotifer which you can use to

send events to Nagios. For example we can enable this from Java as follows:

NagiosEventNotifier notifier = new NagiosEventNotifier();

notifier.getConfiguration().setHost("localhost");

notifier.getConfiguration().setPort(5667);

notifier.getConfiguration().setPassword("password");

CamelContext context = ...

context.getManagementStrategy().addEventNotifier(notifier);

return context;

In Spring XML its just a matter of dening a Spring bean with the type

EventNotifier and Camel will pick it up as documented here: Advanced

conguration of CamelContext using Spring.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

NETTY COMPONENT

Available as of Camel 2.3

The netty component in Camel is a socket communication component,

based on the JBoss Netty community oering (available under an Apache 2.0

license).

Netty is a NIO client server framework which enables quick and easy

development of network applications such as protocol servers and clients.

Netty greatly simplies and streamlines network programming such as TCP

and UDP socket server.

This camel component supports both producer and consumer endpoints.

The netty component has several options and allows ne-grained control

of a number of TCP/UDP communication parameters (buer sizes, keepAlives,

tcpNoDelay etc) and facilitates both In-Only and In-Out communication on a

Camel route.

Maven users will need to add the following dependency to their pom.xml

for this component:

825 CHAPTER 11 - COMPONENT APPENDIX

<groupId>org.apache.camel</groupId>

<artifactId>camel-netty</artifactId>

</dependency>

URI format

The URI scheme for a netty component is as follows

netty:tcp://localhost:99999[?options]

netty:udp://remotehost:99999/[?options]

This component supports producer and consumer endpoints for both TCP and

UDP.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Default

Value Description

keepAlive true Setting to ensure socket is not closed due to inactivity

tcpNoDelay true Setting to improve TCP protocol performance

broadcast false Setting to choose Multicast over UDP

connectTimeout 10000 Time to wait for a socket connection to be available. Value is in millis.

reuseAddress true Setting to facilitate socket multiplexing

sync true Setting to set endpoint as one-way or request-response

ssl false Setting to specify whether SSL encryption is applied to this endpoint

sendBufferSize 65536 bytes The TCP/UDP buer sizes to be used during outbound communication. Size is bytes.

receiveBufferSize 65536 bytes The TCP/UDP buer sizes to be used during inbound communication. Size is bytes.

corePoolSize 10 The number of allocated threads at component startup. Defaults to 10

maxPoolSize 100 The maximum number of threads that may be allocated to this endpoint. Defaults to 100

disconnect false Whether or not to disconnect(close) from Netty Channel right after use. Can be used for both

consumer and producer.

lazyChannelCreation true Channels can be lazily created to avoid exceptions, if the remote server is not up and running

when the Camel producer is started.

transferExchange false

Only used for TCP. You can transfer the exchange over the wire instead of just the body. The

following elds are transferred: In body, Out body, fault body, In headers, Out headers, fault

headers, exchange properties, exchange exception. This requires that the objects are serializable.

Camel will exclude any non-serializable objects and log it at WARN level.

disconnectOnNoReply true If sync is enabled then this option dictates NettyConsumer if it should disconnect where there is

no reply to send back.

noReplyLogLevel WARN If sync is enabled this option dictates NettyConsumer which logging level to use when logging a

there is no reply to send back. Values are: FATAL, ERROR, INFO, DEBUG, OFF.

allowDefaultCodec true

Camel 2.4: The netty component installs a default codec if both, encoder/deocder is null and

textline is false. Setting allowDefaultCodec to false prevents the netty component from installing

a default codec as the rst element in the lter chain.

CHAPTER 11 - COMPONENT APPENDIX 826

textline false Camel 2.4: Only used for TCP. If no codec is specied, you can use this ag to indicate a text line

based codec; if not specied or the value is false, then Object Serialization is assumed over TCP.

delimiter LINE Camel 2.4: The delimiter to use for the textline codec. Possible values are LINE and NULL.

decoderMaxLineLength 1024 Camel 2.4: The max line length to use for the textline codec.

autoAppendDelimiter true Camel 2.4: Whether or not to auto append missing end delimiter when sending using the

textline codec.

encoding null Camel 2.4: The encoding (a charset name) to use for the textline codec. If not provided, Camel

will use the JVM default Charset.

workerCount null

Camel 2.9: When netty works on nio mode, it uses default workerCount parameter from Netty,

which is cpu_core_threads*2. User can use this operation to override the default workerCount

from Netty

sslContextParametersRef null

Camel 2.9: Reference to a org.apache.camel.util.jsse.SSLContextParameters in the

Registry. This reference overrides any congured SSLContextParameters at the component

level. See Using the JSSE Conguration Utility.

Registry based Options

Codec Handlers and SSL Keystores can be enlisted in the Registry, such as in

the Spring XML le.

The values that could be passed in, are the following:

Name Description

passphrase password setting to use in order to encrypt/decrypt payloads sent using SSH

keyStoreFormat keystore format to be used for payload encryption. Defaults to "JKS" if not set

securityProvider Security provider to be used for payload encryption. Defaults to "SunX509" if not set.

keyStoreFile Client side certicate keystore to be used for encryption

trustStoreFile Server side certicate keystore to be used for encryption

sslHandler Reference to a class that could be used to return an SSL Handler

encoder A custom Handler class that can be used to perform special marshalling of outbound payloads. Must override

org.jboss.netty.channel.ChannelDownStreamHandler.

encorders A list of encoder to be used. You can use a String which have values separated by comma, and have the values be looked

up in the Registry. Just remember to prex the value with # so Camel knows it should lookup.

decoder A custom Handler class that can be used to perform special marshalling of inbound payloads. Must override

org.jboss.netty.channel.ChannelUpStreamHandler.

decoders A list of decorder to be used. You can use a String which have values separated by comma, and have the values be looked

up in the Registry. Just remember to prex the value with # so Camel knows it should lookup.

Sending Messages to/from a Netty endpoint

Netty Producer

In Producer mode, the component provides the ability to send payloads to a

socket endpoint

using either TCP or UDP protocols (with optional SSL support).

The producer mode supports both one-way and request-response based

operations.

827 CHAPTER 11 - COMPONENT APPENDIX

Netty Consumer

In Consumer mode, the component provides the ability to:

▪ listen on a specied socket using either TCP or UDP protocols (with

optional SSL support),

▪ receive requests on the socket using text/xml, binary and serialized

object based payloads and

▪ send them along on a route as message exchanges.

The consumer mode supports both one-way and request-response based

operations.

Usage Samples

A UDP Netty endpoint using Request-Reply and

serialized object payload

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from("netty:udp://localhost:5155?sync=true")

.process(new Processor() {

public void process(Exchange exchange) throws Exception {

Poetry poetry = (Poetry) exchange.getIn().getBody();

poetry.setPoet("Dr. Sarojini Naidu");

exchange.getOut().setBody(poetry);

}

};

A TCP based Netty consumer endpoint using One-way

communication

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from("netty:tcp://localhost:5150")

.to("mock:result");

}

};

CHAPTER 11 - COMPONENT APPENDIX 828

An SSL/TCP based Netty consumer endpoint using

Request-Reply communication

Using the JSSE Conguration Utility

As of Camel 2.9, the Netty component supports SSL/TLS conguration

through the Camel JSSE Conguration Utility. This utility greatly decreases

the amount of component specic code you need to write and is congurable

at the endpoint and component levels. The following examples demonstrate

how to use the utility with the Netty component.

Programmatic conguration of the component

KeyStoreParameters ksp = new KeyStoreParameters();

ksp.setResource("/users/home/server/keystore.jks");

ksp.setPassword("keystorePassword");

KeyManagersParameters kmp = new KeyManagersParameters();

kmp.setKeyStore(ksp);

kmp.setKeyPassword("keyPassword");

SSLContextParameters scp = new SSLContextParameters();

scp.setKeyManagers(kmp);

NettyComponent nettyComponent = getContext().getComponent("netty",

NettyComponent.class);

nettyComponent.setSslContextParameters(scp);

Spring DSL based conguration of endpoint

...

<camel:sslContextParameters

id="sslContextParameters">

<camel:keyManagers

keyPassword="keyPassword">

<camel:keyStore

resource="/users/home/server/keystore.jks"

password="keystorePassword"/>

</camel:keyManagers>

</camel:sslContextParameters>...

...

<to

uri="netty:tcp://localhost:5150?sync=true&ssl=true&sslContextParameters=#sslContextParameters"/>

...

829 CHAPTER 11 - COMPONENT APPENDIX

Using Basic SSL/TLS conguration on the Jetty Component

JndiRegistry registry = new JndiRegistry(createJndiContext());

registry.bind("password","changeit");

registry.bind("ksf",new File("src/test/resources/keystore.jks"));

registry.bind("tsf",new File("src/test/resources/keystore.jks"));

context.createRegistry(registry);

context.addRoutes(new RouteBuilder() {

public void configure() {

String netty_ssl_endpoint =

"netty:tcp://localhost:5150?sync=true&ssl=true&passphrase=#password"

+"&keyStoreFile=#ksf&trustStoreFile=#tsf";

String return_string =

"When You Go Home, Tell Them Of Us And Say,"

+"For Your Tomorrow, We Gave Our Today.";

from(netty_ssl_endpoint)

.process(new Processor() {

public void process(Exchange exchange) throws Exception {

exchange.getOut().setBody(return_string);

}

});

Using Multiple Codecs

In certain cases it may be necessary to add chains of encoders and decoders

to the netty pipeline. To add multpile codecs to a camel netty endpoint the

'encoders' and 'decoders' uri parameters should be used. Like the 'encoder'

and 'decoder' parameters they are used to supply references (to lists of

ChannelUpstreamHandlers and ChannelDownstreamHandlers) that should be

added to the pipeline. Note that if encoders is specied then the encoder

param will be ignored, similarly for decoders and the decoder param.

The lists of codecs need to be added to the Camel's registry so they can

be resolved when the endpoint is created.

LengthFieldBasedFrameDecoder lengthDecoder = new

LengthFieldBasedFrameDecoder(1048576, 0, 4, 0, 4);

StringDecoder stringDecoder = new StringDecoder();

registry.bind("length-decoder", lengthDecoder);

registry.bind("string-decoder", stringDecoder);

LengthFieldPrepender lengthEncoder = new LengthFieldPrepender(4);

StringEncoder stringEncoder = new StringEncoder();

registry.bind("length-encoder", lengthEncoder);

registry.bind("string-encoder", stringEncoder);

CHAPTER 11 - COMPONENT APPENDIX 830

List<ChannelUpstreamHandler> decoders = new ArrayList<ChannelUpstreamHandler>();

decoders.add(lengthDecoder);

decoders.add(stringDecoder);

List<ChannelDownstreamHandler> encoders = new ArrayList<ChannelDownstreamHandler>();

encoders.add(lengthEncoder);

encoders.add(stringEncoder);

registry.bind("encoders", encoders);

registry.bind("decoders", decoders);

Spring's native collections support can be used to specify the codec lists in

an application context

<util:list id="decoders" list-class="java.util.LinkedList">

<bean

class="org.jboss.netty.handler.codec.frame.LengthFieldBasedFrameDecoder">

<constructor-arg value="1048576"/>

<constructor-arg value="0"/>

<constructor-arg value="4"/>

<constructor-arg value="0"/>

<constructor-arg value="4"/>

</bean>

</util:list>

<util:list id="encoders" list-class="java.util.LinkedList">

<constructor-arg value="4"/>

</bean>

</util:list>

<bean id="length-encoder"

class="org.jboss.netty.handler.codec.frame.LengthFieldPrepender">

<constructor-arg value="4"/>

</bean>

<bean id="string-encoder"

class="org.jboss.netty.handler.codec.string.StringEncoder"/>

<bean id="length-decoder"

class="org.jboss.netty.handler.codec.frame.LengthFieldBasedFrameDecoder">

<constructor-arg value="1048576"/>

<constructor-arg value="0"/>

<constructor-arg value="4"/>

<constructor-arg value="0"/>

<constructor-arg value="4"/>

</bean>

<bean id="string-decoder"

class="org.jboss.netty.handler.codec.string.StringDecoder"/>

831 CHAPTER 11 - COMPONENT APPENDIX

</beans>

The bean names can then be used in netty endpoint denitions either as a

comma separated list or contained in a List e.g.

from("direct:multiple-codec").to("netty:tcp://localhost:{{port}}?encoders=#encoders&sync=false");

from("netty:tcp://localhost:{{port}}?decoders=#length-decoder,#string-decoder&sync=false").to("mock:multiple-codec");

}

};

}

or via spring.

<camelContext id="multiple-netty-codecs-context" xmlns="http://camel.apache.org/

schema/spring">

<route>

</route>

<route>

<from

uri="netty:tcp://localhost:5150?decoders=#length-decoder,#string-decoder&sync=false"/>

</route>

</camelContext>

Closing Channel When Complete

When acting as a server you sometimes want to close the channel when, for

example, a client conversion is nished.

You can do this by simply setting the endpoint option disconnect=true.

However you can also instruct Camel on a per message basis as follows.

To instruct Camel to close the channel, you should add a header with the key

CamelNettyCloseChannelWhenComplete set to a boolean true value.

For instance, the example below will close the channel after it has written the

bye message back to the client:

from("netty:tcp://localhost:8080").process(new Processor() {

public void process(Exchange exchange) throws Exception {

String body = exchange.getIn().getBody(String.class);

exchange.getOut().setBody("Bye " + body);

CHAPTER 11 - COMPONENT APPENDIX 832

// some condition which determines if we should close

if (close) {

exchange.getOut().setHeader(NettyConstants.NETTY_CLOSE_CHANNEL_WHEN_COMPLETE, true);

}

});

Adding custom channel pipeline factories to gain complete control

over a created pipeline

Available as of Camel 2.5

Custom channel pipelines provide complete control to the user over the

handler/interceptor chain by inserting custom handler(s), encoder(s) &

decoders without having to specify them in the Netty Endpoint URL in a very

simple way.

In order to add a custom pipeline, a custom channel pipeline factory must

be created and registered with the context via the context registry

(JNDIRegistry,or the camel-spring ApplicationContextRegistry etc).

A custom pipeline factory must be constructed as follows

• A Producer linked channel pipeline factory must extend the abstract

class ClientPipelineFactory.

• A Consumer linked channel pipeline factory must extend the abstract

class ServerPipelineFactory.

• The classes can optionally override the getPipeline() method in order

to insert custom handler(s), encoder(s) and decoder(s). Not

overriding the getPipeline() method creates a pipeline with no

handlers, encoders or decoders wired to the pipeline.

The example below shows how ServerChannel Pipeline factory may be

created

public class SampleServerChannelPipelineFactory extends ServerPipelineFactory {

private int maxLineSize = 1024;

private boolean invoked;

public ChannelPipeline getPipeline() throws Exception {

invoked = true;

ChannelPipeline channelPipeline = Channels.pipeline();

channelPipeline.addLast("encoder-SD",new StringEncoder(CharsetUtil.UTF_8));

channelPipeline.addLast("decoder-DELIM",new

DelimiterBasedFrameDecoder(maxLineSize, true, Delimiters.lineDelimiter()));

channelPipeline.addLast("decoder-SD",new StringDecoder(CharsetUtil.UTF_8));

channelPipeline.addLast("handler",new ServerChannelHandler(consumer));

833 CHAPTER 11 - COMPONENT APPENDIX

return channelPipeline;

}

public boolean isfactoryInvoked() {

return invoked;

}

The custom channel pipeline factory can then be added to the registry and

instantiated/utilized on a camel route in the following way

Registry registry = camelContext.getRegistry();

serverPipelineFactory = new TestServerChannelPipelineFactory();

registry.bind("spf", serverPipelineFactory);

context.addRoutes(new RouteBuilder() {

public void configure() {

String netty_ssl_endpoint =

"netty:tcp://localhost:5150?serverPipelineFactory=#spf"

String return_string =

"When You Go Home, Tell Them Of Us And Say,"

+"For Your Tomorrow, We Gave Our Today.";

from(netty_ssl_endpoint)

.process(new Processor() {

public void process(Exchange exchange) throws Exception {

exchange.getOut().setBody(return_string);

}

});

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ MINA

NMR COMPONENT

The nmr component is an adapter to the Normalized Message Router (NMR)

in ServiceMix, which is intended for use by Camel applications deployed

directly into the OSGi container. You can exchange objects with NMR and not

only XML like this is the case with the JBI specication. The interest of this

CHAPTER 11 - COMPONENT APPENDIX 834

component is that you can interconnect camel routes deployed in dierent

OSGI bundles.

By contrast, the JBI component is intended for use by Camel applications

deployed into the ServiceMix JBI container.

Installing

The NMR component is provided with Apache ServiceMix. It is not distributed

with Camel. To install the NMR component in ServiceMix, enter the following

command in the ServiceMix console window:

features install nmr

You also need to instantiate the NMR component. You can do this by editing

your Spring conguration le, META-INF/spring/*.xml, and adding the

following bean instance:

...

<osgi:reference interface="org.apache.servicemix.nmr.api.NMR" />

</property>

</bean>

...

</beans>

NMR consumer and producer endpoints

The following code:

from("nmr:MyServiceEndpoint")

Automatically exposes a new endpoint to the bus with endpoint name

MyServiceEndpoint (see URI-format).

When an NMR endpoint appears at the end of a route, for example:

to("nmr:MyServiceEndpoint")

The messages sent by this producer endpoint are sent to the already

deployed JBI endpoint.

835 CHAPTER 11 - COMPONENT APPENDIX

URI format

nmr:endpointName

URI Options

Option Default

Value Description

runAsSubject false

Apache ServiceMix 4.4: When this is set to true on a consumer endpoint, the endpoint will be invoked on

behalf of the Subject that is set on the Exchange (i.e. the call to

Subject.getSubject(AccessControlContext) will return the Subject instance)

synchronous false When this is set to true on a consumer endpoint, an incoming, synchronous NMR Exchange will be handled on

the sender's thread instead of being handled on a new thread of the NMR endpoint's thread pool

timeout 0

Apache ServiceMix 4.4: When this is set to a value greater than 0, the producer endpoint will timeout if it

doesn't receive a response from the NMR within the given timeout period (in milliseconds). Conguring a

timeout value will switch to using synchronous interactions with the NMR instead of the usual asynchronous

messaging.

Examples

Consumer

from("nmr:MyServiceEndpoint")// consume nmr exchanges asynchronously

from("nmr:MyServiceEndpoint?synchronous=true").to() // consume nmr exchanges

synchronously and use the same thread as defined by NMR ThreadPool

Producer

from()...to("nmr:MyServiceEndpoint")// produce nmr exchanges asynchronously

from()...to("nmr:MyServiceEndpoint?timeout=10000")// produce nmr exchanges

synchronously and wait till 10s to receive response

Using Stream bodies

If you are using a stream type as the message body, you should be aware

that a stream is only capable of being read once. So if you enable DEBUG

logging, the body is usually logged and thus read. To deal with this, Camel

has a streamCaching option that can cache the stream, enabling you to read

it multiple times.

from("nmr:MyEndpoint").streamCaching().to("xslt:transform.xsl","bean:doSomething");

From Camel 1.5 onwards, the stream caching is default enabled, so it is not

necessary to set the streamCaching() option.

CHAPTER 11 - COMPONENT APPENDIX 836

In Camel 2.0 we store big input streams (by default, over 64K) in a temp le

using CachedOutputStream. When you close the input stream, the temp le

will be deleted.

Testing

NMR camel routes can be tested using the camel unit test approach even if

they will be deployed next in dierent bundles on an OSGI runtime. With this

aim in view, you will extend the ServiceMixNMR Mock class

org.apache.servicemix.camel.nmr.AbstractComponentTest which will

create a NMR bus, register the Camel NMR Component and the endpoints

dened into the Camel routes.

public class ExchangeUsingNMRTest extends AbstractComponentTest {

@Test

public void testProcessing() throws InterruptedException {

MockEndpoint mock = getMockEndpoint("mock:simple");

mock.expectedBodiesReceived("Simple message body");

template.sendBody("direct:simple","Simple message body");

assertMockEndpointsSatisfied();

}

@Override

protected RouteBuilder createRouteBuilder() throws Exception {

return new RouteBuilder() {

@Override

public void configure() throws Exception {

from("direct:simple").to("nmr:simple");

from("nmr:simple?synchronous=true").to("mock:simple");

}

};

}

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

837 CHAPTER 11 - COMPONENT APPENDIX

QUARTZ COMPONENT

The quartz: component provides a scheduled delivery of messages using

the Quartz scheduler.

Each endpoint represents a dierent timer (in Quartz terms, a Trigger and

JobDetail).

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-quartz</artifactId>

</dependency>

URI format

quartz://timerName?options

quartz://groupName/timerName?options

quartz://groupName/timerName/cronExpression (@deprecated)

quartz://groupName/timerName/?cron=expression (Camel 2.0)

quartz://timerName?cron=expression (Camel 2.0)

The component uses either a CronTrigger or a SimpleTrigger. If no cron

expression is provided, the component uses a simple trigger. If no groupName

is provided, the quartz component uses the Camel group name.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Parameter Default Description

cron None Species a cron expression (not compatible with the trigger.* or job.* options).

trigger.repeatCount 0 SimpleTrigger: How many times should the timer repeat?

trigger.repeatInterval 0 SimpleTrigger: The amount of time in milliseconds between repeated triggers.

job.name null Sets the job name.

job.XXX null Sets the job option with the XXX setter name.

trigger.XXX null Sets the trigger option with the XXX setter name.

stateful false Uses a Quartz StatefulJob instead of the default job.

fireNow false New to Camel 2.2.0, if it is true will re the trigger when the route is start when using

SimpleTrigger.

For example, the following routing rule will re two timer events to the

mock:results endpoint:

CHAPTER 11 - COMPONENT APPENDIX 838

Using cron expressions

Conguring the cron expression in Camel 1.x is based on path

separators. We changed this to an URI option in Camel 2.0, allowing

a more elegant conguration.

Also it is not possible to use the /cron special character (for

increments) in Camel 1.x, which Camel 2.0 also xes.

You may need to escape certain URI characters such as using ? in the

quartz cron expression.

from("quartz://myGroup/

myTimerName?trigger.repeatInterval=2&trigger.repeatCount=1").routeId("myRoute").to("mock:result");

When using a StatefulJob, the JobDataMap is re-persisted after every

execution of the job, thus preserving state for the next execution.

Conguring quartz.properties le

By default Quartz will look for a quartz.properties le in the root of the

classpath. If you are using WAR deployments this means just drop the

quartz.properties in WEB-INF/classes.

However the Camel Quartz component also allows you to congure

properties:

Parameter Default Type Description

properties null Properties Camel 2.4: You can congure a java.util.Propoperties instance.

propertiesFile null String Camel 2.4: File name of the properties to load from the classpath

To do this you can congure this in Spring XML as follows

</bean>

Starting the Quartz scheduler

Available as of Camel 2.4

The Quartz component oers an option to let the Quartz scheduler be

started delayed, or not auto started at all.

Parameter Default Type Description

startDelayedSeconds 0 int Camel 2.4: Seconds to wait before starting the quartz scheduler.

autoStartScheduler true boolean Camel 2.4: Whether or not the scheduler should be auto started.

839 CHAPTER 11 - COMPONENT APPENDIX

To do this you can congure this in Spring XML as follows

</bean>

Clustering

Available as of Camel 2.4

If you use Quartz in clustered mode, e.g. the JobStore is clustered. Then

from Camel 2.4 onwards the Quartz component will not pause/remove

triggers when a node is being stopped/shutdown. This allows the trigger to

keep running on the other nodes in the cluster.

Note: When running in clustered node no checking is done to ensure

unique job name/group for endpoints.

Message Headers

Camel adds the getters from the Quartz Execution Context as header values.

The following headers are added:

calendar,fireTime,jobDetail,jobInstance,jobRuntTime,

mergedJobDataMap,nextFireTime,previousFireTime,refireCount,

result,scheduledFireTime,scheduler,trigger,triggerName,

triggerGroup.

The fireTime header contains the java.util.Date of when the exchange

was red.

Using Cron Triggers

Available as of Camel 2.0

Quartz supports Cron-like expressions for specifying timers in a handy

format. You can use these expressions in the cron URI parameter; though to

preserve valid URI encoding we allow + to be used instead of spaces. Quartz

provides a little tutorial on how to use cron expressions.

For example, the following will re a message every ve minutes starting

at 12pm (noon) to 6pm on weekdays:

from("quartz://myGroup/myTimerName?cron=0+0/

5+12-18+?+*+MON-FRI").to("activemq:Totally.Rocks");

which is equivalent to using the cron expression

CHAPTER 11 - COMPONENT APPENDIX 840

0 0/5 12-18 ? * MON-FRI

The following table shows the URI character encodings we use to preserve

valid URI syntax:

URI Character Cron character

+Space

Using Cron Triggers in Camel 1.x

@deprecated

Quartz supports Cron-like expressions for specifying timers in a handy

format. You can use these expressions in the URI; though to preserve valid

URI encoding we allow /to be used instead of spaces and $to be used

instead of ?.

For example, the following endpoint URI will re a message at 12pm

(noon) every day

from("quartz://myGroup/myTimerName/0/0/12/*/*/$").to("activemq:Totally.Rocks");

which is equivalent to using the cron expression

0 0 12 * * ?

The following table shows the URI character encodings we use to preserve

valid URI syntax:

URI Character Cron character

/Space

$ ?

Specifying time zone

Available as of Camel 2.8.1

The Quartz Scheduler allows you to congure time zone per trigger. For

example to use a timezone of your country, then you can do as follows:

quartz://groupName/timerName?cron=0+0/5+12-18+?+*+MON-FRI&trigger.timeZone=Europe/

Stockholm

The timeZone value is the values accepted by java.util.TimeZone.

In Camel 2.8.0 or older versions you would have to provide your custom

String to java.util.TimeZone Type Converter to be able congure this

from the endpoint uri.

841 CHAPTER 11 - COMPONENT APPENDIX

From Camel 2.8.1 onwards we have included such a Type Converter in the

camel-core.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

• Timer

QUICKFIX/J COMPONENT

Available as of Camel 2.0

The quickx component adapts the QuickFIX/J FIX engine for using in

Camel . This component uses the standard Financial Interchange (FIX)

protocol for message transport.

Maven users will need to add the following dependency to their pom.xml for

this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-quickfix</artifactId>

</dependency>

URI format

quickfix:configFile[?sessionID=sessionID]

The congFile is the name of the QuickFIX/J conguration to use for the FIX

engine (located as a resource found in your classpath). The optional

sessionID identies a specic FIX session. The format of the sessionID is:

(BeginString):(SenderCompID)[/(SenderSubID)[/(SenderLocationID)]]->(TargetCompID)[/

(TargetSubID)[/(TargetLocationID)]]

Example URIs:

CHAPTER 11 - COMPONENT APPENDIX 842

Previous Versions

The quickx component was rewritten for Camel 2.5. For

information about using the quickx component prior to 2.5 see

the documentation section below.

quickfix:config.cfg

quickfix:config.cfg?sessionID=FIX.4.2:MyTradingCompany->SomeExchange

ENDPOINTS

FIX sessions are endpoints for the quickx component. An endpoint URI may

specify a single session or all sessions managed by a specic QuickFIX/J

engine. Typical applications will use only one FIX engine but advanced users

may create multiple FIX engines by referencing dierent conguration les in

quickx component endpoint URIs.

When a consumer does not include a session ID in the endpoint URI, it will

receive exchanges for all sessions managed by the FIX engine associated

with the conguration le specied in the URI. If a producer does not specify

a session in the endpoint URI then it must include the session-related elds

in the FIX message being sent. If a session is specied in the URI then the

component will automatically inject the session-related elds into the FIX

message.

Exchange Format

The exchange headers include information to help with exchange ltering,

routing and other processing. The following headers are available:

Header

Name Description

EventCategory One of AppMessageReceived,AppMessageSent,AdminMessageReceived,AdminMessageSent,SessionCreated,

SessionLogon,SessionLogoff. See the QuickfixjEventCategory enum.

SessionID The FIX message SessionID

MessageType The FIX MsgType tag value

DataDictionary Species a data dictionary to used for parsing an incoming message. Can be an instance of a data dictionary or a resource

path for a QuickFIX/J data dictionary le

The DataDictionary header is useful if string messages are being received

and need to be parsed in a route. QuickFIX/J requires a data dictionary to

parse certain types of messages (with repeating groups, for example). By

injecting a DataDictionary header in the route after receiving a message

string, the FIX engine can properly parse the data.

843 CHAPTER 11 - COMPONENT APPENDIX

QuickFIX/J Conguration Extensions

When using QuickFIX/J directly, one typically writes code to create instances

of logging adapters, message stores and communication connectors. The

quickx component will automatically create instances of these classes

based on information in the conguration le. It also provides defaults for

many of the common required settings and adds additional capabilities (like

the ability to activate JMX support).

The following sections describe how the quickx component processes

the QuickFIX/J conguration. For comprehensive information about QuickFIX/J

conguration, see the QFJ user manual.

Communication Connectors

When the component detects an initiator or acceptor session setting in the

QuickFIX/J conguration le it will automatically create the corresponding

initiator and/or acceptor connector. These settings can be in the default or in

a specic session section of the conguration le.

Session Setting Component Action

ConnectionType=initiator Create an initiator connector

ConnectionType=acceptor Create an acceptor connector

The threading model for the QuickFIX/J session connectors can also be

specied. These settings aect all sessions in the conguration le and must

be placed in the settings default section.

Default/Global Setting Component Action

ThreadModel=ThreadPerConnector Use SocketInitiator or SocketAcceptor (default)

ThreadModel=ThreadPerSession Use ThreadedSocketInitiator or ThreadedSocketAcceptor

Logging

The QuickFIX/J logger implementation can be specied by including the

following settings in the default section of the conguration le. The

ScreenLog is the default if none of the following settings are present in the

conguration. It's an error to include settings that imply more than one log

implementation. The log factory implementation can also be set directly on

the Quickx component. This will override any related values in the

QuickFIX/J settings le.

Default/Global Setting Component Action

ScreenLogShowEvents Use a ScreenLog

ScreenLogShowIncoming Use a ScreenLog

ScreenLogShowOutgoing Use a ScreenLog

SLF4J* Camel 2.6+. Use a SLF4JLog. Any of the SLF4J settings will cause this log to be used.

FileLogPath Use a FileLog

CHAPTER 11 - COMPONENT APPENDIX 844

JdbcDriver Use a JdbcLog

Message Store

The QuickFIX/J message store implementation can be specied by including

the following settings in the default section of the conguration le. The

MemoryStore is the default if none of the following settings are present in the

conguration. It's an error to include settings that imply more than one

message store implementation. The message store factory implementation

can also be set directly on the Quickx component. This will override any

related values in the QuickFIX/J settings le.

Default/Global Setting Component Action

JdbcDriver Use a JdbcStore

FileStorePath Use a FileStore

SleepycatDatabaseDir Use a SleepcatStore

Message Factory

A message factory is used to construct domain objects from raw FIX

messages. The default message factory is DefaultMessageFactory.

However, advanced applications may require a custom message factory. This

can be set on the QuickFIX/J component.

JMX

Default/Global Setting Component Action

UseJmx if Y, then enable QuickFIX/J JMX

Other Defaults

The component provides some default settings for what are normally

required settings in QuickFIX/J conguration les. SessionStartTime and

SessionEndTime default to "00:00:00", meaning the session will not be

automatically started and stopped. The HeartBtInt (heartbeat interval)

defaults to 30 seconds.

845 CHAPTER 11 - COMPONENT APPENDIX

Minimal Initiator Conguration Example

[SESSION]

ConnectionType=initiator

BeginString=FIX.4.4

SenderCompID=YOUR_SENDER

TargetCompID=YOUR_TARGET

Using the InOut Message Exchange Pattern

Camel 2.8+

Although the FIX protocol is event-driven and asynchronous, there are

specic pairs of messages

that represent a request-reply message exchange. To use an InOut exchange

pattern, there should

be a single request message and single reply message to the request.

Examples include an

OrderStatusRequest message and UserRequest.

Implementing InOut Exchanges for Consumers

Add "exchangePattern=InOut" to the QuickFIX/J enpoint URI. The

MessageOrderStatusService in

the example below is a bean with a synchronous service method. The

method returns the response

to the request (an ExecutionReport in this case) which is then sent back to

the requestor session.

from("quickfix:examples/

inprocess.cfg?sessionID=FIX.4.2:MARKET->TRADER&exchangePattern=InOut")

.filter(header(QuickfixjEndpoint.MESSAGE_TYPE_KEY).isEqualTo(MsgType.ORDER_STATUS_REQUEST))

.bean(new MarketOrderStatusService());

Implementing InOut Exchanges for Producers

For producers, sending a message will block until a reply is received or a

timeout occurs. There

is no standard way to correlate reply messages in FIX. Therefore, a

correlation criteria must be

dened for each type of InOut exchange. The correlation criteria and timeout

CHAPTER 11 - COMPONENT APPENDIX 846

can be specied

using Exchange properties.

Description Key String Key Constant Default

Correlation

Criteria "CorrelationCriteria" QuickxjProducer.CORRELATION_CRITERIA_KEY None

Correlation

Timeout in

Milliseconds

"CorrelationTimeout" QuickxjProducer.CORRELATION_TIMEOUT_KEY 1000

The correlation criteria is dened with a MessagePredicate object. The

following example will treat

a FIX ExecutionReport from the specied session where the transaction type

is STATUS and the Order ID

matches our request. The session ID should be for the requestor, the sender

and target CompID elds

will be reversed when looking for the reply.

exchange.setProperty(QuickfixjProducer.CORRELATION_CRITERIA_KEY,

new MessagePredicate(new SessionID(sessionID), MsgType.EXECUTION_REPORT)

.withField(ExecTransType.FIELD, Integer.toString(ExecTransType.STATUS))

.withField(OrderID.FIELD, request.getString(OrderID.FIELD)));

Example

The source code contains an example called RequestReplyExample that

demonstrates the InOut exchanges

for a consumer and producer. This example creates a simple HTTP server

endpoint that accepts order

status requests. The HTTP request is converted to a FIX

OrderStatusRequestMessage, is augmented with a

correlation criteria, and is then routed to a quickx endpoint. The response is

then converted to a

JSON-formatted string and sent back to the HTTP server endpoint to be

provided as the web response.

Spring Conguration

Camel 2.6+

The QuickFIX/J component includes a Spring FactoryBean for conguring

the session settings within a Spring context. A type converter for QuickFIX/J

session ID strings is also included. The following example shows a simple

847 CHAPTER 11 - COMPONENT APPENDIX

conguration of an acceptor and initiator session with default settings for

both sessions.

<route>

<simple>${in.header.EventCategory} == 'AppMessageReceived'</simple>

</filter>

</route>

</camelContext>

<util:map>

</util:map>

</property>

<bean

class="org.apache.camel.component.quickfixj.QuickfixjSpringTest.CustomMessageFactory"/>

</property>

</bean>

<bean id="quickfixjSettings"

class="org.apache.camel.component.quickfixj.QuickfixjSettingsFactory">

<util:map>

</util:map>

</property>

<util:map>

<entry key="FIX.4.2:INITIATOR->ACCEPTOR">

<util:map>

</util:map>

</entry>

<entry key="FIX.4.2:ACCEPTOR->INITIATOR">

<util:map>

</util:map>

</entry>

</util:map>

CHAPTER 11 - COMPONENT APPENDIX 848

</property>

</bean>

Exception handling

QuickFIX/J behavior can be modied if certain exceptions are thrown during

processing of a message. If a RejectLogon exception is thrown while

processing an incoming logon administrative message, then the logon will be

rejected.

Normally, QuickFIX/J handles the logon process automatically. However,

sometimes an outgoing logon message must be modied to include

credentials required by a FIX counterparty. If the FIX logon message body is

modied when sending a logon message

(EventCategory=AdminMessageSent the modied message will be sent to the

counterparty. It is important that the outgoing logon message is being

processed synchronously. If it is processed asynchronously (on another

thread), the FIX engine will immediately send the unmodied outgoing

message when it's callback method returns.

FIX Sequence Number Management

If an application exception is thrown during synchronous exchange

processing, this will cause QuickFIX/J to not increment incoming FIX message

sequence numbers and will cause a resend of the counterparty message.

This FIX protocol behavior is primarily intended to handle transport errors

rather than application errors. There are risks associated with using this

mechanism to handle application errors. The primary risk is that the message

will repeatedly cause application errors each time it's re-received. A better

solution is to persist the incoming message (database, JMS queue)

immediately before processing it. This also allows the application to process

messages asynchronously without losing messages when errors occur.

Although it's possible to send messages to a FIX session before it's logged

on (the messages will be sent at logon time), it is usually a better practice to

wait until the session is logged on. This eliminates the required sequence

number resynchronization steps at logon. Waiting for session logon can be

done by setting up a route that processes the SessionLogon event category

and signals the application to start sending messages.

See the FIX protocol specications and the QuickFIX/J documentation for

more details about FIX sequence number management.

849 CHAPTER 11 - COMPONENT APPENDIX

Route Examples

Several examples are included in the QuickFIX/J component source code (test

subdirectories). One of these examples implements a trival trade excecution

simulation. The example denes an application component that uses the URI

scheme "trade-executor".

The following route receives messages for the trade executor session and

passes application messages to the trade executor component.

from("quickfix:examples/inprocess.cfg?sessionID=FIX.4.2:MARKET->TRADER").

filter(header(QuickfixjEndpoint.EVENT_CATEGORY_KEY).isEqualTo(QuickfixjEventCategory.AppMessageReceived)).

to("trade-executor:market");

The trade executor component generates messages that are routed back to

the trade session. The session ID must be set in the FIX message itself since

no session ID is specied in the endpoint URI.

from("trade-executor:market").to("quickfix:examples/inprocess.cfg");

The trader session consumes execution report messages from the market

and processes them.

from("quickfix:examples/inprocess.cfg?sessionID=FIX.4.2:TRADER->MARKET").

filter(header(QuickfixjEndpoint.MESSAGE_TYPE_KEY).isEqualTo(MsgType.EXECUTION_REPORT)).

bean(new MyTradeExecutionProcessor());

QUICKFIX/J COMPONENT PRIOR TO CAMEL 2.5

Available since Camel 2.0

The quickx component is an implementation of the QuickFIX/J engine for

Java . This engine allows to connect to a FIX server which is used to

exchange nancial messages according to FIX protocol standard.

Note: The component can be used to send/receives messages to a FIX

server.

URI format

quickfix-server:config file

quickfix-client:config file

CHAPTER 11 - COMPONENT APPENDIX 850

Where cong le is the location (in your classpath) of the quickx

conguration le used to congure the engine at the startup.

Note: Information about parameters available for quickx can be found on

QuickFIX/J web site.

The quickx-server endpoint must be used to receive from FIX server FIX

messages and quickx-client endpoint in the case that you want to send

messages to a FIX gateway.

Exchange data format

The QuickFIX/J engine is like CXF component a messaging bus using MINA as

protocol layer to create the socket connection with the FIX engine gateway.

When QuickFIX/J engine receives a message, then it create a

QuickFix.Message instance which is next received by the camel endpoint.

This object is a 'mapping object' created from a FIX message formatted

initially as a collection of key value pairs data. You can use this object or you

can use the method 'toString' to retrieve the original FIX message.

Note: Alternatively, you can use camel bindy dataformat to transform the

FIX message into your own java POJO

When a message must be send to QuickFix, then you must create a

QuickFix.Message instance.

Samples

Direction : to FIX gateway

<route>

<bean ref="fixService" method="createFixMessage"/> // bean method in charge to

transform message into a QuickFix.Message

<to uri="quickfix-client:META-INF/quickfix/client.cfg"/> // Quickfix engine who

will send the FIX messages to the gateway

</route>

Direction : from FIX gateway

<route>

<from uri="quickfix-server:META-INF/quickfix/server.cfg"/> // QuickFix engine who

will receive the message from FIX gateway

<bean ref="fixService" method="parseFixMessage"/> // bean method parsing the

QuickFix.Message

<to uri="uri="activemq:queue:fix"/>"

</route>

851 CHAPTER 11 - COMPONENT APPENDIX

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

PRINTER COMPONENT

Available as of Camel 2.1

The printer component provides a way to direct payloads on a route to a

printer. Obviously the payload has to be a formatted piece of payload in

order for the component to appropriately print it. The objective is to be able

to direct specic payloads as jobs to a line printer in a camel ow.

This component only supports a camel producer endpoint.

The functionality allows for the payload to be printed on a default printer,

named local, remote or wirelessly linked printer using the javax printing API

under the covers.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-printer</artifactId>

</dependency>

URI format

Since the URI scheme for a printer has not been standardized (the nearest

thing to a standard being the IETF print standard) and therefore not uniformly

applied by vendors, we have chosen "lpr" as the scheme.

lpr://localhost/default[?options]

lpr://remotehost:port/path/to/printer[?options]

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Default Value Description

CHAPTER 11 - COMPONENT APPENDIX 852

mediaSize MediaSizeName.NA_LETTER

Sets the stationary as dened by enumeration settings in the

javax.print.attribute.standard.MediaSizeName API. The default setting is to use North American

Letter sized stationary

copies 1 Sets number of copies based on the javax.print.attribute.standard.Copies API

sides Sides.ONE_SIDED Sets one sided or two sided printing based on the javax.print.attribute.standard.Sides API

flavor DocFlavor.BYTE_ARRAY Sets DocFlavor based on the javax.print.DocFlavor API

mimeType AUTOSENSE Sets mimeTypes supported by the javax.print.DocFlavor API

Sending Messages to a Printer

Printer Producer

Sending data to the printer is very straightforward and involves creating a

producer endpoint that can be sent message exchanges on in route.

Usage Samples

Example 1: Printing text based payloads on a Default

printer using letter stationary and one-sided mode

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from(file://inputdir/?delete=true)

.to("lpr://localhost/default?copies=2" +

"&flavor=DocFlavor.INPUT_STREAM&" +

"&mimeType=AUTOSENSE" +

"&mediaSize=na-letter" +

"&sides=one-sided")

}};

Example 2: Printing GIF based payloads on a Remote

printer using A4 stationary and one-sided mode

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from(file://inputdir/?delete=true)

.to("lpr://remotehost/sales/salesprinter" +

"?copies=2&sides=one-sided" +

"&mimeType=GIF&mediaSize=iso-a4" +

"&flavor=DocFlavor.INPUT_STREAM")

}};

853 CHAPTER 11 - COMPONENT APPENDIX

Example 3: Printing JPEG based payloads on a Remote

printer using Japanese Postcard stationary and one-

sided mode

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from(file://inputdir/?delete=true)

.to("lpr://remotehost/sales/salesprinter" +

"?copies=2&sides=one-sided" +

"&mimeType=JPEG" +

"&mediaSize=japanese-postcard" +

"&flavor=DocFlavor.INPUT_STREAM")

}};

PROPERTIES COMPONENT

Available as of Camel 2.3

URI format

properties:key[?options]

Where key is the key for the property to lookup

Options

Name Type Default Description

cache boolean true Whether or not to cache loaded properties.

locations String null

A list of locations to load properties. You can use comma to separate multiple

locations. This option will override any default locations and only use the

locations from this option.

propertyPrefix String null 2.9 Optional prex prepended to property names before resolution.

propertySuffix String null 2.9 Optional sux appended to property names before resolution.

fallbackToUnaugmentedProperty boolean true

2.9 If true, rst attempt resolution of property name augmented with

propertyPrefix and propertySuffix before falling back the plain property

name specied. If false, only the augmented property name is searched.

prefixToken String {{ 2.9 The token to indicate the beginning of a property token.

suffixToken String }} 2.9 The token to indicate the end of a property token.

USING PROPERTYPLACEHOLDER

Available as of Camel 2.3

Camel now provides a new PropertiesComponent in camel-core which

allows you to use property placeholders when dening Camel Endpoint URIs.

CHAPTER 11 - COMPONENT APPENDIX 854

Resolving property from Java code

You can use the method resolvePropertyPlaceholders on the

CamelContext to resolve a property from any Java code.

This works much like you would do if using Spring's <property-

placeholder> tag. However Spring have a limitation which prevents 3rd

party frameworks to leverage Spring property placeholders to the fullest. See

more at How do I use Spring Property Placeholder with Camel XML.

The property placeholder is generally in use when doing:

▪ lookup or creating endpoints

▪ lookup of beans in the Registry

▪ additional supported in Spring XML (see below in examples)

▪ using Blueprint PropertyPlaceholder with Camel Properties

component

Syntax

The syntax to use Camel's property placeholder is to use {{key}} for

example {{file.uri}} where file.uri is the property key.

You can use property placeholders in parts of the endpoint URI's which for

example you can use placeholders for parameters in the URIs.

PropertyResolver

As usually Camel provides a pluggable mechanism which allows 3rd part to

provide their own resolver to lookup properties. Camel provides a default

implementation

org.apache.camel.component.properties.DefaultPropertiesResolver

which is capable of loading properties from the le system, classpath or

Registry. You can prex the locations with either:

▪ref: Camel 2.4: to lookup in the Registry

▪file: to load the from le system

▪classpath: to load from classpath (this is also the default if no prex

is provided)

▪blueprint: Camel 2.7: to use a specic OSGi blueprint placeholder

service

Dening location

The PropertiesResolver need to know a location(s) where to resolve the

properties. You can dene 1 to many locations. If you dene the location in a

855 CHAPTER 11 - COMPONENT APPENDIX

single String property you can separate multiple locations with comma such

as:

pc.setLocation("com/mycompany/myprop.properties,com/mycompany/other.properties");

Using system and environment variables in locations

Available as of Camel 2.7

The location now supports using placeholders for JVM system properties

and OS environments variables.

For example:

location=file:${karaf.home}/etc/foo.properties

In the location above we dened a location using the le scheme using the

JVM system property with key karaf.home.

To use an OS environment variable instead you would have to prex with

env:

location=file:${env:APP_HOME}/etc/foo.properties

Where APP_HOME is an OS environment.

You can have multiple placeholders in the same location, such as:

location=file:${env:APP_HOME}/etc/${prop.name}.properties

Conguring in Java DSL

You have to create and register the PropertiesComponent under the name

properties such as:

PropertiesComponent pc = new PropertiesComponent();

pc.setLocation("classpath:com/mycompany/myprop.properties");

context.addComponent("properties", pc);

Conguring in Spring XML

Spring XML oers two variations to congure. You can dene a spring bean

as a PropertiesComponent which resembles the way done in Java DSL. Or

you can use the <propertyPlaceholder> tag.

CHAPTER 11 - COMPONENT APPENDIX 856

<bean id="properties"

class="org.apache.camel.component.properties.PropertiesComponent">

</bean>

Using the <propertyPlaceholder> tag makes the conguration a bit more

fresh such as:

</camelContext>

Using a Properties from the Registry

Available as of Camel 2.4

For example in OSGi you may want to expose a service which returns the

properties as a java.util.Properties object.

Then you could setup the Properties component as follows:

Where myProperties is the id to use for lookup in the OSGi registry. Notice

we use the ref: prex to tell Camel that it should lookup the properties for

the Registry.

Examples using properties component

When using property placeholders in the endpoint URIs you can either use

the properties: component or dene the placeholders directly in the URI.

We will show example of both cases, starting with the former.

// properties

cool.end=mock:result

// route

from("direct:start").to("properties:{{cool.end}}");

You can also use placeholders as a part of the endpoint uri:

// properties

cool.foo=result

857 CHAPTER 11 - COMPONENT APPENDIX

// route

from("direct:start").to("properties:mock:{{cool.foo}}");

In the example above the to endpoint will be resolved to mock:result.

You can also have properties with refer to each other such as:

// properties

cool.foo=result

cool.concat=mock:{{cool.foo}}

// route

from("direct:start").to("properties:mock:{{cool.concat}}");

Notice how cool.concat refer to another property.

The properties: component also oers you to override and provide a

location in the given uri using the locations option:

from("direct:start").to("properties:bar.end?locations=com/mycompany/

bar.properties");

Examples

You can also use property placeholders directly in the endpoint uris without

having to use properties:.

// properties

cool.foo=result

// route

from("direct:start").to("mock:{{cool.foo}}");

And you can use them in multiple wherever you want them:

// properties

cool.start=direct:start

cool.showid=true

cool.result=result

// route

from("{{cool.start}}")

.to("log:{{cool.start}}?showBodyType=false&showExchangeId={{cool.showid}}")

.to("mock:{{cool.result}}");

You can also your property placeholders when using ProducerTemplate for

example:

CHAPTER 11 - COMPONENT APPENDIX 858

template.sendBody("{{cool.start}}","Hello World");

Example with Simple language

The Simple language now also support using property placeholders, for

example in the route below:

// properties

cheese.quote=Camel rocks

// route

from("direct:start")

.transform().simple("Hi ${body} do you think ${properties:cheese.quote}?");

You can also specify the location in the Simple language for example:

// bar.properties

bar.quote=Beer tastes good

// route

from("direct:start")

.transform().simple("Hi ${body}. ${properties:com/mycompany/

bar.properties:bar.quote}.");

Additional property placeholder supported in Spring XML

The property placeholders is also supported in many of the Camel Spring

XML tags such as <package>, <packageScan>, <contextScan>,

<jmxAgent>, <endpoint>, <routeBuilder>, <proxy> and the others.

The example below has property placeholder in the <jmxAgent> tag:

<propertyPlaceholder id="properties" location="org/apache/camel/spring/

jmx.properties"/>

<jmxAgent id="agent" registryPort="{{myjmx.port}}" disabled="{{myjmx.disabled}}"

usePlatformMBeanServer="{{myjmx.usePlatform}}"

createConnector="true"

statisticsLevel="RoutesOnly"/>

</route>

859 CHAPTER 11 - COMPONENT APPENDIX

</camelContext>

You can also dene property placeholders in the various attributes on the

<camelContext> tag such as trace as shown here:

<propertyPlaceholder id="properties" location="org/apache/camel/spring/processor/

myprop.properties"/>

<route>

<simple>${in.body} World!</simple>

</setHeader>

</route>

</camelContext>

Overriding a property setting using a JVM System Property

Available as of Camel 2.5

It is possible to override a property value at runtime using a JVM System

property without the need to restart the application to pick up the change.

This may also be accomplished from the command line by creating a JVM

System property of the same name as the property it replaces with a new

value. An example of this is given below

PropertiesComponent pc = context.getComponent("properties",

PropertiesComponent.class);

pc.setCache(false);

System.setProperty("cool.end","mock:override");

System.setProperty("cool.result","override");

context.addRoutes(new RouteBuilder() {

@Override

public void configure() throws Exception {

from("direct:start").to("properties:cool.end");

from("direct:foo").to("properties:mock:{{cool.result}}");

}

});

context.start();

getMockEndpoint("mock:override").expectedMessageCount(2);

CHAPTER 11 - COMPONENT APPENDIX 860

template.sendBody("direct:start","Hello World");

template.sendBody("direct:foo","Hello Foo");

System.clearProperty("cool.end");

System.clearProperty("cool.result");

assertMockEndpointsSatisfied();

Using property placeholders for any kind of attribute in the XML DSL

Available as of Camel 2.7

Previously it was only the xs:string type attributes in the XML DSL that

support placeholders. For example often a timeout attribute would be a

xs:int type and thus you cannot set a string value as the placeholder key.

This is now possible from Camel 2.7 onwards using a special placeholder

namespace.

In the example below we use the prop prex for the namespace

http://camel.apache.org/schema/placeholder by which we can use the

prop prex in the attributes in the XML DSLs. Notice how we use that in the

Multicast to indicate that the option stopOnException should be the value of

the placeholder with the key "stop".

<beans xmlns="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:prop="http://camel.apache.org/schema/placeholder"

xsi:schemaLocation="

http://www.springframework.org/schema/beans http://www.springframework.org/

schema/beans/spring-beans.xsd

http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/

camel-spring.xsd

<!-- Notice in the declaration above, we have defined the prop prefix as the

Camel placeholder namespace -->

<constructor-arg index="0" value="Damn"/>

</bean>

<propertyPlaceholder id="properties"

location="classpath:org/apache/camel/component/

properties/myprop.properties"

xmlns="http://camel.apache.org/schema/spring"/>

<route>

861 CHAPTER 11 - COMPONENT APPENDIX

<!-- use prop namespace, to define a property placeholder, which maps to

option stopOnException={{stop}} -->

</multicast>

</route>

</camelContext>

</beans>

In our properties le we have the value dened as

stop=true

Using property placeholder in the Java DSL

Available as of Camel 2.7

Likewise we have added support for dening placeholders in the Java DSL

using the new placeholder DSL as shown in the following equivalent

example:

from("direct:start")

// use a property placeholder for the option stopOnException on the Multicast EIP

// which should have the value of {{stop}} key being looked up in the properties

file

.multicast().placeholder("stopOnException","stop")

.to("mock:a").throwException(new IllegalAccessException("Damn")).to("mock:b");

Using Blueprint property placeholder with Camel routes

Available as of Camel 2.7

Camel supports Blueprint which also oers a property placeholder service.

Camel supports convention over conguration, so all you have to do is to

dene the OSGi Blueprint property placeholder in the XML le as shown

below:

Listing 85. Using OSGi blueprint property placeholders in Camel routes

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0"

xsi:schemaLocation="

http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/

CHAPTER 11 - COMPONENT APPENDIX 862

blueprint/v1.0.0/blueprint.xsd">

<cm:property-placeholder id="myblueprint.placeholder"

persistent-id="camel.blueprint">

<cm:default-properties>

<cm:property name="result" value="mock:result"/>

</cm:default-properties>

</cm:property-placeholder>

<!-- in the route we can use {{ }} placeholders which will lookup in blueprint

as Camel will auto detect the OSGi blueprint property placeholder and

use it -->

<route>

</route>

</camelContext>

</blueprint>

By default Camel detects and uses OSGi blueprint property placeholder

service. You can disable this by setting the attribute

useBlueprintPropertyResolver to false on the <camelContext> denition.

You can also explicit refer to a specic OSGi blueprint property placeholder

by its id. For that you need to use the Camel's <propertyPlaceholder> as

shown in the example below:

Listing 86. Explicit referring to a OSGi blueprint placeholder in Camel

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0"

xsi:schemaLocation="

http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/

blueprint/v1.0.0/blueprint.xsd">

<cm:property-placeholder id="myblueprint.placeholder"

persistent-id="camel.blueprint">

<cm:default-properties>

<cm:property name="prefix.result" value="mock:result"/>

</cm:default-properties>

</cm:property-placeholder>

863 CHAPTER 11 - COMPONENT APPENDIX

About placeholder syntaxes

Notice how we can use the Camel syntax for placeholders {{ }} in

the Camel route, which will lookup the value from OSGi blueprint.

The blueprint syntax for placeholders is ${ }. So outside the

<camelContext> you must use the ${ } syntax. Where as inside

<camelContext> you must use {{ }} syntax.

OSGi blueprint allows you to congure the syntax, so you can

actually align those if you want.

<!-- using Camel properties component and refer to the blueprint property

placeholder by its id -->

<propertyPlaceholder id="properties"

location="blueprint:myblueprint.placeholder"

prefixToken="[[" suffixToken="]]"

propertyPrefix="prefix."/>

<!-- in the route we can use {{ }} placeholders which will lookup in

blueprint -->

<route>

</route>

</camelContext>

</blueprint>

Notice how we use the blueprint scheme to refer to the OSGi blueprint

placeholder by its id. This allows you to mix and match, for example you can

also have additional schemes in the location. For example to load a le from

the classpath you can do:

location="blueprint:myblueprint.placeholder,classpath:myproperties.properties"

Each location is separated by comma.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

CHAPTER 11 - COMPONENT APPENDIX 864

▪ Jasypt for using encrypted values (eg passwords) in the properties

REF COMPONENT

The ref: component is used for lookup of existing endpoints bound in the

Registry.

URI format

ref:someName

Where someName is the name of an endpoint in the Registry (usually, but

not always, the Spring registry). If you are using the Spring registry,

someName would be the bean ID of an endpoint in the Spring registry.

Runtime lookup

This component can be used when you need dynamic discovery of endpoints

in the Registry where you can compute the URI at runtime. Then you can look

up the endpoint using the following code:

// lookup the endpoint

String myEndpointRef = "bigspenderOrder";

Endpoint endpoint = context.getEndpoint("ref:" + myEndpointRef);

Producer producer = endpoint.createProducer();

Exchange exchange = producer.createExchange();

exchange.getIn().setBody(payloadToSend);

// send the exchange

producer.process(exchange);

...

And you could have a list of endpoints dened in the Registry such as:

...

</camelContext>

Sample

In the sample below we use the ref: in the URI to reference the endpoint

with the spring ID, endpoint2:

865 CHAPTER 11 - COMPONENT APPENDIX

</bean>

<route>

</route>

</camelContext>

You could, of course, have used the ref attribute instead:

Which is the more common way to write it.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

RESTLET COMPONENT

The Restlet component provides Restlet based endpoints for consuming and

producing RESTful resources.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-restlet</artifactId>

</dependency>

CHAPTER 11 - COMPONENT APPENDIX 866

URI format

restlet:restletUrl[?options]

Format of restletUrl:

protocol://hostname[:port][/resourcePattern]

Restlet promotes decoupling of protocol and application concerns. The

reference implementation of Restlet Engine supports a number of protocols.

However, we have tested the HTTP protocol only. The default port is port 80.

We do not automatically switch default port based on the protocol yet.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Default Value Description

headerFilterStrategy=#refName

(2.x or later)

An instance of

RestletHeaderFilterStrategy

Use the #notation (headerFilterStrategy=#refName) to reference a

header lter strategy in the Camel Registry. The strategy will be

plugged into the restlet binding if it is HeaderFilterStrategyAware.

restletBindingRef (1.x),

restletBinding=#refName (2.x

or later)

An instance of

DefaultRestletBinding The bean ID of a RestletBinding object in the Camel Registry.

restletMethod GET

On a producer endpoint, species the request method to use. On a

consumer endpoint, species that the endpoint consumes only

restletMethod requests. The string value is converted to

org.restlet.data.Method by the Method.valueOf(String) method.

restletMethods (2.x or later)None

Consumer only Specify one or more methods separated by commas

(e.g. restletMethods=post,put) to be serviced by a restlet consumer

endpoint. If both restletMethod and restletMethods options are

specied, the restletMethod setting is ignored.

restletRealmRef (1.x),

restletRealm=#refName (2.x or

later)

null The bean ID of the Realm Map in the Camel Registry.

restletUriPatterns=#refName

(2.x or later)None

Consumer only Specify one ore more URI templates to be serviced by

a restlet consumer endpoint, using the #notation to reference a

List<String> in the Camel Registry. If a URI pattern has been dened

in the endpoint URI, both the URI pattern dened in the endpoint and

the restletUriPatterns option will be honored.

throwExceptionOnFailure (2.6

or later)true *Producer only * Throws exception on a producer failure.

Message Headers

Camel 1.x

Name Type Description

org.apache.camel.restlet.auth.login String Login name for basic authentication. It is set on the IN message by the application

and gets ltered before the restlet request header by Camel.

867 CHAPTER 11 - COMPONENT APPENDIX

org.apache.camel.restlet.auth.password String Password name for basic authentication. It is set on the IN message by the

application and gets ltered before the restlet request header by Camel.

org.apache.camel.restlet.mediaType String

Species the content type, which can be set on the OUT message by the application/

processor. The value is the content-type of the response message. If this header is

not set, the content-type is set based on the object type of the OUT message body.

org.apache.camel.restlet.queryString String The query string of the request URI. It is set on the IN message by

DefaultRestletBinding when the restlet component receives a request.

org.apache.camel.restlet.responseCode

String

Integer

The response code can be set on the OUT message by the application/processor. The

value is the response code of the response message. If this header is not set, the

response code is set by the restlet runtime engine.

org.restlet.* Attributes of a restlet message that get propagated to Camel IN headers.

Camel 2.x

Name Type Description

Content-Type String

Species the content type, which can be set on the OUT message by the application/processor. The

value is the content-type of the response message. If this header is not set, the content type is based

on the object type of the OUT message body. In Camel 2.3 onward, if the Content-Type header is

specied in the Camel IN message, the value of the header determine the content type for the Restlet

request message. Otherwise, it is defaulted to "application/x-www-form-urlencoded'. Prior to release

2.3, it is not possible to change the request content type default.

CamelHttpMethod String The HTTP request method. This is set in the IN message header.

CamelHttpQuery String The query string of the request URI. It is set on the IN message by DefaultRestletBinding when the

restlet component receives a request.

CamelHttpResponseCode

String

Integer

The response code can be set on the OUT message by the application/processor. The value is the

response code of the response message. If this header is not set, the response code is set by the restlet

runtime engine.

CamelHttpUri String The HTTP request URI. This is set in the IN message header.

CamelRestletLogin String Login name for basic authentication. It is set on the IN message by the application and gets ltered

before the restlet request header by Camel.

CamelRestletPassword String Password name for basic authentication. It is set on the IN message by the application and gets ltered

before the restlet request header by Camel.

CamelRestletRequest Request Camel 2.8: The org.restlet.Request object which holds all request details.

CamelRestletResponse Response Camel 2.8: The org.restlet.Response object. You can use this to create responses using the API from

Restlet. See examples below.

org.restlet.* Attributes of a Restlet message that get propagated to Camel IN headers.

Message Body

Camel will store the restlet response from the external server on the OUT

body. All headers from the IN message will be copied to the OUT message, so

that headers are preserved during routing.

Samples

Restlet Endpoint with Authentication

The following route starts a restlet consumer endpoint that listens for POST

requests on http://localhost:8080. The processor creates a response that

echoes the request body and the value of the id header.

CHAPTER 11 - COMPONENT APPENDIX 868

from("restlet:http://localhost:" + port +

"/securedOrders?restletMethod=post&restletRealm=#realm").process(new Processor() {

public void process(Exchange exchange) throws Exception {

exchange.getOut().setBody(

"received [" + exchange.getIn().getBody()

+"] as an order id = "

+ exchange.getIn().getHeader("id"));

}

});

The restletRealm setting (in 2.x, use the #notation, that is,

restletRealm=#refName)in the URI query is used to look up a Realm Map in

the registry. If this option is specied, the restlet consumer uses the

information to authenticate user logins. Only authenticated requests can

access the resources. In this sample, we create a Spring application context

that serves as a registry. The bean ID of the Realm Map should match the

restletRealmRef.

<util:map id="realm">

</util:map>

The following sample starts a direct endpoint that sends requests to the

server on http://localhost:8080 (that is, our restlet consumer endpoint).

// Note: restletMethod and restletRealmRef are stripped

// from the query before a request is sent as they are

// only processed by Camel.

from("direct:start-auth").to("restlet:http://localhost:" + port +

"/securedOrders?restletMethod=post");

That is all we need. We are ready to send a request and try out the restlet

component:

final String id = "89531";

Map<String,Object> headers = new HashMap<String,Object>();

headers.put(RestletConstants.RESTLET_LOGIN, "admin");

headers.put(RestletConstants.RESTLET_PASSWORD, "foo");

headers.put("id", id);

String response = (String)template.requestBodyAndHeaders(

"direct:start-auth","<order foo='1'/>", headers);

The sample client sends a request to the direct:start-auth endpoint with

the following headers:

869 CHAPTER 11 - COMPONENT APPENDIX

•CamelRestletLogin (used internally by Camel)

•CamelRestletPassword (used internally by Camel)

•id (application header)

The sample client gets a response like the following:

received [<order foo='1'/>] as an order id = 89531

Single restlet endpoint to service multiple methods and

URI templates (2.0 or later)

It is possible to create a single route to service multiple HTTP methods using

the restletMethods option. This snippet also shows how to retrieve the

request method from the header:

from("restlet:http://localhost:" + portNum + "/users/

{username}?restletMethods=post,get")

.process(new Processor() {

public void process(Exchange exchange) throws Exception {

// echo the method

exchange.getOut().setBody(exchange.getIn().getHeader(Exchange.HTTP_METHOD,

String.class));

}

});

In addition to servicing multiple methods, the next snippet shows how to

create an endpoint that supports multiple URI templates using the

restletUriPatterns option. The request URI is available in the header of

the IN message as well. If a URI pattern has been dened in the endpoint URI

(which is not the case in this sample), both the URI pattern dened in the

endpoint and the restletUriPatterns option will be honored.

from("restlet:http://localhost:" + portNum +

"?restletMethods=post,get&restletUriPatterns=#uriTemplates")

.process(new Processor() {

public void process(Exchange exchange) throws Exception {

// echo the method

String uri = exchange.getIn().getHeader(Exchange.HTTP_URI, String.class);

String out = exchange.getIn().getHeader(Exchange.HTTP_METHOD,

String.class);

if (("http://localhost:" + portNum + "/users/homer").equals(uri)) {

exchange.getOut().setBody(out + " " +

exchange.getIn().getHeader("username",String.class));

}else if (("http://localhost:" + portNum + "/atom/collection/foo/

component/bar").equals(uri)) {

exchange.getOut().setBody(out + " " +

CHAPTER 11 - COMPONENT APPENDIX 870

Note

org.apache.camel.restlet.auth.login and

org.apache.camel.restlet.auth.password will not be

propagated as Restlet header.

exchange.getIn().getHeader("id",String.class)

+" " + exchange.getIn().getHeader("cid",

String.class));

}

});

The restletUriPatterns=#uriTemplates option references the

List<String> bean dened in the Spring XML conguration.

<util:list id="uriTemplates">

<value>/users/{username}</value>

<value>/atom/collection/{id}/component/{cid}</value>

</util:list>

Using Restlet API to populate response

Available as of Camel 2.8

You may want to use the org.restlet.Response API to populate the

response. This gives you full access to the Restlet API and ne grained

control of the response. See the route snippet below where we generate the

response from an inlined Camel Processor:

Listing 87. Generating response using Restlet Response API

from("restlet:http://localhost:" + portNum + "/users/{id}/like/{beer}")

.process(new Processor() {

public void process(Exchange exchange) throws Exception {

// the Restlet request should be available if neeeded

Request request =

exchange.getIn().getHeader(RestletConstants.RESTLET_REQUEST, Request.class);

assertNotNull("Restlet Request", request);

// use Restlet API to create the response

Response response =

exchange.getIn().getHeader(RestletConstants.RESTLET_RESPONSE, Response.class);

assertNotNull("Restlet Response", response);

response.setStatus(Status.SUCCESS_OK);

response.setEntity("<response>Beer is Good</response>",

871 CHAPTER 11 - COMPONENT APPENDIX

MediaType.TEXT_XML);

exchange.getOut().setBody(response);

}

});

Using the Restlet servlet within a webapp

Available as of Camel 2.8

There are three possible ways to congure a Restlet application within a

servlet container and using the subclassed SpringServerServlet enables

conguration within Camel by injecting the Restlet Component.

Use of the Restlet servlet within a servlet container enables routes to be

congured with relative paths in URIs (removing the restrictions of hard-

coded absolute URIs) and for the hosting servlet container to handle

incoming requests (rather than have to spawn a separate server process on a

new port).

To congure, add the following to your camel-context.xml;

<simple>Request type : ${header.CamelHttpMethod} and ID : ${header.id}</simple>

</transform>

</route>

</camelContext>

<bean id="RestletComponentService"

class="org.apache.camel.component.restlet.RestletComponent">

<constructor-arg index="0">

</constructor-arg>

</bean>

And add this to your web.xml;

<servlet-name>RestletServlet</servlet-name>

<servlet-class>org.restlet.ext.spring.SpringServerServlet</servlet-class>

<init-param>

<param-name>org.restlet.component</param-name>

<param-value>RestletComponent</param-value>

</init-param>

CHAPTER 11 - COMPONENT APPENDIX 872

</servlet>

<servlet-mapping>

<servlet-name>RestletServlet</servlet-name>

<url-pattern>/rs/*</url-pattern>

</servlet-mapping>

You will then be able to access the deployed route at http://localhost:8080/

mywebapp/rs/demo/1234 where;

localhost:8080 is the server and port of your servlet container

mywebapp is the name of your deployed webapp

Your browser will then show the following content;

"Request type : GET and ID : 1234"

You will need to add dependency on the Spring extension to restlet which you

can do in your Maven pom.xml le:

<groupId>org.restlet.jee</groupId>

<artifactId>org.restlet.ext.spring</artifactId>

<version>${restlet-version}</version>

</dependency>

And you would need to add dependency on the restlet maven repository as

well:

<id>maven-restlet</id>

<name>Public online Restlet repository</name>

<url>http://maven.restlet.org</url>

</repository>

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

RMI COMPONENT

The rmi: component binds PojoExchanges to the RMI protocol (JRMP).

873 CHAPTER 11 - COMPONENT APPENDIX

Since this binding is just using RMI, normal RMI rules still apply regarding

what methods can be invoked. This component supports only PojoExchanges

that carry a method invocation from an interface that extends the Remote

interface. All parameters in the method should be either Serializable or

Remote objects.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-rmi</artifactId>

</dependency>

URI format

rmi://rmi-regisitry-host:rmi-registry-port/registry-path[?options]

For example:

rmi://localhost:1099/path/to/service

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Default

Value Description

method null As of Camel 1.3, you can set the name of the method to invoke.

remoteInterfaces null Its now possible to use this option from Camel 2.7: in the XML DSL. It can be a list of interface

names separated by comma.

Using

To call out to an existing RMI service registered in an RMI registry, create a

route similar to the following:

from("pojo:foo").to("rmi://localhost:1099/foo");

To bind an existing camel processor or service in an RMI registry, dene an

RMI endpoint as follows:

CHAPTER 11 - COMPONENT APPENDIX 874

RmiEndpoint endpoint= (RmiEndpoint) endpoint("rmi://localhost:1099/bar");

endpoint.setRemoteInterfaces(ISay.class);

from(endpoint).to("pojo:bar");

Note that when binding an RMI consumer endpoint, you must specify the

Remote interfaces exposed.

In XML DSL you can do as follows from Camel 2.7 onwards:

<camel:route>

<from uri="rmi://localhost:37541/

helloServiceBean?remoteInterfaces=org.apache.camel.example.osgi.HelloService"/>

</camel:route>

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

RSS COMPONENT

Available as of Camel 2.0

The rss: component is used for polling RSS feeds. Camel will default poll

the feed every 60th seconds.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-rss</artifactId>

</dependency>

Note: The component currently only supports polling (consuming) feeds.

URI format

rss:rssUri

875 CHAPTER 11 - COMPONENT APPENDIX

Using camel-rss in OSGi environment

Camel-rss uses ROME 1.0 and below. This library has class loading

issues in OSGi environment. We submitted issue 142 to ROME.

You can also nd patched version in this repository. One thing you

have to change is version - patched version is marked as 1.0-osgi.

Where rssUri is the URI to the RSS feed to poll.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Property Default Description

splitEntries true

If true, Camel splits a feed into its individual entries and returns each entry, poll by poll. For

example, if a feed contains seven entries, Camel returns the rst entry on the rst poll, the

second entry on the second poll, and so on. When no more entries are left in the feed, Camel

contacts the remote RSS URI to obtain a new feed. If false, Camel obtains a fresh feed on every

poll and returns all of the feed's entries.

filter true

Use in combination with the splitEntries option in order to lter returned entries. By default,

Camel applies the UpdateDateFilter lter, which returns only new entries from the feed,

ensuring that the consumer endpoint never receives an entry more than once. The lter orders

the entries chronologically, with the newest returned last.

throttleEntries true

Camel 2.5: Sets whether all entries identied in a single feed poll should be delivered

immediately. If true, only one entry is processed per consumer.delay. Only applicable when

splitEntries is set to true.

lastUpdate null

Use in combination with the filter option to block entries earlier than a specic date/time (uses

the entry.updated timestamp). The format is: yyyy-MM-ddTHH:MM:ss. Example:

2007-12-24T17:45:59.

feedHeader true Species whether to add the ROME SyndFeed object as a header.

sortEntries false If splitEntries is true, this species whether to sort the entries by updated date.

consumer.delay 60000 Delay in milliseconds between each poll.

consumer.initialDelay 1000 Milliseconds before polling starts.

consumer.userFixedDelay false Set to true to use xed delay between pools, otherwise xed rate is used. See

ScheduledExecutorService in JDK for details.

Exchange data types

Camel initializes the In body on the Exchange with a ROME SyndFeed.

Depending on the value of the splitEntries ag, Camel returns either a

SyndFeed with one SyndEntry or a java.util.List of SyndEntrys.

Option Value Behavior

splitEntries true A single entry from the current feed is set in the exchange.

splitEntries false The entire list of entries from the current feed is set in the exchange.

Message Headers

Header Description

CHAPTER 11 - COMPONENT APPENDIX 876

org.apache.camel.component.rss.feed Camel 1.x: The entire SyncFeed object.

CamelRssFeed Camel 2.0: The entire SyncFeed object.

RSS Dataformat

The RSS component ships with an RSS dataformat that can be used to

convert between String (as XML) and ROME RSS model objects.

• marshal = from ROME SyndFeed to XML String

• unmarshal = from XML String to ROME SyndFeed

A route using this would look something like this:

from("rss:file:src/test/data/

rss20.xml?splitEntries=false&consumer.delay=1000").marshal().rss().to("mock:marshal");

The purpose of this feature is to make it possible to use Camel's lovely built-

in expressions for manipulating RSS messages. As shown below, an XPath

expression can be used to lter the RSS message:

// only entries with Camel in the title will get through the filter

from("rss:file:src/test/data/rss20.xml?splitEntries=true&consumer.delay=100")

.marshal().rss().filter().xpath("//item/

title[contains(.,'Camel')]").to("mock:result");

Filtering entries

You can lter out entries quite easily using XPath, as shown in the data

format section above. You can also exploit Camel's Bean Integration to

implement your own conditions. For instance, a lter equivalent to the XPath

example above would be:

// only entries with Camel in the title will get through the filter

from("rss:file:src/test/data/rss20.xml?splitEntries=true&consumer.delay=100").

filter().method("myFilterBean","titleContainsCamel").to("mock:result");

The custom bean for this would be:

public static class FilterBean {

public boolean titleContainsCamel(@Body SyndFeed feed) {

SyndEntry firstEntry = (SyndEntry) feed.getEntries().get(0);

return firstEntry.getTitle().contains("Camel");

}

877 CHAPTER 11 - COMPONENT APPENDIX

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ Atom

Unable to render {include} Couldn't nd a page to include called: Scalate

SEDA COMPONENT

The seda: component provides asynchronous SEDA behavior, so that

messages are exchanged on a BlockingQueue and consumers are invoked in

a separate thread from the producer.

Note that queues are only visible within a single CamelContext. If you want

to communicate across CamelContext instances (for example,

communicating between Web applications), see the VM component.

This component does not implement any kind of persistence or recovery, if

the VM terminates while messages are yet to be processed. If you need

persistence, reliability or distributed SEDA, try using either JMS or ActiveMQ.

URI format

seda:someName[?options]

Where someName can be any string that uniquely identies the endpoint

within the current CamelContext.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Default Description

size

The maximum size (= capacity of the number of messages it can max hold) of the SEDA

queue. The default value in Camel 2.2 or older is 1000. From Camel 2.3 onwards the size is

unbounded by default.

concurrentConsumers 1 Camel 1.6.1/2.0: Number of concurrent threads processing exchanges.

waitForTaskToComplete IfReplyExpected

Camel 2.0: Option to specify whether the caller should wait for the async task to complete

or not before continuing. The following three options are supported: Always,Never or

IfReplyExpected. The rst two values are self-explanatory. The last value,

IfReplyExpected, will only wait if the message is Request Reply based. The default option is

IfReplyExpected. See more information about Async messaging.

timeout 30000

Camel 2.0: Timeout in millis a seda producer will at most waiting for an async task to

complete. See waitForTaskToComplete and Async for more details. In Camel 2.2 you can

now disable timeout by using 0 or a negative value.

CHAPTER 11 - COMPONENT APPENDIX 878

Synchronous

The Direct component provides synchronous invocation of any

consumers when a producer sends a message exchange.

Camel 1.x - Same URI must be used for both producer and

consumer

An exactly identical SEDA endpoint URI must be used for both the

producer endpoint and the consumer endpoint. Otherwise Camel

will create a second SEDA endpoint, even thought the someName

portion of the URI is identical. For example:

from("direct:foo").to("seda:bar?concurrentConsumers=5");

from("seda:bar?concurrentConsumers=5").to("file://output");

Notice that we have to use the full URI including options in both the

producer and consumer.

In Camel 2.x this has been xed so its the queue name that must match,

eg in this example we are using bar as the queue name.

multipleConsumers false

Camel 2.2: Species whether multiple consumers is allowed or not. If enabled you can use

SEDA for a pubsub kinda style messaging. Send a message to a seda queue and have

multiple consumers receive a copy of the message.

limitConcurrentConsumers true

Camel 2.3: Whether to limit the concurrentConsumers to maximum 500. If its congured

with a higher number an exception will be thrown. You can disable this check by turning this

option o.

blockWhenFull false

Camel 2.9: Whether to block the current thread when sending a message to a SEDA

endpoint, and the SEDA queue is full (capacity hit). By default an exception will be thrown

stating the queue is full. By setting this option to true the caller thread will instead block

and wait until the message can be delivered to the SEDA queue.

Changes in Camel 2.0

In Camel 2.0 the SEDA component supports using Request Reply, where the

caller will wait for the Async route to complete. For instance:

from("mina:tcp://0.0.0.0:9876?textline=true&sync=true").to("seda:input");

from("seda:input").to("bean:processInput").to("bean:createResponse");

In the route above, we have a TCP listener on port 9876 that accepts

incoming requests. The request is routed to the seda:input queue. As it is a

Request Reply message, we wait for the response. When the consumer on

879 CHAPTER 11 - COMPONENT APPENDIX

the seda:input queue is complete, it copies the response to the original

message response.

Camel 1.x does not have this feature implemented, the SEDA queues in

Camel 1.x will never wait.

Concurrent consumers

By default, the SEDA endpoint uses a single consumer thread, but you can

congure it to use concurrent consumer threads. So instead of thread pools

you can use:

from("seda:stageName?concurrentConsumers=5").process(...)

Dierence between thread pools and concurrent

consumers

The thread pool is a pool that can increase/shrink dynamically at runtime

depending on load, whereas the concurrent consumers are always xed.

Thread pools

Be aware that adding a thread pool to a SEDA endpoint by doing something

like:

from("seda:stageName").thread(5).process(...)

Can wind up with two BlockQueues: one from the SEDA endpoint, and one

from the workqueue of the thread pool, which may not be what you want.

Instead, you might want to consider conguring a Direct endpoint with a

thread pool, which can process messages both synchronously and

asynchronously. For example:

from("direct:stageName").thread(5).process(...)

You can also directly congure number of threads that process messages on

a SEDA endpoint using the concurrentConsumers option.

Sample

In the route below we use the SEDA queue to send the request to this async

queue to be able to send a re-and-forget message for further processing in

CHAPTER 11 - COMPONENT APPENDIX 880

Camel 2.0 - 2.2: Works only with 2 endpoints

Using Request Reply over SEDA or VM only works with 2 endpoints.

You cannot chain endpoints by sending to A -> B -> C etc. Only

between A -> B. The reason is the implementation logic is fairly

simple. To support 3+ endpoints makes the logic much more

complex to handle ordering and notication between the waiting

threads properly.

This has been improved in Camel 2.3 onwards, which allows you to chain

as many endpoints as you like.

another thread, and return a constant reply in this thread to the original

caller.

public void configure() throws Exception {

from("direct:start")

// send it to the seda queue that is async

.to("seda:next")

// return a constant response

.transform(constant("OK"));

from("seda:next").to("mock:result");

}

Here we send a Hello World message and expects the reply to be OK.

Object out = template.requestBody("direct:start","Hello World");

assertEquals("OK", out);

The "Hello World" message will be consumed from the SEDA queue from

another thread for further processing. Since this is from a unit test, it will be

sent to a mock endpoint where we can do assertions in the unit test.

Using multipleConsumers

Available as of Camel 2.2

In this example we have dened two consumers and registered them as

spring beans.

881 CHAPTER 11 - COMPONENT APPENDIX

<!-- define a shared endpoint which the consumers can refer to instead of using

url -->

</camelContext>

Since we have specied multipleConsumers=true on the seda foo

endpoint we can have those two consumers receive their own copy of the

message as a kind of pub-sub style messaging.

As the beans are part of an unit test they simply send the message to a

mock endpoint, but notice how we can use @Consume to consume from the

seda queue.

public class FooEventConsumer {

@EndpointInject(uri = "mock:result")

private ProducerTemplate destination;

@Consume(ref = "foo")

public void doSomething(String body) {

destination.sendBody("foo" + body);

}

Extracting queue information.

If you need it, you can also get information like queue size etc without using

JMX like this:

SedaEndpoint seda = context.getEndpoint("seda:xxxx");

int size = seda.getExchanges().size()

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ VM

▪ Direct

▪ Async

CHAPTER 11 - COMPONENT APPENDIX 882

SERVLET COMPONENT

Available as of Camel 2.0

The servlet: component provides HTTP based endpoints for consuming

HTTP requests that arrive at a HTTP endpoint and this endpoint is bound to a

published Servlet.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-servlet</artifactId>

<\!-\- use the same version as your Camel core version \-->

</dependency>

URI format

servlet://relative_path[?options]

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Default

Value Description

httpBindingRef null Reference to an org.apache.camel.component.http.HttpBinding in the Registry. A HttpBinding

implementation can be used to customize how to write a response.

matchOnUriPrefix false Whether or not the CamelServlet should try to nd a target consumer by matching the URI prex, if no

exact match is found.

servletName CamelServlet Species the servlet name that the servlet endpoint will bind to. This name should match the name you

dene in web.xml le.

Message Headers

Camel will apply the same Message Headers as the HTTP component.

Camel will also populate all request.parameter and request.headers.

For example, if a client request has the URL, http://myserver/

myserver?orderid=123, the exchange will contain a header named orderid

with the value 123.

883 CHAPTER 11 - COMPONENT APPENDIX

Usage

You can only consume from endpoints generated by the Servlet component.

Therefore, it should only be used as input into your camel routes. To issue

HTTP requests against other HTTP endpoints, use the HTTP Component

Sample

In this sample, we dene a route that exposes a HTTP service at

http://localhost:8080/camel/services/hello.

First, you need to publish the CamelHttpTransportServlet through the normal

Web Container, or OSGi Service.

Use the Web.xml le to publish the CamelHttpTransportServlet as follows:

<web-app>

<servlet-name>CamelServlet</servlet-name>

<display-name>Camel Http Transport Servlet</display-name>

<servlet-class>org.apache.camel.component.servlet.CamelHttpTransportServlet</servlet-class>

</servlet>

<servlet-mapping>

<servlet-name>CamelServlet</servlet-name>

<url-pattern>/services/*</url-pattern>

</servlet-mapping>

</web-app>

Then you can dene your route as follows:

from("servlet:///hello?matchOnUriPrefix=true").process(new Processor() {

public void process(Exchange exchange) throws Exception {

String contentType = exchange.getIn().getHeader(Exchange.CONTENT_TYPE,

String.class);

String path = exchange.getIn().getHeader(Exchange.HTTP_PATH, String.class);

assertEquals("Get a wrong content type", CONTENT_TYPE, contentType);

// assert camel http header

String charsetEncoding =

exchange.getIn().getHeader(Exchange.HTTP_CHARACTER_ENCODING, String.class);

assertEquals("Get a wrong charset name from the message heaer","UTF-8",

charsetEncoding);

// assert exchange charset

assertEquals("Get a wrong charset naem from the exchange property","UTF-8",

exchange.getProperty(Exchange.CHARSET_NAME));

exchange.getOut().setHeader(Exchange.CONTENT_TYPE, contentType + ";

charset=UTF-8");

exchange.getOut().setHeader("PATH", path);

exchange.getOut().setBody("<b>Hello World</b>");

CHAPTER 11 - COMPONENT APPENDIX 884

From Camel 2.7 onwards its easier to use Servlet in Spring web

applications. See Servlet Tomcat Example for details.

}

});

Sample when using Spring 3.x

See Servlet Tomcat Example

Sample when using Spring 2.x

When using the Servlet component in a Camel/Spring application it's often

required to load the Spring ApplicationContext after the Servlet component

has started. This can be accomplished by using Spring's

ContextLoaderServlet instead of ContextLoaderListener. In that case

you'll need to start ContextLoaderServlet after CamelHttpTransportServlet

like this:

<web-app>

<servlet-name>CamelServlet</servlet-name>

<servlet-class>

org.apache.camel.component.servlet.CamelHttpTransportServlet

</servlet-class>

<load-on-startup>1</load-on-startup>

</servlet>

<servlet-name>SpringApplicationContext</servlet-name>

<servlet-class>

org.springframework.web.context.ContextLoaderServlet

</servlet-class>

<load-on-startup>2</load-on-startup>

</servlet>

<web-app>

Sample when using OSGi

From Camel 2.6.0, you can publish the CamelHttpTransportServlet as an

OSGi service with help of SpringDM like this.

885 CHAPTER 11 - COMPONENT APPENDIX

Specify the relative path for camel-servlet endpoint

Since we are binding the Http transport with a published servlet,

and we don't know the servlet's application context path, the

camel-servlet endpoint uses the relative path to specify the

endpoint's URL. A client can access the camel-servlet endpoint

through the servlet publish address: ("http://localhost:8080/

camel/services") + RELATIVE_PATH("/hello").

<beans xmlns="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:osgi="http://www.springframework.org/schema/osgi"

xsi:schemaLocation="

http://www.springframework.org/schema/beans http://www.springframework.org/

schema/beans/spring-beans.xsd

http://www.springframework.org/schema/osgi http://www.springframework.org/

schema/osgi/spring-osgi.xsd">

<bean id="camelServlet"

class="org.apache.camel.component.servlet.CamelHttpTransportServlet">

</bean>

<!--

Enlist it in OSGi service registry

This will cause two things:

1) As the pax web whiteboard extender is running the CamelServlet will

be registered with the OSGi HTTP Service

2) It will trigger the HttpRegistry in other bundles so the servlet is

made known there too

-->

<osgi:service ref="camelServlet">

<osgi:interfaces>

<value>javax.servlet.Servlet</value>

<value>org.apache.camel.component.http.CamelServlet</value>

</osgi:interfaces>

<osgi:service-properties>

</osgi:service-properties>

</osgi:service>

</beans>

Then use this service in your camel route like this:

<beans xmlns="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

CHAPTER 11 - COMPONENT APPENDIX 886

xmlns:camel="http://camel.apache.org/schema/spring"

xmlns:osgi="http://www.springframework.org/schema/osgi"

xsi:schemaLocation="

http://www.springframework.org/schema/beans http://www.springframework.org/

schema/beans/spring-beans.xsd

http://www.springframework.org/schema/osgi http://www.springframework.org/

schema/osgi/spring-osgi.xsd

http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/

camel-spring.xsd">

<osgi:reference id="servletref"

interface="org.apache.camel.component.http.CamelServlet">

<osgi:listener bind-method="register" unbind-method="unregister">

</osgi:listener>

</osgi:reference>

<bean id="httpRegistry"

class="org.apache.camel.component.servlet.DefaultHttpRegistry"/>

<bean id="servlet"

class="org.apache.camel.component.servlet.ServletComponent">

</bean>

<bean id="servletProcessor"

class="org.apache.camel.itest.osgi.servlet.ServletProcessor" />

<route>

<!-- notice how we can use the servlet scheme which is that

osgi:reference above -->

</route>

</camelContext>

</beans>

For versions prior to Camel 2.6 you can use an Activator to publish the

CamelHttpTransportServlet on the OSGi platform

import java.util.Dictionary;

import java.util.Hashtable;

import org.apache.camel.component.servlet.CamelHttpTransportServlet;

import org.osgi.framework.BundleActivator;

import org.osgi.framework.BundleContext;

import org.osgi.framework.ServiceReference;

import org.osgi.service.http.HttpContext;

import org.osgi.service.http.HttpService;

import org.slf4j.Logger;

887 CHAPTER 11 - COMPONENT APPENDIX

import org.slf4j.LoggerFactory;

import org.springframework.osgi.context.BundleContextAware;

public final class ServletActivator implements BundleActivator, BundleContextAware {

private static final transient Logger LOG =

LoggerFactory.getLogger(ServletActivator.class);

private static boolean registerService;

/**

* HttpService reference.

private ServiceReference httpServiceRef;

/**

* Called when the OSGi framework starts our bundle

public void start(BundleContext bc) throws Exception {

registerServlet(bc);

}

/**

* Called when the OSGi framework stops our bundle

public void stop(BundleContext bc) throws Exception {

if (httpServiceRef != null) {

bc.ungetService(httpServiceRef);

httpServiceRef = null;

}

protected void registerServlet(BundleContext bundleContext) throws Exception {

httpServiceRef =

bundleContext.getServiceReference(HttpService.class.getName());

if (httpServiceRef != null && !registerService) {

LOG.info("Register the servlet service");

final HttpService httpService =

(HttpService)bundleContext.getService(httpServiceRef);

if (httpService != null) {

// create a default context to share between registrations

final HttpContext httpContext =

httpService.createDefaultHttpContext();

// register the hello world servlet

final Dictionary<String,String> initParams = new Hashtable<String,

String>();

initParams.put("matchOnUriPrefix","false");

initParams.put("servlet-name","CamelServlet");

httpService.registerServlet("/camel/services",// alias

new CamelHttpTransportServlet(), // register servlet

initParams, // init params

httpContext // http context

);

registerService = true;

}

CHAPTER 11 - COMPONENT APPENDIX 888

}

public void setBundleContext(BundleContext bc) {

try {

registerServlet(bc);

}catch (Exception e) {

LOG.error("Cannot register the servlet, the reason is " + e);

}

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ Servlet Tomcat Example

▪ HTTP

▪ Jetty

SHIRO SECURITY COMPONENT

Available as of Camel 2.5

The shiro-security component in Camel is a security focused component,

based on the Apache Shiro security project.

Apache Shiro is a powerful and exible open-source security framework

that cleanly handles authentication, authorization, enterprise session

management and cryptography. The objective of the Apache Shiro project is

to provide the most robust and comprehensive application security

framework available while also being very easy to understand and extremely

simple to use.

This camel shiro-security component allows authentication and

authorization support to be applied to dierent segments of a camel route.

Shiro security is applied on a route using a Camel Policy. A Policy in Camel

utilizes a strategy pattern for applying interceptors on Camel Processors. It

oering the ability to apply cross-cutting concerns (for example. security,

transactions etc) on sections/segments of a camel route.

Maven users will need to add the following dependency to their pom.xml

for this component:

889 CHAPTER 11 - COMPONENT APPENDIX

<groupId>org.apache.camel</groupId>

<artifactId>camel-shiro</artifactId>

</dependency>

Shiro Security Basics

To employ Shiro security on a camel route, a ShiroSecurityPolicy object must

be instantiated with security conguration details (including users,

passwords, roles etc). This object must then be applied to a camel route. This

ShiroSecurityPolicy Object may also be registered in the Camel registry (JNDI

or ApplicationContextRegistry) and then utilized on other routes in the Camel

Context.

Conguration details are provided to the ShiroSecurityPolicy using an Ini

le (properties le) or an Ini object. The Ini le is a standard Shiro

conguration le containing user/role details as shown below

[users]

# user 'ringo' with password 'starr' and the 'sec-level1' role

ringo = starr, sec-level1

george = harrison, sec-level2

john = lennon, sec-level3

paul = mccartney, sec-level3

[roles]

# 'sec-level3' role has all permissions, indicated by the

# wildcard '*'

sec-level3 = *

# The 'sec-level2' role can do anything with access of permission

# readonly (*) to help

sec-level2 = zone1:*

# The 'sec-level1' role can do anything with access of permission

# readonly

sec-level1 = zone1:readonly:*

Instantiating a ShiroSecurityPolicy Object

A ShiroSecurityPolicy object is instantiated as follows

private final String iniResourcePath = "classpath:shiro.ini";

private final byte[] passPhrase = {

(byte) 0x08, (byte) 0x09, (byte) 0x0A, (byte) 0x0B,

CHAPTER 11 - COMPONENT APPENDIX 890

(byte) 0x0C, (byte) 0x0D, (byte) 0x0E, (byte) 0x0F,

(byte) 0x10, (byte) 0x11, (byte) 0x12, (byte) 0x13,

(byte) 0x14, (byte) 0x15, (byte) 0x16, (byte) 0x17};

List<permission> permissionsList = new ArrayList<permission>();

Permission permission = new WildcardPermission("zone1:readwrite:*");

permissionsList.add(permission);

final ShiroSecurityPolicy securityPolicy =

new ShiroSecurityPolicy(iniResourcePath, passPhrase, true,

permissionsList);

ShiroSecurityPolicy Options

Name Default

Value Type Description

iniResourcePath or

ini none Resource String or Ini Object

A mandatory Resource String for the iniResourcePath or an

instance of an Ini object must be passed to the security

policy. Resources can be acquired from the le system,

classpath, or URLs when prexed with "le:, classpath:, or

url:" respectively. For e.g "classpath:shiro.ini"

passPhrase An AES 128

based key byte[] A passPhrase to decrypt ShiroSecurityToken(s) sent along

with Message Exchanges

alwaysReauthenticate true boolean

Setting to ensure re-authentication on every individual

request. If set to false, the user is authenticated and locked

such than only requests from the same user going forward

are authenticated.

permissionsList none List<Permission>

A List of permissions required in order for an authenticated

user to be authorized to perform further action i.e continue

further on the route. If no Permissions list is provided to the

ShiroSecurityPolicy object, then authorization is deemed as

not required

cipherService AES org.apache.shiro.crypto.CipherService

Shiro ships with AES & Blowsh based CipherServices. You

may use one these or pass in your own Cipher

implementation

Applying Shiro Authentication on a Camel Route

The ShiroSecurityPolicy, tests and permits incoming message exchanges

containing a encrypted SecurityToken in the Message Header to proceed

further following proper authentication. The SecurityToken object contains a

Username/Password details that are used to determine where the user is a

valid user.

protected RouteBuilder createRouteBuilder() throws Exception {

final ShiroSecurityPolicy securityPolicy =

new ShiroSecurityPolicy("classpath:shiro.ini", passPhrase);

return new RouteBuilder() {

public void configure() {

onException(UnknownAccountException.class).

to("mock:authenticationException");

onException(IncorrectCredentialsException.class).

891 CHAPTER 11 - COMPONENT APPENDIX

to("mock:authenticationException");

onException(LockedAccountException.class).

to("mock:authenticationException");

onException(AuthenticationException.class).

to("mock:authenticationException");

from("direct:secureEndpoint").

to("log:incoming payload").

policy(securityPolicy).

to("mock:success");

}

};

}

Applying Shiro Authorization on a Camel Route

Authorization can be applied on a camel route by associating a Permissions

List with the ShiroSecurityPolicy. The Permissions List species the

permissions necessary for the user to proceed with the execution of the route

segment. If the user does not have the proper permission set, the request is

not authorized to continue any further.

protected RouteBuilder createRouteBuilder() throws Exception {

final ShiroSecurityPolicy securityPolicy =

new ShiroSecurityPolicy("./src/test/resources/securityconfig.ini",

passPhrase);

return new RouteBuilder() {

public void configure() {

onException(UnknownAccountException.class).

to("mock:authenticationException");

onException(IncorrectCredentialsException.class).

to("mock:authenticationException");

onException(LockedAccountException.class).

to("mock:authenticationException");

onException(AuthenticationException.class).

to("mock:authenticationException");

from("direct:secureEndpoint").

to("log:incoming payload").

policy(securityPolicy).

to("mock:success");

}

};

}

CHAPTER 11 - COMPONENT APPENDIX 892

Creating a ShiroSecurityToken and injecting it into a Message

Exchange

A ShiroSecurityToken object may be created and injected into a Message

Exchange using a Shiro Processor called ShiroSecurityTokenInjector. An

example of injecting a ShiroSecurityToken using a ShiroSecurityTokenInjector

in the client is shown below

ShiroSecurityToken shiroSecurityToken = new ShiroSecurityToken("ringo","starr");

ShiroSecurityTokenInjector shiroSecurityTokenInjector =

new ShiroSecurityTokenInjector(shiroSecurityToken, passPhrase);

from("direct:client").

process(shiroSecurityTokenInjector).

to("direct:secureEndpoint");

Sending Messages to routes secured by a ShiroSecurityPolicy

Messages and Message Exchanges sent along the camel route where the

security policy is applied need to be accompanied by a SecurityToken in the

Exchange Header. The SecurityToken is an encrypted object that holds a

Username and Password. The SecurityToken is encrypted using AES 128 bit

security by default and can be changed to any cipher of your choice.

Given below is an example of how a request may be sent using a

ProducerTemplate in Camel along with a SecurityToken

@Test

public void testSuccessfulShiroAuthenticationWithNoAuthorization() throws

Exception {

//Incorrect password

ShiroSecurityToken shiroSecurityToken = new ShiroSecurityToken("ringo",

"stirr");

// TestShiroSecurityTokenInjector extends ShiroSecurityTokenInjector

TestShiroSecurityTokenInjector shiroSecurityTokenInjector =

new TestShiroSecurityTokenInjector(shiroSecurityToken, passPhrase);

successEndpoint.expectedMessageCount(1);

failureEndpoint.expectedMessageCount(0);

template.send("direct:secureEndpoint", shiroSecurityTokenInjector);

successEndpoint.assertIsSatisfied();

failureEndpoint.assertIsSatisfied();

}

893 CHAPTER 11 - COMPONENT APPENDIX

SIP COMPONENT

Available as of Camel 2.5

The sip component in Camel is a communication component, based on

the Jain SIP implementation (available under the JCP license).

Session Initiation Protocol (SIP) is an IETF-dened signaling protocol,

widely used for controlling multimedia communication sessions such as voice

and video calls over Internet Protocol (IP).The SIP protocol is an Application

Layer protocol designed to be independent of the underlying transport layer;

it can run on Transmission Control Protocol (TCP), User Datagram Protocol

(UDP) or Stream Control Transmission Protocol (SCTP).

The Jain SIP implementation supports TCP and UDP only.

The Camel SIP component only supports the SIP Publish and Subscribe

capability as described in the RFC3903 - Session Initiation Protocol (SIP)

Extension for Event

This camel component supports both producer and consumer endpoints.

Camel SIP Producers (Event Publishers) and SIP Consumers (Event

Subscribers) communicate event & state information to each other using an

intermediary entity called a SIP Presence Agent (a stateful brokering entity).

For SIP based communication, a SIP Stack with a listener must be

instantiated on both the SIP Producer and Consumer (using separate ports if

using localhost). This is necessary in order to support the handshakes &

acknowledgements exchanged between the SIP Stacks during

communication.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-sip</artifactId>

</dependency>

URI format

The URI scheme for a sip endpoint is as follows:

sip://johndoe@localhost:99999[?options]

sips://johndoe@localhost:99999/[?options]

This component supports producer and consumer endpoints for both TCP and

UDP.

CHAPTER 11 - COMPONENT APPENDIX 894

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

The SIP Component oers an extensive set of conguration options &

capability to create custom stateful headers needed to propagate state via

the SIP protocol.

Name Default

Value Description

stackName NAME_NOT_SET Name of the SIP Stack instance associated with an SIP Endpoint.

transport tcp Setting for choice of transport potocol. Valid choices are "tcp" or "udp".

fromUser Username of the message originator. Mandatory setting unless a registry based custom

FromHeader is specied.

fromHost Hostname of the message originator. Mandatory setting unless a registry based

FromHeader is specied

fromPort Port of the message originator. Mandatory setting unless a registry based FromHeader is

specied

toUser Username of the message receiver. Mandatory setting unless a registry based custom

ToHeader is specied.

toHost Hostname of the message receiver. Mandatory setting unless a registry based ToHeader is

specied

toPort Portname of the message receiver. Mandatory setting unless a registry based ToHeader is

specied

maxforwards 0the number of intermediaries that may forward the message to the message receiver. Optional

setting. May alternatively be set using as registry based MaxForwardsHeader

eventId Setting for a String based event Id. Mandatory setting unless a registry based FromHeader

is specied

eventHeaderName Setting for a String based event Id. Mandatory setting unless a registry based FromHeader

is specied

maxMessageSize 1048576 Setting for maximum allowed Message size in bytes.

cacheConnections false Should connections be cached by the SipStack to reduce cost of connection creation. This is useful

if the connection is used for long running conversations.

consumer false This setting is used to determine whether the kind of header (FromHeader,ToHeader etc) that

needs to be created for this endpoint

automaticDialogSupport off Setting to specify whether every communication should be associated with a dialog.

contentType text Setting for contentType can be set to any valid MimeType.

contentSubType xml Setting for contentSubType can be set to any valid MimeSubType.

receiveTimeoutMillis 10000 Setting for specifying amount of time to wait for a Response and/or Acknowledgement can be

received from another SIP stack

useRouterForAllUris false This setting is used when requests are sent to the Presence Agent via a proxy.

msgExpiration 3600 The amount of time a message received at an endpoint is considered valid

presenceAgent false

This setting is used to distingish between a Presence Agent & a consumer. This is due to the fact

that the SIP Camel component ships with a basic Presence Agent (for testing purposes only).

Consumers have to set this ag to true.

Registry based Options

SIP requires a number of headers to be sent/received as part of a request.

These SIP header can be enlisted in the Registry, such as in the Spring XML

le.

The values that could be passed in, are the following:

895 CHAPTER 11 - COMPONENT APPENDIX

Name Description

fromHeader a custom Header object containing message originator settings. Must implement the type javax.sip.header.FromHeader

toHeader a custom Header object containing message receiver settings. Must implement the type javax.sip.header.ToHeader

viaHeaders List of custom Header objects of the type javax.sip.header.ViaHeader. Each ViaHeader containing a proxy address for

request forwarding. (Note this header is automatically updated by each proxy when the request arrives at its listener)

contentTypeHeader a custom Header object containing message content details. Must implement the type

javax.sip.header.ContentTypeHeader

callIdHeader a custom Header object containing call details. Must implement the type javax.sip.header.CallIdHeader

maxForwardsHeader a custom Header object containing details on maximum proxy forwards. This header places a limit on the viaHeaders

possible. Must implement the type javax.sip.header.MaxForwardsHeader

eventHeader a custom Header object containing event details. Must implement the type javax.sip.header.EventHeader

contactHeader an optional custom Header object containing verbose contact details (email, phone number etc). Must implement the

type javax.sip.header.ContactHeader

expiresHeader a custom Header object containing message expiration details. Must implement the type javax.sip.header.ExpiresHeader

extensionHeader a custom Header object containing user/application specic details. Must implement the type

javax.sip.header.ExtensionHeader

Sending Messages to/from a SIP endpoint

Creating a Camel SIP Publisher

In the example below, a SIP Publisher is created to send SIP Event

publications to

a user "agent@localhost:5152". This is the address of the SIP Presence Agent

which acts as a broker between the SIP Publisher and Subscriber

• using a SIP Stack named client

• using a registry based eventHeader called evtHdrName

• using a registry based eventId called evtId

• from a SIP Stack with Listener set up as user2@localhost:3534

• The Event being published is EVENT_A

• A Mandatory Header called REQUEST_METHOD is set to

Request.Publish thereby setting up the endpoint as a Event

publisher"

producerTemplate.sendBodyAndHeader(

"sip://agent@localhost:5152?stackName=client&eventHeaderName=evtHdrName&eventId=evtid&fromUser=user2&fromHost=localhost&fromPort=3534",

"EVENT_A",

"REQUEST_METHOD",

Request.PUBLISH);

CHAPTER 11 - COMPONENT APPENDIX 896

Creating a Camel SIP Subscriber

In the example below, a SIP Subscriber is created to receive SIP Event

publications sent to

a user "johndoe@localhost:5154"

• using a SIP Stack named Subscriber

• registering with a Presence Agent user called agent@localhost:5152

• using a registry based eventHeader called evtHdrName. The

evtHdrName contains the Event which is se to "Event_A"

• using a registry based eventId called evtId

@Override

protected RouteBuilder createRouteBuilder() throws Exception {

return new RouteBuilder() {

@Override

public void configure() throws Exception {

// Create PresenceAgent

from("sip://agent@localhost:5152?stackName=PresenceAgent&presenceAgent=true&eventHeaderName=evtHdrName&eventId=evtid")

.to("mock:neverland");

// Create Sip Consumer(Event Subscriber)

from("sip://johndoe@localhost:5154?stackName=Subscriber&toUser=agent&toHost=localhost&toPort=5152&eventHeaderName=evtHdrName&eventId=evtid")

.to("log:ReceivedEvent?level=DEBUG")

.to("mock:notification");

}

};

}

The Camel SIP component also ships with a Presence Agent that is

meant to be used for Testing and Demo purposes only. An example of

instantiating a Presence Agent is given above.

Note that the Presence Agent is set up as a user agent@localhost:5152

and is capable of communicating with both Publisher as well as Subscriber. It

has a separate SIP stackName distinct from Publisher as well as Subscriber.

While it is set up as a Camel Consumer, it does not actually send any

messages along the route to the endpoint "mock:neverland".

SMPP COMPONENT

Available as of Camel 2.2

This component provides access to an SMSC (Short Message Service

Center) over the SMPP protocol to send and receive SMS. The JSMPP is used.

Starting with Camel 2.9, you are also able to execute ReplaceSm,

QuerySm, SubmitMulti, CancelSm and DataSm.

897 CHAPTER 11 - COMPONENT APPENDIX

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-smpp</artifactId>

</dependency>

URI format

smpp://[username@]hostname[:port][?options]

smpps://[username@]hostname[:port][?options]

If no username is provided, then Camel will provide the default value

smppclient.

If no port number is provided, then Camel will provide the default value

2775.

Camel 2.3: If the protocol name is "smpps", camel-smpp with try to use

SSLSocket to init a connection to the server.

You can append query options to the URI in the following format,

?option=value&option=value&...

URI Options

Name Default

Value Description

password password Species the password to use to log in to the SMSC.

systemType cp This parameter is used to categorize the type of ESME (External Short Message Entity) that is

binding to the SMSC (max. 13 characters).

dataCoding 0

Camel 2.5 onwarts until Camel 2.8.x Denes encoding of data according the SMPP 3.4

specication, section 5.2.19. Example data encodings are:

0: SMSC Default Alphabet

4: 8 bit Alphabet

8: UCS2 Alphabet

alphabet 0

Camel 2.9 onwarts Denes the alphabet of the data according the SMPP 3.4 specication,

section 5.2.19. Example alphabet encodings are:

-1: The SMPP component will try to determine the actual alphabet to be used. The message will be

sent using UCS2 encoding if it contains non standard GSM characters.

0: SMSC Default Alphabet

4: 8 bit Alphabet

8: UCS2 Alphabet

encoding ISO-8859-1 only for SubmitSm, ReplaceSm and SubmitMulti Denes the encoding scheme of the short

message user data.

enquireLinkTimer 5000 Denes the interval in milliseconds between the condence checks. The condence check is used

to test the communication path between an ESME and an SMSC.

transactionTimer 10000

Denes the maximum period of inactivity allowed after a transaction, after which an SMPP entity

may assume that the session is no longer active. This timer may be active on either

communicating SMPP entity (i.e. SMSC or ESME).

CHAPTER 11 - COMPONENT APPENDIX 898

initialReconnectDelay 5000 Denes the initial delay in milliseconds after the consumer/producer tries to reconnect to the

SMSC, after the connection was lost.

reconnectDelay 5000 Denes the interval in milliseconds between the reconnect attempts, if the connection to the SMSC

was lost and the previous was not succeed.

registeredDelivery 1

only for SubmitSm, ReplaceSm, SubmitMulti and DataSm Is used to request an SMSC

delivery receipt and/or SME originated acknowledgements. The following values are dened:

0: No SMSC delivery receipt requested.

1: SMSC delivery receipt requested where nal delivery outcome is success or failure.

2: SMSC delivery receipt requested where the nal delivery outcome is delivery failure.

serviceType CMT

The service type parameter can be used to indicate the SMS Application service associated with

the message. The following generic service_types are dened:

CMT: Cellular Messaging

CPT: Cellular Paging

VMN: Voice Mail Notication

VMA: Voice Mail Alerting

WAP: Wireless Application Protocol

USSD: Unstructured Supplementary Services Data

sourceAddr 1616 Denes the address of SME (Short Message Entity) which originated this message.

destAddr 1717 only for SubmitSm, SubmitMulti, CancelSm and DataSm Denes the destination SME

address. For mobile terminated messages, this is the directory number of the recipient MS.

sourceAddrTon 0

Denes the type of number (TON) to be used in the SME originator address parameters. The

following TON values are dened:

0: Unknown

1: International

2: National

3: Network Specic

4: Subscriber Number

5: Alphanumeric

6: Abbreviated

destAddrTon 0

only for SubmitSm, SubmitMulti, CancelSm and DataSm Denes the type of number (TON)

to be used in the SME destination address parameters. The following TON values are dened:

0: Unknown

1: International

2: National

3: Network Specic

4: Subscriber Number

5: Alphanumeric

6: Abbreviated

sourceAddrNpi 0

Denes the numeric plan indicator (NPI) to be used in the SME originator address parameters. The

following NPI values are dened:

0: Unknown

1: ISDN (E163/E164)

2: Data (X.121)

3: Telex (F.69)

6: Land Mobile (E.212)

8: National

9: Private

10: ERMES

13: Internet (IP)

18: WAP Client Id (to be dened by WAP Forum)

destAddrNpi 0

only for SubmitSm, SubmitMulti, CancelSm and DataSm Denes the numeric plan indicator

(NPI) to be used in the SME destination address parameters. The following NPI values are dened:

0: Unknown

1: ISDN (E163/E164)

2: Data (X.121)

3: Telex (F.69)

6: Land Mobile (E.212)

8: National

9: Private

10: ERMES

13: Internet (IP)

18: WAP Client Id (to be dened by WAP Forum)

priorityFlag 1

only for SubmitSm and SubmitMulti Allows the originating SME to assign a priority level to the

short message. Four Priority Levels are supported:

0: Level 0 (lowest) priority

1: Level 1 priority

2: Level 2 priority

3: Level 3 (highest) priority

replaceIfPresentFlag 0

only for SubmitSm and SubmitMulti Used to request the SMSC to replace a previously

submitted message, that is still pending delivery. The SMSC will replace an existing message

provided that the source address, destination address and service type match the same elds in

the new message. The following replace if present ag values are dened:

0: Don't replace

1: Replace

899 CHAPTER 11 - COMPONENT APPENDIX

typeOfNumber 0

Denes the type of number (TON) to be used in the SME. The following TON values are dened:

0: Unknown

1: International

2: National

3: Network Specic

4: Subscriber Number

5: Alphanumeric

6: Abbreviated

numberingPlanIndicator 0

Denes the numeric plan indicator (NPI) to be used in the SME. The following NPI values are

dened:

0: Unknown

1: ISDN (E163/E164)

2: Data (X.121)

3: Telex (F.69)

6: Land Mobile (E.212)

8: National

9: Private

10: ERMES

13: Internet (IP)

18: WAP Client Id (to be dened by WAP Forum)

lazySessionCreation false Camel 2.8 onwarts Sessions can be lazily created to avoid exceptions, if the SMSC is not

available when the Camel producer is started.

You can have as many of these options as you like.

smpp://smppclient@localhost:2775?password=password&enquireLinkTimer=3000&transactionTimer=5000&systemType=consumer

Message Headers

The following message headers can be used to aect the behavior of the

SMPP producer

Header Description

CamelSmppDestAddr only for SubmitSm, SubmitMulti, CancelSm and DataSm Denes the destination SME address. For

mobile terminated messages, this is the directory number of the recipient MS.

CamelSmppDestAddrTon

only for SubmitSm, SubmitMulti, CancelSm and DataSm Denes the type of number (TON) to be

used in the SME destination address parameters. The following TON values are dened:

0: Unknown

1: International

2: National

3: Network Specic

4: Subscriber Number

5: Alphanumeric

6: Abbreviated

CamelSmppDestAddrNpi

only for SubmitSm, SubmitMulti, CancelSm and DataSm Denes the numeric plan indicator (NPI) to

be used in the SME destination address parameters. The following NPI values are dened:

0: Unknown

1: ISDN (E163/E164)

2: Data (X.121)

3: Telex (F.69)

6: Land Mobile (E.212)

8: National

9: Private

10: ERMES

13: Internet (IP)

18: WAP Client Id (to be dened by WAP Forum)

CamelSmppSourceAddr Denes the address of SME (Short Message Entity) which originated this message.

CamelSmppSourceAddrTon

Denes the type of number (TON) to be used in the SME originator address parameters. The following TON

values are dened:

0: Unknown

1: International

2: National

3: Network Specic

4: Subscriber Number

5: Alphanumeric

6: Abbreviated

CHAPTER 11 - COMPONENT APPENDIX 900

CamelSmppSourceAddrNpi

Denes the numeric plan indicator (NPI) to be used in the SME originator address parameters. The

following NPI values are dened:

0: Unknown

1: ISDN (E163/E164)

2: Data (X.121)

3: Telex (F.69)

6: Land Mobile (E.212)

8: National

9: Private

10: ERMES

13: Internet (IP)

18: WAP Client Id (to be dened by WAP Forum)

CamelSmppServiceType

The service type parameter can be used to indicate the SMS Application service associated with the

message. The following generic service_types are dened:

CMT: Cellular Messaging

CPT: Cellular Paging

VMN: Voice Mail Notication

VMA: Voice Mail Alerting

WAP: Wireless Application Protocol

USSD: Unstructured Supplementary Services Data

CamelSmppRegisteredDelivery

only for SubmitSm, ReplaceSm, SubmitMulti and DataSm Is used to request an SMSC delivery

receipt and/or SME originated acknowledgements. The following values are dened:

0: No SMSC delivery receipt requested.

1: SMSC delivery receipt requested where nal delivery outcome is success or failure.

2: SMSC delivery receipt requested where the nal delivery outcome is delivery failure.

CamelSmppPriorityFlag

only for SubmitSm and SubmitMulti Allows the originating SME to assign a priority level to the short

message. Four Priority Levels are supported:

0: Level 0 (lowest) priority

1: Level 1 priority

2: Level 2 priority

3: Level 3 (highest) priority

CamelSmppScheduleDeliveryTime

only for SubmitSm, SubmitMulti and ReplaceSm This parameter species the scheduled time at

which the message delivery should be rst attempted. It denes either the absolute date and time or

relative time from the current SMSC time at which delivery of this message will be attempted by the SMSC.

It can be specied in either absolute time format or relative time format. The encoding of a time format is

specied in chapter 7.1.1. in the smpp specication v3.4.

CamelSmppValidityPeriod

only for SubmitSm, SubmitMulti and ReplaceSm The validity period parameter indicates the SMSC

expiration time, after which the message should be discarded if not delivered to the destination. It can be

dened in absolute time format or relative time format. The encoding of absolute and relative time format

is specied in chapter 7.1.1 in the smpp specication v3.4.

CamelSmppReplaceIfPresentFlag

only for SubmitSm and SubmitMulti The replace if present ag parameter is used to request the SMSC

to replace a previously submitted message, that is still pending delivery. The SMSC will replace an existing

message provided that the source address, destination address and service type match the same elds in

the new message. The following values are dened:

0: Don't replace

1: Replace

CamelSmppDataCoding

Camel 2.5 onwarts until Camel 2.8.x The data coding according to the SMPP 3.4 specication, section

5.2.19:

0: SMSC Default Alphabet

4: 8 bit Alphabet

8: UCS2 Alphabet

CamelSmppAlphabet

Camel 2.9 onwarts only for SubmitSm, SubmitMulti and ReplaceSm The data coding according to

the SMPP 3.4 specication, section 5.2.19:

-1: The SMPP component will try to determine the actual alphabet to be used. The message will be sent

using UCS2 encoding if it contains non standard GSM characters.

0: SMSC Default Alphabet

4: 8 bit Alphabet

8: UCS2 Alphabet

The following message headers are used by the SMPP producer to set the

response from the SMSC in the message header

Header Description

CamelSmppId

The id to identify the submitted short message(s) for later use (delivery receipt, query sm, cancel sm, replace

sm). From Camel 2.9: In case of a ReplaceSm, QuerySm, CancelSm and DataSm, this header vaule is a

String. In case of a SubmitSm or SubmitMultiSm this header vaule is a String[].

CamelSmppSentMessageCount From Camel 2.9 onwarts only for SubmitSm and SubmitMultiSm The total number of messages which

has been sent.

CamelSmppError

From Camel 2.9 onwarts only for SubmitMultiSm The errors which occurred by sending the short

message(s) the form Map<String, List<Map<String, Object>>> (messageID : (destAddr : address, error :

errorCode)).

901 CHAPTER 11 - COMPONENT APPENDIX

The following message headers are used by the SMPP consumer to set the

request data from the SMSC in the message header

Header Description

CamelSmppSequenceNumber only for AlertNotication, DeliverSm and DataSm A sequence number allows a response PDU to be

correlated with a request PDU. The associated SMPP response PDU must preserve this eld.

CamelSmppCommandId only for AlertNotication, DeliverSm and DataSm The command id eld identies the particular SMPP

PDU. For the complete list of dened values see chapter 5.1.2.1 in the smpp specication v3.4.

CamelSmppSourceAddr only for AlertNotication, DeliverSm and DataSm Denes the address of SME (Short Message Entity)

which originated this message.

CamelSmppSourceAddrNpi

only for AlertNotication and DataSm Denes the numeric plan indicator (NPI) to be used in the SME

originator address parameters. The following NPI values are dened:

0: Unknown

1: ISDN (E163/E164)

2: Data (X.121)

3: Telex (F.69)

6: Land Mobile (E.212)

8: National

9: Private

10: ERMES

13: Internet (IP)

18: WAP Client Id (to be dened by WAP Forum)

CamelSmppSourceAddrTon

only for AlertNotication and DataSm Denes the type of number (TON) to be used in the SME

originator address parameters. The following TON values are dened:

0: Unknown

1: International

2: National

3: Network Specic

4: Subscriber Number

5: Alphanumeric

6: Abbreviated

CamelSmppEsmeAddr only for AlertNotication Denes the destination ESME address. For mobile terminated messages, this is

the directory number of the recipient MS.

CamelSmppEsmeAddrNpi

only for AlertNotication Denes the numeric plan indicator (NPI) to be used in the ESME originator

address parameters. The following NPI values are dened:

0: Unknown

1: ISDN (E163/E164)

2: Data (X.121)

3: Telex (F.69)

6: Land Mobile (E.212)

8: National

9: Private

10: ERMES

13: Internet (IP)

18: WAP Client Id (to be dened by WAP Forum)

CamelSmppEsmeAddrTon

only for AlertNotication Denes the type of number (TON) to be used in the ESME originator address

parameters. The following TON values are dened:

0: Unknown

1: International

2: National

3: Network Specic

4: Subscriber Number

5: Alphanumeric

6: Abbreviated

CamelSmppId only for smsc DeliveryReceipt and DataSm The message ID allocated to the message by the SMSC

when originally submitted.

CamelSmppDelivered only for smsc DeliveryReceipt Number of short messages delivered. This is only relevant where the

original message was submitted to a distribution list.The value is padded with leading zeros if necessary.

CamelSmppDoneDate only for smsc DeliveryReceipt The time and date at which the short message reached it's nal state.

The format is as follows: YYMMDDhhmm.

CamelSmppStatus

only for smsc DeliveryReceipt and DataSm The nal status of the message. The following values are

dened:

DELIVRD: Message is delivered to destination

EXPIRED: Message validity period has expired.

DELETED: Message has been deleted.

UNDELIV: Message is undeliverable

ACCEPTD: Message is in accepted state (i.e. has been manually read on behalf of the subscriber by

customer service)

UNKNOWN: Message is in invalid state

REJECTD: Message is in a rejected state

CHAPTER 11 - COMPONENT APPENDIX 902

CamelSmppError

only for smsc DeliveryReceipt Where appropriate this may hold a Network specic error code or an

SMSC error code for the attempted delivery of the message. These errors are Network or SMSC specic and

are not included here.

CamelSmppSubmitDate

only for smsc DeliveryReceipt The time and date at which the short message was submitted. In the

case of a message which has been replaced, this is the date that the original message was replaced. The

format is as follows: YYMMDDhhmm.

CamelSmppSubmitted

only for smsc DeliveryReceipt Number of short messages originally submitted. This is only relevant

when the original message was submitted to a distribution list.The value is padded with leading zeros if

necessary.

CamelSmppDestAddr only for DeliverSm and DataSm Denes the destination SME address. For mobile terminated messages,

this is the directory number of the recipient MS.

CamelSmppScheduleDeliveryTime

only for DeliverSm and DataSm This parameter species the scheduled time at which the message

delivery should be rst attempted. It denes either the absolute date and time or relative time from the

current SMSC time at which delivery of this message will be attempted by the SMSC. It can be specied in

either absolute time format or relative time format. The encoding of a time format is specied in Section

7.1.1. in the smpp specication v3.4.

CamelSmppValidityPeriod

only for DeliverSm The validity period parameter indicates the SMSC expiration time, after which the

message should be discarded if not delivered to the destination. It can be dened in absolute time format

or relative time format. The encoding of absolute and relative time format is specied in Section 7.1.1 in

the smpp specication v3.4.

CamelSmppServiceType only for DeliverSm and DataSm The service type parameter indicates the SMS Application service

associated with the message.

CamelSmppRegisteredDelivery

only for DataSm Is used to request an delivery receipt and/or SME originated acknowledgements. The

following values are dened:

0: No SMSC delivery receipt requested.

1: SMSC delivery receipt requested where nal delivery outcome is success or failure.

2: SMSC delivery receipt requested where the nal delivery outcome is delivery failure.

CamelSmppDestAddrNpi

only for DataSm Denes the numeric plan indicator (NPI) in the destination address parameters. The

following NPI values are dened:

0: Unknown

1: ISDN (E163/E164)

2: Data (X.121)

3: Telex (F.69)

6: Land Mobile (E.212)

8: National

9: Private

10: ERMES

13: Internet (IP)

18: WAP Client Id (to be dened by WAP Forum)

CamelSmppDestAddrTon

only for DataSm Denes the type of number (TON) in the destination address parameters. The following

TON values are dened:

0: Unknown

1: International

2: National

3: Network Specic

4: Subscriber Number

5: Alphanumeric

6: Abbreviated

CamelSmppMessageType

Camel 2.6 onwarts: Identies the type of an incoming message:

AlertNotification: an SMSC alert notication

DataSm: an SMSC data short message

DeliveryReceipt: an SMSC delivery receipt

DeliverSm: an SMSC deliver short message

Exception handling

This component supports the general Camel exception handling capabilities.

Camel 2.8 onwarts: When the SMPP consumer receives a DeliverSm or

DataSm short message and the processing of these messages fails, you can

also throw a ProcessRequestException instead of handle the failure. In this

case, this exception is forwarded to the underlying JSMPP library which will

return the included error code to the SMSC. This feature is useful to e.g.

instruct the SMSC to resend the short message at a later time. This could be

done with the following lines of code:

903 CHAPTER 11 - COMPONENT APPENDIX

JSMPP library

See the documentation of the JSMPP Library for more details about

the underlying library.

from("smpp://smppclient@localhost:2775?password=password&enquireLinkTimer=3000&transactionTimer=5000&systemType=consumer")

.doTry()

.to("bean:dao?method=updateSmsState")

.doCatch(Exception.class)

.throwException(new ProcessRequestException("update of sms state failed", 100))

.end();

Please refer to the SMPP specication for the complete list of error codes and

their meanings.

Samples

A route which sends an SMS using the Java DSL:

from("direct:start")

.to("smpp://smppclient@localhost:2775?

password=password&enquireLinkTimer=3000&transactionTimer=5000&systemType=producer");

A route which sends an SMS using the Spring XML DSL:

<route>

<to uri="smpp://smppclient@localhost:2775?

password=password&enquireLinkTimer=3000&transactionTimer=5000&systemType=producer"/>

</route>

A route which receives an SMS using the Java DSL:

from("smpp://smppclient@localhost:2775?password=password&enquireLinkTimer=3000&transactionTimer=5000&systemType=consumer")

.to("bean:foo");

A route which receives an SMS using the Spring XML DSL:

<route>

<from uri="smpp://smppclient@localhost:2775?

password=password&enquireLinkTimer=3000&transactionTimer=5000&systemType=consumer"/>

CHAPTER 11 - COMPONENT APPENDIX 904

</route>

Debug logging

This component has log level DEBUG, which can be helpful in debugging

problems. If you use log4j, you can add the following line to your

conguration:

log4j.logger.org.apache.camel.component.smpp=DEBUG

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

SNMP COMPONENT

Available as of Camel 2.1

The snmp: component gives you the ability to poll SNMP capable devices

or receiving traps.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-snmp</artifactId>

</dependency>

URI format

snmp://hostname[:port][?Options]

The component supports polling OID values from an SNMP enabled device

and receiving traps.

905 CHAPTER 11 - COMPONENT APPENDIX

SMSC simulator

If you need an SMSC simulator for your test, you can use the

simulator provided by Logica.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Default

Value Description

type none

The type of action you want to perform. Actually you can enter here POLL or TRAP. The value POLL will instruct

the endpoint to poll a given host for the supplied OID keys. If you put in TRAP you will setup a listener for

SNMP Trap Events.

address none This is the IP address and the port of the host to poll or where to setup the Trap Receiver. Example:

127.0.0.1:162

protocol udp Here you can select which protocol to use. You can use either udp or tcp.

retries 2 Denes how often a retry is made before canceling the request.

timeout 1500 Sets the timeout value for the request in millis.

snmpVersion

0(which

means

SNMPv1)

Sets the snmp version for the request.

snmpCommunity public Sets the community octet string for the snmp request.

delay 60 seconds Denes the delay in seconds between to poll cycles.

oids none

Denes which values you are interested in. Please have a look at the Wikipedia to get a better understanding.

You may provide a single OID or a coma separated list of OIDs. Example:

oids="1.3.6.1.2.1.1.3.0,1.3.6.1.2.1.25.3.2.1.5.1,1.3.6.1.2.1.25.3.5.1.1.1,1.3.6.1.2.1.43.5.1.1.11.1"

The result of a poll

Given the situation, that I poll for the following OIDs:

Listing 88. OIDs

1.3.6.1.2.1.1.3.0

1.3.6.1.2.1.25.3.2.1.5.1

1.3.6.1.2.1.25.3.5.1.1.1

1.3.6.1.2.1.43.5.1.1.11.1

The result will be the following:

Listing 89. Result of toString conversion

<?xml version="1.0" encoding="UTF-8"?>

<snmp>

<entry>

</entry>

CHAPTER 11 - COMPONENT APPENDIX 906

<entry>

</entry>

<entry>

</entry>

<entry>

</entry>

<entry>

<value>My Very Special Printer Of Brand Unknown</value>

</entry>

</snmp>

As you maybe recognized there is one more result than

requested....1.3.6.1.2.1.1.1.0.

This one is lled in by the device automatically in this special case. So it may

absolutely happen, that you receive more than you requested...be prepared.

Examples

Polling a remote device:

snmp:192.168.178.23:161?protocol=udp&type=POLL&oids=1.3.6.1.2.1.1.5.0

Setting up a trap receiver (Note that no OID info is needed here!):

snmp:127.0.0.1:162?protocol=udp&type=TRAP

Routing example in Java: (converts the SNMP PDU to XML String)

from("snmp:192.168.178.23:161?protocol=udp&type=POLL&oids=1.3.6.1.2.1.1.5.0").

convertBodyTo(String.class).

to("activemq:snmp.states");

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

907 CHAPTER 11 - COMPONENT APPENDIX

SPRING INTEGRATION COMPONENT

The spring-integration: component provides a bridge for Camel

components to talk to spring integration endpoints.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-spring-integration</artifactId>

</dependency>

URI format

spring-integration:defaultChannelName[?options]

Where defaultChannelName represents the default channel name which is

used by the Spring Integration Spring context. It will equal to the

inputChannel name for the Spring Integration consumer and the

outputChannel name for the Spring Integration provider.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Type Description

inputChannel String The Spring integration input channel name that this endpoint wants to consume from, where the specied channel

name is dened in the Spring context.

outputChannel String The Spring integration output channel name that is used to send messages to the Spring integration context.

inOut String The exchange pattern that the Spring integration endpoint should use. If inOut=true then a reply channel is

expected, either from the Spring Integration Message header or congured on the endpoint.

Usage

The Spring integration component is a bridge that connects Camel endpoints

with Spring integration endpoints through the Spring integration's input

channels and output channels. Using this component, we can send Camel

messages to Spring Integration endpoints or receive messages from Spring

integration endpoints in a Camel routing context.

CHAPTER 11 - COMPONENT APPENDIX 908

Examples

Using the Spring integration endpoint

You can set up a Spring integration endpoint using a URI, as follows:

<beans:beans xmlns="http://www.springframework.org/schema/integration"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:beans="http://www.springframework.org/schema/beans"

xsi:schemaLocation="http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans.xsd

http://www.springframework.org/schema/integration

http://www.springframework.org/schema/integration/

spring-integration.xsd

http://camel.apache.org/schema/spring

http://camel.apache.org/schema/spring/camel-spring.xsd">

<service-activator input-channel="inputChannel" ref="helloService"

method="sayHello"/>

<service-activator input-channel="onewayChannel" ref="helloService"

method="greet"/>

<beans:bean id="helloService"

class="org.apache.camel.component.spring.integration.HelloWorldService"/>

<route>

<to

uri="spring-integration:inputChannel?inOut=true&inputChannel=outputChannel"/>

</route>

<route>

</route>

</camelContext>

<beans:bean id="myProcessor"

class="org.apache.camel.component.spring.integration.MyProcessor"/>

909 CHAPTER 11 - COMPONENT APPENDIX

<route>

<from

uri="spring-integration://requestChannel?outputChannel=responseChannel&inOut=true"/>

</route>

</camelContext>

Or directly using a Spring integration channel name:

<beans:beans xmlns="http://www.springframework.org/schema/integration"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:beans="http://www.springframework.org/schema/beans"

xsi:schemaLocation="http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans.xsd

http://www.springframework.org/schema/integration

http://www.springframework.org/schema/integration/

spring-integration.xsd

http://camel.apache.org/schema/spring

http://camel.apache.org/schema/spring/camel-spring.xsd">

<route>

</route>

</camelContext>

The Source and Target adapter

Spring integration also provides the Spring integration's source and target

adapters, which can route messages from a Spring integration channel to a

Camel endpoint or from a Camel endpoint to a Spring integration channel.

This example uses the following namespaces:

<beans:beans xmlns="http://www.springframework.org/schema/integration"

xmlns:beans="http://www.springframework.org/schema/beans"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:camel-si="http://camel.apache.org/schema/spring/integration"

xsi:schemaLocation="

http://www.springframework.org/schema/beans

http://www.springframework.org/schema/beans/spring-beans.xsd

http://www.springframework.org/schema/integration

CHAPTER 11 - COMPONENT APPENDIX 910

http://www.springframework.org/schema/integration/spring-integration.xsd

http://camel.apache.org/schema/spring/integration

http://camel.apache.org/schema/spring/integration/camel-spring-integration.xsd

http://camel.apache.org/schema/spring

http://camel.apache.org/schema/spring/camel-spring.xsd

You can bind your source or target to a Camel endpoint as follows:

<route>

</route>

<route>

</route>

</camelContext>

<!-- We can bind the camelTarget to the camel context's endpoint by specifying the

camelEndpointUri attribute -->

<camel-si:camelTarget id="camelTargetA" camelEndpointUri="direct:EndpointA"

expectReply="false">

<camel-si:camelContextRef>camelTargetContext</camel-si:camelContextRef>

</camel-si:camelTarget>

<camel-si:camelTarget id="camelTargetB" camelEndpointUri="direct:EndpointC"

replyChannel="channelC" expectReply="true">

<camel-si:camelContextRef>camelTargetContext</camel-si:camelContextRef>

</camel-si:camelTarget>

<camel-si:camelTarget id="camelTargetD" camelEndpointUri="direct:EndpointC"

expectReply="true">

<camel-si:camelContextRef>camelTargetContext</camel-si:camelContextRef>

</camel-si:camelTarget>

<beans:bean id="myProcessor"

class="org.apache.camel.component.spring.integration.MyProcessor"/>

<service-activator input-channel="channelB" output-channel="channelC"

ref="helloService" method="sayHello"/>

911 CHAPTER 11 - COMPONENT APPENDIX

<beans:bean id="helloService"

class="org.apache.camel.component.spring.integration.HelloWorldService"/>

<route>

</route>

<route>

</route>

</camelContext>

<!-- camelSource will redirect the message coming for direct:EndpointB to the spring

requestChannel channelA -->

<camel-si:camelSource id="camelSourceA" camelEndpointUri="direct:EndpointB"

requestChannel="channelA" expectReply="false">

<camel-si:camelContextRef>camelSourceContext</camel-si:camelContextRef>

</camel-si:camelSource>

<!-- camelSource will redirect the message coming for direct:EndpointC to the spring

requestChannel channelB

then it will pull the response from channelC and put the response message back

to direct:EndpointC -->

<camel-si:camelSource id="camelSourceB" camelEndpointUri="direct:EndpointC"

requestChannel="channelB" replyChannel="channelC"

expectReply="true">

<camel-si:camelContextRef>camelSourceContext</camel-si:camelContextRef>

</camel-si:camelSource>

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

SPRING WEB SERVICES COMPONENT

Available as of Camel 2.6

The spring-ws: component allows you to integrate with Spring Web

Services. It oers both client-side support, for accessing web services, and

server-side support for creating your own contract-rst web services.

Maven users will need to add the following dependency to their pom.xml

for this component:

CHAPTER 11 - COMPONENT APPENDIX 912

<groupId>org.apache.camel</groupId>

<artifactId>camel-spring-ws</artifactId>

</dependency>

URI format

The URI scheme for this component is as follows

spring-ws:[mapping-type:]address[?options]

To expose a web service mapping-type needs to be set to any of the

following:

Mapping

type Description

rootqname Oers the option to map web service requests based on the qualied name of the root element contained in the message.

soapaction Used to map web service requests based on the SOAP action specied in the header of the message.

uri In order to map web service requests that target a specic URI.

xpathresult Used to map web service requests based on the evaluation of an XPath expression against the incoming message. The

result of the evaluation should match the XPath result specied in the endpoint URI.

beanname Allows you to reference a org.apache.camel.component.spring.ws.bean.CamelEndpointDispatcher in order to integrate

with existing (legacy) endpoint mappings like PayloadRootQNameEndpointMapping,SoapActionEndpointMapping, etc

As a consumer the address should contain a value relevant to the specied

mapping-type (e.g. a SOAP action, XPath expression). As a producer the

address should be set to the URI of the web service your calling upon.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Required? Description

soapAction No SOAP action to include inside a SOAP request when accessing remote web services

wsAddressingAction No WS-Addressing 1.0 action header to include when accessing web services. The To header is set to

the address of the web service as specied in the endpoint URI (default Spring-WS behavior).

expression

Only when

mapping-type is

xpathresult

XPath expression to use in the process of mapping web service requests, should match the result

specied by xpathresult

Registry based options

The following options can be specied in the registry (most likely a Spring

ApplicationContext) and referenced from the endpoint URI using the #

notation.

913 CHAPTER 11 - COMPONENT APPENDIX

Dependencies

As of Camel 2.8 this component ships with Spring-WS 2.0.x which

(like the rest of Camel) requires Spring 3.0.x.

Earlier Camel versions shipped Spring-WS 1.5.9 which is compatible with

Spring 2.5.x and 3.0.x. In order to run earlier versions of camel-spring-ws

on Spring 2.5.x you need to add the spring-webmvc module from Spring

2.5.x. In order to run Spring-WS 1.5.9 on Spring 3.0.x you need to exclude

the OXM module from Spring 3.0.x as this module is also included in

Spring-WS 1.5.9 (see this post)

Name Required? Description

webServiceTemplate No

Option to provide a custom WebServiceTemplate. This allows for full control over client-side web

services handling; like adding a custom interceptor or specifying a fault resolver, message sender

or message factory.

messageSender No Option to provide a custom WebServiceMessageSender. For example to perform authentication or

use alternative transports

messageFactory No Option to provide a custom WebServiceMessageFactory. For example when you want Apache

Axiom to handle web service messages instead of SAAJ

transformerFactory No Option to override default TransformerFactory. The provided transformer factory must be of type

javax.xml.transform.TransformerFactory

endpointMapping

Only when

mapping-type is

rootqname,

soapaction,uri

or xpathresult

Reference to org.apache.camel.component.spring.ws.bean.CamelEndpointMapping in the

Registry/ApplicationContext. Only one bean is required in the registry to serve all Camel/Spring-WS

endpoints. This bean is auto-discovered by the MessageDispatcher and used to map requests to

Camel endpoints based on characteristics specied on the endpoint (like root QName, SOAP action,

etc)

Message headers

Name Type Description

CamelSpringWebserviceEndpointUri String URI of the web service your accessing as a client, overrides address part of the

endpoint URI

CamelSpringWebserviceSoapAction String Header to specify the SOAP action of the message, overrides soapAction option if

present

CamelSpringWebserviceAddressingAction URI Use this header to specify the WS-Addressing action of the message, overrides

wsAddressingAction option if present

ACCESSING WEB SERVICES

To call a web service at http://foo.com/bar simply dene a route:

from("direct:example").to("spring-ws:http://foo.com/bar")

And sent a message:

template.requestBody("direct:example","<foobar xmlns=\"http://foo.com\"><msg>test

message</msg></foobar>");

CHAPTER 11 - COMPONENT APPENDIX 914

Remember if it's a SOAP service you're calling you don't have to include

SOAP tags. Spring-WS will perform the XML-to-SOAP marshaling.

Sending SOAP and WS-Addressing action headers

When a remote web service requires a SOAP action or use of the WS-

Addressing standard you dene your route as:

from("direct:example")

.to("spring-ws:http://foo.com/

bar?soapAction=http://foo.com&wsAddressingAction=http://bar.com")

Optionally you can override the endpoint options with header values:

template.requestBodyAndHeader("direct:example",

"<foobar xmlns=\"http://foo.com\"><msg>test message</msg></foobar>",

SpringWebserviceConstants.SPRING_WS_SOAP_ACTION, "http://baz.com");

Using a custom MessageSender and MessageFactory

A custom message sender or factory in the registry can be referenced like

this:

from("direct:example")

.to("spring-ws:http://foo.com/

bar?messageFactory=#messageFactory&messageSender=#messageSender")

Spring conguration:

<bean id="messageSender"

class="org.springframework.ws.transport.http.CommonsHttpMessageSender">

<bean

class="org.apache.commons.httpclient.UsernamePasswordCredentials">

<constructor-arg index="0" value="admin"/>

<constructor-arg index="1" value="secret"/>

</bean>

</property>

</bean>

<!-- force use of Sun SAAJ implementation, http://static.springsource.org/spring-ws/

sites/1.5/faq.html#saaj-jboss -->

<bean id="messageFactory"

class="org.springframework.ws.soap.saaj.SaajSoapMessageFactory">

<bean

915 CHAPTER 11 - COMPONENT APPENDIX

class="com.sun.xml.messaging.saaj.soap.ver1_1.SOAPMessageFactory1_1Impl"></bean>

</property>

</bean>

EXPOSING WEB SERVICES

In order to expose a web service using this component you rst need to set-

up a MessageDispatcher to look for endpoint mappings in a Spring XML le. If

you plan on running inside a servlet container you probably want to use a

MessageDispatcherServlet congured in web.xml.

By default the MessageDispatcherServlet will look for a Spring XML

named /WEB-INF/spring-ws-servlet.xml. To use Camel with Spring-WS the

only mandatory bean in that XML le is CamelEndpointMapping. This bean

allows the MessageDispatcher to dispatch web service requests to your

routes.

web.xml

<web-app>

<servlet-name>spring-ws</servlet-name>

<servlet-class>org.springframework.ws.transport.http.MessageDispatcherServlet</servlet-class>

<load-on-startup>1</load-on-startup>

</servlet>

<servlet-mapping>

<servlet-name>spring-ws</servlet-name>

<url-pattern>/*</url-pattern>

</servlet-mapping>

</web-app>

spring-ws-servlet.xml

<bean id="endpointMapping"

class="org.apache.camel.component.spring.ws.bean.CamelEndpointMapping" />

<bean

class="org.springframework.xml.xsd.SimpleXsdSchema">

</bean>

</property>

</bean>

CHAPTER 11 - COMPONENT APPENDIX 916

More information on setting up Spring-WS can be found in Writing Contract-

First Web Services. Basically paragraph 3.6 "Implementing the Endpoint" is

handled by this component (specically paragraph 3.6.2 "Routing the

Message to the Endpoint" is where CamelEndpointMapping comes in). Also

don't forget to check out the Spring Web Services Example included in the

Camel distribution.

Endpoint mapping in routes

With the XML conguration in-place you can now use Camel's DSL to dene

what web service requests are handled by your endpoint:

The following route will receive all web service requests that have a root

element named "GetFoo" within the http://example.com/ namespace.

from("spring-ws:rootqname:{http://example.com/

}GetFoo?endpointMapping=#endpointMapping")

.convertBodyTo(String.class).to(mock:example)

The following route will receive web service requests containing the

http://example.com/GetFoo SOAP action.

from("spring-ws:soapaction:http://example.com/

GetFoo?endpointMapping=#endpointMapping")

.convertBodyTo(String.class).to(mock:example)

The following route will receive all requests sent to http://example.com/

foobar.

from("spring-ws:uri:http://example.com/foobar?endpointMapping=#endpointMapping")

.convertBodyTo(String.class).to(mock:example)

The route below will receive requests that contain the element

<foobar>abc</foobar> anywhere inside the message (and the default

namespace).

from("spring-ws:xpathresult:abc?expression=//foobar&endpointMapping=#endpointMapping")

.convertBodyTo(String.class).to(mock:example)

Alternative conguration, using existing endpoint mappings

For every endpoint with mapping-type beanname one bean of type

CamelEndpointDispatcher with a corresponding name is required in the

Registry/ApplicationContext. This bean acts as a bridge between the Camel

917 CHAPTER 11 - COMPONENT APPENDIX

endpoint and an existing endpoint mapping like

PayloadRootQNameEndpointMapping.

An example of a route using beanname:

<route>

</route>

</camelContext>

<bean id="legacyEndpointMapping"

class="org.springframework.ws.server.endpoint.mapping.PayloadRootQNameEndpointMapping">

<props>

<prop key="{http://example.com/}GetFuture">FutureEndpointDispatcher</prop>

<prop key="{http://example.com/}GetQuote">QuoteEndpointDispatcher</prop>

</props>

</property>

</bean>

<bean id="QuoteEndpointDispatcher"

class="org.apache.camel.component.spring.ws.bean.CamelEndpointDispatcher" />

<bean id="FutureEndpointDispatcher"

class="org.apache.camel.component.spring.ws.bean.CamelEndpointDispatcher" />

POJO (UN)MARSHALLING

Camel's pluggable data formats oer support for pojo/xml marshalling using

libraries such as JAXB, XStream, JibX, Castor and XMLBeans. You can use

these data formats in your route to sent and receive pojo's, to and from web

services.

When accessing web services you can marshal the request and unmarshal

the response message:

JaxbDataFormat jaxb = new JaxbDataFormat(false);

jaxb.setContextPath("com.example.model");

from("direct:example").marshal(jaxb).to("spring-ws:http://foo.com/

bar").unmarshal(jaxb);

Similarly when providing web services, you can unmarshal XML requests to

POJO's and marshal the response message back to XML:

from("spring-ws:rootqname:{http://example.com/

}GetFoo?endpointMapping=#endpointMapping").unmarshal(jaxb)

.to("mock:example").marshal(jaxb);

CHAPTER 11 - COMPONENT APPENDIX 918

The use of the beanname mapping-type is primarily meant for

(legacy) situations where you're already using Spring-WS and have

endpoint mappings dened in a Spring XML le. The beanname

mapping-type allows you to wire your Camel route into an existing

endpoint mapping. When you're starting from scratch it's

recommended to dene your endpoint mappings as Camel URI's (as

illustrated above with endpointMapping) since it requires less

conguration and is more expressive. Alternatively you could use

vanilla Spring-WS with the help of annotations.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

STREAM COMPONENT

The stream: component provides access to the System.in,System.out and

System.err streams as well as allowing streaming of le and URL.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-stream</artifactId>

</dependency>

URI format

stream:in[?options]

stream:out[?options]

stream:err[?options]

stream:header[?options]

In addition, the file and url endpoint URIs are supported in Camel 2.0:

919 CHAPTER 11 - COMPONENT APPENDIX

stream:file?fileName=/foo/bar.txt

stream:url[?options]

If the stream:header URI is specied, the stream header is used to nd the

stream to write to. This option is available only for stream producers (that is,

it cannot appear in from()).

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Default

Value Description

delay 0 Initial delay in milliseconds before consuming or producing the stream.

encoding JVM Default As of 1.4, you can congure the encoding (is a charset name) to use text-based streams (for example,

message body is a String object). If not provided, Camel uses the JVM default Charset.

promptMessage null Camel 2.0: Message prompt to use when reading from stream:in; for example, you could set this to

Enter a command:

promptDelay 0 Camel 2.0: Optional delay in milliseconds before showing the message prompt.

initialPromptDelay 2000

Camel 2.0: Initial delay in milliseconds before showing the message prompt. This delay occurs only

once. Can be used during system startup to avoid message prompts being written while other logging

is done to the system out.

fileName null Camel 2.0: When using the stream:file URI format, this option species the lename to stream to/

from.

scanStream false Camel 2.0: To be used for continuously reading a stream such as the unix tail command.

Camel 2.4 to Camel 2.6: will retry opening the le if it is overwritten, somewhat like tail --retry

retry false Camel 2.7: will retry opening the le if it's overwritten, somewhat like tail --retry

scanStreamDelay 0 Camel 2.0: Delay in milliseconds between read attempts when using scanStream.

groupLines 0 Camel 2.5: To group X number of lines in the consumer. For example to group 10 lines and therefore

only spit out an Exchange with 10 lines, instead of 1 Exchange per line.

Message content

The stream: component supports either String or byte[] for writing to

streams. Just add either String or byte[] content to the message.in.body.

The special stream:header URI is used for custom output streams. Just add a

java.io.OutputStream object to message.in.header in the key header.

See samples for an example.

Samples

In the following sample we route messages from the direct:in endpoint to

the System.out stream:

@Test

public void testStringContent() throws Exception {

template.sendBody("direct:in","Hello Text World\n");

CHAPTER 11 - COMPONENT APPENDIX 920

}

@Test

public void testBinaryContent() {

template.sendBody("direct:in","Hello Bytes World\n".getBytes());

}

protected RouteBuilder createRouteBuilder() {

return new RouteBuilder() {

public void configure() {

from("direct:in").to("stream:out");

}

};

}

The following sample demonstrates how the header type can be used to

determine which stream to use. In the sample we use our own output stream,

MyOutputStream.

private OutputStream mystream = new MyOutputStream();

private StringBuffer sb = new StringBuffer();

@Test

public void testStringContent() {

template.sendBody("direct:in","Hello");

// StreamProducer appends \n in text mode

assertEquals("Hello\n", sb.toString());

}

@Test

public void testBinaryContent() {

template.sendBody("direct:in","Hello".getBytes());

// StreamProducer is in binary mode so no \n is appended

assertEquals("Hello", sb.toString());

}

protected RouteBuilder createRouteBuilder() {

return new RouteBuilder() {

public void configure() {

from("direct:in").setHeader("stream", constant(mystream)).

to("stream:header");

}

};

}

private class MyOutputStream extends OutputStream {

public void write(int b) throws IOException {

sb.append((char)b);

}

921 CHAPTER 11 - COMPONENT APPENDIX

The following sample demonstrates how to continuously read a le stream

(analogous to the UNIX tail command):

from("stream:file?fileName=/server/logs/

server.log&scanStream=true&scanStreamDelay=1000").to("bean:logService?method=parseLogLine");

One gotcha with scanStream (pre Camel 2.7) or scanStream + retry is the le

will be re-opened and scanned with each iteration of scanStreamDelay. Until

NIO2 is available we cannot reliably detect when a le is deleted/recreated.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

STRING TEMPLATE

The string-template: component allows you to process a message using a

String Template. This can be ideal when using Templating to generate

responses for requests.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-stringtemplate</artifactId>

</dependency>

URI format

string-template:templateName[?options]

Where templateName is the classpath-local URI of the template to invoke;

or the complete URL of the remote template.

You can append query options to the URI in the following format,

?option=value&option=value&...

CHAPTER 11 - COMPONENT APPENDIX 922

Options

Option Default Description

contentCache false New option in Camel 1.4. Cache for the resource content when its loaded.

Headers

Camel will store a reference to the resource in the message header with key,

org.apache.camel.stringtemplate.resource. The Resource is an

org.springframework.core.io.Resource object.

Hot reloading

The string template resource is by default hot-reloadable for both le and

classpath resources (expanded jar). If you set contentCache=true, Camel

loads the resource only once and hot-reloading is not possible. This scenario

can be used in production when the resource never changes.

StringTemplate Attributes

Camel will provide exchange information as attributes (just a

java.util.Map) to the string template. The Exchange is transfered as:

key value

exchange The Exchange itself.

headers The headers of the In message.

camelContext The Camel Context.

request The In message.

in The In message.

body The In message body.

out The Out message (only for InOut message exchange pattern).

response The Out message (only for InOut message exchange pattern).

Samples

For example you could use a string template as follows in order to formulate

a response to a message:

from("activemq:My.Queue").

to("string-template:com/acme/MyResponse.tm");

The Email Sample

In this sample we want to use a string template to send an order

conrmation email. The email template is laid out in StringTemplate as:

923 CHAPTER 11 - COMPONENT APPENDIX

Dear $headers.lastName$, $headers.firstName$

Thanks for the order of $headers.item$.

Regards Camel Riders Bookstore

$body$

And the java code is as follows:

private Exchange createLetter() {

Exchange exchange = context.getEndpoint("direct:a").createExchange();

Message msg = exchange.getIn();

msg.setHeader("firstName","Claus");

msg.setHeader("lastName","Ibsen");

msg.setHeader("item","Camel in Action");

msg.setBody("PS: Next beer is on me, James");

return exchange;

}

@Test

public void testVelocityLetter() throws Exception {

MockEndpoint mock = getMockEndpoint("mock:result");

mock.expectedMessageCount(1);

mock.expectedBodiesReceived("Dear Ibsen, Claus! Thanks for the order of Camel in

Action. Regards Camel Riders Bookstore PS: Next beer is on me, James");

template.send("direct:a", createLetter());

mock.assertIsSatisfied();

}

protected RouteBuilder createRouteBuilder() throws Exception {

return new RouteBuilder() {

public void configure() throws Exception {

from("direct:a").to("string-template:org/apache/camel/component/

stringtemplate/letter.tm").to("mock:result");

}

};

}

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

CHAPTER 11 - COMPONENT APPENDIX 924

SQL COMPONENT

The sql: component allows you to work with databases using JDBC queries.

The dierence between this component and JDBC component is that in case

of SQL the query is a property of the endpoint and it uses message payload

as parameters passed to the query.

This component uses spring-jdbc behind the scenes for the actual SQL

handling.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-sql</artifactId>

</dependency>

The SQL component also supports:

▪ a JDBC based repository for the Idempotent Consumer EIP pattern.

See further below.

▪ a JDBC based repository for the Aggregator EIP pattern. See further

below.

URI format

The SQL component uses the following endpoint URI notation:

sql:select * from table where id=# order by name[?options]

Notice that the standard ?symbol that denotes the parameters to an SQL

query is substituted with the #symbol, because the ?symbol is used to

specify options for the endpoint. The ?symbol replacement can be

congured on endpoint basis.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Option Type Default Description

dataSourceRef String null

Camel 1.5.1/2.0: Reference to a

DataSource to look up in the

registry.

925 CHAPTER 11 - COMPONENT APPENDIX

The SQL component can only be used to dene producer endpoints.

In other words, you cannot dene an SQL endpoint in a from()

statement.

This component can be used as a Transactional Client.

placeholder String #

Camel 2.4: Species a character

that will be replaced to ?in SQL

query. Notice, that it is simple

String.replaceAll() operation

and no SQL parsing is involved

(quoted strings will also change)

template.<xxx> null

Sets additional options on the

Spring JdbcTemplate that is used

behind the scenes to execute the

queries. For instance,

template.maxRows=10. For detailed

documentation, see the

JdbcTemplate javadoc

documentation.

Treatment of the message body

The SQL component tries to convert the message body to an object of

java.util.Iterator type and then uses this iterator to ll the query

parameters (where each query parameter is represented by a #symbol (or

congured placeholder) in the endpoint URI). If the message body is not an

array or collection, the conversion results in an iterator that iterates over

only one object, which is the body itself.

For example, if the message body is an instance of java.util.List, the

rst item in the list is substituted into the rst occurrence of #in the SQL

query, the second item in the list is substituted into the second occurrence of

#, and so on.

Result of the query

For select operations, the result is an instance of List<Map<String,

Object>> type, as returned by the JdbcTemplate.queryForList() method. For

CHAPTER 11 - COMPONENT APPENDIX 926

update operations, the result is the number of updated rows, returned as an

Integer.

Header values

When performing update operations, the SQL Component stores the update

count in the following message headers:

Header Description

SqlProducer.UPDATE_COUNT

Camel 1.x: The number of rows updated for

update operations, returned as an Integer

object.

CamelSqlUpdateCount

Camel 2.0: The number of rows updated for

update operations, returned as an Integer

object.

CamelSqlRowCount

Camel 2.0: The number of rows returned for

select operations, returned as an Integer

object.

CamelSqlQuery

Camel 2.8: Query to execute. This query

takes precedence over the query specied

in the endpoint URI. Note that query

parameters in the header are represented

by a ?instead of a #symbol

Conguration in Camel 1.5.0 or lower

The SQL component must be congured before it can be used. In Spring, you

can congure it as follows:

</bean>

</bean>

Conguration in Camel 1.5.1 or higher

You can now set a reference to a DataSource in the URI directly:

927 CHAPTER 11 - COMPONENT APPENDIX

sql:select * from table where id=# order by name?dataSourceRef=myDS

Sample

In the sample below we execute a query and retrieve the result as a List of

rows, where each row is a Map<String, Object and the key is the column

name.

First, we set up a table to use for our sample. As this is based on an unit

test, we do it java code:

// this is the database we create with some initial data for our unit test

jdbcTemplate.execute("create table projects (id integer primary key,"

+"project varchar(10), license varchar(5))");

jdbcTemplate.execute("insert into projects values (1, 'Camel', 'ASF')");

jdbcTemplate.execute("insert into projects values (2, 'AMQ', 'ASF')");

jdbcTemplate.execute("insert into projects values (3, 'Linux', 'XXX')");

Then we congure our route and our sql component. Notice that we use a

direct endpoint in front of the sql endpoint. This allows us to send an

exchange to the direct endpoint with the URI, direct:simple, which is

much easier for the client to use than the long sql: URI. Note that the

DataSource is looked up up in the registry, so we can use standard Spring

XML to congure our DataSource.

from("direct:simple")

.to("sql:select * from projects where license = # order by id?dataSourceRef=jdbc/

myDataSource")

.to("mock:result");

And then we re the message into the direct endpoint that will route it to

our sql component that queries the database.

MockEndpoint mock = getMockEndpoint("mock:result");

mock.expectedMessageCount(1);

// send the query to direct that will route it to the sql where we will execute the

query

// and bind the parameters with the data from the body. The body only contains one

value

// in this case (XXX) but if we should use multi values then the body will be iterated

// so we could supply a List<String> instead containing each binding value.

template.sendBody("direct:simple","XXX");

mock.assertIsSatisfied();

CHAPTER 11 - COMPONENT APPENDIX 928

// the result is a List

List<?> received = assertIsInstanceOf(List.class,

mock.getReceivedExchanges().get(0).getIn().getBody());

// and each row in the list is a Map

Map<?, ?> row = assertIsInstanceOf(Map.class, received.get(0));

// and we should be able the get the project from the map that should be Linux

assertEquals("Linux", row.get("PROJECT"));

We could congure the DataSource in Spring XML as follows:

<jee:jndi-lookup id="myDS" jndi-name="jdbc/myDataSource"/>

Using the JDBC based idempotent repository

Available as of Camel 2.7: In this section we will use the JDBC based

idempotent repository.

First we have to create the database table which will be used by the

idempotent repository. For Camel 2.7, we use the follwing schema:

CREATE TABLE CAMEL_MESSAGEPROCESSED (

processorName VARCHAR(255),

messageId VARCHAR(100)

)

In Camel 2.8, we added the createdAt column:

CREATE TABLE CAMEL_MESSAGEPROCESSED (

processorName VARCHAR(255),

messageId VARCHAR(100),

createdAt TIMESTAMP

)

We recommend to have a unique constraint on the columns processorName

and messageId. Because the syntax for this constraint diers for database to

database, we do not show it here.

Second we need to setup a javax.sql.DataSource in the spring XML le:

<bean id="dataSource"

class="org.springframework.jdbc.datasource.SingleConnectionDataSource">

929 CHAPTER 11 - COMPONENT APPENDIX

</bean>

And nally we can create our JDBC idempotent repository in the spring XML

le as well:

<bean id="messageIdRepository"

class="org.apache.camel.processor.idempotent.jdbc.JdbcMessageIdRepository">

<constructor-arg ref="dataSource" />

<constructor-arg value="myProcessorName" />

</bean>

<camel:camelContext>

<camel:errorHandler id="deadLetterChannel" type="DeadLetterChannel"

deadLetterUri="mock:error">

<camel:redeliveryPolicy maximumRedeliveries="0"

maximumRedeliveryDelay="0" logStackTrace="false" />

</camel:errorHandler>

<camel:route id="JdbcMessageIdRepositoryTest"

errorHandlerRef="deadLetterChannel">

<camel:from uri="direct:start" />

<camel:idempotentConsumer

messageIdRepositoryRef="messageIdRepository">

<camel:header>messageId</camel:header>

<camel:to uri="mock:result" />

</camel:idempotentConsumer>

</camel:route>

</camel:camelContext>

Using the JDBC based aggregation repository

Available as of Camel 2.6

JdbcAggregationRepository is an AggregationRepository which on the y

persists the aggregated messages. This ensures that you will not loose

messages, as the default aggregator will use an in memory only

AggregationRepository.

The JdbcAggregationRepository allows together with Camel to provide

persistent support for the Aggregator.

It has the following options:

Option Type Description

dataSource DataSource Mandatory: The javax.sql.DataSource to use for accessing the

database.

repositoryName String Mandatory: The name of the repository.

CHAPTER 11 - COMPONENT APPENDIX 930

Using JdbcAggregationRepository in Camel 2.6

In Camel 2.6, the JdbcAggregationRepository is provided in the

camel-jdbc-aggregator component. From Camel 2.7 onwards, the

JdbcAggregationRepository is provided in the camel-sql

component.

transactionManager TransactionManager

Mandatory: The

org.springframework.transaction.PlatformTransactionManager

to mange transactions for the database. The TransactionManager

must be able to support databases.

lobHandler LobHandler

Aorg.springframework.jdbc.support.lob.LobHandler to handle

Lob types in the database. Use this option to use a vendor specic

LobHandler, for example when using Oracle.

returnOldExchange boolean

Whether the get operation should return the old existing Exchange if

any existed. By default this option is false to optimize as we do not

need the old exchange when aggregating.

useRecovery boolean

Whether or not recovery is enabled. This option is by default true.

When enabled the Camel Aggregator automatic recover failed

aggregated exchange and have them resubmitted.

recoveryInterval long

If recovery is enabled then a background task is run every x'th time

to scan for failed exchanges to recover and resubmit. By default this

interval is 5000 millis.

maximumRedeliveries int

Allows you to limit the maximum number of redelivery attempts for a

recovered exchange. If enabled then the Exchange will be moved to

the dead letter channel if all redelivery attempts failed. By default

this option is disabled. If this option is used then the deadLetterUri

option must also be provided.

deadLetterUri String

An endpoint uri for a Dead Letter Channel where exhausted

recovered Exchanges will be moved. If this option is used then the

maximumRedeliveries option must also be provided.

What is preserved when persisting

JdbcAggregationRepository will only preserve any Serializable

compatible data types. If a data type is not such a type its dropped and a

WARN is logged. And it only persists the Message body and the Message

headers. The Exchange properties are not persisted.

931 CHAPTER 11 - COMPONENT APPENDIX

Recovery

The JdbcAggregationRepository will by default recover any failed

Exchange. It does this by having a background tasks that scans for failed

Exchanges in the persistent store. You can use the checkInterval option to

set how often this task runs. The recovery works as transactional which

ensures that Camel will try to recover and redeliver the failed Exchange. Any

Exchange which was found to be recovered will be restored from the

persistent store and resubmitted and send out again.

The following headers is set when an Exchange is being recovered/

redelivered:

Header Type Description

Exchange.REDELIVERED Boolean

Is set to true to indicate the

Exchange is being

redelivered.

Exchange.REDELIVERY_COUNTER Integer The redelivery attempt,

starting from 1.

Only when an Exchange has been successfully processed it will be marked as

complete which happens when the confirm method is invoked on the

AggregationRepository. This means if the same Exchange fails again it will

be kept retried until it success.

You can use option maximumRedeliveries to limit the maximum number

of redelivery attempts for a given recovered Exchange. You must also set the

deadLetterUri option so Camel knows where to send the Exchange when

the maximumRedeliveries was hit.

You can see some examples in the unit tests of camel-sql, for example this

test.

Database

To be operational, each aggregator uses two table: the aggregation and

completed one. By convention the completed has the same name as the

aggregation one suxed with "_COMPLETED". The name must be congured

in the Spring bean with the RepositoryName property. In the following

example aggregation will be used.

The table structure denition of both table are identical: in both case a

String value is used as key (id) whereas a Blob contains the exchange

serialized in byte array.

However one dierence should be remembered: the id eld does not have

the same content depending on the table.

In the aggregation table id holds the correlation Id used by the component to

CHAPTER 11 - COMPONENT APPENDIX 932

aggregate the messages. In the completed table, id holds the id of the

exchange stored in corresponding the blob eld.

Here is the SQL query used to create the tables, just replace

"aggregation" with your aggregator repository name.

CREATE TABLE aggregation (

id varchar(255) NOT NULL,

exchange blob NOT NULL,

constraint aggregation_pk PRIMARY KEY (id)

);

CREATE TABLE aggregation_completed (

id varchar(255) NOT NULL,

exchange blob NOT NULL,

constraint aggregation_completed_pk PRIMARY KEY (id)

);

Codec (Serialization)

Since they can contain any type of payload, Exchanges are not serializable

by design. It is converted into a byte array to be stored in a database BLOB

eld. All those conversions are handled by the JdbcCodec class. One detail of

the code requires your attention: the

ClassLoadingAwareObjectInputStream.

The ClassLoadingAwareObjectInputStream has been reused from the

Apache ActiveMQ project. It wraps an ObjectInputStream and use it with the

ContextClassLoader rather than the currentThread one. The benet is to

be able to load classes exposed by other bundles. This allows the exchange

body and headers to have custom types object references.

Transaction

A Spring PlatformTransactionManager is required to orchestrate

transaction.

Service (Start/Stop)

The start method verify the connection of the database and the presence of

the required tables. If anything is wrong it will fail during starting.

933 CHAPTER 11 - COMPONENT APPENDIX

Aggregator conguration

Depending on the targeted environment, the aggregator might need some

conguration. As you already know, each aggregator should have its own

repository (with the corresponding pair of table created in the database) and

a data source. If the default lobHandler is not adapted to your database

system, it can be injected with the lobHandler property.

Here is the declaration for Oracle:

<bean id="lobHandler"

class="org.springframework.jdbc.support.lob.OracleLobHandler">

</bean>

<bean id="nativeJdbcExtractor"

class="org.springframework.jdbc.support.nativejdbc.CommonsDbcpNativeJdbcExtractor"/>

<bean id="repo"

class="org.apache.camel.processor.aggregate.jdbc.JdbcAggregationRepository">

</bean>

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ JDBC

TEST COMPONENT

Testing of distributed and asynchronous processing is notoriously dicult.

The Mock, Test and DataSet endpoints work great with the Camel Testing

Framework to simplify your unit and integration testing using Enterprise

Integration Patterns and Camel's large range of Components together with

the powerful Bean Integration.

The test component extends the Mock component to support pulling

messages from another endpoint on startup to set the expected message

bodies on the underlying Mock endpoint. That is, you use the test endpoint in

a route and messages arriving on it will be implicitly compared to some

expected messages extracted from some other location.

CHAPTER 11 - COMPONENT APPENDIX 934

So you can use, for example, an expected set of message bodies as les.

This will then set up a properly congured Mock endpoint, which is only valid

if the received messages match the number of expected messages and their

message payloads are equal.

Maven users will need to add the following dependency to their pom.xml

for this component when using Camel 2.8 or older:

<groupId>org.apache.camel</groupId>

<artifactId>camel-spring</artifactId>

</dependency>

From Camel 2.9 onwards the Test component is provided directly in the

camel-core.

URI format

test:expectedMessagesEndpointUri

Where expectedMessagesEndpointUri refers to some other Component

URI that the expected message bodies are pulled from before starting the

test.

Example

For example, you could write a test case as follows:

from("seda:someEndpoint").

to("test:file://data/expectedOutput?noop=true");

If your test then invokes the MockEndpoint.assertIsSatised(camelContext)

method, your test case will perform the necessary assertions.

To see how you can set other expectations on the test endpoint, see the

Mock component.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

935 CHAPTER 11 - COMPONENT APPENDIX

• Spring Testing

TIMER COMPONENT

The timer: component is used to generate message exchanges when a timer

res You can only consume events from this endpoint.

URI format

timer:name[?options]

Where name is the name of the Timer object, which is created and shared

across endpoints. So if you use the same name for all your timer endpoints,

only one Timer object and thread will be used.

You can append query options to the URI in the following format,

?option=value&option=value&...

Note: The IN body of the generated exchange is null. So

exchange.getIn().getBody() returns null.

Options

Name Default

Value Description

time null Ajava.util.Date the rst event should be generated. If using the URI, the pattern expected is: yyyy-MM-dd

HH:mm:ss or yyyy-MM-dd'T'HH:mm:ss.

pattern null Allows you to specify a custom Date pattern to use for setting the time option using URI syntax.

period 1000 If greater than 0, generate periodic events every period milliseconds.

delay 0 The number of milliseconds to wait before the rst event is generated. Should not be used in conjunction with

the time option.

fixedRate false Events take place at approximately regular intervals, separated by the specied period.

daemon true Species whether or not the thread associated with the timer endpoint runs as a daemon.

repeatCount 0 Camel 2.8: Species a maximum limit of number of res. So if you set it to 1, the timer will only re once. If

you set it to 5, it will only re ve times. A value of zero or negative means re forever.

Exchange Properties

When the timer is red, it adds the following information as properties to the

Exchange:

Name Type Description

Exchange.TIMER_NAME String The value of the name option.

Exchange.TIMER_TIME Date The value of the time option.

Exchange.TIMER_PERIOD long The value of the period option.

Exchange.TIMER_FIRED_TIME Date The time when the consumer red.

Exchange.TIMER_COUNTER Long Camel 2.8: The current re counter. Starts from 1.

CHAPTER 11 - COMPONENT APPENDIX 936

Advanced Scheduler

See also the Quartz component that supports much more advanced

scheduling.

Specify time in human friendly format

In Camel 2.3 onwards you can specify the time in human friendly

syntax.

Message Headers

When the timer is red, it adds the following information as headers to the IN

message

Name Type Description

Exchange.TIMER_FIRED_TIME java.util.Date The time when the consumer red

Sample

To set up a route that generates an event every 60 seconds:

from("timer://foo?fixedRate=true&period=60000").to("bean:myBean?method=someMethodName");

The above route will generate an event and then invoke the someMethodName

method on the bean called myBean in the Registry such as JNDI or Spring.

And the route in Spring DSL:

<route>

</route>

Firing only once

Available as of Camel 2.8

You may want to re a message in a Camel route only once, such as when

starting the route. To do that you use the repeatCount option as shown:

937 CHAPTER 11 - COMPONENT APPENDIX

Instead of 60000 you can use period=60s which is more friendly to

read.

<route>

</route>

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

• Quartz

VALIDATION COMPONENT

The Validation component performs XML validation of the message body

using the JAXP Validation API and based on any of the supported XML schema

languages, which defaults to XML Schema

Note that the Jing component also supports the following useful schema

languages:

• RelaxNG Compact Syntax

• RelaxNG XML Syntax

The MSV component also supports RelaxNG XML Syntax.

URI format

validator:someLocalOrRemoteResource

Where someLocalOrRemoteResource is some URL to a local resource on

the classpath or a full URL to a remote resource or resource on the le

system which contains the XSD to validate against. For example:

•msv:org/foo/bar.xsd

•msv:file:../foo/bar.xsd

•msv:http://acme.com/cheese.xsd

•validator:com/mypackage/myschema.xsd

CHAPTER 11 - COMPONENT APPENDIX 938

Maven users will need to add the following dependency to their pom.xml for

this component when using Camel 2.8 or older:

<groupId>org.apache.camel</groupId>

<artifactId>camel-spring</artifactId>

</dependency>

From Camel 2.9 onwards the Validation component is provided directly in the

camel-core.

Options

Option Default Description

useDom false Camel 2.0: Whether DOMSource/DOMResult or SaxSource/SaxResult should be used by the validator.

useSharedSchema true Camel 2.3: Whether the Schema instance should be shared or not. This option is introduced to work around

a JDK 1.6.x bug. Xerces should not have this issue.

Example

The following example shows how to congure a route from endpoint

direct:start which then goes to one of two endpoints, either mock:valid or

mock:invalid based on whether or not the XML matches the given schema

(which is supplied on the classpath).

<route>

<doTry>

<exception>org.apache.camel.ValidationException</exception>

</doCatch>

</doFinally>

</doTry>

</route>

</camelContext>

See Also

• Conguring Camel

939 CHAPTER 11 - COMPONENT APPENDIX

• Component

• Endpoint

• Getting Started

VELOCITY

The velocity: component allows you to process a message using an Apache

Velocity template. This can be ideal when using Templating to generate

responses for requests.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-velocity</artifactId>

</dependency>

URI format

velocity:templateName[?options]

Where templateName is the classpath-local URI of the template to invoke;

or the complete URL of the remote template (eg: le://folder/myle.vm).

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Option Default Description

loaderCache true Velocity based le loader cache.

contentCache New option in Camel 1.4: Cache for the resource content when it is loaded. By default, it's false in Camel

1.x. By default, it's true in Camel 2.x.

encoding null New option in Camel 1.6: Character encoding of the resource content.

propertiesFile null New option in Camel 2.1: The URI of the properties le which is used for VelocityEngine initialization.

Message Headers

The velocity component sets a couple headers on the message (you can't set

these yourself and from Camel 2.1 velocity component will not set these

headers which will cause some side eect on the dynamic template support):

CHAPTER 11 - COMPONENT APPENDIX 940

Header Description

org.apache.camel.velocity.resource Camel 1.x: The resource as an org.springframework.core.io.Resource object.

org.apache.camel.velocity.resourceUri Camel 1.x: The templateName as a String object.

CamelVelocityResource Camel 2.0: The resource as an org.springframework.core.io.Resource object.

CamelVelocityResourceUri Camel 2.0: The templateName as a String object.

In Camel 1.4 headers set during the Velocity evaluation are returned to the

message and added as headers. Then its kinda possible to return values from

Velocity to the Message.

For example, to set the header value of fruit in the Velocity template

.tm:

$in.setHeader('fruit', 'Apple')

The fruit header is now accessible from the message.out.headers.

Velocity Context

Camel will provide exchange information in the Velocity context (just a Map).

The Exchange is transfered as:

key value

exchange The Exchange itself.

exchange.properties The Exchange properties.

headers The headers of the In message.

camelContext The Camel Context intance.

request The In message.

in The In message.

body The In message body.

out The Out message (only for InOut message exchange pattern).

response The Out message (only for InOut message exchange pattern).

Hot reloading

The Velocity template resource is, by default, hot reloadable for both le and

classpath resources (expanded jar). If you set contentCache=true, Camel

will only load the resource once, and thus hot reloading is not possible. This

scenario can be used in production, when the resource never changes.

Dynamic templates

Available as of Camel 2.1

Camel provides two headers by which you can dene a dierent resource

location for a template or the template content itself. If any of these headers

is set then Camel uses this over the endpoint congured resource. This

allows you to provide a dynamic template at runtime.

941 CHAPTER 11 - COMPONENT APPENDIX

Header Type Description

CamelVelocityResourceUri String Camel 2.1: A URI for the template resource to use instead of the endpoint congured.

CamelVelocityTemplate String Camel 2.1: The template to use instead of the endpoint congured.

Samples

For example you could use something like

from("activemq:My.Queue").

to("velocity:com/acme/MyResponse.vm");

To use a Velocity template to formulate a response to a message for InOut

message exchanges (where there is a JMSReplyTo header).

If you want to use InOnly and consume the message and send it to

another destination, you could use the following route:

from("activemq:My.Queue").

to("velocity:com/acme/MyResponse.vm").

to("activemq:Another.Queue");

And to use the content cache, e.g. for use in production, where the .vm

template never changes:

from("activemq:My.Queue").

to("velocity:com/acme/MyResponse.vm?contentCache=true").

to("activemq:Another.Queue");

And a le based resource:

from("activemq:My.Queue").

to("velocity:file://myfolder/MyResponse.vm?contentCache=true").

to("activemq:Another.Queue");

In Camel 2.1 it's possible to specify what template the component should

use dynamically via a header, so for example:

from("direct:in").

setHeader("CamelVelocityResourceUri").constant("path/to/my/template.vm").

to("velocity:dummy");

In Camel 2.1 it's possible to specify a template directly as a header the

component should use dynamically via a header, so for example:

CHAPTER 11 - COMPONENT APPENDIX 942

from("direct:in").

setHeader("CamelVelocityTemplate").constant("Hi this is a velocity template that

can do templating ${body}").

to("velocity:dummy");

The Email Sample

In this sample we want to use Velocity templating for an order conrmation

email. The email template is laid out in Velocity as:

Dear ${headers.lastName}, ${headers.firstName}

Thanks for the order of ${headers.item}.

Regards Camel Riders Bookstore

${body}

And the java code:

private Exchange createLetter() {

Exchange exchange = context.getEndpoint("direct:a").createExchange();

Message msg = exchange.getIn();

msg.setHeader("firstName","Claus");

msg.setHeader("lastName","Ibsen");

msg.setHeader("item","Camel in Action");

msg.setBody("PS: Next beer is on me, James");

return exchange;

}

@Test

public void testVelocityLetter() throws Exception {

MockEndpoint mock = getMockEndpoint("mock:result");

mock.expectedMessageCount(1);

mock.expectedBodiesReceived("Dear Ibsen, Claus\n\nThanks for the order of Camel

in Action.\n\nRegards Camel Riders Bookstore\nPS: Next beer is on me, James");

template.send("direct:a", createLetter());

mock.assertIsSatisfied();

}

protected RouteBuilder createRouteBuilder() throws Exception {

return new RouteBuilder() {

public void configure() throws Exception {

from("direct:a").to("velocity:org/apache/camel/component/velocity/

letter.vm").to("mock:result");

}

};

}

943 CHAPTER 11 - COMPONENT APPENDIX

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

VM COMPONENT

The vm: component provides asynchronous SEDA behavior so that messages

are exchanged on a BlockingQueue and consumers are invoked in a separate

thread pool to the producer.

This component diers from the SEDA component in that VM supports

communication across CamelContext instances, so you can use this

mechanism to communicate across web applications, provided that the

camel-core.jar is on the system/boot classpath.

This component is an extension to the SEDA component.

URI format

vm:someName[?options]

Where someName can be any string to uniquely identify the endpoint within

the JVM (or at least within the classloader which loaded the camel-core.jar)

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

See the SEDA component for options and other important usage as the same

rules applies for this VM component.

Samples

In the route below we send the exchange to the VM queue that is working

across CamelContext instances:

from("direct:in").bean(MyOrderBean.class).to("vm:order.email");

And then in another Camel context such as deployed as in another .war

application:

CHAPTER 11 - COMPONENT APPENDIX 944

Camel 1.x to 2.3 - Same URI must be used for both producer

and consumer

An exactly identical VM endpoint URI must be used for both the

producer endpoint and the consumer endpoint. Otherwise Camel

will create a second VM endpoint, even thought the someName

portion of the URI is identical. For example:

from("direct:foo").to("vm:bar?concurrentConsumers=5");

from("vm:bar?concurrentConsumers=5").to("file://output");

Notice that we have to use the full URI including options in both the

producer and consumer.

In Camel 2.4 this has been xed so its the queue name that must match,

eg in this example we are using bar as the queue name.

from("vm:order.email").bean(MyOrderEmailSender.class);

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

▪ SEDA

XMPP COMPONENT

The xmpp: component implements an XMPP (Jabber) transport.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-xmpp</artifactId>

</dependency>

945 CHAPTER 11 - COMPONENT APPENDIX

URI format

xmpp://[login@]hostname[:port][/participant][?Options]

The component supports both room based and private person-person

conversations.

The component supports both producer and consumer (you can get

messages from XMPP or send messages to XMPP). Consumer mode supports

rooms starting from camel-1.5.0.

You can append query options to the URI in the following format,

?option=value&option=value&...

Options

Name Description

room

If this option is specied, the component will connect to MUC (Multi User Chat). Usually, the domain name for MUC is dierent

from the login domain. For example, if you are superman@jabber.org and want to join the krypton room, then the room URL

is krypton@conference.jabber.org. Note the conference part.

Starting from camel-1.5.0, it is not a requirement to provide the full room JID. If the room parameter does not contain the @

symbol, the domain part will be discovered and added by Camel

user User name (without server name). If not specied, anonymous login will be attempted.

password Password.

resource XMPP resource. The default is Camel.

createAccount If true, an attempt to create an account will be made. Default is false.

participant JID (Jabber ID) of person to receive messages. room parameter has precedence over participant.

nickname Use nickname when joining room. If room is specied and nickname is not, user will be used for the nickname.

serviceName Camel 1.6/2.0 The name of the service you are connecting to. For Google Talk, this would be gmail.com.

Headers and setting Subject or Language

Camel sets the message IN headers as properties on the XMPP message. You

can congure a HeaderFilterStategy if you need custom ltering of

headers.

In Camel 1.6.2/2.0 the Subject and Language of the XMPP message are

also set if they are provided as IN headers.

Examples

User superman to join room krypton at jabber server with password,

secret:

xmpp://superman@jabber.org/?room=krypton@conference.jabber.org&password=secret

User superman to send messages to joker:

CHAPTER 11 - COMPONENT APPENDIX 946

xmpp://superman@jabber.org/joker@jabber.org?password=secret

Routing example in Java:

from("timer://kickoff?period=10000").

setBody(constant("I will win!\n Your Superman.")).

to("xmpp://superman@jabber.org/joker@jabber.org?password=secret");

Consumer conguration, which writes all messages from joker into the

queue, evil.talk.

from("xmpp://superman@jabber.org/joker@jabber.org?password=secret").

to("activemq:evil.talk");

Consumer conguration, which listens to room messages (supported from

camel-1.5.0):

from("xmpp://superman@jabber.org/

?password=secret&room=krypton@conference.jabber.org").

to("activemq:krypton.talk");

Room in short notation (no domain part; for camel-1.5.0+):

from("xmpp://superman@jabber.org/?password=secret&room=krypton").

to("activemq:krypton.talk");

When connecting to the Google Chat service, you'll need to specify the

serviceName as well as your credentials (as of Camel 1.6/2.0):

// send a message from fromuser@gmail.com to touser@gmail.com

from("direct:start").

to("xmpp://talk.google.com:5222/

touser@gmail.com?serviceName=gmail.com&user=fromuser&password=secret").

to("mock:result");

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

947 CHAPTER 11 - COMPONENT APPENDIX

XQUERY

The xquery: component allows you to process a message using an XQuery

template. This can be ideal when using Templating to generate respopnses

for requests.

Maven users will need to add the following dependency to their pom.xml

for this component:

<groupId>org.apache.camel</groupId>

<artifactId>camel-saxon</artifactId>

</dependency>

URI format

xquery:templateName

Where templateName is the classpath-local URI of the template to invoke;

or the complete URL of the remote template.

For example you could use something like this:

from("activemq:My.Queue").

to("xquery:com/acme/mytransform.xquery");

To use an XQuery template to formulate a response to a message for InOut

message exchanges (where there is a JMSReplyTo header).

If you want to use InOnly, consume the message, and send it to another

destination, you could use the following route:

from("activemq:My.Queue").

to("xquery:com/acme/mytransform.xquery").

to("activemq:Another.Queue");

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

CHAPTER 11 - COMPONENT APPENDIX 948

XSLT

The xslt: component allows you to process a message using an XSLT

template. This can be ideal when using Templating to generate respopnses

for requests.

URI format

xslt:templateName[?options]

Where templateName is the classpath-local URI of the template to invoke;

or the complete URL of the remote template. Refer to the Spring

Documentation for more detail of the URI syntax

You can append query options to the URI in the following format,

?option=value&option=value&...

Here are some example URIs

URI Description

xslt:com/acme/mytransform.xsl refers to the le com/acme/mytransform.xsl on the classpath

xslt:file:///foo/bar.xsl refers to the le /foo/bar.xsl

xslt:http://acme.com/cheese/foo.xsl refers to the remote http resource

Maven users will need to add the following dependency to their pom.xml for

this component when using Camel 2.8 or older:

<groupId>org.apache.camel</groupId>

<artifactId>camel-spring</artifactId>

</dependency>

From Camel 2.9 onwards the XSLT component is provided directly in the

camel-core.

949 CHAPTER 11 - COMPONENT APPENDIX

Options

Name Default

Value Description

converter null Option to override default XmlConverter. Will lookup for the converter in the Registry. The

provided converted must be of type org.apache.camel.converter.jaxp.XmlConverter.

transformerFactory null

Camel 1.6 Option to override default TransformerFactory. Will lookup for the transformerFactory

in the Registry. The provided transformer factory must be of type

javax.xml.transform.TransformerFactory.

transformerFactoryClass null Camel 1.6 Option to override default TransformerFactory. Will create a TransformerFactoryClass

instance and set it to the converter.

uriResolver null

Camel 2.3: Allows you to use a custom javax.xml.transformation.URIResolver. Camel will by

default use its own implementation org.apache.camel.builder.xml.XsltUriResolver which is

capable of loading from classpath.

resultHandlerFactory null

Camel 2.3: Allows you to use a custom

org.apache.camel.builder.xml.ResultHandlerFactory which is capable of using custom

org.apache.camel.builder.xml.ResultHandler types.

failOnNullBody true Camel 2.3: Whether or not to throw an exception if the input body is null.

deleteOutputFile false

Camel 2.6: If you have output=file then this option dictates whether or not the output le

should be deleted when the Exchange is done processing. For example suppose the output le is

a temporary le, then it can be a good idea to delete it after use.

output string

Camel 2.3: Option to specify which output type to use. Possible values are: string, bytes,

DOM, file. The rst three options are all in memory based, where as file is streamed directly to

ajava.io.File. For file you must specify the lename in the IN header with the key

Exchange.XSLT_FILE_NAME which is also CamelXsltFileName. Also any paths leading to the

lename must be created beforehand, otherwise an exception is thrown at runtime.

contentCache true Camel 2.6: Cache for the resource content (the stylesheet le) when it is loaded. If set to false

Camel will reload the stylesheet le on each message processing. This is good for development.

allowStAX false Camel 2.8.3/2.9: Whether to allow using StAX as the javax.xml.transform.Source.

Using XSLT endpoints

For example you could use something like

from("activemq:My.Queue").

to("xslt:com/acme/mytransform.xsl");

To use an XSLT template to formulate a response for a message for InOut

message exchanges (where there is a JMSReplyTo header).

If you want to use InOnly and consume the message and send it to

another destination you could use the following route:

from("activemq:My.Queue").

to("xslt:com/acme/mytransform.xsl").

to("activemq:Another.Queue");

Getting Parameters into the XSLT to work with

By default, all headers are added as parameters which are available in the

XSLT.

To do this you will need to declare the parameter so it is then useable.

CHAPTER 11 - COMPONENT APPENDIX 950

And the XSLT just needs to declare it at the top level for it to be available:

<xsl: ...... >

<xsl:param name="myParam"/>

<xsl:template ...>

Spring XML versions

To use the above examples in Spring XML you would use something like

<route>

</route>

</camelContext>

There is a test case along with its Spring XML if you want a concrete

example.

Using xsl:include

Camel 1.6.2/2.2 or older

If you use xsl:include in your XSL les then in Camel 2.2 or older it uses the

default javax.xml.transform.URIResolver which means it can only lookup

les from le system, and its does that relative from the JVM starting folder.

For example this include:

<xsl:include href="staff_template.xsl"/>

Will lookup the staff_tempkalte.xsl le from the starting folder where the

application was started.

Camel 1.6.3/2.3 or newer

Now Camel provides its own implementation of URIResolver which allows

Camel to load included les from the classpath and more intelligent than

before.

For example this include:

951 CHAPTER 11 - COMPONENT APPENDIX

<xsl:include href="staff_template.xsl"/>

Will now be located relative from the starting endpoint, which for example

could be:

.to("xslt:org/apache/camel/component/xslt/staff_include_relative.xsl")

Which means Camel will locate the le in the classpath as org/apache/

camel/component/xslt/staff_template.xsl.

This allows you to use xsl include and have xsl les located in the same

folder such as we do in the example org/apache/camel/component/xslt.

You can use the following two prexes classpath: or file: to instruct

Camel to look either in classpath or le system. If you omit the prex then

Camel uses the prex from the endpoint conguration. If that neither has

one, then classpath is assumed.

You can also refer back in the paths such as

<xsl:include href="../staff_other_template.xsl"/>

Which then will resolve the xsl le under org/apache/camel/component.

Notes on using XSTL and Java Versions

Here are some observations from Sameer, a Camel user, which he kindly

shared with us:

In case anybody faces issues with the XSLT endpoint please review

these points.

I was trying to use an xslt endpoint for a simple transformation

from one xml to another using a simple xsl. The output xml kept

appearing (after the xslt processor in the route) with outermost xml

tag with no content within.

No explanations show up in the DEBUG logs. On the TRACE logs

however I did nd some error/warning indicating that the

XMLConverter bean could no be initialized.

After a few hours of cranking my mind, I had to do the following

to get it to work (thanks to some posts on the users forum that gave

some clue):

1. Use the transformerFactory option in the route ("xslt:my-

transformer.xsl?transformerFactory=tFactory") with the

tFactory bean having bean dened in the spring context for

CHAPTER 11 - COMPONENT APPENDIX 952

class="org.apache.xalan.xsltc.trax.TransformerFactoryImpl".

2. Added the Xalan jar into my maven pom.

My guess is that the default xml parsing mechanism supplied

within the JDK (I am using 1.6.0_03) does not work right in this

context and does not throw up any error either. When I switched to

Xalan this way it works. This is not a Camel issue, but might need a

mention on the xslt component page.

Another note, jdk 1.6.0_03 ships with JAXB 2.0 while Camel needs

2.1. One workaround is to add the 2.1 jar to the jre/lib/endorsed

directory for the jvm or as specied by the container.

Hope this post saves newbie Camel riders some time.

See Also

• Conguring Camel

• Component

• Endpoint

• Getting Started

Labels parameters

LABELS

Enter labels to add to this page:

Add Done

Looking for a label? Just start typing.

granted to Apache Software Foundation. Evaluate Conuence today.

• Powered by Atlassian Conuence 3.4.9, the Enterprise Wiki

• Printed by Atlassian Conuence 3.4.9, the Enterprise Wiki.

• | Report a bug

• | Atlassian News

953 CHAPTER 11 - COMPONENT APPENDIX

Camel Manual Fuse 1.x

camel-manual-1.x-fuse-20111110.013830-10

camel-manual-fuse-1.x

Navigation menu

Versions of this User Manual:

Views

Navigation