Red Hat 6.2 Apache Camel Development guide

, and Wire Tap EIPs do this.

, Recipient List

Fig u re 7.1. Co rrelat io n Id en t if ier Pat t ern

201

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

7.2. Event Message

Eve nt Me ssage

Camel supports the Event Message from the

Introducing Enterprise Integration Patterns

by supporting the

Message Exchange Pattern

on a Message which can be set to In O n ly to

indicate a oneway event message. Camel Components then implement this pattern using the underlying transport or protocols.

202

The default behaviour of many Components is InOnly such as for JMS , File or SEDA

Explicit ly spe cifying InOnly

If you are using a component which defaults to InOut you can override the Message

Exchange Pattern for an endpoint using the pattern property.

foo:bar?exchangePattern=InOnly

From 2.0 onwards on Camel you can specify the

Message Exchange Pattern using the dsl.

Usin g t h e Flu en t Bu ild ers

from("mq:someQueue").

inOnly().

bean(Foo.class); or you can invoke an endpoint with an explicit pattern

CHAPT ER 7 . MESSAG E CO NST RUCT IO N

from("mq:someQueue").

inOnly("mq:anotherQueue");

Usin g t h e Sp rin g XML Ext en sio n s

<route>

</route>

<route>

</route>

7.3. Ret urn Address

Re t urn Addre ss

Apache Camel supports the Return Address from the Introducing Enterprise Integration

Patterns using the JMSR epl yT o header.

For example when using JMS with InOut, the component will by default be returned to the address given in JMSR epl yT o .

Exam ple

Req u est o r Co d e

203

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

getMockEndpoint("mock:bar").expectedBodiesReceived("Bye World");

template.sendBodyAndHeader("direct:start", "World", "JMSReplyTo",

"queue:bar");

Ro u t e Usin g t h e Flu en t Bu ild ers

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");

Ro u t e Usin g t h e Sp rin g XML Ext en sio n s

<route>

</route>

<route>

</transform>

</route>

<route>

</route>

For a complete example of this pattern, see this junit test case

204

CHAPT ER 8 . MESSAG E RO UT ING

CHAPTER 8. MESSAGE ROUTING

Ab st ract

The message routing patterns describe various ways of linking message channels together.

This includes various algorithms that can be applied to the message stream (without modifying the body of the message).

8.1. Cont ent -Based Rout er

Ove rvie w

A content-based router, shown in

Figure 8.1, “ Content-Based Router Pattern” , enables you to

route messages to the appropriate destination based on the message contents.

Fig u re 8.1. Co n t en t - Based Ro u t er Pat t ern

Java DSL e xam ple

The following example shows how to route a request from an input, sed a: a, endpoint to either sed a: b, q ueue: c, or sed a: d depending on the evaluation of various predicate expressions:

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from("seda:a").choice()

.when(header("foo").isEqualTo("bar")).to("seda:b")

.when(header("foo").isEqualTo("cheese")).to("seda:c")

.otherwise().to("seda:d");

}

};

XML co nfigurat io n e xam ple

The following example shows how to configure the same route in XML:

<route>

205

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

<when>

</when>

<when>

<xpath>$foo = 'cheese'</xpath>

</when>

</otherwise>

</choice>

</route>

</camelContext>

8.2. Message Filt er

Ove rvie w

A message filter is a processor that eliminates undesired messages based on specific criteria.

In Apache Camel, the message filter pattern, shown in Figure 8.2, “ Message Filter Pattern”

, is implemented by the fi l ter() Java DSL command. The fi l ter() command takes a single predicate argument, which controls the filter. When the predicate is true, the incoming message is allowed to proceed, and when the predicate is fal se, the incoming message is blocked.

Fig u re 8.2. Messag e Filt er Pat t ern

206

Java DSL e xam ple

The following example shows how to create a route from endpoint, sed a: a, to endpoint,

sed a: b, that blocks all messages except for those messages whose fo o header have the value, bar:

RouteBuilder builder = new RouteBuilder() {

public void configure() { from("seda:a").filter(header("foo").isEqualTo("bar")).to("seda:b");

}

};

CHAPT ER 8 . MESSAG E RO UT ING

To evaluate more complex filter predicates, you can invoke one of the supported scripting

languages, such as XPath, XQuery, or SQL (see Expression and Predicate Languages ). The

following example defines a route that blocks all messages except for those containing a

perso n element whose name attribute is equal to James: from("direct:start").

filter().xpath("/person[@ name='James']").

to("mock:result");

XML co nfigurat io n e xam ple

The following example shows how to configure the route with an XPath predicate in XML (see

Expression and Predicate Languages

<route>

</filter>

</route>

</camelContext>

Filt ered en d p o in t req u ired in sid e </f ilt er> t ag

Make sure you put the endpoint you want to filter (for example, <to

uri = "sed a: b"/>) before the closing </fi l ter> tag or the filter will not be applied (in 2.8+, omitting this will result in an error).

Filt e ring wit h be ans

Here is an example of using a bean to define the filter 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 st o p()

Availab le as o f Camel 2.0

207

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Stop is a special type of filter that filters out all messages. Stop is convenient to use in a

Content-Based Router when you need to stop further processing in one of the predicates.

In the following example, we do not want messages with the word Bye in the message body to propagate any further in the route. We prevent this in the when() predicate using

. sto p().

from("direct:start")

.choice()

.when(bodyAs(String.class).contains("Hello")).to("mock:hello")

.when(bodyAs(String.class).contains("Bye")).to("mock:bye").sto p()

.otherwise().to("mock:other")

.end()

.to("mock:result");

Kno wing if Exchange was filt e re d o r no t

Availab le as o f Camel 2.5

The

Message Filter

EIP will add a property on the Exchange which states if it was filtered or not.

The property has the key Exchanng e. FILT ER _MAT C HED which has the String value of

C amel Fi l terMatched . Its value is a boolean indicating true or fal se. If the value is

true then the Exchange was routed in the filter block.

8.3. Recipient List

Ove rvie w

A recipient list, shown in Figure 8.3, “ Recipient List Pattern” , is a type of router that sends

each incoming message to multiple different destinations. In addition, a recipient list typically requires that the list of recipients be calculated at run time.

Fig u re 8.3. Recip ien t List Pat t ern

208

CHAPT ER 8 . MESSAG E RO UT ING

Re cipie nt list wit h fixe d de st inat io ns

The simplest kind of recipient list is where the list of destinations is fixed and known in advance, and the exchange pattern is InOnly. In this case, you can hardwire the list of destinations into the to () Java DSL command.

No t e

The examples given here, for the recipient list with fixed destinations, work only with

the InOnly exchange pattern (similar to a pipeline ). If you want to create a recipient

list for exchange patterns with Out messages, use the

multicast

pattern instead.

Java DSL e xam ple

The following example shows how to route an InOnly exchange from a consumer endpoint,

q ueue: a, to a fixed list of destinations: from("seda:a").to("seda:b", "seda:c", "seda:d");

XML co nfigurat io n e xam ple

The following example shows how to configure the same route in XML:

<route>

</route>

</camelContext>

Re cipie nt list calculat e d at run t im e

209

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

In most cases, when you use the recipient list pattern, the list of recipients should be calculated at runtime. To do this use the reci pi entLi st() processor, which takes a list of destinations as its sole argument. Because Apache Camel applies a type converter to the list argument, it should be possible to use most standard Java list types (for example, a

collection, a list, or an array). For more details about type converters, see Section 42.3,

“ Built-In Type Converters” .

The recipients receive a copy of the same exchange instance and Apache Camel executes them sequentially.

Java DSL e xam ple

The following example shows how to extract the list of destinations from a message header called reci pi entLi stHead er, where the header value is a comma-separated list of endpoint URIs: from("direct:a").recipientList(header("recipientListHeader").tokenize(

","));

In some cases, if the header value is a list type, you might be able to use it directly as the argument to reci pi entLi st(). For example: from("seda:a").recipientList(header("recipientListHeader"));

However, this example is entirely dependent on how the underlying component parses this particular header. If the component parses the header as a simple string, this example will

not work. The header must be parsed into some type of Java list.

XML co nfigurat io n e xam ple

The following example shows how to configure the preceding route in XML, where the header value is a comma-separated list of endpoint URIs:

<route>

<header>recipientListHeader</header>

</recipientList>

</route>

</camelContext>

Se nding t o m ult iple re cipie nt s in paralle l

Availab le as o f Camel 2.2

210

CHAPT ER 8 . MESSAG E RO UT ING

The

feature in Splitter . Use the parallel processing feature to send the exchange to multiple

supports paral l el P ro cessi ng , which is similar to the corresponding

recipients concurrently—for example: from("direct:a").recipientList(header("myHeader")).parallelProcessing(

);

In Spring XML, the parallel processing feature is implemented as an attribute on the

reci pi entLi st tag—for example:

<route>

<header>myHeader</header>

</recipientList>

</route>

St o p o n e xce pt io n

Availab le as o f Camel 2.2

The

supports the sto pO nExcepti o n feature, which you can use to stop sending to any further recipients, if any recipient fails.

from("direct:a").recipientList(header("myHeader")).stopOnException();

And in Spring XML its an attribute on the recipient list tag.

In Spring XML, the stop on exception feature is implemented as an attribute on the

reci pi entLi st tag—for example:

<route>

<header>myHeader</header>

</recipientList>

</route>

No t e

You can combine paral l el P ro cessi ng and sto pO nExcepti o n in the same route.

Igno re invalid e ndpo int s

Availab le as o f Camel 2.3

The

Routing Slip also supports this option). For example:

supports the i g no reInval i d End po i nts option, which enables the

211

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

recipient list to skip invalid endpoints (

from("direct:a").recipientList(header("myHeader")).ignoreInvalidEndpoi

nts();

And in Spring XML, you can enable this option by setting the i g no reInval i d End po i nts attribute on the reci pi entLi st tag, as follows

<route>

<header>myHeader</header>

</recipientList>

</route>

Consider the case where myHead er contains the two endpoints, d i rect: fo o ,xxx: bar.

The first endpoint is valid and works. The second is invalid and, therefore, ignored. Apache

Camel logs at INFO level whenever an invalid endpoint is encountered.

Using cust o m Aggre gat io nSt rat e gy

Availab le as o f Camel 2.2

You can use a custom Ag g reg ati o nStrateg y with the Recipient List

, which is useful for aggregating replies from the recipients in the list. By default, Apache Camel uses the

UseLatestAg g reg ati o nStrateg y aggregation strategy, which keeps just the last received reply. For a more sophisticated aggregation strategy, you can define your own

implementation of the Ag g reg ati o nStrateg y interface—see Aggregator

EIP for details.

For example, to apply the custom aggregation strategy, MyO wnAg g reg ati o nStrateg y, to the reply messages, you can define a Java DSL route as follows: from("direct:a")

.recipientList(header("myHeader")).aggregationStrategy(new

MyOwnAggregationStrategy())

.to("direct:b");

In Spring XML, you can specify the custom aggregation strategy as an attribute on the

reci pi entLi st tag, as follows:

<route>

<header>myHeader</header>

</recipientList>

</route>

212

CHAPT ER 8 . MESSAG E RO UT ING

Using cust o m t hre ad po o l

Availab le as o f Camel 2.2

This is only needed when you use paral l el P ro cessi ng . By default Camel uses a thread pool with 10 threads. Notice this is subject to change when we overhaul thread pool management and configuration later (hopefully in Camel 2.2).

You configure this just as you would with the custom aggregation strategy.

Using m e t ho d call as re cipie nt list

You can use a Bean to provide the recipients, for example: from("activemq:queue:test").recipientList().method(MessageRouter.class

, "routeTo");

Where the Messag eR o uter bean is defined as follows: public class MessageRouter {

public String routeTo() {

String queueName = "activemq:queue:test2";

return queueName;

}

Be an as re cipie nt list

You can make a bean behave as a recipient list by adding the @ R eci pi entLi st annotation to a methods that returns a list of recipients. For example: public class MessageRouter {

@ RecipientList

public String routeTo() {

String queueList =

"activemq:queue:test1,activemq:queue:test2";

return queueList;

}

In this case, do not include the reci pi entLi st DSL command in the route. Define the route as follows: from("activemq:queue:test").bean(MessageRouter.class, "routeTo");

Using t im e o ut

213

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Availab le as o f Camel 2.5

If you use paral l el P ro cessi ng , you can configure a total ti meo ut value in milliseconds. Camel will then process the messages in parallel until the timeout is hit. This allows you to continue processing if one message is slow.

In the example below, the reci pi entl i st header has the value,

d i rect: a,d i rect: b,d i rect: c, so that the message is sent to three recipients. We have a timeout of 250 milliseconds, which means only the last two messages can be completed within the timeframe. The aggregation therefore yields the string result, BC .

from("direct:start")

.recipientList(header("recipients"), ",")

.aggregationStrategy(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)

// use end to indicate end of recipientList clause

.end()

.to("mock:result"); from("direct:a").delay(500).to("mock:A").setBody(constant("A")); from("direct:b").to("mock:B").setBody(constant("B")); from("direct:c").to("mock:C").setBody(constant("C"));

No t e

This ti meo ut feature is also supported by spl i tter and both mul ti cast and

reci pi entLi st.

By default if a timeout occurs the Ag g reg ati o nStrateg y is not invoked. However you can implement a specialized version

// Java public interface TimeoutAwareAggregationStrategy extends

AggregationStrategy {

/**

* A timeout occurred

214

CHAPT ER 8 . MESSAG E RO UT ING

* @ param oldExchange the oldest exchange (is

& lt;tt>null& lt;/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

void timeout(Exchange oldExchange, int index, int total, long timeout);

This allows you to deal with the timeout in the Ag g reg ati o nStrateg y if you really need to.

T imeo u t is t o t al

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 ti meo ut method in the

T i meo utAwareAg g reg ati o nStrateg y once, for the first index which caused the timeout.

Apply cust o m pro ce ssing t o t he o ut go ing m e ssage s

Before reci pi entLi st sends a message to one of the recipient endpoints, it creates a message replica, which is a shallow copy of the original message. If you want to perform some custom processing on each message replica before the replica is sent to its endpoint, you can invoke the o nP repare DSL command in the reci pi entLi st clause. The

o nP repare command inserts a custom processor just after the message has been shallowcopied and just before the message is dispatched to its endpoint. For example, in the following route, the C usto mP ro c processor is invoked on the message replica for each

recipient endpoint: from("direct:start")

.recipientList().onPrepare(new CustomProc());

A common use case for the o nP repare DSL command is to perform a deep copy of some or all elements of a message. This allows each message replica to be modified independently of the others. For example, the following C usto mP ro c processor class performs a deep copy of the message body, where the message body is presumed to be of type, BodyType, and the deep copy is performed by the method, BodyType. d eepC o py().

// Java import org.apache.camel.*;

...

public class CustomProc implements Processor {

public void process(Exchange exchange) throws Exception {

BodyType body = exchange.getIn().getBody(BodyType.class);

// Make a _deep_ copy of of the body object

BodyType clone = BodyType.deepCopy();

215

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

exchange.getIn().setBody(clone);

// Headers and attachments have already been

// shallow-copied. If you need deep copies,

// add some more code here.

}

Opt io ns

The reci pi entLi st DSL command supports the following options:

Name d el i mi ter strateg yR ef strateg yMetho d Name

Default Value

, strateg yMetho d Al l o wN ul l fal se

Descript ion

Delimiter used if the

Exp ressio n returned multip le end p o ints.

Refers to an

Ag g reg atio nStrateg y to b e used to assemb le the rep lies fro m the recip ients, into a sing le o utg o ing messag e fro m the

Recip ient List

. By d efault Camel will use the last rep ly as the o utg o ing messag e.

This o p tio n can b e used to exp licitly sp ecify the metho d name to use, when using

PO JO s as the

Ag g reg ati o nStrateg y

This o p tio n can b e used , when using PO JO s as the

Ag g reg ati o nStrateg y

. If

fal se

, the

ag g reg ate

metho d is no t used , when there is no d ata to enrich. If

true

nul l

values are used fo r the

o l d Exchang e

, when there is no d ata to enrich.

216

paral l el P ro cessi ng fal se paral l el Ag g reg ate fal se executo rServi ceR ef sto pO nExcepti o n fal se

CHAPT ER 8 . MESSAG E RO UT ING

Camel 2 .2 : If enab les then send ing messag es to the recip ients o ccurs co ncurrently. No te the caller thread will still wait until all messag es has b een fully p ro cessed , b efo re it co ntinues. Its o nly the send ing and p ro cessing the rep lies fro m the recip ients which hap p ens co ncurrently.

If enab led , the

ag g reg ate

metho d o n

Ag g reg ati o nStrateg y

can b e called co ncurrently.

No te that this req uires the imp lementatio n o f

Ag g reg ati o nStrateg y

to b e thread -safe. By d efault, this o p tio n is

fal se

, which means that Camel auto matically synchro nizes calls to the

ag g reg ate

metho d . In so me use-cases, ho wever, yo u can imp ro ve p erfo rmance b y imp lementing

Ag g reg ati o nStrateg y

as thread -safe and setting this o p tio n to

true

Camel 2 .2 : Refers to a custo m Thread Po o l to b e used fo r p arallel p ro cessing . No tice if yo u set this o p tio n, then p arallel p ro cessing is auto matic imp lied , and yo u d o no t have to enab le that o p tio n as well.

Camel 2 .2 : Whether o r no t to sto p co ntinue p ro cessing immed iately when an excep tio n o ccurred . If d isab le, then Camel will send the messag e to all recip ients reg ard less if o ne o f them failed . Yo u can d eal with excep tio ns in the

Ag g reg atio nStrateg y class where yo u have full co ntro l ho w to hand le that.

217

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide i g no reInval i d End po i nts fal se streami ng ti meo ut o nP repareR ef shareUni tO fWo rk cacheSi ze fal se fal se

Camel 2 .3: If an end p o int uri co uld no t b e reso lved , sho uld it b e ig no red .

O therwise Camel will thro wn an excep tio n stating the end p o int uri is no t valid .

Camel 2 .5: If enab led then

Camel will p ro cess rep lies o ut-o f-o rd er, eg in the o rd er they co me b ack. If d isab led ,

Camel will p ro cess rep lies in the same o rd er as the

Exp ressio n sp ecified .

Camel 2 .5: Sets a to tal timeo ut sp ecified in millis. If

the Recip ient List hasn't

b een ab le to send and p ro cess all rep lies within the g iven timeframe, then the timeo ut trig g ers and the

Recip ient List b reaks o ut

and co ntinues. No tice if yo u p ro vid e a

Timeo utAwareAg g reg atio nSt rateg y then the

ti meo ut

metho d is invo ked b efo re b reaking o ut.

Camel 2 .8 : Refers to a custo m Pro cesso r to p rep are the co p y o f the

Exchang e each recip ient will receive. This allo ws yo u to d o any custo m lo g ic, such as d eep -clo ning the messag e p aylo ad if that's need ed etc.

Camel 2 .8 : Whether the unit o f wo rk sho uld b e shared .

See the same o p tio n o n

Sp litter

fo r mo re d etails.

Camel 2 .1 3.1 /2 .1 2 .4 : Allo ws to co nfig ure the cache size fo r the ProducerCache which caches p ro d ucers fo r reuse in the ro uting slip . Will b y d efault use the d efault cache size which is 0 . Setting the value to -1 allo ws to turn o ff the cache all to g ether.

218

CHAPT ER 8 . MESSAG E RO UT ING

Using Exchange Pat t e rn in Re cipie nt List

By default, the Recipient List uses the current exchange pattern. However, there may be few cases where you can send a message to a recipient using a different exchange pattern.

For example, you may have a route that initiates as a InO nl y route. Now, If you want to use

InO ut exchange pattern with a recipient list, you need to configure the exchange pattern directly in the recipient endpoints.

The following example illustrates the route where the new files will start as InOnly and then route to a recipient list. If you want to use InOut with the ActiveMQ (JMS) endpoint, you need to specify this using the exchangePattern equals to InOut option. However, the response form the JMS request or reply will then be continued routed, and thus the response is stored in as a file in the outbox directory.

from( "file:inbox" )

// the exchange pattern is InOnly initially when using a file route

.recipientList().constant( "activemq:queue:inbox?

exchangePattern=InOut" )

.to( "file:outbox" );

No t e

The InO ut exchange pattern must get a response during the timeout. However, it fails if the response is not recieved.

8.4 . Split t er

Ove rvie w

A splitter is a type of router that splits an incoming message into a series of outgoing messages. Each of the outgoing messages contains a piece of the original message. In

Apache Camel, the splitter pattern, shown in Figure 8.4, “ Splitter Pattern” , is implemented by

the spl i t() Java DSL command.

Fig u re 8.4 . Sp lit t er Pat t ern

219

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

The Apache Camel splitter actually supports two patterns, as follows:

Simple splitter—implements the splitter pattern on its own.

Splitter/aggregator—combines the splitter pattern with the aggregator pattern, such that the pieces of the message are recombined after they have been processed.

Java DSL e xam ple

The following example defines a route from sed a: a to sed a: b that splits messages by converting each line of an incoming message into a separate outgoing message:

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from("seda:a")

.split(bodyAs(String.class).tokenize("\n"))

.to("seda:b");

}

};

The splitter can use any expression language, so you can split messages using any of the

supported scripting languages, such as XPath, XQuery, or SQL (see Part II, “ Routing

Expression and Predicate Languages” ). The following example extracts bar elements from

an incoming message and insert them into separate outgoing messages: from("activemq:my.queue")

.split(xpath("//foo/bar"))

.to("file://some/directory")

XML co nfigurat io n e xam ple

The following example shows how to configure a splitter route in XML, using the XPath scripting language:

<route>

<split>

</split>

</route>

</camelContext>

You can use the tokenize expression in the XML DSL to split bodies or headers using a token, where the tokenize expression is defined using the to keni ze element. In the following example, the message body is tokenized using the \n separator character. To use a regular expression pattern, set reg ex= true in the to keni ze element.

220

CHAPT ER 8 . MESSAG E RO UT ING

<route>

<split>

</split>

</route>

</camelContext>

Split t ing int o gro ups o f line s

To split a big file into chunks of 1000 lines, you can define a splitter route as follows in the

Java DSL: from("file:inbox")

.split().tokenize("\n", 1000).streaming()

.to("activemq:queue:order");

The second argument to to keni ze specifies the number of lines that should be grouped into a single chunk. The streami ng () clause directs the splitter not to read the whole file at once (resulting in much better performance if the file is large).

The same route can be defined in XML DSL as follows:

<route>

</split>

</route>

The output when using the g ro up option is always of java. l ang . Stri ng type.

Split t e r re ply

If the exchange that enters the splitter has the InOut message-exchange pattern (that is, a reply is expected), the splitter returns a copy of the original input message as the reply message in the Out message slot. You can override this default behavior by implementing

your own aggregation strategy .

Paralle l e xe cut io n

If you want to execute the resulting pieces of the message in parallel, you can enable the parallel processing option, which instantiates a thread pool to process the message pieces.

For example:

221

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

XPathBuilder xPathBuilder = new XPathBuilder("//foo/bar"); from("activemq:my.queue").split(xPathBuilder).parallelProcessing().to(

"activemq:my.parts");

You can customize the underlying T hread P o o l Executo r used in the parallel splitter. For example, you can specify a custom executor in the Java DSL as follows:

XPathBuilder xPathBuilder = new XPathBuilder("//foo/bar");

ThreadPoolExecutor threadPoolExecutor = new ThreadPoolExecutor(8, 16,

0L, TimeUnit.MILLISECONDS, new LinkedBlockingQueue()); from("activemq:my.queue")

.split(xPathBuilder)

.parallelProcessing()

.executorService(threadPoolExecutor)

.to("activemq:my.parts");

You can specify a custom executor in the XML DSL as follows:

<route>

<xpath>/invoice/lineItems</xpath>

</split>

</route>

</camelContext>

<constructor-arg index="0" value="8"/>

<constructor-arg index="1" value="16"/>

<constructor-arg index="2" value="0"/>

<constructor-arg index="3" value="MILLISECONDS"/>

<constructor-arg index="4"><bean class="java.util.concurrent.LinkedBlockingQueue"/></constructor-arg>

</bean>

Using a be an t o pe rfo rm split t ing

As the splitter can use any expression to do the splitting, we can use a bean to perform splitting, by invoking the metho d () expression. The bean should return an iterable value such as: java. uti l . C o l l ecti o n, java. uti l . Iterato r, or an array.

222

The following route defines a metho d () expression that calls a method on the

mySpl i tterBean bean instance: from("direct:body")

// here we use a POJO bean mySplitterBean to do the split of the payload

.split()

.method("mySplitterBean", "splitBody")

CHAPT ER 8 . MESSAG E RO UT ING

.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");

Where mySpl i tterBean is an instance of the MySpl i tterBean class, which is defined as follows: 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 split

public List<String> splitBody(String body) {

// since this is based on an unit test you can of couse

// use different logic for splitting as Apache 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 split

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 Apache Camel version >= 1.6.1

List<Message> answer = new ArrayList<Message>();

String[] parts = header.split(",");

for (String part : parts) {

223

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

DefaultMessage message = new DefaultMessage();

message.setHeader("user", part);

message.setBody(body);

answer.add(message);

}

return answer;

}

Exchange pro pe rt ie s

The following properties are set on each split exchange:

header

C amel Spl i tInd ex

C amel Spl i tSi ze t ype i nt i nt

C amel Spl i tC o mpl ete bo o l ean descript ion

Ap ache Camel 2.0 : A sp lit co unter that increases fo r each Exchang e b eing sp lit.

The co unter starts fro m 0 .

Ap ache Camel 2.0 : The to tal numb er o f Exchang es that was sp lit. This head er is no t ap p lied fo r stream b ased sp litting .

Ap ache Camel 2.4: Whether o r no t this Exchang e is the last.

Split t e r/aggre gat o r pat t e rn

It is a common pattern for the message pieces to be aggregated back into a single exchange, after processing of the individual pieces has completed. To support this pattern, the

spl i t() DSL command lets you provide an Ag g reg ati o nStrateg y object as the second argument.

Java DSL e xam ple

224

The following example shows how to use a custom aggregation strategy to recombine a split message after all of the message pieces have been processed: from("direct:start")

.split(body().tokenize("@ "), new MyOrderStrategy())

// each split 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 split message

CHAPT ER 8 . MESSAG E RO UT ING

.end()

// after we have split 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")

Aggre gat io nSt rat e gy im ple m e nt at io n

The custom aggregation strategy, MyO rd erStrateg y, used in the preceding route is implemented as follows:

/**

* This is our own order aggregation strategy where we can control

* how each split message should be combined. As we do not want to

* lose 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;

}

St re am base d pro ce ssing

225

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

When parallel processing is enabled, it is theoretically possible for a later message piece to be ready for aggregation before an earlier piece. In other words, the message pieces might arrive at the aggregator out of order. By default, this does not happen, because the splitter implementation rearranges the message pieces back into their original order before passing them into the aggregator.

If you would prefer to aggregate the message pieces as soon as they are ready (and possibly out of order), you can enable the streaming option, as follows: from("direct:streaming")

.split(body().tokenize(","), new MyOrderStrategy())

.parallelProcessing()

.streaming()

.to("activemq:my.parts")

.end()

.to("activemq:all.parts");

You can also supply a custom iterator to use with streaming, as follows:

// Java import static org.apache.camel.builder.ExpressionBuilder.beanExpression;

...

from("direct:streaming")

.split(beanExpression(new MyCustomIteratorFactory(),

"iterator"))

.streaming().to("activemq:my.parts")

St reamin g an d XPat h

You cannot use streaming mode in conjunction with XPath. XPath requires the complete DOM XML document in memory.

St re am base d pro ce ssing wit h XML

If an incoming messages is a very large XML file, you can process the message most efficiently using the to keni zeXML sub-command in streaming mode.

For example, given a large XML file that contains a sequence of o rd er elements, you can split the file into o rd er elements using a route like the following: from("file:inbox")

.split().tokenizeXML("order").streaming()

.to("activemq:queue:order");

226

You can do the same thing in XML, by defining a route like the following:

<route>

CHAPT ER 8 . MESSAG E RO UT ING

</split>

</route>

It is often the case that you need access to namespaces that are defined in one of the enclosing (ancestor) elements of the token elements. You can copy namespace definitions from one of the ancestor elements into the token element, by specifing which element you want to inherit namespace definitions from.

In the Java DSL, you specify the ancestor element as the second argument of

to keni zeXML. For example, to inherit namespace definitions from the enclosing o rd ers element: from("file:inbox")

.split().tokenizeXML("order", "o rd ers").streaming()

.to("activemq:queue:order");

In the XML DSL, you specify the ancestor element using the i nheri tNamespaceT ag Name attribute. For example:

<route>

<tokenize token="order"

xml="true"

i nheri tNamespaceT ag Name= "o rd ers"/>

</split>

</route>

Opt io ns

The spl i t DSL command supports the following options:

Name strateg yR ef

Default Value Descript ion

Refers to an

Ag g reg atio nStrateg y to b e used to assemb le the rep lies fro m the sub -messag es, into a sing le o utg o ing messag e fro m the

Sp litter . See the

sectio n titled What does the

splitter return b elo w fo r whats used b y d efault.

227

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide strateg yMetho d Name strateg yMetho d Al l o wN ul l paral l el P ro cessi ng paral l el Ag g reg ate executo rServi ceR ef fal se fal se fal se

This o p tio n can b e used to exp licitly sp ecify the metho d name to use, when using

PO JO s as the

Ag g reg ati o nStrateg y

This o p tio n can b e used , when using PO JO s as the

Ag g reg ati o nStrateg y

. If

fal se

, the

ag g reg ate

metho d is no t used , when there is no d ata to enrich. If

true

nul l

values are used fo r the

o l d Exchang e

, when there is no d ata to enrich.

If enab les then p ro cessing the sub -messag es o ccurs co ncurrently. No te the caller thread will still wait until all sub -messag es has b een fully p ro cessed , b efo re it co ntinues.

If enab led , the

ag g reg ate

metho d o n

Ag g reg ati o nStrateg y

can b e called co ncurrently.

No te that this req uires the imp lementatio n o f

Ag g reg ati o nStrateg y

to b e thread -safe. By d efault, this o p tio n is

fal se

, which means that Camel auto matically synchro nizes calls to the

ag g reg ate

metho d . In so me use-cases, ho wever, yo u can imp ro ve p erfo rmance b y imp lementing

Ag g reg ati o nStrateg y

as thread -safe and setting this o p tio n to

true

Refers to a custo m Thread

Po o l to b e used fo r p arallel p ro cessing . No tice if yo u set this o p tio n, then p arallel p ro cessing is auto matic imp lied , and yo u d o no t have to enab le that o p tio n as well.

228

sto pO nExcepti o n fal se streami ng ti meo ut fal se

CHAPT ER 8 . MESSAG E RO UT ING

Camel 2 .2 : Whether o r no t to sto p co ntinue p ro cessing immed iately when an excep tio n o ccurred . If d isab le, then Camel co ntinue sp litting and p ro cess the sub -messag es reg ard less if o ne o f them failed . Yo u can d eal with excep tio ns in the

Ag g reg atio nStrateg y class where yo u have full co ntro l ho w to hand le that.

If enab led then Camel will sp lit in a streaming fashio n, which means it will sp lit the inp ut messag e in chunks.

This red uces the memo ry o verhead . Fo r examp le if yo u sp lit b ig messag es its reco mmend ed to enab le streaming . If streaming is enab led then the sub messag e rep lies will b e ag g reg ated o ut-o f-o rd er, eg in the o rd er they co me b ack.

If d isab led , Camel will p ro cess sub -messag e rep lies in the same o rd er as they where sp litted .

Camel 2 .5: Sets a to tal timeo ut sp ecified in millis. If

the Recip ient List hasn't

b een ab le to sp lit and p ro cess all rep lies within the g iven timeframe, then the timeo ut trig g ers and the

Sp litter

b reaks o ut and co ntinues. No tice if yo u p ro vid e a

Timeo utAwareAg g reg atio nSt rateg y then the

ti meo ut

metho d is invo ked b efo re b reaking o ut.

229

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide o nP repareR ef shareUni tO fWo rk fal se

Camel 2 .8 : Refers to a custo m Pro cesso r to p rep are the sub -messag e o f the Exchang e, b efo re its p ro cessed . This allo ws yo u to d o any custo m lo g ic, such as d eep -clo ning the messag e p aylo ad if that's need ed etc.

Camel 2 .8 : Whether the unit o f wo rk sho uld b e shared .

See further b elo w fo r mo re d etails.

8.5. Aggregat or

Ove rvie w

The aggregator pattern, shown in

Figure 8.5, “ Aggregator Pattern”

, enables you to combine a batch of related messages into a single message.

Fig u re 8.5. Ag g reg at o r Pat t ern

230

To control the aggregator's behavior, Apache Camel allows you to specify the properties described in Enterprise Integration Patterns, as follows:

Correlation expression — Determines which messages should be aggregated together. The correlation expression is evaluated on each incoming message to produce a correlation

key. Incoming messages with the same correlation key are then grouped into the same batch. For example, if you want to aggregate all incoming messages into a single message, you can use a constant expression.

Completeness condition — Determines when a batch of messages is complete. You can specify this either as a simple size limit or, more generally, you can specify a predicate condition that flags when the batch is complete.

Aggregation algorithm — Combines the message exchanges for a single correlation key into a single message exchange.

CHAPT ER 8 . MESSAG E RO UT ING

For example, consider a stock market data system that receives 30,000 messages per second. You might want to throttle down the message flow if your GUI tool cannot cope with such a massive update rate. The incoming stock quotes can be aggregated together simply by choosing the latest quote and discarding the older prices. (You can apply a delta processing algorithm, if you prefer to capture some of the history.)

Ho w t he aggre gat o r wo rks

Figure 8.6, “ Aggregator Implementation” shows an overview of how the aggregator works,

assuming it is fed with a stream of exchanges that have correlation keys such as A, B, C, or

Fig u re 8.6 . Ag g reg at o r Imp lemen t at io n

The incoming stream of exchanges shown in Figure 8.6, “ Aggregator Implementation”

is processed as follows:

1. The correlator is responsible for sorting exchanges based on the correlation key. For each incoming exchange, the correlation expression is evaluated, yielding the

correlation key. For example, for the exchange shown in Figure 8.6, “ Aggregator

Implementation” , the correlation key evaluates to A.

2. The aggregation strategy is responsible for merging exchanges with the same correlation key. When a new exchange, A, comes in, the aggregator looks up the corresponding aggregate exchange, A', in the aggregation repository and combines it with the new exchange.

Until a particular aggregation cycle is completed, incoming exchanges are continuously aggregated with the corresponding aggregate exchange. An aggregation cycle lasts until terminated by one of the completion mechanisms.

3. If a completion predicate is specified on the aggregator, the aggregate exchange is tested to determine whether it is ready to be sent to the next processor in the route.

Processing continues as follows:

231

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

If complete, the aggregate exchange is processed by the latter part of the route.

There are two alternative models for this: synchronous (the default), which causes the calling thread to block, or asynchronous (if parallel processing is enabled), where the aggregate exchange is submitted to an executor thread pool (as shown

in Figure 8.6, “ Aggregator Implementation” ).

If not complete, the aggregate exchange is saved back to the aggregation repository.

4. In parallel with the synchronous completion tests, it is possible to enable an asynchronous completion test by enabling either the co mpl eti o nT i meo ut option or the co mpl eti o nInterval option. These completion tests run in a separate thread and, whenever the completion test is satisfied, the corresponding exchange is marked as complete and starts to be processed by the latter part of the route (either synchronously or asynchronously, depending on whether parallel processing is enabled or not).

5. If parallel processing is enabled, a thread pool is responsible for processing exchanges in the latter part of the route. By default, this thread pool contains ten

threads, but you have the option of customizing the pool ( the section called

“ Threading options” ).

Java DSL e xam ple

The following example aggregates exchanges with the same Sto ckSymbo l header value, using the UseLatestAg g reg ati o nStrateg y aggregation strategy. For a given

Sto ckSymbo l value, if more than three seconds elapse since the last exchange with that correlation key was received, the aggregated exchange is deemed to be complete and is sent to the mo ck endpoint.

from("direct:start")

.aggregate(header("id"), new UseLatestAggregationStrategy())

.completionTimeout(3000)

.to("mock:aggregated");

XML DSL e xam ple

The following example shows how to configure the same route in XML:

<route>

<aggregate strategyRef="aggregatorStrategy"

completionTimeout="3000">

<simple>header.StockSymbol</simple>

</correlationExpression>

</aggregate>

</route>

</camelContext>

232

CHAPT ER 8 . MESSAG E RO UT ING

<bean id="aggregatorStrategy" class="org.apache.camel.processor.aggregate.UseLatestAggregationStrate

gy"/>

Spe cifying t he co rre lat io n e xpre ssio n

In the Java DSL, the correlation expression is always passed as the first argument to the

ag g reg ate() DSL command. You are not limited to using the Simple expression language here. You can specify a correlation expression using any of the expression languages or scripting languages, such as XPath, XQuery, SQL, and so on.

For exampe, to correlate exchanges using an XPath expression, you could use the following

Java DSL route: from("direct:start")

.aggregate(xpath("/stockQuote/@ symbol"), new

UseLatestAggregationStrategy())

.completionTimeout(3000)

.to("mock:aggregated");

If the correlation expression cannot be evaluated on a particular incoming exchange, the aggregator throws a C amel Exchang eExcepti o n by default. You can suppress this exception by setting the i g no reInval i d C o rrel ati o nKeys option. For example, in the

Java DSL: from(...).aggregate(...).ignoreInvalidCorrelationKeys()

In the XML DSL, you can set the i g no reInval i d C o rrel ati o nKeys option is set as an attribute, as follows:

<aggregate strategyRef="aggregatorStrategy"

ignoreInvalidCorrelationKeys="true"

...>

...

</aggregate>

Spe cifying t he aggre gat io n st rat e gy

In Java DSL, you can either pass the aggregation strategy as the second argument to the

ag g reg ate() DSL command or specify it using the ag g reg ati o nStrateg y() clause. For example, you can use the ag g reg ati o nStrateg y() clause as follows: from("direct:start")

.aggregate(header("id"))

.aggregationStrategy(new UseLatestAggregationStrategy())

.completionTimeout(3000)

.to("mock:aggregated");

233

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Apache Camel provides the following basic aggregation strategies (where the classes belong to the o rg . apache. camel . pro cesso r. ag g reg ate Java package):

UseLatestAg g reg ati o nStrateg y

Return the last exchange for a given correlation key, discarding all earlier exchanges with this key. For example, this strategy could be useful for throttling the feed from a stock exchange, where you just want to know the latest price of a particular stock symbol.

UseO ri g i nal Ag g reg ati o nStrateg y

Return the first exchange for a given correlation key, discarding all later exchanges with this key. You must set the first exchange by calling

UseO ri g i nal Ag g reg ati o nStrateg y. setO ri g i nal () before you can use this strategy.

G ro uped Exchang eAg g reg ati o nStrateg y

Concatenates all of the exchanges for a given correlation key into a list, which is

stored in the Exchang e. G R O UP ED _EXC HANG E exchange property. See the section called “ Grouped exchanges” .

Im ple m e nt ing a cust o m aggre gat io n st rat e gy

If you want to apply a different aggregation strategy, you can implement one of the following aggregation strategy base interfaces:

o rg . apache. camel . pro cesso r. ag g reg ate. Ag g reg ati o nStrateg y

The basic aggregation strategy interface.

o rg . apache. camel . pro cesso r. ag g reg ate. T i meo utAwareAg g reg ati o nStrateg y

Implement this interface, if you want your implementation to receive a notification when an aggregation cycle times out. The ti meo ut notification method has the following signature: void timeout(Exchange oldExchange, int index, int total, long timeout)

o rg . apache. camel . pro cesso r. ag g reg ate. C o mpl eti o nAwareAg g reg ati o nStrat eg y

Implement this interface, if you want your implementation to receive a notification when an aggregation cycle completes normally. The notification method has the following signature: void onCompletion(Exchange exchange)

234

CHAPT ER 8 . MESSAG E RO UT ING

For example, the following code shows two different custom aggregation strategies,

Stri ng Ag g reg ati o nStrateg y and ArrayLi stAg g reg ati o nStrateg y::

//simply combines Exchange String body values using '+' as a delimiter

class Stri ng Ag g reg ati o nStrateg y 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 ArrayLi stAg g reg ati o nStrateg y 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;

}

No t e

Since Apache Camel 2.0, the Ag g reg ati o nStrateg y. ag g reg ate() callback method is also invoked for the very first exchange. On the first invocation of the

ag g reg ate method, the o l d Exchang e parameter is nul l and the newExchang e parameter contains the first incoming exchange.

To aggregate messages using the custom strategy class,

ArrayLi stAg g reg ati o nStrateg y, define a route like the following: from("direct:start")

.aggregate(header("StockSymbol"), new

ArrayListAggregationStrategy())

.completionTimeout(3000)

235

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

.to("mock:result");

You can also configure a route with a custom aggregation strategy in XML, as follows:

<route>

<aggregate strategyRef="aggregatorStrategy"

completionTimeout="3000">

<simple>header.StockSymbol</simple>

</correlationExpression>

</aggregate>

</route>

</camelContext>

Co nt ro lling t he life cycle o f a cust o m aggre gat io n st rat e gy

You can implement a custom aggregation strategy so that its lifecycle is aligned with the lifecycle of the enterprise integration pattern that is controlling it. This can be useful for ensuring that the aggregation strategy can shut down gracefully.

To implement an aggregation strategy with lifecycle support, you must implement the

o rg . apache. camel . Servi ce interface (in addition to the Ag g reg ati o nStrateg y interface) and provide implementations of the start() and sto p() lifecycle methods. For example, the following code example shows an outline of an aggregation strategy with lifecycle support:

// Java import org.apache.camel.processor.aggregate.AggregationStrategy; import org.apache.camel.Service; import java.lang.Exception;

...

class MyAggStrategyWithLifecycleControl

implements AggregationStrategy, Servi ce {

public Exchange aggregate(Exchange oldExchange, Exchange newExchange) {

// Implementation not shown...

...

}

public void start() throws Exception {

// Actions to perform when the enclosing EIP starts up

...

}

public void sto p() throws Exception {

236

CHAPT ER 8 . MESSAG E RO UT ING

// Actions to perform when the enclosing EIP is stopping

...

}

Exchange pro pe rt ie s

The following properties are set on each aggregated exchange:

T ab le 8.1. Ag g reg at ed Exch an g e Pro p ert ies

Header

Exchang e. AG G R EG AT ED

_SIZE

Exchang e. AG G R EG AT ED

_C O MP LET ED _BY

T ype i nt

Stri ng

Descript ion

The to tal numb er o f exchang es ag g reg ated into this exchang e.

Ind icates the mechanism resp o nsib le fo r co mp leting the ag g reg ate exchang e.

Po ssib le values are:

pred i cate

si ze

ti meo ut

i nterval

, o r

co nsumer

The following properties are set on exchanges redelivered by the HawtDB aggregation

repository (see the section called “ Persistent aggregation repository” ):

T ab le 8.2. Red elivered Exch an g e Pro p ert ies

Header

Exchang e. R ED ELIVER Y

_C O UNT ER

T ype i nt

Descript ion

Seq uence numb er o f the current red elivery attemp t

(starting at

Spe cifying a co m ple t io n co ndit io n

It is mandatory to specify at least one completion condition, which determines when an aggregate exchange leaves the aggregator and proceeds to the next node on the route. The following completion conditions can be specified:

co mpl eti o nP red i cate

Evaluates a predicate after each exchange is aggregated in order to determine completeness. A value of true indicates that the aggregate exchange is complete.

237

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Alternatively, instead of setting this option, you can define a custom

Ag g reg ati o nStrateg y that implements the P red i cate interface, in which case the Ag g reg ati o nStrateg y will be used as the completion predicate.

co mpl eti o nSi ze

Completes the aggregate exchange after the specified number of incoming exchanges are aggregated.

co mpl eti o nT i meo ut

(Incompatible with completionInterval) Completes the aggregate exchange, if no incoming exchanges are aggregated within the specified timeout.

In other words, the timeout mechanism keeps track of a timeout for each correlation key value. The clock starts ticking after the latest exchange with a particular key value is received. If another exchange with the same key value is not received within the specified timeout, the corresponding aggregate exchange is marked complete and sent to the next node on the route.

co mpl eti o nInterval

(Incompatible with completionTimeout) Completes all outstanding aggregate exchanges, after each time interval (of specified length) has elapsed.

The time interval is not tailored to each aggregate exchange. This mechanism forces simultaneous completion of all outstanding aggregate exchanges. Hence, in some cases, this mechanism could complete an aggregate exchange immediately after it started aggregating.

co mpl eti o nFro mBatchC o nsumer

When used in combination with a consumer endpoint that supports the batch

consumer mechanism, this completion option automatically figures out when the current batch of exchanges is complete, based on information it receives from the consumer endpoint. See

the section called “ Batch consumer” .

fo rceC o mpl eti o nO nSto p

When this option is enabled, it forces completion of all outstanding aggregate exchanges when the current route context is stopped.

The preceding completion conditions can be combined arbitrarily, except for the

co mpl eti o nT i meo ut and co mpl eti o nInterval conditions, which cannot be simultaneously enabled. When conditions are used in combination, the general rule is that the first completion condition to trigger is the effective completion condition.

Spe cifying t he co m ple t io n pre dicat e

238

CHAPT ER 8 . MESSAG E RO UT ING

You can specify an arbitrary predicate expression that determines when an aggregated exchange is complete. There are two possible ways of evaluating the predicate expression:

On the latest aggregate exchange—this is the default behavior.

On the latest incoming exchange—this behavior is selected when you enable the

eag erC heckC o mpl eti o n option.

For example, if you want to terminate a stream of stock quotes every time you receive an

ALER T message (as indicated by the value of a Msg T ype header in the latest incoming exchange), you can define a route like the following: from("direct:start")

.aggregate(

header("id"),

new UseLatestAggregationStrategy()

)

.completionPredicate(

header("MsgType").isEqualTo("ALERT")

)

.eagerCheckCompletion()

.to("mock:result");

The following example shows how to configure the same route using XML:

<route>

<aggregate strategyRef="aggregatorStrategy"

eagerCheckCompletion="true">

<simple>header.StockSymbol</simple>

</correlationExpression>

<simple>$MsgType = 'ALERT'</simple>

</completionPredicate>

</aggregate>

</route>

</camelContext>

<bean id="aggregatorStrategy" class="org.apache.camel.processor.aggregate.UseLatestAggregationStrate

gy"/>

Spe cifying a dynam ic co m ple t io n t im e o ut

It is possible to specify a dynamic completion timeout, where the timeout value is recalculated for every incoming exchange. For example, to set the timeout value from the ti meo ut header in each incoming exchange, you could define a route as follows:

239

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

from("direct:start")

.aggregate(header("StockSymbol"), new

UseLatestAggregationStrategy())

.completionTimeout(header("timeout"))

.to("mock:aggregated");

You can configure the same route in the XML DSL, as follows:

<route>

<simple>header.StockSymbol</simple>

</correlationExpression>

<header>timeout</header>

</completionTimeout>

</aggregate>

</route>

</camelContext>

No t e

You can also add a fixed timeout value and Apache Camel will fall back to use this value, if the dynamic value is nul l or 0 .

Spe cifying a dynam ic co m ple t io n size

It is possible to specify a dynamic completion size, where the completion size is recalculated for every incoming exchange. For example, to set the completion size from the mySi ze header in each incoming exchange, you could define a route as follows: from("direct:start")

.aggregate(header("StockSymbol"), new

UseLatestAggregationStrategy())

.completionSize(header("mySize"))

.to("mock:aggregated");

24 0

And the same example using Spring XML:

<route>

CHAPT ER 8 . MESSAG E RO UT ING

<simple>header.StockSymbol</simple>

</correlationExpression>

<header>mySize</header>

</completionSize>

</aggregate>

</route>

</camelContext>

No t e

You can also add a fixed size value and Apache Camel will fall back to use this value, if the dynamic value is nul l or 0 .

Fo rcing co m ple t io n o f a single gro up fro m wit hin an Aggre gat io nSt rat e gy

If you implement a custom Ag g reg ati o nStrateg y class, there is a mechanism available to force the completion of the current message group, by setting the

Exchang e. AG G R EG AT IO N_C O MP LET E_C UR R ENT _G R O UP exchange property to true on the exchange returned from the Ag g reg ati o nStrateg y. ag g reg ate() method. This mechanism only affects the current group: other message groups (with different correlation

IDs) are not forced to complete. This mechanism overrides any other completion mechanisms, such as predicate, size, timeout, and so on.

For example, the following sample Ag g reg ati o nStrateg y class completes the current group, if the message body size is larger than 5:

// Java

public final class MyCompletionStrategy implements AggregationStrategy

{

@ Override public Exchange aggregate(Exchange oldExchange, Exchange newExchange) { if (oldExchange == null ) { return newExchange;

}

String body = oldExchange.getIn().getBody(String.class) + "+"

+ newExchange.getIn().getBody(String.class);

oldExchange.getIn().setBody(body); if (body.length() >= 5 ) { oldExchange.setProperty(Exchange.AGGREGATION_COMPLETE_CURRENT_GROUP, true );

} return oldExchange;

}

24 1

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Fo rcing co m ple t io n o f all gro ups wit h a spe cial m e ssage

It is possible to force completion of all outstanding aggregate messages, by sending a message with a special header to the route. There are two alternative header settings you can use to force completion:

Exchang e. AG G R EG AT IO N_C O MP LET E_ALL_G R O UP S

Set to true, to force completion of the current aggregation cycle. This message acts purely as a signal and is not included in any aggregation cycle. After processing this signal message, the content of the message is discarded.

Exchang e. AG G R EG AT IO N_C O MP LET E_ALL_G R O UP S_INC LUSIVE

Set to true, to force completion of the current aggregation cycle. This message is

included in the current aggregation cycle.

Enfo rcing unique co rre lat io n ke ys

In some aggregation scenarios, you might want to enforce the condition that the correlation key is unique for each batch of exchanges. In other words, when the aggregate exchange for a particular correlation key completes, you want to make sure that no further aggregate exchanges with that correlation key are allowed to proceed. For example, you might want to enforce this condition, if the latter part of the route expects to process exchanges with unique correlation key values.

Depending on how the completion conditions are configured, there might be a risk of more than one aggregate exchange being generated with a particular correlation key. For example, although you might define a completion predicate that is designed to wait until all the exchanges with a particular correlation key are received, you might also define a completion timeout, which could fire before all of the exchanges with that key have arrived. In this case, the late-arriving exchanges could give rise to a second aggregate exchange with the same correlation key value.

For such scenarios, you can configure the aggregator to suppress aggregate exchanges that duplicate previous correlation key values, by setting the

cl o seC o rrel ati o nKeyO nC o mpl eti o n option. In order to suppress duplicate correlation key values, it is necessary for the aggregator to record previous correlation key values in a cache. The size of this cache (the number of cached correlation keys) is specified as an argument to the cl o seC o rrel ati o nKeyO nC o mpl eti o n() DSL command. To specify a cache of unlimited size, you can pass a value of zero or a negative integer. For example, to specify a cache size of 10 0 0 0 key values: from("direct:start")

.aggregate(header("UniqueBatchID"), new MyConcatenateStrategy())

.completionSize(header("mySize"))

.closeCorrelationKeyOnCompletion(10000)

.to("mock:aggregated");

24 2

CHAPT ER 8 . MESSAG E RO UT ING

If an aggregate exchange completes with a duplicate correlation key value, the aggregator throws a C l o sed C o rrel ati o nKeyExcepti o n exception.

Gro upe d e xchange s

You can combine all of the aggregated exchanges in an outgoing batch into a single

o rg . apache. camel . i mpl . G ro uped Exchang e holder class. To enable grouped exchanges, specify the g ro upExchang es() option, as shown in the following Java DSL route: from("direct:start")

.aggregate(header("StockSymbol"))

.completionTimeout(3000)

.groupExchanges()

.to("mock:result");

The grouped exchange sent to mo ck: resul t contains the list of aggregated exchanges in the message body. The following line of code shows how a subsequent processor can access the contents of the grouped exchange in the form of a list:

// Java

List<Exchange> grouped = ex.getIn().getBody(List.class);

No t e

When you enable the grouped exchanges feature, you must not configure an aggregation strategy (the grouped exchanges feature is itself an aggregation strategy).

No t e

The old approach of accessing the grouped exchanges from a property on the outgoing exchange is now deprecated and will be removed in a future release.

Bat ch co nsum e r

The aggregator can work together with the batch consumer pattern to aggregate the total number of messages reported by the batch consumer (a batch consumer endpoint sets the

C amel BatchSi ze, C amel BatchInd ex , and C amel BatchC o mpl ete properties on the incoming exchange). For example, to aggregate all of the files found by a File consumer endpoint, you could use a route like the following: from("file://inbox")

.aggregate(xpath("//order/@ customerId"), new

AggregateCustomerOrderStrategy())

.completionFromBatchConsumer()

.to("bean:processOrder");

24 3

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Currently, the following endpoints support the batch consumer mechanism: File, FTP, Mail, iBatis, and JPA.

Pe rsist e nt aggre gat io n re po sit o ry

If you want pending aggregated exchanges to be stored persistently, you can use either the

HawtDB component or the SQL Component for persistence support as a persistent aggregation repository. For example, if using HawtDB, you need to include a dependency on the camel -hawtd b component in your Maven POM. You can then configure a route to use the HawtDB aggregation repository as follows: public void configure() throws Exception {

HawtDBAggregationRepository repo = new

AggregationRepository("repo1", "target/data/hawtdb.dat");

from("direct:start")

.aggregate(header("id"), new UseLatestAggregationStrategy())

.completionTimeout(3000)

.aggregationRepository(repo)

.to("mock:aggregated");

}

The HawtDB aggregation repository has a feature that enables it to recover and retry any failed exchanges (that is, any exchange that raised an exception while it was being

processed by the latter part of the route). Figure 8.7, “ Recoverable Aggregation Repository”

shows an overview of the recovery mechanism.

Fig u re 8.7. Reco verab le Ag g reg at io n Rep o sit o ry

24 4

The recovery mechanism works as follows:

1. The aggregator creates a dedicated recovery thread, which runs in the background, scanning the aggregation repository to find any failed exchanges.

2. Each failed exchange is checked to see whether its current redelivery count exceeds the maximum redelivery limit. If it is under the limit, the recovery task resubmits the exchange for processing in the latter part of the route.

3. If the current redelivery count is over the limit, the failed exchange is passed to the dead letter queue.

CHAPT ER 8 . MESSAG E RO UT ING

For more details about the HawtDB component, see chapter "HawtDB" in "Apache Camel

Component Reference" .

T hre ading o pt io ns

As shown in Figure 8.6, “ Aggregator Implementation”

, the aggregator is decoupled from the latter part of the route, where the exchanges sent to the latter part of the route are processed by a dedicated thread pool. By default, this pool contains just a single thread. If you want to specify a pool with multiple threads, enable the paral l el P ro cessi ng option, as follows: from("direct:start")

.aggregate(header("id"), new UseLatestAggregationStrategy())

.completionTimeout(3000)

.parallelProcessing()

.to("mock:aggregated");

By default, this creates a pool with 10 worker threads.

If you want to exercise more control over the created thread pool, specify a custom

java. uti l . co ncurrent. Executo rServi ce

instance using the executo rServi ce option (in which case it is unnecessary to enable the paral l el P ro cessi ng option).

Aggre gat ing int o a List

A common aggregation scenario involves aggregating a series of incoming message bodies into a Li st object. To facilitate this scenario, Apache Camel provides the

AbstractLi stAg g reg ati o nStrateg y abstract class, which you can quickly extend to create an aggregation strategy for this case. Incoming message bodies of type, T , are aggregated into a completed exchange, with a message body of type Li st<T >.

For example, to aggregate a series of Integ er message bodies into a Li st<Integ er> object, you could use an aggregation strategy defined as follows: import org.apache.camel.processor.aggregate.AbstractListAggregationStrategy;

...

/**

* Strategy to aggregate integers into a List<Integer>.

*/ public final class MyListOfNumbersStrategy extends

AbstractListAggregationStrategy<Integer> {

@ Override

public Integer getValue(Exchange exchange) {

// the message body contains a number, so just return that asis

return exchange.getIn().getBody(Integer.class);

}

Aggre gat o r o pt io ns

24 5

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Aggre gat o r o pt io ns

The aggregator supports the following options:

T ab le 8.3. Ag g reg at o r O p t io n s

O pt ion co rrel ati o nExpressi o n

Default ag g reg ati o nStrateg y strateg yR ef

Descript ion

Mand ato ry Exp ressio n which evaluates the co rrelatio n key to use fo r ag g reg atio n. The

Exchang e which has the same co rrelatio n key is ag g reg ated to g ether. If the co rrelatio n key co uld no t b e evaluated an Excep tio n is thro wn. Yo u can d isab le this b y using the

i g no reBad C o rrel ati o n

Keys

o p tio n.

Mand ato ry

Ag g reg ati o nStrateg y

which is used to merge the inco ming Exchang e with the existing alread y merg ed exchang es. At first call the

o l d Exchang e

p arameter is

nul l

. O n sub seq uent invo catio ns the

o l d Exchang e

co ntains the merg ed exchang es and

newExchang e

is o f co urse the new inco ming Exchang e.

Fro m Camel 2.9 .2 o nward s, the strateg y can o p tio nally b e a

T i meo utAwareAg g reg at i o nStrateg y

imp lementatio n, which sup p o rts a timeo ut callb ack

A reference to lo o kup the

Ag g reg ati o nStrateg y

in the Reg istry.

24 6

O pt ion co mpl eti o nSi ze

Default co mpl eti o nT i meo ut co mpl eti o nInterval

CHAPT ER 8 . MESSAG E RO UT ING

Descript ion

Numb er o f messag es ag g reg ated b efo re the ag g reg atio n is co mp lete.

This o p tio n can b e set as either a fixed value o r using an Exp ressio n which allo ws yo u to evaluate a size d ynamically - will use

Integ er

as result. If b o th are set Camel will fallb ack to use the fixed value if the

Exp ressio n result was

nul l

o r

Time in millis that an ag g reg ated exchang e sho uld b e inactive b efo re its co mp lete. This o p tio n can b e set as either a fixed value o r using an Exp ressio n which allo ws yo u to evaluate a timeo ut d ynamically - will use

Lo ng

as result. If b o th are set Camel will fallb ack to use the fixed value if the

Exp ressio n result was

nul l

o r

. Yo u canno t use this o p tio n to g ether with co mp letio nInterval, o nly o ne o f the two can b e used .

A rep eating p erio d in millis b y which the ag g reg ato r will co mp lete all current ag g reg ated exchang es.

Camel has a b ackg ro und task which is trig g ered every p erio d . Yo u canno t use this o p tio n to g ether with co mp letio nTimeo ut, o nly o ne o f them can b e used .

24 7

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

O pt ion co mpl eti o nP red i cate

Default co mpl eti o nFro mBatchC o nsumer fal se

Descript ion

Sp ecifies a p red icate (o f

o rg . apache. camel . P re d i cate

typ e), which sig nals when an ag g reg ated exchang e is co mp lete.

Alternatively, instead o f setting this o p tio n, yo u can d efine a custo m

Ag g reg ati o nStrateg y

that imp lements the

P red i cate

interface, in which case the

Ag g reg ati o nStrateg y

will b e used as the co mp letio n p red icate.

This o p tio n is if the exchang es are co ming fro m a Batch Co nsumer. Then when enab led the

Ag g reg ato r

will use the b atch size d etermined b y the

Batch Co nsumer in the messag e head er

C amel BatchSi ze

. See mo re d etails at Batch

Co nsumer. This can b e used to ag g reg ate all files co nsumed fro m a File end p o int in that g iven p o ll.

24 8

O pt ion Default eag erC heckC o mpl eti o n fal se fo rceC o mpl eti o nO nSto p fal se g ro upExchang es fal se

CHAPT ER 8 . MESSAG E RO UT ING

Descript ion

Whether o r no t to eag er check fo r co mp letio n when a new inco ming Exchang e has b een received . This o p tio n influences the b ehavio r o f the

co mpl eti o nP red i cate

o p tio n as the Exchang e b eing p assed in chang es acco rd ing ly. When

fal se

the Exchang e p assed in the

Pred icate is the aggregated

Exchang e which means any info rmatio n yo u may sto re o n the ag g reg ated Exchang e fro m the

Ag g reg ati o nStrateg y

is availab le fo r the Pred icate.

When

true

the Exchang e p assed in the Pred icate is the incoming Exchang e, which means yo u can access d ata fro m the inco ming Exchang e.

true

, co mp lete all ag g reg ated exchang es when the current ro ute co ntext is sto p p ed .

If enab led then Camel will g ro up all ag g reg ated

Exchang es into a sing le co mb ined

o rg . apache. camel . i mp l . G ro uped Exchang e

ho ld er class that ho ld s all the ag g reg ated Exchang es.

And as a result o nly o ne

Exchang e is b eing sent o ut fro m the ag g reg ato r. Can b e used to co mb ine many inco ming Exchang es into a sing le o utp ut Exchang e witho ut co d ing a custo m

Ag g reg ati o nStrateg y

yo urself.

24 9

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

O pt ion i g no reInval i d C o rrel ati o nKeys

Default fal se cl o seC o rrel ati o nKeyO nC o mpl eti o n d i scard O nC o mpl eti o n

T i meo ut ag g reg ati o nR epo si to r y fal se

Descript ion

Whether o r no t to ig no re co rrelatio n keys which co uld no t b e evaluated to a value.

By d efault Camel will thro w an Excep tio n, b ut yo u can enab le this o p tio n and ig no re the situatio n instead .

Whether o r no t late

Exchang es sho uld b e accep ted o r no t. Yo u can enab le this to ind icate that if a co rrelatio n key has alread y b een co mp leted , then any new exchang es with the same co rrelatio n key b e d enied .

Camel will then thro w a

cl o sed C o rrel ati o nKey

Excepti o n

excep tio n.

When using this o p tio n yo u p ass in a

i nteg er

which is a numb er fo r a LRUCache which keep s that last X numb er o f clo sed co rrelatio n keys. Yo u can p ass in 0 o r a neg ative value to ind icate a unb o und ed cache. By p assing in a numb er yo u are ensured that cache wo nt g ro wn to o b ig if yo u use a lo g o f d ifferent co rrelatio n keys.

Camel 2 .5: Whether o r no t exchang es which co mp lete d ue to a timeo ut sho uld b e d iscard ed . If enab led , then when a timeo ut o ccurs the ag g reg ated messag e will

not b e sent o ut b ut d ro p p ed

(d iscard ed ).

Allo ws yo u to p lug in yo u o wn imp lementatio n o f

o rg . apache. camel . spi

. Ag g reg ati o nR epo si t o ry

which keep s track o f the current inflig ht ag g reg ated exchang es. Camel uses b y d efault a memo ry b ased imp lementatio n.

250

O pt ion ag g reg ati o nR epo si to r yR ef

Default paral l el P ro cessi ng fal se executo rServi ce executo rServi ceR ef ti meo utC heckerExecut o rServi ce ti meo utC heckerExecut o rServi ceR ef

CHAPT ER 8 . MESSAG E RO UT ING

Descript ion

Reference to lo o kup a

ag g reg ati o nR epo si to r y

in the Reg istry.

When ag g reg ated are co mp leted they are b eing send o ut o f the ag g reg ato r.

This o p tio n ind icates whether o r no t Camel sho uld use a thread p o o l with multip le thread s fo r co ncurrency. If no custo m thread p o o l has b een sp ecified then Camel creates a d efault p o o l with 10 co ncurrent thread s.

If using

paral l el P ro cessi ng

yo u can sp ecify a custo m thread p o o l to b e used . In fact also if yo u are no t using

paral l el P ro cessi ng

this custo m thread p o o l is used to send o ut ag g reg ated exchang es as well.

Reference to lo o kup a

executo rServi ce

in the

Reg istry

If using o ne o f the

co mpl eti o nT i meo ut

co mpl eti o nT i meo utExp ressi o n

, o r

co mpl eti o nInterval

o p tio ns, a b ackg ro und thread is created to check fo r the co mp letio n fo r every ag g reg ato r. Set this o p tio n to p ro vid e a custo m thread p o o l to b e used rather than creating a new thread fo r every ag g reg ato r.

Reference to lo o k up a

ti meo utC heckerExecut o rServi ce

in the reg istry.

251

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

O pt ion o pti mi sti cLo cki ng

Default fal se

Descript ion

Turns o n o p timistic lo cking , which can b e used in co mb inatio n with an ag g reg atio n rep o sito ry.

Co nfig ures the retry p o licy fo r o p timistic lo cking .

o pti mi sti cLo ckR etryP o l i cy

8.6. Resequencer

Ove rvie w

The resequencer pattern, shown in

Figure 8.8, “ Resequencer Pattern” , enables you to

resequence messages according to a sequencing expression. Messages that generate a low value for the sequencing expression are moved to the front of the batch and messages that generate a high value are moved to the back.

Fig u re 8.8. Reseq u en cer Pat t ern

252

Apache 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 cases where a message arrives with the same message expression. However, in batch mode you can enable the resequencer to allow duplicates.

Bat ch re se que ncing

The batch resequencing algorithm is enabled by default. For example, to resequence a batch of incoming messages based on the value of a timestamp contained in the

T i meStamp header, you can define the following route in Java DSL:

CHAPT ER 8 . MESSAG E RO UT ING

from("direct:start").resequence(header("TimeStamp")).to("mock:result")

;

By default, the batch is obtained by collecting all of the incoming messages that arrive in a time interval of 1000 milliseconds (default batch timeout), up to a maximum of 100 messages

(default batch size). You can customize the values of the batch timeout and the batch size by appending a batch() DSL command, which takes a BatchR eseq uencerC o nfi g instance as its sole argument. For example, to modify the preceding route so that the batch consists of messages collected in a 4000 millisecond time window, up to a maximum of 300 messages, you can define the Java DSL route as follows: import org.apache.camel.model.config.BatchResequencerConfig;

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from("direct:start").resequence(header("TimeStamp")).batch(new

BatchResequencerConfig(300,4000L)).to("mock:result");

}

};

You can also specify a batch resequencer pattern using XML configuration. The following example defines a batch resequencer with a batch size of 300 and a batch timeout of 4000 milliseconds:

<route>

<!--

batch-config can be omitted for default (batch) resequencer settings

-->

<batch-config batchSize="300" batchTimeout="4000" />

<simple>header.TimeStamp</simple>

</resequence>

</route>

</camelContext>

Bat ch o pt io ns

Table 8.4, “ Batch Resequencer Options”

shows the options that are available in batch mode only.

T ab le 8.4 . Bat ch Reseq u en cer O p t io n s

253

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Java DSL XML DSL al l o wD upl i cate s() batchco nfi g /@ al l o w

D upl i cates

Default fal se reverse() batchco nfi g /@ revers e fal se

Descript ion

true

, d o no t d iscard d up licate messag es fro m the b atch (where

duplicate means that the messag e exp ressio n evaluates to the same value).

true

, p ut the messag es in reverse o rd er (where the d efault o rd ering ap p lied to a messag e exp ressio n is b ased o n Java's string lexical o rd ering , as d efined

b y

String .co mp areTo () )

254

For example, if you want to resequence messages from JMS queues based on

JMSP ri o ri ty, you would need to combine the options, al l o wD upl i cates and reverse, as follows: 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).allowDuplica

tes().reverse()

.to("mock:result");

St re am re se que ncing

To enable the stream resequencing algorithm, you must append stream() to the

reseq uence() DSL command. For example, to resequence incoming messages based on the value of a sequence number in the seq num header, you define a DSL route as follows: from("direct:start").resequence(header("seqnum")).stream().to("mock:re sult");

The stream-processing resequencer algorithm is based on the detection of gaps in a message stream, rather than on a fixed batch size. Gap detection, in combination with timeouts, removes the constraint of needing to know the number of messages of a sequence

CHAPT ER 8 . MESSAG E RO UT ING

(that is, 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 successor of 3 is missing. The resequencer therefore must retain message 5 until message 4 arrives (or a timeout occurs).

By default, the stream resequencer is configured with a timeout of 1000 milliseconds, and a maximum message capacity of 100. To customize the stream's timeout and message capacity, you can pass a StreamR eseq uencerC o nfi g object as an argument to

stream(). For example, to configure a stream resequencer with a message capacity of 5000 and a timeout of 4000 milliseconds, you define a route as follows:

// Java import org.apache.camel.model.config.StreamResequencerConfig;

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from("direct:start").resequence(header("seqnum")).

stream(new StreamResequencerConfig(5000, 4000L)).

to("mock:result");

}

};

If the maximum time delay between successive messages (that is, messages with adjacent sequence numbers) in a message stream is known, the resequencer's timeout parameter should be set to this value. In this case, you can guarantee that all messages in the stream are delivered in the correct order to the next processor. The lower the timeout value that is compared to the out-of-sequence time difference, the more likely it is that the resequencer will deliver messages out of sequence. Large timeout values should be supported by sufficiently high capacity values, where the capacity parameter is used to prevent the resequencer from running out of memory.

If you want to use sequence numbers of some type other than l o ng , you would must define a custom comparator, as follows:

// Java

ExpressionResultComparator<Exchange> comparator = new MyComparator();

StreamResequencerConfig config = new StreamResequencerConfig(5000,

4000L, comparator); from("direct:start").resequence(header("seqnum")).stream(config).to("m ock:result");

You can also specify a stream resequencer pattern using XML configuration. The following example defines a stream resequencer with a message capacity of 5000 and a timeout of

4000 milliseconds:

<route>

<stream-config capacity="5000" timeout="4000"/>

255

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

<simple>header.seqnum</simple>

</resequence>

</route>

</camelContext>

Igno re invalid e xchange s

The resequencer EIP throws a C amel Exchang eExcepti o n exception, if the incoming exchange is not valid—that is, if the sequencing expression cannot be evaluated for some reason (for example, due to a missing header). You can use the

i g no reInval i d Exchang es option to ignore these exceptions, which means the resequencer will skip any invalid exchanges.

from("direct:start")

.resequence(header("seqno")).batch().timeout(1000)

// ignore invalid exchanges (they are discarded)

.i g no reInval i d Exchang es()

.to("mock:result");

Re je ct o ld m e ssage s

The rejectO l d option can be used to prevent messages being sent out of order, regardless of the mechanism used to resequence messages. When the rejectO l d option is enabled, the resequencer rejects an incoming message (by throwing a

Messag eR ejected Excepti o n exception), if the incoming messages is older (as defined by the current comparator) than the last delivered message.

from("direct:start")

.onException(MessageRejectedException.class).handled(true).to("moc k:error").end()

.resequence(header("seqno")).stream().timeout(1000). rejectO l d ()

.to("mock:result");

8.7. Rout ing Slip

Ove rvie w

The routing slip pattern, shown in Figure 8.9, “ Routing Slip Pattern”

, enables 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. The list of endpoints through which the message should pass is stored in a header field (the slip), which Apache Camel reads at run time to construct a pipeline on the fly.

Fig u re 8.9 . Ro u t in g Slip Pat t ern

256

CHAPT ER 8 . MESSAG E RO UT ING

T he slip he ade r

The routing slip appears in a user-defined header, where the header value is a commaseparated list of endpoint URIs. For example, a routing slip that specifies a sequence of security tasks—decrypting, authenticating, and de-duplicating a message—might look like the following: cxf:bean:decrypt,cxf:bean:authenticate,cxf:bean:dedup

T he curre nt e ndpo int pro pe rt y

From Camel 2.5 the Routing Slip will set a property (Exchang e. SLIP _END P O INT ) on the exchange which contains the current endpoint as it advanced though the slip. This enables you to find out how far the exchange has progressed through 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-fly then use the Dynamic Router pattern instead.

Java DSL e xam ple

The following route takes messages from the d i rect: a endpoint and reads a routing slip from the aR o uti ng Sl i pHead er header: from("direct:b").routingSlip("aRoutingSlipHeader");

You can specify the header name either as a string literal or as an expression.

You can also customize the URI delimiter using the two-argument form of ro uti ng Sl i p().

The following example defines a route that uses the aR o uti ng Sl i pHead er header key for the routing slip and uses the # character as the URI delimiter: from("direct:c").routingSlip("aRoutingSlipHeader", "#");

XML co nfigurat io n e xam ple

257

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

XML co nfigurat io n e xam ple

The following example shows how to configure the same route in XML:

<route>

<headerName>aRoutingSlipHeader</headerName>

</routingSlip>

</route>

</camelContext>

Igno re invalid e ndpo int s

The

Routing Slip now supports i g no reInval i d End po i nts, which the

is absent, then the Throttler

pattern also supports. You can use it to skip endpoints that are invalid. For example: from("direct:a").routingSlip("myHeader").ignoreInvalidEndpoints();

In Spring XML, this feature is enabled by setting the i g no reInval i d End po i nts attribute on the <ro uti ng Sl i p> tag:

<route>

<headerName>myHeader</headerName>

</routingSlip>

</route>

Consider the case where myHead er contains the two endpoints, d i rect: fo o ,xxx: bar.

The first endpoint is valid and works. The second is invalid and, therefore, ignored. Apache

Camel logs at INFO level whenever an invalid endpoint is encountered.

Opt io ns

The ro uti ng Sl i p DSL command supports the following options:

Name uri D el i mi ter

Default Value

Descript ion

Delimiter used if the

Exp ressio n returned multip le end p o ints.

258

i g no reInval i d End po i nts fal se cacheSi ze 0

CHAPT ER 8 . MESSAG E RO UT ING

If an end p o int uri co uld no t b e reso lved , sho uld it b e ig no red . O therwise Camel will thro wn an excep tio n stating the end p o int uri is no t valid .

8.8. T hrot t ler

Ove rvie w

A throttler is a processor that limits the flow rate of incoming messages. You can use this pattern to protect a target endpoint from getting overloaded. In Apache Camel, you can implement the throttler pattern using the thro ttl e() Java DSL command.

Java DSL e xam ple

To limit the flow rate to 100 messages per second, define a route as follows: from("seda:a").throttle(100).to("seda:b");

If necessary, you can customize the time period that governs the flow rate using the

ti meP eri o d Mi l l i s() DSL command. For example, to limit the flow rate to 3 messages per 30000 milliseconds, define a route as follows: from("seda:a").throttle(3).timePeriodMillis(30000).to("mock:result");

XML co nfigurat io n e xam ple

The following example shows how to configure the preceding route in XML:

<route>

259

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

</throttle>

</route>

</camelContext>

Dynam ically changing m axim um re que st s pe r pe rio d

Availab le o s o f 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. l ang . Lo ng type. In the example below we use a header from the message to determine the maximum requests per period. If the header

uses the old value. So that allows you to only provide a header if the value is to be changed:

<route>

<!-- use a header to determine how many messages to throttle per

0.5 sec -->

<header>throttleValue</header>

</throttle>

</route>

</camelContext>

Asynchro no us de laying

The throttler can enable non-blocking asynchronous delaying, which means that Apache Camel schedules a task to be executed in the future. The task is responsible for processing the latter part of the route (after the throttler). This allows the caller thread to unblock and service further incoming messages. For example: from("seda:a").throttle(100).asyncDelayed().to("seda:b");

Opt io ns

The thro ttl e DSL command supports the following options:

Name Default Value Descript ion

260

maxi mumR eq uestsP erP e ri o d ti meP eri o d Mi l l i s asyncD el ayed executo rServi ceR ef

10 0 0 fal se cal l erR unsWhenR eject ed true

CHAPT ER 8 . MESSAG E RO UT ING

Maximum numb er o f req uests p er p erio d to thro ttle. This o p tio n must b e p ro vid ed and a p o sitive numb er. No tice, in the XML

DSL, fro m Camel 2 .8 o nward s this o p tio n is co nfig ured using an

Exp ressio n instead o f an attrib ute.

The time p erio d in millis, in which the thro ttler will allo w at mo st

maxi mumR eq uestsP erP e ri o d

numb er o f messag es.

Camel 2 .4 : If enab led then any messag es which is d elayed hap p ens asynchro no usly using a sched uled thread p o o l.

Camel 2 .4 : Refers to a custo m Thread Po o l to b e used if

asyncD el ay

has b een enab led .

Camel 2 .4 : Is used if

asyncD el ayed

was enab led . This co ntro ls if the caller thread sho uld execute the task if the thread p o o l rejected the task.

8.9. Delayer

Ove rvie w

A delayer is a processor that enables you to apply a relative time delay to incoming messages.

Java DSL e xam ple

You can use the d el ay() command to add a relative time delay, in units of milliseconds, to incoming messages. For example, the following route delays all incoming messages by 2 seconds: from("seda:a").delay(2000).to("mock:result");

261

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Alternatively, you can specify the time delay using an expression: from("seda:a").delay(header("MyDelay")).to("mock:result");

The DSL commands that follow d el ay() are interpreted as sub-clauses of d el ay().

Hence, in some contexts it is necessary to terminate the sub-clauses of delay() by inserting the end () command. For example, when d el ay() appears inside an o nExcepti o n() clause, you would terminate it as follows: from("direct:start")

.onException(Exception.class)

.maximumRedeliveries(2)

.backOffMultiplier(1.5)

.handled(true)

.delay(1000)

.log("Halting for some time")

.to("mock:halt")

.end()

.to("mock:result");

XML co nfigurat io n e xam ple

The following example demonstrates the delay in XML DSL:

<route>

<delay>

<header>MyDelay</header>

</delay>

</route>

<route>

<delay>

</delay>

</route>

</camelContext>

Cre at ing a cust o m de lay

You can use an expression combined with a bean to determine the delay as follows: from("activemq:foo").

delay().expression().method("someBean", "computeDelay").

to("activemq:bar");

262

Where the bean class could be defined as follows:

CHAPT ER 8 . MESSAG E RO UT ING

public class SomeBean {

public long computeDelay() {

long delay = 0;

// use java code to compute a delay value in millis

return delay;

}

Asynchro no us de laying

You can let the delayer use non-blocking asynchronous delaying, which means that Apache

Camel schedules a task to be executed in the future. The task is responsible for processing the latter part of the route (after the delayer). This allows the caller thread to unblock and service further incoming messages. For example: from("activemq:queue:foo")

.delay(1000)

.asyncDelayed()

.to("activemq:aDelayedQueue");

The same route can be written in the XML DSL, as follows:

<route>

<constant>1000& lt;/constant>

</delay>

</route>

Opt io ns

The delayer pattern supports the following options:

Name asyncD el ayed executo rServi ceR ef

Default Value fal se

Descript ion

Camel 2 .4 : If enab led then d elayed messag es hap p ens asynchro no usly using a sched uled thread p o o l.

Camel 2 .4 : Refers to a custo m Thread Po o l to b e used if

asyncD el ay

has b een enab led .

263

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide cal l erR unsWhenR eject ed true

Camel 2 .4 : Is used if

asyncD el ayed

was enab led . This co ntro ls if the caller thread sho uld execute the task if the thread p o o l rejected the task.

8.10. Load Balancer

Ove rvie w

The load balancer pattern allows you to delegate message processing to one of several endpoints, using a variety of different load-balancing policies.

Java DSL e xam ple

The following route distributes incoming messages between the target endpoints, mo ck: x,

mo ck: y, mo ck: z, using a round robin load-balancing policy: from("direct:start").loadBalance().roundRobin().to("mock:x", "mock:y",

"mock:z");

XML co nfigurat io n e xam ple

The following example shows how to configure the same route in XML:

<route>

</loadBalance>

</route>

</camelContext>

Lo ad-balancing po licie s

264

The Apache Camel load balancer supports the following load-balancing policies:

Round robin

Random

Sticky

CHAPT ER 8 . MESSAG E RO UT ING

Topic

the section called “ Failover”

the section called “ Weighted round robin and weighted random”

the section called “ Custom Load Balancer”

Circuit Breaker

Ro und ro bin

The round robin load-balancing policy cycles through all of the target endpoints, sending each incoming message to the next endpoint in the cycle. For example, if the list of target endpoints is, mo ck: x, mo ck: y, mo ck: z, then the incoming messages are sent to the following sequence of endpoints: mo ck: x, mo ck: y, mo ck: z, mo ck: x, mo ck: y, mo ck: z, and so on.

You can specify the round robin load-balancing policy in Java DSL, as follows: from("direct:start").loadBalance().roundRobin().to("mock:x", "mock:y",

"mock:z");

Alternatively, you can configure the same route in XML, as follows:

<route>

</loadBalance>

</route>

</camelContext>

Rando m

The random load-balancing policy chooses the target endpoint randomly from the specified list.

You can specify the random load-balancing policy in Java DSL, as follows: from("direct:start").loadBalance().random().to("mock:x", "mock:y",

"mock:z");

Alternatively, you can configure the same route in XML, as follows:

265

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

<route>

</loadBalance>

</route>

</camelContext>

St icky

The sticky load-balancing policy directs the In message to an endpoint that is chosen by calculating a hash value from a specified expression. The advantage of this load-balancing policy is that expressions of the same value are always sent to the same server. For example, by calculating the hash value from a header that contains a username, you ensure that messages from a particular user are always sent to the same target endpoint. Another useful approach is to specify an expression that extracts the session ID from an incoming message. This ensures that all messages belonging to the same session are sent to the same target endpoint.

You can specify the sticky load-balancing policy in Java DSL, as follows: from("direct:start").loadBalance().sticky(header("username")).to("mock

:x", "mock:y", "mock:z");

Alternatively, you can configure the same route in XML, as follows:

<route>

<simple>header.username</simple>

</expression>

</sticky>

</loadBalance>

</route>

</camelContext>

266

T o pic

The topic load-balancing policy sends a copy of each In message to all of the listed destination endpoints (effectively broadcasting the message to all of the destinations, like a

JMS topic).

CHAPT ER 8 . MESSAG E RO UT ING

You can use the Java DSL to specify the topic load-balancing policy, as follows: from("direct:start").loadBalance().topic().to("mock:x", "mock:y",

"mock:z");

Alternatively, you can configure the same route in XML, as follows:

<route>

</loadBalance>

</route>

</camelContext>

Failo ve r

Availab le as o f Ap ach e Camel 2.0 The fai l o ver load balancer is capable of trying the next processor in case an Exchange failed with an excepti o n during processing. You can configure the fai l o ver with a list of specific exceptions that trigger failover. If you do not specify any exceptions, failover is triggered by any exception. The failover load balancer uses the same strategy for matching exceptions as the o nExcepti o n exception clause.

En ab le st ream cach in g if u sin g st reams

If you use streaming, you should enable Stream Caching when using the failover load balancer. This is needed so the stream can be re-read when failing over.

The fai l o ver load balancer supports the following options:

O pt ion T ype Default Descript ion

267

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide i nheri tErro rHan d l er bo o l ean true

Camel 2 .3: Sp ecifies whether to use the

erro rHand l er

co nfig ured o n the ro ute. If yo u want to fail o ver immed iately to the next end p o int, yo u sho uld d isab le this o p tio n (value o f

fal se

). If yo u enab le this o p tio n,

Ap ache Camel will first attemp t to p ro cess the messag e using the

erro rHand l er

Fo r examp le, the

erro rHand l er

mig ht b e co nfig ured to red eliver messag es and use d elays b etween attemp ts. Ap ache

Camel will initially try to red eliver to the

original end p o int, and o nly fail o ver to the next end p o int when the

erro rHand l er

is exhausted .

maxi mumFai l o ve rAttempts i nt -1

Camel 2 .3: Sp ecifies the maximum numb er o f attemp ts to fail o ver to a new end p o int. The value,

, imp lies that no failo ver attemp ts are mad e and the value,

-1

, imp lies an infinite numb er o f failo ver attemp ts.

268

CHAPT ER 8 . MESSAG E RO UT ING ro und R o bi n bo o l ean fal se

Camel 2 .3: Sp ecifies whether the

fai l o ver

lo ad b alancer sho uld o p erate in ro und ro b in mo d e o r no t. If no t, it will always start fro m the first end p o int when a new messag e is to b e p ro cessed . In o ther wo rd s it restarts fro m the to p fo r every messag e. If ro und ro b in is enab led , it keep s state and co ntinues with the next end p o int in a ro und ro b in fashio n. When using ro und ro b in it will no t stick to last kno wn g o o d end p o int, it will always p ick the next end p o int to use.

The following example is configured to fail over, only if an IO Excepti o n exception is 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 optionally specify multiple exceptions to fail over, as follows:

// enable redelivery so failover can react errorHandler(defaultErrorHandler().maximumRedeliveries(5)); from("direct:foo")

.loadBalance()

.failover(IOException.class, MyOtherException.class)

.to("direct:a", "direct:b");

You can configure the same route in XML, as follows:

269

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

<exception>java.io.IOException</exception>

<exception>com.mycompany.MyOtherException</exception>

</failover>

</loadBalance>

</route>

The following example shows how to fail over in round robin mode: from("direct:start")

// Use failover load balancer in stateful round robin mode,

// which means it will fail over immediately in case of an exception

// as it does NOT inherit error handler. It will also keep retrying, as

// it is configured to retry indefinitely.

.loadBalance().failover(-1, false, true)

.to("direct:bad", "direct:bad2", "direct:good", "direct:good2");

You can configure the same route in XML, as follows:

<route>

<!-- failover using stateful round robin,

which will keep retrying the 4 endpoints indefinitely.

You can set the maximumFailoverAttempt to break out after X attempts -->

</loadBalance>

</route>

We ight e d ro und ro bin and we ight e d rando m

In many enterprise environments, where server nodes of unequal processing power are hosting services, it is usually preferable to distribute the load in accordance with the individual server processing capacities. A weighted round robin algorithm or a weighted random algorithm 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 the others. You can specify this value as a positive processing weight for each server. A larger number indicates that the server can handle a larger load.

The processing weight is used to determine the payload distribution ratio of each processing endpoint with respect to the others.

270

CHAPT ER 8 . MESSAG E RO UT ING

The parameters that can be used are

T ab le 8.5. Weig h t ed O p t io n s

O pt ion ro und R o bi n d i stri buti o nR a ti o D el i mi ter

T ype bo o l ean

Stri ng

Default fal se

Descript ion

The d efault value fo r ro und -ro b in is

fal se

. In the ab sence o f this setting o r p arameter, the lo ad -b alancing alg o rithm used is rand o m.

The

d i stri buti o nR a ti o D el i mi ter

is the d elimiter used to sp ecify the

d i stri buti o nR a ti o

. If this attrib ute is no t sp ecified , co mma

is the d efault d elimiter.

The following Java DSL examples show how to define a weighted round-robin route and a weighted random route:

// Java

// 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");

You can configure the round-robin route in XML, as follows:

<route>

271

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

</loadBalance>

</route>

Cust o m Lo ad Balance r

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

Lo ad Bal ancerSuppo rt and Si mpl eLo ad Bal ancerSuppo rt. The former supports the asynchronous routing engine, and the latter does not. Here is an example:

272

CHAPT ER 8 . MESSAG E RO UT ING

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;

}

Circuit Bre ake r

The Circuit Breaker load balancer is a stateful pattern that is used to monitor all calls for certain exceptions. Initially, the Circuit Breaker is in closed state and passes all messages. If there are failures and the threshold is reached, it moves to open state and rejects all calls until hal fO penAfter timeout is reached. After the timeout, if there is a new call, the Circuit

Breaker passes all the messages. If the result is success, the Circuit Breaker moves to a closed state, if not, it moves back to open state.

Java DSL example: from( "direct:start" ).loadBalance()

.circuitBreaker( 2 , 1000L , MyCustomException.class)

.to( "mock:result" );

Spring XML example:

<route>

<exception>MyCustomException</exception>

</circuitBreaker>

</loadBalance>

</route>

</camelContext>

273

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

8.11. Mult icast

Ove rvie w

The multicast pattern, shown in Figure 8.10, “ Multicast Pattern”

, is a variation of the recipient list with a fixed destination pattern, which is compatible with the InOut message exchange

pattern. This is in contrast to recipient list, which is only compatible with the InOnly exchange pattern.

Fig u re 8.10. Mu lt icast Pat t ern

Mult icast wit h a cust o m aggre gat io n st rat e gy

Whereas the multicast processor receives multiple Out messages in response to the original request (one from each of the recipients), the original caller is only expecting to receive a

single reply. Thus, there is an inherent mismatch on the reply leg of the message exchange, and to overcome this mismatch, you must provide a custom aggregation strategy to the multicast processor. The aggregation strategy class is responsible for aggregating all of the

Out messages into a single reply message.

Consider the example of an electronic auction service, where a seller offers an item for sale to a list of buyers. The buyers each put in a bid for the item, and the seller automatically selects the bid with the highest price. You can implement the logic for distributing an offer to a fixed list of buyers using the mul ti cast() DSL command, as follows: from("cxf:bean:offer").multicast(new HighestBidAggregationStrategy()).

to("cxf:bean:Buyer1", "cxf:bean:Buyer2", "cxf:bean:Buyer3");

274

Where the seller is represented by the endpoint, cxf: bean: o ffer, and the buyers are represented by the endpoints, cxf: bean: Buyer1, cxf: bean: Buyer2,

cxf: bean: Buyer3. To consolidate the bids received from the various buyers, the multicast processor uses the aggregation strategy, Hi g hestBi d Ag g reg ati o nStrateg y. You can implement the Hi g hestBi d Ag g reg ati o nStrateg y in Java, as follows:

// Java import org.apache.camel.processor.aggregate.AggregationStrategy;

CHAPT ER 8 . MESSAG E RO UT ING

import org.apache.camel.Exchange; public class HighestBidAggregationStrategy implements

AggregationStrategy {

public Exchange aggregate(Exchange oldExchange, Exchange newExchange) {

float oldBid = oldExchange.getOut().getHeader("Bid",

Float.class);

float newBid = newExchange.getOut().getHeader("Bid",

Float.class);

return (newBid > oldBid) ? newExchange : oldExchange;

}

Where it is assumed that the buyers insert the bid price into a header named, Bi d . For more

details about custom aggregation strategies, see Section 8.5, “ Aggregator” .

Paralle l pro ce ssing

By default, the multicast processor invokes each of the recipient endpoints one after another

(in the order listed in the to () command). In some cases, this might cause unacceptably long latency. To avoid these long latency times, you have the option of enabling parallel processing by adding the paral l el P ro cessi ng () clause. For example, to enable parallel processing in the electronic auction example, define the route as follows: from("cxf:bean:offer")

.multicast(new HighestBidAggregationStrategy())

.parallelProcessing()

.to("cxf:bean:Buyer1", "cxf:bean:Buyer2", "cxf:bean:Buyer3");

Where the multicast processor now invokes the buyer endpoints, using a thread pool that has one thread for each of the endpoints.

If you want to customize the size of the thread pool that invokes the buyer endpoints, you can invoke the executo rServi ce() method to specify your own custom executor service.

For example: from("cxf:bean:offer")

.multicast(new HighestBidAggregationStrategy())

.executorService(MyExecutor)

.to("cxf:bean:Buyer1", "cxf:bean:Buyer2", "cxf:bean:Buyer3");

Where MyExecutor is an instance of java.util.concurrent.ExecutorService

type.

When the exchange has an InOut pattern, an aggregation strategy is used to aggregate reply messages. The default aggregation strategy takes the latest reply message and discards earlier replies. For example, in the following route, the custom strategy,

MyAg g reg ati o nStrateg y, is used to aggregate the replies from the endpoints, d i rect: a,

d i rect: b, and d i rect: c: from("direct:start")

275

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

.multicast(new MyAggregationStrategy())

.parallelProcessing()

.timeout(500)

.to("direct:a", "direct:b", "direct:c")

.end()

.to("mock:result");

XML co nfigurat io n e xam ple

The following example shows how to configure a similar route in XML, where the route uses a custom aggregation strategy and a custom thread executor:

<?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-3.0.xsd

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

<route>

<multicast strategyRef="highestBidAggregationStrategy"

parallelProcessing="true"

threadPoolRef="myThreadExcutor">

</multicast>

</route>

</camelContext>

</beans>

Where both the paral l el P ro cessi ng attribute and the thread P o o l R ef attribute are optional. It is only necessary to set them if you want to customize the threading behavior of the multicast processor.

Apply cust o m pro ce ssing t o t he o ut go ing m e ssage s

Before multicast sends a message to one of the recipient endpoints, it creates a message replica, which is a shallow copy of the original message. If you want to perform some custom processing on each message replica before the replica is sent to its endpoint, you can invoke the o nP repare DSL command in the mul ti cast clause. The o nP repare command

276

CHAPT ER 8 . MESSAG E RO UT ING

inserts a custom processor just after the message has been shallow-copied and just before the message is dispatched to its endpoint. For example, in the following route, the

C usto mP ro c processor is invoked on the message sent to d i rect: a and the C usto mP ro c processor is also invoked on the message sent to d i rect: b.

from("direct:start")

.multicast().onPrepare(new CustomProc())

.to("direct:a").to("direct:b");

A common use case for the o nP repare DSL command is to perform a deep copy of some or all elements of a message. For example, the following C usto mP ro c processor class performs a deep copy of the message body, where the message body is presumed to be of type, BodyType, and the deep copy is performed by the method, BodyType. d eepC o py().

// Java import org.apache.camel.*;

...

public class CustomProc implements Processor {

public void process(Exchange exchange) throws Exception {

BodyType body = exchange.getIn().getBody(BodyType.class);

// Make a _deep_ copy of of the body object

BodyType clone = BodyType.deepCopy();

exchange.getIn().setBody(clone);

// Headers and attachments have already been

// shallow-copied. If you need deep copies,

// add some more code here.

}

No t e

Although the mul ti cast syntax allows you to invoke the pro cess DSL command in the mul ti cast clause, this does not make sense semantically and it does not have the same effect as o nP repare (in fact, in this context, the pro cess DSL command has no effect).

Using o nPre pare t o e xe cut e cust o m lo gic whe n pre paring m e ssage s

The

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 o nP repare which allows you to do this using the Processor interface.

Notice the o nP repare can be used for any kind of custom logic which you would like to execute before the Exchang e is being multicasted.

277

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

No t e

Its best practice to design for immutable objects.

278

For example if you have a mutable message body as this Animal class: 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;

}

Then we can create a deep clone processor which clones the message body: public class AnimalDeepClonePrepare implements Processor {

public void process(Exchange exchange) throws Exception {

CHAPT ER 8 . MESSAG E RO UT ING

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

route using the

o nP repare option as shown: from("direct:start")

.multicast().onPrepare(new

AnimalDeepClonePrepare()).to("direct:a").to("direct:b");

And the same example in XML DSL

<route>

</multicast>

</route>

<route>

</route>

<route>

</route>

</camelContext>

Opt io ns

The mul ti cast DSL command supports the following options:

279

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Default Value Name strateg yR ef strateg yMetho d Name strateg yMetho d Al l o wN ul l paral l el P ro cessi ng fal se fal se

Descript ion

Refers to an

Ag g reg atio nStrateg y to b e used to assemb le the rep lies fro m the multicasts, into a sing le o utg o ing messag e fro m the

Multicast . By d efault

Camel will use the last rep ly as the o utg o ing messag e.

This o p tio n can b e used to exp licitly sp ecify the metho d name to use, when using

PO JO s as the

Ag g reg ati o nStrateg y

This o p tio n can b e used , when using PO JO s as the

Ag g reg ati o nStrateg y

. If

fal se

, the

ag g reg ate

metho d is no t used , when there is no d ata to enrich. If

true

nul l

values are used fo r the

o l d Exchang e

, when there is no d ata to enrich.

If enab led , send ing messag es to the multicasts o ccurs co ncurrently. No te the caller thread will still wait until all messag es has b een fully p ro cessed , b efo re it co ntinues. Its o nly the send ing and p ro cessing the rep lies fro m the multicasts which hap p ens co ncurrently.

280

paral l el Ag g reg ate fal se executo rServi ceR ef sto pO nExcepti o n streami ng fal se fal se

CHAPT ER 8 . MESSAG E RO UT ING

If enab led , the

ag g reg ate

metho d o n

Ag g reg ati o nStrateg y

can b e called co ncurrently.

No te that this req uires the imp lementatio n o f

Ag g reg ati o nStrateg y

to b e thread -safe. By d efault, this o p tio n is

fal se

, which means that Camel auto matically synchro nizes calls to the

ag g reg ate

metho d . In so me use-cases, ho wever, yo u can imp ro ve p erfo rmance b y imp lementing

Ag g reg ati o nStrateg y

as thread -safe and setting this o p tio n to

true

Refers to a custo m Thread

Po o l to b e used fo r p arallel p ro cessing . No tice if yo u set this o p tio n, then p arallel p ro cessing is auto matic imp lied , and yo u d o no t have to enab le that o p tio n as well.

Camel 2 .2 : Whether o r no t to sto p co ntinue p ro cessing immed iately when an excep tio n o ccurred . If d isab le, then Camel will send the messag e to all multicasts reg ard less if o ne o f them failed . Yo u can d eal with excep tio ns in the

Ag g reg atio nStrateg y class where yo u have full co ntro l ho w to hand le that.

If enab led then Camel will p ro cess rep lies o ut-o f-o rd er, eg in the o rd er they co me b ack. If d isab led , Camel will p ro cess rep lies in the same o rd er as multicasted .

281

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide ti meo ut o nP repareR ef shareUni tO fWo rk fal se

Camel 2 .5: Sets a to tal timeo ut sp ecified in millis. If

the Multicast

hasn't b een ab le to send and p ro cess all rep lies within the g iven timeframe, then the timeo ut trig g ers and the

The composed message processor pattern, as shown in Figure 8.11, “ Composed Message

b reaks o ut and co ntinues.

No tice if yo u p ro vid e a

Timeo utAwareAg g reg atio nSt rateg y then the

ti meo ut

metho d is invo ked b efo re b reaking o ut.

Camel 2 .8 : Refers to a custo m Pro cesso r to p rep are the co p y o f the

Exchang e each multicast will receive. This allo ws yo u to d o any custo m lo g ic, such as d eep -clo ning the messag e p aylo ad if that's need ed etc.

Camel 2 .8 : Whether the unit o f wo rk sho uld b e shared .

See the same o p tio n o n

Sp litter

fo r mo re d etails.

8.12. Composed Message Processor

Co m po se d Me ssage Pro ce sso r

Processor Pattern” , allows you to process a composite message by splitting it up, routing

the sub-messages to appropriate destinations, and then re-aggregating the responses back into a single message.

Fig u re 8.11. Co mp o sed Messag e Pro cesso r Pat t ern

282

CHAPT ER 8 . MESSAG E RO UT ING

Java DSL e xam ple

The following example checks that a multipart order can be filled, where each part of the order requires a check to be made at a different 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")

.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");

XML DSL e xam ple

The preceding route can also be written in XML DSL, as follows:

<route>

<split>

<when>

</when>

283

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

</otherwise>

</choice>

</split>

</route>

<route>

<simple>header.orderId</simple>

</correlationExpression>

</aggregate>

</route>

Pro ce ssing st e ps

Processing starts by splitting the order, using a Splitter . The Splitter then sends individual

O rd erItems to a

Content Based Router

, which routes messages based on the item type.

Widget items get sent for checking in the wi d g etInvento ry bean and gadget items get sent to the g ad g etInvento ry bean. Once these O rd erItems have been validated by the

appropriate bean, they are sent on to the Aggregator which collects and re-assembles the

validated O rd erItems into an order again.

Each received order has a header containing an order ID. We make use of the order ID during the aggregation step: the . head er("o rd erId ") qualifier on the ag g reg ate() DSL command instructs the aggregator to use the header with the key, o rd erId , as the correlation expression.

For full details, check the example source here:

8.13. Scat t er-Gat her

Scat t e r-Gat he r

The scatter-gather pattern, as shown in Figure 8.12, “ Scatter-Gather Pattern” , enables you to

route messages to a number of dynamically specified recipients and re-aggregate the responses back into a single message.

Fig u re 8.12. Scat t er- G at h er Pat t ern

284

CHAPT ER 8 . MESSAG E RO UT ING

Dynam ic scat t e r-gat he r e xam ple

The following example outlines an application that gets the best quote for beer from several

different vendors. The examples uses a dynamic Recipient List to request a quote from all

vendors and an

Aggregator to pick the best quote out of all the responses. The routes for

this application are defined as follows:

<route>

<header>listOfVendors</header>

</recipientList>

</route>

<route>

<header>quoteRequestId</header>

</correlationExpression>

</aggregate>

</route>

</camelContext>

In the first route, the Recipient List looks at the l i stO fVend o rs header to obtain the list of

recipients. Hence, the client that sends messages to this application needs to add a

l i stO fVend o rs header to the message.

Example 8.1, “ Messaging Client Sample”

shows some sample code from a messaging client that adds the relevant header data to outgoing messages.

Examp le 8.1. Messag in g Clien t Samp le

285

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

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);

286

The message would be distributed to the following endpoints: bean: vend o r1,

bean: vend o r2, and bean: vend o r3. These beans are all implemented by the following class: 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);

}

The bean instances, vend o r1, vend o r2, and vend o r3, are instantiated using Spring XML syntax, as follows:

<bean id="aggregatorStrategy" class="org.apache.camel.spring.processor.scattergather.LowestQuoteAggr

egationStrategy"/>

<constructor-arg>

</constructor-arg>

</bean>

<constructor-arg>

</constructor-arg>

</bean>

CHAPT ER 8 . MESSAG E RO UT ING

<constructor-arg>

</constructor-arg>

</bean>

Each bean is initialized with a different price for beer (passed to the constructor argument).

When a message is sent to each bean endpoint, it arrives at the MyVend o r. g etQ uo te method. This method does a simple check to see 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 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 find out which one was

the best (that is, the lowest). For this, we use an Aggregator

with a custom aggregation strategy. The

Aggregator needs to identify which messages are relevant to the current quote,

which is done by correlating messages based on the value of the q uo teR eq uestId header

(passed to the co rrel ati o nExpressi o n). As shown in Example 8.1, “ Messaging Client

Sample” , the correlation ID is set to q uo teR eq uest-1 (the correlation ID should be

unique). To pick the lowest quote out of the set, you can use a custom aggregation strategy like the following: 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;

}

St at ic scat t e r-gat he r e xam ple

You can specify the recipients explicitly in the scatter-gather application by employing a

static Recipient List . The following example shows the routes you would use to implement a

static scatter-gather scenario: 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");

287

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

from("seda:quoteAggregator")

.aggregate(header("quoteRequestId"), new

LowestQuoteAggregationStrategy()).to("mock:result")

8.14 . Loop

Lo o p

The loop pattern enables you to process a message multiple times. It is used mainly for testing.

Def au lt mo d e

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 pro pe rt ie s

On each loop iteration, two exchange properties are set, which can optionally be read by any processors included in the loop.

Propert y

C amel Lo o pSi ze

C amel Lo o pInd ex

Descript ion

Ap ache Camel 2.0 : To tal numb er o f lo o p s

Ap ache Camel 2.0 : Ind ex o f the current iteratio n (0 b ased )

Java DSL e xam ple s

The following examples show how to take a request from the d i rect: x endpoint and then send the message repeatedly to mo ck: resul t. The number of loop iterations is specified either as an argument to l o o p() or by evaluating an expression at run time, where the expression must evaluate to an i nt (or else a R unti meC amel Excepti o n is thrown).

The following example passes the loop count as a constant: from("direct:a").loop(8).to("mock:result");

The following example evaluates a simple expression to determine the loop count: from("direct:b").loop(header("loop")).to("mock:result");

288

CHAPT ER 8 . MESSAG E RO UT ING

The following example evaluates an XPath expression to determine the loop count: from("direct:c").loop().xpath("/hello/@ times").to("mock:result");

XML co nfigurat io n e xam ple

You can configure the same routes in Spring XML.

The following example passes the loop count as a constant:

<route>

<loop>

</loop>

</route>

The following example evaluates a simple expression to determine the loop count:

<route>

<loop>

</loop>

</route>

Using co py m o de

Now suppose we send a message to d i rect: start endpoint containing the letter A. The output of processing this route will be that, each mo ck: l o o p 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 mo ck: l o o p will receive AB, ABB, ABBB messages.

from("direct:start")

// by default loop will keep using the same exchange so on the

289

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

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>

Opt io ns

The l o o p DSL command supports the following options:

Name co py

Default Value fal se

Descript ion

Camel 2 .8 : Whether o r no t co p y mo d e is used . If

fal se

then the same

Exchang e is b eing used thro ug ho ut the lo o p ing . So the result fro m the p revio us iteratio n will b e visible fo r the next iteratio n. Instead yo u can enab le co p y mo d e, and then each iteratio n is

restarting with a fresh co p y o f the inp ut

Exchang e

8.15. Sampling

Sam pling T hro t t le r

290

A sampling throttler allows you to extract a sample of exchanges from the traffic through a route. It is configured with a sampling period during which only a single exchange is allowed to pass through. All other exchanges will be stopped.

CHAPT ER 8 . MESSAG E RO UT ING

By default, the sample period is 1 second.

Java DSL e xam ple

Use the sampl e() DSL command to invoke the sampler as follows:

// Sample with default sampling period (1 second) from("direct:sample")

.sample()

.to("mock:result");

// Sample with explicitly specified sample period from("direct:sample-configured")

.sample(1, TimeUnit.SECONDS)

.to("mock:result");

// Alternative syntax for specifying sampling period 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");

Spring XML e xam ple

In Spring XML, use the sample element to invoke the sampler, where you have the option of specifying the sampling period using the sampl eP eri o d and uni ts attributes:

<route>

</sample>

</route>

<route>

</sample>

</route>

<route>

</sample>

</route>

291

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Opt io ns

The sampl e DSL command supports the following options:

Name messag eFreq uency sampl eP eri o d uni ts

Default Value

SEC O ND

Descript ion

Samp les the messag e every

N'th messag e. Yo u can o nly use either freq uency o r p erio d .

Samp les the messag e every

N'th p erio d . Yo u can o nly use either freq uency o r p erio d .

Time unit as an enum o f

java. uti l . co ncurrent

. T i meUni t

fro m the JDK.

8.16. Dynamic Rout er

Dynam ic Ro ut e r

The Dynamic Router pattern, as shown in

Figure 8.13, “ Dynamic Router Pattern” , enables

you to route a message consecutively through a series of processing steps, where the sequence of steps is not known at design time. The list of endpoints through which the message should pass is calculated dynamically at run time. Each time the message returns from an endpoint, the dynamic router calls back on a bean to discover the next endpoint in the route.

Fig u re 8.13. Dyn amic Ro u t er Pat t ern

292

CHAPT ER 8 . MESSAG E RO UT ING

In Camel 2.5 we introduced a d ynami cR o uter in the DSL, which is like a dynamic Routing

Slip that evaluates the slip on-the-fly.

Beware

You must ensure the expression used for the d ynami cR o uter (such as a bean), returns nul l to indicate the end. Otherwise, the d ynami cR o uter will continue in an endless loop.

Dynam ic Ro ut e r in Cam e l 2 .5 o nwards

From Camel 2.5, the Dynamic Router

updates the exchange property,

Exchang e. SLIP _END P O INT , with the current endpoint as it advances through the slip.

This enables you to find out how far the exchange has progressed through the slip. (It's a slip because the

Dynamic Router

implementation is based on Routing Slip ).

Java DSL

In Java DSL you can use the d ynami cR o uter as follows: 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-fly, which could be implemented as follows:

// Java

/**

* Use this method to compute dynamic where we should route next.

* @ param body the message body

* @ 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";

}

293

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

// no more so return null

return null;

}

No t e

The preceding example is not thread safe. You would have to store the state on the

Exchang e to ensure thread safety.

Spring XML

The same example in Spring XML would be:

<route>

</dynamicRouter>

</route>

<route>

<transform><constant>Bye World</constant></transform>

</route>

</camelContext>

Opt io ns

The d ynami cR o uter DSL command supports the following options:

Name uri D el i mi ter

Default Value

Descript ion

Delimiter used if the

Exp ressio n returned multip le

end p o ints.

294

i g no reInval i d End po i nts fal se

CHAPT ER 8 . MESSAG E RO UT ING

If an end p o int uri co uld no t b e reso lved , sho uld it b e ig no red . O therwise Camel will thro wn an excep tio n stating the end p o int uri is no t valid .

@Dynam icRo ut e r anno t at io n

You can also use the @ D ynami cR o uter annotation. For example:

// Java 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.

}

The ro ute method is invoked repeatedly as the message progresses through the slip. The idea is to return the endpoint URI of the next destination. Return nul l 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.

295

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 9. MESSAGE TRANSFORMATION

Ab st ract

The message transformation patterns describe how to modify the contents of messages for various purposes.

9.1. Cont ent Enricher

Ove rvie w

The content enricher pattern describes a scenario where the message destination requires more data than is present in the original message. In this case, you would use a content enricher to pull in the extra data from an external resource.

Fig u re 9 .1. Co n t en t En rich er Pat t ern

Mo de ls o f co nt e nt e nrichm e nt

Apache Camel supports two kinds of content enricher, as follows:

enri ch()—obtains additional data from the resource by sending a copy of the current exchange to a producer endpoint and then using the data from the resulting reply (the exchange created by the enricher is always an InOut exchange).

296

po l l Enri ch()—obtains the additional data by polling a consumer endpoint for data.

Effectively, the consumer endpoint from the main route and the consumer endpoint in

po l l Enri ch() are coupled, such that exchanges incoming on the main route trigger a poll of the po l l Enri ch() endpoint.

Co nt e nt e nrichm e nt using e nrich()

AggregationStrategy aggregationStrategy = ...

CHAPT ER 9 . MESSAG E T RANSFO RMAT IO N

from("direct:start")

.enrich("direct:resource", aggregationStrategy)

.to("direct:result"); from("direct:resource")

...

The content enricher (enri ch) retrieves additional data from a resource endpoint in order to enrich an incoming message (contained in the orginal exchange). An aggregation strategy combines the original exchange and the resource exchange. The first parameter of the

Ag g reg ati o nStrateg y. ag g reg ate(Exchang e, Exchang e) method corresponds to the the original exchange, and the second parameter corresponds to the resource exchange.

The results from the resource endpoint are stored in the resource exchange's Out message.

Here is a sample template for implementing your own aggregation strategy class: 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 have any exchange pattern. The resource exchange created by the enricher is always an InOut exchange.

Spring XML e nrich e xam ple

The preceding example can also be implemented in Spring XML:

<route>

</route>

<route>

...

297

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

</route>

</camelContext>

De fault aggre gat io n st rat e gy

The aggregation strategy is optional. If you do not provide it, Apache Camel will use the body obtained from the resource by default. For example: from("direct:start")

.enrich("direct:resource")

.to("direct:result");

In the preceding route, the message sent to the d i rect: resul t endpoint contains the output from the d i rect: reso urce, because this example does not use any custom aggregation.

In XML DSL, just omit the strateg yR ef attribute, as follows:

<route>

</route>

Enrich Opt io ns

The enri ch DSL command supports the following options:

Name uri ref

Default Value Descript ion

The end p o int uri fo r the external servie to enrich fro m. Yo u must use either

uri

o r

ref

Refers to the end p o int fo r the external servie to enrich fro m. Yo u must use either

uri

o r

ref

298

strateg yR ef ag g reg ateO nExcepti o n

CHAPT ER 9 . MESSAG E T RANSFO RMAT IO N

Refers to an

Ag g reg atio nStrateg y to b e used to merg e the rep ly fro m the external service, into a sing le o utg o ing messag e.

By d efault Camel will use the rep ly fro m the external service as o utg o ing messag e.

Refers to the Ag g reg ate metho d . The ag g reg ateO nExcep tio n enab les yo u to d eal with excep tio ns. Fo r examp le, yo u can sup p ress the excep tio n o r set a custo m messag e.

Co nt e nt e nrich using po llEnrich

The po l l Enri ch command treats the resource endpoint as a consumer. Instead of sending an exchange to the resource endpoint, it polls the endpoint. By default, the poll returns immediately, if there is no exchange available from the resource endpoint. For example, the following route reads a file whose name is extracted from the header of an incoming JMS message: from("activemq:queue:order")

.pollEnrich("file://order/data/additional?fileName=orderId")

.to("bean:processOrder");

And if you want to wait at most 20 seconds for the file to be ready, you can use a timeout as follows: from("activemq:queue:order")

.pollEnrich("file://order/data/additional?fileName=orderId", 20000)

// timeout is in milliseconds

.to("bean:processOrder");

You can also specify an aggregation strategy for po l l Enri ch, as follows:

.pollEnrich("file://order/data/additional?fileName=orderId", 20000, aggregationStrategy)

No t e

The resource exchange passed to the aggregation strategy's ag g reg ate() method might be nul l , if the poll times out before an exchange is received.

299

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Dat a f ro m cu rren t Exch an g e n o t u sed

po l l Enri ch does not access any data from the current Exchange, so that, when polling, it cannot use any of the existing headers you may have set on the

Exchange. For example, you cannot set a filename in the Exchang e. FILE_NAME header and use po l l Enri ch to consume only that file. For that, you must set the filename in the endpoint URI.

Po lling m e t ho ds use d by po llEnrich()

In general, the po l l Enri ch() enricher polls the consumer endpoint using one of the following polling methods:

recei veNo Wai t() (used by default)

recei ve() recei ve(l o ng ti meo ut)

The po l l Enri ch() command's timeout argument (specified in milliseconds) determines which method gets called, as follows:

Timeout is 0 or not specified, recei veNo Wai t is called.

Timeout is negative, recei ve is called.

Otherwise, recei ve(ti meo ut) is called.

po llEnrich e xam ple

In this example we enrich the message by loading the content from the file named inbox/data.txt.

from("direct:start")

.pollEnrich("file:inbox?fileName=data.txt")

.to("direct:result");

And in XML DSL you do:

<route>

</route>

300

CHAPT ER 9 . MESSAG E T RANSFO RMAT IO N

If there is no file then the message is empty. We can use a timeout to either wait (potential forever) until a file exists, or use a timeout to wait a period. For example to wait up til 5 seconds you can do:

<route>

</route>

Po llEnrich Opt io ns

The po l l Enri ch DSL command supports the following options:

Name uri ref strateg yR ef ti meo ut

Default Value

Descript ion

The end p o int uri fo r the external servie to enrich fro m. Yo u must use either

uri

o r

ref

Refers to the end p o int fo r the external servie to enrich fro m. Yo u must use either

uri

o r

ref

Refers to an

Ag g reg atio nStrateg y to b e used to merg e the rep ly fro m the external service, into a sing le o utg o ing messag e.

By d efault Camel will use the rep ly fro m the external service as o utg o ing messag e.

Timeo ut in millis to use when p o lling fro m the external service. See b elo w fo r imp o rtant d etails ab o ut the timeo ut.

9.2. Cont ent Filt er

Ove rvie w

The content filter pattern describes a scenario where you need to filter out extraneous content from a message before delivering it to its intended recipient. For example, you might employ a content filter to strip out confidential information from a message.

301

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Fig u re 9 .2. Co n t en t Filt er Pat t ern

302

A common way to filter messages is to use an expression in the DSL, written in one of the supported scripting languages (for example, XSLT, XQuery or JoSQL).

Im ple m e nt ing a co nt e nt filt e r

A content filter is essentially an application of a message processing technique for a particular purpose. To implement a content filter, you can employ any of the following message processing techniques:

Message translator—see message translators

Processors—see Chapter 43, Implementing a Processor

Bean integration .

XML co nfigurat io n e xam ple

The following example shows how to configure the same route in XML:

<route>

</route>

</camelContext>

Using an XPat h filt e r

You can also use XPath to filter out part of the message you are interested in:

<route>

</setBody>

</route>

CHAPT ER 9 . MESSAG E T RANSFO RMAT IO N

9.3. Normaliz er

Ove rvie w

The normalizer pattern is used to process messages that are semantically equivalent, but arrive in different formats. The normalizer transforms the incoming messages into a common format.

In Apache Camel, you can implement the normalizer pattern by combining a content-based router , which detects the incoming message's format, with a collection of different message

translators , which transform the different incoming formats into a common format.

Fig u re 9 .3. No rmaliz er Pat t ern

Java DSL e xam ple

This example shows a Message Normalizer that converts two types of XML messages into a common format. Messages in this common format are then filtered.

Usin g t h e Flu en t Bu ild ers

// 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

// Java public class MyNormalizer {

public void employeeToPerson(Exchange exchange,

303

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

@ 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 "& lt;person name=\"" + name + "\"/>";

}

XML co nfigurat io n e xam ple

The same example in the XML DSL

<route>

<when>

<xpath>/employee</xpath>

</when>

<when>

<xpath>/customer</xpath>

</when>

</choice>

</route>

</camelContext>

9.4 . Claim Check

Claim Che ck

The claim check pattern, shown in

Figure 9.4, “ Claim Check Pattern”

, 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 file 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.

304

Fig u re 9 .4 . Claim Ch eck Pat t ern

CHAPT ER 9 . MESSAG E T RANSFO RMAT IO N

Java DSL e xam ple

The following example shows how to replace a message body with a claim check and restore the body at a later step.

from("direct:start").to("bean:checkLuggage", "mock:testCheckpoint",

"bean:dataEnricher", "mock:result");

The next step in the pipeline is the mo ck: testC heckpo i nt endpoint, which checks that the message body has been removed, the claim check added, and so on.

XML DSL e xam ple

The preceding example can also be written in XML, as follows:

<route>

</pipeline>

</route>

che ckLuggage be an

The message is first sent to the checkLug g ag e bean which is implemented as follows: 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

305

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

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 are using a HashMap to store the message body; in a real application you would use a database or the file system. The claim check is added as a message header for later use and, finally, we remove the body from the message and pass it down the pipeline.

t e st Che ckpo int e ndpo int

The example route is just a

Pipeline . In a real application, you would substitute some other

steps for the mo ck: testC heckpo i nt endpoint.

dat aEnriche r be an

To add the message body back into the message, we use the d ataEnri cher bean, which is implemented as follows: 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 recovered data back into the message body. The bean then deletes the message data from the data store and removes the cl ai mC heck header from the message.

9.5. Sort

So rt

The sort pattern is used to sort the contents of a message body, assuming that the message body contains a list of items that can be sorted.

306

CHAPT ER 9 . MESSAG E T RANSFO RMAT IO N

By default, the contents of the message are sorted using a default comparator that handles numeric values or strings. You can provide your own comparator and you can specify an expression that returns the list to be sorted (the expression must be convertible to

java. uti l . Li st).

Java DSL e xam ple

The following example generates the list of items to sort by tokenizing on the line break character: from("file://inbox").sort(body().tokenize("\n")).to("bean:MyServiceBea n.processLine");

You can pass in your own comparator as the second argument to so rt(): from("file://inbox").sort(body().tokenize("\n"), new

MyReverseComparator()).to("bean:MyServiceBean.processLine");

XML co nfigurat io n e xam ple

You can configure the same routes in Spring XML.

The following example generates the list of items to sort by tokenizing on the line break character:

<route>

<sort>

</sort>

</route>

And to use a custom comparator, you can reference it as a Spring bean:

<route>

</sort>

</route>

Besides <si mpl e>, you can supply an expression using any language you like, so long as it returns a list.

Opt io ns

307

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Opt io ns

The so rt DSL command supports the following options:

Name co mparato rR ef

Default Value Descript ion

Refers to a custo m

java. uti l . C o mparato r

to use fo r so rting the messag e b o d y. Camel will b y d efault use a co mp arato r which d o es a A..Z so rting .

9.6. Validat e

Ove rvie w

The validate pattern provides a convenient syntax to check whether the content of a message is valid. The validate DSL command takes a predicate expression as its sole argument: if the predicate evaluates to true, the route continues processing normally; if the predicate evaluates to fal se, a P red i cateVal i d ati o nExcepti o n is thrown.

Java DSL e xam ple

The following route validates the body of the current message using a regular expression: from("jms:queue:incoming")

.validate(body(String.class).regex("^\\w{10}\\,\\d{2}\\,\\w{24}$"))

.to("bean:MyServiceBean.processLine");

You can also validate a message header—for example: from("jms:queue:incoming")

.validate(header("bar").isGreaterThan(100))

.to("bean:MyServiceBean.processLine");

And you can use validate with the simple expression language: from("jms:queue:incoming")

.validate(simple("${in.header.bar} == 100"))

.to("bean:MyServiceBean.processLine");

XML DSL e xam ple

To use validate in the XML DSL, the recommended approach is to use the simple expression language:

308

CHAPT ER 9 . MESSAG E T RANSFO RMAT IO N

<route>

<simple>${body} regex ^\\w{10}\\,\\d{2}\\,\\w{24}$</simple>

</validate>

</route>

You can also validate a message header—for example:

<route>

<simple>${in.header.bar} == 100</simple>

</validate>

</route>

309

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 10. MESSAGING ENDPOINTS

Ab st ract

The messaging endpoint patterns describe various features and qualities of service that can be configured on an endpoint.

10.1. Messaging Mapper

Ove rvie w

The messaging mapper pattern describes how to map domain objects to and from a canonical message format, where the message format is chosen to be as platform neutral as possible.

The chosen message format should be suitable for transmission through a message bus

, where the message bus is the backbone for integrating a variety of different systems, some of which might not be object-oriented.

Many different approaches are possible, but not all of them fulfill the requirements of a messaging mapper. For example, an obvious way to transmit an object is to use object

serialization, which enables you to write an object to a data stream using an unambiguous encoding (supported natively in Java). However, this is not a suitable approach to use for the messaging mapper pattern, however, because the serialization format is understood only by Java applications. Java object serialization creates an impedance mismatch between the original application and the other applications in the messaging system.

The requirements for a messaging mapper can be summarized as follows:

The canonical message format used to transmit domain objects should be suitable for consumption by non-object oriented applications.

The mapper code should be implemented separately from both the domain object code and the messaging infrastructure. Apache Camel helps fulfill this requirement by providing hooks that can be used to insert mapper code into a route.

The mapper might need to find an effective way of dealing with certain object-oriented concepts such as inheritance, object references, and object trees. The complexity of these issues varies from application to application, but the aim of the mapper implementation must always be to create messages that can be processed effectively by non-objectoriented applications.

Finding o bje ct s t o m ap

You can use one of the following mechanisms to find the objects to map:

Find a registered bean. — For singleton objects and small numbers of objects, you could use the C amel C o ntext registry to store references to beans. For example, if a bean instance is instantiated using Spring XML, it is automatically entered into the registry, where the bean is identified by the value of its i d attribute.

310

CHAPT ER 1 0 . MESSAG ING ENDPO INT S

Select objects using the JoSQL language. — If all of the objects you want to access are already instantiated at runtime, you could use the JoSQL language to locate a specific object (or objects). For example, if you have a class,

o rg . apache. camel . bui l d er. sq l . P erso n, with a name bean property and the incoming message has a UserName header, you could select the object whose name property equals the value of the UserName header using the following code: import static org.apache.camel.builder.sql.SqlBuilder.sql; import org.apache.camel.Expression;

...

Expression expression = sql( "SELECT * FROM org.apache.camel.builder.sql.Person where name = :UserName" );

Object value = expression.evaluate(exchange);

Where the syntax, : HeaderName, is used to substitute the value of a header in a JoSQL expression.

Dynamic — For a more scalable solution, it might be necessary to read object data from a database. In some cases, the existing object-oriented application might already provide a finder object that can load objects from the database. In other cases, you might have to write some custom code to extract objects from a database, and in these cases the JDBC component and the SQL component might be useful.

10.2. Event Driven Consumer

Ove rvie w

The event-driven consumer pattern, shown in Figure 10.1, “ Event Driven Consumer Pattern” ,

is a pattern for implementing the consumer endpoint in a Apache Camel component, and is only relevant to programmers who need to develop a custom component in Apache Camel.

Existing components already have a consumer implementation pattern hard-wired into them.

Fig u re 10.1. Even t Driven Co n su mer Pat t ern

Consumers that conform to this pattern provide an event method that is automatically called by the messaging channel or transport layer whenever an incoming message is received.

One of the characteristics of the event-driven consumer pattern is that the consumer endpoint itself does not provide any threads to process the incoming messages. Instead, the underlying transport or messaging channel implicitly provides a processor thread when it invokes the exposed event method (which blocks for the duration of the message processing).

311

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

For more details about this implementation pattern, see Section 46.1.3, “ Consumer Patterns and Threading” and Chapter 49, Consumer Interface .

10.3. Polling Consumer

Ove rvie w

The polling consumer pattern, shown in Figure 10.2, “ Polling Consumer Pattern” , is a pattern

for implementing the consumer endpoint in a Apache Camel component, so it is only relevant to programmers who need to develop a custom component in Apache Camel. Existing components already have a consumer implementation pattern hard-wired into them.

Consumers that conform to this pattern expose polling methods, recei ve(),

recei ve(l o ng ti meo ut), and recei veNo Wai t() that return a new exchange object, if one is available from the monitored resource. A polling consumer implementation must provide its own thread pool to perform the polling.

For more details about this implementation pattern, see Section 46.1.3, “ Consumer Patterns and Threading” , Chapter 49, Consumer Interface , and Section 45.2, “ Using the Consumer

Template” .

Fig u re 10.2. Po llin g Co n su mer Pat t ern

312

Sche dule d po ll co nsum e r

Many of the Apache Camel consumer endpoints employ a scheduled poll pattern to receive messages at the start of a route. That is, the endpoint appears to implement an event-driven consumer interface, but internally a scheduled poll is used to monitor a resource that provides the incoming messages for the endpoint.

See

Section 49.2, “ Implementing the Consumer Interface”

for details of how to implement this pattern.

Quart z co m po ne nt

You can use the quartz component to provide scheduled delivery of messages using the

Quartz enterprise scheduler. See chapter "Quartz" in "Apache Camel Component Reference" and Quartz Component for details.

CHAPT ER 1 0 . MESSAG ING ENDPO INT S

10.4 . Compet ing Consumers

Ove rvie w

The competing consumers pattern, shown in

Figure 10.3, “ Competing Consumers Pattern”

, enables multiple consumers to pull messages from the same queue, with the guarantee that

each message is consumed once only. This pattern can be used to replace serial message processing with concurrent message processing (bringing a corresponding reduction in response latency).

Fig u re 10.3. Co mp et in g Co n su mers Pat t ern

The following components demonstrate the competing consumers pattern:

the section called “ JMS based competing consumers” the section called “ SEDA based competing consumers”

JMS base d co m pe t ing co nsum e rs

A regular JMS queue implicitly guarantees that each message can only be consumed at once. Hence, a JMS queue automatically supports the competing consumers pattern. For example, you could define three competing consumers that pull messages from the JMS queue, Hi g hVo l umeQ , as follows:

313

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

from("jms:HighVolumeQ").to("cxf:bean:replica01"); from("jms:HighVolumeQ").to("cxf:bean:replica02"); from("jms:HighVolumeQ").to("cxf:bean:replica03");

Where the CXF (Web services) endpoints, repl i ca0 1, repl i ca0 2, and repl i ca0 3, process messages from the Hi g hVo l umeQ queue in parallel.

Alternatively, you can set the JMS query option, co ncurrentC o nsumers, to create a thread pool of competing consumers. For example, the following route creates a pool of three competing threads that pick messages from the specified queue: from("jms:HighVolumeQ?

concurrentConsumers=3").to("cxf:bean:replica01");

And the co ncurrentC o nsumers option can also be specified in XML DSL, as follows:

<route>

</route>

No t e

JMS topics cannot support the competing consumers pattern. By definition, a JMS topic is intended to send multiple copies of the same message to different consumers. Therefore, it is not compatible with the competing consumers pattern.

SEDA base d co m pe t ing co nsum e rs

The purpose of the SEDA component is to simplify concurrent processing by breaking the computation into stages. A SEDA endpoint essentially encapsulates an in-memory blocking queue (implemented by java. uti l . co ncurrent. Bl o cki ng Q ueue). Therefore, you can use a SEDA endpoint to break a route into stages, where each stage might use multiple threads. For example, you can define a SEDA route consisting of two stages, as follows:

// Stage 1: Read messages from file system.

from("file://var/messages").to("seda:fanout");

// Stage 2: Perform concurrent processing (3 threads).

from("seda:fanout").to("cxf:bean:replica01"); from("seda:fanout").to("cxf:bean:replica02"); from("seda:fanout").to("cxf:bean:replica03");

Where the first stage contains a single thread that consumes message from a file endpoint,

fi l e: //var/messag es, and routes them to a SEDA endpoint, sed a: fano ut. The second stage contains three threads: a thread that routes exchanges to cxf: bean: repl i ca0 1, a thread that routes exchanges to cxf: bean: repl i ca0 2, and a thread that routes

314

CHAPT ER 1 0 . MESSAG ING ENDPO INT S

exchanges to cxf: bean: repl i ca0 3. These three threads compete to take exchange instances from the SEDA endpoint, which is implemented using a blocking queue. Because the blocking queue uses locking to prevent more than one thread from accessing the queue at a time, you are guaranteed that each exchange instance can only be consumed once.

For a discussion of the differences between a SEDA endpoint and a thread pool created by

thread (), see chapter "SEDA" in "Apache Camel Component Reference" .

10.5. Message Dispat cher

Ove rvie w

The message dispatcher pattern, shown in

Figure 10.4, “ Message Dispatcher Pattern”

, is used to consume messages from a channel and then distribute them locally to performers, which are responsible for processing the messages. In a Apache Camel application, performers are usually represented by in-process endpoints, which are used to transfer messages to another section of the route.

Fig u re 10.4 . Messag e Disp at ch er Pat t ern

You can implement the message dispatcher pattern in Apache Camel using one of the following approaches:

the section called “ JMS selectors”

the section called “ JMS selectors in ActiveMQ”

315

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

the section called “ Content-based router”

JMS se le ct o rs

If your application consumes messages from a JMS queue, you can implement the message dispatcher pattern using JMS selectors. A JMS selector is a predicate expression involving

JMS headers and JMS properties. If the selector evaluates to true, the JMS message is allowed to reach the consumer, and if the selector evaluates to fal se, the JMS message is blocked. In many respects, a JMS selector is like a

filter processor , but it has the additional

advantage that the filtering is implemented inside the JMS provider. This means that a JMS selector can block messages before they are transmitted to the Apache Camel application.

This provides a significant efficiency advantage.

In Apache Camel, you can define a JMS selector on a consumer endpoint by setting the

sel ecto r query option on a JMS endpoint URI. For example: from("jms:dispatcher?

selector=CountryCode='US'").to("cxf:bean:replica01"); from("jms:dispatcher?

selector=CountryCode='IE'").to("cxf:bean:replica02"); from("jms:dispatcher?

selector=CountryCode='DE'").to("cxf:bean:replica03");

Where the predicates that appear in a selector string are based on a subset of the SQL92 conditional expression syntax (for full details, see the JMS specification ). The identifiers appearing in a selector string can refer either to JMS headers or to JMS properties. For example, in the preceding routes, the sender sets a JMS property called C o untryC o d e.

If you want to add a JMS property to a message from within your Apache Camel application, you can do so by setting a message header (either on In message or on Out messages).

When reading or writing to JMS endpoints, Apache Camel maps JMS headers and JMS properties to, and from, its native message headers.

Technically, the selector strings must be URL encoded according to the appl i cati o n/x-

www-fo rm-url enco d ed MIME format (see the

HTML specification ). In practice, the

& (ampersand) character might cause difficulties because it is used to delimit each query option in the URI. For more complex selector strings that might need to embed the & character, you can encode the strings using the java. net. UR LEnco d er utility class. For example: from("jms:dispatcher?selector=" + java.net.URLEncoder.encode("CountryCode='US'","UTF-8")).

to("cxf:bean:replica01");

Where the UTF-8 encoding must be used.

JMS se le ct o rs in Act ive MQ

You can also define JMS selectors on ActiveMQ endpoints. For example:

316

CHAPT ER 1 0 . MESSAG ING ENDPO INT S

from("activemq:dispatcher?

selector=CountryCode='US'").to("cxf:bean:replica01"); from("activemq:dispatcher?

selector=CountryCode='IE'").to("cxf:bean:replica02"); from("activemq:dispatcher?

selector=CountryCode='DE'").to("cxf:bean:replica03");

For more details, see ActiveMQ: JMS Selectors and ActiveMQ Message Properties .

Co nt e nt -base d ro ut e r

The essential difference between the content-based router pattern and the message dispatcher pattern is that a content-based router dispatches messages to physically separate destinations (remote endpoints), and a message dispatcher dispatches messages locally, within the same process space. In Apache Camel, the distinction between these two patterns is determined by the target endpoint. The same router logic is used to implement both a content-based router and a message dispatcher. When the target endpoint is remote, the route defines a content-based router. When the target endpoint is in-process, the route defines a message dispatcher.

For details and examples of how to use the content-based router pattern see Section 8.1,

“ Content-Based Router” .

10.6. Select ive Consumer

Ove rvie w

The selective consumer pattern, shown in Figure 10.5, “ Selective Consumer Pattern”

, describes a consumer that applies a filter to incoming messages, so that only messages meeting specific selection criteria are processed.

Fig u re 10.5. Select ive Co n su mer Pat t ern

You can implement the selective consumer pattern in Apache Camel using one of the following approaches:

the section called “ JMS selector” the section called “ JMS selector in ActiveMQ”

317

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

the section called “ Message filter”

JMS se le ct o r

A JMS selector is a predicate expression involving JMS headers and JMS properties. If the selector evaluates to true, the JMS message is allowed to reach the consumer, and if the selector evaluates to fal se, the JMS message is blocked. For example, to consume messages from the queue, sel ecti ve, and select only those messages whose country code property is equal to US, you can use the following Java DSL route: from("jms:selective?selector=" + java.net.URLEncoder.encode("CountryCode='US'","UTF-8")).

to("cxf:bean:replica01");

Where the selector string, C o untryC o d e= ' US' , must be URL encoded (using UTF-8 characters) to avoid trouble with parsing the query options. This example presumes that the

JMS property, C o untryC o d e, is set by the sender. For more details about JMS selectors, see

the section called “ JMS selectors”

No t e

If a selector is applied to a JMS queue, messages that are not selected remain on the queue and are potentially available to other consumers attached to the same queue.

JMS se le ct o r in Act ive MQ

You can also define JMS selectors on ActiveMQ endpoints. For example: from("acivemq:selective?selector=" + java.net.URLEncoder.encode("CountryCode='US'","UTF-8")).

to("cxf:bean:replica01");

For more details, see ActiveMQ: JMS Selectors and ActiveMQ Message Properties .

Me ssage filt e r

If it is not possible to set a selector on the consumer endpoint, you can insert a filter processor into your route instead. For example, you can define a selective consumer that processes only messages with a US country code using Java DSL, as follows: from("seda:a").filter(header("CountryCode").isEqualTo("US")).process(m yProcessor);

318

The same route can be defined using XML configuration, as follows:

<route>

<xpath>$CountryCode = 'US'</xpath>

</filter>

</route>

</camelContext>

CHAPT ER 1 0 . MESSAG ING ENDPO INT S

For more information about the Apache Camel filter processor, see Message Filter .

Warn in g

Be careful about using a message filter to select messages from a JMS queue.

When using a filter processor, blocked messages are simply discarded. Hence, if the messages are consumed from a queue (which allows each message to be consumed only once—see

Section 10.4, “ Competing Consumers” ), then blocked

messages are not processed at all. This might not be the behavior you want.

10.7. Durable Subscriber

Ove rvie w

A durable subscriber, as shown in Figure 10.6, “ Durable Subscriber Pattern”

, is a consumer

that wants to receive all of the messages sent over a particular publish-subscribe

channel, including messages sent while the consumer is disconnected from the messaging system.

This requires the messaging system to store messages for later replay to the disconnected consumer. There also has to be a mechanism for a consumer to indicate that it wants to establish a durable subscription. Generally, a publish-subscribe channel (or topic) can have both durable and non-durable subscribers, which behave as follows:

n o n - d u rab le su b scrib er—Can have two states: connected and disconnected. While a non-durable subscriber is connected to a topic, it receives all of the topic's messages in real time. However, a non-durable subscriber never receives messages sent to the topic while the subscriber is disconnected.

d u rab le su b scrib er—Can have two states: connected and inactive. The inactive state means that the durable subscriber is disconnected from the topic, but wants to receive the messages that arrive in the interim. When the durable subscriber reconnects to the topic, it receives a replay of all the messages sent while it was inactive.

Fig u re 10.6 . Du rab le Su b scrib er Pat t ern

319

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

320

JMS durable subscribe r

The JMS component implements the durable subscriber pattern. In order to set up a durable subscription on a JMS endpoint, you must specify a client ID, which identifies this particular connection, and a durable subscription name, which identifies the durable subscriber. For example, the following route sets up a durable subscription to the JMS topic, news, with a client ID of co nn0 1 and a durable subscription name of Jo hn. D o e: from("jms:topic:news?

clientId=conn01& durableSubscriptionName=John.Doe").

to("cxf:bean:newsprocessor");

You can also set up a durable subscription using the ActiveMQ endpoint: from("activemq:topic:news?

clientId=conn01& durableSubscriptionName=John.Doe").

to("cxf:bean:newsprocessor");

If you want to process the incoming messages concurrently, you can use a SEDA endpoint to fan out the route into multiple, parallel segments, as follows: from("jms:topic:news?

clientId=conn01& durableSubscriptionName=John.Doe").

to("seda:fanout"); from("seda:fanout").to("cxf:bean:newsproc01"); from("seda:fanout").to("cxf:bean:newsproc02"); from("seda:fanout").to("cxf:bean:newsproc03");

Where each message is processed only once, because the SEDA component supports the

competing consumers pattern.

CHAPT ER 1 0 . MESSAG ING ENDPO INT S

Alt e rnat ive e xam ple

Another alternative is to combine the

Message Dispatcher

Content-Based Router

with File component or JPA component components for durable subscribers then something like

SEDA component for non-durable.

Here is a simple example of creating durable subscribers to a chapter "JMS" in "Apache

Camel Component Reference" topic

Usin g t h e Flu en t Bu ild ers

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");

Usin g t h e Sp rin g XML Ext en sio n s

<route>

</route>

<route>

<from uri="activemq:topic:foo?

clientId=1& durableSubscriptionName=bar1"/>

</route>

<route>

<from uri="activemq:topic:foo?

clientId=2& durableSubscriptionName=bar2"/>

</route>

Here is another example of JMS durable subscribers, but this time using virtual topics

(recommended by AMQ over durable subscriptions)

Usin g t h e Flu en t Bu ild ers

from("direct:start").to("activemq:topic:VirtualTopic.foo");

from("activemq:queue:Consumer.1.VirtualTopic.foo").to("mock:result1")

;

from("activemq:queue:Consumer.2.VirtualTopic.foo").to("mock:result2")

;

321

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Usin g t h e Sp rin g XML Ext en sio n s

<route>

</route>

<route>

</route>

<route>

</route>

10.8. Idempot ent Consumer

Ove rvie w

The idempotent consumer pattern is used to filter out duplicate messages. For example, consider a scenario where the connection between a messaging system and a consumer endpoint is abruptly lost due to some fault in the system. If the messaging system was in the middle of transmitting a message, it might be unclear whether or not the consumer received the last message. To improve delivery reliability, the messaging system might decide to redeliver such messages as soon as the connection is re-established. Unfortunately, this entails the risk that the consumer might receive duplicate messages and, in some cases, the effect of duplicating a message may have undesirable consequences (such as debiting a sum of money twice from your account). In this scenario, an idempotent consumer could be used to weed out undesired duplicates from the message stream.

Camel provides the following Idempotent Consumer implementations:

Memo ryId empo tentR epo si to ry

File

HazelcastIdempotentRepository

JdbcMessageIdRepository

JpaMessageIdRepository

Ide m po t e nt co nsum e r wit h in-m e m o ry cache

In Apache Camel, the idempotent consumer pattern is implemented by the

i d empo tentC o nsumer() processor, which takes two arguments:

322

messag eId Expressi o n — An expression that returns a message ID string for the

CHAPT ER 1 0 . MESSAG ING ENDPO INT S

messag eId Expressi o n — An expression that returns a message ID string for the current message.

messag eId R epo si to ry — A reference to a message ID repository, which stores the IDs of all the messages received.

As each message comes in, the idempotent consumer processor looks up the current message ID in the repository to see if this message has been seen before. If yes, the message is discarded; if no, the message is allowed to pass and its ID is added to the repository.

The code shown in

Example 10.1, “ Filtering Duplicate Messages with an In-memory Cache”

uses the T ransacti o nID header to filter out duplicates.

Examp le 10.1. Filt erin g Du p licat e Messag es wit h an In - memo ry Cach e

import static org.apache.camel.processor.idempotent.MemoryMessageIdRepository.memo

ryMessageIdRepository;

...

RouteBuilder builder = new RouteBuilder() {

public void configure() {

from("seda:a")

.idempotentConsumer(

header("TransactionID"),

memoryMessageIdRepository(200)

).to("seda:b");

}

};

Where the call to memo ryMessag eId R epo si to ry(20 0 ) creates an in-memory cache that can hold up to 200 message IDs.

You can also define an idempotent consumer using XML configuration. For example, you can define the preceding route in XML, as follows:

<route>

<simple>header.TransactionID</simple>

</idempotentConsumer>

</route>

</camelContext>

<bean id="MsgIDRepos" class="org.apache.camel.processor.idempotent.MemoryMessageIdRepository

323

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

<constructor-arg type="int" value="200"/>

</bean>

Ide m po t e nt co nsum e r wit h JPA re po sit o ry

The in-memory cache suffers from the disadvantages of easily running out of memory and not working in a clustered environment. To overcome these disadvantages, you can use a

Java Persistent API (JPA) based repository instead. The JPA message ID repository uses an object-oriented database to store the message IDs. For example, you can define a route that uses a JPA repository for the idempotent consumer, as follows:

324

import org.springframework.orm.jpa.JpaTemplate; import org.apache.camel.spring.SpringRouteBuilder; import static org.apache.camel.processor.idempotent.jpa.JpaMessageIdRepository.jpaMe

ssageIdRepository;

...

RouteBuilder builder = new SpringRouteBuilder() {

public void configure() {

from("seda:a").idempotentConsumer(

header("TransactionID"),

jpaMessageIdRepository(bean(JpaTemplate.class),

"myProcessorName")

).to("seda:b");

}

};

The JPA message ID repository is initialized with two arguments:

JpaT empl ate instance—Provides the handle for the JPA database.

processor name—Identifies the current idempotent consumer processor.

The Spri ng R o uteBui l d er. bean() method is a shortcut that references a bean defined in the Spring XML file. The JpaT empl ate bean provides a handle to the underlying JPA database. See the JPA documentation for details of how to configure this bean.

For more details about setting up a JPA repository, see JPA Component documentation, the

Spring JPA documentation, and the sample code in the Camel JPA unit test .

Spring XML e xam ple

The following example uses the myMessag eId header to filter out duplicates:

<bean id="myRepo"

CHAPT ER 1 0 . MESSAG ING ENDPO INT S

class="org.apache.camel.processor.idempotent.MemoryIdempotentRepositor

y"/>

<route>

<header>messageId</header>

</idempotentConsumer>

</route>

</camelContext>

Ide m po t e nt co nsum e r wit h JDBC re po sit o ry

A JDBC repository is also supported for storing message IDs in the idempotent consumer pattern. The implementation of the JDBC repository is provided by the SQL component, so if you are using the Maven build system, add a dependency on the camel -sq l artifact.

You can use the Si ng l eC o nnecti o nD ataSo urce JDBC wrapper class from the Spring persistence API in order to instantiate the connection to a SQL database. For example, to instantiate a JDBC connection to a HyperSQL database instance, you could define the following JDBC data source:

<bean id="dataSource" class="org.springframework.jdbc.datasource.SingleConnectionDataSource"

</bean>

No t e

The preceding JDBC data source uses the HyperSQL mem protocol, which creates a memory-only database instance. This is a toy implementation of the HyperSQL database which is not actually persistent.

Using the preceding data source, you can define an idempotent consumer pattern that uses the JDBC message ID repository, as follows:

<bean id="messageIdRepository" class="org.apache.camel.processor.idempotent.jdbc.JdbcMessageIdReposit

ory">

<constructor-arg ref="dataSource" />

<constructor-arg value="myProcessorName" />

</bean>

325

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

326

<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>

Ho w t o handle duplicat e m e ssage s in t he ro ut e

Availab le as o f Camel 2.8

You can now set the ski pD upl i cate option to fal se 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.

from("direct:start")

// instruct idempotent consumer to not skip duplicates as we will filter then our self

.idempotentConsumer(header("messageId")).messageIdRepository(repo).ski

pDuplicate(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");

The sample example in XML DSL would be:

<bean id="myRepo" class="org.apache.camel.processor.idempotent.MemoryIdempotentRepositor

CHAPT ER 1 0 . MESSAG ING ENDPO INT S

y"/>

<route>

<header>messageId</header>

<!-- we will to handle duplicate messages using a filter

-->

<property>CamelDuplicateMessage</property>

<stop/>

</filter>

</idempotentConsumer>

</route>

</camelContext>

Ho w t o handle duplicat e m e ssage in a clust e re d e nviro nm e nt wit h a dat a grid

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 finds the nodes over multicast (which is default - configure 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");

You have to define 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 configuration . For additional information see

camel-hazelcast

See this Idempotent Repository tutorial , to learn more about how setup such an idempotent repository on two cluster nodes using Apache Karaf.

327

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Opt io ns

The Idempotent Consumer has the following options:

O pt ion eag er

Default true messag eId R epo si to ryR ef nul l ski pD upl i cate true

Descript ion

Camel 2 .0 : Eag er co ntro ls whether Camel ad d s the messag e to the rep o sito ry b efo re o r after the exchang e has b een p ro cessed . If enab led b efo re then Camel will b e ab le to d etect d up licate messag es even when messag es are currently in p ro g ress. By d isab ling

Camel will o nly d etect d up licates when a messag e has successfully b een p ro cessed .

A reference to a

Id empo tentR epo si to ry

to lo o kup in the reg istry.

This o p tio n is mand ato ry when using XML DSL.

Camel 2 .8 : Sets whether to skip d up licate messag es. If set to

fal se

then the messag e will b e co ntinued .

Ho wever the

Exchang e

has b een marked as a d up licate b y having the

Exchang e. D UP LIC AT E_M

ESSAG

exchang e p ro p erty set to a

Bo o l ean. T R UE

value.

10.9. T ransact ional Client

Ove rvie w

The transactional client pattern, shown in

Figure 10.7, “ Transactional Client Pattern”

, refers to messaging endpoints that can participate in a transaction. Apache Camel supports transactions using Spring transaction management .

Fig u re 10.7. T ran sact io n al Clien t Pat t ern

328

CHAPT ER 1 0 . MESSAG ING ENDPO INT S

T ransact io n o rie nt e d e ndpo int s

Not all Apache Camel endpoints support transactions. Those that do are called transaction

oriented endpoints (or TOEs). For example, both the JMS component and the ActiveMQ component support transactions.

To enable transactions on a component, you must perform the appropriate initialization before adding the component to the C amel C o ntext. This entails writing code to initialize your transactional components explicitly.

Re fe re nce s

The details of configuring transactions in Apache Camel are beyond the scope of this guide.

For full details of how to use transactions, see the Apache Camel Transaction Guide.

10.10. Messaging Gat eway

Ove rvie w

The messaging gateway pattern, shown in Figure 10.8, “ Messaging Gateway Pattern” ,

describes an approach to integrating with a messaging system, where the messaging system's API remains hidden from the programmer at the application level. One of the more common example is when you want to translate synchronous method calls into request/reply message exchanges, without the programmer being aware of this.

Fig u re 10.8. Messag in g G at eway Pat t ern

329

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

The following Apache Camel components provide this kind of integration with the messaging system: chapter "CXF" in "Apache Camel Component Reference" chapter "Bean" in "Apache Camel Component Reference"

10.11. Service Act ivat or

Ove rvie w

The service activator pattern, shown in

Figure 10.9, “ Service Activator Pattern”

, describes the scenario where a service's operations are invoked in response to an incoming request message. The service activator identifies which operation to call and extracts the data to use as the operation's parameters. Finally, the service activator invokes an operation using the data extracted from the message. The operation invocation can be either oneway (request only) or two-way (request/reply).

Fig u re 10.9 . Service Act ivat o r Pat t ern

In many respects, a service activator resembles a conventional remote procedure call (RPC), where operation invocations are encoded as messages. The main difference is that a service activator needs to be more flexible. An RPC framework standardizes the request and reply message encodings (for example, Web service operations are encoded as SOAP messages), whereas a service activator typically needs to improvise the mapping between the messaging system and the service's operations.

Be an int e grat io n

330

The main mechanism that Apache Camel provides to support the service activator pattern is

bean integration. Bean integration provides a general framework for mapping incoming messages to method invocations on Java objects. For example, the Java fluent DSL provides the processors bean() and beanR ef() that you can insert into a route to invoke methods on a registered Java bean. The detailed mapping of message data to Java method

CHAPT ER 1 0 . MESSAG ING ENDPO INT S

parameters is determined by the bean binding, which can be implemented by adding annotations to the bean class.

For example, consider the following route which calls the Java method,

BankBean. g etUserAccBal ance(), to service requests incoming on a JMS/ActiveMQ queue: from("activemq:BalanceQueries")

.setProperty("userid", xpath("/Account/BalanceQuery/UserID").stringResult())

.beanRef("bankBean", "getUserAccBalance")

.to("velocity:file:src/scripts/acc_balance.vm")

.to("activemq:BalanceResults");

The messages pulled from the ActiveMQ endpoint, acti vemq : Bal anceQ ueri es, have a simple XML format that provides the user ID of a bank account. For example:

<?xml version='1.0' encoding='UTF-8'?>

<UserID>James.Strachan</UserID>

</BalanceQuery>

</Account>

The first processor in the route, setP ro perty(), extracts the user ID from the In message and stores it in the useri d exchange property. This is preferable to storing it in a header, because the In headers are not available after invoking the bean.

The service activation step is performed by the beanR ef() processor, which binds the incoming message to the g etUserAccBal ance() method on the Java object identified by the bankBean bean ID. The following code shows a sample implementation of the

BankBean class: package tutorial;

i mpo rt o rg . apache. camel . l ang uag e. XP ath;

public class BankBean { public int getUserAccBalance(@ XP ath(

"/Acco unt/Bal anceQ uery/UserID "

) String user)

{ if (user.equals( "James.Strachan" )) { return 1200 ;

} else { return 0 ;

}

Where the binding of message data to method parameter is enabled by the @ XP ath

331

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

annotation, which injects the content of the UserID XML element into the user method parameter. On completion of the call, the return value is inserted into the body of the Out message which is then copied into the In message for the next step in the route. In order for the bean to be accessible to the beanR ef() processor, you must instantiate an instance in

Spring XML. For example, you can add the following lines to the MET A-

INF/spri ng /camel -co ntext. xml configuration file to instantiate the bean:

<?xml version="1.0" encoding="UTF-8"?>

...

</beans>

Where the bean ID, bankBean, identifes this bean instance in the registry.

The output of the bean invocation is injected into a Velocity template, to produce a properly formatted result message. The Velocity endpoint,

vel o ci ty: fi l e: src/scri pts/acc_bal ance. vm, specifies the location of a velocity script with the following contents:

<?xml version='1.0' encoding='UTF-8'?>

<UserID>${exchange.getProperty("userid")}</UserID>

</BalanceResult>

</Account>

The exchange instance is available as the Velocity variable, exchang e, which enables you to retrieve the useri d exchange property, using

${exchang e. g etP ro perty("useri d ")}. The body of the current In message, ${bo d y}, contains the result of the g etUserAccBal ance() method invocation.

332

CHAPT ER 1 1 . SYST EM MANAG EMENT

CHAPTER 11. SYSTEM MANAGEMENT

Ab st ract

The system management patterns describe how to monitor, test, and administer a messaging system.

11.1. Det our

De t o ur

The Detour from the

Introducing Enterprise Integration 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.

Exam ple

In this example we essentially have a route like

fro m("d i rect: start"). to ("mo ck: resul t") with a conditional detour to the

mo ck: d eto ur endpoint in the middle of the route..

from("direct:start").choice()

.when().method("controlBean", "isDetour").to("mock:detour").end()

.to("mock:result");

Usin g t h e Sp rin g XML Ext en sio n s

<route>

<when>

</when>

</choice>

333

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

</split>

</route> whether the detour is turned on or off is decided by the C o ntro l Bean. So, when the detour is on the message is routed to mo ck: d eto ur and then mo ck: resul t. When the detour is off, the message is routed to mo ck: resul t.

For full details, check the example source here: camel-core/src/test/java/org/apache/camel/processor/DetourTest.java

11.2. LogEIP

Ove rvie w

Apache Camel provides several ways to perform logging in a route:

Using the l o g DSL command.

Using the Log component, which can log the message content.

Using the Tracer, which traces message flow.

Using a P ro cesso r or a Bean endpoint to perform logging in Java.

Dif f eren ce b et ween t h e lo g DSL co mman d an d t h e lo g co mp o n en t

The l o g DSL is much lighter and meant for logging human logs such as

Starti ng to d o . . . . It can only log a message based on the

Simple language. In contrast, the Log component is a fully featured logging component.

The Log component is capable of logging the message itself and you have many

URI options to control the logging.

Java DSL e xam ple

Since Ap ach e Camel 2.2, you can use the l o g DSL command to construct a log message at run time using the Simple expression language. For example, you can create a log message within a route, as follows: from("direct:start").log("Processing ${id}").to("bean:foo");

334

CHAPT ER 1 1 . SYST EM MANAG EMENT

This route constructs a Stri ng format message at run time. The log message will by logged at INFO level, using the route ID as the log name. By default, routes are named consecutively, ro ute-1, ro ute-2 and so on. But you can use the DSL command,

ro uteId ("myC o o l R o ute"), to specify a custom route ID.

The log DSL also provides variants that enable you to set the logging level and the log name explicitly. For example, to set the logging level explicitly to Lo g g i ng Level . D EBUG , you can invoke the log DSL as follows: has overloaded methods to set the logging level and/or name as well.

from("direct:start").log(LoggingLevel.DEBUG, "Processing

${id}").to("bean:foo");

To set the log name to fi l eR o ute, you can invoke the log DSL as follows: from("file://target/files").log(LoggingLevel.DEBUG, "fileRoute",

"Processing file ${file:name}").to("bean:foo");

XML DSL e xam ple

In XML DSL, the log DSL is represented by the l o g element and the log message is specified by setting the messag e attribute to a Simple expression, as follows:

</route>

The l o g element supports the messag e, l o g g i ng Level and l o g Name attributes. For example:

</route>

11.3. Wire T ap

Wire T ap

The wire tap pattern, as shown in Figure 11.1, “ Wire Tap Pattern”

, enables you to route a copy of the message to a separate tap location, while the original message is forwarded to the ultimate destination.

Fig u re 11.1. Wire T ap Pat t ern

335

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

336

St reams

If you Wire Tap a stream message body, you should consider enabling

Stream

Caching to ensure the message body can be re-read. See more details at Stream

Caching

Wire T ap no de

Apache Camel 2.0 introduces the wi reT ap node for doing wire taps. The wi reT ap node copies the original exchange to a tapped exchange, whose exchange pattern is set to InOnly, because the tapped exchange should be propagated in a oneway style. The tapped exchange is processed in a separate thread, so that it can run concurrently with the main route.

The wi reT ap supports two different approaches to tapping an exchange:

Tap a copy of the original exchange.

Tap a new exchange instance, enabling you to customize the tapped exchange.

T ap a co py o f t he o riginal e xchange

Using the Java DSL: from("direct:start")

.to("log:foo")

.wireTap("direct:tap")

.to("mock:result");

Using Spring XML extensions:

<route>

CHAPT ER 1 1 . SYST EM MANAG EMENT

</route>

T ap and m o dify a co py o f t he o riginal e xchange

Using the Java DSL, Apache Camel supports using either a processor or an expression to modify a copy of the original exchange. Using a processor gives you full power over how the exchange is populated, because you can set properties, headers and so on. The expression approach can only be used to modify the In message body.

For example, to modify a copy of the original exchange using the processor approach: from("direct:start")

.wireTap("direct:foo", new Processor() {

public void process(Exchange exchange) throws Exception {

exchange.getIn().setHeader("foo", "bar");

}

}).to("mock:result"); from("direct:foo").to("mock:foo");

And to modify a copy of the original exchange using the expression approach: from("direct:start")

.wireTap("direct:foo", constant("Bye World"))

.to("mock:result"); from("direct:foo").to("mock:foo");

Using the Spring XML extensions, you can modify a copy of the original exchange using the

processor approach, where the pro cesso rR ef attribute references a spring bean with the

myP ro cesso r ID:

<route>

</route>

And to modify a copy of the original exchange using the expression approach:

<route>

<body><constant>Bye World</constant></body>

</wireTap>

</route>

T ap a ne w e xchange inst ance

337

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

T ap a ne w e xchange inst ance

You can define a wiretap with a new exchange instance by setting the copy flag to fal se

(the default is true). In this case, an initially empty exchange is created for the wiretap.

For example, to create a new exchange instance using the processor approach: 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");

Where the second wi reT ap argument sets the copy flag to fal se, indicating that the original exchange is not copied and an empty exchange is created instead.

To create a new exchange instance using the expression approach: from("direct:start")

.wireTap("direct:foo", false, constant("Bye World"))

.to("mock:result"); from("direct:foo").to("mock:foo");

Using the Spring XML extensions, you can indicate that a new exchange is to be created by setting the wi reT ap element's co py attribute to fal se.

To create a new exchange instance using the processor approach, where the

pro cesso rR ef attribute references a spring bean with the myP ro cesso r ID, as follows:

<route>

</route>

338

And to create a new exchange instance using the expression approach:

<route>

<body><constant>Bye World</constant></body>

</wireTap>

</route>

CHAPT ER 1 1 . SYST EM MANAG EMENT

Se nding a ne w Exchange and se t he ade rs in DSL

Availab le as o f 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

Processors 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");

XML DSL

The XML DSL is slightly different than Java DSL as how you configure the message body and headers. In XML you use <body> and <setHeader> as shown:

<route>

<body><constant>Bye World</constant></body>

</setHeader>

339

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

<setHeader headerName="date"><simple>${date:now:yyyyMMdd}

</simple></setHeader>

</wireTap>

</route>

Using o nPre pare t o e xe cut e cust o m lo gic whe n pre paring m e ssage s

Availab le as o f Camel 2.8

For details, see Multicast .

Opt io ns

The wi reT ap DSL command supports the following options:

Name uri ref executo rServi ceR ef pro cesso rR ef co py

Default Value true

Descript ion

The end p o int uri where to send the wire tap p ed messag e. Yo u sho uld use either

uri

o r

ref

Refers to the end p o int where to send the wire tap p ed messag e. Yo u sho uld use either

uri

o r

ref

Refers to a custo m Thread

Po o l to b e used when

p ro cessing the wire tap p ed messag es. If no t set then

Camel uses a d efault thread p o o l.

Refers to a custo m

Pro cesso rs to b e used fo r

creating a new messag e (eg the send a new messag e mo d e). See b elo w.

Camel 2 .3: Sho uld a co p y o f

the Exchang e

to used when wire tap p ing the messag e.

34 0

o nP repareR ef

CHAPT ER 1 1 . SYST EM MANAG EMENT

Camel 2 .8 : Refers to a custo m

Pro cesso rs

to p rep are the co p y o f the

Exchang e

to b e wire tap p ed .

This allo ws yo u to d o any custo m lo g ic, such as d eep clo ning the messag e p aylo ad if that's need ed etc.

1. SERVICE COMPONENT RUNT IME

Abst ract

Service Component Runtime (SCR) is an implementation of OSGi Declarative Services specification. It enables any plain old Java object to expose and use OSGi services with no boilerplate code.

Working wit h Camel and SCR

Apache Camel SCR component provides an integration of Camel with the OSGi Service

Component Runtime.

OSGi framework has ability to know the object by looking at SCR descriptor file in its bundle which are generated from Java annotations by a plugin such as

o rg . apache. fel i x: maven-scr-pl ug i n. Using SCR, the bundle remains completely in

Java world. There is no need to edit XML or properties file. It offers you full control over the project.

Creat ing a Service Component

Following are the steps to create a service component out of your java class.

1. Add the required o rg . apache. fel i x. scr. anno tati o ns at class level. For example,

@ Component

@ References({

@ Reference(name = "camelComponent" ,referenceInterface =

ComponentResolver.class,

cardinality = ReferenceCardinality.MANDATORY_MULTIPLE, policy = ReferencePolicy.DYNAMIC,

policyOption = ReferencePolicyOption.GREEDY, bind =

"gotCamelComponent" , unbind = "lostCamelComponent" )

})

34 1

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

2. Implement the g etR o uteBui l d ers() method that returns the Camel route you want to run. For example,

@ Override protected List<RoutesBuilder> getRouteBuilders() {

List<RoutesBuilder> routesBuilders = new ArrayList<>();

routesBuilders.add( new YourRouteBuilderHere(registry));

routesBuilders.add( new AnotherRouteBuilderHere(registry)); return routesBuilders;

}

3. Finally, enter the default configuration in annotations.

@ Properties({

@ Property(name = "camelContextId" , value = "my-test" ),

@ Property(name = "active" , value = "true" ),

@ Property(name = "..." , value = "..." ),

...

})

34 2

Example of a Service Component class

The following example illustrates the use of camel -archetype-scr to generate a complete service component class:

// This file was generated from org.apache.camel.archetypes/camelarchetype-scr/2.15-SNAPSHOT

package example; import java.util.ArrayList; import java.util.List; import org.apache.camel.scr.AbstractCamelRunner; import example.internal.CamelScrExampleRoute; import org.apache.camel.RoutesBuilder; import org.apache.camel.spi.ComponentResolver; import org.apache.felix.scr.annotations.*;

@ Component(label = CamelScrExample.COMPONENT_LABEL, description =

CamelScrExample.COMPONENT_DESCRIPTION, immediate = true , metatype = true )

@ Properties({

@ Property(name = "camelContextId" , value = "camel-scr-example" ),

@ Property(name = "camelRouteId" , value = "foo/timer-log" ),

@ Property(name = "active" , value = "true" ),

@ Property(name = "from" , value = "timer:foo?period=5000" ),

@ Property(name = "to" , value = "log:foo?showHeaders=true" ),

@ Property(name = "messageOk" , value = "Success: {{from}} ->

{{to}}" ),

@ Property(name = "messageError" , value = "Failure: {{from}} ->

{{to}}" ),

CHAPT ER 1 1 . SYST EM MANAG EMENT

@ Property(name = "maximumRedeliveries" , value = "0" ),

@ Property(name = "redeliveryDelay" , value = "5000" ),

@ Property(name = "backOffMultiplier" , value = "2" ),

@ Property(name = "maximumRedeliveryDelay" , value = "60000" )

})

@ References({

@ Reference(name = "camelComponent" ,referenceInterface =

ComponentResolver.class,

cardinality = ReferenceCardinality.MANDATORY_MULTIPLE, policy

= ReferencePolicy.DYNAMIC,

policyOption = ReferencePolicyOption.GREEDY, bind =

"gotCamelComponent" , unbind = "lostCamelComponent" )

}) public class CamelScrExample extends AbstractCamelRunner { public static final String COMPONENT_LABEL =

"example.CamelScrExample" ; public static final String COMPONENT_DESCRIPTION = "This is the description for camel-scr-example." ;

@ Override protected List<RoutesBuilder> getRouteBuilders() {

List<RoutesBuilder> routesBuilders = new ArrayList<>();

routesBuilders.add( new CamelScrExampleRoute(registry)); return routesBuilders;

}

Example of a Rout eBuilder class

The following example illustrates the use of camel -archetype-scr to generate a

R o uteBui l d er class:

// This file was generated from org.apache.camel.archetypes/camelarchetype-scr/2.15-SNAPSHOT

package example.internal; import org.apache.camel.LoggingLevel; import org.apache.camel.builder.RouteBuilder; import org.apache.camel.impl.SimpleRegistry; import org.apache.commons.lang.Validate; public class CamelScrExampleRoute extends RouteBuilder {

SimpleRegistry registry;

// Configured fields

private String camelRouteId; private Integer maximumRedeliveries; private Long redeliveryDelay; private Double backOffMultiplier; private Long maximumRedeliveryDelay;

34 3

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

public CamelScrExampleRoute( final SimpleRegistry registry) { this .registry = registry;

}

@ Override public void configure() throws Exception {

checkProperties();

// Add a bean to Camel context registry

registry.put( "test" , "bean" );

errorHandler(defaultErrorHandler()

.retryAttemptedLogLevel(LoggingLevel.WARN)

.maximumRedeliveries(maximumRedeliveries)

.redeliveryDelay(redeliveryDelay)

.backOffMultiplier(backOffMultiplier)

.maximumRedeliveryDelay(maximumRedeliveryDelay));

from( "{{from}}" )

.startupOrder( 2 )

.routeId(camelRouteId)

.onCompletion()

.to( "direct:processCompletion" )

.end()

.removeHeaders( "CamelHttp*" )

.to( "{{to}}" );

from( "direct:processCompletion" )

.startupOrder( 1 )

.routeId(camelRouteId + ".completion" )

.choice()

.when(simple( "${exception} == null" ))

.log( "{{messageOk}}" )

.otherwise()

.log(LoggingLevel.ERROR, "{{messageError}}" )

.end();

}

} public void checkProperties() {

Validate.notNull(camelRouteId, "camelRouteId property is not set" );

Validate.notNull(maximumRedeliveries, "maximumRedeliveries property is not set" );

Validate.notNull(redeliveryDelay, "redeliveryDelay property is not set" );

Validate.notNull(backOffMultiplier, "backOffMultiplier property is not set" );

Validate.notNull(maximumRedeliveryDelay,

"maximumRedeliveryDelay property is not set" );

}

34 4

Using Apache Camel SCR bundle as a t emplat e

CHAPT ER 1 1 . SYST EM MANAG EMENT

Using Apache Camel SCR bundle as a t emplat e

If you have a Camel SCR bundle that implements an integration pattern that you use frequently, then, probably there is no need to create a separate bundle for every instance.

The following example illustrates how to use a Camel SCR bundle as a template. It includes the following steps:

1. Create a configuration PID for your service component and add a tail with a dash.

2. Camel SCR will use the configuration to create a new instance of your component.

3. Finally, you can start a new C amel C o ntext with your overridden properties.

# Create a PID with a tail karaf@ root> config:edit example.CamelScrExample-anotherone

# Override some properties karaf@ root> config:propset camelContextId my-other-context karaf@ root> config:propset to "file://removeme?

fileName=removemetoo.txt"

# Save the PID karaf@ root> config:update

No t e

Make sure that your service component does not start with the default configuration. To prevent this, add po l i cy =

C o nfi g urati o nP o l i cy. R EQ UIR E to the class level at component annotation.

Using Apache camel-archet ype-scr

With the help of Apache camel -archetype-scr and maven, you can easily create Apache

Camel SCR bundle project. It includes the following steps:

1. Run the following command:

$ mvn archetype:generate -

Dfilter=org.apache.camel.archetypes:camel-archetype-scr

Choose archetype: local -> org.apache.camel.archetypes:camel-archetype-scr

(Creates a new Camel SCR bundle project for Karaf)

Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 1

Define value for property 'groupId': : example

[INFO] Using property: groupId = example

Define value for property 'artifactId' : : camel-scr-example

34 5

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Define value for property 'version' : 1.0

-SNAPSHOT: :

Define value for property 'package' : example: :

[INFO] Using property: archetypeArtifactId = camel-archetype-scr

[INFO] Using property: archetypeGroupId = org.apache.camel.archetypes

[INFO] Using property: archetypeVersion = 2.15

-SNAPSHOT

Define value for property 'className' : : CamelScrExample

Confirm properties configuration: groupId: example artifactId: camel-scr-example version: 1.0

-SNAPSHOT package : example archetypeArtifactId: camel-archetype-scr archetypeGroupId: org.apache.camel.archetypes

archetypeVersion: 2.15

-SNAPSHOT className: CamelScrExample

Y: :

2. Run Apache Maven.

No t e

For details on setting up Apache Maven to work with Red Hat JBoss Fuse, see Building with Maven in Red Hat JBoss Fuse Deploying into the

Container on the Red Hat Customer Portal

3. You can now deploy the bundle. To deploy the bundle on Apache Karaf, perform the following steps on Karaf command line:

# Add Camel feature repository karaf@ root> features:chooseurl camel 2.15

-SNAPSHOT

# Install camel-scr feature karaf@ root> features:install camel-scr

# Install commons-lang, used to validate parameters karaf@ root> osgi:install mvn:commons-lang/commons-lang/ 2.6

# Install and start your bundle karaf@ root> osgi:install -s mvn:example/camel-scr-example/ 1.0

SNAPSHOT

# View the log.

karaf@ root> log:tail -n 10

Press ctrl-c to stop the log.

34 6

4. By default, the Service Component's configuration PID equals the fully qualified name of its class. You can change the properties of a bundle with Apache Karaf's

co nfi g . * commands:

CHAPT ER 1 1 . SYST EM MANAG EMENT

co nfi g . * commands:

# Override the messageOk property karaf@ root> config:propset -p example.CamelScrExample messageOk

"This is better logging" .

You can also change the configuration by editing the property file in Apache Karaf's

etc directory.

34 7

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

PART II. ROUTING EXPRESSION AND PREDICATE

LANGUAGES

Ab st ract

This guide describes the basic syntax used by the evaluative languages supported by

Apache Camel.

34 8

CHAPT ER 1 2 . INT RO DUCT IO N

CHAPTER 12. INTRODUCTION

Ab st ract

This chapter provides an overview of all the expression languages supported by Apache

Camel.

12.1. OVERVIEW OF T HE LANGUAGES

T able of expression and predicat e languages

Table 12.1, “ Expression and Predicate Languages”

gives an overview of the different syntaxes for invoking expression and predicate languages.

T ab le 12.1. Exp ressio n an d Pred icat e Lan g u ag es

Language

St at ic

Met hod bean()

Fluent DSL

Met hod

EIP(). met ho d ()

XML

Element metho d

Annot at ion Art ifact

@ Bean

Camel core

co nstant(

) el () g ro o vy()

EIP(). co n stant() co nstant

EIP(). el (

) el

EIP(). g ro o vy() g ro o vy head er() javaScri p t() sq l ()

EIP(). hea d er() head er

EIP(). jav aScri pt() javaScri p t

EIP(). sq l () sq l

None

EIP(). jso npath()

EIP(). jxp ath() jso npath jxpath

@ C o nstant

@ EL

@ G ro o vy

@ Head er

Camel core

camel juel camel g ro o vy

Camel core

@ JavaScri pt

@ SQ L camel scri pt camel jo sq l

@ JSo nP ath camel jso npath

@ JXP ath camel jxpath

34 9

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Language

St at ic

Met hod mvel () o g nl () php() pro perty(

) pytho n() ref() ruby() si mpl e() spel () xpath() xq uery()

Fluent DSL

Met hod

XML

Element

EIP(). mve l () mvel

EIP(). o g nl () o g nl

EIP(). php

() php

EIP(). pro perty() pro perty

EIP(). pyt ho n() pytho n ref EIP(). ref

()

EIP(). rub y() ruby

EIP(). si m pl e() si mpl e

EIP(). spe l () spel

EIP(). xpa th() xpath

EIP(). xq u ery() xq uery

Annot at ion Art ifact

@ MVEL

@ O G NL camel mvel camel o g nl

@ P HP camel scri pt

@ P ro perty

Camel core

@ P ytho n

N/A

@ R uby

@ Si mpl e

@ SpEL

@ XP ath

@ XQ uery camel scri pt

Camel core

camel scri pt

Camel core

camel spri ng

Camel core

camel saxo n

12.2. HOW T O INVOKE AN EXPRESSION LANGUAGE

Prerequisit es

Before you can use a particular expression language, you must ensure that the required JAR files are available on the classpath. If the language you want to use is not included in the

Apache Camel core, you must add the relevant JARs to your classpath.

350

If you are using the Maven build system, you can modify the build-time classpath simply by adding the relevant dependency to your POM file. For example, if you want to use the Ruby language, add the following dependency to your POM file:

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

CHAPT ER 1 2 . INT RO DUCT IO N

<artifactId>camel-script</artifactId>

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

</dependency>

If you are going to deploy your application in a Red Hat JBoss Fuse OSGi container, you also need to ensure that the relevant language features are installed (features are named after the corresponding Maven artifact). For example, to use the Groovy language in the

OSGi container, you must first install the camel -g ro o vy feature by entering the following

OSGi console command: karaf@ root> features:install camel-groovy

Approaches t o invoking

As shown in Table 12.1, “ Expression and Predicate Languages” , there are several different

syntaxes for invoking an expression language, depending on the context in which it is used.

You can invoke an expression language:

the section called “ As a static method”

the section called “ As a fluent DSL method”

the section called “ As an XML element”

the section called “ As an annotation”

As a st at ic met hod

Most of the languages define a static method that can be used in any context where an

o rg . apache. camel . Expressi o n type or an o rg . apache. camel . P red i cate type is expected. The static method takes a string expression (or predicate) as its argument and returns an Expressi o n object (which is usually also a P red i cate object).

For example, to implement a content-based router that processes messages in XML format, you could route messages based on the value of the /o rd er/ad d ress/co untryC o d e element, as follows: from("SourceURL")

.choice

.when(xpath("/o rd er/ad d ress/co untryC o d e = ' us' "))

.to("file://countries/us/")

.when(xpath("/o rd er/ad d ress/co untryC o d e = ' uk' "))

.to("file://countries/uk/")

.otherwise()

.to("file://countries/other/")

.to("TargetURL");

As a fluent DSL met hod

351

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

As a fluent DSL met hod

The Java fluent DSL supports another style of invoking expression languages. Instead of providing the expression as an argument to an Enterprise Integration Pattern (EIP), you can provide the expression as a sub-clause of the DSL command. For example, instead of invoking an XPath expression as fi l ter(xpath("Expression")), you can invoke the expression as, fi l ter(). xpath("Expression").

For example, the preceding content-based router can be re-implemented in this style of invocation, as follows: from("SourceURL")

.choice

.when().xpath("/o rd er/ad d ress/co untryC o d e = ' us' ")

.to("file://countries/us/")

.when().xpath("/o rd er/ad d ress/co untryC o d e = ' uk' ")

.to("file://countries/uk/")

.otherwise()

.to("file://countries/other/")

.to("TargetURL");

As an XML element

You can also invoke an expression language in XML, by putting the expression string inside the relevant XML element.

For example, the XML element for invoking XPath in XML is xpath (which belongs to the standard Apache Camel namespace). You can use XPath expressions in a XML DSL content-based router, as follows:

<when>

<xpath>/o rd er/ad d ress/co untryC o d e = ' us' </xpath>

</when>

<when>

<xpath>/o rd er/ad d ress/co untryC o d e = ' uk' </xpath>

</when>

</otherwise>

</choice>

Alternatively, you can specify a language expression using the l ang uag e element, where you specify the name of the language in the l ang uag e attribute. For example, you can define an XPath expression using the l ang uag e element as follows:

<language language="xpath">/order/address/countryCode =

'us'</language>

352

CHAPT ER 1 2 . INT RO DUCT IO N

As an annot at ion

Language annotations are used in the context of bean integration (see Section 2.4, “ Bean

Integration” ). The annotations provide a convenient way of extracting information from a

message or header and then injecting the extracted data into a bean's method parameters.

For example, consider the bean, myBeanP ro c, which is invoked as a predicate of the

fi l ter() EIP. If the bean's checkC red enti al s method returns true, the message is allowed to proceed; but if the method returns fal se, the message is blocked by the filter. The filter pattern is implemented as follows:

// Java

MyBeanProcessor myBeanProc = new MyBeanProcessor(); from("SourceURL")

.filter().method(myBeanProc, "checkCredentials")

.to("TargetURL");

The implementation of the MyBeanP ro cesso r class exploits the @ XP ath annotation to extract the username and passwo rd from the underlying XML message, as follows:

// Java import org.apache.camel.language.XPath; public class MyBeanProcessor {

boolean void checkCredentials(

@ XP ath("/cred enti al s/username/text()") String user,

@ XP ath("/cred enti al s/passwo rd /text()") String pass

) {

// Check the user/pass credentials...

...

}

The @ XP ath annotation is placed just before the parameter into which it gets injected. Notice how the XPath expression explicitly selects the text node, by appending /text() to the path, which ensures that just the content of the element is selected, not the enclosing tags.

As a Camel endpoint URI

Using the Camel Language component, you can invoke a supported language in an endpoint URI. There are two alternative syntaxes.

To invoke a language script stored in a file (or other resource type defined by Scheme), use the following URI syntax: language://LanguageName:resource:Scheme:Location[?Options]

Where the scheme can be fi l e: , cl asspath: , or http: .

353

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

For example, the following route executes the mysi mpl escri pt. txt from the classpath: from("direct:start")

.to("language:simple:classpath:org/apache/camel/component/language/mys implescript.txt")

.to("mock:result");

To invoke an embedded language script, use the following URI syntax: language://LanguageName[:Script][?Options]

For example, to run the Simple language script stored in the scri pt string:

String script = URLEncoder.encode("Hello ${body}", "UTF-8"); from("direct:start")

.to("language:simple:" + script)

.to("mock:result");

For more details about the Language component, see chapter "Language" in "Apache

Camel Component Reference" .

354

CHAPT ER 1 3. CO NST ANT

CHAPTER 13. CONSTANT

OVERVIEW

The constant language is a trivial built-in language that is used to specify a plain text string.

This makes it possible to provide a plain text string in any context where an expression type is expected.

XML EXAMPLE

In XML, you can set the username header to the value, Jane D o e as follows:

<route>

</setHeader>

</route>

</camelContext>

JAVA EXAMPLE

In Java, you can set the username header to the value, Jane D o e as follows: from("SourceURL")

.setHeader("username", constant("Jane Doe"))

.to("TargetURL");

355

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 14. EL

OVERVIEW

The Unified Expression Language (EL) was originally specified as part of the JSP 2.1

standard (JSR-245), but it is now available as a standalone language. Apache Camel integrates with JUEL ( http://juel.sourceforge.net/ ), which is an open source implementation of the EL language.

ADDING JUEL PACKAGE

To use EL in your routes you need to add a dependency on camel -juel to your project as shown in

Example 14.1, “ Adding the camel-juel dependency”

Examp le 14 .1. Ad d in g t h e camel- ju el d ep en d en cy

<camel-version> 2.15.1.redhat-620133 </camel-version>

...

</properties>

...

<groupId> org.apache.camel

</groupId>

<artifactId> camel-juel </artifactId>

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

</dependency>

...

</dependencies>

356

ST AT IC IMPORT

To use the el () static method in your application code, include the following import statement in your Java source files: import static org.apache.camel.language.juel.JuelExpression.el;

VARIABLES

Table 14.1, “ EL variables” lists the variables that are accessible when using EL.

T ab le 14 .1. EL variab les

CHAPT ER 1 4 . EL

Variable exchang e i n o ut

T ype Value o rg . apache. camel . Exc hang e

The current Exchang e

o rg . apache. camel . Mes sag e

The IN messag e

o rg . apache. camel . Mes sag e

The O UT messag e

EXAMPLE

Example 14.2, “ Routes using EL”

shows two routes that use EL.

Examp le 14 .2. Ro u t es u sin g EL

<route>

<language language= "el" > ${in.headers.foo == 'bar'} </language>

</filter>

</route>

<route>

<language language= "el" > ${in.headers['My Header'] ==

'bar'} </language>

</filter>

</route>

</camelContext>

357

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 15. THE FILE LANGUAGE

Ab st ract

The file language is an extension to the simple language, not an independent language in its own right. But the file language extension can only be used in conjunction with File or

FTP endpoints.

15.1. WHEN T O USE T HE FILE LANGUAGE

Overview

The file language is an extension to the simple language which is not always available. You can use it under the following circumstances:

the section called “ In a File or FTP consumer endpoint”

the section called “ On exchanges created by a File or FTP consumer”

No t e

The escape character, \, is not available in the file language.

In a File or FT P consumer endpoint

There are several URI options that you can set on a File or FTP consumer endpoint, which take a file language expression as their value. For example, in a File consumer endpoint URI you can set the fi l eName, mo ve, preMo ve, mo veFai l ed , and so rtBy options using a file expression.

In a File consumer endpoint, the fi l eName option acts as a filter, determining which file will actually be read from the starting directory. If a plain text string is specified (for example,

fi l eName= repo rt. txt), the File consumer reads the same file each time it is updated. You can make this option more dynamic, however, by specifying a simple expression. For example, you could use a counter bean to select a different file each time the File consumer polls the starting directory, as follows: file://target/filelanguage/bean/?

fileName=${bean:counter.next}.txt& delete=true

Where the ${bean: co unter. next} expression invokes the next() method on the bean registered under the ID, co unter.

The mo ve option is used to move files to a backup location after then have been read by a

File consumer endpoint. For example, the following endpoint moves files to a backup directory, after they have been processed:

358

CHAPT ER 1 5. T HE FILE LANG UAG E

file://target/filelanguage/?

move=backup/${date:now:yyyyMMdd}/${file:name.noext}.bak& recursive=fals e

Where the ${fi l e: name. no ext}. bak expression modifies the original file name, replacing the file extension with . bak.

You can use the so rtBy option to specify the order in which file should be processed. For example, to process files according to the alphabetical order of their file name, you could use the following File consumer endpoint: file://target/filelanguage/?sortBy=file:name

To process file according to the order in which they were last modified, you could use the following File consumer endpoint: file://target/filelanguage/?sortBy=file:modified

You can reverse the order by adding the reverse: prefix—for example: file://target/filelanguage/?sortBy=reverse:file:modified

On exchanges creat ed by a File or FT P consumer

When an exchange originates from a File or FTP consumer endpoint, it is possible to apply file language expressions to the exchange throughout the route (as long as the original message headers are not erased). For example, you could define a content-based router, which routes messages according to their file extension, as follows:

<when>

</when>

<when>

</when>

</otherwise>

</choice>

15.2. FILE VARIABLES

Overview

359

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

File variables can be used whenever a route starts with a File or FTP consumer endpoint, which implies that the underlying message body is of java. i o . Fi l e type. The file variables enable you to access various parts of the file pathname, almost as if you were invoking the methods of the java. i o . Fi l e class (in fact, the file language extracts the information it needs from message headers that have been set by the File or FTP endpoint).

St art ing direct ory

Some of file variables return paths that are defined relative to a starting directory, which is just the directory that is specified in the File or FTP endpoint. For example, the following File consumer endpoint has the starting directory, . /fi l etransfer (a relative path): file:filetransfer

The following FTP consumer endpoint has the starting directory, . /ftptransfer (a relative path): ftp://myhost:2100/ftptransfer

Naming convent ion of file variables

In general, the file variables are named after corresponding methods on the

java. i o . Fi l e class. For example, the fi l e: abso l ute variable gives the value that would be returned by the java. i o . Fi l e. g etAbso l ute() method.

No t e

This naming convention is not strictly followed, however. For example, there is no such method as java. i o . Fi l e. g etSi ze().

T able of variables

Table 15.1, “ Variables for the File Language”

shows all of the variable supported by the file language.

T ab le 15.1. Variab les f o r t h e File Lan g u ag e

Variable fi l e: name fi l e: name. ext

T ype

Stri ng

Descript ion

The p athname relative to the starting d irecto ry.

The file extensio n

(characters fo llo wing the last

character in the p athname).

360

CHAPT ER 1 5. T HE FILE LANG UAG E

Variable fi l e: name. no ext fi l e: o nl yname fi l e: o nl yname. no ext Stri ng fi l e: ext fi l e: parent fi l e: path fi l e: abso l ute fi l e: abso l ute. path Stri ng fi l e: l eng th

T ype

Stri ng

Bo o l ean

Lo ng

Descript ion

The p athname relative to the starting d irecto ry, o mitting the file extensio n.

The final seg ment o f the p athname. That is, the file name witho ut the p arent d irecto ry p ath.

The final seg ment o f the p athname, o mitting the file extensio n.

The file extensio n (same as

fi l e: name. ext

The p athname o f the p arent d irecto ry, includ ing the starting d irecto ry in the p ath.

The file p athname, includ ing the starting d irecto ry in the p ath.

true

, if the starting d irecto ry was sp ecified as an ab so lute p ath;

fal se

, o therwise.

The ab so lute p athname o f the file.

The size o f the referenced file.

Same as

file:length

Date last mo d ified .

fi l e: si ze fi l e: mo d i fi ed

Lo ng java. uti l . D ate

15.3. EXAMPLES

Relat ive pat hname

Consider a File consumer endpoint, where the starting directory is specified as a relative

pathname. For example, the following File endpoint has the starting directory,

. /fi l el ang uag e: file://filelanguage

361

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Now, while scanning the fi l el ang uag e directory, suppose that the endpoint has just consumed the following file:

./filelanguage/test/hello.txt

And, finally, assume that the fi l el ang uag e directory itself has the following absolute location:

/workspace/camel/camel-core/target/filelanguage

Given the preceding scenario, the file language variables return the following values, when applied to the current exchange:

Expression fi l e: name fi l e: name. ext fi l e: name. no ext fi l e: o nl yname fi l e: o nl yname. no ext fi l e: ext fi l e: parent fi l e: path fi l e: abso l ute fi l e: abso l ute. path

Result test/hel l o . txt txt test/hel l o hel l o . txt hel l o txt fi l el ang uag e/test fi l el ang uag e/test/hel l o . txt fal se

/wo rkspace/camel /camel co re/targ et/fi l el ang uag e/test/he l l o . txt

Absolut e pat hname

Consider a File consumer endpoint, where the starting directory is specified as an absolute

pathname. For example, the following File endpoint has the starting directory,

/wo rkspace/camel /camel -co re/targ et/fi l el ang uag e: file:///workspace/camel/camel-core/target/filelanguage

Now, while scanning the fi l el ang uag e directory, suppose that the endpoint has just consumed the following file:

362

CHAPT ER 1 5. T HE FILE LANG UAG E

./filelanguage/test/hello.txt

Given the preceding scenario, the file language variables return the following values, when applied to the current exchange:

Expression fi l e: name fi l e: name. ext fi l e: name. no ext fi l e: o nl yname fi l e: o nl yname. no ext fi l e: ext fi l e: parent fi l e: path fi l e: abso l ute fi l e: abso l ute. path

Result test/hel l o . txt txt test/hel l o hel l o . txt hel l o txt

/wo rkspace/camel /camel co re/targ et/fi l el ang uag e/test

/wo rkspace/camel /camel co re/targ et/fi l el ang uag e/test/he l l o . txt true

/wo rkspace/camel /camel co re/targ et/fi l el ang uag e/test/he l l o . txt

363

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 16. GROOVY

OVERVIEW

Groovy is a Java-based scripting language that allows quick parsing of object. The Groovy support is part of the camel -scri pt module.

ADDING T HE SCRIPT MODULE

To use Groovy in your routes you need to add a dependency on camel -scri pt to your

project as shown in Example 16.1, “ Adding the camel-script dependency”

Examp le 16 .1. Ad d in g t h e camel- scrip t d ep en d en cy

<camel-version> 2.15.1.redhat-620133 </camel-version>

...

</properties>

...

<groupId> org.apache.camel

</groupId>

<artifactId> camel-script </artifactId>

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

</dependency>

...

</dependencies>

ST AT IC IMPORT

To use the g ro o vy() static method in your application code, include the following import statement in your Java source files: import static org.apache.camel.builder.camel.script.ScriptBuilder.*;

BUILT -IN AT T RIBUT ES

Table 16.1, “ Groovy attributes” lists the built-in attributes that are accessible when using

Groovy.

T ab le 16 .1. G ro o vy at t rib u t es

364

At t ribut e co ntext exchang e req uest respo nse pro perti es

CHAPT ER 1 6 . G RO O VY

T ype Value o rg . apache. camel . C am el C o ntext

The Camel Co ntext

o rg . apache. camel . Exc hang e

The current Exchang e

o rg . apache. camel . Mes sag e

The IN messag e

o rg . apache. camel . Mes sag e

The O UT messag e

o rg . apache. camel . bui l d er. scri pt. P ro perti esFuncti o n

Functio n with a

reso l ve

metho d to make it easier to use the p ro p erties co mp o nent insid e scrip ts.

The attributes all set at ENG INE_SC O P E.

EXAMPLE

Example 16.2, “ Routes using Groovy”

shows two routes that use Groovy scripts.

Examp le 16 .2. Ro u t es u sin g G ro o vy

<route>

<language language= "groovy" > request.lineItems.any { i -> i.value > 100 } </language>

</filter>

</route>

<route>

<language language= "groovy" > $user.firstName

$user.lastName

</language>

</setHeader>

</route>

</camelContext>

USING T HE PROPERT IES COMPONENT

365

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

To access a property value from the properties component, invoke the reso l ve method on the built-in pro perti es attribute, as follows:

.setHeader("myHeader").groovy("properties.resolve(PropKey)")

Where PropKey is the key of the property you want to resolve, where the key value is of

Stri ng type.

For more details about the properties component, see chapter "Properties" in "Apache Camel

Component Reference" .

CUST OMIZING GROOVY SHELL

Sometimes, you might need to use the custom G ro o vyShel l instance, in your Groovy expressions. To provide custom G ro o vyShel l , add an implementation of the

o rg . apache. camel . l ang uag e. g ro o vy. G ro o vyShel l Facto ry SP I interface to your Camel registry.

For example, when you add the following bean to your Spring context, Apache Camel will use the custom G ro o vyShel l instance that includes the custom static imports, instead of the default one.

public class CustomGroovyShellFactory implements GroovyShellFactory { public GroovyShell createGroovyShell(Exchange exchange) {

ImportCustomizer importCustomizer = new ImportCustomizer();

importCustomizer.addStaticStars( "com.example.Utils" );

CompilerConfiguration configuration = new CompilerConfiguration();

configuration.addCompilationCustomizers(importCustomizer); return new GroovyShell(configuration);

}

366

CHAPT ER 1 7 . HEADER

CHAPTER 17. HEADER

OVERVIEW

The header language provides a convenient way of accessing header values in the current message. When you supply a header name, the header language performs a caseinsensitive lookup and returns the corresponding header value.

The header language is part of camel -co re.

XML EXAMPLE

For example, to resequence incoming exchanges according to the value of a

Seq uenceNumber header (where the sequence number must be a positive integer), you can define a route as follows:

<route>

<language language="header">SequenceNumber</language>

</resequence>

</route>

</camelContext>

JAVA EXAMPLE

The same route can be defined in Java, as follows: from("SourceURL")

.resequence(header("SequenceNumber"))

.to("TargetURL");

367

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 18. JAVASCRIPT

OVERVIEW

JavaScript, also known as ECMAScript is a Java-based scripting language that allows quick parsing of object. The JavaScript support is part of the camel -scri pt module.

ADDING T HE SCRIPT MODULE

To use JavaScript in your routes you need to add a dependency on camel -scri pt to your

project as shown in Example 18.1, “ Adding the camel-script dependency”

Examp le 18.1. Ad d in g t h e camel- scrip t d ep en d en cy

<camel-version> 2.15.1.redhat-620133 </camel-version>

...

</properties>

...

<groupId> org.apache.camel

</groupId>

<artifactId> camel-script </artifactId>

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

</dependency>

...

</dependencies>

ST AT IC IMPORT

To use the javaScri pt() static method in your application code, include the following import statement in your Java source files: import static org.apache.camel.builder.camel.script.ScriptBuilder.*;

BUILT -IN AT T RIBUT ES

Table 18.1, “ JavaScript attributes” lists the built-in attributes that are accessible when using

JavaScript.

T ab le 18.1. JavaScrip t at t rib u t es

368

At t ribut e co ntext exchang e req uest respo nse pro perti es

CHAPT ER 1 8 . JAVASCRIPT

T ype Value o rg . apache. camel . C am el C o ntext

The Camel Co ntext

o rg . apache. camel . Exc hang e

The current Exchang e

o rg . apache. camel . Mes sag e

The IN messag e

o rg . apache. camel . Mes sag e

The O UT messag e

o rg . apache. camel . bui l d er. scri pt. P ro perti esFuncti o n

Functio n with a

reso l ve

metho d to make it easier to use the p ro p erties co mp o nent insid e scrip ts.

The attributes all set at ENG INE_SC O P E.

EXAMPLE

Example 18.2, “ Route using JavaScript”

shows a route that uses JavaScript.

Examp le 18.2. Ro u t e u sin g JavaScrip t

<route>

<when>

<langauge langauge= "javaScript" > request.headers.get('user')

== 'admin' </langauge>

</when>

</otherwise>

</choice>

</route>

</camelContext>

USING T HE PROPERT IES COMPONENT

To access a property value from the properties component, invoke the reso l ve method on the built-in pro perti es attribute, as follows:

369

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

.setHeader("myHeader").javaScript("properties.resolve(PropKey)")

Where PropKey is the key of the property you want to resolve, where the key value is of

Stri ng type.

For more details about the properties component, see chapter "Properties" in "Apache Camel

Component Reference" .

370

CHAPT ER 1 9 . JO SQ L

CHAPTER 19. JOSQL

OVERVIEW

The JoSQL (SQL for Java objects) language enables you to evaluate predicates and expressions in Apache Camel. JoSQL employs a SQL-like query syntax to perform selection and ordering operations on data from in-memory Java objects—however, JoSQL is not a database. In the JoSQL syntax, each Java object instance is treated like a table row and each object method is treated like a column name. Using this syntax, it is possible to construct powerful statements for extracting and compiling data from collections of Java objects. For details, see http://josql.sourceforge.net/ .

ADDING T HE JOSQL MODULE

To use JoSQL in your routes you need to add a dependency on camel -jo sq l to your

project as shown in Example 19.1, “ Adding the camel-josql dependency”

Examp le 19 .1. Ad d in g t h e camel- jo sq l d ep en d en cy

...

...

<groupId> org.apache.camel

</groupId>

<artifactId> camel-josql </artifactId>

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

</dependency>

...

</dependencies>

ST AT IC IMPORT

To use the sq l () static method in your application code, include the following import statement in your Java source files: import static org.apache.camel.builder.sql.SqlBuilder.sql;

VARIABLES

Table 19.1, “ SQL variables” lists the variables that are accessible when using JoSQL.

T ab le 19 .1. SQ L variab les

371

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Name exchang e i n o ut

property header variable

T ype o rg . apache. camel . Exc hang e

The current Exchang e

o rg . apache. camel . Mes sag e

The IN messag e

o rg . apache. camel . Mes sag e

The O UT messag e

O bject

the Exchang e p ro p erty who se key is property

O bject

Descript ion

the IN messag e head er who se key is header the variab le who se key is

variable

EXAMPLE

Example 19.2, “ Route using JoSQL”

shows a route that uses JoSQL.

Examp le 19 .2. Ro u t e u sin g Jo SQ L

<route>

<language language= "sql" > select * from MyType </language>

</setBody>

</route>

</camelContext>

372

CHAPT ER 2 0 . JSO NPAT H

CHAPTER 20. JSONPATH

OVERVIEW

The JSonPath language provides a convenient syntax for extracting portions of a JSon message. The syntax of JSon is similar to XPath, but it is used to extract JSon objects from a

JSon message, instead of acting on XML. The jso npath DSL command can be used either as an expression or as a predicate (where an empty result gets interpreted as boolean

fal se).

ADDING T HE JSONPAT H PACKAGE

To use JSonPath in your Camel routes, you need to add a dependency on camel -

jso npath to your project, as follows:

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

<artifactId>camel-jsonpath</artifactId>

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

</dependency>

JAVA EXAMPLE

The following Java example shows how to use the jso npath() DSL command to select items in a certain price range: from("queue:books.new")

.choice()

.when().jsonpath("$.store.book[?(@ .price < 10)]")

.to("jms:queue:book.cheap")

.when().jsonpath("$.store.book[?(@ .price < 30)]")

.to("jms:queue:book.average")

.otherwise()

.to("jms:queue:book.expensive")

If the JSonPath query returns an empty set, the result is interpreted as fal se. In this way, you can use a JSonPath query as a predicate.

XML EXAMPLE

The following XML example shows how to use the jso npath DSL element to define predicates in a route:

<route>

373

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

<when>

<jsonpath>$.store.book[?(@ .price & lt; 10)]</jsonpath>

</when>

<when>

<jsonpath>$.store.book[?(@ .price & lt; 30)]</jsonpath>

</when>

</otherwise>

</choice>

</route>

</camelContext>

JSONPAT H INJECT ION

When using bean integration to invoke a bean method, you can use JSonPath to extract a value from the message and bind it to a method parameter. For example:

// Java public class Foo {

@ Consume(uri = "activemq:queue:books.new")

public void doSomething(@ JsonPath("$.store.book[*].author") String author, @ Body String json) {

// process the inbound message here

}

REFERENCE

For more details about JSonPath, see the JSonPath project page .

374

CHAPT ER 2 1 . JXPAT H

CHAPTER 21. JXPATH

OVERVIEW

The JXPath language enables you to invoke Java beans using the Apache Commons

JXPath language. The JXPath language has a similar syntax to XPath, but instead of selecting element or attribute nodes from an XML document, it invokes methods on an object graph of Java beans. If one of the bean attributes returns an XML document (a DOM/JDOM instance), however, the remaining portion of the path is interpreted as an XPath expression and is used to extract an XML node from the document. In other words, the JXPath language provides a hybrid of object graph navigation and XML node selection.

ADDING JXPAT H PACKAGE

To use JXPath in your routes you need to add a dependency on camel -jxpath to your

project as shown in Example 21.1, “ Adding the camel-jxpath dependency”

Examp le 21.1. Ad d in g t h e camel- jxp at h d ep en d en cy

<camel-version> 2.15.1.redhat-620133 </camel-version>

...

</properties>

...

<groupId> org.apache.camel

</groupId>

<artifactId> camel-jxpath </artifactId>

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

</dependency>

...

</dependencies>

VARIABLES

Table 21.1, “ JXPath variables”

lists the variables that are accessible when using JXPath.

T ab le 21.1. JXPat h variab les

Variable thi s

T ype Value o rg . apache. camel . Exc hang e

The current Exchang e

375

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Variable i n o ut

T ype Value o rg . apache. camel . Mes sag e

The IN messag e

o rg . apache. camel . Mes sag e

The O UT messag e

EXAMPLE

Example 21.2, “ Routes using JXPath” shows a route that use JXPath.

Examp le 21.2. Ro u t es u sin g JXPat h

<route>

<jxpath> in/body/name = 'James' </xpath>

</filter>

</route>

</camelContext>

376

CHAPT ER 2 2 . MVEL

CHAPTER 22. MVEL

OVERVIEW

MVEL is a Java-based dynamic language that is similar to OGNL, but is reported to be much faster. The MVEL support is in the camel -mvel module.

SYNT AX

You use the MVEL dot syntax to invoke Java methods, for example: getRequest().getBody().getFamilyName()

Because MVEL is dynamically typed, it is unnecessary to cast the message body instance (of

O bject type) before invoking the g etFami l yName() method. You can also use an abbreviated syntax for invoking bean attributes, for example: request.body.familyName

ADDING T HE MVEL MODULE

To use MVEL in your routes you need to add a dependency on camel -mvel to your project

as shown in Example 22.1, “ Adding the camel-mvel dependency” .

Examp le 22.1. Ad d in g t h e camel- mvel d ep en d en cy

<camel-version> 2.15.1.redhat-620133 </camel-version>

...

</properties>

...

<groupId> org.apache.camel

</groupId>

<artifactId> camel-mvel </artifactId>

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

</dependency>

...

</dependencies>

BUILT -IN VARIABLES

377

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Table 22.1, “ MVEL variables” lists the built-in variables that are accessible when using

MVEL.

T ab le 22.1. MVEL variab les

Name thi s exchang e excepti o n exchang eID faul t req uest respo nse pro perti es pro perty(name) pro perty(name, type)

T ype Descript ion o rg . apache. camel . Exc hang e

The current Exchang e

o rg . apache. camel . Exc hang e

The current Exchang e

T hro wabl e

the Exchang e excep tio n (if any)

Stri ng o rg . apache. camel . Mes sag e

the Exchang e ID

The Fault messag e(if any)

o rg . apache. camel . Mes sag e

The IN messag e

o rg . apache. camel . Mes sag e

The O UT messag e

Map

O bject

The Exchang e p ro p erties

The value o f the named

Exchang e p ro p erty

Type

The typ ed value o f the named Exchang e p ro p erty

EXAMPLE

Example 22.2, “ Route using MVEL”

shows a route that uses MVEL.

Examp le 22.2. Ro u t e u sin g MVEL

<route>

<language langauge= "mvel" > request.headers.foo ==

'bar' </language>

378

</filter>

</route>

</camelContext>

CHAPT ER 2 2 . MVEL

379

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 23. THE OBJECT-GRAPH NAVIGATION

LANGUAGE(OGNL)

OVERVIEW

OGNL is an expression language for getting and setting properties of Java objects. You use the same expression for both getting and setting the value of a property. The OGNL support is in the camel -o g nl module.

ADDING T HE OGNL MODULE

To use OGNL in your routes you need to add a dependency on camel -o g nl to your project

as shown in Example 23.1, “ Adding the camel-ognl dependency” .

Examp le 23.1. Ad d in g t h e camel- o g n l d ep en d en cy

...

...

<groupId> org.apache.camel

</groupId>

<artifactId> camel-ognl </artifactId>

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

</dependency>

...

</dependencies>

ST AT IC IMPORT

To use the o g nl () static method in your application code, include the following import statement in your Java source files: import static org.apache.camel.language.ognl.OgnlExpression.ognl;

BUILT -IN VARIABLES

Table 23.1, “ OGNL variables”

lists the built-in variables that are accessible when using

OGNL.

T ab le 23.1. O G NL variab les

380

CHAPT ER 2 3. T HE O BJECT - G RAPH NAVIG AT IO N LANG UAG E(O G NL)

Name thi s exchang e excepti o n exchang eID faul t req uest respo nse pro perti es pro perty(name) pro perty(name, type)

T ype Descript ion o rg . apache. camel . Exc hang e

The current Exchang e

o rg . apache. camel . Exc hang e

The current Exchang e

T hro wabl e

the Exchang e excep tio n (if any)

Stri ng o rg . apache. camel . Mes sag e

the Exchang e ID

The Fault messag e(if any)

o rg . apache. camel . Mes sag e

The IN messag e

o rg . apache. camel . Mes sag e

The O UT messag e

Map

O bject

The Exchang e p ro p erties

The value o f the named

Exchang e p ro p erty

Type

The typ ed value o f the named Exchang e p ro p erty

EXAMPLE

Example 23.2, “ Route using OGNL” shows a route that uses OGNL.

Examp le 23.2. Ro u t e u sin g O G NL

<route>

<language langauge= "ognl" > request.headers.foo ==

'bar' </language>

</filter>

</route>

</camelContext>

381

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 24. PHP

OVERVIEW

PHP is a widely-used general-purpose scripting language that is especially suited for Web development. The PHP support is part of the camel -scri pt module.

ADDING T HE SCRIPT MODULE

To use PHP in your routes you need to add a dependency on camel -scri pt to your

project as shown in Example 24.1, “ Adding the camel-script dependency”

Examp le 24 .1. Ad d in g t h e camel- scrip t d ep en d en cy

...

...

<groupId> org.apache.camel

</groupId>

<artifactId> camel-script </artifactId>

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

</dependency>

...

</dependencies>

382

ST AT IC IMPORT

To use the php() static method in your application code, include the following import statement in your Java source files: import static org.apache.camel.builder.camel.script.ScriptBuilder.*;

BUILT -IN AT T RIBUT ES

Table 24.1, “ PHP attributes”

lists the built-in attributes that are accessible when using PHP.

T ab le 24 .1. PHP at t rib u t es

At t ribut e co ntext

T ype Value o rg . apache. camel . C am el C o ntext

The Camel Co ntext

At t ribut e exchang e req uest respo nse pro perti es

CHAPT ER 2 4 . PHP

T ype Value o rg . apache. camel . Exc hang e

The current Exchang e

o rg . apache. camel . Mes sag e

The IN messag e

o rg . apache. camel . Mes sag e

The O UT messag e

o rg . apache. camel . bui l d er. scri pt. P ro perti esFuncti o n

Functio n with a

reso l ve

metho d to make it easier to use the p ro p erties co mp o nent insid e scrip ts.

The attributes all set at ENG INE_SC O P E.

EXAMPLE

Example 24.2, “ Route using PHP” shows a route that uses PHP.

Examp le 24 .2. Ro u t e u sin g PHP

<route>

<when>

<language language= "php" > strpos(request.headers.get('user'),

'admin')!== FALSE </language>

</when>

</otherwise>

</choice>

</route>

</camelContext>

USING T HE PROPERT IES COMPONENT

To access a property value from the properties component, invoke the reso l ve method on the built-in pro perti es attribute, as follows:

.setHeader("myHeader").php("properties.resolve(PropKey)")

383

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Where PropKey is the key of the property you want to resolve, where the key value is of

Stri ng type.

For more details about the properties component, see chapter "Properties" in "Apache Camel

Component Reference" .

384

CHAPT ER 2 5. EXCHANG E PRO PERT Y

CHAPTER 25. EXCHANGE PROPERTY

OVERVIEW

The exchange property language provides a convenient way of accessing exchange

properties. When you supply a key that matches one of the exchange property names, the exchange property language returns the corresponding value.

The exchange property language is part of camel -co re.

XML EXAMPLE

For example, to implement the recipient list pattern when the l i stO fEnd po i nts exchange property contains the recipient list, you could define a route as follows:

<route>

<exchangeProperty>listOfEndpoints</exchangeProperty>

</recipientList>

</route>

</camelContext>

JAVA EXAMPLE

The same recipient list example can be implemented in Java as follows: from("direct:a").recipientList(exchangeProperty("listOfEndpoints"));

385

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 26. PYTHON

OVERVIEW

Python is a remarkably powerful dynamic programming language that is used in a wide variety of application domains. Python is often compared to Tcl, Perl, Ruby, Scheme or

Java. The Python support is part of the camel -scri pt module.

ADDING T HE SCRIPT MODULE

To use Python in your routes you need to add a dependency on camel -scri pt to your

project as shown in Example 26.1, “ Adding the camel-script dependency” .

Examp le 26 .1. Ad d in g t h e camel- scrip t d ep en d en cy

...

...

<groupId> org.apache.camel

</groupId>

<artifactId> camel-script </artifactId>

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

</dependency>

...

</dependencies>

ST AT IC IMPORT

To use the pytho n() static method in your application code, include the following import statement in your Java source files: import static org.apache.camel.builder.camel.script.ScriptBuilder.*;

BUILT -IN AT T RIBUT ES

Table 26.1, “ Python attributes” lists the built-in attributes that are accessible when using

Python.

T ab le 26 .1. Pyt h o n at t rib u t es

386

At t ribut e co ntext exchang e req uest respo nse pro perti es

CHAPT ER 2 6 . PYT HO N

T ype Value o rg . apache. camel . C am el C o ntext

The Camel Co ntext

o rg . apache. camel . Exc hang e

The current Exchang e

o rg . apache. camel . Mes sag e

The IN messag e

o rg . apache. camel . Mes sag e

The O UT messag e

o rg . apache. camel . bui l d er. scri pt. P ro perti esFuncti o n

Functio n with a

reso l ve

metho d to make it easier to use the p ro p erties co mp o nent insid e scrip ts.

The attributes all set at ENG INE_SC O P E.

EXAMPLE

Example 26.2, “ Route using Python”

shows a route that uses Python.

Examp le 26 .2. Ro u t e u sin g Pyt h o n

<route>

<when>

<langauge langauge= "python" > if request.headers.get('user')

= 'admin' </langauge>

</when>

</otherwise>

</choice>

</route>

</camelContext>

USING T HE PROPERT IES COMPONENT

To access a property value from the properties component, invoke the reso l ve method on the built-in pro perti es attribute, as follows:

387

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

.setHeader("myHeader").python("properties.resolve(PropKey)")

Where PropKey is the key of the property you want to resolve, where the key value is of

Stri ng type.

For more details about the properties component, see chapter "Properties" in "Apache Camel

Component Reference" .

388

CHAPT ER 2 7 . REF

CHAPTER 27. REF

OVERVIEW

The Ref expression language is really just a way to look up a custom Expression from the

Registry . This is particular convenient to use in the XML DSL.

The Ref language is part of camel -co re.

ST AT IC IMPORT

To use the Ref language in your Java application code, include the following import statement in your Java source files: import static org.apache.camel.language.simple.RefLanguage.ref;

XML EXAMPLE

For example, the splitter pattern can reference a custom expression using the Ref language, as follows:

...

<route>

<split>

<ref>myExpressi o n</ref>

</split>

</route>

</camelContext>

</beans>

JAVA EXAMPLE

The preceding route can also be implemented in the Java DSL, as follows: from("seda:a")

.split().ref("myExpression")

.to("seda:b");

389

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 28. RUBY

OVERVIEW

Ruby is a dynamic, open source programming language with a focus on simplicity and productivity. It has an elegant syntax that is natural to read and easy to write. The Ruby support is part of the camel -scri pt module.

ADDING T HE SCRIPT MODULE

To use Ruby in your routes you need to add a dependency on camel -scri pt to your

project as shown in Example 28.1, “ Adding the camel-script dependency” .

Examp le 28.1. Ad d in g t h e camel- scrip t d ep en d en cy

...

...

<groupId> org.apache.camel

</groupId>

<artifactId> camel-script </artifactId>

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

</dependency>

...

</dependencies>

ST AT IC IMPORT

To use the ruby() static method in your application code, include the following import statement in your Java source files: import static org.apache.camel.builder.camel.script.ScriptBuilder.*;

BUILT -IN AT T RIBUT ES

Table 28.1, “ Ruby attributes”

lists the built-in attributes that are accessible when using Ruby.

T ab le 28.1. Ru b y at t rib u t es

At t ribut e T ype Value

390

At t ribut e co ntext exchang e req uest respo nse pro perti es

CHAPT ER 2 8 . RUBY

T ype Value o rg . apache. camel . C am el C o ntext

The Camel Co ntext

o rg . apache. camel . Exc hang e

The current Exchang e

o rg . apache. camel . Mes sag e

The IN messag e

o rg . apache. camel . Mes sag e

The O UT messag e

o rg . apache. camel . bui l d er. scri pt. P ro perti esFuncti o n

Functio n with a

reso l ve

metho d to make it easier to use the p ro p erties co mp o nent insid e scrip ts.

The attributes all set at ENG INE_SC O P E.

EXAMPLE

Example 28.2, “ Route using Ruby”

shows a route that uses Ruby.

Examp le 28.2. Ro u t e u sin g Ru b y

<route>

<when>

<langauge langauge= "ruby" > $request.headers['user'] ==

'admin' </langauge>

</when>

</otherwise>

</choice>

</route>

</camelContext>

USING T HE PROPERT IES COMPONENT

To access a property value from the properties component, invoke the reso l ve method on the built-in pro perti es attribute, as follows:

391

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

.setHeader("myHeader").ruby("properties.resolve(PropKey)")

Where PropKey is the key of the property you want to resolve, where the key value is of

Stri ng type.

For more details about the properties component, see chapter "Properties" in "Apache Camel

Component Reference" .

392

CHAPT ER 2 9 . T HE SIMPLE LANG UAG E

CHAPTER 29. THE SIMPLE LANGUAGE

Ab st ract

The simple language is a language that was developed in Apache Camel specifically for the purpose of accessing and manipulating the various parts of an exchange object. The language is not quite as simple as when it was originally created and it now features a comprehensive set of logical operators and conjunctions.

29.1. JAVA DSL

Simple expressions in Java DSL

In the Java DSL, there are two styles for using the si mpl e() command in a route. You can either pass the si mpl e() command as an argument to a processor, as follows: from("seda:order")

.filter(simple("${in.header.foo}"))

.to("mock:fooOrders");

Or you can call the si mpl e() command as a sub-clause on the processor, for example: from("seda:order")

.filter()

.simple("${in.header.foo}")

.to("mock:fooOrders");

Embedding in a st ring

If you are embedding a simple expression inside a plain text string, you must use the placeholder syntax, ${Expression}. For example, to embed the i n. head er. name expression in a string: simple("Hello ${in.header.name}, how are you?")

Cust omiz ing t he st art and end t okens

From Java, you can customize the start and end tokens ({ and }, by default) by calling the

chang eFuncti o nStartT o ken static method and the chang eFuncti o nEnd T o ken static method on the Si mpl eLang uag e object.

For example, you can change the start and end tokens to [ and ] in Java, as follows:

// Java import org.apache.camel.language.simple.SimpleLanguage;

...

SimpleLanguage.changeFunctionStartToken("[");

393

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

SimpleLanguage.changeFunctionEndToken("]");

No t e

Customizing the start and end tokens affects all Apache Camel applications that share the same camel -co re library on their classpath. For example, in an OSGi server this might affect many applications; whereas in a Web application (WAR file) it would affect only the Web application itself.

29.2. XML DSL

Simple expressions in XML DSL

In the XML DSL, you can use a simple expression by putting the expression inside a si mpl e element. For example, to define a route that performs filtering based on the contents of the

fo o header:

<simple>${in.header.foo}</simple>

</filter>

</route>

Alt ernat ive placeholder synt ax

Sometimes—for example, if you have enabled Spring property placeholders or OSGi blueprint property placeholders—you might find that the ${Expression} syntax clashes with another property placeholder syntax. In this case, you can disambiguate the placeholder using the alternative syntax, $si mpl e{Expression}, for the simple expression. For example:

<simple>Hello $simple{in.header.name}, how are you?</simple>

Cust omiz ing t he st art and end t okens

From XML configuration, you can customize the start and end tokens ({ and }, by default) by overriding the Si mpl eLang uag e instance. For example, to change the start and end tokens to [ and ], define a new Si mpl eLang uag e bean in your XML configuration file, as follows:

<constructor-arg name="functionStartToken" value="["/>

<constructor-arg name="functionEndToken" value="]"/>

</bean>

394

CHAPT ER 2 9 . T HE SIMPLE LANG UAG E

No t e

Whit espace and aut o-t rim in XML DSL

By default, whitespace preceding and following a simple expression is automatically trimmed in XML DSL. So this expression with surrounding whitespace:

data=${body}

</simple>

</transform> is automatically trimmed, so that it is equivalent to this expression (no surrounding whitespace):

</transform>

If you want to include newlines before or after the expression, you can either explicitly add a newline character, as follows:

</transform> or you can switch off auto-trimming, by setting the tri m attribute to fal se, as follows:

<simple>data=${body}

</simple>

</transform>

29.3. INVOKING AN EXT ERNAL SCRIPT

Overview

It is possible to execute Simple scripts that are stored in an external resource, as described here.

395

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Synt ax for script resource

Use the following syntax to access a Simple script that is stored as an external resource: resource:Scheme:Location

Where the Scheme: can be either cl asspath: , fi l e: , or http: .

For example, to read the mysi mpl e. txt script from the classpath, simple("resource:classpath:mysimple.txt")

29.4 . EXPRESSIONS

Overview

The simple language provides various elementary expressions that return different parts of a message exchange. For example, the expression, si mpl e("${head er. ti meO fD ay}"), would return the contents of a header called ti meO fD ay from the incoming message.

No t e

Since Apache Camel 2.9, you must always use the placeholder syntax,

${Expression}, to return a variable value. It is never permissible to omit the enclosing tokens (${ and }).

Cont ent s of a single variable

You can use the simple language to define string expressions, based on the variables provided. For example, you can use a variable of the form, i n. head er. HeaderName, to obtain the value of the HeaderName header, as follows: simple("${in.header.foo}")

Variables embedded in a st ring

You can embed simple variables in a string expression—for example: simple("Received a message from ${in.header.user} on

${date:in.header.date:yyyyMMdd}.")

dat e and bean variables

396

CHAPT ER 2 9 . T HE SIMPLE LANG UAG E

As well as providing variables that access all of the different parts of an exchange (see

Table 29.1, “ Variables for the Simple Language”

), the simple language also provides special variables for formatting dates, d ate: command: pattern, and for calling bean methods,

bean: beanRef. For example, you can use the date and the bean variables as follows: simple("Todays date is ${date:now:yyyyMMdd}") simple("The order type is ${bean:orderService?method=getOrderType}")

Specifying t he result t ype

You can specify the result type of an expression explicitly. This is mainly useful for converting the result type to a boolean or numerical type.

In the Java DSL, specify the result type as an extra argument to si mpl e(). For example, to return an integer result, you could evaluate a simple expression as follows:

...

.setHeader("five", simple("5", Integ er. cl ass))

In the XML DSL, specify the result type using the resul tT ype attribute. For example:

</setHeader>

Nest ed expressions

Simple expressions can be nested—for example: simple("${header.${bean:headerChooser?method=whichHeader}}")

Accessing const ant s or enums

You can access a bean's constant or enum fields using the following syntax: type:ClassName.Field

For example, consider the following Java enum type: package org.apache.camel.processor;

...

public enum Customer {

GOLD, SILVER, BRONZE

}

397

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

You can access the C usto mer enum fields, as follows:

from("direct:start")

.choice()

.when().simple("${header.customer} ==

${type:org.apache.camel.processor.Customer.GOLD}")

.to("mock:gold")

.when().simple("${header.customer} ==

${type:org.apache.camel.processor.Customer.SILVER}")

.to("mock:silver")

.otherwise()

.to("mock:other");

OGNL expressions

The Object Graph Navigation Language (OGNL) is a notation for invoking bean methods in a chain-like fashion. If a message body contains a Java bean, you can easily access its bean properties using OGNL notation. For example, if the message body is a Java object with a g etAd d ress() accessor, you can access the Ad d ress object and the Ad d ress object's properties as follows: simple("${body.address}") simple("${body.address.street}") simple("${body.address.zip}") simple("${body.address.city}")

Where the notation, ${bo d y. ad d ress. street}, is shorthand for

${bo d y. g etAd d ress. g etStreet}.

OGNL null-safe operat or

You can use the null-safe operator, ?. , to avoid encountering null-pointer exceptions, in case the body does not have an address. For example: simple("${body?.address?.street}")

If the body is a java. uti l . Map type, you can look up a value in the map with the key, fo o , using the following notation: simple("${body[foo]?.name}")

398

OGNL list element access

You can also use square brackets notation, [k], to access the elements of a list. For example: simple("${body.address.lines[0]}") simple("${body.address.lines[1]}") simple("${body.address.lines[2]}")

CHAPT ER 2 9 . T HE SIMPLE LANG UAG E

The l ast keyword returns the index of the last element of a list. For example, you can access the second last element of a list, as follows: simple("${body.address.lines[last-1]}")

You can use the si ze method to query the size of a list, as follows: simple("${body.address.lines.size}")

OGNL array lengt h access

You can access the length of a Java array through the l eng th method, as follows:

String[] lines = new String[]{"foo", "bar", "cat"}; exchange.getIn().setBody(lines); simple("There are ${body.length} lines")

29.5. PREDICAT ES

Overview

You can construct predicates by testing expressions for equality. For example, the predicate,

si mpl e("${head er. ti meO fD ay} = = ' 14 : 30 ' "), tests whether the ti meO fD ay header in the incoming message is equal to 14 : 30 .

In addition, whenever the resul tT ype is specified as a Boolean the expression is evaluated as a predicate instead of an expression. This allows the predicate syntax to be used for these expressions.

Synt ax

You can also test various parts of an exchange (headers, message body, and so on) using simple predicates. Simple predicates have the following general syntax:

${LHSVariable} Op RHSValue

Where the variable on the left hand side, LHSVariable, is one of the variables shown in

Table 29.1, “ Variables for the Simple Language”

and the value on the right hand side,

RHSValue, is one of the following:

Another variable, ${RHSVariable}.

A string literal, enclosed in single quotes, ' ' .

A numeric constant, enclosed in single quotes, ' ' .

399

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

The null object, nul l .

The simple language always attempts to convert the RHS value to the type of the LHS value.

No t e

While the simple language will attempt to convert the RHS, depending on the operator the LHS may need to be cast into the appropriate Type before the comparison is made.

Examples

For example, you can perform simple string comparisons and numerical comparisons as follows: simple("${in.header.user} == 'john'") simple("${in.header.number} > '100'") // String literal can be converted to integer

You can test whether the left hand side is a member of a comma-separated list, as follows: simple("${in.header.type} in 'gold,silver'")

You can test whether the left hand side matches a regular expression, as follows: simple("${in.header.number} regex '\d{4}'")

You can test the type of the left hand side using the i s operator, as follows: simple("${in.header.type} is 'java.lang.String'") simple("${in.header.type} is 'String'") // You can abbreviate java.lang. types

You can test whether the left hand side lies in a specified numerical range (where the range is inclusive), as follows: simple("${in.header.number} range '100..199'")

Conjunct ions

You can also combine predicates using the logical conjunctions, & & and | | .

For example, here is an expression using the & & conjunction (logical and):

4 00

CHAPT ER 2 9 . T HE SIMPLE LANG UAG E

simple("${in.header.title} contains 'Camel' & & ${in.header.type} ==

'gold'")

And here is an expression using the | | conjunction (logical inclusive or): simple("${in.header.title} contains 'Camel' || ${in.header.type} ==

'gold'")

29.6. VARIABLE REFERENCE

T able of variables

Table 29.1, “ Variables for the Simple Language”

shows all of the variables supported by the simple language.

T ab le 29 .1. Variab les f o r t h e Simp le Lan g u ag e

Variable camel C o ntext camel Id exchang eId i d bo d y

T ype

O bject

Stri ng

O bject

Descript ion

The Camel co ntext. Supports

OGNL expressions.

The Camel co ntext's ID value.

The exchang e's ID value.

The In messag e ID value.

i n. bo d y o ut. bo d y

O bject

The In messag e b o d y.

Supports OGNL expressions.

The In messag e b o d y.

Supports OGNL expressions.

bo d yAs(Type)

Type

The Out messag e b o d y.

The In messag e b o d y, co nverted to the sp ecified typ e. All typ es, Type, must b e sp ecified using their fullyq ualified Java name, excep t fo r the typ es:

byte[]

Stri ng

Integ er

, and

Lo ng

. The co nverted b o d y can b e null.

4 01

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Variable mand ato ryBo d yAs(Type

)

T ype

Type

head er.

head er[ head ers.

head ers[ i n. head er.

i n. head er[

HeaderName

i n. head ers.

i n. head ers[

] o ut. head er.

o ut. head er[

]

HeaderName

]

HeaderName

]

HeaderName

O bject

Descript ion

The In messag e b o d y, co nverted to the sp ecified typ e. All typ es, Type, must b e sp ecified using their fullyq ualified Java name, excep t fo r the typ es:

byte[]

Stri ng

Integ er

, and

Lo ng

. The co nverted b o d y is exp ected to b e no n-null.

The In messag e's

HeaderName head er.

Supports OGNL expressions.

The In messag e's

HeaderName head er

(alternative syntax).

The In messag e's

HeaderName head er.

The In messag e's

HeaderName head er

(alternative syntax).

The In messag e's

HeaderName head er.

Supports OGNL expressions.

The In messag e's

HeaderName head er

(alternative syntax).

The In messag e's

HeaderName head er.

Supports OGNL expressions.

The In messag e's

HeaderName head er

(alternative syntax).

The Out messag e's

HeaderName head er.

The Out messag e's

HeaderName head er

(alternative syntax).

4 02

Variable o ut. head ers.

HeaderNam e

o ut. head ers[

HeaderNam e

]

T ype

O bject

O bject head erAs(Key,Type)

Type

head ers i n. head ers pro perty.

PropertyName

Map

O bject pro perty[

PropertyName

] O bject sys.

SysPropertyName

sysenv.

SysEnvVar

excepti o n

Stri ng

CHAPT ER 2 9 . T HE SIMPLE LANG UAG E

Descript ion

The Out messag e's

HeaderName head er.

The Out messag e's

HeaderName head er

(alternative syntax).

The Key head er, co nverted to the sp ecified typ e. All typ es, Type, must b e sp ecified using their fullyq ualified Java name, excep t fo r the typ es:

byte[]

Stri ng

Integ er

, and

Lo ng

. The co nverted value can b e null.

All o f the In head ers (as a

java. uti l . Map

typ e).

All o f the In head ers (as a

java. uti l . Map

typ e).

The PropertyName p ro p erty o n the exchang e.

The PropertyName p ro p erty o n the exchang e (alternative syntax).

The SysPropertyName Java system p ro p erty.

The SysEnvVar system enviro nment variab le.

Either the excep tio n o b ject fro m

Exchang e. g etExcepti o n()

o r, if this value is null, the caug ht excep tio n fro m the

Exchang e. EXC EP T IO N_

C AUG HT

p ro p erty; o therwise null. Supports OGNL

expressions.

4 03

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Variable excepti o n. messag e

T ype

Stri ng excepti o n. stacktrace d ate:

command

pattern

bean: beanID. Method

Stri ng

O bject

Descript ion

If an excep tio n is set o n the exchang e, returns the value o f

Excepti o n. g etMessag e

()

; o therwise, returns

nul l

If an excep tio n is set o n the exchang e, returns the value o f

Excepti o n. g etStackT r ace()

; o therwise, returns

nul l

. Not e: The simp le lang uag e first tries to retrieve an excep tio n fro m

Exchang e. g etExcepti o n()

. If that p ro p erty is no t set, it checks fo r a caug ht excep tio n, b y calling

Exchang e. g etP ro perty

(Exchang e. C AUG HT _EXC

EP T IO N)

A d ate fo rmatted using a java.text.Simp leDateFo rmat p attern. The fo llo wing co mmand s are sup p o rted :

no w

, fo r the current d ate and time;

head er.

HeaderName, o r

i n. head er.

HeaderName

to use a java.util.Date

o b ject in the HeaderName head er fro m the In messag e;

o ut. head er.

HeaderName

to use a java.util.Date

o b ject in the HeaderName head er fro m the Out messag e;

Invo kes a metho d o n the referenced b ean and returns

the result of the method

invocation. To sp ecify a metho d name, yo u can either use the

beanID. Method

syntax; o r yo u can use the

beanID?

metho d =

methodName

syntax.

4 04

CHAPT ER 2 9 . T HE SIMPLE LANG UAG E

Variable ref: beanID pro perti es: Key pro perti es: Location:

Key

Stri ng thread Name ro uteId type: Name[. Field]

T ype

O bject

Stri ng

O bject

Descript ion

Lo o ks up the b ean with the

ID, beanID, in the reg istry and returns a reference to the

bean itself. Fo r examp le, if yo u are using the sp litter

EIP, yo u co uld use this variab le to reference the b ean that imp lements the sp litting alg o rithm.

The value o f the Key p ro p erty p laceho ld er (see

Sectio n 2.7, “ Pro p erty

Placeho ld ers” ).

The value o f the Key p ro p erty p laceho ld er, where the lo catio n o f the p ro p erties file is g iven b y Location (see

Sectio n 2.7, “ Pro p erty

Placeho ld ers” ).

The name o f the current thread .

Returns the ID o f the current ro ute thro ug h which the

Exchang e

is b eing ro uted .

References a typ e o r field b y its Fully-Q ualified -Name

(FQ N). To refer to a field , ap p end

. Field

. Fo r examp le, yo u can refer to the

FILE_NAME

co nstant field fro m the

Exchang e

class as

type: o rg . apache. came l . Exchang e. FILE_NAME

29.7. OPERAT OR REFERENCE

Binary operat ors

The binary operators for simple language predicates are shown in Table 29.2, “ Binary

Operators for the Simple Language” .

T ab le 29 .2. Bin ary O p erat o rs f o r t h e Simp le Lan g u ag e

4 05

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

O perat or

= =

! = co ntai ns no t co ntai ns reg ex no t reg ex i n no t i n i s no t i s rang e no t rang e

Descript ion

Eq uals.

G reater than.

G reater than o r eq uals.

Less than.

Less than o r eq uals.

No t eq ual to .

Test if LHS string co ntains RHS string .

Test if LHS string d o es not co ntain RHS string .

Test if LHS string matches RHS reg ular exp ressio n.

Test if LHS string d o es not match RHS reg ular exp ressio n.

Test if LHS string ap p ears in the RHS co mma-sep arated list.

Test if LHS string d o es not ap p ear in the

RHS co mma-sep arated list.

Test if LHS is an instance o f RHS Java typ e

(using Java

i nstanceo f

o p erato r).

Test if LHS is not an instance o f RHS Java typ e (using Java

i nstanceo f

o p erato r).

Test if LHS numb er lies in the RHS rang e

(where rang e has the fo rmat,

min

. . .

max

Test if LHS numb er d o es not lie in the RHS rang e (where rang e has the fo rmat,

min

. . .

max

Unary operat ors and charact er escapes

The binary operators for simple language predicates are shown in Table 29.3, “ Unary

Operators for the Simple Language” .

4 06

T ab le 29 .3. Un ary O p erat o rs f o r t h e Simp le Lan g u ag e

O perat or

+ +

CHAPT ER 2 9 . T HE SIMPLE LANG UAG E

Descript ion

Increment a numb er b y 1.

Decrement a numb er b y 1.

The newline character.

The carriag e return character.

The tab character.

(Obsolete) Since Camel versio n 2.11, the b ackslash escap e character is no t sup p o rted .

Combining predicat es

The conjunctions shown in

Table 29.4, “ Conjunctions for Simple Language Predicates”

can be used to combine two or more simple language predicates.

T ab le 29 .4 . Co n ju n ct io n s f o r Simp le Lan g u ag e Pred icat es

O perat or

& &

| | and o r

Descript ion

Co mb ine two p red icates with lo g ical and.

Co mb ine two p red icates with lo g ical inclusive

or.

Deprecated. Use

& &

instead .

Deprecated. Use

| |

instead .

4 07

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 30. SPEL

OVERVIEW

The Spring Expression Language (SpEL) is an object graph navigation language provided with Spring 3, which can be used to construct predicates and expressions in a route. A notable feature of SpEL is the ease with which you can access beans from the registry.

SYNT AX

The SpEL expressions must use the placeholder syntax, #{SpelExpression}, so that they can be embedded in a plain text string (in other words, SpEL has expression templating enabled).

SpEL can also look up beans in the registry (typically, the Spring registry), using the

@ BeanID syntax. For example, given a bean with the ID, head erUti l s, and the method,

co unt() (which counts the number of headers on the current message), you could use the

head erUti l s bean in an SpEL predicate, as follows:

#{@ headerUtils.count > 4}

ADDING SPEL PACKAGE

To use SpEL in your routes you need to add a dependency on camel -spri ng to your

project as shown in Example 30.1, “ Adding the camel-spring dependency”

Examp le 30.1. Ad d in g t h e camel- sp rin g d ep en d en cy

<camel-version> 2.15.1.redhat-620133 </camel-version>

...

</properties>

...

<groupId> org.apache.camel

</groupId>

<artifactId> camel-spring </artifactId>

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

</dependency>

...

</dependencies>

4 08

VARIABLES

CHAPT ER 30 . SPEL

Table 30.1, “ SpEL variables”

lists the variables that are accessible when using SpEL.

T ab le 30.1. Sp EL variab les

Variable thi s exchang e exchang eId excepti o n faul t req uest respo nse

T ype

Exchang e

Stri ng

T hro wabl e

Messag e

Messag e pro perti es pro perty(Name)

Map

O bject pro perty(Name, Type) T ype

Descript ion

The current exchang e is the ro o t o b ject.

The current exchang e.

The current exchang e's ID.

The exchang e excep tio n (if any).

The fault messag e (if any).

The exchang e's In messag e.

The exchang e's Out messag e (if any).

The exchang e p ro p erties.

The exchang e p ro p erty keyed b y Name.

The exchang e p ro p erty keyed b y Name, co nverted to the typ e, Type.

XML EXAMPLE

For example, to select only those messages whose C o untry header has the value USA, you can use the following SpEL expression:

<route>

<spel>#{request.headers['Country'] == 'USA'}}</spel>

</filter>

</route>

JAVA EXAMPLE

You can define the same route in the Java DSL, as follows:

4 09

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

from("SourceURL")

.filter().spel("#{request.headers['Country'] == 'USA'}")

.to("TargetURL");

The following example shows how to embed SpEL expressions within a plain text string: from("SourceURL")

.setBody(spel("Hello #{request.body}! What a beautiful #

{request.headers['dayOrNight']}"))

.to("TargetURL");

4 10

CHAPT ER 31 . T HE XPAT H LANG UAG E

CHAPTER 31. THE XPATH LANGUAGE

Ab st ract

When processing XML messages, the XPath language enables you to select part of a message, by specifying an XPath expression that acts on the message's Document Object

Model (DOM). You can also define XPath predicates to test the contents of an element or an attribute.

31.1. JAVA DSL

Basic expressions

You can use xpath("Expression") to evaluate an XPath expression on the current exchange (where the XPath expression is applied to the body of the current In message). The result of the xpath() expression is an XML node (or node set, if more than one node matches).

For example, to extract the contents of the /perso n/name element from the current In message body and use it to set a header named user, you could define a route like the following: from("queue:foo")

.setHeader("user", xpath("/person/name/text()"))

.to("direct:tie");

Instead of specifying xpath() as an argument to setHead er(), you can use the fluent builder xpath() command—for example: from("queue:foo")

.setHeader("user").xpath("/person/name/text()")

.to("direct:tie");

If you want to convert the result to a specific type, specify the result type as the second argument of xpath(). For example, to specify explicitly that the result type is Stri ng : xpath("/person/name/text()", String.class)

Namespaces

Typically, XML elements belong to a schema, which is identified by a namespace URI. When processing documents like this, it is necessary to associate namespace URIs with prefixes, so that you can identify element names unambiguously in your XPath expressions. Apache

Camel provides the helper class, o rg . apache. camel . bui l d er. xml . Namespaces, which enables you to define associations between namespaces and prefixes.

4 11

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

For example, to associate the prefix, cust, with the namespace,

http: //acme. co m/custo mer/reco rd , and then extract the contents of the element,

/cust: perso n/cust: name, you could define a route like the following: import org.apache.camel.builder.xml.Namespaces;

...

Namespaces ns = new Namespaces("cust",

"http://acme.com/customer/record"); from("queue:foo")

.setHeader("user", xpath("/cust:person/cust:name/text()", ns))

.to("direct:tie");

Where you make the namespace definitions available to the xpath() expression builder by passing the Namespaces object, ns, as an additional argument. If you need to define multiple namespaces, use the Namespace. ad d () method, as follows: import org.apache.camel.builder.xml.Namespaces;

...

Namespaces ns = new Namespaces("cust",

"http://acme.com/customer/record"); ns.add("inv", "http://acme.com/invoice"); ns.add("xsi", "http://www.w3.org/2001/XMLSchema-instance");

If you need to specify the result type and define namespaces, you can use the three-argument form of xpath(), as follows: xpath("/person/name/text()", String.class, ns)

Audit ing namespaces

One of the most frequent problems that can occur when using XPath expressions is that there is a mismatch between the namespaces appearing in the incoming messages and the namespaces used in the XPath expression. To help you troubleshoot this kind of problem, the XPath language supports an option to dump all of the namespaces from all of the incoming messages into the system log.

To enable namespace logging at the INFO log level, enable the l o g Namespaces option in the Java DSL, as follows: xpath("/foo:person/@ id", String.class).logNamespaces()

Alternatively, you could configure your logging system to enable T R AC E level logging on the

o rg . apache. camel . bui l d er. xml . XP athBui l d er logger.

When namespace logging is enabled, you will see log messages like the following for each processed message:

4 12

CHAPT ER 31 . T HE XPAT H LANG UAG E

2012-01-16 13:23:45,878 [stSaxonWithFlag] INFO XPathBuilder -

Namespaces discovered in message: {xmlns:a=[http://apache.org/camel],

DEFAULT=[http://apache.org/default], xmlns:b=[http://apache.org/camelA, http://apache.org/camelB]}

31.2. XML DSL

Basic expressions

To evaluate an XPath expression in the XML DSL, put the XPath expression inside an xpath element. The XPath expression is applied to the body of the current In message and returns an XML node (or node set). Typically, the returned XML node is automatically converted to a string.

For example, to extract the contents of the /perso n/name element from the current In message body and use it to set a header named user, you could define a route like the following:

<route>

<xpath>/person/name/text()</xpath>

</setHeader>

</route>

</camelContext>

</beans>

If you want to convert the result to a specific type, specify the result type by setting the

resul tT ype attribute to a Java type name (where you must specify the fully-qualified type name). For example, to specify explicitly that the result type is java. l ang . Stri ng (you can omit the java. l ang . prefix here):

<xpath resultType="String">/person/name/text()</xpath>

Namespaces

When processing documents whose elements belong to one or more XML schemas, it is typically necessary to associate namespace URIs with prefixes, so that you can identify element names unambiguously in your XPath expressions. It is possible to use the standard

XML mechanism for associating prefixes with namespace URIs. That is, you can set an attribute like this: xml ns: Prefix= "NamespaceURI".

4 13

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

For example, to associate the prefix, cust, with the namespace,

http: //acme. co m/custo mer/reco rd , and then extract the contents of the element,

/cust: perso n/cust: name, you could define a route like the following:

<camelContext xmlns="http://camel.apache.org/schema/spring"

xml ns: cust= "http: //acme. co m/custo mer/reco rd " >

<route>

<xpath>/cust:person/cust:name/text()</xpath>

</setHeader>

</route>

</camelContext>

</beans>

Audit ing namespaces

To enable namespace logging at the INFO log level, enable the l o g Namespaces option in the XML DSL, as follows:

<xpath logNamespaces="true" resultType="String">/foo:person/@ id</xpath>

Alternatively, you could configure your logging system to enable T R AC E level logging on the

o rg . apache. camel . bui l d er. xml . XP athBui l d er logger.

When namespace logging is enabled, you will see log messages like the following for each processed message:

2012-01-16 13:23:45,878 [stSaxonWithFlag] INFO XPathBuilder -

Namespaces discovered in message: {xmlns:a=[http://apache.org/camel],

DEFAULT=[http://apache.org/default], xmlns:b=[http://apache.org/camelA, http://apache.org/camelB]}

31.3. XPAT H INJECT ION

Paramet er binding annot at ion

4 14

CHAPT ER 31 . T HE XPAT H LANG UAG E

When using Apache Camel bean integration to invoke a method on a Java bean, you can use the @ XP ath annotation to extract a value from the exchange and bind it to a method parameter.

For example, consider the following route fragment, which invokes the cred i t method on an

Acco untServi ce object: from("queue:payments")

.beanRef("accountService","credit")

...

The cred i t method uses parameter binding annotations to extract relevant data from the message body and inject it into its parameters, as follows: public class AccountService {

...

public void credit(

@ XPath("/transaction/transfer/receiver/text()") String name,

@ XPath("/transaction/transfer/amount/text()") String amount

)

{

...

}

...

}

For more information about bean integration, see Section 2.4, “ Bean Integration”

Namespaces

Table 31.1, “ Predefined Namespaces for @XPath” shows the namespaces that are

predefined for XPath. You can use these namespace prefixes in the XP ath expression that appears in the @ XP ath annotation.

T ab le 31.1. Pred ef in ed Namesp aces f o r @ XPat h

Namespace URI http: //www. w3. o rg /20 0 1/XMLSchem a http: //www. w3. o rg /20 0 3/0 5/so apenvel o pe

Prefix xsd so ap

Cust om namespaces

4 15

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

You can use the @ NamespaceP refi x annotation to define custom XML namespaces.

Invoke the @ NamespaceP refi x annotation to initialize the namespaces argument of the

@ XP ath annotation. The namespaces defined by @ NamespaceP refi x can then be used in the @ XP ath annotation's expression value.

For example, to associate the prefix, ex, with the custom namespace,

http: //fuseso urce. co m/exampl es, invoke the @ XP ath annotation as follows: public class AccountService {

...

public void credit(

@ XPath(

value = "/ex:transaction/ex:transfer/ex:receiver/text()",

namespaces = @ NamespaceP refi x(

prefi x = "ex",

uri = "http: //fuseso urce. co m/exampl es"

)

) String name,

@ XPath(

value = "/ex:transaction/ex:transfer/ex:amount/text()",

namespaces = @ NamespaceP refi x(

prefi x = "ex",

uri = "http: //fuseso urce. co m/exampl es"

)

) String amount,

)

{

...

}

...

}

31.4 . XPAT H BUILDER

Overview

The o rg . apache. camel . bui l d er. xml . XP athBui l d er class enables you to evaluate

XPath expressions independently of an exchange. That is, if you have an XML fragment from any source, you can use XP athBui l d er to evaluate an XPath expression on the XML fragment.

Mat ching expressions

Use the matches() method to check whether one or more XML nodes can be found that match the given XPath expression. The basic syntax for matching an XPath expression using XP athBui l d er is as follows: boolean matches = XPathBuilder

.xpath("Expression")

.matches(CamelContext, "XMLString");

4 16

CHAPT ER 31 . T HE XPAT H LANG UAG E

Where the given expression, Expression, is evaluated against the XML fragment, XMLString, and the result is true, if at least one node is found that matches the expression. For example, the following example returns true, because the XPath expression finds a match in the xyz attribute.

boolean matches = XPathBuilder

.xpath("/foo/bar/@ xyz")

.matches(getContext(), "<foo><bar xyz='cheese'/>

</foo>"));

Evaluat ing expressions

Use the eval uate() method to return the contents of the first node that matches the given

XPath expression. The basic syntax for evaluating an XPath expression using

XP athBui l d er is as follows:

String nodeValue = XPathBuilder

.xpath("Expression")

.evaluate(CamelContext, "XMLString");

You can also specify the result type by passing the required type as the second argument to

eval uate()—for example:

String name = XPathBuilder

.xpath("foo/bar")

.evaluate(context, "<foo><bar>cheese</bar></foo>",

String.class);

Integer number = XPathBuilder

.xpath("foo/bar")

.evaluate(context, "<foo><bar>123</bar></foo>",

Integer.class);

Boolean bool = XPathBuilder

.xpath("foo/bar")

.evaluate(context, "<foo><bar>true</bar></foo>",

Boolean.class);

31.5. ENABLING SAXON

Prerequisit es

A prerequisite for using the Saxon parser is that you add a dependency on the camel -

saxo n artifact (either adding this dependency to your Maven POM, if you use Maven, or adding the camel -saxo n-6 . 2. 0 . red hat-133. jar file to your classpath, otherwise).

Using t he Saxon parser in Java DSL

In Java DSL, the simplest way to enable the Saxon parser is to call the saxo n() fluent builder method. For example, you could invoke the Saxon parser as shown in the following example:

4 17

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

// Java

// create a builder to evaluate the xpath using saxon

XPathBuilder builder = XPathBuilder.xpath("tokenize(/foo/bar, '_')

[2]").saxon();

// evaluate as a String result

String result = builder.evaluate(context, "<foo><bar>abc_def_ghi</bar>

</foo>");

Using t he Saxon parser in XML DSL

In XML DSL, the simplest way to enable the Saxon parser is to set the saxo n attribute to true in the xpath element. For example, you could invoke the Saxon parser as shown in the following example:

<xpath saxon="true" resultType="java.lang.String">current-dateTime()

</xpath>

Programming wit h Saxon

If you want to use the Saxon XML parser in your application code, you can create an instance of the Saxon transformer factory explicitly using the following code:

// Java

import javax.xml.transform.TransformerFactory; import net.sf.saxon.TransformerFactoryImpl;

...

TransformerFactory saxonFactory = new net.sf.saxon.TransformerFactoryImpl();

On the other hand, if you prefer to use the generic JAXP API to create a transformer factory instance, you must first set the javax. xml . transfo rm. T ransfo rmerFacto ry property in the ESBInstall/etc/system. pro perti es file, as follows: javax.xml.transform.TransformerFactory=net.sf.saxon.TransformerFactory

Impl

You can then instantiate the Saxon factory using the generic JAXP API, as follows:

// Java

import javax.xml.transform.TransformerFactory;

...

TransformerFactory factory = TransformerFactory.newInstance();

If your application depends on any third-party libraries that use Saxon, it might be necessary to use the second, generic approach.

4 18

CHAPT ER 31 . T HE XPAT H LANG UAG E

No t e

The Saxon library must be installed in the container as the OSGi bundle,

net. sf. saxo n/saxo n9 he (normally installed by default). In versions of Fuse

ESB prior to 7.1, it is not possible to load Saxon using the generic JAXP API.

31.6. EXPRESSIONS

Result t ype

By default, an XPath expression returns a list of one or more XML nodes, of

o rg . w3c. d o m. No d eLi st type. You can use the type converter mechanism to convert the result to a different type, however. In the Java DSL, you can specify the result type in the second argument of the xpath() command. For example, to return the result of an XPath expression as a Stri ng : xpath("/person/name/text()", String.class)

In the XML DSL, you can specify the result type in the resul tT ype attribute, as follows:

<xpath resultType="java.lang.String">/person/name/text()</xpath>

Pat t erns in locat ion pat hs

You can use the following patterns in XPath location paths:

/peo pl e/perso n

The basic location path specifies the nested location of a particular element. That is, the preceding location path would match the person element in the following XML fragment:

</people>

Note that this basic pattern can match multiple nodes—for example, if there is more than one perso n element inside the peo pl e element.

/name/text()

If you just want to access the text inside by the element, append /text() to the location path, otherwise the node includes the element's start and end tags (and these tags would be included when you convert the node to a string).

/perso n/tel epho ne/@ i sD ayT i me

4 19

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

To select the value of an attribute, AttributeName, use the syntax @ AttributeName.

For example, the preceding location path returns true when applied to the following

XML fragment:

</person>

A wildcard that matches all elements in the specified scope. For example,

/peo pl e/perso n/* matches all the child elements of perso n.

@ *

A wildcard that matches all attributes of the matched elements. For example,

/perso n/name/@ * matches all attributes of every matched name element.

Match the location path at every nesting level. For example, the //name pattern matches every name element highlighted in the following XML fragment:

<name .../>

</person>

</invoice>

<name .../>

</person>

<name .../>

. .

no d e()

Selects the parent of the current context node. Not normally useful in the Apache

Camel XPath language, because the current context node is the document root, which has no parent.

text()

Match any kind of node.

Match a text node.

co mment()

Match a comment node.

4 20

CHAPT ER 31 . T HE XPAT H LANG UAG E pro cessi ng -i nstructi o n()

Match a processing-instruction node.

Predicat e filt ers

You can filter the set of nodes matching a location path by appending a predicate in square brackets, [Predicate]. For example, you can select the N th

node from the list of matches by appending [N] to a location path. The following expression selects the first matching

perso n element:

/people/person[1]

The following expression selects the second-last perso n element:

/people/person[last()-1]

You can test the value of attributes in order to select elements with particular attribute values.

The following expression selects the name elements, whose surname attribute is either

Strachan or Davies:

/person/name[@ surname="Strachan" or @ surname="Davies"]

You can combine predicate expressions using any of the conjunctions and , o r, no t(), and you can compare expressions using the comparators, = , ! = , >, >= , <, <= (in practice, the less-than symbol must be replaced by the & l t; entity). You can also use XPath functions in the predicate filter.

Axes

When you consider the structure of an XML document, the root element contains a sequence of children, and some of those child elements contain further children, and so on. Looked at in this way, where nested elements are linked together by the child-of relationship, the whole

XML document has the structure of a tree. Now, if you choose a particular node in this element tree (call it the context node), you might want to refer to different parts of the tree relative to the chosen node. For example, you might want to refer to the children of the context node, to the parent of the context node, or to all of the nodes that share the same parent as the context node (sibling nodes).

An XPath axis is used to specify the scope of a node match, restricting the search to a particular part of the node tree, relative to the current context node. The axis is attached as a prefix to the node name that you want to match, using the syntax,

AxisType: : MatchingNode. For example, you can use the chi l d : : axis to search the children of the current context node, as follows:

/invoice/items/child::item

The context node of chi l d : : i tem is the i tems element that is selected by the path,

4 21

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

/i nvo i ce/i tems. The chi l d : : axis restricts the search to the children of the context node, i tems, so that chi l d : : i tem matches the children of i tems that are named i tem.

As a matter of fact, the chi l d : : axis is the default axis, so the preceding example can be written equivalently as:

/invoice/items/item

But there several other axes (13 in all), some of which you have already seen in abbreviated form: @ is an abbreviation of attri bute: : , and // is an abbreviation of d escend ant-o r-

sel f: : . The full list of axes is as follows (for details consult the reference below):

ancesto r ancesto r-o r-sel f attri bute chi l d d escend ant d escend ant-o r-sel f fo l l o wi ng fo l l o wi ng -si bl i ng namespace parent preced i ng preced i ng -si bl i ng sel f

Funct ions

XPath provides a small set of standard functions, which can be useful when evaluating predicates. For example, to select the last matching node from a node set, you can use the last() function, which returns the index of the last node in a node set, as follows:

/people/person[last()]

4 22

CHAPT ER 31 . T HE XPAT H LANG UAG E

Where the preceding example selects the last perso n element in a sequence (in document order).

For full details of all the functions that XPath provides, consult the reference below.

Reference

For full details of the XPath grammar, see the XML Path Language, Version 1.0

specification.

31.7. PREDICAT ES

Basic predicat es

You can use xpath in the Java DSL or the XML DSL in a context where a predicate is expected—for example, as the argument to a fi l ter() processor or as the argument to a

when() clause.

For example, the following route filters incoming messages, allowing a message to pass, only if the /perso n/ci ty element contains the value, Lo nd o n: from("direct:tie")

.filter().xpath("/person/city =

'London'").to("file:target/messages/uk");

The following route evaluates the XPath predicate in a when() clause: from("direct:tie")

.choice()

.when(xpath("/person/city =

'London'")).to("file:target/messages/uk")

.otherwise().to("file:target/messages/others");

XPat h predicat e operat ors

The XPath language supports the standard XPath predicate operators, as shown in

Table 31.2, “ Operators for the XPath Language” .

T ab le 31.2. O p erat o rs f o r t h e XPat h Lan g u ag e

O perat or

! =

Descript ion

Eq uals.

No t eq ual to .

G reater than.

4 23

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

O perat or

<= o r and

Descript ion

G reater than o r eq uals.

Less than.

Less than o r eq uals.

Co mb ine two p red icates with lo g ical and.

Co mb ine two p red icates with lo g ical inclusive

or.

Neg ate p red icate arg ument.

no t()

31.8. USING VARIABLES AND FUNCT IONS

Evaluat ing variables in a rout e

When evaluating XPath expressions inside a route, you can use XPath variables to access the contents of the current exchange, as well as O/S environment variables and Java system properties. The syntax to access a variable value is $VarName or $Prefix: VarName, if the variable is accessed through an XML namespace.

For example, you can access the In message's body as $i n: bo d y and the In message's header value as $i n: HeaderName. O/S environment variables can be accessed as

$env: EnvVar and Java system properties can be accessed as $system: SysVar.

In the following example, the first route extracts the value of the /perso n/ci ty element and inserts it into the ci ty header. The second route filters exchanges using the XPath expression, $i n: ci ty = ' Lo nd o n' , where the $i n: ci ty variable is replaced by the value of the ci ty header.

from("file:src/data?noop=true")

.setHeader("city").xpath("/person/city/text()")

.to("direct:tie"); from("direct:tie")

.filter().xpath("$in:city =

'London'").to("file:target/messages/uk");

Evaluat ing funct ions in a rout e

In addition to the standard XPath functions, the XPath language defines additional

functions. These additional functions (which are listed in Table 31.4, “ XPath Custom

Functions” ) can be used to access the underlying exchange, to evaluate a simple

expression or to look up a property in the Apache Camel property placeholder component.

4 24

CHAPT ER 31 . T HE XPAT H LANG UAG E

For example, the following example uses the i n: head er() function and the i n: bo d y() function to access a head and the body from the underlying exchange: from("direct:start").choice()

.when().xpath("in:header('foo') = 'bar'").to("mock:x")

.when().xpath("in:body() = '<two/>'").to("mock:y")

.otherwise().to("mock:z");

Notice the similarity between theses functions and the corresponding i n: HeaderName or

i n: bo d y variables. The functions have a slightly different syntax however:

i n: head er('HeaderName') instead of i n: HeaderName; and i n: bo d y() instead of

i n: bo d y.

Evaluat ing variables in XPat hBuilder

You can also use variables in expressions that are evaluated using the XP athBui l d er class. In this case, you cannot use variables such as $i n: bo d y or $i n: HeaderName, because there is no exchange object to evaluate against. But you can use variables that are defined inline using the vari abl e(Name, Value) fluent builder method.

For example, the following XPathBuilder construction evaluates the $test variable, which is defined to have the value, Lo nd o n:

String var = XPathBuilder.xpath("$test")

.variable("test", "London")

.evaluate(getContext(), "<name>foo</name>");

Note that variables defined in this way are automatically entered into the global namespace

(for example, the variable, $test, uses no prefix).

31.9. VARIABLE NAMESPACES

T able of namespaces

Table 31.3, “ XPath Variable Namespaces”

shows the namespace URIs that are associated with the various namespace prefixes.

T ab le 31.3. XPat h Variab le Namesp aces

Namespace URI http: //camel . apache.

o rg /schema/spri ng

Prefix

None

Descript ion

Default namesp ace

(asso ciated with variab les that have no namesp ace p refix).

4 25

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Namespace URI http: //camel . apache.

o rg /xml /i n/

Prefix i n http: //camel . apache.

o rg /xml /o ut/ o ut http: //camel . apache.

o rg /xml /functi o ns/ http: //camel . apache.

o rg /xml /vari abl es/en vi ro nment-vari abl es functi o ns env http: //camel . apache.

o rg /xml /vari abl es/sy stem-pro perti es system http: //camel . apache.

o rg /xml /vari abl es/ex chang e-pro perty

Undefined

Descript ion

Used to reference head er o r b o d y o f the current exchang e's In messag e.

Used to reference head er o r b o d y o f the current exchang e's Out messag e.

Used to reference so me custo m functio ns.

Used to reference O /S enviro nment variab les.

Used to reference Java system p ro p erties.

Funct ion i n: bo d y() i n: head er(HeaderName) o ut: bo d y() o ut: head er(HeaderName)

Used to reference exchang e p ro p erties. Yo u must d efine yo ur o wn p refix fo r this namesp ace.

31.10. FUNCT ION REFERENCE

T able of cust om funct ions

Table 31.4, “ XPath Custom Functions”

shows the custom functions that you can use in

Apache Camel XPath expressions. These functions can be used in addition to the standard

XPath functions.

T ab le 31.4 . XPat h Cu st o m Fu n ct io n s

Descript ion

Returns the In messag e b o d y.

Returns the In messag e head er with name,

HeaderName.

Returns the Out messag e b o d y.

Returns the Out messag e head er with name,

HeaderName.

4 26

Funct ion functi o n: pro perti es(PropKey) functi o n: si mpl e(SimpleExp)

CHAPT ER 31 . T HE XPAT H LANG UAG E

Descript ion

Lo o ks up a p ro p erty with the key, PropKey

(see

Sectio n 2.7, “ Pro p erty Placeho ld ers”

Evaluates the sp ecified simp le exp ressio n,

SimpleExp.

4 27

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 32. XQUERY

OVERVIEW

XQuery was originally devised as a query language for data stored in XML form in a database. The XQuery language enables you to select parts of the current message, when the message is in XML format. XQuery is a superset of the XPath language; hence, any valid

XPath expression is also a valid XQuery expression.

JAVA SYNT AX

You can pass an XQuery expression to xq uery() in several ways. For simple expressions, you can pass the XQuery expressions as a string (java. l ang . Stri ng ). For longer

XQuery expressions, you might prefer to store the expression in a file, which you can then reference by passing a java. i o . Fi l e argument or a java. net. UR L argument to the overloaded xq uery() method. The XQuery expression implicitly acts on the message content and returns a node set as the result. Depending on the context, the return value is interpreted either as a predicate (where an empty node set is interpreted as false) or as an expression.

ADDING T HE SAXON MODULE

To use XQuery in your routes you need to add a dependency on camel -saxo n to your

project as shown in Example 32.1, “ Adding the camel-saxon dependency” .

Examp le 32.1. Ad d in g t h e camel- saxo n d ep en d en cy

...

...

<groupId> org.apache.camel

</groupId>

<artifactId> camel-saxon </artifactId>

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

</dependency>

...

</dependencies>

4 28

ST AT IC IMPORT

To use the xq uery() static method in your application code, include the following import statement in your Java source files: import static org.apache.camel.builder.saxon.XQueryBuilder.xquery;

CHAPT ER 32 . XQ UERY

VARIABLES

Table 32.1, “ XQuery variables”

lists the variables that are accessible when using XQuery.

T ab le 32.1. XQ u ery variab les

Variable exchang e i n. bo d y o ut. bo d y i n. head ers. key o ut. head ers. key

key

T ype

Exchang e

O bject

Descript ion

The current Exchang e

The b o d y o f the IN messag e

The b o d y o f the O UT messag e

The IN messag e head er who se key is key

The O UT messag e head er who se key is key

The Exchang e p ro p erty who se key is key

EXAMPLE

Example 32.2, “ Route using XQuery” shows a route that uses XQuery.

Examp le 32.2. Ro u t e u sin g XQ u ery

<route>

<language langauge= "xquery" > /foo:person[@ name='James'] </language>

</filter>

</route>

</camelContext>

4 29

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

PART III. WEB SERVICES AND ROUTING WITH CAMEL CXF

Ab st ract

This guide describes how to use Apache Camel's CXF component to create Web services or wrap existing functionality in Web service facades.

4 30

CHAPT ER 33. DEMO NST RAT IO N CO DE FO R CAMEL/CXF

CHAPTER 33. DEMONSTRATION CODE FOR CAMEL/CXF

Ab st ract

This chapter explains how to install, build, and run the demonstrations that accompany this guide.

33.1. DOWNLOADING AND INST ALLING T HE DEMONST RAT IONS

Overview

Most of the examples discussed in this guide are based on working demonstrations, which you can download and try out for yourself. The examples can easily be run by deploying them into a Red Hat JBoss Fuse container, as described here.

Prerequisit es

For building and running the demonstration code, you must have the following prerequisites installed:

Java platform—the demonstrations can run on Java 6 or Java 7.

Apache Maven build tool—to build the demonstration, you require Apache Maven 3.0.4

Internet connection—Maven requires an Internet connection in order to download required dependencies from remote repositories while performing a build.

Red Hat JBoss Fuse—the demonstrations are deployed into the JBoss Fuse container.

No t e

For more details of the requirements for installing and working with JBoss Fuse, see "Installation Guide" .

Downloading t he demonst rat ion package

The source code for the demonstrations is packaged as a Z ip file, cxf-webi nars-jbo ss-

fuse-6 . 2. zi p, and is available from the following location: https://github.com/FuseByExample/cxf-webinars/archive/jboss-fuse-6.2.zip

33.2. RUNNING T HE DEMONST RAT IONS

Building t he demonst rat ions

4 31

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Use Apache Maven to build the demonstrations. Open a new command prompt, change directory to cxf-webi nars-jbo ss-fuse-6 . 2, and enter the following commands: mvn install

This command builds all of the demonstrations under the cxf-webi nars-jbo ss-fuse-

6 . 2 directory (where the demonstrations are defined to be submodules of the cxf-

webi nars-jbo ss-fuse-6 . 2/po m. xml project). While Maven is building the demonstration code, it downloads whatever dependencies it needs from the Internet and installs them in the local Maven repository.

St art ing and configuring t he Red Hat JBoss Fuse cont ainer

Start and configure the Red Hat JBoss Fuse container as follows:

1. (Optional) If your local Maven repository is in a non-standard location, you might need to edit the JBoss Fuse configuration to specify your custom location. Edit the

InstallDir/etc/o rg . o ps4 j. pax. url . mvn. cfg file and set the

o rg . o ps4 j. pax. url . mvn. l o cal R epo si to ry property to the location of your local Maven repository:

# Path to the local maven repository which is used to avoid downloading

# artifacts when they already exist locally.

# The value of this property will be extracted from the settings.xml file

# above, or defaulted to:

# System.getProperty( "user.home" ) + "/.m2/repository"

#org.ops4j.pax.url.mvn.localRepository= org.ops4j.pax.url.mvn.localRepository=file:E:/Data/.m2/repositor y

2. Launch the JBoss Fuse container. Open a new command prompt, change directory to InstallDir/bi n, and enter the following command:

./fuse

Running t he cust omer-ws-osgi-bundle demonst rat ion

It is now a relatively straightforward task to run each of the demonstrations by installing the relevant OSGi bundles.

For example, to start up the WSDL-first Web service (discussed in Chapter 35, WSDL-First

Service Implementation

), enter the following console commands:

JBossFuse:karaf@ root> install -s mvn:com.fusesource.byexample.cxfwebinars/customer-ws-osgi-bundle

4 32

CHAPT ER 33. DEMO NST RAT IO N CO DE FO R CAMEL/CXF

To see the Web service in action, start up the sample Web service client (discussed in

Chapter 36, Implementing a WS Client

), by entering the following console command:

JBossFuse:karaf@ root> install -s mvn:com.fusesource.byexample.cxfwebinars/customer-ws-client

The bundle creates a thread that invokes the Web service once a second and logs the response. View the log by entering the following console command:

JBossFuse:karaf@ root> log:tail -n 4

You should see log output like the following:

2015-08-20 16:10:16,271 | INFO | #0 - timer://foo | timerToLog

| ? ? | 198 - org.apache.camel.camel-core - 2.15.1.redhat-620133 | The message contains Hi from Camel at 2015-08-20 16:10:16

2015-08-20 16:10:16,367 | INFO | qtp432302853-183 |

CustomerServiceImpl | ?

? | 283 - com.fusesource.byexample.cxf-webinars.customer-ws-osgibundle - 1.0.0.SNAPSHOT | Getting status for customer 1234

2015-08-20 16:10:16,370 | INFO | invoker thread. | ClientInvoker

| ? ? | 284 - com.fusesource.byexample.cxf-webinars.customer-ws-client -

1.0.0.SNAPSHOT | Got back: status = Active, statusMessage = In the park, playing with my frisbee.

2015-08-20 16:10:18,373 | INFO | qtp432302853-182 |

CustomerServiceImpl | ?

? | 283 - com.fusesource.byexample.cxf-webinars.customer-ws-osgibundle - 1.0.0.SNAPSHOT | Getting status for customer 1234

2015-08-20 16:10:18,376 | INFO | invoker thread. | ClientInvoker

| ? ? | 284 - com.fusesource.byexample.cxf-webinars.customer-ws-client -

1.0.0.SNAPSHOT | Got back: status = Active, statusMessage = In the park, playing with my frisbee.

To stop viewing the log, type the interrupt character (usually Ctrl-C).

To stop the client, first discover the client's bundle ID using the o sg i : l i st console command. For example:

JBossFuse:karaf@ root> list | grep customer-ws-client

[ 284] [Active ] [ ] [Started] [ 80] customer-wsclient (1.0.0.SNAPSHOT)

You can then stop the client using the o sg i : sto p console command. For example:

JBossFuse:karaf@ root> stop 284

To shut down the container completely, enter the following console command:

4 33

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

JBossFuse:karaf@ root> shutdown -f

Running t he ot her demonst rat ions

The remaining demonstrations are all based on the Camel CXF component. You can only run one of these demonstrations at a time, because they all use the same Web service port and would clash, if started at the same time:

custo mer-ws-camel -cxf-po jo custo mer-ws-camel -cxf-payl o ad custo mer-ws-camel -cxf-pro vi d er

The preceding demonstrations all require the Camel CXF component and some of them require the Camel Velocity component as well. Before you run the demonstrations, you must install the requisite features for these Camel components, as follows:

JBossFuse:karaf@ root> features:install camel-cxf

JBossFuse:karaf@ root> features:install camel-velocity

You can test these demonstrations using the provided custo mer-ws-cl i ent client or using the third-party SoapUI utility.

4 34

CHAPT ER 34 . JAVA- FIRST SERVICE IMPLEMENT AT IO N

CHAPTER 34. JAVA-FIRST SERVICE IMPLEMENTATION

34 .1. JAVA-FIRST OVERVIEW

Overview

The Java-first approach is a convenient way to get started with Web services, if you are unfamiliar with WSDL syntax. Using this approach, you can define the Web service interface using an ordinary Java interface and then use the provided Apache CXF utilities to generate the corresponding WSDL contract from the Java interface.

No t e

There is no demonstration code to accompany this example.

Service Endpoint Int erface (SEI)

An SEI is an ordinary Java interface. In order to use the standard JAX-WS frontend, the SEI

must be annotated with the @ WebServi ce annotation.

[1]

In the Java-first approach, the SEI is the starting point for implementing the Web service and it plays a central role in the development of the Web service implementation. The SEI is used in the following ways:

Base type of the Web service implementation (server side)—you define the Web service by implementing the SEI.

Proxy type (client side)—on the client side, you use the SEI to invoke operations on the client proxy object.

Basis for generating the WSDL contract—in the Java-first approach, you generate the WSDL contract by converting the SEI to WSDL.

WSDL cont ract

The WSDL contract is a platform-neutral and language-neutral description of the Web service interface. When you want to make the Web service available to third-party clients, you should publish the WSDL contract to some well-known location. The WSDL contract contains all of the metadata required by WS clients.

T he Cust omerService demonst rat ion

Figure 34.1, “ Building a Java-First Web Service”

shows an overview of the files required to implement and build the C usto merServi ce Web service using the Java-first approach.

Fig u re 34 .1. Bu ild in g a Java- First Web Service

4 35

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Implement ing and building t he service

To implement and build the Java-first example shown in Figure 34.1, “ Building a Java-First

Web Service” , you would perform the following steps:

1. Implement the SEI, which constitutes the basic definition of the Web service's interface.

2. Annotate the SEI (you can use the annotations to influence the ultimate form of the generated WSDL contract).

3. Implement any other requisite Java classes. In particular, implement the following:

Any data types referenced by the SEI—for example, the C usto mer class.

The implementation of the SEI, C usto merServi ceImpl .

4. Instantiate the Web service endpoint, by adding the appropriate code to a Spring

XML file.

5. Generate the WSDL contract using a Java-to-WSDL converter.

34 .2. DEFINE SEI AND RELAT ED CLASSES

Overview

The Service Endpoint Interface (SEI) is the starting point for implementing a Web service in the Java-first approach. The SEI represents the Web service in Java and it is ultimately used as the basis for generating the WSDL contract. This section describes how to create a sample SEI, the C usto merServi ce interface, which enables you to access the details of a customer's account.

4 36

T he Cust omerService SEI

CHAPT ER 34 . JAVA- FIRST SERVICE IMPLEMENT AT IO N

T he Cust omerService SEI

A JAX-WS service endpoint interface (SEI) is essentially an ordinary Java interface, augmented by certain annotations (which are discussed in the next section). For example, consider the following C usto merServi ce interface, which defines methods for accessing the C usto mer data type:

// Java package com.fusesource.demo.wsdl.customerservice;

// NOT YET ANNOTATED!

public interface C usto merServi ce {

public com.fusesource.demo.customer.Customer lookupCustomer(

java.lang.String customerId

);

public void updateCustomer(

com.fusesource.demo.customer.Customer cust

);

public void getCustomerStatus(

java.lang.String customerId,

javax.xml.ws.Holder<java.lang.String> status,

javax.xml.ws.Holder<java.lang.String> statusMessage

);

}

After adding the requisite annotations to the C usto merServi ce interface, this interface provides the basis for defining the C usto merServi ce Web service.

javax.xml.ws.Holder<?> t ypes

The g etC usto merStatus method from the C usto merServi ce interface has parameters declared to be of javax. xml . ws. Ho l d er<Stri ng > type. These so-called holder types are needed in order to declare the O UT or INO UT parameters of a WSDL operation.

The syntax of WSDL operations allows you to define any number of OUT or INOUT parameters, which means that the parameters are used to return a value to the caller. This kind of parameter passing is not natively supported by the Java language. Normally, the only way that Java allows you to return a value is by declaring it as the return value of a method. You can work around this language limitation, however, by declaring parameters to be holder types.

For example, consider the definition of the following method, g etStri ng Val ues(), which takes a holder type as its second parameter:

// Java public void getStringValues(

String wrongWay,

javax. xml . ws. Ho l d er<Stri ng > rightWay

4 37

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

) {

wrongWay = "Caller will never see this string!";

ri g htWay. val ue = "But the caller *can* see this string.";

}

The caller can access the value of the returned ri g htWay string as ri g htWay. val ue. For example:

// Java

String wrongWay = "This string never changes"; javax.xml.ws.Holder<String> rightWay.value = "This value *can* change."; sampleObject.getStringValues(wrongWay, rightWay);

System.out.println("Unchanged string: " + wrongWay);

System.out.println("Changed string: " + ri g htWay. val ue);

It is, perhaps, slightly unnatural to use Ho l d er<> types in a Java-first example, because this is not a normal Java idiom. But it is interesting to include OUT parameters in the example, so that you can see how a Web service processes this kind of parameter.

Relat ed classes

When you run the Java-to-WSDL compiler on the SEI, it converts not only the SEI, but also the classes referenced as parameters or return values. The parameter types must be convertible to XML, otherwise it would not be possible for WSDL operations to send or to receive those data types. In fact, when you run the Java-to-WSDL compiler, it is typically necessary to convert an entire tree of related classes to XML using the standard JAXB encoding.

Normally, as long as the related classes do not require any exotic language features, the

JAXB encoding should be quite straightforward.

Default const ruct or for relat ed classes

There is one simple rule, however, that you need to keep in mind when implementing related classes: each related class must have a default constructor (that is, a constructor without arguments). If you do not define any constructor for a class, the Java language automatically adds a default constructor. But if you define a class's constructors explicitly, you must ensure that one of them is a default constructor.

T he Cust omer class

For example, the C usto mer class appears as a related class in the definition of the

C usto merServi ce SEI (

the section called “ The CustomerService SEI” ). The C usto mer

class consists of a collection of Stri ng fields and the only special condition it needs to satisfy is that it includes a default constructor:

4 38

CHAPT ER 34 . JAVA- FIRST SERVICE IMPLEMENT AT IO N

// Java package com.fusesource.demo.customer; public class Customer {

protected String firstName;

protected String lastName;

protected String phoneNumber;

protected String id;

// Default constructor, required by JAX-WS

publ i c C usto mer() { }

public Customer(String firstName, String lastName, String phoneNumber,

String id) {

super();

this.firstName = firstName;

this.lastName = lastName;

this.phoneNumber = phoneNumber;

this.id = id;

}

public String getFirstName() {

return firstName;

}

public void setFirstName(String value) {

this.firstName = value;

}

public String getLastName() {

return lastName;

}

public void setLastName(String value) {

this.lastName = value;

}

public String getPhoneNumber() {

return phoneNumber;

}

public void setPhoneNumber(String value) {

this.phoneNumber = value;

}

public String getId() {

return id;

}

public void setId(String value) {

this.id = value;

}

4 39

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

34 .3. ANNOT AT E SEI FOR JAX-WS

Overview

To use the JAX-WS frontend, an SEI must be annotated using standardised JAX-WS annotations. The annotations signal to the Web services tooling that the SEI uses JAX-WS and the annotations are also used to customize the mapping from Java to WSDL. Here we only cover the most basic annotations—for complete details of JAX-WS annotations, see

Developing Applications Using JAX-WS from the Apache CXF library.

No t e

It sometimes makes sense also to annotate the service implementation class (the class that implements the SEI)—for example, if you want to associate an implementation class with a specific WSDL servi ceName and po rtName (there can be more than one implementation of a given SEI).

Minimal annot at ion

The minimal annotation required for an SEI using the JAX-WS frontend is to prefix the interface declaration with @ WebServi ce. For example, the C usto merServi ce SEI could be minimally annotated as follows:

// Java package com.fusesource.demo.wsdl.customerservice;

i mpo rt javax. jws. WebServi ce;

@ WebServi ce

public interface CustomerService {

...

}

If you run the Java-to-WSDL utility on this interface, it will generate a complete WSDL contract using the standard default style of code conversion.

@WebService annot at ion

Although it is sufficient to specify the @ WebServi ce annotation without any attributes, it is usually better to specify some attributes to provide a more descriptive WSDL service name and WSDL port name. You will also usually want to specify the XML target namespace. For this, you can specify the following optional attributes of the @ WebServi ce annotation:

name

Specifies the name of the WSDL contract (appearing in the wsd l : d efi ni ti o ns element).

4 4 0

CHAPT ER 34 . JAVA- FIRST SERVICE IMPLEMENT AT IO N servi ceName

Specifies the name of the WSDL service (a SOAP service is defined by default in the generated contract).

po rtName

Specifies the name of the WSDL port (a SOAP/HTTP port is defined by default in the generated contract).

targ etNamespace

The XML schema namespace that is used, by default, to qualify the elements and types defined in the contract.

@WebParam annot at ion

You can add the @ WebP aram annotation to method arguments in the SEI. The @ WebP aram annotation is optional, but there are a couple of good reasons for adding it:

By default, JAX-WS maps Java arguments to parameters with names like arg 0 , ..., arg N.

Messages are much easier to read, however, when the parameters have meaningful names.

It is a good idea to define parameter elements without a namespace. This makes the XML encoding of requests and responses more compact.

To enable support for WSDL OUT and INOUT parameters.

You can add @ WebP aram annotations with the following attributes:

name

Specifies the mapped name of the parameter.

targ etNamespace

Specifies the namespace of the mapped parameter. Set this to a blank string for a more compact XML encoding.

mo d e

Can have one of the following values:

WebP aram. Mo d e. IN—(default) parameter is passed from client to service (in request).

4 4 1

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

WebP aram. Mo d e. INO UT —parameter is passed from client to service (request) and from the service back to the client (in reply).

WebP aram. Mo d e. O UT —parameter is passed from service back to the client (in reply).

OUT and INOUT paramet ers

In WSDL, OUT and INOUT parameters represent values that can be sent from the service back to the client (where the INOUT parameter is sent in both directions).

In Java syntax, the only value that can ordinarily be returned from a method is the method's return value. In order to support OUT or INOUT parameters in Java (which are effectively like additional return values), you must:

Declare the corresponding Java argument using a

javax. xml . ws. Ho l d er<ParamType> type, where ParamType is the type of the parameter you want to send.

Annotate the Java argument with @ WebP aram, setting either mo d e =

WebP aram. Mo d e. O UT or mo d e = WebP aram. Mo d e. INO UT .

Annot at ed Cust omerService SEI

The following example shows the C usto merServi ce SEI after it has been annotated. Many other annotations are possible, but this level of annotation is usually adequate for a WSDLfirst project.

// Java package com.fusesource.demo.wsdl.customerservice; import javax.jws.WebParam; import javax.jws.WebService;

@ WebServi ce(

targ etNamespace =

"http: //d emo . fuseso urce. co m/wsd l /C usto merServi ce/",

name = "C usto merServi ce",

servi ceName = "C usto merServi ce",

po rtName = "SO AP O verHT T P "

)

public interface CustomerService {

public com.fusesource.demo.customer.Customer lookupCustomer(

@ WebP aram(name = "custo merId ", targ etNamespace = "")

java.lang.String customerId

);

public void updateCustomer(

@ WebP aram(name = "cust", targ etNamespace = "")

4 4 2

CHAPT ER 34 . JAVA- FIRST SERVICE IMPLEMENT AT IO N

com.fusesource.demo.customer.Customer cust

);

public void getCustomerStatus(

@ WebP aram(name = "custo merId ", targ etNamespace = "")

java.lang.String customerId,

@ WebP aram(mo d e = WebP aram. Mo d e. O UT , name = "status", targ etNamespace = "")

javax.xml.ws.Holder<java.lang.String> status,

@ WebP aram(mo d e = WebP aram. Mo d e. O UT , name = "statusMessag e", targ etNamespace = "")

javax.xml.ws.Holder<java.lang.String> statusMessage

);

}

34 .4 . INST ANT IAT E T HE WS ENDPOINT

Overview

In Apache CXF, you create a WS endpoint by defining a jaxws: end po i nt element in XML.

The WS endpoint is effectively the runtime representation of the Web service: it opens an IP port to listen for SOAP/HTTP requests, is responsible for marshalling and unmarshalling messages (making use of the generated Java stub code), and routes incoming requests to the relevant methods on the implementor class.

In other words, creating a Web service in Spring XML consists essentially of the following two steps:

1. Create an instance of the implementor class, using the Spring bean element.

2. Create a WS endpoint, using the jaxws: end po i nt element.

T he jaxws:endpoint element

You can instantiate a WS endpoint using the jaxws: end po i nt element in a Spring file, where the jaxws: prefix is associated with the http: //cxf. apache. o rg /jaxws namespace.

No t e

Take care not to confuse the jaxws: end po i nt element with the

cxf: cxfEnd po i nt element, which you meet later in this guide: the

jaxws: end po i nt element is used to integrate a WS endpoint with a Java implementation class; whereas the cxf: cxfEnd po i nt is used to integrate a WS endpoint with a Camel route.

Define JAX-WS endpoint in XML

4 4 3

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

The following sample Spring file shows how to define a JAX-WS endpoint in XML, using the

jaxws: end po i nt element.

<?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:jaxws="http://cxf.apache.org/jaxws"

xmlns:soap="http://cxf.apache.org/bindings/soap"

xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd

http://cxf.apache.org/bindings/soap http://cxf.apache.org/schemas/configuration/soap.xsd

http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd">

<jaxws:endpoint

xmlns:customer="http://demo.fusesource.com/wsdl/CustomerService/"

id="customerService"

address="/C usto mer"

serviceName="customer:CustomerService"

endpointName="customer:SOAPOverHTTP"

implementor="#custo merServi ceImpl ">

</jaxws:endpoint>

<bean id="custo merServi ceImpl "

class="com.fusesource.customer.ws.CustomerServiceImpl"/>

</beans>

Address for t he Jet t y cont ainer

Apache CXF deploys the WS endpoint into a Jetty servlet container instance and the

ad d ress attribute of jaxws: end po i nt is therefore used to configure the addressing information for the endpoint in the Jetty container.

Apache CXF supports the notion of a default servlet container instance. The way the default servlet container is initialized and configured depends on the particular mode of deployment that you choose. For example the Red Hat JBoss Fuse container and Web containers (such as Tomcat) provide a default servlet container.

There are two different syntaxes you can use for the endpoint address, where the syntax that you use effectively determines whether or not the endpoint is deployed into the default servlet container, as follows:

Address syntax for default servlet container—to use the default servlet container, specify only the servlet context for this endpoint. Do not specify the protocol, host, and IP port in the address. For example, to deploy the endpoint to the /C usto mers servlet context in the default servlet container: address="/Customers"

4 4 4

CHAPT ER 34 . JAVA- FIRST SERVICE IMPLEMENT AT IO N

Address syntax for custom servlet container—to instantiate a custom Jetty container for the endpoint, specify a complete HTTP URL, including the host and IP port (the value of the

IP port effectively identifies the target Jetty container). Typically, for a Jetty container, you specify the host as 0 . 0 . 0 . 0 , which is interpreted as a wildcard that matches every IP network interface on the local machine (that is, if deployed on a multi-homed host, Jetty opens a listening port on every network card). For example, to deploy the endpoint to the custom Jetty container listening on IP port, 80 83: address="http://0.0.0.0:8083/Customers"

No t e

If you want to configure a secure endpoint (secured by SSL), you would specify the https: scheme in the address.

Referencing t he service implement at ion

The i mpl emento r attribute of the jaxws: end po i nt element references the implementation of the WS service. The value of this attribute can either be the name of the implementation class or (as in this example) a bean reference in the format, #BeanID, where the # character indicates that the following identifier is the name of a bean in the bean registry.

34 .5. JAVA-T O-WSDL MAVEN PLUG-IN

Overview

To generate a WSDL contract from your SEI, you can use either the java2ws command-line utility or the cxf-java2ws-pl ug i n Maven plug-in. The plug-in approach is ideal for

Maven-based projects: after you paste the requisite plug-in configuration into your POM file, the WSDL code generation step is integrated into your build.

Configure t he Java-t o-WSDL Maven plug-in

Configuring the Java-to-WSDL Maven plug-in is relatively easy, because most of the default configuration settings can be left as they are. After copying and pasting the sample pl ug i n element into your project's POM file, there are just a few basic settings that need to be customized, as follows:

CXF version—make sure that the plug-in's dependencies are using the latest version of

Apache CXF.

SEI class name—specify the fully-qualified class name of the SEI in the

co nfi g urati o n/cl assName element.

Location of output—specify the location of the generated WSDL file in the

co nfi g urati o n/o utputFi l e element.

4 4 5

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

For example, the following POM fragment shows how to configure the cxf-java2ws-

pl ug i n plug-in to generate WSDL from the CustomerService SEI:

...

<cxf. versi o n>3. 0 . 4 . red hat-6 20 133</cxf. versi o n>

</properties>

<build>

<defaultGoal>install</defaultGoal>

...

<groupId>org.apache.cxf</groupId>

<version>${cxf. versi o n}</version>

<groupId>org.apache.cxf</groupId>

<artifactId>cxf-rt-frontend-jaxws</artifactId>

<version>${cxf. versi o n}</version>

</dependency>

<groupId>org.apache.cxf</groupId>

<artifactId>cxf-rt-frontend-simple</artifactId>

<version>${cxf. versi o n}</version>

</dependency>

</dependencies>

<id>process-classes</id>

<phase>process-classes</phase>

<className>o rg . fuseso urce. d emo . camel cxf. ws. server. C usto merServi ce</c lassName>

<outputFile>${based i r}/. . /src/mai n/reso urces/wsd l /C usto merServi ce. ws

d l </outputFile>

</configuration>

<goals>

</goals>

</execution>

</executions>

</plugin>

</plugins>

</build>

</project>

4 4 6

CHAPT ER 34 . JAVA- FIRST SERVICE IMPLEMENT AT IO N

Generat ed WSDL

When using the Java-first approach to defining a Web service, there are typically other parts of your application (for example, WS clients) that depend on the generated WSDL file. For this reason, it is generally a good idea to output the generated WSDL file to a common location, which is accessible to other projects in your application, using the o utputFi l e configuration element.

If you do not specify the o utputFi l e configuration element, the generated WSDL is sent to the following location, by default:

BaseDir/target/generated/wsdl/SEIClassName.wsdl

Reference

For full details of how to configure the Java-to-WSDL plug-in, see the Maven Java2WS plugin reference page .

[1]

If the SEI is left witho ut anno tatio ns, Ap ache CXF d efaults to using the

simp le fro ntend . This is a no n-stand ard fro ntend , which is not reco mmend ed fo r mo st ap p licatio ns.

4 4 7

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 35. WSDL-FIRST SERVICE IMPLEMENTATION

35.1. WSDL-FIRST OVERVIEW

Overview

If you are familiar with the syntax of WSDL and you want to have ultimate control over the layout and conventions applied to the WSDL contract, you will probably prefer to develop your Web service using the WSDL-first approach. In this approach, you start with the WSDL contract and then use the provided Apache CXF utilities to generate the requisite Java stub files from the WSDL contract.

Demonst rat ion locat ion

The code presented in this chapter is taken from the following demonstration: cxf-webinars-jboss-fuse-6.2/custo mer-ws-o sg i -bund l e

For details of how to download and install the demonstration code, see Chapter 33,

Figure 35.1, “ Building a WSDL-First Web Service” shows an overview of the files required to

WSDL cont ract

The WSDL contract is a platform-neutral and language-neutral description of the Web service interface. In the WSDL-first approach, the WSDL contract is the starting point for implementing the Web service. You can use it to generate Java stub code, which provides the basis for implementing the Web service on the server side.

Service Endpoint Int erface (SEI)

The most important piece of the generated stub code is the SEI, which is an ordinary Java interface that represents the Web service interface in the Java language.

The SEI is used in the following ways:

Base type of the Web service implementation (server side)—you define the Web service by implementing the SEI.

Proxy type (client side)—on the client side, you use the SEI to invoke operations on the client proxy object.

T he Cust omerService demonst rat ion

implement and build the C usto merServi ce Web service using the WSDL-first approach.

4 4 8

CHAPT ER 35. WSDL- FIRST SERVICE IMPLEMENT AT IO N

Fig u re 35.1. Bu ild in g a WSDL- First Web Service

Implement ing and building t he service

To implement and build the WSDL-first example shown in Figure 35.1, “ Building a WSDL-

First Web Service” , starting from scratch, you would perform the following steps:

1. Create the WSDL contract.

2. Generate the Java stub code from the WSDL contract using a WSDL-to-Java converter, ws2java. This gives you the SEI, C usto merServi ce, and its related classes, such as C usto mer.

3. Write the implementation of the SEI, C usto merServi ceImpl .

4. Instantiate the Web service endpoint, by adding the appropriate code to a Spring

XML file.

35.2. CUST OMERSERVICE WSDL CONT RACT

Sample WSDL cont ract

The WSDL contract used in this demonstration is the C usto merServi ce WSDL contract, which is available in the following location: cxf-webinars-jboss-fuse-6.2/src/main/resources/wsdl

Because the WSDL contract is a fairly verbose format, it is not shown in here in full. The main point you need to be aware of is that the C usto merSeri vi ce WSDL contract exposes the following operations:

4 4 9

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide l o o kupC usto mer

Given a customer ID, the operation returns the corresponding C usto mer data object.

upd ateC usto mer

Stores the given C usto mer data object against the given customer ID.

g etC usto merStatus

Returns the status of the customer with the given customer ID.

Part s of t he WSDL cont ract

A WSDL contract has the following main parts:

the section called “ Port type” .

the section called “ WSDL binding”

the section called “ WSDL port”

Port t ype

The port type is defined in the WSDL contract by the wsd l : po rtT ype element. It is analogous to an interface and it defines the operations that can be invoked on the Web service.

For example, the following WSDL fragment shows the wsd l : po rtT ype definition from the

C usto merServi ce WSDL contract:

<wsdl:definitions name= "CustomerService"

targetNamespace= "http://demo.fusesource.com/wsdl/CustomerService/"

...>

...

<wsdl:portType name= "CustomerService" >

<wsdl:operation name= "lookupCustomer" >

<wsdl:input message= "tns:lookupCustomer" ></wsdl:input>

<wsdl:output message= "tns:lookupCustomerResponse" ></wsdl:output>

</wsdl:operation>

<wsdl:operation name= "updateCustomer" >

<wsdl:input message= "tns:updateCustomer" ></wsdl:input>

<wsdl:output message= "tns:updateCustomerResponse" ></wsdl:output>

</wsdl:operation>

<wsdl:operation name= "getCustomerStatus" >

4 50

CHAPT ER 35. WSDL- FIRST SERVICE IMPLEMENT AT IO N

<wsdl:input message= "tns:getCustomerStatus" ></wsdl:input>

<wsdl:output message= "tns:getCustomerStatusResponse" ></wsdl:output>

</wsdl:operation>

</wsdl:portType>

...

</wsdl:definitions>

WSDL binding

A WSDL binding describes how to encode all of the operations and data types associated with a particular port type. A binding is specific to a particular protocol—for example, SOAP or JMS.

WSDL port

A WSDL port specifies the transport protocol and contains addressing data that enables clients to locate and connect to a remote server endpoint.

For example, the C usto merServi ce WSDL contract defines the following WSDL port:

<wsdl:definitions ...>

...

<wsdl:service name="CustomerService">

<wsdl:port name="SOAPOverHTTP" binding="tns:CustomerServiceSOAP">

<soap:address location="http://0.0.0.0:8183/CustomerService" />

</wsdl:port>

</wsdl:service>

</wsdl:definitions>

The address specified by the so ap: ad d ress element's l o cati o n attribute in the original

WSDL contract is typically overridden at run time, however.

T he get Cust omerSt at us operat ion

Because a WSDL contract is fairly verbose, it can be a bit difficult to see what the parameters of an operation are. Typically, for each operation, you can find data types in the XML schema section that represent the operation request and the operation response. For example, the g etC usto merStatus operation has its request parameters (IN parameters) encoded by the g etC usto merStatus element and its response parameters (OUT parameters) encoded by the g etC usto merStatusR espo nse element, as follows:

<wsdl:definitions name="CustomerService"

targetNamespace="http://demo.fusesource.com/wsdl/CustomerService/"

...>

<wsdl:types>

4 51

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

<xsd:schema ...>

...

<xsd:element name="g etC usto merStatus">

<xsd:complexType>

<xsd:sequence>

<xsd:element name="customerId" type="xsd:string"/>

</xsd:sequence>

</xsd:complexType>

</xsd:element>

<xsd:element name="g etC usto merStatusR espo nse">

<xsd:complexType>

<xsd:sequence>

<xsd:element name="status" type="xsd:string"/>

<xsd:element name="statusMessage" type="xsd:string"/>

</xsd:sequence>

</xsd:complexType>

</xsd:element>

</xsd:schema>

</wsdl:types>

...

</wsdl:definitions>

References

For more details about the format of WSDL contracts and how to create your own WSDL contracts, see Writing WSDL Contracts and the Eclipse JAX-WS Tools Component .

35.3. WSDL-T O-JAVA MAVEN PLUG-IN

Overview

In contrast to the Java-first approach, which starts with a Java interface and then generates the WSDL contract, the WSDL-first approach needs to generate Java stub code from the

WSDL contract.

To generate Java stub code from the WSDL contract, you can use either the ws2java command-line utility or the cxf-co d eg en-pl ug i n Maven plug-in. The plug-in approach is ideal for Maven-based projects: after you paste the requisite plug-in configuration into your

POM file, the WSDL-to-Java code generation step is integrated into your build.

Configure t he WSDL-t o-Java Maven plug-in

Configuring the WSDL-to-Java Maven plug-in is relatively easy, because most of the default configuration settings can be left as they are. After copying and pasting the sample pl ug i n element into your project's POM file, there are just a few basic settings that need to be customized, as follows:

4 52

CHAPT ER 35. WSDL- FIRST SERVICE IMPLEMENT AT IO N

CXF version—make sure that the plug-in's dependencies are using the latest version of

Apache CXF.

WSDL file location—specify the WSDL file location in the

co nfi g urati o n/wsd l O pti o ns/wsd l O pti o n/wsd l element.

Location of output—specify the root directory of the generated Java source files in the

co nfi g urati o n/so urceR o o t element.

For example, the following POM fragment shows how to configure the cxf-co d eg en-

pl ug i n plug-in to generate Java stub code from the C usto merServi ce. wsd l WSDL file:

...

<groupId>com.fusesource.byexample.cxf-webinars</groupId>

<artifactId>cxf-webinars</artifactId>

<version>1.0-SNAPSHOT</version>

</parent>

<build>

<defaultGoal>install</defaultGoal>

...

<groupId>org.apache.cxf</groupId>

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

<id>generate-sources</id>

<phase>generate-sources</phase>

<sourceRoot>${based i r}/targ et/g enerated -

so urces/jaxws</sourceRoot>

<wsdl>${based i r}/. . /src/mai n/reso urces/wsd l /C usto merServi ce. wsd l </wsd l>

</wsdlOption>

</wsdlOptions>

</configuration>

<goals>

</goals>

</execution>

</executions>

</plugin>

4 53

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

</plugins>

</build>

</project>

Generat ed Java source code

With the sample configuration shown here, the generated Java source code is written under the targ et/g enerated -so urces/jaxws directory. Note that the Web service implementation is dependent on this generated stub code—for example, the service implementation class must implement the generated C usto merServi ce SEI.

Adding t he generat ed source t o an IDE

If you are using an IDE such as Eclipse or Intellij's IDEA, you need to make sure that the IDE is aware of the generated Java code. For example, in Eclipse it is necessary to add the

targ et/g enerated -so urces/jaxws directory to the project as a source code directory.

Compiling t he generat ed code

You must ensure that the generated Java code is compiled and added to the deployment package. By convention, Maven automatically compiles any source files that it finds under the following directory:

BaseDir/target/generated-sources/

Hence, if you configure the output directory as shown in the preceding POM fragment, the generated code is automatically compiled by Maven.

Reference

For full details of how to configure the Java-to-WSDL plug-in, see the Maven cxf-codegenplugin reference page.

35.4 . INST ANT IAT E T HE WS ENDPOINT

Overview

In Apache CXF, you create a WS endpoint by defining a jaxws: end po i nt element in XML.

In other words, creating a Web service in Spring XML consists essentially of the following two steps:

4 54

CHAPT ER 35. WSDL- FIRST SERVICE IMPLEMENT AT IO N

1. Create an instance of the implementor class, using the Spring bean element.

2. Create a WS endpoint, using the jaxws: end po i nt element.

Define JAX-WS endpoint in XML

The following sample Spring file shows how to define a JAX-WS endpoint in XML, using the

jaxws: end po i nt element.

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

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

xmlns:jaxws="http://cxf.apache.org/jaxws"

xmlns:soap="http://cxf.apache.org/bindings/soap"

xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd

http://cxf.apache.org/bindings/soap http://cxf.apache.org/schemas/configuration/soap.xsd

http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd">

<jaxws:endpoint

xmlns:customer="http://demo.fusesource.com/wsdl/CustomerService/"

id="customerService"

address="/C usto mer"

serviceName="customer:CustomerService"

endpointName="customer:SOAPOverHTTP"

implementor="#customerServiceImpl">

</jaxws:endpoint>

<bean id="customerServiceImpl"

class="com.fusesource.customer.ws.CustomerServiceImpl"/>

</beans>

Address for t he Jet t y cont ainer

In the preceding example, the ad d ress attribute of the jaxws: end po i nt element specifies the servlet context for this endpoint, relative to the Jetty container in which it is deployed.

For more details about the options for specifying the endpoint address, see the section called “ Address for the Jetty container” .

Referencing t he service implement at ion

The i mpl emento r attribute of the jaxws: end po i nt element is used to reference the implementation of the WS service. The value of this attribute can either be the name of the implementation class or (as in this example) a bean reference in the format, #BeanID, where the # character indicates that the following identifier is the name of a bean in the bean registry.

4 55

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

35.5. DEPLOY T O AN OSGI CONT AINER

Overview

One of the options for deploying the Web service is to package it as an OSGi bundle and deploy it into an OSGi container such as Red Hat JBoss Fuse. Some of the advantages of an OSGi deployment include:

Bundles are a relatively lightweight deployment option (because dependencies can be shared between deployed bundles).

OSGi provides sophisticated dependency management, ensuring that only versionconsistent dependencies are added to the bundle's classpath.

Using t he Maven bundle plug-in

The Maven bundle plug-in is used to package your project as an OSGi bundle, in preparation for deployment into the OSGi container. There are two essential modifications to make to your project's po m. xml file:

1. Change the packaging type to bund l e (by editing the value of the

pro ject/packag i ng element in the POM).

2. Add the Maven bundle plug-in to your POM file and configure it as appropriate.

Configuring the Maven bundle plug-in is quite a technical task (although the default settings are often adequate). For full details of how to customize the plug-in configuration, consult

Deploying into the OSGi Container and Managing OSGi Dependencies.

Sample bundle plug-in configurat ion

The following POM fragment shows a sample configuration of the Maven bundle plug-in, which is appropriate for the current example.

<?xml version="1.0"?>

...

<groupId>com.fusesource.byexample.cxf-webinars</groupId>

<artifactId>customer-ws-osgi-bundle</artifactId>

<name>customer-ws-osgi-bundle</name>

<url>http://www.fusesource.com</url>

<packag i ng >bund l e</packag i ng >

...

<build>

...

<groupId>org.apache.felix</groupId>

4 56

CHAPT ER 35. WSDL- FIRST SERVICE IMPLEMENT AT IO N

<artifactId>maven-bund l e-pl ug i n</artifactId>

<version>${version.maven-bundle-plugin}</version>

<Export-Package>

!com.fusesource.customer.ws,

!com.fusesource.demo.customer,

!com.fusesource.demo.wsdl.customerservice

</Export-Package>

<Import-Package>

</Import-Package>

<DynamicImport-Package>

org.apache.cxf.*,

org.springframework.beans.*

</DynamicImport-Package>

</instructions>

</configuration>

</plugin>

...

</plugins>

</build>

</project>

Dynamic import s

The Java packages from Apache CXF and the Spring API are imported using dynamic imports (specified using the D ynami cImpo rt-P ackag e element). This is a pragmatic way of dealing with the fact that Spring XML files are not terribly well integrated with the Maven bundle plug-in. At build time, the Maven bundle plug-in is not able to figure out which Java classes are required by the Spring XML code. By listing wildcarded package names in the

D ynami cImpo rt-P ackag e element, however, you allow the OSGi container to figure out which Java classes are needed by the Spring XML code at run time.

No t e

In general, using D ynami cImpo rt-P ackag e headers is not recommended in

OSGi, because it short-circuits OSGi version checking. Normally, what should happen is that the Maven bundle plug-in lists the Java packages used at build time, along with their versions, in the Impo rt-P ackag e header. At deploy time, the OSGi container then checks that the available Java packages are compatible with the build-time versions listed in the Impo rt-P ackag e header. With dynamic imports, this version checking cannot be performed.

Build and deploy t he service bundle

After you have configured the POM file, you can build the Maven project and install it in your local repository by entering the following command: mvn install

4 57

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

To deploy the service bundle, enter the following command at the command console: karaf@ root> install -s mvn:com.fusesource.byexample.cxfwebinars/customer-ws-osgi-bundle

No t e

If your local Maven repository is stored in a non-standard location, you might need to customize the value of the o rg . o ps4 j. pax. url . mvn. l o cal R epo si to ry property in the EsbInstallDir/etc/o rg . o ps4 j. pax. url . mvn. cfg file, before you can use the mvn: scheme to access Maven artifacts.

Red Hat JBoss Fuse default servlet cont ainer

Red Hat JBoss Fuse has a default Jetty container which, by default, listens for HTTP requests on port 8181. Moreover, WS endpoints in this container are implicitly deployed under the servlet context cxf/. Hence, any WS endpoint whose ad d ress attribute is configured in the jaxws: end po i nt element as /EndpointContext will have the following effective address: http://Hostname:8181/cxf/EndpointContext

You can optionally customize the default servlet container by editing settings in the following file:

InstallDir/etc/org.ops4j.pax.web.cfg

Full details of the properties you can set in this file are given in the Ops4j Pax Web configuration reference .

Check t hat t he service is running

A simple way of checking that the service is running is to point your browser at the following

URL: http://localhost:8181/cxf/Customer?wsdl

This query should return a copy of the WS endpoint's WSDL contract.

4 58

CHAPT ER 36 . IMPLEMENT ING A WS CLIENT

CHAPTER 36. IMPLEMENTING A WS CLIENT

36.1. WS CLIENT OVERVIEW

Overview

The key object in a WS client is the WS client proxy object, which enables you to access the remote Web service by invoking methods on the SEI. The proxy object itself can easily be instantiated using the jaxws: cl i ent element in Spring XML.

Demonst rat ion locat ion

The code presented in this chapter is taken from the following demonstration: cxf-webinars-jboss-fuse-6.2/custo mer-ws-cl i ent

For details of how to download and install the demonstration code, see Chapter 33,

Figure 36.1, “ Building a WS Client” shows an overview of the files required to implement and

WSDL cont ract

The WSDL contract is a platform-neutral and language-neutral description of the Web service interface. It contains all of the metadata that a client needs to find a Web service and invoke its operations. You can generate Java stub code from the WSDL contract, which provides an API that makes it easy to invoke the remote WSDL operations.

Service Endpoint Int erface (SEI)

The most important piece of the generated stub code is the SEI, which is an ordinary Java interface that represents the Web service interface in the Java language.

WS client proxy

The WS client proxy is an object that converts Java method invocations to remote procedure calls, sending and receiving messages to a remote instance of the Web service across the network. The methods of the proxy are exposed through the SEI.

No t e

The proxy type is generated dynamically by Apache CXF at run time. That is, their is no class in the stub code that corresponds to the implementation of the proxy (the only relevant entity is the SEI, which defines the proxy's interface).

T he Cust omerService client

4 59

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

To take a specific example, consider the custo mer-ws-cl i ent demonstration, which is available from the following location: cxf-webinars-jboss-fuse-6.2/customer-ws-client

build the WS client.

Fig u re 36 .1. Bu ild in g a WS Clien t

4 60

Implement ing and building t he WS client

To implement and build the sample WS client shown in Figure 36.1, “ Building a WS Client”

, starting from scratch, you would perform the following steps:

1. Obtain a copy of the WSDL contract.

2. Generate the Java stub code from the WSDL contract using a WSDL-to-Java converter, ws2java. This gives you the SEI, C usto merServi ce, and its related classes, such as C usto mer.

3. Implement the main client class, C l i entInvo ker, which invokes the Web service operations. In this class define a bean property of type, C usto merServi ce, so that the client class can receive a reference to the WS client proxy by property injection.

4. In a Spring XML file, instantiate the WS client proxy and inject it into the main client class, C l i entInvo ker.

36.2. WSDL-T O-JAVA MAVEN PLUG-IN

Overview

CHAPT ER 36 . IMPLEMENT ING A WS CLIENT

To generate Java stub code from the WSDL contract, you can use either the ws2java command-line utility or the cxf-co d eg en-pl ug i n Maven plug-in. When using Maven, the plug-in approach is ideal: after you paste the requisite plug-in configuration into your POM file, the WSDL-to-Java code generation step is integrated into your build.

Configure t he WSDL-t o-Java Maven plug-in

CXF version—make sure that the plug-in's dependencies are using the latest version of

Apache CXF.

WSDL file location—specify the WSDL file location in the

co nfi g urati o n/wsd l O pti o ns/wsd l O pti o n/wsd l element.

Location of output—specify the root directory of the generated Java source files in the

co nfi g urati o n/so urceR o o t element.

For example, the following POM fragment shows how to configure the cxf-co d eg en-

pl ug i n plug-in to generate Java stub code from the C usto merServi ce. wsd l WSDL file:

...

<groupId>com.fusesource.byexample.cxf-webinars</groupId>

<artifactId>cxf-webinars</artifactId>

<version>1.0-SNAPSHOT</version>

</parent>

<build>

<defaultGoal>install</defaultGoal>

...

<groupId>org.apache.cxf</groupId>

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

<id>generate-sources</id>

<phase>generate-sources</phase>

<sourceRoot>${based i r}/targ et/g enerated -

so urces/jaxws</sourceRoot>

<wsdl>${based i r}/. . /src/mai n/reso urces/wsd l /C usto merServi ce. wsd l </wsd l>

4 61

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

</wsdlOption>

</wsdlOptions>

</configuration>

<goals>

</goals>

</execution>

</executions>

</plugin>

</plugins>

</build>

</project>

Generat ed Java source code

With the sample configuration shown here, the generated Java source code is written under the targ et/g enerated -so urces/jaxws directory. Note that the client implementation is dependent on this generated stub code—for example, the client invokes the proxy using the generated C usto merServi ce SEI.

Add generat ed source t o IDE

If you are using an IDE such as Eclipse or Intellij's IDEA, you need to make sure that the IDE is aware of the generated Java code. For example, in Eclipse it is necessary to add the

targ et/g enerated -so urces/jaxws directory to the project as a source code directory.

Compiling t he generat ed code

You must ensure that the generated Java code is compiled and added to the deployment package. By convention, Maven automatically compiles any source files that it finds under the following directory:

BaseDir/target/generated-sources/

Hence, if you configure the output directory as shown in the preceding POM fragment, the generated code is automatically compiled by Maven.

Reference

For full details of how to configure the Java-to-WSDL plug-in, see the Maven cxf-codegenplugin reference page.

36.3. INST ANT IAT E T HE WS CLIENT PROXY

Overview

4 62

CHAPT ER 36 . IMPLEMENT ING A WS CLIENT

The WS client proxy is the most important kind of object in a WS client, because it provides a simple way of invoking operations on a remote Web service. The proxy enables you to access a Web service by invoking methods locally on a Java interface. The methods invoked on the proxy object are then translated into remote procedure calls on the Web service.

You can instantiate a WS client proxy straightforwardly using the jaxws: cl i ent element.

Define t he WS client in XML

The following Spring XML fragment shows how to instantiate a client proxy bean using the

jaxws: cl i ent element.

<?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:jaxws="http://cxf.apache.org/jaxws"

xmlns:soap="http://cxf.apache.org/bindings/soap"

xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd

http://cxf.apache.org/bindings/soap http://cxf.apache.org/schemas/configuration/soap.xsd

http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd">

<jaxws:client

id="custo merServi ceP ro xy"

address="http://localhost:8181/cxf/Customer" serviceClass="com.fusesource.demo.wsdl.customerservice.CustomerService"

<bean id="customerServiceClient"

class="com.fusesource.customer.client.ClientInvoker"

init-method="init" destroy-method="destroy">

</bean>

</beans>

T he jaxws:client element

The jaxws: cl i ent element creates a client proxy dynamically (that is, there is no dedicated class that represents a proxy implementation in the Java stub code). The following attributes are used to define the proxy:

i d

The ID that you specify here is entered in the bean registry and can be used to reference the proxy instance from other beans.

ad d ress

4 63

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

The full address of the remote Web service that this proxy connects to.

servi ceC l ass

The fully-qualified class name of the Web service's SEI (you invoke methods on the proxy through the SEI).

Inject ing wit h t he proxy reference

To access the proxy instance, simply inject the proxy into one or more other beans defined in

XML. Given that the proxy ID has the value, custo merServi ceP ro xy, you can inject it into a bean property using the Spring pro perty element, as follows:

</bean>

The bean class that is being injected must have a corresponding setC usto merServi ce setter method—for example:

// Java

...

public class ClientInvoker implements Runnable {

...

public void setCustomerService(CustomerService customerService) {

this.customerService = customerService;

}

36.4 . INVOKE WS OPERAT IONS

Proxy int erface is SEI int erface

The proxy implements the SEI. Hence, to make remote procedure calls on the Web service, simply invoke the SEI methods on the proxy instance.

Invoking t he lookupCust omer operat ion

For example, the C usto merServi ce SEI exposes the l o o kupC usto mer method, which takes a customer ID as its argument and returns a C usto mer data object. Using the proxy instance, custo merServi ce, you can invoke the l o o kupC usto mer operation as follows:

// Java com.fusesource.demo.customer.Customer response

= customerService.lookupCustomer("1234");

4 64

CHAPT ER 36 . IMPLEMENT ING A WS CLIENT

log.info("Got back " + response.getFirstName() + " "

+ response.getLastName()

+ ", ph:" + response.getPhoneNumber() );

T he Client Invoker class

In the cxf-webi nars-jbo ss-fuse-6 . 2/custo mer-ws-cl i ent project, there is a

C l i entInvo ker class (located in

src/mai n/java/co m/fuseso urce/custo mer/cl i ent), which defines a continuous loop that invokes the l o o kupC usto mer operation.

When you are experimenting with the demonstration code in the latter chapters of this guide, you might need to modify the C l i entInvo ker class, possibly adding operation invocations.

36.5. DEPLOY T O AN OSGI CONT AINER

Overview

One of the options for deploying the WS client is to package it as an OSGi bundle and deploy it into an OSGi container such as Red Hat JBoss Fuse. Some of the advantages of an OSGi deployment include:

Bundles are a relatively lightweight deployment option (because dependencies can be shared between deployed bundles).

OSGi provides sophisticated dependency management, ensuring that only versionconsistent dependencies are added to the bundle's classpath.

Using t he Maven bundle plug-in

1. Change the packaging type to bund l e (by editing the value of the

pro ject/packag i ng element in the POM).

2. Add the Maven bundle plug-in to your POM file and configure it as appropriate.

Configuring the Maven bundle plug-in is quite a technical task (although the default settings are often adequate). For full details of how to customize the plug-in configuration, consult

Deploying into the OSGi Container and Managing OSGi Dependencies.

Sample bundle plug-in configurat ion

4 65

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

The following POM fragment shows a sample configuration of the Maven bundle plug-in, which is appropriate for the current example.

<?xml version= "1.0" ?>

...

<groupId> com.fusesource.byexample.cxf-webinars </groupId>

<artifactId> customer-ws-client </artifactId>

<name> customer-ws-client </name>

bund l e

</packaging>

...

<build>

...

<groupId> org.apache.felix

</groupId>

maven-bund l e-pl ug i n

</artifactId>

<Export-Package>

!com.fusesource.customer.client,

!com.fusesource.demo.customer,

!com.fusesource.demo.wsdl.customerservice

</Export-Package>

<Import-Package>

</Import-Package>

<DynamicImport-Package>

org.apache.cxf.*,

org.springframework.beans.*

</DynamicImport-Package>

</instructions>

</configuration>

</plugin>

...

</plugins>

</build>

</project>

Dynamic import s

D ynami cImpo rt-P ackag e element, however, you allow the OSGi container to figure out which Java classes are needed by the Spring XML code at run time.

4 66

CHAPT ER 36 . IMPLEMENT ING A WS CLIENT

No t e

In general, using D ynami cImpo rt-P ackag e headers is not recommended in

OSGi, because it short-circuits OSGi version checking. Normally, what should happen is that the Maven bundle plug-in lists the Java packages used at build time, along with their versions, in the Impo rt-P ackag e header. At deploy time, the OSGi container then checks that the available Java packages are compatible with the build time versions listed in the Impo rt-P ackag e header. With dynamic imports, this version checking cannot be performed.

Build and deploy t he client bundle

After you have configured the POM file, you can build the Maven project and install it in your local repository by entering the following command: mvn install

To deploy the client bundle, enter the following command at the containers command console: karaf@ root> install -s mvn:com.fusesource.byexample.cxfwebinars/customer-ws-client

No t e

Check t hat t he client is running

Assuming that you have already deployed the corresponding Web service into the OSGi container, you can verify that the client is successfully invoking WSDL operations by checking the log, as follows: karaf@ root> log:display -n 10

The client invokes an operation on the Web service once every second.

4 67

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 37. POJO-BASED ROUTE

37.1. PROCESSING MESSAGES IN POJO FORMAT

Overview

By default, the Camel CXF component marshals incoming Web service requests into the

POJO data form, where the In message body is encoded as a list of Java objects (one for each operation parameter). The POJO data format has advantages and disadvantages, as follows:

The big advantage of the POJO data format is that the operation parameters are encoded using the JAXB standard, which makes them easy to manipulate in Java.

The downside of the POJO data format, on the other hand, is that it requires that the

WSDL metadata is converted to Java in advance (as defined by the JAX-WS and JAXB mappings) and compiled into your application. This means that a POJO-based route is not very dynamic.

Demonst rat ion locat ion

The code presented in this chapter is taken from the following demonstration: cxf-webinars-jboss-fuse-6.2/custo mer-ws-camel -cxf-po jo

For details of how to download and install the demonstration code, see Chapter 33,

Figure 37.1, “ Sample POJO Route”

Camel CXF component

The Camel CXF component is an Apache CXF component that integrates Web services with routes. You can use it either to instantiate consumer endpoints (at the start of a route), which behave like Web service instances, or to instantiate producer endpoints (at any other points in the route), which behave like WS clients.

No t e

Camel CXF endpoints—which are instantiated using the cxf: cxfEnd po i nt XML element and are implemented by the Apache Camel project—are not to be confused with the Apache CXF JAX-WS endpoints—which are instantiated using the

jaxws: end po i nt XML element and are implemented by the Apache CXF project.

4 68

POJO dat a format

POJO data format is the default data format used by the Camel CXF component and it has the following characteristics:

CHAPT ER 37 . PO JO - BASED RO UT E

JAX-WS and JAXB stub code (as generated from the WSDL contract) must be provided.

The SOAP body is marshalled into a list of Java objects.

One Java object for each part or parameter of the corresponding WSDL operation.

The type of the message body is

o rg . apache. cxf. messag e. Messag eC o ntentsLi st.

The SOAP headers are converted into headers in the exchange's In message.

Implement ing and building a POJO rout e

To implement and build the demonstration POJO-based route, starting from scratch, you would perform the following steps:

1. Obtain a copy of the WSDL contract that is to be integrated into the route.

2. Generate the Java stub code from the WSDL contract using a WSDL-to-Java converter. This gives you the SEI, C usto merServi ce, and its related classes, such as C usto mer.

3. Instantiate the Camel CXF endpoint in Spring, using the cxf: cxfEnd po i nt element.

4. Implement the route in XML, where you can use the content-based router to sort requests by operation name.

5. Implement the operation processor beans, which are responsible for processing each operation. When implementing these beans, the message contents must be accessed in POJO data format.

Sample POJO rout e

shows an outline of the route that is used to process the operations of the C usto merServi ce Web service using the POJO data format. After sorting the request messages by operation name, an operation-specific processor bean reads the incoming request parameters and then generates a response in the POJO data format.

Fig u re 37.1. Samp le PO JO Ro u t e

4 69

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

4 70

37.2. WSDL-T O-JAVA MAVEN PLUG-IN

Overview

Configure t he WSDL-t o-Java Maven plug-in

CXF version—make sure that the plug-in's dependencies are using the latest version of

Apache CXF.

WSDL file location—specify the WSDL file location in the

co nfi g urati o n/wsd l O pti o ns/wsd l O pti o n/wsd l element.

Location of output—specify the root directory of the generated Java source files in the

co nfi g urati o n/so urceR o o t element.

For example, the following POM fragment shows how to configure the cxf-co d eg en-

pl ug i n plug-in to generate Java stub code from the C usto merServi ce. wsd l WSDL file:

...

<groupId>com.fusesource.byexample.cxf-webinars</groupId>

<artifactId>cxf-webinars</artifactId>

CHAPT ER 37 . PO JO - BASED RO UT E

<version>1.0-SNAPSHOT</version>

</parent>

<build>

<defaultGoal>install</defaultGoal>

...

<groupId>org.apache.cxf</groupId>

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

<id>generate-sources</id>

<phase>generate-sources</phase>

<sourceRoot>${based i r}/targ et/g enerated -

so urces/jaxws</sourceRoot>

<wsdl>${based i r}/. . /src/mai n/reso urces/wsd l /C usto merServi ce. wsd l </wsd l>

</wsdlOption>

</wsdlOptions>

</configuration>

<goals>

</goals>

</execution>

</executions>

</plugin>

</plugins>

</build>

</project>

Generat ed Java source code

With the sample configuration shown here, the generated Java source code is written under the targ et/g enerated -so urces/jaxws directory. Note that the route is dependent on this generated stub code—for example, when processing the POJO parameters, the parameter processor uses the C usto mer data type from the stub code.

Add generat ed code t o IDE

If you are using an IDE such as Eclipse or Intellij's IDEA, you need to make sure that the IDE is aware of the generated Java code. For example, in Eclipse it is necessary to add the

targ et/g enerated -so urces/jaxws directory to the project as a source code directory.

Compiling t he generat ed code

4 71

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

You must ensure that the generated Java code is compiled and added to the deployment package. By convention, Maven automatically compiles any source files that it finds under the following directory:

BaseDir/target/generated-sources/

Hence, if you configure the output directory as shown in the preceding POM fragment, the generated code is automatically compiled by Maven.

Reference

For full details of how to configure the Java-to-WSDL plug-in, see the Maven cxf-codegenplugin reference page.

37.3. INST ANT IAT E T HE WS ENDPOINT

Overview

In Apache Camel, the Camel CXF component is the key to integrating routes with Web services. You can use the Camel CXF component to create a CXF endpoint, which can be used in either of the following ways:

Consumer—(at the start of a route) represents a Web service instance, which integrates with the route. The type of payload injected into the route depends on the value of the endpoint's d ataFo rmat option.

Producer—(at other points in the route) represents a WS client proxy, which converts the current exchange object into an operation invocation on a remote Web service. The format of the current exchange must match the endpoint's d ataFo rmat setting.

In the current demonstration, we are interested in creating a Camel CXF consumer endpoint, with the d ataFo rmat option set to POJO.

Maven dependency

The Camel CXF component requires you to add a dependency on the camel -cxf component in your Maven POM. For example, the po m. xml file from the custo mer-ws-

camel -cxf-po jo demonstration project includes the following dependency:

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

<artifactId>camel-cxf</artifactId>

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

</dependency>

T he cxf:bean: URI synt ax

4 72

CHAPT ER 37 . PO JO - BASED RO UT E

The cxf: bean: URI is used to bind an Apache CXF endpoint to a route and has the following general syntax: cxf:bean:CxfEndpointID[?Options]

Where CxfEndpointID is the ID of a bean created using the cxf: cxfEnd po i nt element, which configures the details of the WS endpoint. You can append options to this URI (where the options are described in detail in chapter "CXF" in "Apache Camel Component

Reference" ). If you do not specify any additional options, the endpoint uses the POJO data

format by default.

For example, to start a route with a Apache CXF endpoint that is configured by the bean with

ID, custo mer-ws, define the route as follows:

<route>

...

</route>

No t e

There is an alternative URI syntax, cxf: //WsAddress[?Options], which enables you to specify all of the WS endpoint details in the URI (so there is no need to reference a bean instance). This typically results in a long and cumbersome URI, but is useful in some cases.

T he cxf:cxfEndpoint element

The cxf: cxfEnd po i nt element is used to define a WS endpoint that binds either to the start (consumer endpoint) or the end (producer endpoint) of a route. For example, to define the custo mer-ws WS endpoint referenced in the preceding route, you would define a

cxf: cxfEnd po i nt element as follows:

<?xml version="1.0" encoding="UTF-8"?>

<beans ...

xmlns:cxf="http://camel.apache.org/schema/cxf" ...>

...

<cxf:cxfEndpoint id="custo mer-ws"

ad d ress= "/C usto mer"

endpointName="c:SOAPOverHTTP"

serviceName="c:CustomerService" serviceClass="com.fusesource.demo.wsdl.customerservice.CustomerService"

xmlns:c="http://demo.fusesource.com/wsdl/CustomerService/"/>

...

</beans>

4 73

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Imp o rt an t

Remember that the cxf: cxfEnd po i nt element and the jaxws: end po i nt element use different XML schemas (although the syntax looks superficially similar).

These elements bind a WS endpoint in different ways: the cxf: cxfEnd po i nt element instantiates and binds a WS endpoint to an Apache Camel route, whereas the jaxws: end po i nt element instantiates and binds a WS endpoint to a Java class using the JAX-WS mapping.

Address for t he Jet t y cont ainer

Apache CXF deploys the WS endpoint into a Jetty servlet container instance and the

ad d ress attribute of cxf: cxfEnd po i nt is therefore used to configure the addressing information for the endpoint in the Jetty container.

Address syntax for default servlet container—to use the default servlet container, specify only the servlet context for this endpoint. Do not specify the protocol, host, and IP port in the address. For example, to deploy the endpoint to the /C usto mer servlet context in the default servlet container: address="/Customer"

Address syntax for custom servlet container—to instantiate a custom Jetty container for this endpoint, specify a complete HTTP URL, including the host and IP port (the value of the

No t e

If you want to configure a secure endpoint (secured by SSL), you would specify the https: scheme in the address.

Referencing t he SEI

4 74

CHAPT ER 37 . PO JO - BASED RO UT E

The servi ceC l ass attribute of the cxf: cxfEnd po i nt element references the SEI of the

Web service, which in this case is the C usto merServi ce interface.

37.4 . SORT MESSAGES BY OPERAT ION NAME

T he operat ionName header

When the WS endpoint parses an incoming operation invocation in POJO mode, it automatically sets the o perati o nName header to the name of the invoked operation. You can then use this header to sort messages by operation name.

Sort ing by operat ion name

For example, the custo mer-ws-camel -cxf-po jo demonstration defines the following route, which uses the content-based router pattern to sort incoming messages, based on the operation name. The when predicates check the value of the o perati o nName header using simple language expressions, sorting messages into invocations on the upd ateC usto mer operation, the l o o kupC usto mer operation, or the g etC usto merStatus operation.

...

<route>

<when>

<simple>${in.header.operationName} ==

'updateCustomer'</simple>

</when>

<when>

<simple>${in.header.operationName} ==

'lookupCustomer'</simple>

</when>

<when>

<simple>${in.header.operationName} ==

'getCustomerStatus'</simple>

</when>

</choice>

</route>

</camelContext>

<bean id="getCustomerStatus" class="com.fusesource.customerwscamelcxfpojo.GetCustomerStatusProcessor

4 75

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

"/>

</beans>

4 76

Beans as endpoint s

Note how the preceding route uses a convenient shortcut to divert each branch of the

cho i ce DSL to a different processor bean. The DSL for sending exchanges to producer endpoints (for example, <to uri = "Destination"/>) is integrated with the bean registry: if the Destination does not resolve to an endpoint or a component, the Destination is used as a bean ID to look up the bean registry. In this example, the exchange is routed to processor beans (which implement the o rg . apache. camel . P ro cesso r interface).

37.5. PROCESS OPERAT ION PARAMET ERS

Overview

The most important characteristic of using Camel CXF in POJO mode is that the exchange's message body contains a list of Java objects, representing the parameters of the WSDL operation. The types of the Java objects are defined by the standard JAXB mapping and the implementations of these parameter types are provided by the Java stub code.

Cont ent s of request message body

In POJO mode, the body of the request message is an

o rg . apache. cxf. messag e. Messag eC o ntentsLi st object. You can also obtain the message body as an O bject[] array (where type conversion is automatic).

When the body is obtained as an O bject[] array, the array contains the list of all the operation's IN, INOUT, and OUT parameters in exactly the same order as defined in the WSDL

contract (and in the same order as the corresponding operation signature of the SEI). The parameter mode affects the content as follows:

INO UT

Contains a parameter value from the client.

Contains a Ho l d er object containing a parameter value from the client.

O UT

Contains an empty Ho l d er object, which is a placeholder for the response.

CHAPT ER 37 . PO JO - BASED RO UT E

No t e

Unlike OUT parameters, there is no placeholder in the request's O bject[] array to represent a return value.

Cont ent s of response message body

In POJO mode, the body of the response message can be either an

o rg . apache. cxf. messag e. Messag eC o ntentsLi st object or an O bject[] array.

When setting the response body as an O bject[] array, the array should contain only the operation's INOUT and OUT parameters in the same order as defined in the WSDL contract, omitting the IN parameters. The parameter mode affects the content as follows:

INO UT

Contains a Ho l d er object, which you must set to a response value. The Ho l d er object used here must be exactly the Holder object for the corresponding parameter that

was extracted from the request Object[] array. Creating and inserting a new Ho l d er object into the O bject[] array does not work.

O UT

Contains a Ho l d er object, which you must initialize with a response value. The

Ho l d er object used here must be exactly the Holder object for the corresponding

parameter that was extracted from the request Object[] array. Creating and inserting a new Ho l d er object into the O bject[] array does not work.

No t e

If you defined the Web service interface using the Java-first approach, note that the return value (if any) must be set as the first element in the response's O bject[] array. The return type is set as a plain object: it does not use a Ho l d er object.

Example: get Cust omerSt at us operat ion

For example, the g etC usto merStatus operation takes three parameters: IN, OUT, and OUT, respectively. The corresponding method signature in the SEI is, as follows:

// Java public void getCustomerStatus(

@ WebParam(name = "customerId", targetNamespace = "")

java.lang.String customerId,

@ WebParam(mode = WebParam.Mode.OUT, name = "status", targetNamespace = "")

javax.xml.ws.Holder<java.lang.String> status,

4 77

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

@ WebParam(mode = WebParam.Mode.OUT, name = "statusMessage", targetNamespace = "")

javax.xml.ws.Holder<java.lang.String> statusMessage

);

Example: request and response bodies

For the g etC usto merStatus operation, the bodies of the request message and the response message have the following contents:

Request message—as an O bject[] array type, the contents are: { Stri ng

custo merId , Ho l d er<Stri ng > status, Ho l d er<Stri ng > statusMessag e }.

Response message—as an O bject[] array type, the contents are: {Ho l d er<Stri ng >

status, Ho l d er<Stri ng > statusMessag e }

Example: processing get Cust omerSt at us

The G etC usto merStatusP ro cesso r class is responsible for processing incoming

g etC usto merStatus invocations. The following sample implementation for POJO mode shows how to read the request parameters from the In message body and then set the response parameters in the Out message body.

// Java package com.fusesource.customerwscamelcxfpojo; import javax.xml.ws.Holder; import org.apache.camel.Exchange; import org.apache.camel.Processor; import org.slf4j.Logger; import org.slf4j.LoggerFactory; public class GetCustomerStatusProcessor implements Processor {

public static final Logger log =

LoggerFactory.getLogger(GetCustomerStatusProcessor.class);

public void process(Exchange exchng) throws Exception {

Object[] args = exchng.getIn().getBody(Object[].class);

String id = (String) args[0];

Holder<String> status = (Holder<String>) args[1];

Holder<String> statusMsg = (Holder<String>) args[2];

log.debug("Getting status for customer '" + id + "'");

// This is where you'd actually do the work! Setting

// the holder values to constants for the sake of brevity.

status.value = "Offline";

statusMsg.value = "Going to sleep now!";

4 78

CHAPT ER 37 . PO JO - BASED RO UT E

exchng.getOut().setBody(new Object[] {status , statusMsg});

}

37.6. DEPLOY T O OSGI

Overview

One of the options for deploying the POJO-based route is to package it as an OSGi bundle and deploy it into an OSGi container such as Red Hat JBoss Fuse. Some of the advantages of an OSGi deployment include:

Bundles are a relatively lightweight deployment option (because dependencies can be shared between deployed bundles).

OSGi provides sophisticated dependency management, ensuring that only versionconsistent dependencies are added to the bundle's classpath.

Using t he Maven bundle plug-in

1. Change the packaging type to bund l e (by editing the value of the

pro ject/packag i ng element in the POM).

2. Add the Maven bundle plug-in to your POM file and configure it as appropriate.

Configuring the Maven bundle plug-in is quite a technical task (although the default settings are often adequate). For full details of how to customize the plug-in configuration, consult

Deploying into the OSGi Container and Managing OSGi Dependencies.

Sample bundle plug-in configurat ion

The following POM fragment shows a sample configuration of the Maven bundle plug-in, which is appropriate for the current example.

<?xml version="1.0"?>

...

<groupId>com.fusesource.byexample.cxf-webinars</groupId>

<artifactId>customer-ws-camel-cxf-pojo</artifactId>

<name>customer-ws-camel-cxf-pojo</name>

4 79

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

<packag i ng >bund l e</packag i ng >

...

<build>

...

<groupId>org.apache.felix</groupId>

<artifactId>maven-bundle-plugin</artifactId>

<Import-Package>

</Import-Package>

<DynamicImport-Package>

org.apache.cxf.*,

org.springframework.beans.*

</DynamicImport-Package>

</instructions>

</configuration>

</plugin>

...

</plugins>

</build>

</project>

Dynamic import s

D ynami cImpo rt-P ackag e element, however, you allow the OSGi container to figure out which Java classes are needed by the Spring XML code at run time.

No t e

In general, using D ynami cImpo rt-P ackag e headers is not recommended in

OSGi, because it short-circuits OSGi version checking. Normally, what should happen is that the Maven bundle plug-in lists the Java packages used at build time, along with their versions, in the Impo rt-P ackag e header. At deploy time, the OSGi container then checks that the available Java packages are compatible with the build time versions listed in the Impo rt-P ackag e header. With dynamic imports, this version checking cannot be performed.

Build and deploy t he POJO rout e bundle

4 80

After you have configured the POM file, you can build the Maven project and install it in your local repository by entering the following command: mvn install

CHAPT ER 37 . PO JO - BASED RO UT E

To deploy the route bundle, enter the following command at the JBoss Fuse console: karaf@ root> install -s mvn:com.fusesource.byexample.cxfwebinars/customer-ws-camel-cxf-pojo

No t e

4 81

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 38. PAYLOAD-BASED ROUTE

38.1. PROCESSING MESSAGES IN PAYLOAD FORMAT

Overview

Select the PAYLOAD format, if you want to access the SOAP message body in XML format, encoded as a DOM object (that is, of o rg . w3c. d o m. No d e type). One of the advantages of the PAYLOAD format is that no JAX-WS and JAXB stub code is required, which allows your application to be dynamic, potentially handling many different WSDL interfaces.

Having a message body in XML format enables you to parse the request using XML languages such as XPath and to generate responses using templating languages, such as

Velocity.

No t e

The DOM format is not the optimal type to use for large XML message bodies. For

large messages, consider using the techniques described in Chapter 39, Provider-

Based Route

Demonst rat ion locat ion

The code presented in this chapter is taken from the following demonstration: cxf-webinars-jboss-fuse-6.2/custo mer-ws-camel -cxf-payl o ad

For details of how to download and install the demonstration code, see Chapter 33,

Figure 38.1, “ Sample PAYLOAD Route”

Camel CXF component

No t e

Came CXF endpoints—which are instantiated using the cxf: cxfEnd po i nt XML element and are implemented by the Apache Camel project—are not to be confused with the Apache CXF JAX-WS endpoints—which are instantiated using the

jaxws: end po i nt XML element and are implemented by the Apache CXF project.

PAYLOAD dat a format

4 82

CHAPT ER 38 . PAYLO AD- BASED RO UT E

The PAYLOAD data format is selected by setting the d ataFo rmat= P AY LO AD option on a

Camel CXF endpoint URI and it has the following characteristics:

Enables you to access the message body as a DOM object (XML payload).

No JAX-WS or JAXB stub code required.

The SOAP body is marshalled as follows:

The message body is effectively an XML payload of o rg . w3c. d o m. No d e type

(wrapped in a C xfP ayl o ad object).

The type of the message body is

o rg . apache. camel . co mpo nent. cxf. C xfP ayl o ad .

The SOAP headers are converted into headers in the exchange's In message, of

o rg . apache. cxf. bi nd i ng . so ap. So apHead er type.

Implement ing and building a PAYLOAD rout e

To implement and build the demonstration PAYLOAD-based route, starting from scratch, you would perform the following steps:

1. Instantiate the Camel CXF endpoint in Spring, using the cxf: cxfEnd po i nt element.

2. Implement the route in XML, where you can use the content-based router to sort requests by operation name.

3. For each operation, define a processor bean to process the request.

4. Define velocity templates for generating the reponse messages.

Sample PAYLOAD rout e

shows an outline of the route that is used to process the operations of the C usto merServi ce Web service using the PAYLOAD data format. After sorting the request messages by operation name, an operation-specific processor bean reads the incoming request parameters. Finally, the response messages are generated using

Velocity templates.

Fig u re 38.1. Samp le PAYLO AD Ro u t e

4 83

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

4 84

38.2. INST ANT IAT E T HE WS ENDPOINT

Overview

In Apache Camel, the CXF component is the key to integrating routes with Web services. You can use the CXF component to create two different kinds of endpoint:

Consumer endpoint—(at the start of a route) represents a Web service instance, which integrates with the route. The type of payload injected into the route depends on the value of the endpoint's d ataFo rmat option.

Producer endpoint—represents a special kind of WS client proxy, which converts the current exchange object into an operation invocation on a remote Web service. The format of the current exchange must match the endpoint's d ataFo rmat setting.

T he cxf:bean: URI synt ax

The cxf: bean: URI is used to bind an Apache CXF endpoint to a route and has the following general syntax: cxf:bean:CxfEndpointID[?Options]

Reference" ). To enable payload mode, you must set the URI option,

d ataFo rmat= P AY LO AD .

For example, to start a route with an endpoint in PAYLOAD mode, where the endpoint is configured by the custo mer-ws bean, define the route as follows:

<route>

...

</route>

CHAPT ER 38 . PAYLO AD- BASED RO UT E

T he cxf:cxfEndpoint element

The cxf: cxfEnd po i nt element is used to define a WS endpoint that binds either to the start (consumer endpoint) or the end (producer endpoint) of a route. For example, to define the custo mer-ws WS endpoint in PAYLOAD mode, you define a cxf: cxfEnd po i nt element as follows:

<?xml version="1.0" encoding="UTF-8"?>

...

<cxf:cxfEndpoint id="customer-ws"

ad d ress= "/C usto mer"

endpointName="c:SOAPOverHTTP"

serviceName="c:CustomerService"

wsd l UR L= "wsd l /C usto merServi ce. wsd l "

xmlns:c="http://demo.fusesource.com/wsdl/CustomerService/"/>

...

</beans>

No t e

In the case of PAYLOAD mode, you do not need to reference the SEI and you must specify the WSDL location instead. In fact, in PAYLOAD mode, you do not require any Java stub code at all.

Address for t he Jet t y cont ainer

Apache CXF deploys the WS endpoint into a Jetty servlet container instance and the

ad d ress attribute of cxf: cxfEnd po i nt is therefore used to configure the addressing information for the endpoint in the Jetty container.

Apache CXF supports the notion of a default servlet container instance. The way the default servlet container is initialized and configured depends on the particular mode of deployment that you choose. For example the OSGi container and Web containers (such as Tomcat) provide a default servlet container.

Address syntax for default servlet container—to use the default servlet container, specify only the servlet context for this endpoint. Do not specify the protocol, host, and IP port in the address. For example, to deploy the endpoint to the /C usto mer servlet context in the default servlet container: address="/Customer"

Address syntax for custom servlet container—to instantiate a custom Jetty container for this endpoint, specify a complete HTTP URL, including the host and IP port (the value of the

4 85

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

No t e

If you want to configure a secure endpoint (secured by SSL), you would specify the https: scheme in the address.

Specifying t he WSDL locat ion

The wsd l UR L attribute of the cxf: cxfEnd po i nt element is used to specify the location of the WSDL contract for this endpoint. The WSDL contract is used exclusively as the source of metadata for this endpoint: there is need to specify an SEI in PAYLOAD mode.

38.3. SORT MESSAGES BY OPERAT ION NAME

T he operat ionName header

When the WS endpoint parses an incoming operation invocation in PAYLOAD mode, it automatically sets the o perati o nName header to the name of the invoked operation. You can then use this header to sort messages by operation name.

Sort ing by operat ion name

For example, the custo mer-ws-camel -cxf-payl o ad demonstration defines the following route, which uses the content-based router pattern to sort incoming messages, based on the operation name. The when predicates check the value of the o perati o nName header using simple language expressions, sorting messages into invocations on the upd ateC usto mer operation, the l o o kupC usto mer operation, or the g etC usto merStatus operation.

...

<route>

<when>

<simple>${in.header.operationName} ==

'updateCustomer'</simple>

...

</when>

<when>

<simple>${in.header.operationName} ==

4 86

CHAPT ER 38 . PAYLO AD- BASED RO UT E

'lookupCustomer'</simple>

...

</when>

<when>

<simple>${in.header.operationName} ==

'getCustomerStatus'</simple>

...

</when>

</choice>

</route>

</camelContext>

</beans>

38.4 . SOAP/HT T P-T O-JMS BRIDGE USE CASE

Overview

In this section, we consider a SOAP/HTTP-to-JMS bridge use case: that is, you want to create a route that transforms a synchronous operation invocation (over SOAP/HTTP) into an asynchronous message delivery (by pushing the message onto a JMS queue). In this way, it becomes possible to process the incoming operation invocations at a later time, by pulling messages off the JMS queue.

Of course, an alternative solution would be to modify the WSDL contract directly to declare the operation as OneWay, thus making the operation asynchronous. Unfortunately, it is often impractical to modify existing WSDL contracts in the real world, because this can have an impact on third-party applications.

Figure 38.2, “ SOAP/HTTP-to-JMS Bridge” shows the general outline of a bridge that can

transform synchronous SOAP/HTTP invocations into asynchronous JMS message deliveries.

Fig u re 38.2. SO AP/HT T P- t o - JMS Brid g e

T ransforming RPC operat ions t o One Way

4 87

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

As shown in Figure 38.2, “ SOAP/HTTP-to-JMS Bridge”

, the route for transforming synchronous SOAP/HTTP to asynchronous JMS works as follows:

1. The WS client invokes a synchronous operation on the Camel CXF endpoint at the start of the route. The Camel CXF endpoint then creates an initial InOut exchange at the start of the route, where the body of the exchange message contains a payload in

XML format.

2. The i nO nl y DSL command pushes a copy of the XML payload onto a JMS queue, so that it can be processed offline at some later time.

3. The transfo rm DSL command constructs an immediate response to send back to the client, where the response has the form of an XML string.

4. The Camel CXF component supports implicit type conversion of the XML string to payload format.

5. The response is sent back to the WS client, thus completing the synchronous operation invocation.

Evidently, this transformation can only work, if the original operation invocation has no return value. Otherwise, it would be impossible to generate a response message before the request has been processed.

Creat ing a broker inst ance

You can use Apache ActiveMQ as the JMS implementation. A convenient approach to use in this demonstration is to embed the Apache ActiveMQ broker in the bridge bundle. Simply define an amq : bro ker element in the Spring XML file, as follows:

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

...

xmlns:amq="http://activemq.apache.org/schema/core"

...>

<amq:broker brokerName="CxfPayloadDemo" persistent="false">

<amq:transportConnectors>

<amq:transportConnector name="openwire" uri="tcp://localhost:51616"/>

<amq:transportConnector name="vm" uri="vm:local"/>

</amq:transportConnectors>

</amq:broker>

...

</beans>

4 88

CHAPT ER 38 . PAYLO AD- BASED RO UT E

No t e

This broker instance is created with the persi stent attribute set to fal se, so that the messages are stored only in memory.

Configuring t he JMS component

Because the broker is co-located with the bridge route (in the same JVM), the most efficient way to connect to the broker is to use the VM (Virtual Machine) transport. Configure the

Apache ActiveMQ component as follows, to connect to the co-located broker using the VM protocol:

...

</bean>

...

</beans>

No t e

By defining the bean with an i d value of acti vemq , you are implicitly overriding the component associated with the endpoint URI prefix, acti vemq : . In other words, your custom Acti veMQ C o mpo nent instance is used instead of the default

Acti veMQ C o mpo nent instance from the camel -acti vemq JAR file.

Sample SOAP/HT T P-t o-JMS rout e

For example, you could define a route that implements the SOAP/HTTP-to-JMS bridge specifically for the upd ateC usto mer operation from the C usto merServi ce SEI, as follows:

<when>

<simple>${in.header.operationName} == 'updateCustomer'</simple>

<![CDATA[

<ns2:updateCustomerResponse xmlns:ns2="http://demo.fusesource.com/wsdl/CustomerService/"/>

]]>

</constant>

</transform>

</when>

Sending t o t he JMS endpoint in inOnly mode

4 89

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Note how the message payload is sent to the JMS queue using the i nO nl y DSL command instead of the to DSL command. When you send a message using the to DSL command, the default behavior is to use the same invocation mode as the current exchange. But the current exchange has an InOut MEP, which means that the to DSL command would wait forever for a response message from JMS.

The invocation mode we want to use when sending the payload to the JMS queue is InOnly

(asynchronous), and we can force this mode by inserting the i nO nl y DSL command into the route.

No t e

By specifying the option, jmsMessag eT ype= T ext, Camel CXF implicitly converts the message payload to an XML string before pushing it onto the JMS queue.

Ret urning a lit eral response value

The transfo rm DSL command uses an expression to set the body of the exchange's Out message and this message is then used as the response to the client. Your first impulse when defining a response in XML format might be to use a DOM API, but in this example, the response is specified as a string literal. This approach has the advantage of being both efficient and very easy to program.

The final step of processing, which consists of converting the XML string to a DOM object, is performed by Apache Camel's implicit type conversion mechanism.

38.5. GENERAT ING RESPONSES USING T EMPLAT ES

Overview

One of the simplest and quickest approaches to generating a response message is to use a

velocity template. Figure 38.3, “ Response Generated by Velocity” shows the outline of a

general template-based route. At the start of the route is a Camel CXF endpoint in PAYLOAD mode, which is the appropriate mode to use for processing the message as an XML document. After doing the work required to process the message and stashing some intermediate results in message headers, the route generates the response message using a

Velocity template.

Fig u re 38.3. Resp o n se G en erat ed b y Velo cit y

4 90

CHAPT ER 38 . PAYLO AD- BASED RO UT E

Sample t emplat e-based rout e

For example, you could define a template-based route specifically for the

g etC usto emrStatus operation, as follows:

...

<when>

<simple>${in.header.operationName} ==

'getCustomerStatus'</simple>

<xpath>/cus:getCustomerStatus/customerId/text()</xpath>

</setHeader>

</when>

</choice>

</route>

</camelContext

...

Rout e processing st eps

Given the preceding route definition, any message whose operation name matches

g etC usto merStatus would be processed as follows:

1. To facilitate processing the payload body, the first step uses co nvertBo d yT o to convert the body type from o rg . apache. camel . co mpo nent. cxf. C xfP ayl o ad

(the default payload type) to o rg . w3c. d o m. No d e.

2. The route then applies an XPath expression to the message in order to extract the customer ID value and then stashes it in the custo merId header.

3. The next step sends the message to the g etC usto merStatus bean, which does whatever processing is required to get the customer status for the specified customer

ID. The results from this step are stashed in message headers.

4. Finally, a response is generated using a velocity template.

No t e

A common pattern when implementing Apache Camel routes is to use message headers as a temporary stash to hold intermediate results (you could also use exchange properties in the same way).

Convert ing XPat h result t o a st ring

4 91

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Because the default return type of XPath is a node list, you must explicitly convert the result to a string, if you want to obtain the string contents of an element. There are two alternative ways of obtaining the string value of an element:

Specify the result type explicitly using the resul tT ype attribute, as follows:

<xpath

resul tT ype= "java. l ang . Stri ng ">/cus:getCustomerStatus/customerId</xp ath>

Modify the expression so that it returns a text() node, which automatically converts to string:

<xpath>/cus:getCustomerStatus/customerId/text()</xpath>

get Cust omerSt at us processor bean

The g etC usto merStatus processor bean is an instance of the G etC usto merStatus processor class, which is defined as follows:

// Java package com.fusesource.customerwscamelcxfpayload; import org.apache.camel.Exchange; import org.apache.camel.Processor; public class GetCustomerStatus implements Processor

{

public void process(Exchange exchng) throws Exception {

String id = exchng.getIn().getHeader("customerId",

String.class);

// Maybe do some kind of lookup here!

exchng.getIn().setHeader("status", "Away");

exchng.getIn().setHeader("statusMessage", "Going to sleep.");

}

The implementation shown here is just a placeholder. In a realistic application you would perform some sort of checks or database lookup to obtain the customer status. In the demonstration code, however, the status and statusMessag e are simply set to constant values and stashed in message headers.

In the preceding code, we make the modifications directly to the In message. When the exchange's Out message is nul l , the next processor in the route gets a copy of the current

In message instead

4 92

CHAPT ER 38 . PAYLO AD- BASED RO UT E

No t e

An exceptional case occurs when the message exchange pattern is inOnly, in which case the Out message value is always copied into the In message, even if it is nul l .

get Cust omerSt at usResponse.vm Velocit y t emplat e

You can generate a response message very simply using a Velocity template. The Velocity template consists of a message in plain text, where specific pieces of data can be inserted using expressions—for example, the expression ${head er. HeaderName} substitutes the value of a named header.

The Velocity template for generating the g etC usto merStatus reponse is located in the

custo mer-ws-camel -cxf-payl o ad /src/mai n/reso urces directory and it contains the following template script:

<ns2:getCustomerStatusResponse xmlns:ns2="http://demo.fusesource.com/wsdl/CustomerService/">

<status>${headers.status}</status>

<statusMessage>${headers.statusMessage}</statusMessage>

</ns2:getCustomerStatusResponse>

38.6. T YPECONVERT ER FOR CXFPAYLOAD

Overview

Apache Camel supports a type converter mechanism, which is used to perform implicit and explicit type conversions of message bodies and message headers. The payload demonstration requires a customer type converter that can convert Stri ng objects to

C XFP ayl o ad objects. This type converter automatically gets invoked at the end of the

Camel route, when the generated response message (which is a Stri ng type) gets converted into a C XFP ayl o ad object.

St ring t o CXFPayload t ype convert er

The Stri ng to C XFP ayl o ad type converter is implemented in the

Ad d i ti o nal C xfP ayl o ad C o nverters class, as follows:

// Java package com.fusesource.customerwscamelcxfpayload; import java.io.ByteArrayInputStream; import java.io.StringWriter; import java.util.ArrayList; import java.util.List; import javax.xml.transform.OutputKeys; import javax.xml.transform.Transformer; import javax.xml.transform.TransformerFactory;

4 93

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

import javax.xml.transform.dom.DOMSource; import javax.xml.transform.stream.StreamResult; import org.apache.camel.Converter; import org.apache.camel.component.cxf.CxfPayload; import org.apache.cxf.binding.soap.SoapHeader; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.w3c.dom.Document; import org.w3c.dom.Element; import org.w3c.dom.Node;

@ Converter public class AdditionalCxfPayloadConverters {

...

@ Converter

public static CxfPayload<SoapHeader> to C xfP ayl o ad (String xml) {

// System.out.println("To CxfPayload " + xml);

List<Element> elements = new ArrayList<Element>();

try {

Document doc = b.newDocumentBuilder().parse(new

ByteArrayInputStream(xml.getBytes()));

elements.add(doc.getDocumentElement());

} catch (Exception ex) {

log.warn("Exception while converting String payload to

CxfPayload; resulting payload will be empty.");

}

// The CxfPayload is changed to use Source object under layer, the elements API only work if we already setup the list before creating the CxfPayload

CxfPayload<SoapHeader> ret = new CxfPayload<SoapHeader>(null, elements);

return ret;

}

...

}

Reference

For full details of the type converter mechanism in Apache Camel, see Section 42.3, “ Built-In

Type Converters” and Chapter 44, Type Converters .

38.7. DEPLOY T O OSGI

Overview

One of the options for deploying the payload-based route is to package it as an OSGi bundle and deploy it into an OSGi container such as Red Hat JBoss Fuse. Some of the advantages of an OSGi deployment include:

Bundles are a relatively lightweight deployment option (because dependencies can be shared between deployed bundles).

4 94

CHAPT ER 38 . PAYLO AD- BASED RO UT E

OSGi provides sophisticated dependency management, ensuring that only versionconsistent dependencies are added to the bundle's classpath.

Using t he Maven bundle plug-in

1. Change the packaging type to bund l e (by editing the value of the

pro ject/packag i ng element in the POM).

2. Add the Maven bundle plug-in to your POM file and configure it as appropriate.

Configuring the Maven bundle plug-in is quite a technical task (although the default settings are often adequate). For full details of how to customize the plug-in configuration, consult

Deploying into the OSGi Container and Managing OSGi Dependencies.

Sample bundle plug-in configurat ion

The following POM fragment shows a sample configuration of the Maven bundle plug-in, which is appropriate for the current example.

<?xml version="1.0"?>

...

<groupId>com.fusesource.byexample.cxf-webinars</groupId>

<artifactId>customer-ws-camel-cxf-payload</artifactId>

<name>customer-ws-camel-cxf-payload</name>

<packag i ng >bund l e</packag i ng >

...

<build>

...

<groupId>org.apache.felix</groupId>

<artifactId>maven-bundle-plugin</artifactId>

<Import-Package>

org.apache.camel.component.velocity,

javax.jws,

javax.wsdl,

javax.xml.bind,

javax.xml.bind.annotation,

javax.xml.namespace,

javax.xml.ws,

org.w3c.dom,

</Import-Package>

4 95

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

<DynamicImport-Package>

org.apache.cxf.*,

org.springframework.beans.*

</DynamicImport-Package>

</instructions>

</configuration>

</plugin>

...

</plugins>

</build>

</project>

Dynamic import s

D ynami cImpo rt-P ackag e element, however, you allow the OSGi container to figure out which Java classes are needed by the Spring XML code at run time.

No t e

In general, using D ynami cImpo rt-P ackag e headers is not recommended in

OSGi, because it short-circuits OSGi version checking. Normally, what should happen is that the Maven bundle plug-in lists the Java packages used at build time, along with their versions, in the Impo rt-P ackag e header. At deploy time, the OSGi container then checks that the available Java packages are compatible with the build time versions listed in the Impo rt-P ackag e header. With dynamic imports, this version checking cannot be performed.

Build and deploy t he client bundle

After you have configured the POM file, you can build the Maven project and install it in your local repository by entering the following command: mvn install

Install the camel -vel o ci ty feature, which is needed for this example: karaf@ root> features:install camel-velocity

To deploy the route bundle, enter the following command at the console: karaf@ root> install -s mvn:com.fusesource.byexample.cxfwebinars/customer-ws-camel-cxf-payload

4 96

CHAPT ER 38 . PAYLO AD- BASED RO UT E

No t e

If your local Maven repository is stored in a non-standard location, you might need to customize the value of the o rg . o ps4 j. pax. url . mvn. l o cal R epo si to ry property in the InstallDir/etc/o rg . o ps4 j. pax. url . mvn. cfg file, before you can use the mvn: scheme to access Maven artifacts.

4 97

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 39. PROVIDER-BASED ROUTE

39.1. PROVIDER-BASED JAX-WS ENDPOINT

Overview

Use the provider-based approach, if you need to process very large Web services messages.

The provider-based approach is a variant of the PAYLOAD data format that enables you to encode the message body as an XML streaming type, such as SAXSo urce. Since the

XMLstreaming types are more efficient than DOM objects, the provider-based approach is ideal for large XML messages.

Demonst rat ion locat ion

The code presented in this chapter is taken from the following demonstration: cxf-webinars-jboss-fuse-6.2/custo mer-ws-camel -cxf-pro vi d er

For details of how to download and install the demonstration code, see Chapter 33,

the section called “ The SAXSourceService provider class” ).

Camel CXF component

No t e

jaxws: end po i nt XML element and are implemented by the Apache CXF project.

Provider-based approach and t he PAYLOAD dat a format

The provider-based approach is a variant of the PAYLOAD data format, which is enabled as follows:

Define a custom javax. xml . ws. P ro vi d er<StreamType> class, where the

StreamType type is an XML streaming type, such as SAXSo urce.

The PAYLOAD data format is selected by an annotation on the custom P ro vi d er<?> class (see

4 98

CHAPT ER 39 . PRO VIDER- BASED RO UT E

The custom P ro vi d er<?> class is referenced by setting the servi ceC l ass attribute of the cxf: cxfEnd po i nt element in XML configuration.

The provider-based approach has the following characteristics:

Enables you to access the message body as a streamed XML type—for example,

javax. xml . transfo rm. sax. SAXSo urce.

No JAX-WS or JAXB stub code required.

The SOAP body is marshalled into a stream-based SAXSo urce type.

The SOAP headers are converted into headers in the exchange's In message, of

o rg . apache. cxf. bi nd i ng . so ap. So apHead er type.

Implement ing and building a provider-based rout e

To implement and build the demonstration provider-based route, starting from scratch, you would perform the following steps:

1. Define a custom javax. xml . ws. P ro vi d er<StreamType> class (the current demonstration uses SAXSo urce as the StreamType type).

2. Instantiate the Camel CXF endpoint in Spring, using the cxf: cxfEnd po i nt element and reference the custom provider class (using the servi ceC l ass attribute).

3. Implement the route in XML, where you can use the content-based router to sort requests by operation name.

4. For each operation, define a processor bean to process the request.

5. Define velocity templates for generating the reponse messages.

6. Define a custom type converter, to support converting a Stri ng message body to a

SAXSo urce message body.

Sample provider-based rout e

Figure 39.1, “ Sample Provider-Based Route”

shows an outline of the route that is used to process the operations of the C usto merServi ce Web service using the provider-based approach. After sorting the request messages by operation name, an operation-specific processor bean reads the incoming request parameters. Finally, the response messages are generated using Velocity templates.

Fig u re 39 .1. Samp le Pro vid er- Based Ro u t e

4 99

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

500

39.2. CREAT E A PROVIDER<?> IMPLEMENT AT ION CLASS

Overview

The fundamental prerequisite for using provider mode is to define a custom P ro vi d er<> class that implements the i nvo ke() method. In fact, the sole purpose of this class is to provide runtime type information for Apache CXF: the invoke() method never gets called!

By implementing the provider class in the way shown here, you are merely indicating to the

Apache CXF runtime that the WS endpoint should operate in in PAYLOAD mode and the type of the message PAYLOAD should be SAXSo urce.

T he SAXSourceService provider class

The definition of the provider class is relatively short and the complete definition of the customer provider class, SAXSo urceServi ce, is as follows:

// Java package com.fusesource.customerwscamelcxfprovider; import javax.xml.transform.sax.SAXSource; import javax.xml.ws.Provider; import javax.xml.ws.Service.Mode; import javax.xml.ws.ServiceMode; import javax.xml.ws.WebServiceProvider;

@ WebServiceProvider()

@ ServiceMode(Mode.PAYLOAD) public class SAXSourceService implements Provider<SAXSource>

{

public SAXSource invoke(SAXSource t) {

throw new UnsupportedOperationException("Not supported yet.");

}

CHAPT ER 39 . PRO VIDER- BASED RO UT E

The customer provider class, SAXSo urceServi ce, must be annotated by the

@ WebServi ceP ro vi d er annotation to mark it as a provider class and can be optionally annotated by the @ Servi ceMo d e annotation to select PAYLOAD mode.

39.3. INST ANT IAT E T HE WS ENDPOINT

Overview

In Apache Camel, the CXF component is the key to integrating routes with Web services. You can use the CXF component to create two different kinds of endpoint:

T he cxf:bean: URI synt ax

The cxf: bean: URI is used to bind an Apache CXF endpoint to a route and has the following general syntax: cxf:bean:CxfEndpointID[?Options]

Reference" ). Provider mode is essentially a variant of PAYLOAD mode: you could specify this mode on the URI (by setting d ataFo rmat= P AY LO AD ), but this is not necessary, because

PAYLOAD mode is already selected by the @ Servi ceMo d e annotation on the custom

P ro vi d er class.

For example, to start a route with an endpoint in provider mode, where the endpoint is configured by the custo mer-ws bean, define the route as follows:

<route>

...

</route>

T he cxf:cxfEndpoint element

501

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

The cxf: cxfEnd po i nt element is used to define a WS endpoint that binds either to the start (consumer endpoint) or the end (producer endpoint) of a route. For example, to define the custo mer-ws WS endpoint in provider mode, you define a cxf: cxfEnd po i nt element as follows:

<?xml version="1.0" encoding="UTF-8"?>

...

<cxf:cxfEndpoint id="customer-ws"

ad d ress= "/C usto mer"

endpointName="c:SOAPOverHTTP"

serviceName="c:CustomerService"

wsd l UR L= "wsd l /C usto merServi ce. wsd l "

servi ceC l ass= "co m. fuseso urce. custo merwscamel cxfpro vi d er. SAXSo urceSer vi ce"

xmlns:c="http://demo.fusesource.com/wsdl/CustomerService/"/>

...

</beans>

Specifying t he WSDL locat ion

The wsd l UR L attribute of the cxf: cxfEnd po i nt element is used to specify the location of the WSDL contract for this endpoint. The WSDL contract is used as the source of metadata for this endpoint.

Specifying t he service class

A key difference between provider mode and ordinary PAYLOAD mode is that the

servi ceC l ass attribute must be set to the provider class, SAXSo urceServi ce.

39.4 . SORT MESSAGES BY OPERAT ION NAME

T he operat ionName header

When the WS endpoint parses an incoming operation invocation in PROVIDER mode, it automatically sets the o perati o nName header to the name of the invoked operation. You can then use this header to sort messages by operation name.

Sort ing by operat ion name

For example, the custo mer-ws-camel -cxf-pro vi d er demonstration defines the following route, which uses the content-based router pattern to sort incoming messages, based on the operation name. The when predicates check the value of the o perati o nName header using simple language expressions, sorting messages into invocations on the

upd ateC usto mer operation, the l o o kupC usto mer operation, or the

g etC usto merStatus operation.

502

CHAPT ER 39 . PRO VIDER- BASED RO UT E

...

<route>

<when>

<simple>${in.header.operationName} ==

'updateCustomer'</simple>

...

</when>

<when>

<simple>${in.header.operationName} ==

'lookupCustomer'</simple>

...

</when>

<when>

<simple>${in.header.operationName} ==

'getCustomerStatus'</simple>

...

</when>

</choice>

</route>

</camelContext>

...

</beans>

39.5. SOAP/HT T P-T O-JMS BRIDGE USE CASE

Overview

Figure 39.2, “ SOAP/HTTP-to-JMS Bridge” shows the general outline of a bridge that can

transform synchronous SOAP/HTTP invocations into asynchronous JMS message deliveries.

Fig u re 39 .2. SO AP/HT T P- t o - JMS Brid g e

503

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

504

T ransforming RPC operat ions t o One Way

As shown in Figure 39.2, “ SOAP/HTTP-to-JMS Bridge”

, the route for transforming synchronous SOAP/HTTP to asynchronous JMS works as follows:

XML format.

2. The i nO nl y DSL command pushes a copy of the XML payload onto a JMS queue, so that it can be processed offline at some later time.

3. The transfo rm DSL command constructs an immediate response to send back to the client, where the response has the form of an XML string.

4. The route explicitly converts the XML string to the

javax. xml . transfo rm. sax. SAXSo urce type.

5. The response is sent back to the WS client, thus completing the synchronous operation invocation.

Creat ing a broker inst ance

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

...

CHAPT ER 39 . PRO VIDER- BASED RO UT E

xmlns:amq="http://activemq.apache.org/schema/core"

...>

<amq:broker brokerName="CxfPayloadDemo" persistent="false">

<amq:transportConnectors>

<amq:transportConnector name="openwire" uri="tcp://localhost:51616"/>

<amq:transportConnector name="vm" uri="vm:local"/>

</amq:transportConnectors>

</amq:broker>

...

</beans>

No t e

This broker instance is created with the persi stent attribute set to fal se, so that the messages are stored only in memory.

Configuring t he JMS component

Because the broker is co-located with the bridge route (in the same JVM), the most efficient way to connect to the broker is to use the VM (Virtual Machine) transport. Configure the

Apache ActiveMQ component as follows, to connect to the co-located broker using the VM protocol:

...

</bean>

...

</beans>

No t e

Acti veMQ C o mpo nent instance from the camel -acti vemq JAR file.

Sample SOAP/HT T P-t o-JMS rout e

For example, you could define a route that implements the SOAP/HTTP-to-JMS bridge specifically for the upd ateC usto mer operation from the C usto merServi ce SEI, as follows:

<when>

<simple>${in.header.operationName} == 'updateCustomer'</simple>

505

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

<![CDATA[

<ns2:updateCustomerResponse xmlns:ns2="http://demo.fusesource.com/wsdl/CustomerService/"/>

]]>

</constant>

</transform>

</when>

Sending t o t he JMS endpoint in inOnly mode

The invocation mode we want to use when sending the payload to the JMS queue is InOnly

(asynchronous), and we can force this mode by inserting the i nO nl y DSL command into the route.

No t e

By specifying the option, jmsMessag eT ype= T ext, Camel CXF implicitly converts the message payload to an XML string before pushing it onto the JMS queue.

Ret urning a lit eral response value

T ype conversion of t he response message

In this example, the reply message (like the request message) is required to be of type,

javax. xml . transfo rm. sax. SAXSo urce. In the last step of the route, therefore, you must convert the message body from Stri ng type to javax. xml . transfo rm. sax. SAXSo urce type, by invoking the co nvertBo d yT o DSL command.

The implementation of the String to SAXSo urce conversion is provided by a custom type converter, as described in

Section 39.7, “ TypeConverter for SAXSource” .

506

39.6. GENERAT ING RESPONSES USING T EMPLAT ES

CHAPT ER 39 . PRO VIDER- BASED RO UT E

Overview

One of the simples and quickest approaches to generating a response message is to use a

velocity template. Figure 39.3, “ Response Generated by Velocity” shows the outline of a

general template-based route. At the start of the route is a Camel CXF endpoint in provider mode, which is the appropriate mode to use for processing the message as an XML document. After doing the work required to process the message and stashing some intermediate results in message headers, the route generates the response message using a

Velocity template.

Fig u re 39 .3. Resp o n se G en erat ed b y Velo cit y

Sample t emplat e-based rout e

For example, you could define a template-based route specifically for the

g etC usto emrStatus operation, as follows:

...

<when>

<simple>${in.header.operationName} ==

'getCustomerStatus'</simple>

<xpath resultType="java.lang.String">/cus:getCustomerStatus/customerId</xpath

</setHeader>

</when>

</choice>

</route>

</camelContext

...

Rout e processing st eps

507

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Given the preceding route definition, any message whose operation name matches

g etC usto merStatus would be processed as follows:

1. The route applies an XPath expression to the message in order to extract the customer ID value and then stashes it in the custo merId header.

2. The next step sends the message to the g etC usto merStatus bean, which does whatever processing is required to get the customer status for the specified customer

ID. The results from this step are stashed in message headers.

3. A response is generated using a Velocity template.

4. Finally, the XML string generated by the Velocity template must be explicitly converted to the javax. xml . transfo rm. sax. SAXSo urce type using co nvertBo d yT o

(which implicitly relies on a type converter).

No t e

A common pattern when implementing Apache Camel routes is to use message headers as a temporary stash to hold intermediate results (you could also use exchange properties in the same way).

XPat h expressions and SAXSource

XPath expressions can be applied directly to SAXSource objects. The XPath implementation has a pluggable architecture that supports a variety of XML parsers and when XPath encounters a SAXSource object, it automatically loads the plug-in required to support

SAXSource parsing.

get Cust omerSt at us processor bean

The g etC usto merStatus processor bean is an instance of the G etC usto merStatus processor class, which is defined as follows:

// Java package com.fusesource.customerwscamelcxfpayload; import org.apache.camel.Exchange; import org.apache.camel.Processor; public class GetCustomerStatus implements Processor

{

public void process(Exchange exchng) throws Exception {

String id = exchng.getIn().getHeader("customerId",

String.class);

// Maybe do some kind of lookup here!

508

CHAPT ER 39 . PRO VIDER- BASED RO UT E

exchng.getIn().setHeader("status", "Away");

exchng.getIn().setHeader("statusMessage", "Going to sleep.");

}

get Cust omerSt at usResponse.vm Velocit y t emplat e

The Velocity template for generating the g etC usto merStatus reponse is located in the

custo mer-ws-camel -cxf-pro vi d er/src/mai n/reso urces directory and it contains the following template script:

<ns2:getCustomerStatusResponse xmlns:ns2="http://demo.fusesource.com/wsdl/CustomerService/">

<status>${headers.status}</status>

<statusMessage>${headers.statusMessage}</statusMessage>

</ns2:getCustomerStatusResponse>

39.7. T YPECONVERT ER FOR SAXSOURCE

Overview

Apache Camel supports a type converter mechanism, which is used to perform implicit and explicit type conversions of message bodies and message headers. The type converter mechanism is extensible and it so happens that the provider demonstration requires a custom type converter that can convert Stri ng objects to SAXSo urce objects.

St ring t o SAXSource t ype convert er

The Stri ng to SAXSo urce type converter is implemented in the Ad d i ti o nal C o nverters class, as follows:

// Java package com.fusesource.customerwscamelcxfprovider; import java.io.ByteArrayInputStream; import javax.xml.transform.sax.SAXSource; import org.apache.camel.Converter; import org.xml.sax.InputSource;

509

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

@ Converter public class AdditionalConverters {

@ Converter

public static SAXSource toSAXSource(String xml) {

return new SAXSource(new InputSource(new

ByteArrayInputStream(xml.getBytes())));

}

Reference

For full details of the type converter mechanism in Apache Camel, see Section 42.3, “ Built-In

Type Converters” and Chapter 44, Type Converters .

39.8. DEPLOY T O OSGI

Overview

One of the options for deploying the provider-based route is to package it as an OSGi bundle and deploy it into an OSGi container such as Red Hat JBoss Fuse. Some of the advantages of an OSGi deployment include:

Bundles are a relatively lightweight deployment option (because dependencies can be shared between deployed bundles).

OSGi provides sophisticated dependency management, ensuring that only versionconsistent dependencies are added to the bundle's classpath.

Using t he Maven bundle plug-in

1. Change the packaging type to bund l e (by editing the value of the

pro ject/packag i ng element in the POM).

2. Add the Maven bundle plug-in to your POM file and configure it as appropriate.

Configuring the Maven bundle plug-in is quite a technical task (although the default settings are often adequate). For full details of how to customize the plug-in configuration, consult

Deploying into the OSGi Container and Managing OSGi Dependencies.

Sample bundle plug-in configurat ion

510

CHAPT ER 39 . PRO VIDER- BASED RO UT E

The following POM fragment shows a sample configuration of the Maven bundle plug-in, which is appropriate for the current example.

<?xml version="1.0"?>

...

<groupId>com.fusesource.byexample.cxf-webinars</groupId>

<artifactId>customer-ws-camel-cxf-provider</artifactId>

<name>customer-ws-camel-cxf-provider</name>

<packag i ng >bund l e</packag i ng >

...

<build>

...

<groupId>org.apache.felix</groupId>

<artifactId>maven-bundle-plugin</artifactId>

<Import-Package>

org.apache.camel.component.velocity,

javax.jws,

javax.wsdl,

javax.xml.bind,

javax.xml.bind.annotation,

javax.xml.namespace,

javax.xml.ws,

org.w3c.dom,

</Import-Package>

<DynamicImport-Package>

org.apache.cxf.*,

org.springframework.beans.*

</DynamicImport-Package>

</instructions>

</configuration>

</plugin>

...

</plugins>

</build>

</project>

Dynamic import s

D ynami cImpo rt-P ackag e element, however, you allow the OSGi container to figure out which Java classes are needed by the Spring XML code at run time.

511

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

No t e

In general, using D ynami cImpo rt-P ackag e headers is not recommended in

OSGi, because it short-circuits OSGi version checking. Normally, what should happen is that the Maven bundle plug-in lists the Java packages used at build time, along with their versions, in the Impo rt-P ackag e header. At deploy time, the OSGi container then checks that the available Java packages are compatible with the build time versions listed in the Impo rt-P ackag e header. With dynamic imports, this version checking cannot be performed.

Build and deploy t he client bundle

After you have configured the POM file, you can build the Maven project and install it in your local repository by entering the following command: mvn install

To deploy the route bundle, enter the following command at the container console: karaf@ root> install -s mvn:com.fusesource.byexample.cxfwebinars/customer-ws-camel-cxf-provider

No t e

512

CHAPT ER 4 0 . PRO XYING A WEB SERVICE

CHAPTER 40. PROXYING A WEB SERVICE

Ab st ract

A common use case for the Camel CXF component is to use a route as a proxy for a Web service. That is, in order to perform additional processing of WS request and response messages, you interpose a route between the WS client and the original Web service.

4 0.1. PROXYING WIT H HT T P

Overview

The simplest way to proxy a SOAP/HTTP Web service is to treat the request and reply messages as HTTP packets. This type of proxying can be used where there is no requirement to read or modify the messages passing through the route. For example, you could use this kind of proxying to apply various patterns of flow control on the WS messges.

Figure 40.1, “ Proxy Route with Message in HTTP Format”

shows an overview of how to proxy a Web service using an Apache Camel route, where the route treats the messages as HTTP packets. The key feature of this route is that both the consumer endpoint (at the start of the route) and the producer endpoint (at the end of the route) must be compatible with the HTTP packet format.

Fig u re 4 0.1. Pro xy Ro u t e wit h Messag e in HT T P Fo rmat

Alt ernat ives for t he consumer endpoint

The following Apache Camel endpoints can be used as consumer endpoints for HTTP format messages:

Jetty endpoint—is a lightweight Web server. You can use Jetty to handle messages for any

HTTP-based protocol, including the commonly-used Web service SOAP/HTTP protocol.

Camel CXF endpoint in MESSAGE mode—when a Camel CXF endpoint is used in MESSAGE mode, the body of the exchange message is the raw message received from the transport layer (which is HTTP). In other words, the Camel CXF endpoint in MESSAGE mode is equivalent to a Jetty endpoint in the case of HTTP-based protocols.

Consumer endpoint for HT T P

A Jetty endpoint has the general form, jetty: HttpAddress. To configure the Jetty

513

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

endpoint to be a proxy for a Web service, use a HttpAddress value that is almost identical to the HTTP address the client connects to, except that Jetty's version of HttpAddress uses the special hostname, 0 . 0 . 0 . 0 (which matches all of the network interfaces on the current machine).

<route>

<from uri="jetty: http: //0 . 0 . 0 . 0 : 9 0 9 3/C usto mers?

matchO nUri P refi x= true"/>

...

</route>

mat chOnUriPrefix opt ion

Normally, a Jetty consumer endpoint accepts only an exact match on the context path. For example, a request that is sent to the address http: //l o cal ho st: 9 0 9 3/C usto mers would be accepted, but a request sent to http: //l o cal ho st: 9 0 9 3/C usto mers/Fo o would be rejected. By setting matchO nUri P refi x to true, however, you enable a kind of wildcarding on the context path, so that any context path prefixed by /C usto mers is accepted.

Alt ernat ives for t he producer endpoint

The following Apache Camel endpoints can be used as producer endpoints for HTTP format messages:

Jetty HTTP client endpoint—(recommended) the Jetty library implements a HTTP client. In particular, the Jetty HTTP client features support for HttpC l i ent thread pools, which means that the Jetty implementation scales particularly well.

HTTP endpoint—the HTTP endpoint implements a HTTP client based on the HttpC l i ent

3.x API.

HTTP4 endpoint—the HTTP endpoint implements a HTTP client based on the HttpC l i ent

4.x API.

Producer endpoint for HT T P

To configure a Jetty HTTP endpoint to send HTTP requests to a remote SOAP/HTTP Web service, set the uri attribute of the to element at the end of the route to be the address of the remote Web service, as follows:

<route>

...

<to uri="jetty: http: //l o cal ho st: 80 83/C usto mers?

bri d g eEnd po i nt= true& amp;thro wExcepti o nO nFai l ure= fal se"/>

</route>

bridgeEndpoint opt ion

514

CHAPT ER 4 0 . PRO XYING A WEB SERVICE

The HTTP component supports a bri d g eEnd po i nt option, which you can enable on a

HTTP producer endpoint to configure the endpoint appropriately for operating in a HTTP-to-

HTTP bridge (as is the case in this demonstration). In particular, when

bri d g eEnd po i nt= true, the HTTP endpoint ignores the value of the

Exchang e. HT T P _UR I header, using the HTTP address from the endpoint URI instead.

t hrowExcept ionOnFailure opt ion

Setting thro wExcepti o nO nFai l ure to fal se ensures that any HTTP exceptions are relayed back to the original WS client, instead of being thrown within the route.

Handling message headers

When defining a HTTP bridge application, the C amel Http* headers set by the consumer endpoint at the start of the route can affect the behavior of the producer endpoint. For this reason, in a bridge application it is advisable to remove the C amel Http* headers before the message reaches the producer endpoint, as follows:

<route>

...

<remo veHead ers pattern= "C amel Http*"/>

</route>

Out going HT T P headers

By default, any headers in the exchange that are not prefixed by C amel will be converted into HTTP headers and sent out over the wire by the HTTP producer endpoint. This could have adverse consequences on the behavior of your application, so it is important to be aware

of any headers that are set in the exchange object and to remove them, if necessary.

For more details about dealing with headers, see Section 40.4, “ Handling HTTP Headers” .

4 0.2. PROXYING WIT H POJO FORMAT

Overview

If you want to access the content of the Web services messages that pass throught the route, you might prefer to process the messages in POJO format: that is, where the body of the exchange consists of a list of Java objects representing the WS operation parameters. The key advantate of using POJO format is that you can easily process the contents of a message, by accessing the operation parameters as Java objects.

Figure 40.2, “ Proxy Route with Message in POJO Format” shows an overview of how to

proxy a Web service using an Apache Camel route, where the route processes the messages in POJO format. The key feature of this route is that both the consumer endpoint (at the start of the route) and the producer endpoint (at the end of the route) must be compatible with the

POJO data format.

515

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Fig u re 4 0.2. Pro xy Ro u t e wit h Messag e in PO JO Fo rmat

516

Consumer endpoint for CXF/POJO

To parse incoming messages into POJO data format, the consumer endpoint at the start of the route must be a Camel CXF endpoint that is configured to use POJO mode. Use the

cxf: bean: BeanID URI format to reference the Camel CXF endpoint as follows (where the

d ataFo rmat option defaults to POJO):

<route>

...

</route>

The bean with the ID, custo merServi ceP ro xy, is a Camel CXF/POJO endpoint, which is defined as follows:

<?xml version="1.0" encoding="UTF-8"?>

...

<cxf:cxfEndpoint

id="custo merServi ceP ro xy"

xmlns:c="http://demo.fusesource.org/wsdl/camelcxf"

address="/C usto mers"

endpointName="c:SOAPOverHTTP"

serviceName="c:CustomerService"

wsdlURL="wsdl/CustomerService.wsdl" serviceClass="o rg . fuseso urce. d emo . wsd l . camel cxf. C usto merServi ce"

...

</beans>

Producer endpoint for CXF/POJO

To convert the exchange body from POJO data format to a SOAP/HTTP message, the producer endpoint at the end of the route must be a Camel CXF endpoint configured to use

POJO mode. Use the cxf: bean: BeanID URI format to reference the Camel CXF endpoint as follows (where the d ataFo rmat option defaults to POJO):

CHAPT ER 4 0 . PRO XYING A WEB SERVICE

<route>

...

</route>

The bean with the ID, custo merServi ceR eal , is a Camel CXF/POJO endpoint, which is defined as follows:

<?xml version="1.0" encoding="UTF-8"?>

...

<cxf:cxfEndpoint

id="custo merServi ceR eal "

xmlns:c="http://demo.fusesource.org/wsdl/camelcxf"

address="http: //l o cal ho st: 80 83/C usto mers"

endpointName="c:SOAPOverHTTP"

serviceName="c:CustomerService"

wsdlURL="wsdl/CustomerService.wsdl" serviceClass="o rg . fuseso urce. d emo . wsd l . camel cxf. C usto merServi ce"

...

</beans>

4 0.3. PROXYING WIT H PAYLOAD FORMAT

Overview

If you want to access the content of the Web services messages that pass throught the route, you might prefer to process the messages in the normal PAYLOAD format: that is, where the body of the exchange is accessible as an XML document (essentially, an

o rg . w3c. d o m. No d e object). The key advantate of using PAYLOAD format is that you can easily process the contents of a message, by accessing the message body as an XML document.

Figure 40.3, “ Proxy Route with Message in PAYLOAD Format”

shows an overview of how to proxy a Web service using an Apache Camel route, where the route processes the messages in PAYLOAD format. The key feature of this route is that both the consumer endpoint (at the start of the route) and the producer endpoint (at the end of the route) must be compatible with the PAYLOAD data format.

Fig u re 4 0.3. Pro xy Ro u t e wit h Messag e in PAYLO AD Fo rmat

Consumer endpoint for CXF/PAYLOAD

517

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

518

To parse incoming messages into PAYLOAD data format, the consumer endpoint at the start of the route must be a Camel CXF endpoint that is configured to use PAYLOAD mode. Use the

cxf: bean: BeanID URI format to reference the Camel CXF endpoint as follows, where you

must set the d ataFo rmat option to PAYLOAD:

<route>

...

</route>

The bean with the ID, custo merServi ceP ro xy, is a Camel CXF/PAYLOAD endpoint, which is defined as follows:

<?xml version="1.0" encoding="UTF-8"?>

...

<cxf:cxfEndpoint

id="custo merServi ceP ro xy"

xmlns:c="http://demo.fusesource.org/wsdl/camelcxf"

address="/C usto mers"

endpointName="c:SOAPOverHTTP"

serviceName="c:CustomerService"

wsdlURL="wsdl/CustomerService.wsdl"

...

</beans>

Producer endpoint for CXF/PAYLOAD

To convert the exchange body from PAYLOAD data format to a SOAP/HTTP message, the producer endpoint at the end of the route must be a Camel CXF endpoint configured to use

PAYLOAD mode. Use the cxf: bean: BeanID URI format to reference the Camel CXF endpoint as follows, where you must set the d ataFo rmat option to PAYLOAD:

<route>

...

</route>

The bean with the ID, custo merServi ceR eal , is a Camel CXF/PAYLOAD endpoint, which is defined as follows:

<?xml version="1.0" encoding="UTF-8"?>

...

<cxf:cxfEndpoint

id="custo merServi ceR eal "

CHAPT ER 4 0 . PRO XYING A WEB SERVICE

xmlns:c="http://demo.fusesource.org/wsdl/camelcxf"

address="http: //l o cal ho st: 80 83/C usto mers"

endpointName="c:SOAPOverHTTP"

serviceName="c:CustomerService"

wsdlURL="wsdl/CustomerService.wsdl"

...

</beans>

Out going HT T P headers

By default, any headers in the exchange that are not prefixed by C amel will be converted into HTTP headers and sent out over the wire by the Camel CXF producer endpoint. This could have adverse consequences on the behavior of your application, so it is important to be

aware of any headers that are set in the exchange object and to remove them, if necessary.

For more details about dealing with headers, see Section 40.4, “ Handling HTTP Headers” .

4 0.4 . HANDLING HT T P HEADERS

Overview

When building bridge applications using HTTP or HTTP-based components, it is important to be aware of how the HTTP-based endpoints process headers. In many cases, internal headers (prefixed by Camel) or other headers can cause unwanted side-effects on your application. It is often necessary to remove or filter out certain headings or classes of headings in your route, in order to ensure that your application behaves as expected.

HT T P-based component s

The behavior described in this section affects not just the Camel HTTP component (camel -

http), but also a number of other HTTP-based components, including: camel-http camel-http4 camel-jetty camel-restlet camel-cxf camel-cxfrs

HT T P headers in Camel CXF

The Camel CXF component copies HTTP headers into message headers for all of the supported data formats:

P O JO

P AY LO AD

519

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

MESSAG E

HT T P consumer endpoint

When a HTTP consumer endpoint receives an incoming message, it creates an In message with the following headers:

C amel Http* h ead ers

Several headers with the C amel Http prefix are created, which record the status of the incoming message. For details of these internal headers, see HTTP .

HT T P h ead ers

All of the HTTP headers from the original incoming message are mapped to headers on the exchange's In message.

URL o p t io n s (Jetty only)

The URL options from the original HTTP request URL are mapped to headers on the exchange's In message. For example, given the client request with the URL,

http: //myserver/myserver?o rd eri d = 123, a Jetty consumer endpoint creates the o rd eri d header with value 123.

HT T P producer endpoint

When a HTTP producer endpoint receives an exchange and converts it to the target message format, it handles the In message headers as follows:

C amel Http*

Headers prefixed by C amel Http are used to control the behaviour of the HTTP producer endpoint. Any headers of this kind are consumed by the HTTP producer endpoint and the endpoint behaves as directed.

No t e

However, C amel Http message headers are ignored by Camel CXF producer endpoints (but not by Camel CXF-RS producer endpoints).

C amel *

All other headers prefixed by C amel are presumed to be meant for internal use and are not mapped to HTTP headers in the target message (in other words, these headers are ignored).

520

CHAPT ER 4 0 . PRO XYING A WEB SERVICE

All other headers are converted to HTTP headers in the target message, with the exception of the following headers, which are blocked (based on a case-insensitive match): content-length content-type cache-control connection date pragma trailer transfer-encoding upgrade via warning

Implicat ions for HT T P bridge applicat ions

When defining a HTTP bridge application (that is, a route starting with a HTTP consumer endpoint and ending with a HTTP producer endpoint), the C amel Http* headers set by the consumer endpoint at the start of the route can affect the behavior of the producer endpoint.

For this reason, in a bridge application it is advisable to remove the C amel Http* headers, as follows: from("http://0.0.0.0/context/path")

. remo veHead ers("C amel Http*)

...

.to("http://remoteHost/context/path");

Set t ing a cust om header filt er

If you want to customize the way that a HTTP producer endpoint processes headers, you can define your own customer header filter by defining the head erFi l terStrateg y option on the endpoint URI. For example, to configure a producer endpoint with the

myHead erFi l terStrateg y filter, you could use a URI like the following: http://remoteHost/context/path?

headerFilterStrategy=#myHeaderFilterStrategy

Where myHead erFi l terStrateg y is the bean ID of your custom filter instance.

521

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 41. FILTERING SOAP MESSAGE HEADERS

Ab st ract

The Camel CXF component supports a flexible header filtering mechanism, which enables you to process SOAP headers, applying different filters according to the header's XML namespace.

4 1.1. BASIC CONFIGURAT ION

Overview

When more than one CXF endpoint appears in a route, you need to decide whether or not to allow headers to propagate between the endpoints. By default, the headers are relayed back and forth between the endpoints, but in many cases it might be necessary to filter the headers or to block them altogether. You can control header propagation by applying filters to producer endpoints.

CxfHeaderFilt erSt rat egy

Header filtering is controlled by the C xfHead erFi l terStrateg y class. Basic configuration of the C xfHead erFi l terStrateg y class involves setting one or more of the following options:

the section called “ relayHeaders option”

the section called “ relayAllMessageHeaders option” .

relayHeaders opt ion

The semantics of the rel ayHead ers option can be summarized as follows:

O ut - of- band headers

Filter

rel ayHead ers= true

d ataFo rmat= P AY LO AD rel ayHead ers= true

d ataFo rmat= P O JO rel ayHead ers= fal se

In-band headers

In- band headers

Filter

Relay all

Block

Filter

Block

522

CHAPT ER 4 1 . FILT ERING SO AP MESSAG E HEADERS

An in-band header is a header that is explicitly defined as part of the WSDL binding contract for an endpoint.

Out -of-band headers

An out-of-band header is a header that is serialized over the wire, but is not explicitly part of the WSDL binding contract. In particular, the SOAP binding permits out-of-band headers, because the SOAP specification does not require headers to be defined in the WSDL contract.

Payload format

The CXF endpoint's payload format affects the filter behavior as follows:

P O JO

(Default) Only out-of-band headers are available for filtering, because the in-band headers have already been processed and removed from the list by CXF. The inband headers are incorporated into the Messag eC o ntentLi st in POJO mode. If you require access to headers in POJO mode, you have the option of implementing a custom CXF interceptor or JAX-WS handler.

P AY LO AD

In this mode, both in-band and out-of-band headers are available for filtering.

MESSAG E

Not applicable. (In this mode, the message remains in a raw format and the headers are not processed at all.)

Default filt er

The default filter is of type, So apMessag eHead erFi l ter, which removes only the SOAP headers that the SOAP specification expects an intermediate Web service to consume. For more details, see

the section called “ SoapMessageHeaderFilter”

Overriding t he default filt er

You can override the default C xfHead erFi l terStrateg y instance by defining a new

C xfHead erFi l terStrateg y bean and associating it with a CXF endpoint.

Sample relayHeaders configurat ion

The following example shows how you can use the rel ayHead ers option to create a

C xfHead erFi l terStrateg y bean that blocks all message headers. The CXF endpoints in the route use the head erFi l terStrateg y option to install the filter strategy in the endpoint,

523

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

where the head erFi l terStrateg y setting has the syntax,

head erFi l terStrateg y= #BeanID.

...

<bean id="d ro pAl l Messag eHead ersStrateg y" class="org.apache.camel.component.cxf.common.header.CxfHeaderFilterStr

ategy">

</bean>

<route>

<from uri="cxf:bean:routerNoRelayEndpoint?

headerFilterStrategy=#d ro pAl l Messag eHead ersStrateg y"/>

<to uri="cxf:bean:serviceNoRelayEndpoint?

headerFilterStrategy=#d ro pAl l Messag eHead ersStrateg y"/>

</route>

</camelContext>

...

</beans>

relayAllMessageHeaders opt ion

The rel ayAl l Messag eHead ers option is used to propagate all SOAP headers, without applying any filtering (any installed filters would be bypassed). In order to enable this feature, you must set both rel ayHead ers and rel ayAl l Messag eHead ers to true.

Sample relayAllMessageHeaders configurat ion

The following example shows how to configure CXF endpoints to propagate all SOAP message headers. The pro pag ateAl l Messag es filter strategy sets both rel ayHead ers and rel ayAl l Messag eHead ers to true.

...

<bean id="pro pag ateAl l Messag es" class="org.apache.camel.component.cxf.common.header.CxfHeaderFilterStr

ategy">

</bean>

<route>

<from uri="cxf:bean:routerNoRelayEndpoint?

524

CHAPT ER 4 1 . FILT ERING SO AP MESSAG E HEADERS

headerFilterStrategy=#pro pag ateAl l Messag es"/>

<to uri="cxf:bean:serviceNoRelayEndpoint?

headerFilterStrategy=#pro pag ateAl l Messag es"/>

</route>

</camelContext>

...

</beans>

4 1.2. HEADER FILT ERING

Overview

You can optionally install multiple headers in a C xfHead erFi l terStrateg y instance. The filtering mechanism then uses the header's XML namespace to lookup a particular filter, which it then applies to the header.

Filt er map

Figure 41.1, “ Filter Map” shows an overview of the filter map that is contained within a

C xfHead erFi l terStrateg y instance. For each filter that you install in

C xfHead erFi l terStrateg y, corresponding entries are made in the filter map, where one or more XML schema namespaces are associated with each filter.

Fig u re 4 1.1. Filt er Map

Filt er behavior

525

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

When a header is filtered, the filter mechanism peeks at the header to discover the header's

XML namespace. The filter then looks up the XML namespace in the filter map to find the corresponding filter implementation. This filter is then applied to the header.

PAYLOAD mode

In PAYLOAD mode, both in-band and out-of-band messages pass through the installed filters.

POJO mode

In POJO mode, only out-of-band messages pass through the installed filters. In-band messages bypass the filters and are propagated by default.

4 1.3. IMPLEMENT ING A CUST OM FILT ER

Overview

You can implement your own customer message header filters by implementing the

Messag eHead erFi l ter Java interface. You must associate a filter with one or more XML schema namespaces (representing the header's namespace) and it is possible to differentiate between request message headers and response message headers.

MessageHeaderFilt er int erface

The Messag eHead erFi l ter interface is defined in the

o rg . apache. camel . co mpo nent. cxf. co mmo n. head er package, as follows:

// Java package org.apache.camel.component.cxf.common.header; import java.util.List; import org.apache.camel.spi.HeaderFilterStrategy.Direction; import org.apache.cxf.headers.Header; public interface MessageHeaderFilter {

List<String> getActivationNamespaces();

void filter(Direction direction, List<Header> headers);

}

Implement ing t he filt er() met hod

The Messag eHead erFi l ter. fi l ter() method is reponsible for applying header filtering.

Filtering is applied both before and after an operation is invoked on an endpoint. Hence, there are two directions to which filtering is applied, as follows:

526

CHAPT ER 4 1 . FILT ERING SO AP MESSAG E HEADERS

D i recti o n. O UT

When the d i recti o n parameter equals D i recti o n. O UT , the filter is being applied to a request either leaving a consumer endpoint or entering a producer endpoint

(that is, it applies to a WS request message propagating through a route).

D i recti o n. IN

When the d i recti o n parameter equals D i recti o n. IN, the filter is being applied to a response either leaving a producer endpoint or entering a consumer endpoint

(that is, it applies to a WS response message being sent back).

Filtering can be applied by removing elements from the list of headers, head ers. Any headers left in the list are propagated.

Binding filt ers t o XML namespaces

It is possible to register multiple header filters against a given CXF endpoint. The CXF endpoint selects the appropriate filter to use based on the XML namespace of the WSDL binding protocol (for example, the namespace for the SOAP 1.1 binding or for the SOAP 1.2

binding). If a header's namespace is unknown, the header is propagated by default.

To bind a filter to one or more namespaces, implement the g etActi vati o nNamespaces() method, which returns the list of bound XML namespaces.

Ident ifying t he namespace t o bind t o

Example 41.1, “ Sample Binding Namespaces” illustrates how to identify the namespaces to

which you can bind a filter. This example shows the WSDL file for a Bank server that exposes SOAP endpoints.

Examp le 4 1.1. Samp le Bin d in g Namesp aces

<wsdl:definitions targetNamespace="http://cxf.apache.org/schemas/cxf/idl/bank"

xmlns:tns="http://cxf.apache.org/schemas/cxf/idl/bank"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:so ap="http: //schemas. xml so ap. o rg /wsd l /so ap/"

xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">

...

<wsdl:binding name="BankSOAPBinding" type="tns:Bank">

<so ap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />

<wsdl:operation name="getAccount">

...

</wsdl:operation>

527

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

...

</wsdl:binding>

...

</wsdl>

From the so ap: bi nd i ng tag, you can infer that namespace associated with the SOAP binding is http: //schemas. xml so ap. o rg /wsd l /so ap/.

Implement ing a cust om filt er

If you want to implement your own custom filter, define a class that inherits from the

Messag eHead erFi l ter interface and implement its methods as described in this section.

For example,

Example 41.2, “ Sample Header Filter Implementation”

shows an example of a custom filter, C usto mHead erFi l ter, that binds to the namespace,

http: //cxf. apache. o rg /bi nd i ng s/custo m, and relays all of the headers that pass through it.

Examp le 4 1.2. Samp le Head er Filt er Imp lemen t at io n

// Java package org.apache.camel.component.cxf.soap.headers; import java.util.Arrays; import java.util.List; import org.apache.camel.component.cxf.common.header.MessageHeaderFilter; import org.apache.camel.spi.HeaderFilterStrategy.Direction; import org.apache.cxf.headers.Header; public class CustomHeaderFilter implements MessageHeaderFilter {

public static final String ACTIVATION_NAMESPACE =

"http://cxf.apache.org/bindings/custom";

public static final List<String> ACTIVATION_NAMESPACES =

Arrays.asList(ACTIVATION_NAMESPACE);

public List<String> getActivationNamespaces() {

return ACTIVATION_NAMESPACES;

}

public void filter(Direction direction, List<Header> headers) {

}

4 1.4 . INST ALLING FILT ERS

528

Overview

CHAPT ER 4 1 . FILT ERING SO AP MESSAG E HEADERS

To install message header filters, set the messag eHead erFi l ters property of the

C xfHead erFi l terStrateg y object. When you initialize this property with a list of message header filters, the header filter strategy combines the specified filters to make a filter map.

The messag eHead erFi l ters property is of type, Li st<Messag eHead erFi l ter>.

Inst alling filt ers in XML

The following example shows how to create a C xfHead erFi l terStrateg y instance, specifying a customized list of header filters in the messag eHead erFi l ters property.

There are two header filters in this example: So apMessag eHead erFi l ter and

C usto mHead erFi l ter.

<bean id="customMessageFilterStrategy" class="org.apache.camel.component.cxf.common.header.CxfHeaderFilterStr

ategy">

<list>

<bean class="org.apache.camel.component.cxf.common.header.SoapMessageHeaderF

ilter"/>

<bean class="org.apache.camel.component.cxf.soap.headers.CustomHeaderFilter"

</list>

</property>

</bean>

SoapMessageHeaderFilt er

The first header filter in the preceding example is the So apMessag eHead erFi l ter filter, which is the default header filter. This filter is designed to filter standard SOAP headers and is bound to the following XML namespaces: http://schemas.xmlsoap.org/soap/ http://schemas.xmlsoap.org/wsdl/soap/ http://schemas.xmlsoap.org/wsdl/soap12/

This filter peeks at the header element, in order to decide whether or not to block a particular header. If the so ap: acto r attribute (SOAP 1.1) or the so ap: ro l e attribute (SOAP 1.2) is present and has the value next, the header is removed from the message. Otherwise, the header is propagated.

Namespace clashes

529

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Normally, each namespace should be bound to just a single header filter. If a namespace is bound to more than one header filter, this normally causes an error. It is possible, however, to override this policy by setting the al l o wFi l terNamespaceC l ash property to true in the C xfHead erFi l terStrateg y instance. When this policy is set to true, the nearest to last filter is selected, in the event of a namespace clash.

530

PART IV. PRO G RAMMING EIP CO MPO NENT S

PART IV. PROGRAMMING EIP COMPONENTS

Ab st ract

This guide describes how to use the Apache Camel API.

531

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 42. UNDERSTANDING MESSAGE FORMATS

Ab st ract

Before you can begin programming with Apache Camel, you should have a clear understanding of how messages and message exchanges are modelled. Because Apache

Camel can process many message formats, the basic message type is designed to have an abstract format. Apache Camel provides the APIs needed to access and transform the data formats that underly message bodies and message headers.

4 2.1. EXCHANGES

Overview

An exchange object is a wrapper that encapsulates a received message and stores its associated metadata (including the exchange properties). In addition, if the current message is dispatched to a producer endpoint, the exchange provides a temporary slot to hold the reply (the Out message).

An important feature of exchanges in Apache Camel is that they support lazy creation of messages. This can provide a significant optimization in the case of routes that do not require explicit access to messages.

Fig u re 4 2.1. Exch an g e O b ject Passin g t h ro u g h a Ro u t e

532

Figure 42.1, “ Exchange Object Passing through a Route” shows an exchange object

passing through a route. In the context of a route, an exchange object gets passed as the argument of the P ro cesso r. pro cess() method. This means that the exchange object is directly accessible to the source endpoint, the target endpoint, and all of the processors in between.

T he Exchange int erface

The o rg . apache. camel . Exchang e interface defines methods to access In and Out messages, as shown in

Example 42.1, “ Exchange Methods”

Examp le 4 2.1. Exch an g e Met h o d s

CHAPT ER 4 2 . UNDERST ANDING MESSAG E FO RMAT S

// Access the In message

Message getIn(); void setIn(Message in);

// Access the Out message (if any)

Message getOut(); void setOut(Message out); boolean hasOut();

// Access the exchange ID

String getExchangeId(); void setExchangeId(String id);

For a complete description of the methods in the Exchang e interface, see Section 51.1, “ The

Exchange Interface” .

Laz y creat ion of messages

Apache Camel supports lazy creation of In, Out, and Fault messages. This means that message instances are not created until you try to access them (for example, by calling

g etIn() or g etO ut()). The lazy message creation semantics are implemented by the

o rg . apache. camel . i mpl . D efaul tExchang e class.

If you call one of the no-argument accessors (g etIn() or g etO ut()), or if you call an accessor with the boolean argument equal to true (that is, g etIn(true) or

g etO ut(true)), the default method implementation creates a new message instance, if one does not already exist.

If you call an accessor with the boolean argument equal to fal se (that is, g etIn(fal se) or g etO ut(fal se)), the default method implementation returns the current message value.

[2]

Laz y creat ion of exchange IDs

Apache Camel supports lazy creation of exchange IDs. You can call g etExchang eId () on any exchange to obtain a unique ID for that exchange instance, but the ID is generated only when you actually call the method. The D efaul tExchang e. g etExchang eId () implementation of this method delegates ID generation to the UUID generator that is registered with the C amel C o ntext.

For details of how to register UUID generators with the C amel C o ntext, see Section 42.4,

“ Built-In UUID Generators” .

4 2.2. MESSAGES

Overview

533

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Message objects represent messages using the following abstract model:

Message body

Message headers

Message attachments

The message body and the message headers can be of arbitrary type (they are declared as type O bject) and the message attachments are declared to be of type

javax. acti vati o n. D ataHand l er , which can contain arbitrary MIME types. If you need to obtain a concrete representation of the message contents, you can convert the body and headers to another type using the type converter mechanism and, possibly, using the marshalling and unmarshalling mechanism.

One important feature of Apache Camel messages is that they support lazy creation of message bodies and headers. In some cases, this means that a message can pass through a route without needing to be parsed at all.

T he Message int erface

The o rg . apache. camel . Messag e interface defines methods to access the message

body, message headers and message attachments, as shown in Example 42.2, “ Message

Interface” .

Examp le 4 2.2. Messag e In t erf ace

// Access the message body

Object getBody();

<T> T getBody(Class<T> type); void setBody(Object body);

<T> void setBody(Object body, Class<T> type);

// Access message headers

Object getHeader(String name);

<T> T getHeader(String name, Class<T> type); void setHeader(String name, Object value);

Object removeHeader(String name);

Map<String, Object> getHeaders(); void setHeaders(Map<String, Object> headers);

// Access message attachments

javax.activation.DataHandler getAttachment(String id); java.util.Map<String, javax.activation.DataHandler> getAttachments(); java.util.Set<String> getAttachmentNames(); void addAttachment(String id, javax.activation.DataHandler content)

534

CHAPT ER 4 2 . UNDERST ANDING MESSAG E FO RMAT S

// Access the message ID

String getMessageId(); void setMessageId(String messageId);

For a complete description of the methods in the Messag e interface, see Section 52.1, “ The

Message Interface” .

Laz y creat ion of bodies, headers, and at t achment s

Apache Camel supports lazy creation of bodies, headers, and attachments. This means that the objects that represent a message body, a message header, or a message attachment are not created until they are needed.

For example, consider the following route that accesses the fo o message header from the In message: from("SourceURL")

.filter(header("foo")

.isEqualTo("bar"))

.to("TargetURL");

In this route, if we assume that the component referenced by SourceURL supports lazy creation, the In message headers are not actually parsed until the head er("fo o ") call is executed. At that point, the underlying message implementation parses the headers and populates the header map. The message body is not parsed until you reach the end of the route, at the to ("TargetURL") call. At that point, the body is converted into the format required for writing it to the target endpoint, TargetURL.

By waiting until the last possible moment before populating the bodies, headers, and attachments, you can ensure that unnecessary type conversions are avoided. In some cases, you can completely avoid parsing. For example, if a route contains no explicit references to message headers, a message could traverse the route without ever parsing the headers.

Whether or not lazy creation is implemented in practice depends on the underlying component implementation. In general, lazy creation is valuable for those cases where creating a message body, a message header, or a message attachment is expensive. For

details about implementing a message type that supports lazy creation, see Section 52.2,

“ Implementing the Message Interface” .

Laz y creat ion of message IDs

Apache Camel supports lazy creation of message IDs. That is, a message ID is generated only when you actually call the g etMessag eId () method. The

D efaul tExchang e. g etExchang eId () implementation of this method delegates ID generation to the UUID generator that is registered with the C amel C o ntext.

535

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Some endpoint implementations would call the g etMessag eId () method implicitly, if the endpoint implements a protocol that requires a unique message ID. In particular, JMS messages normally include a header containing unique message ID, so the JMS component automatically calls g etMessag eId () to obtain the message ID (this is controlled by the

messag eId Enabl ed option on the JMS endpoint).

For details of how to register UUID generators with the C amel C o ntext, see Section 42.4,

“ Built-In UUID Generators” .

Init ial message format

The initial format of an In message is determined by the source endpoint, and the initial format of an Out message is determined by the target endpoint. If lazy creation is supported by the underlying component, the message remains unparsed until it is accessed explicitly by the application. Most Apache Camel components create the message body in a relatively raw form—for example, representing it using types such as byte[], ByteBuffer,

InputStream, or O utputStream. This ensures that the overhead required for creating the initial message is minimal. Where more elaborate message formats are required components usually rely on type converters or marshalling processors.

T ype convert ers

It does not matter what the initial format of the message is, because you can easily convert a

message from one format to another using the built-in type converters (see Section 42.3,

“ Built-In Type Converters” ). There are various methods in the Apache Camel API that expose

type conversion functionality. For example, the co nvertBo d yT o (C l ass type) method can be inserted into a route to convert the body of an In message, as follows: from("SourceURL").convertBodyTo(String.class).to("TargetURL");

Where the body of the In message is converted to a java. l ang . Stri ng . The following example shows how to append a string to the end of the In message body: from("SourceURL").setBody(bodyAs(String.class).append("My Special

Signature")).to("TargetURL");

Where the message body is converted to a string format before appending a string to the end. It is not necessary to convert the message body explicitly in this example. You can also use: from("SourceURL").setBody(body().append("My Special

Signature")).to("TargetURL");

Where the append () method automatically converts the message body to a string before appending its argument.

T ype conversion met hods in Message

536

CHAPT ER 4 2 . UNDERST ANDING MESSAG E FO RMAT S

The o rg . apache. camel . Messag e interface exposes some methods that perform type conversion explicitly:

g etBo d y(C l ass<T > type)—Returns the message body as type, T .

g etHead er(Stri ng name, C l ass<T > type)—Returns the named header value as type, T .

For the complete list of supported conversion types, see Section 42.3, “ Built-In Type

Converters” .

Convert ing t o XML

In addition to supporting conversion between simple types (such as byte[], ByteBuffer,

Stri ng , and so on), the built-in type converter also supports conversion to XML formats. For example, you can convert a message body to the o rg . w3c. d o m. D o cument type. This conversion is more expensive than the simple conversions, because it involves parsing the entire message and then creating a tree of nodes to represent the XML document structure.

You can convert to the following XML document types:

o rg . w3c. d o m. D o cument javax. xml . transfo rm. sax. SAXSo urce

XML type conversions have narrower applicability than the simpler conversions. Because not every message body conforms to an XML structure, you have to remember that this type conversion might fail. On the other hand, there are many scenarios where a router deals exclusively with XML message types.

Marshalling and unmarshalling

Marshalling involves converting a high-level format to a low-level format, and unmarshalling involves converting a low-level format to a high-level format. The following two processors are used to perform marshalling or unmarshalling in a route:

marshal () unmarshal ()

For example, to read a serialized Java object from a file and unmarshal it into a Java object, you could use the route definition shown in

Example 42.3, “ Unmarshalling a Java Object” .

Examp le 4 2.3. Un marsh allin g a Java O b ject

from("file://tmp/appfiles/serialized")

.unmarshal()

.serialization()

537

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

.<FurtherProcessing>

.to("TargetURL");

Final message format

When an In message reaches the end of a route, the target endpoint must be able to convert the message body into a format that can be written to the physical endpoint. The same rule applies to Out messages that arrive back at the source endpoint. This conversion is usually performed implicitly, using the Apache Camel type converter. Typically, this involves converting from a low-level format to another low-level format, such as converting from a

byte[] array to an InputStream type.

4 2.3. BUILT -IN T YPE CONVERT ERS

Overview

This section describes the conversions supported by the master type converter. These conversions are built into the Apache Camel core.

Usually, the type converter is called through convenience functions, such as

Messag e. g etBo d y(C l ass<T > type) or Messag e. g etHead er(Stri ng name,

C l ass<T > type). It is also possible to invoke the master type converter directly. For example, if you have an exchange object, exchang e, you could convert a given value to a

Stri ng as shown in

Example 42.4, “ Converting a Value to a String” .

Examp le 4 2.4 . Co n vert in g a Valu e t o a St rin g

org.apache.camel.TypeConverter tc = exchange.getContext().getTypeConverter();

String str_value = tc.convertTo(String.class, value);

538

Basic t ype convert ers

Apache Camel provides built-in type converters that perform conversions to and from the following basic types:

java. i o . Fi l e

Stri ng

byte[] and java. ni o . ByteBuffer

java. i o . InputStream and java. i o . O utputStream

CHAPT ER 4 2 . UNDERST ANDING MESSAG E FO RMAT S

java. i o . R ead er and java. i o . Wri ter

java. i o . Buffered R ead er and java. i o . Buffered Wri ter

java. i o . Stri ng R ead er

However, not all of these types are inter-convertible. The built-in converter is mainly focused on providing conversions from the Fi l e and Stri ng types. The Fi l e type can be converted to any of the preceding types, except R ead er, Wri ter, and Stri ng R ead er. The

Stri ng type can be converted to Fi l e, byte[], ByteBuffer, InputStream, or

Stri ng R ead er. The conversion from Stri ng to Fi l e works by interpreting the string as a file name. The trio of Stri ng , byte[], and ByteBuffer are completely inter-convertible.

No t e

You can explicitly specify which character encoding to use for conversion from

byte[] to Stri ng and from Stri ng to byte[] by setting the

Exchang e. C HAR SET _NAME exchange property in the current exchange. For example, to perform conversions using the UTF-8 character encoding, call

exchang e. setP ro perty("Exchang e. C HAR SET _NAME", "UT F-8"). The supported character sets are described in the java. ni o . charset. C harset class.

Collect ion t ype convert ers

Apache Camel provides built-in type converters that perform conversions to and from the following collection types:

O bject[] java. uti l . Set java. uti l . Li st

All permutations of conversions between the preceding collection types are supported.

Map t ype convert ers

Apache Camel provides built-in type converters that perform conversions to and from the following map types:

java. uti l . Map java. uti l . HashMap java. uti l . Hashtabl e

539

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide java. uti l . P ro perti es

The preceding map types can also be converted into a set, of java. uti l . Set type, where the set elements are of the MapEntry<K,V> type.

DOM t ype convert ers

You can perform type conversions to the following Document Object Model (DOM) types:

o rg . w3c. d o m. D o cument—convertible from byte[], Stri ng , java. i o . Fi l e, and

java. i o . InputStream.

o rg . w3c. d o m. No d e

javax. xml . transfo rm. d o m. D O MSo urce—convertible from Stri ng .

javax. xml . transfo rm. So urce—convertible from byte[] and Stri ng .

All permutations of conversions between the preceding DOM types are supported.

SAX t ype convert ers

You can also perform conversions to the javax. xml . transfo rm. sax. SAXSo urce type, which supports the SAX event-driven XML parser (see the SAX Web site for details). You can convert to SAXSo urce from the following types:

Stri ng

InputStream

So urce

StreamSo urce

D O MSo urce

enum t ype convert er

Camel provides a type converter for performing Stri ng to enum type conversions, where the string value is converted to the matching enum constant from the specified enumeration class (the matching is case-insensitive). This type converter is rarely needed for converting message bodies, but it is frequently used internally by Apache Camel to select particular options.

54 0

For example, when setting the logging level option, the following value, INFO , is converted into an enum constant:

CHAPT ER 4 2 . UNDERST ANDING MESSAG E FO RMAT S

Because the enum type converter is case-insensitive, any of the following alternatives would also work:

Cust om t ype convert ers

Apache Camel also enables you to implement your own custom type converters. For details

on how to implement a custom type converter, see Chapter 44, Type Converters

4 2.4 . BUILT -IN UUID GENERAT ORS

Overview

Apache Camel enables you to register a UUID generator in the C amel C o ntext. This UUID generator is then used whenever Apache Camel needs to generate a unique ID—in particular, the registered UUID generator is called to generate the IDs returned by the

Exchang e. g etExchang eId () and the Messag e. g etMessag eId () methods.

For example, you might prefer to replace the default UUID generator, if part of your application does not support IDs with a length of 36 characters (like Websphere MQ). Also, it can be convenient to generate IDs using a simple counter (see the

Si mpl eUui d G enerato r) for testing purposes.

Provided UUID generat ors

You can configure Apache Camel to use one of the following UUID generators, which are provided in the core:

o rg . apache. camel . i mpl . Acti veMQ Uui d G enerato r—(Default) generates the same style of ID as is used by Apache ActiveMQ. This implementation might not be suitable for all applications, because it uses some JDK APIs that are forbidden in the context of cloud computing (such as the Google App Engine).

o rg . apache. camel . i mpl . Si mpl eUui d G enerato r—implements a simple counter

ID, starting at 1. The underlying implementation uses the

java. uti l . co ncurrent. ato mi c. Ato mi cLo ng type, so that it is thread-safe.

o rg . apache. camel . i mpl . JavaUui d G enerato r—implements an ID based on the

java. uti l . UUID type. Because java. uti l . UUID is synchronized, this might affect performance on some highly concurrent systems.

Cust om UUID generat or

54 1

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

To implement a custom UUID generator, implement the

o rg . apache. camel . spi . Uui d G enerato r interface, which is shown in

Example 42.5,

“ UuidGenerator Interface” . The g enerateUui d () must be implemented to return a unique

ID string.

Examp le 4 2.5. Uu id G en erat o r In t erf ace

// Java package org.apache.camel.spi;

/**

* Generator to generate UUID strings.

*/ public interface UuidGenerator {

String generateUuid();

}

Specifying t he UUID generat or using Java

To replace the default UUID generator using Java, call the setUui d G enerato r() method on the current C amel C o ntext object. For example, you can register a

Si mpl eUui d G enerato r instance with the current C amel C o ntext, as follows:

// Java getContext().setUuidGenerator(new org.apache.camel.impl.SimpleUuidGenerator());

No t e

The setUui d G enerato r() method should be called during startup, before any routes are activated.

Specifying t he UUID generat or using Spring

To replace the default UUID generator using Spring, all you need to do is to create an instance of a UUID generator using the Spring bean element. When a camel C o ntext instance is created, it automatically looks up the Spring registry, searching for a bean that implements o rg . apache. camel . spi . Uui d G enerato r. For example, you can register a

Si mpl eUui d G enerato r instance with the C amel C o ntext as follows:

<bean id="simpleUuidGenerator"

class="org.apache.camel.impl.SimpleUuidGenerator" />

54 2

CHAPT ER 4 2 . UNDERST ANDING MESSAG E FO RMAT S

...

</camelContext>

...

</beans>

[2]

If there is no active metho d the returned value will b e

nul l

54 3

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 43. IMPLEMENTING A PROCESSOR

Ab st ract

Apache Camel allows you to implement a custom processor. You can then insert the custom processor into a route to perform operations on exchange objects as they pass through the route.

4 3.1. PROCESSING MODEL

Pipelining model

The pipelining model describes the way in which processors are arranged in Section 5.4,

“ Pipes and Filters” . Pipelining is the most common way to process a sequence of endpoints

(a producer endpoint is just a special type of processor). When the processors are arranged

in this way, the exchange's In and Out messages are processed as shown in Figure 43.1,

“ Pipelining Model” .

Fig u re 4 3.1. Pip elin in g Mo d el

The processors in the pipeline look like services, where the In message is analogous to a request, and the Out message is analogous to a reply. In fact, in a realistic pipeline, the nodes in the pipeline are often implemented by Web service endpoints, such as the CXF component.

For example,

Example 43.1, “ Java DSL Pipeline” shows a Java DSL pipeline constructed

from a sequence of two processors, P ro cesso rA, P ro cesso rB, and a producer endpoint,

TargetURI.

Examp le 4 3.1. Java DSL Pip elin e

from(SourceURI).pipeline(ProcessorA, ProcessorB, TargetURI);

54 4

4 3.2. IMPLEMENT ING A SIMPLE PROCESSOR

Overview

CHAPT ER 4 3. IMPLEMENT ING A PRO CESSO R

This section describes how to implement a simple processor that executes message processing logic before delegating the exchange to the next processor in the route.

Processor int erface

Simple processors are created by implementing the o rg . apache. camel . P ro cesso r

interface. As shown in Example 43.2, “ Processor Interface” , the interface defines a single

method, pro cess(), which processes an exchange object.

Examp le 4 3.2. Pro cesso r In t erf ace

package org.apache.camel; public interface Processor { void process(Exchange exchange) throws Exception;

}

Implement ing t he Processor int erface

To create a simple processor you must implement the P ro cesso r interface and provide the logic for the pro cess() method.

Example 43.3, “ Simple Processor Implementation” shows

the outline of a simple processor implementation.

Examp le 4 3.3. Simp le Pro cesso r Imp lemen t at io n

import org.apache.camel.Processor; public class MyProcessor implements Processor { public MyProcessor() { } public void process(Exchange exchange) throws Exception

{

// Insert code that gets executed *before* delegating

// to the next processor in the chain.

...

}

All of the code in the pro cess() method gets executed before the exchange object is delegated to the next processor in the chain.

For examples of how to access the message body and header values inside a simple processor, see

Section 43.3, “ Accessing Message Content” .

Insert ing t he simple processor int o a rout e

54 5

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Use the pro cess() DSL command to insert a simple processor into a route. Create an instance of your custom processor and then pass this instance as an argument to the

pro cess() method, as follows: org.apache.camel.Processor myProc = new MyProcessor(); from("SourceURL").process(myProc).to("TargetURL");

4 3.3. ACCESSING MESSAGE CONT ENT

Accessing message headers

Message headers typically contain the most useful message content from the perspective of a router, because headers are often intended to be processed in a router service. To access header data, you must first get the message from the exchange object (for example, using

Exchang e. g etIn()), and then use the Messag e interface to retrieve the individual headers (for example, using Messag e. g etHead er()).

Example 43.4, “ Accessing an Authorization Header”

shows an example of a custom processor that accesses the value of a header named Autho ri zati o n. This example uses the Exchang eHel per. g etMand ato ryHead er() method, which eliminates the need to test for a null header value.

Examp le 4 3.4 . Accessin g an Au t h o riz at io n Head er

import org.apache.camel.*; import org.apache.camel.util.ExchangeHelper; public class MyProcessor implements Processor { public void process(Exchange exchange) {

String auth = ExchangeHelper.g etMand ato ryHead er(

exchange,

"Authorization" ,

String.class

);

// process the authorization string...

// ...

}

54 6

For full details of the Messag e interface, see

Section 42.2, “ Messages”

Accessing t he message body

You can also access the message body. For example, to append a string to the end of the In

message, you can use the processor shown in Example 43.5, “ Accessing the Message

Body” .

CHAPT ER 4 3. IMPLEMENT ING A PRO CESSO R

Examp le 4 3.5. Accessin g t h e Messag e Bo d y

import org.apache.camel.*; import org.apache.camel.util.ExchangeHelper; public class MyProcessor implements Processor { public void process(Exchange exchange) {

Message in = exchange.getIn();

in.setBody(in.getBody(String.class) + " World!" );

}

Accessing message at t achment s

You can access a message's attachments using either the Messag e. g etAttachment()

method or the Messag e. g etAttachments() method. See Example 42.2, “ Message

Interface” for more details.

4 3.4 . T HE EXCHANGEHELPER CLASS

Overview

The o rg . apache. camel . uti l . Exchang eHel per class is a Apache Camel utility class that provides methods that are useful when implementing a processor.

Resolve an endpoint

The static reso l veEnd po i nt() method is one of the most useful methods in the

Exchang eHel per class. You use it inside a processor to create new End po i nt instances on the fly.

Examp le 4 3.6 . T h e reso l veEnd po i nt() Met h o d

public final class ExchangeHelper {

...

@ SuppressWarnings({"unchecked" })

public static Endpoint

resolveEndpoint(Exchange exchange, Object value)

throws NoSuchEndpointException { ... }

...

}

The first argument to reso l veEnd po i nt() is an exchange instance, and the second argument is usually an endpoint URI string.

Example 43.7, “ Creating a File Endpoint” shows

how to create a new file endpoint from an exchange instance exchang e

54 7

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Examp le 4 3.7. Creat in g a File En d p o in t

Endpoint file_endp = ExchangeHelper.resolveEndpoint(exchange,

"file://tmp/messages/in.xml");

54 8

Wrapping t he exchange accessors

The Exchang eHel per class provides several static methods of the form

g etMand ato ryBeanProperty(), which wrap the corresponding g etBeanProperty() methods on the Exchang e class. The difference between them is that the original

g etBeanProperty() accessors return nul l , if the corresponding property is unavailable, and the g etMand ato ryBeanProperty() wrapper methods throw a Java exception. The following wrapper methods are implemented in the Exchang eHel per class: public final class ExchangeHelper {

...

public static <T> T getMandatoryProperty(Exchange exchange,

String propertyName, Class<T> type)

throws NoSuchPropertyException { ... }

public static <T> T getMandatoryHeader(Exchange exchange, String propertyName, Class<T> type)

throws NoSuchHeaderException { ... }

public static Object getMandatoryInBody(Exchange exchange)

throws InvalidPayloadException { ... }

public static <T> T getMandatoryInBody(Exchange exchange, Class<T> type)

throws InvalidPayloadException { ... }

public static Object getMandatoryOutBody(Exchange exchange)

throws InvalidPayloadException { ... }

public static <T> T getMandatoryOutBody(Exchange exchange,

Class<T> type)

throws InvalidPayloadException { ... }

...

}

T est ing t he exchange pat t ern

Several different exchange patterns are compatible with holding an In message. Several different exchange patterns are also compatible with holding an Out message. To provide a quick way of checking whether or not an exchange object is capable of holding an In message or an Out message, the Exchang eHel per class provides the following methods: public final class ExchangeHelper {

...

public static boolean isInCapable(Exchange exchange) { ... }

CHAPT ER 4 3. IMPLEMENT ING A PRO CESSO R

public static boolean isOutCapable(Exchange exchange) { ... }

...

}

Get t he In message's MIME cont ent t ype

If you want to find out the MIME content type of the exchange's In message, you can access it by calling the Exchang eHel per. g etC o ntentT ype(exchang e) method. To implement this, the Exchang eHel per object looks up the value of the In message's C o ntent-T ype header—this method relies on the underlying component to populate the header value).

54 9

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 44. TYPE CONVERTERS

Ab st ract

Apache Camel has a built-in type conversion mechanism, which is used to convert message bodies and message headers to different types. This chapter explains how to extend the type conversion mechanism by adding your own custom converter methods.

4 4 .1. T YPE CONVERT ER ARCHIT ECT URE

Overview

This section describes the overall architecture of the type converter mechanism, which you must understand, if you want to write custom type converters. If you only need to use the

built-in type converters, see Chapter 42, Understanding Message Formats

T ype convert er int erface

Example 44.1, “ TypeConverter Interface” shows the definition of the

o rg . apache. camel . T ypeC o nverter interface, which all type converters must implement.

Examp le 4 4 .1. T yp eCo n vert er In t erf ace

package org.apache.camel; public interface TypeConverter {

<T> T convertTo(Class<T> type, Object value);

}

550

Mast er t ype convert er

The Apache Camel type converter mechanism follows a master/slave pattern. There are many

slave type converters, which are each capable of performing a limited number of type conversions, and a single master type converter, which aggregates the type conversions performed by the slaves. The master type converter acts as a front-end for the slave type converters. When you request the master to perform a type conversion, it selects the appropriate slave and delegates the conversion task to that slave.

For users of the type conversion mechanism, the master type converter is the most important because it provides the entry point for accessing the conversion mechanism. During start up, Apache Camel automatically associates a master type converter instance with the

C amel C o ntext object. To obtain a reference to the master type converter, you call the

C amel C o ntext. g etT ypeC o nverter() method. For example, if you have an exchange object, exchang e, you can obtain a reference to the master type converter as shown in

Example 44.2, “ Getting a Master Type Converter” .

Examp le 4 4 .2. G et t in g a Mast er T yp e Co n vert er

org.apache.camel.TypeConverter tc = exchange.getContext().getTypeConverter();

CHAPT ER 4 4 . T YPE CO NVERT ERS

T ype convert er loader

The master type converter uses a type converter loader to populate the registry of slave type converters. A type converter loader is any class that implements the

T ypeC o nverterLo ad er interface. Apache Camel currently uses only one kind of type converter loader—the annotation type converter loader (of

Anno tati o nT ypeC o nverterLo ad er type).

T ype conversion process

Figure 44.1, “ Type Conversion Process” gives an overview of the type conversion process,

showing the steps involved in converting a given data value, val ue, to a specified type,

to T ype.

Fig u re 4 4 .1. T yp e Co n versio n Pro cess

551

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

The type conversion mechanism proceeds as follows:

1. The C amel C o ntext object holds a reference to the master T ypeC o nverter instance. The first step in the conversion process is to retrieve the master type converter by calling C amel C o ntext. g etT ypeC o nverter().

2. Type conversion is initiated by calling the co nvertT o () method on the master type converter. This method instructs the type converter to convert the data object, val ue, from its original type to the type specified by the to T ype argument.

3. Because the master type converter is a front end for many different slave type converters, it looks up the appropriate slave type converter by checking a registry of type mappings The registry of type converters is keyed by a type mapping pair

(toType, fromType). If a suitable type converter is found in the registry, the master type converter calls the slave's co nvertT o () method and returns the result.

4. If a suitable type converter cannot be found in the registry, the master type converter loads a new type converter, using the type converter loader.

5. The type converter loader searches the available JAR libraries on the classpath to find a suitable type converter. Currently, the loader strategy that is used is implemented by the annotation type converter loader, which attempts to load a class

annotated by the o rg . apache. camel . C o nverter annotation. See the section called “ Create a TypeConverter file” .

6. If the type converter loader is successful, a new slave type converter is loaded and entered into the type converter registry. This type converter is then used to convert the

val ue argument to the to T ype type.

7. If the data is successfully converted, the converted data value is returned. If the conversion does not succeed, nul l is returned.

4 4 .2. IMPLEMENT ING T YPE CONVERT ER USING ANNOT AT IONS

Overview

The type conversion mechanism can easily be customized by adding a new slave type converter. This section describes how to implement a slave type converter and how to integrate it with Apache Camel, so that it is automatically loaded by the annotation type converter loader.

How t o implement a t ype convert er

552

To implement a custom type converter, perform the following steps:

Implement an annotated converter class

Create a TypeConverter file .

CHAPT ER 4 4 . T YPE CO NVERT ERS

Package the type converter

Implement an annot at ed convert er class

You can implement a custom type converter class using the @ C o nverter annotation. You must annotate the class itself and each of the stati c methods intended to perform type conversion. Each converter method takes an argument that defines the from type, optionally takes a second Exchang e argument, and has a non-void return value that defines the to type. The type converter loader uses Java reflection to find the annotated methods and

integrate them into the type converter mechanism. Example 44.3, “ Example of an Annotated

Converter Class” shows an example of an annotated converter class that defines a converter

method for converting from java. i o . Fi l e to java. i o . InputStream and another converter method (with an Exchang e argument) for converting from byte[] to Stri ng .

Examp le 4 4 .3. Examp le o f an An n o t at ed Co n vert er Class

package com.YourDomain.YourPackageName; import org.apache.camel.C o nverter; import java.io.*;

@ C o nverter

public class IOConverter { private IOConverter() {

}

@ C o nverter public

stati c

InputStream toInputStream(File file) throws

FileNotFoundException { return new BufferedInputStream( new FileInputStream(file));

}

@ C o nverter public

stati c

String toString( byte [] data, Exchang e exchange) { if (exchange != null ) {

String charsetName = exchange.getProperty(Exchange.CHARSET_NAME, String.class); if (charsetName != null ) { try { return new String(data, charsetName);

} catch (UnsupportedEncodingException e) {

LOG.warn( "Can't convert the byte to String with the charset " + charsetName, e);

}

} return new String(data);

}

553

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

The to InputStream() method is responsible for performing the conversion from the Fi l e type to the InputStream type and the to Stri ng () method is responsible for performing the conversion from the byte[] type to the Stri ng type.

No t e

The method name is unimportant, and can be anything you choose. What is important are the argument type, the return type, and the presence of the

@ C o nverter annotation.

Creat e a T ypeConvert er file

To enable the discovery mechanism (which is implemented by the annotation type converter

loader) for your custom converter, create a T ypeC o nverter file at the following location:

META-INF/services/org/apache/camel/TypeConverter

The T ypeC o nverter file must contain a comma-separated list of package names identifying the packages that contain type converter classes. For example, if you want the type converter loader to search the co m. YourDomain. YourPackageName package for annotated converter classes, the T ypeC o nverter file would have the following contents: com.YourDomain.YourPackageName

Package t he t ype convert er

The type converter is packaged as a JAR file containing the compiled classes of your custom type converters and the MET A-INF directory. Put this JAR file on your classpath to make it available to your Apache Camel application.

Fallback convert er met hod

In addition to defining regular converter methods using the @ C o nverter annotation, you can optionally define a fallback converter method using the @ Fal l backC o nverter annotation. The fallback converter method will only be tried, if the master type converter fails to find a regular converter method in the type registry.

The essential difference between a regular converter method and a fallback converter method is that whereas a regular converter is defined to perform conversion between a specific pair of types (for example, from byte[] to Stri ng ), a fallback converter can potentially perform conversion between any pair of types. It is up to the code in the body of the fallback converter method to figure out which conversions it is able to perform. At run time, if a conversion cannot be performed by a regular converter, the master type converter iterates through every available fallback converter until it finds one that can perform the conversion.

The method signature of a fallback converter can have either of the following forms:

554

CHAPT ER 4 4 . T YPE CO NVERT ERS

// 1. Non-generic form of signature

@ FallbackConverter public static Object MethodName(

Class type,

Exchange exchange,

Object value,

TypeConverterRegistry registry

)

// 2. Templating form of signature

@ FallbackConverter public static <T> T MethodName(

Class<T> type,

Exchange exchange,

Object value,

TypeConverterRegistry registry

)

Where MethodName is an arbitrary method name for the fallback converter.

For example, the following code extract (taken from the implementation of the File component) shows a fallback converter that can convert the body of a G eneri cFi l e object, exploiting the type converters already available in the type converter registry: package org.apache.camel.component.file; import org.apache.camel.C o nverter; import org.apache.camel.Fal l backC o nverter; import org.apache.camel.Exchange; import org.apache.camel.TypeConverter; import org.apache.camel.spi.TypeConverterRegistry;

@ C o nverter

public final class GenericFileConverter {

private GenericFileConverter() {

// Helper Class

}

@ Fal l backC o nverter

public static <T> T convertTo(Class<T> type, Exchange exchange,

Object value, TypeConverterRegistry registry) {

// use a fallback type converter so we can convert the embedded body if the value is GenericFile

if (GenericFile.class.isAssignableFrom(value.getClass())) {

GenericFile file = (GenericFile) value;

Class from = file.getBody().getClass();

TypeConverter tc = registry.lookup(type, from);

if (tc != null) {

Object body = file.getBody();

return tc.convertTo(type, exchange, body);

}

555

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

return null;

}

...

}

556

4 4 .3. IMPLEMENT ING A T YPE CONVERT ER DIRECT LY

Overview

Generally, the recommended way to implement a type converter is to use an annotated class,

as described in the previous section, Section 44.2, “ Implementing Type Converter Using

Annotations” . But if you want to have complete control over the registration of your type

converter, you can implement a custom slave type converter and add it directly to the type converter registry, as described here.

Implement t he T ypeConvert er int erface

To implement your own type converter class, define a class that implements the

T ypeC o nverter interface. For example, the following MyO rd erT ypeC o nverter class converts an integer value to a MyO rd er object, where the integer value is used to initialize the order ID in the MyO rd er object.

import org.apache.camel.TypeConverter

private class MyOrderTypeConverter implements TypeConverter {

public <T> T convertTo(Class<T> type, Object value) {

// converter from value to the MyOrder bean

MyOrder order = new MyOrder();

order.setId(Integer.parseInt(value.toString()));

return (T) order;

}

public <T> T convertTo(Class<T> type, Exchange exchange, Object value) {

// this method with the Exchange parameter will be preferd by

Camel to invoke

// this allows you to fetch information from the exchange during convertions

// such as an encoding parameter or the likes

return convertTo(type, value);

}

public <T> T mandatoryConvertTo(Class<T> type, Object value) {

return convertTo(type, value);

}

public <T> T mandatoryConvertTo(Class<T> type, Exchange exchange,

Object value) {

return convertTo(type, value);

}

CHAPT ER 4 4 . T YPE CO NVERT ERS

Add t he t ype convert er t o t he regist ry

You can add the custom type converter directly to the type converter registry using code like the following:

// Add the custom type converter to the type converter registry context.getTypeConverterRegistry().addTypeConverter(MyOrder.class,

String.class, new MyOrderTypeConverter());

Where co ntext is the current o rg . apache. camel . C amel C o ntext instance. The

ad d T ypeC o nverter() method registers the MyO rd erT ypeC o nverter class against the specific type conversion, from Stri ng . cl ass to MyO rd er. cl ass.

557

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 45. PRODUCER AND CONSUMER TEMPLATES

Ab st ract

The producer and consumer templates in Apache Camel are modelled after a feature of the

Spring container API, whereby access to a resource is provided through a simplified, easyto-use API known as a template. In the case of Apache Camel, the producer template and consumer template provide simplified interfaces for sending messages to and receiving messages from producer endpoints and consumer endpoints.

4 5.1. USING T HE PRODUCER T EMPLAT E

4 5.1.1. Int roduct ion t o t he Producer T emplat e

Ove rvie w

The producer template supports a variety of different approaches to invoking producer endpoints. There are methods that support different formats for the request message (as an

Exchang e object, as a message body, as a message body with a single header setting, and so on) and there are methods to support both the synchronous and the asynchronous style of invocation. Overall, producer template methods can be grouped into the following categories:

the section called “ Synchronous invocation” .

the section called “ Synchronous invocation with a processor”

the section called “ Asynchronous invocation”

the section called “ Asynchronous invocation with a callback”

Synchro no us invo cat io n

The methods for invoking endpoints synchronously have names of the form send Suffix() and req uestSuffix(). For example, the methods for invoking an endpoint using either the default message exchange pattern (MEP) or an explicitly specified MEP are named send (),

send Bo d y(), and send Bo d yAnd Head er() (where these methods respectively send an

Exchang e object, a message body, or a message body and header value). If you want to force the MEP to be InOut (request/reply semantics), you can call the req uest(),

req uestBo d y(), and req uestBo d yAnd Head er() methods instead.

The following example shows how to create a P ro d ucerT empl ate instance and use it to send a message body to the acti vemq : MyQ ueue endpoint. The example also shows how to send a message body and header value using send Bo d yAnd Head er().

import org.apache.camel.ProducerTemplate

import org.apache.camel.impl.DefaultProducerTemplate

558

CHAPT ER 4 5. PRO DUCER AND CO NSUMER T EMPLAT ES

...

ProducerTemplate template = context.createProducerTemplate();

// Send to a specific queue template.sendBody("activemq:MyQueue", "<hello>world!</hello>");

// Send with a body and header template.sendBodyAndHeader(

"activemq:MyQueue",

"<hello>world!</hello>",

"CustomerRating", "Gold" );

Synchro no us invo cat io n wit h a pro ce sso r

A special case of synchronous invocation is where you provide the send () method with a

P ro cesso r argument instead of an Exchang e argument. In this case, the producer template implicitly asks the specified endpoint to create an Exchang e instance (typically, but not always having the InOnly MEP by default). This default exchange is then passed to the processor, which initializes the contents of the exchange object.

The following example shows how to send an exchange initialized by the MyP ro cesso r processor to the acti vemq : MyQ ueue endpoint.

import org.apache.camel.ProducerTemplate

import org.apache.camel.impl.DefaultProducerTemplate

...

ProducerTemplate template = context.createProducerTemplate();

// Send to a specific queue, using a processor to initialize template.send("activemq:MyQueue", new MyProcessor());

The MyP ro cesso r class is implemented as shown in the following example. In addition to setting the In message body (as shown here), you could also initialize message heades and exchange properties.

import org.apache.camel.Processor; import org.apache.camel.Exchange;

...

public class MyProcessor implements Processor {

public MyProcessor() { }

public void process(Exchange ex) {

ex.getIn().setBody("<hello>world!</hello>");

}

Asynchro no us invo cat io n

The methods for invoking endpoints asynchronously have names of the form

asyncSend Suffix() and asyncR eq uestSuffix(). For example, the methods for invoking an endpoint using either the default message exchange pattern (MEP) or an

559

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

explicitly specified MEP are named asyncSend () and asyncSend Bo d y() (where these methods respectively send an Exchang e object or a message body). If you want to force the

MEP to be InOut (request/reply semantics), you can call the asyncR eq uestBo d y(),

asyncR eq uestBo d yAnd Head er(), and asyncR eq uestBo d yAnd Head ers() methods instead.

The following example shows how to send an exchange asynchronously to the

d i rect: start endpoint. The asyncSend () method returns a

java. uti l . co ncurrent. Future object, which is used to retrieve the invocation result at a later time.

import java.util.concurrent.Future; import org.apache.camel.Exchange; import org.apache.camel.impl.DefaultExchange;

...

Exchange exchange = new DefaultExchange(context); exchange.getIn().setBody("Hello");

Future<Exchange> future = template.asyncSend("direct:start", exchange);

// You can do other things, whilst waiting for the invocation to complete

...

// Now, retrieve the resulting exchange from the Future

Exchange result = future.get();

The producer template also provides methods to send a message body asynchronously (for example, using asyncSend Bo d y() or asyncR eq uestBo d y()). In this case, you can use one of the following helper methods to extract the returned message body from the Future object:

<T> T extractFutureBody(Future future, Class<T> type);

<T> T extractFutureBody(Future future, long timeout, TimeUnit unit,

Class<T> type) throws TimeoutException;

The first version of the extractFutureBo d y() method blocks until the invocation completes and the reply message is available. The second version of the

extractFutureBo d y() method allows you to specify a timeout. Both methods have a type argument, type, which casts the returned message body to the specified type using a built-in type converter.

The following example shows how to use the asyncR eq uestBo d y() method to send a message body to the d i rect: start endpoint. The blocking extractFutureBo d y() method is then used to retrieve the reply message body from the Future object.

Future<Object> future = template.asyncRequestBody("direct:start",

"Hello");

// You can do other things, whilst waiting for the invocation to

560

CHAPT ER 4 5. PRO DUCER AND CO NSUMER T EMPLAT ES

complete

...

// Now, retrieve the reply message body as a String type

String result = template.extractFutureBody(future, String.class);

Asynchro no us invo cat io n wit h a callback

In the preceding asynchronous examples, the request message is dispatched in a subthread, while the reply is retrieved and processed by the main thread. The producer template also gives you the option, however, of processing replies in the sub-thread, using one of the

asyncC al l back(), asyncC al l backSend Bo d y(), or

asyncC al l backR eq uestBo d y() methods. In this case, you supply a callback object (of

o rg . apache. camel . i mpl . Synchro ni zati o nAd apter type), which automatically gets invoked in the sub-thread as soon as a reply message arrives.

The Synchro ni zati o n callback interface is defined as follows: package org.apache.camel.spi; import org.apache.camel.Exchange; public interface Synchro ni zati o n {

void onComplete(Exchange exchange);

void onFailure(Exchange exchange);

}

Where the o nC o mpl ete() method is called on receipt of a normal reply and the

o nFai l ure() method is called on receipt of a fault message reply. Only one of these methods gets called back, so you must override both of them to ensure that all types of reply are processed.

The following example shows how to send an exchange to the d i rect: start endpoint, where the reply message is processed in the sub-thread by the Synchro ni zati o nAd apter callback object.

import java.util.concurrent.Future; import java.util.concurrent.TimeUnit; import org.apache.camel.Exchange; import org.apache.camel.impl.DefaultExchange; import org.apache.camel.impl.SynchronizationAdapter;

...

Exchange exchange = context.getEndpoint("direct:start").createExchange(); exchange.getIn().setBody("Hello");

Future<Exchange> future = template.asyncCallback("direct:start", exchange, new SynchronizationAdapter() {

@ Override

561

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

public void onComplete(Exchange exchange) {

assertEquals("Hello World", exchange.getIn().getBody());

}

});

Where the Synchro ni zati o nAd apter class is a default implementation of the

Synchro ni zati o n interface, which you can override to provide your own definitions of the

o nC o mpl ete() and o nFai l ure() callback methods.

You still have the option of accessing the reply from the main thread, because the

asyncC al l back() method also returns a Future object—for example:

// Retrieve the reply from the main thread, specifying a timeout

Exchange reply = future.get(10, TimeUnit.SECONDS);

4 5.1.2. Synchronous Send

Ove rvie w

The synchronous send methods are a collection of methods that you can use to invoke a producer endpoint, where the current thread blocks until the method invocation is complete and the reply (if any) has been received. These methods are compatible with any kind of message exchange protocol.

Se nd an e xchange

The basic send () method is a general-purpose method that sends the contents of an

Exchang e object to an endpoint, using the message exchange pattern (MEP) of the exchange. The return value is the exchange that you get after it has been processed by the producer endpoint (possibly containing an Out message, depending on the MEP).

There are three varieties of send () method for sending an exchange that let you specify the target endpoint in one of the following ways: as the default endpoint, as an endpoint URI, or as an End po i nt object.

Exchange send(Exchange exchange);

Exchange send(String endpointUri, Exchange exchange);

Exchange send(Endpoint endpoint, Exchange exchange);

Se nd an e xchange po pulat e d by a pro ce sso r

A simple variation of the general send () method is to use a processor to populate a default

exchange, instead of supplying the exchange object explicitly (see the section called

“ Synchronous invocation with a processor” for details).

562

CHAPT ER 4 5. PRO DUCER AND CO NSUMER T EMPLAT ES

The send () methods for sending an exchange populated by a processor let you specify the target endpoint in one of the following ways: as the default endpoint, as an endpoint URI, or as an End po i nt object. In addition, you can optionally specify the exchange's MEP by supplying the pattern argument, instead of accepting the default.

Exchange send(Processor processor);

Exchange send(String endpointUri, Processor processor);

Exchange send(Endpoint endpoint, Processor processor);

Exchange send(

String endpointUri,

ExchangePattern pattern,

Processor processor

);

Exchange send(

Endpoint endpoint,

ExchangePattern pattern,

Processor processor

);

Se nd a m e ssage bo dy

If you are only concerned with the contents of the message body that you want to send, you can use the send Bo d y() methods to provide the message body as an argument and let the producer template take care of inserting the body into a default exchange object.

The send Bo d y() methods let you specify the target endpoint in one of the following ways: as the default endpoint, as an endpoint URI, or as an End po i nt object. In addition, you can optionally specify the exchange's MEP by supplying the pattern argument, instead of accepting the default. The methods without a pattern argument return vo i d (even though the invocation might give rise to a reply in some cases); and the methods with a pattern argument return either the body of the Out message (if there is one) or the body of the In message (otherwise).

void sendBody(Object body); void sendBody(String endpointUri, Object body); void sendBody(Endpoint endpoint, Object body);

Object sendBody(

String endpointUri,

ExchangePattern pattern,

Object body

);

Object sendBody(

Endpoint endpoint,

ExchangePattern pattern,

Object body

);

Se nd a m e ssage bo dy and he ade r(s)

For testing purposes, it is often interesting to try out the effect of a single header setting and the send Bo d yAnd Head er() methods are useful for this kind of header testing. You supply the message body and header setting as arguments to send Bo d yAnd Head er() and let the

563

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

producer template take care of inserting the body and header setting into a default exchange object.

The send Bo d yAnd Head er() methods let you specify the target endpoint in one of the following ways: as the default endpoint, as an endpoint URI, or as an End po i nt object. In addition, you can optionally specify the exchange's MEP by supplying the pattern argument, instead of accepting the default. The methods without a pattern argument return

vo i d (even though the invocation might give rise to a reply in some cases); and the methods with a pattern argument return either the body of the Out message (if there is one) or the body of the In message (otherwise).

void sendBodyAndHeader(

Object body,

String header,

Object headerValue

); void sendBodyAndHeader(

String endpointUri,

Object body,

String header,

Object headerValue

); void sendBodyAndHeader(

Endpoint endpoint,

Object body,

String header,

Object headerValue

);

Object sendBodyAndHeader(

String endpointUri,

ExchangePattern pattern,

Object body,

String header,

Object headerValue

);

Object sendBodyAndHeader(

Endpoint endpoint,

ExchangePattern pattern,

Object body,

String header,

Object headerValue

);

The send Bo d yAnd Head ers() methods are similar to the send Bo d yAnd Head er() methods, except that instead of supplying just a single header setting, these methods allow you to specify a complete hash map of header settings.

void sendBodyAndHeaders(

Object body,

Map<String, Object> headers

); void sendBodyAndHeaders(

String endpointUri,

Object body,

564

CHAPT ER 4 5. PRO DUCER AND CO NSUMER T EMPLAT ES

Map<String, Object> headers

); void sendBodyAndHeaders(

Endpoint endpoint,

Object body,

Map<String, Object> headers

);

Object sendBodyAndHeaders(

String endpointUri,

ExchangePattern pattern,

Object body,

Map<String, Object> headers

);

Object sendBodyAndHeaders(

Endpoint endpoint,

ExchangePattern pattern,

Object body,

Map<String, Object> headers

);

Se nd a m e ssage bo dy and e xchange pro pe rt y

You can try out the effect of setting a single exchange property using the

send Bo d yAnd P ro perty() methods. You supply the message body and property setting as arguments to send Bo d yAnd P ro perty() and let the producer template take care of inserting the body and exchange property into a default exchange object.

The send Bo d yAnd P ro perty() methods let you specify the target endpoint in one of the following ways: as the default endpoint, as an endpoint URI, or as an End po i nt object. In addition, you can optionally specify the exchange's MEP by supplying the pattern argument, instead of accepting the default. The methods without a pattern argument return

void sendBodyAndProperty(

Object body,

String property,

Object propertyValue

); void sendBodyAndProperty(

String endpointUri,

Object body,

String property,

Object propertyValue

); void sendBodyAndProperty(

Endpoint endpoint,

Object body,

String property,

Object propertyValue

);

Object sendBodyAndProperty(

String endpoint,

565

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

ExchangePattern pattern,

Object body,

String property,

Object propertyValue

);

Object sendBodyAndProperty(

Endpoint endpoint,

ExchangePattern pattern,

Object body,

String property,

Object propertyValue

);

4 5.1.3. Synchronous Request wit h InOut Pat t ern

Ove rvie w

The synchronous request methods are similar to the synchronous send methods, except that the request methods force the message exchange pattern to be InOut (conforming to request/reply semantics). Hence, it is generally convenient to use a synchronous request method, if you expect to receive a reply from the producer endpoint.

Re que st an e xchange po pulat e d by a pro ce sso r

The basic req uest() method is a general-purpose method that uses a processor to populate a default exchange and forces the message exchange pattern to be InOut (so that the invocation obeys request/reply semantics). The return value is the exchange that you get after it has been processed by the producer endpoint, where the Out message contains the reply message.

The req uest() methods for sending an exchange populated by a processor let you specify the target endpoint in one of the following ways: as an endpoint URI, or as an End po i nt object.

Exchange request(String endpointUri, Processor processor);

Exchange request(Endpoint endpoint, Processor processor);

Re que st a m e ssage bo dy

If you are only concerned with the contents of the message body in the request and in the reply, you can use the req uestBo d y() methods to provide the request message body as an argument and let the producer template take care of inserting the body into a default exchange object.

The req uestBo d y() methods let you specify the target endpoint in one of the following ways: as the default endpoint, as an endpoint URI, or as an End po i nt object. The return value is the body of the reply message (Out message body), which can either be returned as plain O bject or converted to a specific type, T , using the built-in type converters (see

Section 42.3, “ Built-In Type Converters”

566

CHAPT ER 4 5. PRO DUCER AND CO NSUMER T EMPLAT ES

Object requestBody(Object body);

<T> T requestBody(Object body, Class<T> type);

Object requestBody(

String endpointUri,

Object body

);

<T> T requestBody(

String endpointUri,

Object body,

Class<T> type

);

Object requestBody(

Endpoint endpoint,

Object body

);

<T> T requestBody(

Endpoint endpoint,

Object body,

Class<T> type

);

Re que st a m e ssage bo dy and he ade r(s)

You can try out the effect of setting a single header value using the

req uestBo d yAnd Head er() methods. You supply the message body and header setting as arguments to req uestBo d yAnd Head er() and let the producer template take care of inserting the body and exchange property into a default exchange object.

The req uestBo d yAnd Head er() methods let you specify the target endpoint in one of the following ways: as an endpoint URI, or as an End po i nt object. The return value is the body of the reply message (Out message body), which can either be returned as plain O bject or

converted to a specific type, T , using the built-in type converters (see Section 42.3, “ Built-In

Type Converters” ).

Object requestBodyAndHeader(

String endpointUri,

Object body,

String header,

Object headerValue

);

<T> T requestBodyAndHeader(

String endpointUri,

Object body,

String header,

Object headerValue,

Class<T> type

);

Object requestBodyAndHeader(

Endpoint endpoint,

Object body,

String header,

Object headerValue

);

<T> T requestBodyAndHeader(

567

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Endpoint endpoint,

Object body,

String header,

Object headerValue,

Class<T> type

);

The req uestBo d yAnd Head ers() methods are similar to the req uestBo d yAnd Head er() methods, except that instead of supplying just a single header setting, these methods allow you to specify a complete hash map of header settings.

Object requestBodyAndHeaders(

String endpointUri,

Object body,

Map<String, Object> headers

);

<T> T requestBodyAndHeaders(

String endpointUri,

Object body,

Map<String, Object> headers,

Class<T> type

);

Object requestBodyAndHeaders(

Endpoint endpoint,

Object body,

Map<String, Object> headers

);

<T> T requestBodyAndHeaders(

Endpoint endpoint,

Object body,

Map<String, Object> headers,

Class<T> type

);

4 5.1.4 . Asynchronous Send

Ove rvie w

The producer template provides a variety of methods for invoking a producer endpoint asynchronously, so that the main thread does not block while waiting for the invocation to complete and the reply message can be retrieved at a later time. The asynchronous send methods described in this section are compatible with any kind of message exchange protocol.

Se nd an e xchange

The basic asyncSend () method takes an Exchang e argument and invokes an endpoint asynchronously, using the message exchange pattern (MEP) of the specified exchange. The return value is a java. uti l . co ncurrent. Future object, which is a ticket you can use to collect the reply message at a later time—for details of how to obtain the return value from the

Future object, see the section called “ Asynchronous invocation”

568

CHAPT ER 4 5. PRO DUCER AND CO NSUMER T EMPLAT ES

The following asyncSend () methods let you specify the target endpoint in one of the following ways: as an endpoint URI, or as an End po i nt object.

Future<Exchange> asyncSend(String endpointUri, Exchange exchange);

Future<Exchange> asyncSend(Endpoint endpoint, Exchange exchange);

Se nd an e xchange po pulat e d by a pro ce sso r

A simple variation of the general asyncSend () method is to use a processor to populate a default exchange, instead of supplying the exchange object explicitly.

The following asyncSend () methods let you specify the target endpoint in one of the following ways: as an endpoint URI, or as an End po i nt object.

Future<Exchange> asyncSend(String endpointUri, Processor processor);

Future<Exchange> asyncSend(Endpoint endpoint, Processor processor);

Se nd a m e ssage bo dy

If you are only concerned with the contents of the message body that you want to send, you can use the asyncSend Bo d y() methods to send a message body asynchronously and let the producer template take care of inserting the body into a default exchange object.

The asyncSend Bo d y() methods let you specify the target endpoint in one of the following ways: as an endpoint URI, or as an End po i nt object.

Future<Object> asyncSendBody(String endpointUri, Object body);

Future<Object> asyncSendBody(Endpoint endpoint, Object body);

4 5.1.5. Asynchronous Request wit h InOut Pat t ern

Ove rvie w

The asynchronous request methods are similar to the asynchronous send methods, except that the request methods force the message exchange pattern to be InOut (conforming to request/reply semantics). Hence, it is generally convenient to use an asynchronous request method, if you expect to receive a reply from the producer endpoint.

Re que st a m e ssage bo dy

The asyncR eq uestBo d y() methods let you specify the target endpoint in one of the following ways: as an endpoint URI, or as an End po i nt object. The return value that is

569

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

retrievable from the Future object is the body of the reply message (Out message body), which can be returned either as a plain O bject or converted to a specific type, T , using a

built-in type converter (see the section called “ Asynchronous invocation”

Future<Object> asyncRequestBody(

String endpointUri,

Object body

);

<T> Future<T> asyncRequestBody(

String endpointUri,

Object body,

Class<T> type

);

Future<Object> asyncRequestBody(

Endpoint endpoint,

Object body

);

<T> Future<T> asyncRequestBody(

Endpoint endpoint,

Object body,

Class<T> type

);

Re que st a m e ssage bo dy and he ade r(s)

570

You can try out the effect of setting a single header value using the

asyncR eq uestBo d yAnd Head er() methods. You supply the message body and header setting as arguments to asyncR eq uestBo d yAnd Head er() and let the producer template take care of inserting the body and exchange property into a default exchange object.

The asyncR eq uestBo d yAnd Head er() methods let you specify the target endpoint in one of the following ways: as an endpoint URI, or as an End po i nt object. The return value that is retrievable from the Future object is the body of the reply message (Out message body), which can be returned either as a plain O bject or converted to a specific type, T , using a

built-in type converter (see the section called “ Asynchronous invocation”

Future<Object> asyncRequestBodyAndHeader(

String endpointUri,

Object body,

String header,

Object headerValue

);

<T> Future<T> asyncRequestBodyAndHeader(

String endpointUri,

Object body,

String header,

Object headerValue,

Class<T> type

);

Future<Object> asyncRequestBodyAndHeader(

Endpoint endpoint,

Object body,

String header,

Object headerValue

CHAPT ER 4 5. PRO DUCER AND CO NSUMER T EMPLAT ES

);

<T> Future<T> asyncRequestBodyAndHeader(

Endpoint endpoint,

Object body,

String header,

Object headerValue,

Class<T> type

);

The asyncR eq uestBo d yAnd Head ers() methods are similar to the

asyncR eq uestBo d yAnd Head er() methods, except that instead of supplying just a single header setting, these methods allow you to specify a complete hash map of header settings.

Future<Object> asyncRequestBodyAndHeaders(

String endpointUri,

Object body,

Map<String, Object> headers

);

<T> Future<T> asyncRequestBodyAndHeaders(

String endpointUri,

Object body,

Map<String, Object> headers,

Class<T> type

);

Future<Object> asyncRequestBodyAndHeaders(

Endpoint endpoint,

Object body,

Map<String, Object> headers

);

<T> Future<T> asyncRequestBodyAndHeaders(

Endpoint endpoint,

Object body,

Map<String, Object> headers,

Class<T> type

);

4 5.1.6. Asynchronous Send wit h Callback

Ove rvie w

The producer template also provides the option of processing the reply message in the same sub-thread that is used to invoke the producer endpoint. In this case, you provide a callback object, which automatically gets invoked in the sub-thread as soon as the reply message is received. In other words, the asynchronous send with callback methods enable you to initiate an invocation in your main thread and then have all of the associated processing— invocation of the producer endpoint, waiting for a reply and processing the reply—occur asynchronously in a sub-thread.

Se nd an e xchange

The basic asyncC al l back() method takes an Exchang e argument and invokes an endpoint asynchronously, using the message exchange pattern (MEP) of the specified

571

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

exchange. This method is similar to the asyncSend () method for exchanges, except that it takes an additional o rg . apache. camel . spi . Synchro ni zati o n argument, which is a callback interface with two methods: o nC o mpl ete() and o nFai l ure(). For details of how

to use the Synchro ni zati o n callback, see the section called “ Asynchronous invocation with a callback” .

The following asyncC al l back() methods let you specify the target endpoint in one of the following ways: as an endpoint URI, or as an End po i nt object.

Future<Exchange> asyncCallback(

String endpointUri,

Exchange exchange,

Synchronization onCompletion

);

Future<Exchange> asyncCallback(

Endpoint endpoint,

Exchange exchange,

Synchronization onCompletion

);

Se nd an e xchange po pulat e d by a pro ce sso r

The asyncC al l back() method for processors calls a processor to populate a default exchange and forces the message exchange pattern to be InOut (so that the invocation obeys request/reply semantics).

The following asyncC al l back() methods let you specify the target endpoint in one of the following ways: as an endpoint URI, or as an End po i nt object.

Future<Exchange> asyncCallback(

String endpointUri,

Processor processor,

Synchronization onCompletion

);

Future<Exchange> asyncCallback(

Endpoint endpoint,

Processor processor,

Synchronization onCompletion

);

572

Se nd a m e ssage bo dy

If you are only concerned with the contents of the message body that you want to send, you can use the asyncC al l backSend Bo d y() methods to send a message body asynchronously and let the producer template take care of inserting the body into a default exchange object.

The asyncC al l backSend Bo d y() methods let you specify the target endpoint in one of the following ways: as an endpoint URI, or as an End po i nt object.

Future<Object> asyncCallbackSendBody(

CHAPT ER 4 5. PRO DUCER AND CO NSUMER T EMPLAT ES

String endpointUri,

Object body,

Synchronization onCompletion

);

Future<Object> asyncCallbackSendBody(

Endpoint endpoint,

Object body,

Synchronization onCompletion

);

Re que st a m e ssage bo dy

If you are only concerned with the contents of the message body in the request and in the reply, you can use the asyncC al l backR eq uestBo d y() methods to provide the request message body as an argument and let the producer template take care of inserting the body into a default exchange object.

The asyncC al l backR eq uestBo d y() methods let you specify the target endpoint in one of the following ways: as an endpoint URI, or as an End po i nt object.

Future<Object> asyncCallbackRequestBody(

String endpointUri,

Object body,

Synchronization onCompletion

);

Future<Object> asyncCallbackRequestBody(

Endpoint endpoint,

Object body,

Synchronization onCompletion

);

4 5.2. USING T HE CONSUMER T EMPLAT E

Overview

The consumer template provides methods for polling a consumer endpoint in order to receive incoming messages. You can choose to receive the incoming message either in the form of an exchange object or in the form of a message body (where the message body can be cast to a particular type using a built-in type converter).

Example of polling exchanges

You can use a consumer template to poll a consumer endpoint for exchanges using one of the following polling methods: blocking recei ve(); recei ve() with a timeout; or

recei veNo Wai t(), which returns immediately. Because a consumer endpoint represents a service, it is also essential to start the service thread by calling start() before you attempt to poll for exchanges.

The following example shows how to poll an exchange from the sed a: fo o consumer endpoint using the blocking recei ve() method:

573

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

import org.apache.camel.ProducerTemplate; import org.apache.camel.ConsumerTemplate; import org.apache.camel.Exchange;

...

ProducerTemplate template = context.createProducerTemplate();

ConsumerTemplate consumer = context.createConsumerTemplate();

// Start the consumer service consumer.start();

...

template.sendBody("seda:foo", "Hello");

Exchange out = consumer.recei ve("seda:foo");

...

// Stop the consumer service consumer.sto p();

Where the consumer template instance, co nsumer, is instantiated using the

C amel C o ntext. createC o nsumerT empl ate() method and the consumer service thread is started by calling C o nsumerT empl ate. start().

Example of polling message bodies

You can also poll a consumer endpoint for incoming message bodies using one of the following methods: blocking recei veBo d y(); recei veBo d y() with a timeout; or

recei veBo d yNo Wai t(), which returns immediately. As in the previous example, it is also essential to start the service thread by calling start() before you attempt to poll for exchanges.

The following example shows how to poll an incoming message body from the sed a: fo o consumer endpoint using the blocking recei veBo d y() method: import org.apache.camel.ProducerTemplate; import org.apache.camel.ConsumerTemplate;

...

ProducerTemplate template = context.createProducerTemplate();

ConsumerTemplate consumer = context.createConsumerTemplate();

// Start the consumer service consumer.start();

...

template.sendBody("seda:foo", "Hello");

Object body = consumer.recei veBo d y("seda:foo");

...

// Stop the consumer service consumer.sto p();

Met hods for polling exchanges

574

CHAPT ER 4 5. PRO DUCER AND CO NSUMER T EMPLAT ES

There are three basic methods for polling exchanges from a consumer endpoint: recei ve() without a timeout blocks indefinitely; recei ve() with a timeout blocks for the specified period of milliseconds; and recei veNo Wai t() is non-blocking. You can specify the consumer endpoint either as an endpoint URI or as an End po i nt instance.

Exchange receive(String endpointUri);

Exchange receive(String endpointUri, long timeout);

Exchange receiveNoWait(String endpointUri);

Exchange receive(Endpoint endpoint);

Exchange receive(Endpoint endpoint, long timeout);

Exchange receiveNoWait(Endpoint endpoint);

Met hods for polling message bodies

There are three basic methods for polling message bodies from a consumer endpoint:

recei veBo d y() without a timeout blocks indefinitely; recei veBo d y() with a timeout blocks for the specified period of milliseconds; and recei veBo d yNo Wai t() is nonblocking. You can specify the consumer endpoint either as an endpoint URI or as an

End po i nt instance. Moreover, by calling the templating forms of these methods, you can convert the returned body to a particular type, T , using a built-in type converter.

Object receiveBody(String endpointUri);

Object receiveBody(String endpointUri, long timeout);

Object receiveBodyNoWait(String endpointUri);

Object receiveBody(Endpoint endpoint);

Object receiveBody(Endpoint endpoint, long timeout);

Object receiveBodyNoWait(Endpoint endpoint);

<T> T receiveBody(String endpointUri, Class<T> type);

<T> T receiveBody(String endpointUri, long timeout, Class<T> type);

<T> T receiveBodyNoWait(String endpointUri, Class<T> type);

<T> T receiveBody(Endpoint endpoint, Class<T> type);

<T> T receiveBody(Endpoint endpoint, long timeout, Class<T> type);

<T> T receiveBodyNoWait(Endpoint endpoint, Class<T> type);

575

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 46. IMPLEMENTING A COMPONENT

Ab st ract

This chapter provides a general overview of the approaches can be used to implement a

Apache Camel component.

4 6.1. COMPONENT ARCHIT ECT URE

4 6.1.1. Fact ory Pat t erns for a Component

Ove rvie w

A Apache Camel component consists of a set of classes that are related to each other through a factory pattern. The primary entry point to a component is the C o mpo nent object itself (an instance of o rg . apache. camel . C o mpo nent type). You can use the C o mpo nent object as a factory to create End po i nt objects, which in turn act as factories for creating

C o nsumer, P ro d ucer, and Exchang e objects. These relationships are summarized in

Figure 46.1, “ Component Factory Patterns”

Fig u re 4 6 .1. Co mp o n en t Fact o ry Pat t ern s

576

Co m po ne nt

A component implementation is an endpoint factory. The main task of a component implementor is to implement the C o mpo nent. createEnd po i nt() method, which is responsible for creating new endpoints on demand.

Each kind of component must be associated with a component prefix that appears in an endpoint URI. For example, the file component is usually associated with the file prefix, which can be used in an endpoint URI like file://tmp/messages/input. When you install a new component in Apache Camel, you must define the association between a particular component prefix and the name of the class that implements the component.

CHAPT ER 4 6 . IMPLEMENT ING A CO MPO NENT

Endpo int

Each endpoint instance encapsulates a particular endpoint URI. Every time Apache Camel encounters a new endpoint URI, it creates a new endpoint instance. An endpoint object is also a factory for creating consumer endpoints and producer endpoints.

Endpoints must implement the o rg . apache. camel . End po i nt interface. The End po i nt interface defines the following factory methods:

createC o nsumer() and createP o l l i ng C o nsumer()—Creates a consumer endpoint, which represents the source endpoint at the beginning of a route.

createP ro d ucer()—Creates a producer endpoint, which represents the target endpoint at the end of a route.

createExchang e()—Creates an exchange object, which encapsulates the messages passed up and down the route.

Co nsum e r

Consumer endpoints consume requests. They always appear at the start of a route and they encapsulate the code responsible for receiving incoming requests and dispatching outgoing replies. From a service-oriented prospective a consumer represents a service.

Consumers must implement the o rg . apache. camel . C o nsumer interface. There are a number of different patterns you can follow when implementing a consumer. These patterns

are described in Section 46.1.3, “ Consumer Patterns and Threading” .

Pro duce r

Producer endpoints produce requests. They always appears at the end of a route and they encapsulate the code responsible for dispatching outgoing requests and receiving incoming replies. From a service-oriented prospective a producer represents a service consumer.

Producers must implement the o rg . apache. camel . P ro d ucer interface. You can optionally implement the producer to support an asynchronous style of processing. See

Section 46.1.4, “ Asynchronous Processing” for details.

Exchange

Exchange objects encapsulate a related set of messages. For example, one kind of message exchange is a synchronous invocation, which consists of a request message and its related reply.

Exchanges must implement the o rg . apache. camel . Exchang e interface. The default implementation, D efaul tExchang e, is sufficient for many component implementations.

However, if you want to associated extra data with the exchanges or have the exchanges preform additional processing, it can be useful to customize the exchange implementation.

577

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Me ssage

There are two different message slots in an Exchang e object:

In message—holds the current message.

Out message—temporarily holds a reply message.

All of the message types are represented by the same Java object,

o rg . apache. camel . Messag e. It is not always necessary to customize the message implementation—the default implementation, D efaul tMessag e, is usually adequate.

4 6.1.2. Using a Component in a Rout e

Ove rvie w

A Apache Camel route is essentially a pipeline of processors, of

o rg . apache. camel . P ro cesso r type. Messages are encapsulated in an exchange object, E, which gets passed from node to node by invoking the pro cess() method. The

architecture of the processor pipeline is illustrated in Figure 46.2, “ Consumer and Producer

Instances in a Route” .

Fig u re 4 6 .2. Co n su mer an d Pro d u cer In st an ces in a Ro u t e

578

So urce e ndpo int

At the start of the route, you have the source endpoint, which is represented by an

o rg . apache. camel . C o nsumer object. The source endpoint is responsible for accepting incoming request messages and dispatching replies. When constructing the route, Apache

Camel creates the appropriate C o nsumer type based on the component prefix from the

endpoint URI, as described in Section 46.1.1, “ Factory Patterns for a Component”

Pro ce sso rs

Each intermediate node in the pipeline is represented by a processor object (implementing the o rg . apache. camel . P ro cesso r interface). You can insert either standard processors

(for example, fi l ter, thro ttl er, or d el ayer) or insert your own custom processor implementations.

T arge t e ndpo int

CHAPT ER 4 6 . IMPLEMENT ING A CO MPO NENT

At the end of the route is the target endpoint, which is represented by an

o rg . apache. camel . P ro d ucer object. Because it comes at the end of a processor pipeline, the producer is also a processor object (implementing the

o rg . apache. camel . P ro cesso r interface). The target endpoint is responsible for sending outgoing request messages and receiving incoming replies. When constructing the route, Apache Camel creates the appropriate P ro d ucer type based on the component prefix from the endpoint URI.

4 6.1.3. Consumer Pat t erns and T hreading

Ove rvie w

The pattern used to implement the consumer determines the threading model used in processing the incoming exchanges. Consumers can be implemented using one of the following patterns:

Event-driven pattern —The consumer is driven by an external thread.

Scheduled poll pattern —The consumer is driven by a dedicated thread pool.

Polling pattern

—The threading model is left undefined.

Eve nt -drive n pat t e rn

In the event-driven pattern, the processing of an incoming request is initiated when another part of the application (typically a third-party library) calls a method implemented by the consumer. A good example of an event-driven consumer is the Apache Camel JMX component, where events are initiated by the JMX library. The JMX library calls the

hand l eNo ti fi cati o n() method to initiate request processing—see

Example 49.4,

“ JMXConsumer Implementation” for details.

Figure 46.3, “ Event-Driven Consumer” shows an outline of the event-driven consumer

pattern. In this example, it is assumed that processing is triggered by a call to the notify() method.

Fig u re 4 6 .3. Even t - Driven Co n su mer

The event-driven consumer processes incoming requests as follows:

579

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

1. The consumer must implement a method to receive the incoming event (in

Figure 46.3, “ Event-Driven Consumer” this is represented by the notify() method).

The thread that calls notify() is normally a separate part of the application, so the consumer's threading policy is externally driven.

For example, in the case of the JMX consumer implementation, the consumer implements the No ti fi cati o nLi stener. hand l eNo ti fi cati o n() method to receive notifications from JMX. The threads that drive the consumer processing are created within the JMX layer.

2. In the body of the notify() method, the consumer first converts the incoming event into an exchange object, E, and then calls pro cess() on the next processor in the route, passing the exchange object as its argument.

Sche dule d po ll pat t e rn

In the scheduled poll pattern, the consumer retrieves incoming requests by checking at regular time intervals whether or not a request has arrived. Checking for requests is scheduled automatically by a built-in timer class, the scheduled executor service, which is a standard pattern provided by the java.util.concurrent library. The scheduled executor service executes a particular task at timed intervals and it also manages a pool of threads, which are used to run the task instances.

Figure 46.4, “ Scheduled Poll Consumer”

shows an outline of the scheduled poll consumer pattern.

Fig u re 4 6 .4 . Sch ed u led Po ll Co n su mer

580

The scheduled poll consumer processes incoming requests as follows:

1. The scheduled executor service has a pool of threads at its disposal, that can be used to initiate consumer processing. After each scheduled time interval has elapsed, the scheduled executor service attempts to grab a free thread from its pool (there are five threads in the pool by default). If a free thread is available, it uses that thread to call the po l l () method on the consumer.

CHAPT ER 4 6 . IMPLEMENT ING A CO MPO NENT

2. The consumer's po l l () method is intended to trigger processing of an incoming request. In the body of the po l l () method, the consumer attempts to retrieve an incoming message. If no request is available, the po l l () method returns immediately.

3. If a request message is available, the consumer inserts it into an exchange object and then calls pro cess() on the next processor in the route, passing the exchange object as its argument.

Po lling pat t e rn

In the polling pattern, processing of an incoming request is initiated when a third-party calls one of the consumer's polling methods:

recei ve() recei veNo Wai t() recei ve(l o ng ti meo ut)

It is up to the component implementation to define the precise mechanism for initiating calls on the polling methods. This mechanism is not specified by the polling pattern.

Figure 46.5, “ Polling Consumer” shows an outline of the polling consumer pattern.

Fig u re 4 6 .5. Po llin g Co n su mer

The polling consumer processes incoming requests as follows:

1. Processing of an incoming request is initiated whenever one of the consumer's polling methods is called. The mechanism for calling these polling methods is implementation defined.

2. In the body of the recei ve() method, the consumer attempts to retrieve an incoming

581

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

request message. If no message is currently available, the behavior depends on which receive method was called.

recei veNo Wai t() returns immediately

recei ve(l o ng ti meo ut) waits for the specified timeout interval

[3]

before returning

recei ve() waits until a message is received

3. If a request message is available, the consumer inserts it into an exchange object and then calls pro cess() on the next processor in the route, passing the exchange object as its argument.

4 6.1.4 . Asynchronous Processing

Ove rvie w

Producer endpoints normally follow a synchronous pattern when processing an exchange.

When the preceding processor in a pipeline calls pro cess() on a producer, the

pro cess() method blocks until a reply is received. In this case, the processor's thread remains blocked until the producer has completed the cycle of sending the request and receiving the reply.

Sometimes, however, you might prefer to decouple the preceding processor from the producer, so that the processor's thread is released immediately and the pro cess() call does not block. In this case, you should implement the producer using an asynchronous pattern, which gives the preceding processor the option of invoking a non-blocking version of the pro cess() method.

To give you an overview of the different implementation options, this section describes both the synchronous and the asynchronous patterns for implementing a producer endpoint.

Synchro no us pro duce r

Figure 46.6, “ Synchronous Producer”

shows an outline of a synchronous producer, where the preceding processor blocks until the producer has finished processing the exchange.

Fig u re 4 6 .6 . Syn ch ro n o u s Pro d u cer

582

CHAPT ER 4 6 . IMPLEMENT ING A CO MPO NENT

The synchronous producer processes an exchange as follows:

1. The preceding processor in the pipeline calls the synchronous pro cess() method on the producer to initiate synchronous processing. The synchronous pro cess() method takes a single exchange argument.

2. In the body of the pro cess() method, the producer sends the request (In message) to the endpoint.

3. If required by the exchange pattern, the producer waits for the reply (Out message) to arrive from the endpoint. This step can cause the pro cess() method to block indefinitely. However, if the exchange pattern does not mandate a reply, the

pro cess() method can return immediately after sending the request.

4. When the pro cess() method returns, the exchange object contains the reply from the synchronous call (an Out message message).

Asynchro no us pro duce r

Figure 46.7, “ Asynchronous Producer”

shows an outline of an asynchronous producer, where the producer processes the exchange in a sub-thread, and the preceding processor is not blocked for any significant length of time.

Fig u re 4 6 .7. Asyn ch ro n o u s Pro d u cer

583

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

584

The asynchronous producer processes an exchange as follows:

1. Before the processor can call the asynchronous pro cess() method, it must create an asynchronous callback object, which is responsible for processing the exchange on the return portion of the route. For the asynchronous callback, the processor must implement a class that inherits from the AsyncC al l back interface.

2. The processor calls the asynchronous pro cess() method on the producer to initiate asynchronous processing. The asynchronous pro cess() method takes two arguments: an exchange object a synchronous callback object

3. In the body of the pro cess() method, the producer creates a R unnabl e object that encapsulates the processing code. The producer then delegates the execution of this

R unnabl e object to a sub-thread.

4. The asynchronous pro cess() method returns, thereby freeing up the processor's thread. The exchange processing continues in a separate sub-thread.

5. The R unnabl e object sends the In message to the endpoint.

6. If required by the exchange pattern, the R unnabl e object waits for the reply (Out or

Fault message) to arrive from the endpoint. The R unnabl e object remains blocked until the reply is received.

CHAPT ER 4 6 . IMPLEMENT ING A CO MPO NENT

7. After the reply arrives, the R unnabl e object inserts the reply (Out message) into the exchange object and then calls d o ne() on the asynchronous callback object. The asynchronous callback is then responsible for processing the reply message

(executed in the sub-thread).

4 6.2. HOW T O IMPLEMENT A COMPONENT

Overview

This section gives a brief overview of the steps required to implement a custom Apache

Camel component.

Which int erfaces do you need t o implement ?

When implementing a component, it is usually necessary to implement the following Java interfaces:

o rg . apache. camel . C o mpo nent o rg . apache. camel . End po i nt o rg . apache. camel . C o nsumer o rg . apache. camel . P ro d ucer

In addition, it can also be necessary to implement the following Java interfaces:

o rg . apache. camel . Exchang e o rg . apache. camel . Messag e

Implement at ion st eps

You typically implement a custom component as follows:

1. Implement the Component interface—A component object acts as an endpoint factory.

You extend the D efaul tC o mpo nent class and implement the createEnd po i nt() method.

See Chapter 47, Component Interface .

2. Implement the Endpoint interface—An endpoint represents a resource identified by a specific URI. The approach taken when implementing an endpoint depends on whether the consumers follow an event-driven pattern, a scheduled poll pattern, or a

polling pattern.

585

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

For an event-driven pattern, implement the endpoint by extending the

D efaul tEnd po i nt class and implementing the following methods:

createP ro d ucer() createC o nsumer()

For a scheduled poll pattern, implement the endpoint by extending the

Sched ul ed P o l l End po i nt class and implementing the following methods:

createP ro d ucer() createC o nsumer()

For a polling pattern, implement the endpoint by extending the

D efaul tP o l l i ng End po i nt class and implementing the following methods:

createP ro d ucer() createP o l l C o nsumer()

See Chapter 48, Endpoint Interface

3. Implement the Consumer interface—There are several different approaches you can take to implementing a consumer, depending on which pattern you need to implement (event-driven, scheduled poll, or polling). The consumer implementation is also crucially important for determining the threading model used for processing a message exchange.

See Section 49.2, “ Implementing the Consumer Interface” .

4. Implement the Producer interface—To implement a producer, you extend the

D efaul tP ro d ucer class and implement the pro cess() method.

See Chapter 50, Producer Interface .

5. Optionally implement the Exchange or the Message interface—The default implementations of Exchang e and Messag e can be used directly, but occasionally, you might find it necessary to customize these types.

See Chapter 51, Exchange Interface

and Chapter 52, Message Interface .

Inst alling and configuring t he component

You can install a custom component in one of the following ways:

586

Add the component directly to the CamelContext—The C amel C o ntext. ad d C o mpo nent()

CHAPT ER 4 6 . IMPLEMENT ING A CO MPO NENT

Add the component directly to the CamelContext—The C amel C o ntext. ad d C o mpo nent() method adds a component programatically.

Add the component using Spring configuration—The standard Spring bean element creates a component instance. The bean's i d attribute implicitly defines the component prefix. For

details, see Section 46.3.2, “ Configuring a Component”

Configure Apache Camel to auto-discover the component—Auto-discovery, ensures that

Apache Camel automatically loads the component on demand. For details, see

Section 46.3.1, “ Setting Up Auto-Discovery”

4 6.3. AUT O-DISCOVERY AND CONFIGURAT ION

4 6.3.1. Set t ing Up Aut o-Discovery

Ove rvie w

Auto-discovery is a mechanism that enables you to dynamically add components to your

Apache Camel application. The component URI prefix is used as a key to load components on demand. For example, if Apache Camel encounters the endpoint URI, activemq://MyQName, and the ActiveMQ endpoint is not yet loaded, Apache Camel searches for the component identified by the activemq prefix and dynamically loads the component.

Availabilit y o f co m po ne nt classe s

Before configuring auto-discovery, you must ensure that your custom component classes are accessible from your current classpath. Typically, you bundle the custom component classes into a JAR file, and add the JAR file to your classpath.

Co nfiguring aut o -disco ve ry

To enable auto-discovery of your component, create a Java properties file named after the component prefix, component-prefix, and store that file in the following location:

/META-INF/services/org/apache/camel/component/component-prefix

The component-prefix properties file must contain the following property setting: class=component-class-name

Where component-class-name is the fully-qualified name of your custom component class.

You can also define additional system property settings in this file.

Exam ple

For example, you can enable auto-discovery for the Apache Camel FTP component by creating the following Java properties file:

587

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

/META-INF/services/org/apache/camel/component/ftp

Which contains the following Java property setting: class=org.apache.camel.component.file.remote.RemoteFileComponent

No t e

The Java properties file for the FTP component is already defined in the JAR file,

camel -ftp-Version. jar.

4 6.3.2. Configuring a Component

Ove rvie w

You can add a component by configuring it in the Apache Camel Spring configuration file,

MET A-INF/spri ng /camel -co ntext. xml . To find the component, the component's URI prefix is matched against the ID attribute of a bean element in the Spring configuration. If the component prefix matches a bean element ID, Apache Camel instantiates the referenced class and injects the properties specified in the Spring configuration.

No t e

This mechanism has priority over auto-discovery. If the CamelContext finds a

Spring bean with the requisite ID, it will not attempt to find the component using auto-discovery.

De fine be an pro pe rt ie s o n yo ur co m po ne nt class

If there are any properties that you want to inject into your component class, define them as bean properties. For example: public class CustomComponent extends

DefaultComponent<CustomExchange> {

...

PropType getProperty() { ... }

void setProperty(PropType v) { ... }

}

The g etProperty() method and the setProperty() method access the value of property.

Co nfigure t he co m po ne nt in Spring

To configure a component in Spring, edit the configuration file, MET A-

INF/spri ng /camel -co ntext. xml , as shown in

Example 46.1, “ Configuring a

Component in Spring” .

588

CHAPT ER 4 6 . IMPLEMENT ING A CO MPO NENT

Examp le 4 6 .1. Co n f ig u rin g a Co mp o n en t in Sp rin g

<?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.0.xsd

http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd" >

RouteBuilderPackage

</package>

</camelContext>

</bean>

</beans>

The bean element with ID component-prefix configures the component-class-name component.

You can inject properties into the component instance using pro perty elements. For example, the pro perty element in the preceding example would inject the value,

propertyValue, into the property property by calling setProperty() on the component.

Exam ple s

Example 46.2, “ JMS Component Spring Configuration” shows an example of how to

configure the Apache Camel's JMS component by defining a bean element with ID equal to

jms. These settings are added to the Spring configuration file, camel -co ntext. xml .

Examp le 4 6 .2. JMS Co mp o n en t Sp rin g Co n f ig u rat io n

<?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.0.xsd

http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">

<package>org.apache.camel.example.spring</package>

</camelContext>

<bean id="jms"

589

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

class="org.apache.camel.component.jms.JmsComponent">

<property name="brokerURL"

value="vm://localhost?

broker.persistent=false& amp;broker.useJmx=false"/>

</bean>

</property>

</bean>

</beans>

The C amel C o ntext automatically instantiates any R o uteBui l d er classes that it finds in the specified Java package, org.apache.camel.example.spring.

The bean element with ID, jms, configures the JMS component. The bean ID corresponds to the component's URI prefix. For example, if a route specifies an endpoint with the URI, jms://MyQName, Apache Camel automatically loads the JMS component using the settings from the jms bean element.

JMS is just a wrapper for a messaging service. You must specify the concrete implementation of the messaging system by setting the co nnecti o nFacto ry property on the JmsC o mpo nent class.

In this example, the concrete implementation of the JMS messaging service is Apache

ActiveMQ. The bro kerUR L property initializes a connection to an ActiveMQ broker instance, where the message broker is embedded in the local Java virtual machine

(JVM). If a broker is not already present in the JVM, ActiveMQ will instantiate it with the options bro ker. persi stent= fal se (the broker does not persist messages) and bro ker. useJmx= fal se (the broker does not open a JMX port).

[3]

The timeo ut interval is typ ically sp ecified in milliseco nd s.

590

CHAPT ER 4 7 . CO MPO NENT INT ERFACE

CHAPTER 47. COMPONENT INTERFACE

Ab st ract

This chapter describes how to implement the C o mpo nent interface.

4 7.1. T HE COMPONENT INT ERFACE

Overview

To implement a Apache Camel component, you must implement the

o rg . apache. camel . C o mpo nent interface. An instance of C o mpo nent type provides the entry point into a custom component. That is, all of the other objects in a component are

ultimately accessible through the C o mpo nent instance. Figure 47.1, “ Component Inheritance

Hierarchy” shows the relevant Java interfaces and classes that make up the C o mpo nent

inheritance hierarchy.

Fig u re 4 7.1. Co mp o n en t In h erit an ce Hierarch y

T he Component int erface

Example 47.1, “ Component Interface” shows the definition of the

o rg . apache. camel . C o mpo nent interface.

Examp le 4 7.1. Co mp o n en t In t erf ace

package org.apache.camel; public interface Component {

CamelContext getCamelContext(); void setCamelContext(CamelContext context);

Endpoint createEndpoint(String uri) throws Exception;

}

591

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Component met hods

The C o mpo nent interface defines the following methods:

g etC amel C o ntext() and setC amel C o ntext()—References the C amel C o ntext to which this C o mpo nent belongs. The setC amel C o ntext() method is automatically called when you add the component to a C amel C o ntext.

createEnd po i nt()—The factory method that gets called to create End po i nt instances for this component. The uri parameter is the endpoint URI, which contains the details required to create the endpoint.

4 7.2. IMPLEMENT ING T HE COMPONENT INT ERFACE

T he Default Component class

You implement a new component by extending the

o rg . apache. camel . i mpl . D efaul tC o mpo nent class, which provides some standard functionality and default implementations for some of the methods. In particular, the

D efaul tC o mpo nent class provides support for URI parsing and for creating a scheduled

executor (which is used for the scheduled poll pattern).

URI parsing

The createEnd po i nt(Stri ng uri ) method defined in the base C o mpo nent interface takes a complete, unparsed endpoint URI as its sole argument. The D efaul tC o mpo nent class, on the other hand, defines a three-argument version of the createEnd po i nt() method with the following signature: protected abstract Endpoint createEndpoint(

String uri,

String remaining,

Map parameters

) throws Exception;

uri is the original, unparsed URI; remai ni ng is the part of the URI that remains after stripping off the component prefix at the start and cutting off the query options at the end; and parameters contains the parsed query options. It is this version of the

createEnd po i nt() method that you must override when inheriting from

D efaul tC o mpo nent. This has the advantage that the endpoint URI is already parsed for you.

The following sample endpoint URI for the fi l e component shows how URI parsing works in practice: file:///tmp/messages/foo?delete=true& moveNamePostfix=.old

592

CHAPT ER 4 7 . CO MPO NENT INT ERFACE

For this URI, the following arguments are passed to the three-argument version of

createEnd po i nt():

Argument uri remai ni ng parameters

Sample Value

file:///tmp /messag es/fo o ?d elete=true&mo veNamePo stfix=.o ld

/tmp/messag es/fo o

Two entries are set in

java. uti l . Map

: p arameter

d el ete

is b o o lean

true

p arameter

mo veNameP o stfi x

has the string value,

. o l d

Paramet er inject ion

By default, the parameters extracted from the URI query options are injected on the endpoint's bean properties. The D efaul tC o mpo nent class automatically injects the parameters for you.

For example, if you want to define a custom endpoint that supports two URI query options:

d el ete and mo veNameP o stfi x. All you must do is define the corresponding bean methods (getters and setters) in the endpoint class: public class FileEndpoint extends ScheduledPollEndpoint {

...

public boolean isDelete() { return delete;

} public void setDelete( boolean delete) { this .delete = delete;

}

...

public String getMoveNamePostfix() { return moveNamePostfix;

} public void setMoveNamePostfix(String moveNamePostfix) { this .moveNamePostfix = moveNamePostfix;

}

It is also possible to inject URI query options into consumer parameters. For details, see the section called “ Consumer parameter injection” .

Disabling endpoint paramet er inject ion

593

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

If there are no parameters defined on your End po i nt class, you can optimize the process of endpoint creation by disabling endpoint parameter injection. To disable parameter injection on endpoints, override the useIntro specti o nO nEnd po i nt() method and implement it to return fal se, as follows: protected boolean useIntrospectionOnEndpoint() {

return false;

}

No t e

The useIntro specti o nO nEnd po i nt() method does not affect the parameter injection that might be performed on a C o nsumer class. Parameter injection at that level is controlled by the End po i nt. co nfi g ureP ro perti es() method (see

Section 48.2, “ Implementing the Endpoint Interface” ).

Scheduled execut or service

The scheduled executor is used in the scheduled poll pattern, where it is responsible for driving the periodic polling of a consumer endpoint (a scheduled executor is effectively a thread pool implementation).

To instantiate a scheduled executor service, use the Executo rServi ceStrateg y object that is returned by the C amel C o ntext. g etExecuto rServi ceStrateg y() method. For details of the Apache Camel threading model, see

Section 2.8, “ Threading Model” .

No t e

Prior to Apache Camel 2.3, the D efaul tC o mpo nent class provided a

g etExecuto rServi ce() method for creating thread pool instances. Since 2.3, however, the creation of thread pools is now managed centrally by the

Executo rServi ceStrateg y object.

Validat ing t he URI

If you want to validate the URI before creating an endpoint instance, you can override the

val i d ateUR I() method from the D efaul tC o mpo nent class, which has the following signature:

pro tected vo i d val i d ateUR I(Stri ng uri ,

Stri ng path,

Map parameters)

thro ws R eso l veEnd po i ntFai l ed Excepti o n;

If the supplied URI does not have the required format, the implementation of

val i d ateUR I() should throw the

o rg . apache. camel . R eso l veEnd po i ntFai l ed Excepti o n exception.

Creat ing an endpoint

594

CHAPT ER 4 7 . CO MPO NENT INT ERFACE

Example 47.2, “ Implementation of createEnd po i nt()” outlines how to implement the

D efaul tC o mpo nent. createEnd po i nt() method, which is responsible for creating endpoint instances on demand.

Examp le 4 7.2. Imp lemen t at io n o f createEnd po i nt()

public class CustomComponent extends DefaultComponent {

...

protected Endpoint createEndpoint(String uri, String remaining,

Map parameters) throws Exception {

CustomEndpoint result = new CustomEndpoint(uri, this);

// ...

return result;

}

The CustomComponent is the name of your custom component class, which is defined by extending the D efaul tC o mpo nent class.

When extending D efaul tC o mpo nent, you must implement the createEnd po i nt() method with three arguments (see

the section called “ URI parsing” ).

Create an instance of your custom endpoint type, CustomEndpoint, by calling its constructor. At a minimum, this constructor takes a copy of the original URI string,

uri , and a reference to this component instance, thi s.

Example

Example 47.3, “ FileComponent Implementation”

shows a sample implementation of a

Fi l eC o mpo nent class.

Examp le 4 7.3. FileCo mp o n en t Imp lemen t at io n

package org.apache.camel.component.file; import org.apache.camel.CamelContext; import org.apache.camel.Endpoint; import org.apache.camel.impl.DefaultComponent;

595

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

import java.io.File; import java.util.Map; public class FileComponent extends DefaultComponent {

public static final String HEADER_FILE_NAME =

"org.apache.camel.file.name";

public FileComponent() {

}

public FileComponent(CamelContext context) {

super(context);

}

protected Endpoint createEndpoint(String uri, String remaining,

Map parameters) throws Exception {

File file = new File(remaining);

FileEndpoint result = new FileEndpoint(file, uri, this);

return result;

}

Always define a no-argument constructor for the component class in order to facilitate automatic instantiation of the class.

A constructor that takes the parent C amel C o ntext instance as an argument is convenient when creating a component instance by programming.

The implementation of the Fi l eC o mpo nent. createEnd po i nt() method follows

the pattern described in Example 47.2, “ Implementation of createEnd po i nt()”

. The implementation creates a Fi l eEnd po i nt object.

Synchroniz at ionRout eAware Int erface

Synchro ni zati o nR o uteAware interface allows you to have callbacks before and after the exchange has been routed.

o nBefo reR o ute: Invoked before the exchange has been routed by the given route.

However, this callback may not get invoked, if you add the

Synchro ni zati o nR o uteAware implementation to the Uni tO fWo rk, after starting the route.

596

o nAfterR o ute: Invoked after the exchange has been routed by the given route.

CHAPT ER 4 7 . CO MPO NENT INT ERFACE

o nAfterR o ute: Invoked after the exchange has been routed by the given route.

However, if the exchange is being routed through multiple routes, it would generate call backs for each route.

This invocation occurs before these callbacks:

The consumer of the route writes any response back to the caller (if in InO ut mode)

The Uni tO fWo rk is done by calling either

Synchro ni zati o n. o nC o mpl ete(o rg . apache. camel . Exchang e) or

Synchro ni zati o n. o nFai l ure(o rg . apache. camel . Exchang e)

597

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 48. ENDPOINT INTERFACE

Ab st ract

This chapter describes how to implement the End po i nt interface, which is an essential step in the implementation of a Apache Camel component.

4 8.1. T HE ENDPOINT INT ERFACE

Overview

An instance of o rg . apache. camel . End po i nt type encapsulates an endpoint URI, and it also serves as a factory for C o nsumer, P ro d ucer, and Exchang e objects. There are three different approaches to implementing an endpoint:

Event-driven scheduled poll polling

These endpoint implementation patterns complement the corresponding patterns for

implementing a consumer—see Section 49.2, “ Implementing the Consumer Interface”

Figure 48.1, “ Endpoint Inheritance Hierarchy” shows the relevant Java interfaces and

classes that make up the End po i nt inheritance hierarchy.

Fig u re 4 8.1. En d p o in t In h erit an ce Hierarch y

598

CHAPT ER 4 8 . ENDPO INT INT ERFACE

T he Endpoint int erface

Example 48.1, “ Endpoint Interface” shows the definition of the

o rg . apache. camel . End po i nt interface.

Examp le 4 8.1. En d p o in t In t erf ace

package org.apache.camel; public interface Endpoint { boolean isSingleton();

String getEndpointUri();

String getEndpointKey();

CamelContext getCamelContext(); void setCamelContext(CamelContext context); void configureProperties(Map options); boolean isLenientProperties();

599

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Exchange createExchange();

Exchange createExchange(ExchangePattern pattern);

Exchange createExchange(Exchange exchange);

Producer createProducer() throws Exception;

Consumer createConsumer(Processor processor) throws Exception;

PollingConsumer createPollingConsumer() throws Exception;

}

600

Endpoint met hods

The End po i nt interface defines the following methods:

i sSi ng l eto n()—Returns true, if you want to ensure that each URI maps to a single endpoint within a CamelContext. When this property is true, multiple references to the identical URI within your routes always refer to a single endpoint instance. When this property is fal se, on the other hand, multiple references to the same URI within your routes refer to distinct endpoint instances. Each time you refer to the URI in a route, a new endpoint instance is created.

g etEnd po i ntUri ()—Returns the endpoint URI of this endpoint.

g etEnd po i ntKey()—Used by o rg . apache. camel . spi . Li fecycl eStrateg y when registering the endpoint.

g etC amel C o ntext()—return a reference to the C amel C o ntext instance to which this endpoint belongs.

setC amel C o ntext()—Sets the C amel C o ntext instance to which this endpoint belongs.

co nfi g ureP ro perti es()—Stores a copy of the parameter map that is used to inject parameters when creating a new C o nsumer instance.

i sLeni entP ro perti es()—Returns true to indicate that the URI is allowed to contain unknown parameters (that is, parameters that cannot be injected on the End po i nt or the

C o nsumer class). Normally, this method should be implemented to return fal se.

createExchang e()—An overloaded method with the following variants:

Exchang e createExchang e()—Creates a new exchange instance with a default exchange pattern setting.

Exchang e createExchang e(Exchang eP attern pattern)—Creates a new exchange instance with the specified exchange pattern.

CHAPT ER 4 8 . ENDPO INT INT ERFACE

Exchang e createExchang e(Exchang e exchang e)—Converts the given

exchang e argument to the type of exchange needed for this endpoint. If the given exchange is not already of the correct type, this method copies it into a new instance of the correct type. A default implementation of this method is provided in the

D efaul tEnd po i nt class.

createP ro d ucer()—Factory method used to create new P ro d ucer instances.

createC o nsumer()—Factory method to create new event-driven consumer instances.

The pro cesso r argument is a reference to the first processor in the route.

createP o l l i ng C o nsumer()—Factory method to create new polling consumer instances.

Endpoint singlet ons

In order to avoid unnecessary overhead, it is a good idea to create a single endpoint instance for all endpoints that have the same URI (within a CamelContext). You can enforce this condition by implementing i sSi ng l eto n() to return true.

No t e

In this context, same URI means that two URIs are the same when compared using string equality. In principle, it is possible to have two URIs that are equivalent, though represented by different strings. In that case, the URIs would not be treated as the same.

4 8.2. IMPLEMENT ING T HE ENDPOINT INT ERFACE

Alt ernat ive ways of implement ing an endpoint

The following alternative endpoint implementation patterns are supported:

Event-driven endpoint implementation

Scheduled poll endpoint implementation

Polling endpoint implementation

Event -driven endpoint implement at ion

If your custom endpoint conforms to the event-driven pattern (see Section 46.1.3, “ Consumer

Patterns and Threading” ), it is implemented by extending the abstract class,

o rg . apache. camel . i mpl . D efaul tEnd po i nt, as shown in

Example 48.2,

“ Implementing DefaultEndpoint” .

601

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Examp le 4 8.2. Imp lemen t in g Def au lt En d p o in t

import java.util.Map; import java.util.concurrent.BlockingQueue; import org.apache.camel.Component; import org.apache.camel.Consumer; import org.apache.camel.Exchange; import org.apache.camel.Processor; import org.apache.camel.Producer; import org.apache.camel.impl.DefaultEndpoint; import org.apache.camel.impl.DefaultExchange; public class CustomEndpoint extends DefaultEndpoint {

public CustomEndpoint(String endpointUri, Component component)

{

super(endpointUri, component);

// Do any other initialization...

}

public Producer createProducer() throws Exception {

return new CustomProducer(this);

}

public Consumer createConsumer(Processor processor) throws

Exception {

return new CustomConsumer(this, processor);

}

public boolean isSingleton() {

return true;

}

// Implement the following methods, only if you need to set exchange properties.

public Exchange createExchange() {

return this.createExchange(getExchangePattern());

}

public Exchange createExchange(ExchangePattern pattern) {

Exchange result = new DefaultExchange(getCamelContext(), pattern);

// Set exchange properties

...

return result;

}

602

CHAPT ER 4 8 . ENDPO INT INT ERFACE

Implement an event-driven custom endpoint, CustomEndpoint, by extending the

D efaul tEnd po i nt class.

You must have at least one constructor that takes the endpoint URI, end po i ntUri , and the parent component reference, co mpo nent, as arguments.

Implement the createP ro d ucer() factory method to create producer endpoints.

Implement the createC o nsumer() factory method to create event-driven consumer instances.

Imp o rt an t

Do not override the createP o l l i ng C o nsumer() method.

In general, it is not necessary to override the createExchang e() methods. The implementations inherited from D efaul tEnd po i nt create a D efaul tExchang e object by default, which can be used in any Apache Camel component. If you need to initialize some exchange properties in the D efaul tExchang e object, however, it is appropriate to override the createExchang e() methods here in order to add the exchange property settings.

The D efaul tEnd po i nt class provides default implementations of the following methods, which you might find useful when writing your custom endpoint code:

g etEnd po i ntUri ()—Returns the endpoint URI.

g etC amel C o ntext()—Returns a reference to the C amel C o ntext.

g etC o mpo nent()—Returns a reference to the parent component.

createP o l l i ng C o nsumer()—Creates a polling consumer. The created polling consumer's functionality is based on the event-driven consumer. If you override the event-driven consumer method, createC o nsumer(), you get a polling consumer implementation for free.

603

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

createExchang e(Exchang e e)—Converts the given exchange object, e, to the type required for this endpoint. This method creates a new endpoint using the overridden

createExchang e() endpoints. This ensures that the method also works for custom exchange types.

Scheduled poll endpoint implement at ion

If your custom endpoint conforms to the scheduled poll pattern (see Section 46.1.3,

“ Consumer Patterns and Threading” ) it is implemented by inheriting from the abstract class,

o rg . apache. camel . i mpl . Sched ul ed P o l l End po i nt, as shown in

Example 48.3,

“ ScheduledPollEndpoint Implementation” .

Examp le 4 8.3. Sch ed u led Po llEn d p o in t Imp lemen t at io n

import org.apache.camel.Consumer; import org.apache.camel.Processor; import org.apache.camel.Producer; import org.apache.camel.ExchangePattern; import org.apache.camel.Message; import org.apache.camel.impl.ScheduledPollEndpoint; public class CustomEndpoint extends ScheduledPollEndpoint {

protected CustomEndpoint(String endpointUri, CustomComponent component) {

super(endpointUri, component);

// Do any other initialization...

}

public Producer createProducer() throws Exception {

Producer result = new CustomProducer(this);

return result;

}

public Consumer createConsumer(Processor processor) throws

Exception {

Consumer result = new CustomConsumer(this, processor);

configureConsumer(result);

return result;

}

public boolean isSingleton() {

return true;

}

// Implement the following methods, only if you need to set exchange properties.

public Exchange createExchange() {

return this.createExchange(getExchangePattern());

}

604

CHAPT ER 4 8 . ENDPO INT INT ERFACE

public Exchange createExchange(ExchangePattern pattern) {

Exchange result = new DefaultExchange(getCamelContext(), pattern);

// Set exchange properties

...

return result;

}

Implement a scheduled poll custom endpoint, CustomEndpoint, by extending the

Sched ul ed P o l l End po i nt class.

You must to have at least one constructor that takes the endpoint URI,

end po i ntUri , and the parent component reference, co mpo nent, as arguments.

Implement the createP ro d ucer() factory method to create a producer endpoint.

Implement the createC o nsumer() factory method to create a scheduled poll consumer instance.

Imp o rt an t

Do not override the createP o l l i ng C o nsumer() method.

The co nfi g ureC o nsumer() method, defined in the Sched ul ed P o l l End po i nt base class, is responsible for injecting consumer query options into the consumer.

See the section called “ Consumer parameter injection” .

605

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

appropriate to override the createExchang e() methods here in order to add the exchange property settings.

Polling endpoint implement at ion

If your custom endpoint conforms to the polling consumer pattern (see Section 46.1.3,

“ Consumer Patterns and Threading” ), it is implemented by inheriting from the abstract class,

o rg . apache. camel . i mpl . D efaul tP o l l i ng End po i nt, as shown in

Example 48.4,

“ DefaultPollingEndpoint Implementation” .

Examp le 4 8.4 . Def au lt Po llin g En d p o in t Imp lemen t at io n

import org.apache.camel.Consumer; import org.apache.camel.Processor; import org.apache.camel.Producer; import org.apache.camel.ExchangePattern; import org.apache.camel.Message; import org.apache.camel.impl.DefaultPollingEndpoint; public class CustomEndpoint extends DefaultPollingEndpoint {

...

public PollingConsumer createPollingConsumer() throws Exception

{

PollingConsumer result = new CustomConsumer( this );

configureConsumer(result); return result;

}

// Do NOT implement createConsumer(). It is already implemented in DefaultPollingEndpoint.

...

}

606

Because this CustomEndpoint class is a polling endpoint, you must implement the

createP o l l i ng C o nsumer() method instead of the createC o nsumer() method. The consumer instance returned from createP o l l i ng C o nsumer() must inherit from the

P o l l i ng C o nsumer interface. For details of how to implement a polling consumer, see the section called “ Polling consumer implementation” .

Apart from the implementation of the createP o l l i ng C o nsumer() method, the steps for implementing a D efaul tP o l l i ng End po i nt are similar to the steps for implementing a

Sched ul ed P o l l End po i nt. See

Example 48.3, “ ScheduledPollEndpoint Implementation”

for details.

Implement ing t he BrowsableEndpoint int erface

If you want to expose the list of exchange instances that are pending in the current endpoint, you can implement the o rg . apache. camel . spi . Bro wsabl eEnd po i nt interface, as shown in

Example 48.5, “ BrowsableEndpoint Interface”

. It makes sense to implement this

CHAPT ER 4 8 . ENDPO INT INT ERFACE

interface if the endpoint performs some sort of buffering of incoming events. For example, the

Apache Camel SEDA endpoint implements the Bro wsabl eEnd po i nt interface—see

Example 48.6, “ SedaEndpoint Implementation” .

Examp le 4 8.5. Bro wsab leEn d p o in t In t erf ace

package org.apache.camel.spi; import java.util.List; import org.apache.camel.Endpoint; import org.apache.camel.Exchange; public interface BrowsableEndpoint extends Endpoint {

List<Exchange> getExchanges();

}

Example

Example 48.6, “ SedaEndpoint Implementation” shows a sample implementation of

Sed aEnd po i nt. The SEDA endpoint is an example of an event-driven endpoint. Incoming events are stored in a FIFO queue (an instance of

java. uti l . co ncurrent. Bl o cki ng Q ueue) and a SEDA consumer starts up a thread to read and process the events. The events themselves are represented by

o rg . apache. camel . Exchang e objects.

Examp le 4 8.6 . Sed aEn d p o in t Imp lemen t at io n

package org.apache.camel.component.seda; import java.util.ArrayList; import java.util.List; import java.util.Map; import java.util.concurrent.BlockingQueue; import org.apache.camel.Component; import org.apache.camel.Consumer; import org.apache.camel.Exchange; import org.apache.camel.Processor; import org.apache.camel.Producer; import org.apache.camel.impl.DefaultEndpoint; import org.apache.camel.spi.BrowsableEndpoint; public class SedaEndpoint extends DefaultEndpoint implements

BrowsableEndpoint {

private BlockingQueue<Exchange> queue;

public SedaEndpoint(String endpointUri, Component component,

BlockingQueue<Exchange> queue) {

607

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

super(endpointUri, component);

this.queue = queue;

}

public SedaEndpoint(String uri, SedaComponent component, Map parameters) {

this(uri, component, component.createQueue(uri, parameters));

}

public Producer createProducer() throws Exception {

return new CollectionProducer(this, getQueue());

}

public Consumer createConsumer(Processor processor) throws

Exception {

return new SedaConsumer(this, processor);

}

public BlockingQueue<Exchange> getQueue() {

return queue;

}

public boolean isSingleton() {

return true;

}

public List<Exchange> getExchanges() {

return new ArrayList<Exchange>(getQueue());

}

608

The Sed aEnd po i nt class follows the pattern for implementing an event-driven endpoint by extending the D efaul tEnd po i nt class. The Sed aEnd po i nt class also implements the Bro wsabl eEnd po i nt interface, which provides access to the list of exchange objects in the queue.

Following the usual pattern for an event-driven consumer, Sed aEnd po i nt defines a constructor that takes an endpoint argument, end po i ntUri , and a component reference argument, co mpo nent.

Another constructor is provided, which delegates queue creation to the parent component instance.

CHAPT ER 4 8 . ENDPO INT INT ERFACE

The createP ro d ucer() factory method creates an instance of

C o l l ecti o nP ro d ucer, which is a producer implementation that adds events to the queue.

The createC o nsumer() factory method creates an instance of Sed aC o nsumer, which is responsible for pulling events off the queue and processing them.

The g etQ ueue() method returns a reference to the queue.

The i sSi ng l eto n() method returns true, indicating that a single endpoint instance should be created for each unique URI string.

The g etExchang es() method implements the corresponding abstract method from

Bro wsabl eEnd po i nt.

609

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 49. CONSUMER INTERFACE

Ab st ract

This chapter describes how to implement the C o nsumer interface, which is an essential step in the implementation of a Apache Camel component.

4 9.1. T HE CONSUMER INT ERFACE

Overview

An instance of o rg . apache. camel . C o nsumer type represents a source endpoint in a

route. There are several different ways of implementing a consumer (see Section 46.1.3,

“ Consumer Patterns and Threading” ), and this degree of flexibility is reflected in the

inheritance hierarchy ( see Figure 49.1, “ Consumer Inheritance Hierarchy”

), which includes several different base classes for implementing a consumer.

Fig u re 4 9 .1. Co n su mer In h erit an ce Hierarch y

610

Consumer paramet er inject ion

For consumers that follow the scheduled poll pattern (see the section called “ Scheduled poll pattern” ), Apache Camel provides support for injecting parameters into consumer instances.

For example, consider the following endpoint URI for a component identified by the custo m prefix:

CHAPT ER 4 9 . CO NSUMER INT ERFACE

custom:destination?consumer.myConsumerParam

Apache Camel provides support for automatically injecting query options of the form

co nsumer. *. For the co nsumer. myC o nsumerP aram parameter, you need to define corresponding setter and getter methods on the C o nsumer implementation class as follows: public class CustomConsumer extends ScheduledPollConsumer {

...

String getMyConsumerParam() { ... } void setMyConsumerParam(String s) { ... }

...

}

Where the getter and setter methods follow the usual Java bean conventions (including capitalizing the first letter of the property name).

In addition to defining the bean methods in your Consumer implementation, you must also remember to call the co nfi g ureC o nsumer() method in the implementation of

End po i nt. createC o nsumer(). See the section called “ Scheduled poll endpoint implementation” ). Example 49.1, “ FileEndpoint createConsumer() Implementation” shows an

example of a createC o nsumer() method implementation, taken from the Fi l eEnd po i nt class in the file component:

Examp le 4 9 .1. FileEn d p o in t creat eCo n su mer( ) Imp lemen t at io n

...

public class FileEndpoint extends ScheduledPollEndpoint {

...

public Consumer createConsumer(Processor processor) throws

Exception {

Consumer result = new FileConsumer( this , processor);

configureConsumer(result); return result;

}

...

}

At run time, consumer parameter injection works as follows:

1. When the endpoint is created, the default implementation of

D efaul tC o mpo nent. createEnd po i nt(Stri ng uri ) parses the URI to extract the consumer parameters, and stores them in the endpoint instance by calling

Sched ul ed P o l l End po i nt. co nfi g ureP ro perti es().

2. When createC o nsumer() is called, the method implementation calls

co nfi g ureC o nsumer() to inject the consumer parameters (see

Example 49.1,

“ FileEndpoint createConsumer() Implementation” ).

611

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

3. The co nfi g ureC o nsumer() method uses Java reflection to call the setter methods whose names match the relevant options after the co nsumer. prefix has been stripped off.

Scheduled poll paramet ers

A consumer that follows the scheduled poll pattern automatically supports the consumer

parameters shown in Table 49.1, “ Scheduled Poll Parameters” (which can appear as query

options in the endpoint URI).

T ab le 4 9 .1. Sch ed u led Po ll Paramet ers

Name i ni ti al D el ay d el ay useFi xed D el ay

Default

10 0 0

50 0

Descript ion

Delay, in milliseco nd s, b efo re the first p o ll.

Dep end s o n the value o f the

useFi xed D el ay

flag

(time unit is milliseco nd s).

fal se

, the

d el ay

p arameter is interp reted as the p o lling p erio d . Po lls will o ccur at

i ni ti al D el ay

i ni ti al D el ay+ d el ay

i ni ti al D el ay+ 2*d el ay

, and so o n.

true

, the

d el ay

p arameter is interp reted as the time elap sed b etween the p revio us executio n and the next executio n. Po lls will o ccur at

i ni ti al D el ay

i ni ti al D el ay+ [ProcessingTime]+ d el ay

, and so o n. Where ProcessingTime is the time taken to p ro cess an exchang e o b ject in the current thread .

612

Convert ing bet ween event -driven and polling consumers

Apache Camel provides two special consumer implementations which can be used to convert back and forth between an event-driven consumer and a polling consumer. The following conversion classes are provided:

o rg . apache. camel . i mpl . EventD ri venP o l l i ng C o nsumer—Converts an eventdriven consumer into a polling consumer instance.

o rg . apache. camel . i mpl . D efaul tSched ul ed P o l l C o nsumer—Converts a polling consumer into an event-driven consumer instance.

In practice, these classes are used to simplify the task of implementing an End po i nt type.

The End po i nt interface defines the following two methods for creating a consumer instance: package org.apache.camel;

CHAPT ER 4 9 . CO NSUMER INT ERFACE

public interface Endpoint {

...

Consumer createConsumer(Processor processor) throws Exception;

PollingConsumer createPollingConsumer() throws Exception;

}

createC o nsumer() returns an event-driven consumer and createP o l l i ng C o nsumer() returns a polling consumer. You would only implement one these methods. For example, if you are following the event-driven pattern for your consumer, you would implement the

createC o nsumer() method provide a method implementation for

createP o l l i ng C o nsumer() that simply raises an exception. With the help of the conversion classes, however, Apache Camel is able to provide a more useful default implementation.

For example, if you want to implement your consumer according to the event-driven pattern, you implement the endpoint by extending D efaul tEnd po i nt and implementing the

createC o nsumer() method. The implementation of createP o l l i ng C o nsumer() is inherited from D efaul tEnd po i nt, where it is defined as follows: public PollingConsumer<E> createPollingConsumer() throws Exception {

return new EventDrivenPollingConsumer<E>(this);

}

The EventD ri venP o l l i ng C o nsumer constructor takes a reference to the event-driven consumer, thi s, effectively wrapping it and converting it into a polling consumer. To implement the conversion, the EventD ri venP o l l i ng C o nsumer instance buffers incoming events and makes them available on demand through the recei ve(), the recei ve(l o ng

ti meo ut), and the recei veNo Wai t() methods.

Analogously, if you are implementing your consumer according to the polling pattern, you implement the endpoint by extending D efaul tP o l l i ng End po i nt and implementing the

createP o l l i ng C o nsumer() method. In this case, the implementation of the

createC o nsumer() method is inherited from D efaul tP o l l i ng End po i nt, and the default implementation returns a D efaul tSched ul ed P o l l C o nsumer instance (which converts the polling consumer into an event-driven consumer).

Shut downPrepared int erface

Consumer classes can optionally implement the

o rg . apache. camel . spi . Shutd o wnP repared interface, which enables your custom consumer endpoint to receive shutdown notifications.

Example 49.2, “ ShutdownPrepared Interface”

shows the definition of the

Shutd o wnP repared interface.

Examp le 4 9 .2. Sh u t d o wn Prep ared In t erf ace

package org.apache.camel.spi;

613

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

public interface ShutdownPrepared {

void prepareShutdown(boolean forced);

}

The Shutd o wnP repared interface defines the following methods:

prepareShutd o wn

Receives notifications to shut down the consumer endpoint in one or two phases, as follows:

1. Graceful shutdown—where the fo rced argument has the value fal se.

Attempt to clean up resources gracefully. For example, by stopping threads gracefully.

2. Forced shutdown—where the fo rced argument has the value true. This means that the shutdown has timed out, so you must clean up resources more aggressively. This is the last chance to clean up resources before the process exits.

Shut downAware int erface

Consumer classes can optionally implement the

o rg . apache. camel . spi . Shutd o wnAware interface, which interacts with the graceful shutdown mechanism, enabling a consumer to ask for extra time to shut down. This is typically needed for components such as SEDA, which can have pending exchanges stored in an internal queue. Normally, you would want to process all of the exchanges in the queue before shutting down the SEDA consumer.

Example 49.3, “ ShutdownAware Interface” shows the definition of the Shutd o wnAware

interface.

Examp le 4 9 .3. Sh u t d o wn Aware In t erf ace

// Java package org.apache.camel.spi; import org.apache.camel.ShutdownRunningTask; public interface ShutdownAware extends ShutdownPrepared {

614

CHAPT ER 4 9 . CO NSUMER INT ERFACE

boolean deferShutdown(ShutdownRunningTask shutdownRunningTask);

int getPendingExchangesSize();

}

The Shutd o wnAware interface defines the following methods:

d eferShutd o wn

Return true from this method, if you want to delay shutdown of the consumer. The

shutd o wnR unni ng T ask argument is an enum which can take either of the following values:

Shutd o wnR unni ng T ask. C o mpl eteC urrentT askO nl y—finish processing the exchanges that are currently being processed by the consumer's thread pool, but do not attempt to process any more exchanges than that.

Shutd o wnR unni ng T ask. C o mpl eteAl l T asks—process all of the pending exchanges. For example, in the case of the SEDA component, the consumer would process all of the exchanges from its incoming queue.

g etP end i ng Exchang esSi ze

Indicates how many exchanges remain to be processed by the consumer. A zero value indicates that processing is finished and the consumer can be shut down.

For an example of how to define the Shutd o wnAware methods, see Example 49.7, “ Custom

Threading Implementation” .

4 9.2. IMPLEMENT ING T HE CONSUMER INT ERFACE

Alt ernat ive ways of implement ing a consumer

You can implement a consumer in one of the following ways:

Event-driven consumer implementation

Scheduled poll consumer implementation

Polling consumer implementation

Custom threading implementation

Event -driven consumer implement at ion

615

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

In an event-driven consumer, processing is driven explicitly by external events. The events are received through an event-listener interface, where the listener interface is specific to the particular event source.

Example 49.4, “ JMXConsumer Implementation”

shows the implementation of the

JMXC o nsumer class, which is taken from the Apache Camel JMX component implementation.

The JMXC o nsumer class is an example of an event-driven consumer, which is implemented by inheriting from the o rg . apache. camel . i mpl . D efaul tC o nsumer class. In the case of the JMXC o nsumer example, events are represented by calls on the

No ti fi cati o nLi stener. hand l eNo ti fi cati o n() method, which is a standard way of receiving JMX events. In order to receive these JMX events, it is necessary to implement the

No ti fi cati o nLi stener interface and override the hand l eNo ti fi cati o n() method,

as shown in Example 49.4, “ JMXConsumer Implementation” .

Examp le 4 9 .4 . JMXCo n su mer Imp lemen t at io n

package org.apache.camel.component.jmx; import javax.management.Notification; import javax.management.NotificationListener; import org.apache.camel.Processor; import org.apache.camel.impl.DefaultConsumer; public class JMXConsumer extends DefaultConsumer implements

NotificationListener {

JMXEndpoint jmxEndpoint;

public JMXConsumer(JMXEndpoint endpoint, Processor processor) {

super(endpoint, processor);

this.jmxEndpoint = endpoint;

}

public void handleNotification(Notification notification,

Object handback) {

try {

getProcessor().process(jmxEndpoint.createExchange(notification));

} catch (Throwable e) {

handleException(e);

}

616

CHAPT ER 4 9 . CO NSUMER INT ERFACE

The JMXC o nsumer pattern follows the usual pattern for event-driven consumers by extending the D efaul tC o nsumer class. Additionally, because this consumer is designed to receive events from JMX (which are represented by JMX notifications), it is necessary to implement the No ti fi cati o nLi stener interface.

You must implement at least one constructor that takes a reference to the parent endpoint, end po i nt, and a reference to the next processor in the chain,

pro cesso r, as arguments.

The hand l eNo ti fi cati o n() method (which is defined in

No ti fi cati o nLi stener) is automatically invoked by JMX whenever a JMX notification arrives. The body of this method should contain the code that performs the consumer's event processing. Because the hand l eNo ti fi cati o n() call originates from the JMX layer, the consumer's threading model is implicitly controlled by the JMX layer, not by the JMXC o nsumer class.

No t e

The hand l eNo ti fi cati o n() method is specific to the JMX example.

When implementing your own event-driven consumer, you must identify an analogous event listener method to implement in your custom consumer.

This line of code combines two steps. First, the JMX notification object is converted into an exchange object, which is the generic representation of an event in Apache

Camel. Then the newly created exchange object is passed to the next processor in the route (invoked synchronously).

The hand l eExcepti o n() method is implemented by the D efaul tC o nsumer base class. By default, it handles exceptions using the

o rg . apache. camel . i mpl . Lo g g i ng Excepti o nHand l er class.

Scheduled poll consumer implement at ion

In a scheduled poll consumer, polling events are automatically generated by a timer class,

java. uti l . co ncurrent. Sched ul ed Executo rServi ce. To receive the generated polling events, you must implement the Sched ul ed P o l l C o nsumer. po l l () method (see

Section 46.1.3, “ Consumer Patterns and Threading”

617

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Example 49.5, “ ScheduledPollConsumer Implementation”

shows how to implement a consumer that follows the scheduled poll pattern, which is implemented by extending the

Sched ul ed P o l l C o nsumer class.

Examp le 4 9 .5. Sch ed u led Po llCo n su mer Imp lemen t at io n

import java.util.concurrent.ScheduledExecutorService; import org.apache.camel.Consumer; import org.apache.camel.Endpoint; import org.apache.camel.Exchange; import org.apache.camel.Message; import org.apache.camel.PollingConsumer; import org.apache.camel.Processor; import org.apache.camel.impl.ScheduledPollConsumer; public class CustomConsumer extends ScheduledPollConsumer {

private final CustomEndpoint endpoint;

public CustomConsumer(CustomEndpoint endpoint, Processor processor) {

super(endpoint, processor);

this.endpoint = endpoint;

}

protected void poll() throws Exception {

Exchange exchange = /* Receive exchange object ... */;

// Example of a synchronous processor.

getProcessor().process(exchange);

}

@ Override

protected void doStart() throws Exception {

// Pre-Start:

// Place code here to execute just before start of processing.

super.doStart();

// Post-Start:

// Place code here to execute just after start of processing.

}

@ Override

protected void doStop() throws Exception {

// Pre-Stop:

// Place code here to execute just before processing stops.

super.doStop();

// Post-Stop:

// Place code here to execute just after processing stops.

}

618

CHAPT ER 4 9 . CO NSUMER INT ERFACE

Implement a scheduled poll consumer class, CustomConsumer, by extending the

o rg . apache. camel . i mpl . Sched ul ed P o l l C o nsumer class.

You must implement at least one constructor that takes a reference to the parent endpoint, end po i nt, and a reference to the next processor in the chain,

pro cesso r, as arguments.

Override the po l l () method to receive the scheduled polling events. This is where you should put the code that retrieves and processes incoming events (represented by exchange objects).

In this example, the event is processed synchronously. If you want to process events asynchronously, you should use a reference to an asynchronous processor instead, by calling g etAsyncP ro cesso r(). For details of how to process events asynchronously, see

Section 46.1.4, “ Asynchronous Processing”

(Optional) If you want some lines of code to execute as the consumer is starting up, override the d o Start() method as shown.

(Optional) If you want some lines of code to execute as the consumer is stopping, override the d o Sto p() method as shown.

Polling consumer implement at ion

Example 49.6, “ PollingConsumerSupport Implementation” outlines how to implement a

consumer that follows the polling pattern, which is implemented by extending the

P o l l i ng C o nsumerSuppo rt class.

Examp le 4 9 .6 . Po llin g Co n su merSu p p o rt Imp lemen t at io n

import org.apache.camel.Exchange;

619

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

import org.apache.camel.RuntimeCamelException; import org.apache.camel.impl.PollingConsumerSupport; public class CustomConsumer extends PollingConsumerSupport {

private final CustomEndpoint endpoint;

public CustomConsumer(CustomEndpoint endpoint) {

super(endpoint);

this.endpoint = endpoint;

}

public Exchange receiveNoWait() {

Exchange exchange = /* Obtain an exchange object. */;

// Further processing ...

return exchange;

}

public Exchange receive() {

// Blocking poll ...

}

public Exchange receive(long timeout) {

// Poll with timeout ...

}

protected void doStart() throws Exception {

// Code to execute whilst starting up.

}

protected void doStop() throws Exception {

// Code to execute whilst shutting down.

}

Implement your polling consumer class, CustomConsumer, by extending the

o rg . apache. camel . i mpl . P o l l i ng C o nsumerSuppo rt class.

You must implement at least one constructor that takes a reference to the parent endpoint, end po i nt, as an argument. A polling consumer does not need a reference to a processor instance.

620

The recei veNo Wai t() method should implement a non-blocking algorithm for retrieving an event (exchange object). If no event is available, it should return nul l .

CHAPT ER 4 9 . CO NSUMER INT ERFACE

retrieving an event (exchange object). If no event is available, it should return nul l .

The recei ve() method should implement a blocking algorithm for retrieving an event. This method can block indefinitely, if events remain unavailable.

The recei ve(l o ng ti meo ut) method implements an algorithm that can block for as long as the specified timeout (typically specified in units of milliseconds).

If you want to insert code that executes while a consumer is starting up or shutting down, implement the d o Start() method and the d o Sto p() method, respectively.

Cust om t hreading implement at ion

If the standard consumer patterns are not suitable for your consumer implementation, you can implement the C o nsumer interface directly and write the threading code yourself. When writing the threading code, however, it is important that you comply with the standard

Apache Camel threading model, as described in

Section 2.8, “ Threading Model” .

For example, the SEDA component from camel -co re implements its own consumer

threading, which is consistent with the Apache Camel threading model. Example 49.7,

“ Custom Threading Implementation” shows an outline of how the Sed aC o nsumer class

implements its threading.

Examp le 4 9 .7. Cu st o m T h read in g Imp lemen t at io n

package org.apache.camel.component.seda; import java.util.ArrayList; import java.util.List; import java.util.concurrent.BlockingQueue; import java.util.concurrent.ExecutorService; import java.util.concurrent.TimeUnit; import org.apache.camel.Consumer; import org.apache.camel.Endpoint; import org.apache.camel.Exchange; import org.apache.camel.Processor; import org.apache.camel.ShutdownRunningTask; import org.apache.camel.impl.LoggingExceptionHandler; import org.apache.camel.impl.ServiceSupport; import org.apache.camel.util.ServiceHelper;

...

import org.apache.commons.logging.Log;

621

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

import org.apache.commons.logging.LogFactory;

/**

* A Consumer for the SEDA component.

* @ version $Revision: 922485 $

*/ public class SedaConsumer extends ServiceSupport implements

Consumer, Runnable, ShutdownAware {

private static final transient Log LOG =

LogFactory.getLog(SedaConsumer.class);

private SedaEndpoint endpoint;

private Processor processor;

private ExecutorService executor;

...

public SedaConsumer(SedaEndpoint endpoint, Processor processor)

{

this.endpoint = endpoint;

this.processor = processor;

}

...

public void run() {

BlockingQueue<Exchange> queue = endpoint.getQueue();

// Poll the queue and process exchanges

...

}

...

protected void doStart() throws Exception {

int poolSize = endpoint.getConcurrentConsumers();

executor = endpoint.getCamelContext().getExecutorServiceStrategy()

.newFixedThreadPool(this, endpoint.getEndpointUri(), poolSize);

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

executor.execute(this);

}

endpoint.onStarted(this);

}

protected void doStop() throws Exception {

endpoint.onStopped(this);

// must shutdown executor on stop to avoid overhead of having them running endpoint.getCamelContext().getExecutorServiceStrategy().shutdownNow

(executor);

executor = null;

if (multicast != null) {

ServiceHelper.stopServices(multicast);

}

622

CHAPT ER 4 9 . CO NSUMER INT ERFACE

}

...

//----------

// Implementation of ShutdownAware interface

public boolean deferShutdown(ShutdownRunningTask shutdownRunningTask) {

// deny stopping on shutdown as we want seda consumers to run in case some other queues

// depend on this consumer to run, so it can complete its exchanges

return true;

}

public int getPendingExchangesSize() {

// number of pending messages on the queue

return endpoint.getQueue().size();

}

The Sed aC o nsumer class is implemented by extending the

o rg . apache. camel . i mpl . Servi ceSuppo rt class and implementing the

C o nsumer, R unnabl e, and Shutd o wnAware interfaces.

Implement the R unnabl e. run() method to define what the consumer does while it is running in a thread. In this case, the consumer runs in a loop, polling the queue for new exchanges and then processing the exchanges in the latter part of the queue.

The d o Start() method is inherited from Servi ceSuppo rt. You override this method in order to define what the consumer does when it starts up.

Instead of creating threads directly, you should create a thread pool using the

Executo rServi ceStrateg y object that is registered with the C amel C o ntext. This is important, because it enables Apache Camel to implement centralized management of threads and support such features as graceful shutdown.

For details, see

Section 2.8, “ Threading Model” .

623

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Kick off the threads by calling the Executo rServi ce. execute() method

po o l Si ze times.

The d o Sto p() method is inherited from Servi ceSuppo rt. You override this method in order to define what the consumer does when it shuts down.

Shut down the thread pool, which is represented by the executo r instance.

624

CHAPT ER 50 . PRO DUCER INT ERFACE

CHAPTER 50. PRODUCER INTERFACE

Ab st ract

This chapter describes how to implement the P ro d ucer interface, which is an essential step in the implementation of a Apache Camel component.

50.1. T HE PRODUCER INT ERFACE

Overview

An instance of o rg . apache. camel . P ro d ucer type represents a target endpoint in a route. The role of the producer is to send requests (In messages) to a specific physical endpoint and to receive the corresponding response (Out or Fault message). A P ro d ucer object is essentially a special kind of P ro cesso r that appears at the end of a processor chain (equivalent to a route).

Figure 50.1, “ Producer Inheritance Hierarchy” shows the

inheritance hierarchy for producers.

Fig u re 50.1. Pro d u cer In h erit an ce Hierarch y

T he Producer int erface

Example 50.1, “ Producer Interface”

shows the definition of the

o rg . apache. camel . P ro d ucer interface.

Examp le 50.1. Pro d u cer In t erf ace

package org.apache.camel; public interface Producer extends Processor, Service, IsSingleton {

Endpoint<E> getEndpoint();

Exchange createExchange();

625

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Exchange createExchange(ExchangePattern pattern);

Exchange createExchange(E exchange);

}

Producer met hods

The P ro d ucer interface defines the following methods:

pro cess() (inherited from Processor)—The most important method. A producer is essentially a special type of processor that sends a request to an endpoint, instead of forwarding the exchange object to another processor. By overriding the pro cess() method, you define how the producer sends and receives messages to and from the relevant endpoint.

g etEnd po i nt()—Returns a reference to the parent endpoint instance.

createExchang e()—These overloaded methods are analogous to the corresponding methods defined in the End po i nt interface. Normally, these methods delegate to the corresponding methods defined on the parent End po i nt instance (this is what the

D efaul tEnd po i nt class does by default). Occasionally, you might need to override these methods.

Asynchronous processing

Processing an exchange object in a producer—which usually involves sending a message to a remote destination and waiting for a reply—can potentially block for a significant length of time. If you want to avoid blocking the current thread, you can opt to implement the producer as an asynchronous processor. The asynchronous processing pattern decouples the preceding processor from the producer, so that the pro cess() method returns without

delay. See Section 46.1.4, “ Asynchronous Processing”

When implementing a producer, you can support the asynchronous processing model by implementing the o rg . apache. camel . AsyncP ro cesso r interface. On its own, this is not enough to ensure that the asynchronous processing model will be used: it is also necessary for the preceding processor in the chain to call the asynchronous version of the pro cess()

method. The definition of the AsyncP ro cesso r interface is shown in Example 50.2,

“ AsyncProcessor Interface” .

Examp le 50.2. Asyn cPro cesso r In t erf ace

package org.apache.camel; public interface AsyncProcessor extends Processor {

boolean process(Exchange exchange, AsyncCallback callback);

}

626

CHAPT ER 50 . PRO DUCER INT ERFACE

The asynchronous version of the pro cess() method takes an extra argument, cal l back, of o rg . apache. camel . AsyncC al l back type. The corresponding AsyncC al l back interface is defined as shown in

Example 50.3, “ AsyncCallback Interface”

Examp le 50.3. Asyn cCallb ack In t erf ace

package org.apache.camel; public interface AsyncCallback {

void done(boolean doneSynchronously);

}

The caller of AsyncP ro cesso r. pro cess() must provide an implementation of

AsyncC al l back to receive the notification that processing has finished. The

AsyncC al l back. d o ne() method takes a boolean argument that indicates whether the processing was performed synchronously or not. Normally, the flag would be fal se, to indicate asynchronous processing. In some cases, however, it can make sense for the producer not to process asynchronously (in spite of being asked to do so). For example, if the producer knows that the processing of the exchange will complete rapidly, it could optimise the processing by doing it synchronously. In this case, the d o neSynchro no usl y flag should be set to true.

ExchangeHelper class

When implementing a producer, you might find it helpful to call some of the methods in the

o rg . apache. camel . uti l . Exchang eHel per utility class. For full details of the

Exchang eHel per class, see

Section 43.4, “ The ExchangeHelper Class”

50.2. IMPLEMENT ING T HE PRODUCER INT ERFACE

Alt ernat ive ways of implement ing a producer

You can implement a producer in one of the following ways:

How to implement a synchronous producer

How to implement an asynchronous producer .

How t o implement a synchronous producer

Example 50.4, “ DefaultProducer Implementation” outlines how to implement a synchronous

producer. In this case, call to P ro d ucer. pro cess() blocks until a reply is received.

Examp le 50.4 . Def au lt Pro d u cer Imp lemen t at io n

627

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

import org.apache.camel.Endpoint; import org.apache.camel.Exchange; import org.apache.camel.Producer; import org.apache.camel.impl.DefaultProducer; public class CustomProducer extends DefaultProducer {

public CustomProducer(Endpoint endpoint) {

super(endpoint);

// Perform other initialization tasks...

}

public void process(Exchange exchange) throws Exception {

// Process exchange synchronously.

// ...

}

Implement a custom synchronous producer class, CustomProducer, by extending the

o rg . apache. camel . i mpl . D efaul tP ro d ucer class.

Implement a constructor that takes a reference to the parent endpoint.

The pro cess() method implementation represents the core of the producer code.

The implementation of the pro cess() method is entirely dependent on the type of component that you are implementing. In outline, the pro cess() method is normally implemented as follows:

If the exchange contains an In message, and if this is consistent with the specified exchange pattern, then send the In message to the designated endpoint.

If the exchange pattern anticipates the receipt of an Out message, then wait until the Out message has been received. This typically causes the pro cess() method to block for a significant length of time.

When a reply is received, call exchang e. setO ut() to attach the reply to the exchange object. If the reply contains a fault message, set the fault flag on the Out message using Messag e. setFaul t(true).

How t o implement an asynchronous producer

628

CHAPT ER 50 . PRO DUCER INT ERFACE

Example 50.5, “ CollectionProducer Implementation” outlines how to implement an

asynchronous producer. In this case, you must implement both a synchronous pro cess() method and an asynchronous pro cess() method (which takes an additional

AsyncC al l back argument).

Examp le 50.5. Co llect io n Pro d u cer Imp lemen t at io n

import org.apache.camel.AsyncCallback; import org.apache.camel.AsyncProcessor; import org.apache.camel.Endpoint; import org.apache.camel.Exchange; import org.apache.camel.Producer; import org.apache.camel.impl.DefaultProducer; public class CustomProducer extends DefaultProducer implements

AsyncProcessor {

public CustomProducer(Endpoint endpoint) {

super(endpoint);

// ...

}

public void process(Exchange exchange) throws Exception {

// Process exchange synchronously.

// ...

}

public boolean process(Exchange exchange, AsyncCallback callback) {

// Process exchange asynchronously.

CustomProducerTask task = new CustomProducerTask(exchange, callback);

// Process 'task' in a separate thread...

// ...

return false;

}

public class CustomProducerTask implements Runnable {

private Exchange exchange;

private AsyncCallback callback;

public CustomProducerTask(Exchange exchange, AsyncCallback callback) {

this.exchange = exchange;

this.callback = callback;

}

public void run() {

// Process exchange.

629

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

// ...

callback.done(false);

}

630

Implement a custom asynchronous producer class, CustomProducer, by extending the o rg . apache. camel . i mpl . D efaul tP ro d ucer class, and implementing the

AsyncP ro cesso r interface.

Implement a constructor that takes a reference to the parent endpoint.

Implement the synchronous pro cess() method.

Implement the asynchronous pro cess() method. You can implement the asynchronous method in several ways. The approach shown here is to create a

java. l ang . R unnabl e instance, task, that represents the code that runs in a subthread. You then use the Java threading API to run the task in a sub-thread (for example, by creating a new thread or by allocating the task to an existing thread pool).

Normally, you return fal se from the asynchronous pro cess() method, to indicate that the exchange was processed asynchronously.

The CustomProducerT ask class encapsulates the processing code that runs in a sub-thread. This class must store a copy of the Exchang e object, exchang e, and the AsyncC al l back object, cal l back, as private member variables.

The run() method contains the code that sends the In message to the producer endpoint and waits to receive the reply, if any. After receiving the reply (Out message or Fault message) and inserting it into the exchange object, you must call

cal l back. d o ne() to notify the caller that processing is complete.

CHAPT ER 51 . EXCHANG E INT ERFACE

CHAPTER 51. EXCHANGE INTERFACE

Ab st ract

This chapter describes the Exchang e interface. Since the refactoring of the camel-core module performed in Apache Camel 2.0, there is no longer any necessity to define custom exchange types. The D efaul tExchang e implementation can now be used in all cases.

51.1. T HE EXCHANGE INT ERFACE

Overview

An instance of o rg . apache. camel . Exchang e type encapsulates the current message passing through a route, with additional metadata encoded as exchange properties.

Figure 51.1, “ Exchange Inheritance Hierarchy” shows the inheritance hierarchy for the

exchange type. The default implementation, D efaul tExchang e, is always used.

Fig u re 51.1. Exch an g e In h erit an ce Hierarch y

T he Exchange int erface

Example 51.1, “ Exchange Interface” shows the definition of the

o rg . apache. camel . Exchang e interface.

Examp le 51.1. Exch an g e In t erf ace

package org.apache.camel; import java.util.Map; import org.apache.camel.spi.Synchronization; import org.apache.camel.spi.UnitOfWork; public interface Exchange {

631

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

// Exchange property names (string constants)

// (Not shown here)

...

ExchangePattern getPattern(); void setPattern(ExchangePattern pattern);

Object getProperty(String name);

Object getProperty(String name, Object defaultValue);

<T> T getProperty(String name, Class<T> type);

<T> T getProperty(String name, Object defaultValue, Class<T> type); void setProperty(String name, Object value);

Object removeProperty(String name);

Map<String, Object> getProperties(); boolean hasProperties();

Message getIn();

<T> T getIn(Class<T> type); void setIn(Message in);

Message getOut();

<T> T getOut(Class<T> type); void setOut(Message out); boolean hasOut();

Throwable getException();

<T> T getException(Class<T> type); void setException(Throwable e); boolean isFailed(); boolean isTransacted(); boolean isRollbackOnly();

CamelContext getContext();

Exchange copy();

Endpoint getFromEndpoint(); void setFromEndpoint(Endpoint fromEndpoint);

String getFromRouteId(); void setFromRouteId(String fromRouteId);

UnitOfWork getUnitOfWork(); void setUnitOfWork(UnitOfWork unitOfWork);

String getExchangeId(); void setExchangeId(String id); void addOnCompletion(Synchronization onCompletion); void handoverCompletions(Exchange target);

}

632

CHAPT ER 51 . EXCHANG E INT ERFACE

Exchange met hods

The Exchang e interface defines the following methods:

g etP attern(), setP attern()—The exchange pattern can be one of the values enumerated in o rg . apache. camel . Exchang eP attern. The following exchange pattern values are supported:

InO nl y

R o bustInO nl y

InO ut

InO pti o nal O ut

O utO nl y

R o bustO utO nl y

O utIn

O utO pti o nal In

setP ro perty(), g etP ro perty(), g etP ro perti es(), remo veP ro perty(),

hasP ro perti es()—Use the property setter and getter methods to associate named properties with the exchange instance. The properties consist of miscellaneous metadata that you might need for your component implementation.

setIn(), g etIn()—Setter and getter methods for the In message.

The g etIn() implementation provided by the D efaul tExchang e class implements lazy creation semantics: if the In message is null when g etIn() is called, the

D efaul tExchang e class creates a default In message.

setO ut(), g etO ut(), hasO ut()—Setter and getter methods for the Out message.

The g etO ut() method implicitly supports lazy creation of an Out message. That is, if the current Out message is nul l , a new message instance is automatically created.

setExcepti o n(), g etExcepti o n()—Getter and setter methods for an exception object (of T hro wabl e type).

i sFai l ed ()—Returns true, if the exchange failed either due to an exception or due to a fault.

633

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

i sT ransacted ()—Returns true, if the exchange is transacted.

i sR o l l back()—Returns true, if the exchange is marked for rollback.

g etC o ntext()—Returns a reference to the associated C amel C o ntext instance.

co py()—Creates a new, identical (apart from the exchange ID) copy of the current custom exchange object. The body and headers of the In message, the Out message (if any), and the Fault message (if any) are also copied by this operation.

setFro mEnd po i nt(), g etFro mEnd po i nt()—Getter and setter methods for the consumer endpoint that orginated this message (which is typically the endpoint appearing in the fro m() DSL command at the start of a route).

setFro mR o uteId (), g etFro mR o uteId ()—Getters and setters for the route ID that originated this exchange. The g etFro mR o uteId () method should only be called internally.

setUni tO fWo rk(), g etUni tO fWo rk()—Getter and setter methods for the

o rg . apache. camel . spi . Uni tO fWo rk bean property. This property is only required for exchanges that can participate in a transaction.

setExchang eId (), g etExchang eId ()—Getter and setter methods for the exchange

ID. Whether or not a custom component uses and exchange ID is an implementation detail.

ad d O nC o mpl eti o n()—Adds an o rg . apache. camel . spi . Synchro ni zati o n callback object, which gets called when processing of the exchange has completed.

hand o verC o mpl eti o ns()—Hands over all of the OnCompletion callback objects to the specified exchange object.

634

CHAPT ER 52 . MESSAG E INT ERFACE

CHAPTER 52. MESSAGE INTERFACE

Ab st ract

This chapter describes how to implement the Messag e interface, which is an optional step in the implementation of a Apache Camel component.

52.1. T HE MESSAGE INT ERFACE

Overview

An instance of o rg . apache. camel . Messag e type can represent any kind of message (In

or Out). Figure 52.1, “ Message Inheritance Hierarchy”

shows the inheritance hierarchy for the message type. You do not always need to implement a custom message type for a component. In many cases, the default implementation, D efaul tMessag e, is adequate.

Fig u re 52.1. Messag e In h erit an ce Hierarch y

T he Message int erface

Example 52.1, “ Message Interface” shows the definition of the

o rg . apache. camel . Messag e interface.

Examp le 52.1. Messag e In t erf ace

package org.apache.camel; import java.util.Map; import java.util.Set; import javax.activation.DataHandler; public interface Message {

String getMessageId();

void setMessageId(String messageId);

635

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Exchange getExchange();

boolean isFault();

void setFault(boolean fault);

Object getHeader(String name);

Object getHeader(String name, Object defaultValue);

<T> T getHeader(String name, Class<T> type);

<T> T getHeader(String name, Object defaultValue, Class<T> type);

Map<String, Object> getHeaders();

void setHeader(String name, Object value);

void setHeaders(Map<String, Object> headers);

Object removeHeader(String name);

boolean removeHeaders(String pattern);

boolean hasHeaders();

Object getBody();

Object getMandatoryBody() throws InvalidPayloadException;

<T> T getBody(Class<T> type);

<T> T getMandatoryBody(Class<T> type) throws

InvalidPayloadException;

void setBody(Object body);

<T> void setBody(Object body, Class<T> type);

DataHandler getAttachment(String id);

Map<String, DataHandler> getAttachments();

Set<String> getAttachmentNames();

void removeAttachment(String id);

void addAttachment(String id, DataHandler content);

void setAttachments(Map<String, DataHandler> attachments);

boolean hasAttachments();

Message copy();

void copyFrom(Message message);

String createExchangeId();

}

Message met hods

The Messag e interface defines the following methods:

setMessag eId (), g etMessag eId ()—Getter and setter methods for the message ID.

Whether or not you need to use a message ID in your custom component is an implementation detail.

g etExchang e()—Returns a reference to the parent exchange object.

636

CHAPT ER 52 . MESSAG E INT ERFACE

i sFaul t(), setFaul t()—Getter and setter methods for the fault flag, which indicates whether or not this message is a fault message.

g etHead er(), g etHead ers(), setHead er(), setHead ers(), remo veHead er(),

hasHead ers()—Getter and setter methods for the message headers. In general, these message headers can be used either to store actual header data, or to store miscellaneous metadata.

g etBo d y(), g etMand ato ryBo d y(), setBo d y()—Getter and setter methods for the message body. The getMandatoryBody() accessor guarantees that the returned body is non-null, otherwise the Inval i d P ayl o ad Excepti o n exception is thrown.

g etAttachment(), g etAttachments(), g etAttachmentNames(),

remo veAttachment(), ad d Attachment(), setAttachments(),

hasAttachments()—Methods to get, set, add, and remove attachments.

co py()—Creates a new, identical (including the message ID) copy of the current custom message object.

co pyFro m()—Copies the complete contents (including the message ID) of the specified generic message object, messag e, into the current message instance. Because this method must be able to copy from any message type, it copies the generic message properties, but not the custom properties.

createExchang eId ()—Returns the unique ID for this exchange, if the message implementation is capable of providing an ID; otherwise, return nul l .

52.2. IMPLEMENT ING T HE MESSAGE INT ERFACE

How t o implement a cust om message

Example 52.2, “ Custom Message Implementation”

outlines how to implement a message by extending the D efaul tMessag e class.

Examp le 52.2. Cu st o m Messag e Imp lemen t at io n

import org.apache.camel.Exchange; import org.apache.camel.impl.DefaultMessage; public class CustomMessage extends DefaultMessage {

public CustomMessage() {

// Create message with default properties...

}

@ Override

public String toString() {

// Return a stringified message...

637

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

}

@ Override

public CustomMessage newInstance() {

return new CustomMessage( ... );

}

@ Override

protected Object createBody() {

// Return message body (lazy creation).

}

@ Override

protected void populateInitialHeaders(Map<String, Object> map)

{

// Initialize headers from underlying message (lazy creation).

}

@ Override

protected void populateInitialAttachments(Map<String,

DataHandler> map) {

// Initialize attachments from underlying message (lazy creation).

}

Implements a custom message class, CustomMessage, by extending the

o rg . apache. camel . i mpl . D efaul tMessag e class.

Typically, you need a default constructor that creates a message with default properties.

Override the to Stri ng () method to customize message stringification.

The newInstance() method is called from inside the Messag eSuppo rt. co py() method. Customization of the newInstance() method should focus on copying all of the custom properties of the current message instance into the new message instance. The Messag eSuppo rt. co py() method copies the generic message properties by calling co pyFro m().

638

CHAPT ER 52 . MESSAG E INT ERFACE

The createBo d y() method works in conjunction with the

Messag eSuppo rt. g etBo d y() method to implement lazy access to the message body. By default, the message body is nul l . It is only when the application code tries to access the body (by calling g etBo d y()), that the body should be created.

The Messag eSuppo rt. g etBo d y() automatically calls createBo d y(), when the message body is accessed for the first time.

The po pul ateIni ti al Head ers() method works in conjunction with the header getter and setter methods to implement lazy access to the message headers. This method parses the message to extract any message headers and inserts them into the hash map, map. The po pul ateIni ti al Head ers() method is automatically called when a user attempts to access a header (or headers) for the first time (by calling g etHead er(), g etHead ers(), setHead er(), or setHead ers()).

The po pul ateIni ti al Attachments() method works in conjunction with the attachment getter and setter methods to implement lazy access to the attachments.

This method extracts the message attachments and inserts them into the hash map,

map. The po pul ateIni ti al Attachments() method is automatically called when a user attempts to access an attachment (or attachments) for the first time by calling

g etAttachment(), g etAttachments(), g etAttachmentNames(), or

ad d Attachment().

639

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

PART V. THE API COMPONENT FRAMEWORK

Ab st ract

How to create a Camel component that wraps any Java API, using the API Component

Framework.

64 0

CHAPT ER 53. INT RO DUCT IO N T O T HE API CO MPO NENT FRAMEWO RK

CHAPTER 53. INTRODUCTION TO THE API COMPONENT

FRAMEWORK

Ab st ract

The API component framework helps you with the challenge of implementing complex Camel components based on a large Java API.

53.1. WHAT IS T HE API COMPONENT FRAMEWORK?

Mot ivat ion

For components with a small number of options, the standard approach to implementing components (

Chapter 46, Implementing a Component

) is quite effective. Where it starts to become problematic, however, is when you need to implement a component with a large number of options. This problem becomes dramatic when it comes to enterprise-level components, which can require you to wrap an API consisting of hundreds of operations.

Such components require a large effort to create and maintain.

The API component framework was developed precisely to deal with the challenge of implementing such components.

T urning APIs int o component s

Experience of implementing Camel components based on Java APIs has shown that a lot of the work is routine and mechanical. It consists of taking a particular Java method, mapping it to a particular URI syntax, and enabling the user to set the method parameters through URI options. This type of work is an obvious candidate for automation and code generation.

Generic URI format

The first step in automating the implementation of a Java API is to design a standard way of mapping an API method to a URI. For this we need to define a generic URI format, which can be used to wrap any Java API. Hence, the API component framework defines the following syntax for endpoint URIs:

scheme://endpoint-prefix/endpoint?Option1=Value1& ...& OptionN=ValueN

Where scheme is the default URI scheme defined by the component; endpoint-prefix is a short API name, which maps to one of the classes or interfaces from the wrapped Java API;

endpoint maps to a method name; and the URI options map to method argument names.

URI format for a single API class

In the case where an API consists of just a single Java class, the endpoint-prefix part of the URI becomes redundant, and you can specify the URI in the following, shorter format:

64 1

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

scheme://endpoint?Option1=Value1& ...& OptionN=ValueN

No t e

To enable this URI format, it is also necessary for the component implementor to leave the api Name element blank in the configuration of the API component Maven plug-in.

Reflect ion and met adat a

In order to map Java method invocations to a URI syntax, it is obvious that some form of reflection mechanism is needed. But the standard Java reflection API suffers from a notable limitation: it does not preserve method argument names. This is a problem, because we need the method argument names in order to generate meaningful URI option names. The solution is to provide metadata in alternative format: either as Javadoc or in method signature files.

Javadoc

Javadoc is an ideal form of metadata for the API component framework, because it preserves the complete method signature, including method argument names. It is also easy to generate (particularly, using maven-javad o c-pl ug i n) and, in many cases, is already provided in a third-party library.

Met hod signat ure files

If Javadoc is unavailable or unsuitable for some reason, the API component framework also supports an alternative source of metadata: the method signature files. A signature file is a simple text file which consists of a list of Java method signatures. It is relatively easy to create these files manually by copying and pasting from Java code (and lightly editing the resulting files).

What does t he framework consist of?

From the perspective of a component developer, the API component framework consists of a number of different elements, as follows:

A Maven arch et yp e

The camel -archetype-api -co mpo nent Maven archetype is used to generate skeleton code for the component implementation.

A Maven p lu g - in

The camel -api -co mpo nent-maven-pl ug i n Maven plug-in is responsible for generating the code that implements the mapping between the Java API and the endpoint URI syntax.

64 2

CHAPT ER 53. INT RO DUCT IO N T O T HE API CO MPO NENT FRAMEWO RK

Sp ecializ ed b ase classes

To support the programming model of the API component framework, the Apache

Camel core provides a specialized API in the

o rg . apache. camel . uti l . co mpo nent package. Amongst other things, this API provides specialized base classes for the component, endpoint, consumer, and producer classes.

53.2. HOW T O USE T HE FRAMEWORK

Overview

The procedure for implementing a component using the API framework involve a mixture of automated code generation, implementing Java code, and customizing the build, by editing

Maven POM files. FIG gives an overview of this development process.

Fig u re 53.1. Usin g t h e API Co mp o n en t Framewo rk

Java API

The starting point for your API component is always a Java API. Generally speaking, in the context of Camel, this usually means a Java client API, which connects to a remote server endpoint. The first question is, where does the Java API come from? Here are a few possibilities:

64 3

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Implement the Java API yourself (though this typically would involve a lot of work and is generally not the preferred approach).

Use a third-party Java API. For example, the Apache Camel Box component is based on the third-party Box Java SDK library.

Generate the Java API from a language-neutral interface. For example, the Apache Camel

LinkedIn component obtains its Java API by converting a WADL description of its REST services to Java (using the Apache CXF wad l 2java tool).

Javadoc met adat a

You have the option of providing metadata for the Java API in the form of Javadoc (which is needed for generating code in the API component framework). If you use a third-party Java

API from a Maven repository, you will usually find that the Javadoc is already provided in the

Maven artifact. But even in the cases where Javadoc is not provided, you can easily generate it, using the maven-javad o c-pl ug i n Maven plug-in.

No t e

Currently, there is a limitation in the processing of Javadoc metadata, such that generic nesting is not supported. For example, java. uti l . Li st<Stri ng > is supported, but java. uti l . Li st<java. uti l . Li st<Stri ng >> is not. The workaround is to specify the nested generic type as

java. uti l . Li st<java. uti l . Li st> in a signature file.

Signat ure file met adat a

If for some reason it is not convenient to provide Java API metadata in the form of Javadoc, you have the option of providing metadata in the form of signature files. The signature files consist of a list of method signatures (one method signature per line). These files can be created manually and are needed only at build time.

Note the following points about signature files:

You must create one signature file for each proxy class (Java API class).

The method signatures must not include a rai ses clause. All exceptions raised at runtime are wrapped in a R unti meC amel Excepti o n and returned from the endpoint.

Class names that specify the type of an argument must be fully-qualified class names

(except for the java. l ang . * types). There is no mechanism for importing package names.

Currently, there is a limitation in the signature parser, such that generic nesting is not supported. For example, java. uti l . Li st<Stri ng > is supported, whereas

java. uti l . Li st<java. uti l . Li st<Stri ng >> is not. The workaround is to specify the nested generic type as java. uti l . Li st<java. uti l . Li st>.

64 4

CHAPT ER 53. INT RO DUCT IO N T O T HE API CO MPO NENT FRAMEWO RK

The following shows a simple example of the contents of a signature file: public String sayHi(); public String greetMe(String name); public String greetUs(String name1, String name2);

Generat e st art ing code wit h t he Maven archet ype

The easiest way to get started developing an API component is to generate an initial Maven project using the camel -archetype-api -co mpo nent Maven archetype. For details of how to run the archetype, see

Section 54.1, “ Generate Code with the Maven Archetype” .

After you run the Maven archetype, you will find two sub-projects under the generated

ProjectName directory:

ProjectName-api

This project contains the Java API, which forms the basis of the API component.

When you build this project, it packages up the Java API in a Maven bundle and generates the requisite Javadoc as well. If the Java API and Javadoc are already provided by a third-party, however, you do not need this sub-project.

ProjectName-co mpo nent

This project contains the skeleton code for the API component.

Edit component classes

You can edit the skeleton code in ProjectName-co mpo nent to develop your own component implementation. The following generated classes make up the core of the skeleton implementation:

ComponentNameComponent

ComponentNameEndpoint

ComponentNameConsumer

ComponentNameProducer

ComponentNameConfiguration

Cust omiz e POM files

You also need to edit the Maven POM files to customize the build, and to configure the

camel -api -co mpo nent-maven-pl ug i n Maven plug-in.

Configure t he camel-api-component -maven-plugin

64 5

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

The most important aspect of configuring the POM files is the configuration of the camel -

api -co mpo nent-maven-pl ug i n Maven plug-in. This plug-in is responsible for generating the mapping between API methods and endpoint URIs, and by editing the plug-in configuration, you can customize the mapping.

For example, the following camel -api -co mpo nent-maven-pl ug i n plug-in configuration shows a minimal configuration for an API class called Exampl eJavad o cHel l o :

<apis>

<api>

<apiName>hello-javadoc</apiName>

<proxyClass>org.jboss.fuse.example.api.ExampleJavadocHello</proxyClass

</api>

</apis>

</configuration>

In this example, the hel l o -javad o c API name is mapped to the Exampl eJavad o cHel l o class, which means you can invoke methods from this class using URIs of the form,

scheme: //hel l o -javad o c/endpoint. The presence of the fro mJavad o c element indicates that the Exampl eJavad o cHel l o class gets its metadata from Javadoc.

OSGi bundle configurat ion

The sample POM for the component sub-project, ProjectName-co mpo nent/po m. xml , is configured to package the component as an OSGi bundle. The component POM includes a sample configuration of the maven-bund l e-pl ug i n. You should customize the configuration of the maven-bund l e-pl ug i n plug-in, to ensure that Maven generates a properly configured OSGi bundle for your component.

Build t he component

When you build the component with Maven, the camel -api -co mpo nent-maven-pl ug i n plug-in automatically generates the API mapping classes (which define the mapping between the Java API and the endpoint URI syntax), placing them into the

targ et/g enerated -cl asses project subdirectory. When you are dealing with a large and complex Java API, this generated code actually constitutes the bulk of the component source code.

When the Maven build completes, the compiled code and resources are packaged up as an

OSGi bundle and stored in your local Maven repository as a Maven artifact.

64 6

CHAPT ER 54 . G ET T ING ST ART ED WIT H T HE FRAMEWO RK

CHAPTER 54. GETTING STARTED WITH THE

FRAMEWORK

Ab st ract

This chapter explains the basic principles of implementing a Camel component using the API component framework, based on code generated using the camel -archetype-api -

co mpo nent Maven archetype.

54 .1. GENERAT E CODE WIT H T HE MAVEN ARCHET YPE

Maven archet ypes

A Maven archetype is analogous to a code wizard: given a few simple parameters, it generates a complete, working Maven project, populated with sample code. You can then use this project as a template, customizing the implementation to create your own application.

T he API component Maven archet ype

The API component framework provides a Maven archetype, camel -archetype-api -

co mpo nent, that can generate starting point code for your own API component implementation. This is the recommended approach to start creating your own API component.

Prerequisit es

The only prerequisites for running the camel -archetype-api -co mpo nent archetype are that Apache Maven is installed and the Maven setti ng s. xml file is configured to use the standard JBoss Fuse repositories. For more details, see appendix "Red Hat JBoss Fuse

Maven Repositories" in "Installation Guide" .

Invoke t he Maven archet ype

To create an Exampl e component, which uses the exampl e URI scheme, invoke the

camel -archetype-api -co mpo nent archetype to generate a new Maven project, as follows: mvn archetype:generate \

-DarchetypeGroupId=org.apache.camel.archetypes \

-DarchetypeArtifactId=camel-archetype-api-component \

-DarchetypeVersion=2.15.1.redhat-620133 \

-DgroupId=org.jboss.fuse.example \

-DartifactId=camel-api-example \

-Dname=Example \

-Dscheme=example \

-Dversion=1.0-SNAPSHOT \

-DinteractiveMode=false

64 7

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

No t e

The backslash character, \, at the end of each line represents line continuation, which works only on Linux and UNIX platforms. On Windows platforms, remove the backslash and put the arguments all on a single line.

Opt ions

Options are provided to the archetype generation command using the syntax, -

D Name= Value. Most of the options should be set as shown in the preceding mvn

archetype: g enerate command, but a few of the options can be modified, to customize the generated project. The following table shows the options that you can use to customize the generated API component project:

Name g ro upId arti factId name scheme archetypeVersi o n

Descript ion

(Generic Maven option) Sp ecifies the g ro up ID o f the g enerated Maven p ro ject. By d efault, this value also d efines the Java p ackag e name fo r the g enerated classes. Hence, it is a g o o d id ea to cho o se this value to match the Java p ackag e name that yo u want.

(Generic Maven option) Sp ecifies the artifact ID o f the g enerated Maven p ro ject.

The name o f the API co mp o nent. This value is used fo r g enerating class names in the g enerated co d e (hence, it is reco mmend ed that the name sho uld start with a cap ital letter).

The d efault scheme to use in URIs fo r this co mp o nent. Yo u sho uld make sure that this scheme d o es no t co nflict with the scheme o f any existing Camel co mp o nents.

(Generic Maven option) Id eally, this sho uld b e the Ap ache Camel versio n used b y the co ntainer where yo u p lan to d ep lo y the co mp o nent. If necessary, ho wever, yo u can also mo d ify the versio ns o f Maven d ep end encies after yo u have g enerated the p ro ject.

St ruct ure of t he generat ed project

64 8

CHAPT ER 54 . G ET T ING ST ART ED WIT H T HE FRAMEWO RK

Assuming that the code generation step completes successfully, you should see a new directory, camel -api -exampl e, which contains the new Maven project. If you look inside the camel -api -exampl e directory, you will see that it has the following general structure: camel-api-example/

pom.xml

camel-api-example-api/

camel-api-example-component/

At the top level of the project is an aggregate POM, po m. xml , which is configured to build two sub-projects, as follows:

camel- ap i- examp le- ap i

The API sub-project (named as ArtifactId-api ) holds the Java API which you are about to turn into a component. If you are basing the API component on a Java

API that you wrote yourself, you can put the Java API code directly into this project.

The API sub-project can be used for one or more of the following purposes:

To package up the Java API code (if it is not already available as a Maven package).

To generate Javadoc for the Java API (providing the needed metadata for the API component framework).

To generate the Java API code from an API description (for example, from a WADL description of a REST API).

In some cases, however, you might not need to perform any of these tasks. For example, if the API component is based on a third-party API, which already provides the Java API and Javadoc in a Maven package. In such cases, you can delete the

API sub-project.

camel- ap i- examp le- co mp o n en t

The component sub-project (named as ArtifactId-co mpo nent) holds the implementation of the new API component. This includes the component implementation classes and the configuration of the camel -api -co mpo nent-

maven plug-in (which generates the API mapping classes from the Java API).

54 .2. GENERAT ED API SUB-PROJECT

Overview

64 9

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Assuming that you generated a new Maven project as described in Section 54.1, “ Generate

Code with the Maven Archetype” , you can now find a Maven sub-project for packaging the

Java API under the camel -api -exampl e/camel -api -exampl e-api project directory. In this section, we take a closer look at the generated example code and describe how it works.

Sample Java API

The generated example code includes a sample Java API, on which the example API component is based. The sample Java API is relatively simple, consisting of just two Hello

World classes: Exampl eJavad o cHel l o and Exampl eFi l eHel l o .

ExampleJavadocHello class

Example 54.1, “ ExampleJavadocHello class” shows the Exampl eJavad o cHel l o class

from the sample Java API. As the name of the class suggests, this particular class is used to show how you can supply mapping metadata from Javadoc.

Examp le 54 .1. Examp leJavad o cHello class

// Java

package org.jboss.fuse.example.api;

/**

* Sample API used by Example Component whose method signatures are read from Javadoc.

public class ExampleJavadocHello { public String sayHi() { return "Hello!" ;

} public String greetMe(String name) { return "Hello " + name;

} public String greetUs(String name1, String name2) { return "Hello " + name1 + ", " + name2;

}

650

ExampleFileHello class

Example 54.2, “ ExampleFileHello class”

shows the Exampl eFi l eHel l o class from the sample Java API. As the name of the class suggests, this particular class is used to show how you can supply mapping metadata from a signature file.

Examp le 54 .2. Examp leFileHello class

CHAPT ER 54 . G ET T ING ST ART ED WIT H T HE FRAMEWO RK

// Java

package org.jboss.fuse.example.api;

/**

* Sample API used by Example Component whose method signatures are read from File.

public class ExampleFileHello { public String sayHi() { return "Hello!" ;

} public String greetMe(String name) { return "Hello " + name;

} public String greetUs(String name1, String name2) { return "Hello " + name1 + ", " + name2;

}

Generat ing t he Javadoc met adat a for ExampleJavadocHello

Because the metadata for Exampl eJavad o cHel l o is provided as Javadoc, it is necessary to generate Javadoc for the sample Java API and install it into the camel -api -exampl e-

api Maven artifact. The API POM file, camel -api -exampl e-api /po m. xml , configures the maven-javad o c-pl ug i n to perform this step automatically during the Maven build.

54 .3. GENERAT ED COMPONENT SUB-PROJECT

Overview

The Maven sub-project for building the new component is located under the camel -api -

exampl e/camel -api -exampl e-co mpo nent project directory. In this section, we take a closer look at the generated example code and describe how it works.

Providing t he Java API in t he component POM

The Java API must be provided as a dependency in the component POM. For example, the sample Java API is defined as a dependency in the component POM file, camel -api -

exampl e-co mpo nent/po m. xml , as follows:

<?xml version="1.0" encoding="UTF-8"?>

<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">

651

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

...

...

<groupId>org.jboss.fuse.example</groupId>

<artifactId>camel-api-example-api</artifactId>

<version>1.0-SNAPSHOT</version>

</dependency>

...

</dependencies>

...

</project>

Providing t he Javadoc met adat a in t he component POM

If you are using Javadoc metadata for all or part of the Java API, you must provide the

Javadoc as a dependency in the component POM. There are two things to note about this dependency:

The Maven coordinates for the Javadoc are almost the same as for the Java API, except that you must also specify a cl assi fi er element, as follows:

<classifier>javadoc</classifier>

You must declare the Javadoc to have pro vi d ed scope, as follows:

<scope>provided</scope>

652

For example, in the component POM, the Javadoc dependency is defined as follows:

<?xml version="1.0" encoding="UTF-8"?>

<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>org.jboss.fuse.example</groupId>

<artifactId>camel-api-example-api</artifactId>

<version>1.0-SNAPSHOT</version>

<classifier>javadoc</classifier>

<scope>provided</scope>

</dependency>

...

</dependencies>

...

</project>

CHAPT ER 54 . G ET T ING ST ART ED WIT H T HE FRAMEWO RK

Defining t he file met adat a for Example File Hello

The metadata for Exampl eFi l eHel l o is provided in a signature file. In general, this file must be created manually, but it has quite a simple format, which consists of a list of method signatures (one on each line). The example code provides the signature file, fi l e-si g -

api . txt, in the directory, camel -api -exampl e-co mpo nent/si g natures, which has the following contents: public String sayHi(); public String greetMe(String name); public String greetUs(String name1, String name2);

For more details about the signature file format, see the section called “ Signature file metadata” .

Configuring t he API mapping

One of the key features of the API component framework is that it automatically generates the code to perform API mapping. That is, generating stub code that maps endpoint URIs to method invocations on the Java API. The basic inputs to the API mapping are: the Java API, the Javadoc metadata, and/or the signature file metadata.

The component that performs the API mapping is the camel -api -co mpo nent-maven-

pl ug i n Maven plug-in, which is configured in the component POM. The following extract from the component POM shows how the camel -api -co mpo nent-maven-pl ug i n plugin is configured:

<?xml version= "1.0" encoding= "UTF-8" ?>

<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" >

...

<build>

<defaultGoal> install </defaultGoal>

...

<groupId> org.apache.camel

</groupId>

<artifactId> camel-api-component-maven-plugin </artifactId>

<id> generate-test-component-classes </id>

<goals>

<goal> fromApis </goal>

</goals>

<apis>

653

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

<api>

<apiName> hello-file </apiName>

<proxyClass> org.jboss.fuse.example.api.ExampleFileHello

</proxyClass>

<fromSignatureFile> signatures/file-sigapi.txt

</fromSignatureFile>

</api>

<api>

<apiName> hello-javadoc </apiName>

<proxyClass> org.jboss.fuse.example.api.ExampleJavadocHello

</proxyClass

</api>

</apis>

</configuration>

</execution>

</executions>

</plugin>

...

</plugins>

...

</build>

...

</project>

The plug-in is configured by the co nfi g urati o n element, which contains a single api s child element to configure the classes of the Java API. Each API class is configured by an

api element, as follows:

api Name

The API name is a short name for the API class and is used as the endpoint-

prefix part of an endpoint URI.

No t e

If the API consists of just a single Java class, you can leave the api Name element empty, so that the endpoint-prefix becomes redundant, and

you can then specify the endpoint URI using the format shown in the section called “ URI format for a single API class” .

pro xyC l ass

The proxy class element specifies the fully-qualified name of the API class.

fro mJavad o c

654

CHAPT ER 54 . G ET T ING ST ART ED WIT H T HE FRAMEWO RK

If the API class is accompanied by Javadoc metadata, you must indicate this by including the fro mJavad o c element and the Javadoc itself must also be specified in

the Maven file, as a pro vi d ed dependency (see the section called “ Providing the

Javadoc metadata in the component POM” ).

fro mSi g natureFi l e

If the API class is accompanied by signature file metadata, you must indicate this by including the fro mSi g natureFi l e element, where the content of this element specifies the location of the signature file.

No t e

The signature files do not get included in the final package built by Maven, because these files are needed only at build time, not at run time.

Generat ed component implement at ion

The API component consists of the following core classes (which must be implemented for every Camel component), under the camel -api -exampl e-co mpo nent/src/mai n/java directory:

Exampl eC o mpo nent

Represents the component itself. This class acts as a factory for endpoint instances

(for example, instances of Exampl eEnd po i nt).

Exampl eEnd po i nt

Represents an endpoint URI. This class acts as a factory for consumer endpoints (for example, Exampl eC o nsumer) and as a factory for producer endpoints (for example,

Exampl eP ro d ucer).

Exampl eC o nsumer

Represents a concrete instance of a consumer endpoint, which is capable of consuming messages from the location specified in the endpoint URI.

Exampl eP ro d ucer

Represents a concrete instance of a producer endpoint, which is capable of sending messages to the location specified in the endpoint URI.

Exampl eC o nfi g urati o n

Can be used to define endpoint URI options. The URI options defined by this configuration class are not tied to any specific API class. That is, you can combine these URI options with any of the API classes or methods. This can be useful, for example, if you need to declare username and password credentials in order to

655

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

connect to the remote service. The primary purpose of the

Exampl eC o nfi g urati o n class is to provide values for parameters required to instantiate API classes, or classes that implement API interfaces. For example, these could be constructor parameters, or parameter values for a factory method or class.

To implement a URI option, option, in this class, all that you need to do is implement the pair of accessor methods, g etOption and setOption. The component framework automatically parses the endpoint URI and injects the option values at run time.

ExampleComponent class

The generated Exampl eC o mpo nent class is defined as follows:

// Java

package org.jboss.fuse.example; import org.apache.camel.CamelContext; import org.apache.camel.Endpoint; import org.apache.camel.spi.UriEndpoint; import org.apache.camel.util.component.AbstractApiComponent; import org.jboss.fuse.example.internal.ExampleApiCollection; import org.jboss.fuse.example.internal.ExampleApiName;

/**

* Represents the component that manages {@link ExampleEndpoint}.

@ UriEndpoint(scheme = "example" , consumerClass =

ExampleConsumer.class, consumerPrefix = "consumer" ) public class ExampleComponent extends

AbstractApiComponent<ExampleApiName, ExampleConfiguration,

ExampleApiCollection> { public ExampleComponent() { super (ExampleEndpoint.class, ExampleApiName.class,

ExampleApiCollection.getCollection());

} public ExampleComponent(CamelContext context) { super (context, ExampleEndpoint.class, ExampleApiName.class,

ExampleApiCollection.getCollection());

}

@ Override protected ExampleApiName getApiName(String apiNameStr) throws

IllegalArgumentException { return ExampleApiName.fromValue(apiNameStr);

}

@ Override protected Endpoint createEndpoint(String uri, String methodName,

ExampleApiName apiName,

ExampleConfiguration

656

CHAPT ER 54 . G ET T ING ST ART ED WIT H T HE FRAMEWO RK

endpointConfiguration) { return new ExampleEndpoint(uri, this , apiName, methodName, endpointConfiguration);

}

The important method in this class is createEnd po i nt, which creates new endpoint instances. Typically, you do not need to change any of the default code in the component class. If there are any other objects with the same life cycle as this component, however, you might want to make those objects available from the component class (for example, by adding a methods to create those objects or by injecting those objects into the component).

ExampleEndpoint class

The generated Exampl eEnd po i nt class is defined as follows:

// Java

package org.jboss.fuse.example; import java.util.Map; import org.apache.camel.Consumer; import org.apache.camel.Processor; import org.apache.camel.Producer; import org.apache.camel.spi.UriEndpoint; import org.apache.camel.util.component.AbstractApiEndpoint; import org.apache.camel.util.component.ApiMethod; import org.apache.camel.util.component.ApiMethodPropertiesHelper; import org.jboss.fuse.example.api.ExampleFileHello; import org.jboss.fuse.example.api.ExampleJavadocHello; import org.jboss.fuse.example.internal.ExampleApiCollection; import org.jboss.fuse.example.internal.ExampleApiName; import org.jboss.fuse.example.internal.ExampleConstants; import org.jboss.fuse.example.internal.ExamplePropertiesHelper;

/**

* Represents a Example endpoint.

@ UriEndpoint(scheme = "example" , consumerClass =

ExampleConsumer.class, consumerPrefix = "consumer" ) public class ExampleEndpoint extends

AbstractApiEndpoint<ExampleApiName, ExampleConfiguration> {

// TODO create and manage API proxy

private Object apiProxy; public ExampleEndpoint(String uri, ExampleComponent component,

ExampleApiName apiName, String methodName,

ExampleConfiguration endpointConfiguration) { super (uri, component, apiName, methodName,

ExampleApiCollection.getCollection().getHelper(apiName), endpointConfiguration);

657

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

} public Producer createProducer() throws Exception { return new ExampleProducer( this );

} public Consumer createConsumer(Processor processor) throws

Exception {

// make sure inBody is not set for consumers

if (inBody != null ) { throw new IllegalArgumentException( "Option inBody is not supported for consumer endpoint" );

} final ExampleConsumer consumer = new ExampleConsumer( this , processor);

// also set consumer.* properties

configureConsumer(consumer); return consumer;

}

@ Override protected ApiMethodPropertiesHelper<ExampleConfiguration> getPropertiesHelper() { return ExamplePropertiesHelper.getHelper();

} protected String getThreadProfileName() { return ExampleConstants.THREAD_PROFILE_NAME;

}

@ Override protected void afterConfigureProperties() {

// TODO create API proxy, set connection properties, etc.

switch (apiName) { case HELLO_FILE:

apiProxy = new ExampleFileHello(); break ; case HELLO_JAVADOC:

apiProxy = new ExampleJavadocHello(); break ; default : throw new IllegalArgumentException( "Invalid API name

" + apiName);

}

@ Override public Object getApiProxy(ApiMethod method, Map<String, Object> args) { return apiProxy;

}

In the context of the API component framework, one of the key steps performed by the endpoint class is to create an API proxy. The API proxy is an instance from the target Java

658

CHAPT ER 54 . G ET T ING ST ART ED WIT H T HE FRAMEWO RK

API, whose methods are invoked by the endpoint. Because a Java API typically consists of many classes, it is necessary to pick the appropriate API class, based on the end po i nt-

prefi x appearing in the URI (recall that a URI has the general form,

scheme: //endpoint-prefix/endpoint).

ExampleConsumer class

The generated Exampl eC o nsumer class is defined as follows:

// Java package org.jboss.fuse.example; import org.apache.camel.Processor; import org.apache.camel.util.component.AbstractApiConsumer; import org.jboss.fuse.example.internal.ExampleApiName;

/**

* The Example consumer.

*/ public class ExampleConsumer extends

AbstractApiConsumer<ExampleApiName, ExampleConfiguration> {

public ExampleConsumer(ExampleEndpoint endpoint, Processor processor) {

super(endpoint, processor);

}

ExampleProducer class

The generated Exampl eP ro d ucer class is defined as follows:

// Java

package org.jboss.fuse.example; import org.apache.camel.util.component.AbstractApiProducer; import org.jboss.fuse.example.internal.ExampleApiName; import org.jboss.fuse.example.internal.ExamplePropertiesHelper;

/**

* The Example producer.

public class ExampleProducer extends

AbstractApiProducer<ExampleApiName, ExampleConfiguration> { public ExampleProducer(ExampleEndpoint endpoint) { super (endpoint, ExamplePropertiesHelper.getHelper());

}

659

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

ExampleConfigurat ion class

The generated Exampl eC o nfi g urati o n class is defined as follows:

// Java

package org.jboss.fuse.example; import org.apache.camel.spi.UriParams;

/**

* Component configuration for Example component.

@ UriParams public class ExampleConfiguration {

// TODO add component configuration properties

}

To add a URI option, option, to this class, define a field of the appropriate type, and implement a corresponding pair of accessor methods, g etOption and setOption. The component framework automatically parses the endpoint URI and injects the option values at run time.

No t e

This class is used to define general URI options, which can be combined with any

API method. To define URI options tied to a specific API method, configure extra

options in the API component Maven plug-in. See

Section 55.7, “ Extra Options”

for details.

URI format

Recall the general format of an API component URI:

scheme://endpoint-prefix/endpoint?Option1=Value1& ...& OptionN=ValueN

In general, a URI maps to a specific method invocation on the Java API. For example, suppose you want to invoke the API method, Exampl eJavad o cHel l o . g reetMe("Jane

D o e"), the URI would be constructed, as follows:

[ scheme]

The API component scheme, as specified when you generated the code with the

Maven archetype. In this case, the scheme is exampl e.

[ endpoint-prefix]

660

CHAPT ER 54 . G ET T ING ST ART ED WIT H T HE FRAMEWO RK

The API name, which maps to the API class defined by the camel -api -

co mpo nent-maven-pl ug i n Maven plug-in configuration. For the

Exampl eJavad o cHel l o class, the relevant configuration is:

<apis>

<api>

<apiName>hel l o -javad o c</apiName>

<proxyClass>org.jboss.fuse.example.api.ExampleJavadocHello</prox yClass>

</api>

...

</apis>

</configuration>

Which shows that the required endpoint-prefix is hel l o -javad o c.

[ endpoint]

The endpoint maps to the method name, which is g reetMe.

[ Option1= Value1]

The URI options specify method parameters. The g reetMe(Stri ng name) method takes the single parameter, name, which can be specified as name= Jane%20 D o e. If you want to define default values for options, you can do this by overriding the

i nterceptP ro perti es method (see

Section 54.4, “ Programming Model”

Putting together the pieces of the URI, we see that we can invoke

Exampl eJavad o cHel l o . g reetMe("Jane D o e") with the following URI: example://hello-javadoc/greetMe?name=Jane%20Doe

Default component inst ance

In order to map the exampl e URI scheme to the default component instance, the Maven archetype creates the following file under the camel -api -exampl e-co mpo nent subproject: src/main/resources/META-

INF/services/org/apache/camel/component/example

This resource file is what enables the Camel core to identify the component associated with the exampl e URI scheme. Whenever you use an exampl e: // URI in a route, Camel searches the classpath to look for the corresponding exampl e resource file. The exampl e file has the following contents: class=org.jboss.fuse.example.ExampleComponent

661

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

This enables the Camel core to create a default instance of the Exampl eC o mpo nent component. The only time you would need to edit this file is if you refactor the name of the component class.

54 .4 . PROGRAMMING MODEL

Overview

In the context of the API component framework, the main component implementation classes are derived from base classes in the o rg . apache. camel . uti l . co mpo nent package.

These base classes define some methods which you can (optionally) override when you are implementing your component. In this section, we provide a brief description of those methods and how you might use them in your own component implementation.

Component met hods t o implement

In addition to the generated method implementations (which you usually do not need to modify), you can optionally override some of the following methods in the C o mpo nent class:

d o Start()

(Optional) A callback to create resources for the component during a cold start. An alternative approach is to adopt the strategy of lazy initialization (creating resources only when they are needed). In fact, lazy initialization is often the best strategy, so the

d o Start method is often not needed.

d o Sto p()

(Optional) A callback to invoke code while the component is stopping. Stopping a component means that all of its resources are shut down, internal state is deleted, caches are cleared, and so on.

No t e

Camel guarantees that d o Sto p is always called when the current

C amel C o ntext shuts down, even if the corresponding d o Start was never called.

d o Shutd o wn

(Optional) A callback to invoke code while the C amel C o ntext is shutting down.

Whereas a stopped component can be restarted (with the semantics of a cold start), a component that gets shut down is completely finished. Hence, this callback represents the last chance to free up any resources belonging to the component.

What else t o implement in t he Component class?

662

CHAPT ER 54 . G ET T ING ST ART ED WIT H T HE FRAMEWO RK

The C o mpo nent class is the natural place to hold references to objects that have the same

(or similar) life cycle to the component object itself. For example, if a component uses OAuth security, it would be natural to hold references to the required OAuth objects in the

C o mpo nent class and to define methods in the C o mpo nent class for creating the OAuth objects.

Endpoint met hods t o implement

You can modify some of the generated methods and, optionally, override some inherited methods in the End po i nt class, as follows:

afterC o nfi g ureP ro perti es()

The main thing you need to do in this method is to create the appropriate type of proxy class (API class), to match the API name. The API name (which has already been extracted from the endpoint URI) is available either through the inherited

api Name field or through the g etApi Name accessor. Typically, you would do a switch on the api Name field to create the corresponding proxy class. For example:

// Java

private Object apiProxy;

...

@ Override protected void afterConfigureProperties() {

// TODO create API proxy, set connection properties, etc.

switch (apiName) { case HELLO_FILE:

apiProxy = new ExampleFileHello(); break ; case HELLO_JAVADOC:

apiProxy = new ExampleJavadocHello(); break ; default : throw new IllegalArgumentException( "Invalid API name " + apiName);

}

g etApi P ro xy(Api Metho d metho d , Map<Stri ng , O bject> arg s)

Override this method to return the proxy instance that you created in

afterC o nfi g ureP ro perti es. For example:

@ Override public Object getApiProxy(ApiMethod method, Map<String, Object> args) {

return apiProxy;

}

In special cases, you might want to make the choice of proxy dependent on the API method and arguments. The g etApi P ro xy gives you the flexibility to take this approach, if required.

663

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide d o Start()

(Optional) A callback to create resources during a cold start. Has the same semantics as C o mpo nent. d o Start().

d o Sto p()

(Optional) A callback to invoke code while the component is stopping. Has the same semantics as C o mpo nent. d o Sto p().

d o Shutd o wn

(Optional) A callback to invoke code while the component is shutting down. Has the same semantics as C o mpo nent. d o Shutd o wn().

i nterceptP ro pertyNames(Set<Stri ng > pro pertyNames)

(Optional) The API component framework uses the endpoint URI and supplied option values to determine which method to invoke (ambiguity could be due to overloading and aliases). If the component internally adds options or method parameters, however, the framework might need help in order to determine the right method to invoke. In this case, you must override the i nterceptP ro pertyNames method and add the extra (hidden or implicit) options to the pro pertyNames set. When the complete list of method parameters are provided in the pro pertyNames set, the framework will be able to identify the right method to invoke.

No t e

You can override this method at the level of the End po i nt, P ro d ucer or

C o nsumer class. The basic rule is, if an option affects both producer endpoints and consumer endpoints, override the method in the End po i nt class.

i nterceptP ro perti es(Map<Stri ng ,O bject> pro perti es)

(Optional) By overriding this method, you can modify or set the actual values of the options, before the API method is invoked. For example, you could use this method to set default values for some options, if necessary. In practice, it is often necessary to override both the i nterceptP ro pertyNames method and the i nterceptP ro perty method.

No t e

You can override this method at the level of the End po i nt, P ro d ucer or

C o nsumer class. The basic rule is, if an option affects both producer endpoints and consumer endpoints, override the method in the End po i nt class.

664

Consumer met hods t o implement

CHAPT ER 54 . G ET T ING ST ART ED WIT H T HE FRAMEWO RK

You can optionally override some inherited methods in the C o nsumer class, as follows:

i nterceptP ro pertyNames(Set<Stri ng > pro pertyNames)

(Optional) The semantics of this method are similar to

End po i nt. i nterceptP ro pertyNames i nterceptP ro perti es(Map<Stri ng ,O bject> pro perti es)

(Optional) The semantics of this method are similar to

End po i nt. i nterceptP ro perti es d o Invo keMetho d (Map<Stri ng , O bject> arg s)

(Optional) Overriding this method enables you to intercept the invocation of the Java

API method. The most common reason for overriding this method is to customize the error handling around the method invocation. For example, a typical approach to overriding d o Invo keMetho d is shown in the following code fragment:

// Java

@ Override protected Object doInvokeMethod(Map<String, Object> args) { try { return super .doInvokeMethod(args);

} catch (RuntimeCamelException e) {

// TODO - Insert custom error handling here!

...

}

You should invoke d o Invo keMetho d on the super-class, at some point in this implementation, to ensure that the Java API method gets invoked.

i nterceptR esul t(O bject metho d R esul t, Exchang e resul tExchang e)

(Optional) Do some additional processing on the result of the API method invocation.

For example, you could add custom headers to the Camel exchange object,

resul tExchang e, at this point.

O bject spl i tR esul t(O bject resul t)

(Optional) By default, if the result of the method API invocation is a

java. uti l . C o l l ecti o n object or a Java array, the API component framework splits the result into multiple exchange objects (so that a single invocation result is converted into multiple messages).

If you want to change the default behaviour, you can override the spl i tR esul t method in the consumer endpoint. The resul t argument contains the result of the

API message invocation. If you want to split the result, you should return an array type.

665

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

No t e

You can also switch off the default splitting behaviour by setting

co nsumer. spl i tR esul t= fal se on the endpoint URI.

Producer met hods t o implement

You can optionally override some inherited methods in the P ro d ucer class, as follows:

i nterceptP ro pertyNames(Set<Stri ng > pro pertyNames)

(Optional) The semantics of this method are similar to

End po i nt. i nterceptP ro pertyNames i nterceptP ro perti es(Map<Stri ng ,O bject> pro perti es)

(Optional) The semantics of this method are similar to

End po i nt. i nterceptP ro perti es d o Invo keMetho d (Map<Stri ng , O bject> arg s)

(Optional) The semantics of this method are similar to

C o nsumer. d o Invo keMetho d .

i nterceptR esul t(O bject metho d R esul t, Exchang e resul tExchang e)

(Optional) The semantics of this method are similar to

C o nsumer. i nterceptR esul t.

No t e

The P ro d ucer. spl i tR esul t() method is never called, so it is not possible to split an API method result in the same way as you can for a consumer endpoint. To get a similar effect for a producer endpoint, you can use Camel's spl i t() DSL command (one of the standard enterprise integration patterns) to split

C o l l ecti o n or array results.

Consumer polling and t hreading model

The default threading model for consumer endpoints in the API component framework is

scheduled poll consumer. This implies that the API method in a consumer endpoint is invoked

at regular, scheduled time intervals. For more details, see the section called “ Scheduled poll consumer implementation” .

54 .5. SAMPLE COMPONENT IMPLEMENT AT IONS

666

CHAPT ER 54 . G ET T ING ST ART ED WIT H T HE FRAMEWO RK

Overview

Several of the components distributed with Apache Camel have been implemented with the aid of the API component framework. If you want to learn more about the techniques for implementing Camel components using the framework, it is a good idea to study the source code of these component implementations.

Box.com

The Camel Box component shows how to model and invoke the third party Box.com Java

SDK using the API component framework. It also demonstrates how the framework can be adapted to customize consumer polling, in order to support Box.com's long polling API.

The Camel LinkedIn component demonstrates how to wrap a REST API provided in the form of WADL and XML schemas. The implementation of this component exploits the Apache CXF

wad l 2java Maven plug-in to generate a Java API, which can then be wrapped using the

API component framework.

This approach can be easily replicated to create a Camel component for any SaaS product or platform.

GoogleDrive

The Camel GoogleDrive component demonstrates how the API component framework can handle even Method Object style Google APIs. In this case, URI options are mapped to a method object, which is then invoked by overriding the d o Invo ke method in the consumer and the producer.

Olingo2

The Camel Olingo2 component demonstrates how a callback-based Asynchronous API can be wrapped using the API component framework. This example shows how asynchronous processing can be pushed into underlying resources, like HTTP NIO connections, to make

Camel endpoints more resource efficient.

667

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

CHAPTER 55. CONFIGURING THE API COMPONENT

MAVEN PLUG-IN

Ab st ract

This chapter provides a reference for all of the configuration options available on the API component Maven plug-in.

55.1. OVERVIEW OF T HE PLUG-IN CONFIGURAT ION

Overview

The main purpose of the API component Maven plug-in, camel -api -co mpo nent-maven-

pl ug i n, is to generate the API mapping classes, which implement the mapping between endpoint URIs and API method invocations. By editing the configuration of the API component Maven plug-in, you can customize various aspects of the API mapping.

Locat ion of t he generat ed code

The API mapping classes generated by the API component Maven plug-in are placed in the following location, by default:

ProjectName-component/target/generated-sources/camel-component

Prerequisit es

The main inputs to the API component Maven plug-in are the Java API classes and the

Javadoc metadata. These are made available to the plug-in by declaring them as regular

Maven dependencies (where the Javadoc Maven dependencies should be declared with

pro vi d ed scope).

Set t ing up t he plug-in

The recommended way to set up the API component Maven plug-in is to generate starting point code using the API component archetype. This generates the default plug-in configuration in the ProjectName-co mpo nent/po m. xml file, which you can then customize for your project. The main aspects of the plug-in set-up are, as follows:

1. Maven dependencies must be declared for the requisite Java API and for the

Javadoc metadata.

2. The plug-in's base configuration is declared in the pl ug i nManag ement scope

(which also defines the version of the plug-in to use).

3. The plug-in instance itself is declared and configured.

668

CHAPT ER 55. CO NFIG URING T HE API CO MPO NENT MAVEN PLUG - IN

4. The bui l d -hel per-maven plug-in is configured to pick up the generated sources from the targ et/g enerated -so urces/camel -co mpo nent directory and include them in the Maven build.

Example base configurat ion

The following POM file extract shows the base configuration of the API component Maven plug-in, as defined in the Maven pl ug i nManag ement scope when the code has been generated using the API component archetype:

<?xml version= "1.0" encoding= "UTF-8" ?>

...

<build>

...

<groupId> org.apache.camel

</groupId>

<artifactId> camel-api-component-maven-plugin </artifactId>

<version> 2.15.1.redhat-620133 </version>

<scheme> ${schemeName} </scheme>

<componentName> ${componentName} </componentName>

<componentPackage> ${componentPackage} </componentPackage>

<outPackage> ${outPackage} </outPackage>

</configuration>

</plugin>

</plugins>

</pluginManagement>

...

</build>

...

</project

The configuration specified in the pl ug i nManag ement scope provides default settings for the plug-in. It does not actually create an instance of a plug-in, but its default settings will be used by any API component plug-in instance.

Base configurat ion

In addition to specifying the plug-in version (in the versi o n element), the preceding base configuration specifies the following configuration properties:

scheme

The URI scheme for this API component.

co mpo nentName

669

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

The name of this API component (which is also used as a prefix for generated class names).

co mpo nentP ackag e

Specifies the Java package containing the classes generated by the API component

Maven archetype. This package is also exported by the default maven-bund l e-

pl ug i n configuration. Hence, if you want a class to be publicly visible, you should place it in this Java package.

o utP ackag e

Specifies the Java package where the generated API mapping classes are placed

(when they are generated by the API component Maven plug-in). By default, this has the value of the co mpo nentName property, with the addition of the . i nternal suffix. This package is declared as private by the default maven-bund l e-pl ug i n configuration. Hence, if you want a class to be private, you should place it in this

Java package.

Example inst ance configurat ion

The following POM file extract shows a sample instance of the API component Maven plugin, which is configured to generate an API mapping during the Maven build:

<?xml version= "1.0" encoding= "UTF-8" ?>

<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" >

...

<build>

<defaultGoal> install </defaultGoal>

...

<groupId> org.apache.camel

</groupId>

<artifactId> camel-api-component-maven-plugin </artifactId>

<id> generate-test-component-classes </id>

<goals>

<goal> fromApis </goal>

</goals>

<apis>

<api>

<apiName> hello-file </apiName>

<proxyClass> org.jboss.fuse.example.api.ExampleFileHello

</proxyClass>

<fromSignatureFile> signatures/file-sig-

670

CHAPT ER 55. CO NFIG URING T HE API CO MPO NENT MAVEN PLUG - IN

api.txt

</fromSignatureFile>

</api>

<api>

<apiName> hello-javadoc </apiName>

<proxyClass> org.jboss.fuse.example.api.ExampleJavadocHello

</proxyClass

</api>

</apis>

</configuration>

</execution>

</executions>

</plugin>

...

</plugins>

...

</build>

...

</project>

Basic mapping configurat ion

The plug-in is configured by the co nfi g urati o n element, which contains a single api s child element to configure the classes of the Java API. Each API class is configured by an

api element, as follows:

api Name

The API name is a short name for the API class and is used as the endpoint-

prefix part of an endpoint URI.

No t e

If the API consists of just a single Java class, you can leave the api Name element empty, so that the endpoint-prefix becomes redundant, and

you can then specify the endpoint URI using the format shown in the section called “ URI format for a single API class” .

pro xyC l ass

This element specifies the fully-qualified name of the API class.

fro mJavad o c

If the API class is accompanied by Javadoc metadata, you must indicate this by including the fro mJavad o c element and the Javadoc itself must also be specified in the Maven file, as a pro vi d ed dependency.

fro mSi g natureFi l e

671

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

No t e

The signature files do not get included in the final package built by Maven, because these files are needed only at build time, not at run time.

Cust omiz ing t he API mapping

The following aspects of the API mapping can be customized by configuring the plug-in:

Method aliases—you can define additional names (aliases) for an API method using the

al i ases configuration element. For details, see

Section 55.3, “ Method Aliases” .

Nullable options—you can use the nul l abl eO pti o ns configuration element to declare method arguments that default to nul l . For details, see

Section 55.4, “ Nullable Options”

Argument name substitution—due to the way the API mapping is implemented, the arguments from all of the methods in a particular API class belong to the same namespace. If two arguments with the same name are declared to be of different type, this leads to a clash. To avoid such name clashes, you can use the substi tuti o ns configuration element to rename method arguments (as they would appear in a URI). For

details, see Section 55.5, “ Argument Name Substitution” .

Excluding arguments—when it comes to mapping Java arguments to URI options, you might sometimes want to exclude certain arguments from the mapping. You can filter out unwanted arguments by specifying either the excl ud eC o nfi g Names element or the

excl ud eC o nfi g T ypes element. For details, see

Section 55.6, “ Excluded Arguments” .

Extra options—sometimes you might want to define extra options, which are not part of the

Java API. You can do this using the extraO pti o ns configuration element.

Configuring Javadoc met adat a

It is possible to filter the Javadoc metadata to ignore or explicitly include certain content. For

details of how to do this, see Section 55.2, “ Javadoc Options” .

Configuring signat ure file met adat a

In cases where no Javadoc is available, you can resort to signature files to supply the needed mapping metadata. The fro mSi g natureFi l e is used to specify the location of the corresponding signature file. It has no special options.

55.2. JAVADOC OPT IONS

672

CHAPT ER 55. CO NFIG URING T HE API CO MPO NENT MAVEN PLUG - IN

Overview

If the metadata for your Java API is provided by Javadoc, it is generally sufficient to specify the fro mJavad o c element with no options. But in cases where you do not want to include the entire Java API in your API mapping, you can filter the Javadoc metadata to customize the content. In other words, because the API component Maven plug-in generates the API mapping by iterating over the Javadoc metadata, it is possible to customize the scope of the generated API mapping by filtering out unwanted parts of the Javadoc metadata.

Synt ax

The fro mJavad o c element can be configured with optional child elements, as follows:

<excludePackages>PackageNamePattern</excludePackages>

<excludeClasses>ClassNamePattern</excludeClasses>

<excludeMethods>MethodNamePattern</excludeMethods>

<includeMethods>MethodNamePattern</includeMethods>

<includeStaticMethods>[true|false]<includeStaticMethods>

</fromJavadoc>

Scope

As shown in the following extract, the fro mJavad o c element can optionally appear as a child of the api s element and/or as a child of api elements:

<apis>

<api>

...

<fro mJavad o c>. . . </fro mJavad o c>

</api>

<fro mJavad o c>. . . </fro mJavad o c>

...

</apis>

</configuration>

You can define the fro mJavad o c element at the following scopes:

As a child of an api element—the fro mJavad o c options apply only to the API class specified by the api element.

As a child of the apis element—the fro mJavad o c options apply to all API classes by default, but can be overridden at the api level.

Opt ions

The following options can be defined as child elements of fro mJavad o c:

673

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide excl ud eP ackag es

Specifies a regular expression (java. uti l . reg ex syntax) for excluding Java packages from the API mapping model. All package names that match the regular expression are excluded; and all classes derived from the excluded classes are also

ignored. Default value is javax?\. l ang . *.

excl ud eC l asses

Specifies a regular expression (java. uti l . reg ex syntax) for excluding API base classes from the API mapping. All class names that match the regular expression are excluded; and all classes derived from the excluded classes are also ignored.

excl ud eMetho d s

Specifies a regular expression (java. uti l . reg ex syntax) for excluding methods from the API mapping model.

i ncl ud eMetho d s

Specifies a regular expression (java. uti l . reg ex syntax) for including methods from the API mapping model.

i ncl ud eStati cMetho d s

If true, static methods will also be included in the API mapping model. Default is

fal se.

55.3. MET HOD ALIASES

Overview

Often it can be useful to define additional names (aliases) for a given method, in addition to the standard method name that appears in the Java API. A particularly common case is where you allow a property name (such as wi d g et) to be used as an alias for an accessor method (such as g etWi d g et or setWi d g et).

Synt ax

The al i ases element can be defined with one or more al i as child elements, as follows:

<alias>

<methodPattern>MethodPattern</methodPattern>

<methodAlias>Alias</methodAlias>

</alias>

...

</aliases>

674

CHAPT ER 55. CO NFIG URING T HE API CO MPO NENT MAVEN PLUG - IN

Where MethodPattern is a regular expression (java. uti l . reg ex syntax) for matching method names from the Java API, and the pattern typically includes capturing groups. The

Alias is the replacement expression (for use in a URI), which can use the text from the preceding capturing groups (for example, specified as $1, $2, or $3 for the text from the first, second, or third capturing group).

Scope

As shown in the following extract, the al i ases element can optionally appear as a child of the api s element and/or as a child of api elements:

<apis>

<api>

...

<al i ases>. . . </al i ases>

</api>

<al i ases>. . . </al i ases>

...

</apis>

</configuration>

You can define the al i ases element at the following scopes:

As a child of an api element—the al i ases mappings apply only to the API class specified by the api element.

As a child of the apis element—the al i ases mappings apply to all API classes by default, but can be overridden at the api level.

Example

The following example shows how to generate aliases for the common get/set bean method pattern:

<alias>

</alias>

</aliases>

With the preceding alias definition, you could use wi d g et as an alias for either of the methods g etWi d g et or setWi d g et. Note the use of a capturing group, (. + ), to capture the latter part of the method name (for example, Wi d g et).

55.4 . NULLABLE OPT IONS

675

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Overview

In some cases, it can make sense to let method arguments default to nul l . But this is not allowed by default. If you want to allow some of your method arguments from the Java API to take nul l values, you must declare this explicitly using the nul l abl eO pti o ns element.

Synt ax

The nul l abl eO pti o ns element can be defined with one or more nul l abl eO pti o n child elements, as follows:

<nullableOption>ArgumentName</nullableOption>

...

</nullableOptions>

Where ArgumentName is the name of a method argument from the Java API.

Scope

As shown in the following extract, the nul l abl eO pti o ns element can optionally appear as a child of the api s element and/or as a child of api elements:

<apis>

<api>

...

<nul l abl eO pti o ns>. . . </nul l abl eO pti o ns>

</api>

...

<nul l abl eO pti o ns>. . . </nul l abl eO pti o ns>

</apis>

</configuration>

You can define the nul l abl eO pti o ns element at the following scopes:

As a child of an api element—the nul l abl eO pti o ns mappings apply only to the API class specified by the api element.

As a child of the apis element—the nul l abl eO pti o ns mappings apply to all API classes by default, but can be overridden at the api level.

Example

The following example shows the nullable options declared for the C o mpani esR eso urce proxy class from the Apache Camel LinkedIn component:

676

CHAPT ER 55. CO NFIG URING T HE API CO MPO NENT MAVEN PLUG - IN

<nullableOption> companySizes </nullableOption>

<nullableOption> count </nullableOption>

<nullableOption> email_domain </nullableOption>

<nullableOption> end_timestamp </nullableOption>

<nullableOption> event_type </nullableOption>

<nullableOption> industries </nullableOption>

<nullableOption> is_company_admin </nullableOption>

<nullableOption> jobFunc </nullableOption>

<nullableOption> secure_urls </nullableOption>

<nullableOption> seniorities </nullableOption>

<nullableOption> start </nullableOption>

<nullableOption> start_timestamp </nullableOption>

<nullableOption> statistics_update_key </nullableOption>

<nullableOption> time_granularity </nullableOption>

</nullableOptions>

55.5. ARGUMENT NAME SUBST IT UT ION

Overview

The API component framework requires that URI option names are unique within each proxy

class (Java API class). This is not always the case for method argument names, however. For example, consider the following Java methods in an API class: public void doSomething( int id, String name); public void doSomethingElse( int id, String name);

When you build your Maven project, the camel -api -co mpo nent-maven-pl ug i n generates the configuration class, ProxyClassEnd po i ntC o nfi g urati o n, which contains getter and setter methods for all of the arguments in the ProxyClass class. For example, given the preceding methods, the plug-in would generate the following getter and setter methods in the configuration class: public int getId(); public void setId(int id); public String getName(); public void setName(String name);

But what happens, if the i d argument appears multiple times as different types, as in the following example: public void doSomething(i nt id, String name); public void doSomethingElse(i nt id, String name); public String lookupByID(Stri ng id);

677

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

In this case, the code generation would fail, because you cannot define a g etId method that returns i nt and a g etId method that returns Stri ng in the same scope. The solution to this problem is to use argument name substitution to customize the mapping of argument names to URI option names.

Synt ax

The substi tuti o ns element can be defined with one or more substi tuti o n child elements, as follows:

<method>MethodPattern</method>

<argName>ArgumentNamePattern</argName>

<argType>TypeNamePattern</argType>

<replacement>SubstituteArgName</replacement>

<replaceWithType>[true|false]</replaceWithType>

</substitution>

...

</substitutions>

Where the arg T ype element and the repl aceWi thT ype element are optional and can be omitted.

Scope

As shown in the following extract, the substi tuti o ns element can optionally appear as a child of the api s element and/or as a child of api elements:

<apis>

<api>

...

<substi tuti o ns>. . . </substi tuti o ns>

</api>

<substi tuti o ns>. . . </substi tuti o ns>

...

</apis>

</configuration>

You can define the substi tuti o ns element at the following scopes:

As a child of an api element—the substi tuti o ns apply only to the API class specified by the api element.

As a child of the apis element—the substi tuti o ns apply to all API classes by default, but can be overridden at the api level.

678

Child element s

CHAPT ER 55. CO NFIG URING T HE API CO MPO NENT MAVEN PLUG - IN

Each substi tuti o n element can be defined with the following child elements:

metho d

Specifies a regular expression (java. uti l . reg ex syntax) to match a method name from the Java API.

arg Name

Specifies a regular expression (java. uti l . reg ex syntax) to match an argument name from the matched method, where the pattern typically includes capturing groups.

arg T ype

(Optional) Specifies a regular expression (java. uti l . reg ex syntax) to match the type of the argument. If you set the repl aceWi thT ype option to true, you would typically use capturing groups in this regular expression.

repl acement

Given a particular match of the metho d pattern, arg Name pattern, and (optionally)

arg T ype pattern, the repl acement element defines the substitute argument name

(for use in a URI). The replacement text can be constructed using strings captured from the arg Name regular expression pattern (using the syntax, $1, $2, $3 to insert the first, second, or third capturing group, respectively). Alternatively, the replacement text can be constructed using strings captured from the arg T ype regular expression pattern, if you set the repl aceWi thT ype option to true.

repl aceWi thT ype

When true, specifies that the replacement text is constructed using strings captured from the arg T ype regular expression. Defaults to fal se.

Example

The following substitution example modifies every argument of java. l ang . Stri ng type, by adding the suffix, P aram to the argument name:

<argType> java.lang.String

</argType>

<replacement> $1Param </replacement>

<replaceWithType> false </replaceWithType>

</substitution>

</substitutions>

For example, given the following method signature:

679

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

public String greetUs(String name1, String name2);

The arguments of this method would be specified through the options, name1P aram and

name2P aram, in the endpoint URI.

55.6. EXCLUDED ARGUMENT S

Overview

Sometimes, you might need to exclude certain arguments, when it comes to mapping Java arguments to URI options. You can filter out unwanted arguments by specifying either the

excl ud eC o nfi g Names element or the excl ud eC o nfi g T ypes element in the camel -

api -co mpo nent-maven-pl ug i n plug-in configuration.

Synt ax

The excl ud eC o nfi g Names element and the excl ud eC o nfi g T ypes element are specified as follows:

<excludeConfigNames>ArgumentNamePattern</excludeConfigNames>

<excludeConfigTypes>TypeNamePattern</excludeConfigTypes>

Where ArgumentNamePattern and TypeNamePattern are regular expressions that match the argument name and the argument type, respectively.

Scope

As shown in the following extract, the excl ud eC o nfi g Names element and the

excl ud eC o nfi g T ypes element can optionally appear as children of the api s element and/or as children of api elements:

<apis>

<api>

...

<excl ud eC o nfi g Names>. . . </excl ud eC o nfi g Names>

<excl ud eC o nfi g T ypes>. . . </excl ud eC o nfi g T ypes>

</api>

<excl ud eC o nfi g Names>. . . </excl ud eC o nfi g Names>

<excl ud eC o nfi g T ypes>. . . </excl ud eC o nfi g T ypes>

...

</apis>

</configuration>

You can define the excl ud eC o nfi g Names element and the excl ud eC o nfi g T ypes element at the following scopes:

680

CHAPT ER 55. CO NFIG URING T HE API CO MPO NENT MAVEN PLUG - IN

As a child of an api element—the exclusions apply only to the API class specified by the

api element.

As a child of the apis element—the exclusions apply to all API classes by default, but can be overridden at the api level.

Element s

The following elements can be used to exclude arguments from the API mapping (so that they are unavailable as URI options):

excl ud eC o nfi g Names

Specifies a regular expression (java. uti l . reg ex syntax) for excluding arguments, based on matching the argument name.

excl ud eC o nfi g T ypes

Specifies a regular expression (java. uti l . reg ex syntax) for excluding arguments, based on matching the argument type.

55.7. EXT RA OPT IONS

Overview

The extraO pti o ns options are usually used to either compute or hide complex API parameters by providing simpler options instead. For example, the API method might take a

POJO option, that could be provided more easily as parts of the POJO in the URI. The component could do this by adding the parts as extra options, and creating the POJO parameter internally. To complete the implementation of these extra options, you also need to override the i nterceptP ro perti es method in the End po i ntC o nsumer and/or

End po i ntP ro d ucer classes (see

Section 54.4, “ Programming Model”

Synt ax

The extraO pti o ns element can be defined with one or more extraO pti o n child elements, as follows:

<type>TypeName</type>

<name>OptionName</name>

</extraOption>

</extraOptions>

Where TypeName is the fully-qualified type name of the extra option and OptionName is the name of the extra URI option.

681

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

Scope

As shown in the following extract, the extraO pti o ns element can optionally appear as a child of the api s element and/or as a child of api elements:

<apis>

<api>

...

<extraO pti o ns>. . . </extraO pti o ns>

</api>

<extraO pti o ns>. . . </extraO pti o ns>

...

</apis>

</configuration>

You can define the extraO pti o ns element at the following scopes:

As a child of an api element—the extraO pti o ns apply only to the API class specified by the api element.

As a child of the apis element—the extraO pti o ns apply to all API classes by default, but can be overridden at the api level.

Child element s

Each extraO pti o ns element can be defined with the following child elements:

type

Specifies the fully-qualified type name of the extra option.

name

Specifies the option name, as it would appear in an endpoint URI.

Example

The following example defines an extra URI option, custo mO pti o n, which is of

java. uti l . l i st<Stri ng > type:

<type> java.util.List& lt;String& gt; </type>

<name> customOption </name>

</extraOption>

</extraOptions>

682

INDEX

Symbols

@ Co n vert er, Imp lemen t an an n o t at ed co n vert er class

A

Asyn cCallb ack,

Asyn ch ro n o u s p ro cessin g

asyn ch ro n o u s p ro d u cer imp lemen t in g ,

Ho w t o imp lemen t an asyn ch ro n o u s p ro d u cer

Asyn cPro cesso r,

Asyn ch ro n o u s p ro cessin g

au t o - d isco very co n f ig u rat io n ,

Co n f ig u rin g au t o - d isco very

C

Co mp o n en t

creat eEn d p o in t ( ) , URI p arsin g

d ef in it io n , T h e Co mp o n en t in t erf ace

met h o d s, Co mp o n en t met h o d s

co mp o n en t p ref ix,

Co mp o n en t co mp o n en t s, Co mp o n en t

b ean p ro p ert ies,

Def in e b ean p ro p ert ies o n yo u r co mp o n en t class

co n f ig u rin g , In st allin g an d co n f ig u rin g t h e co mp o n en t

imp lemen t at io n st ep s, Imp lemen t at io n st ep s

in st allin g , In st allin g an d co n f ig u rin g t h e co mp o n en t

in t erf aces t o imp lemen t ,

Wh ich in t erf aces d o yo u n eed t o imp lemen t ?

p aramet er in ject io n ,

Paramet er in ject io n

Sp rin g co n f ig u rat io n ,

Co n f ig u re t h e co mp o n en t in Sp rin g

Co n su mer,

Co n su mer

INDEX

683

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide

co n su mers, Co n su mer

even t - d riven ,

Even t - d riven p at t ern ,

Imp lemen t at io n st ep s

p o llin g ,

Po llin g p at t ern

, Imp lemen t at io n st ep s

sch ed u led , Sch ed u led p o ll p at t ern

, Imp lemen t at io n st ep s

t h read in g ,

O verview

D

Def au lt Co mp o n en t

creat eEn d p o in t ( ) , URI p arsin g

Def au lt En d p o in t , Even t - d riven en d p o in t imp lemen t at io n creat eExch an g e( ) , Even t - d riven en d p o in t imp lemen t at io n

creat ePo llin g Co n su mer( ) ,

Even t - d riven en d p o in t imp lemen t at io n

g et CamelCo n ext ( ) ,

Even t - d riven en d p o in t imp lemen t at io n

g et Co mp o n en t ( ) ,

Even t - d riven en d p o in t imp lemen t at io n g et En d p o in t Uri( ) , Even t - d riven en d p o in t imp lemen t at io n

E

En d p o in t ,

En d p o in t

creat eCo n su mer( ) ,

En d p o in t met h o d s creat eExch an g e( ) , En d p o in t met h o d s

creat ePo llin g Co n su mer( ) ,

En d p o in t met h o d s

creat ePro d u cer( ) ,

En d p o in t met h o d s

g et CamelCo n t ext ( ) ,

En d p o in t met h o d s g et En d p o in t URI( ) , En d p o in t met h o d s

in t erf ace d ef in it io n ,

T h e En d p o in t in t erf ace

isLen ien t Pro p ert ies( ) ,

En d p o in t met h o d s

isSin g let o n ( ) ,

En d p o in t met h o d s set CamelCo n t ext ( ) , En d p o in t met h o d s

684

en d p o in t even t - d riven ,

Even t - d riven en d p o in t imp lemen t at io n

sch ed u led , Sch ed u led p o ll en d p o in t imp lemen t at io n

en d p o in t s, En d p o in t

Exch an g e,

Exch an g e

T h e Exch an g e in t erf ace

co p y( ) , Exch an g e met h o d s

g et Exch an g eId ( ) ,

Exch an g e met h o d s

g et In ( ) ,

Accessin g messag e h ead ers

, Exch an g e met h o d s g et O u t ( ) , Exch an g e met h o d s g et Pat t ern ( ) , Exch an g e met h o d s

g et Pro p ert ies( ) ,

Exch an g e met h o d s g et Pro p ert y( ) , Exch an g e met h o d s

g et Un it O f Wo rk( ) ,

Exch an g e met h o d s remo vePro p ert y( ) , Exch an g e met h o d s set Exch an g eId ( ) , Exch an g e met h o d s set In ( ) , Exch an g e met h o d s set O u t ( ) , Exch an g e met h o d s

set Pro p ert y( ) ,

Exch an g e met h o d s set Un it O f Wo rk( ) , Exch an g e met h o d s

exch an g e in cap ab le,

o u t cap ab le,

accessin g , Wrap p in g t h e exch an g e accesso rs

exch an g e p ro p ert ies

Exch an g eHelp er, T h e Exch an g eHelp er Class

g et Co n t en t T yp e( ) , G et t h e In messag e' s MIME co n t en t t yp e

g et Man d at o ryHead er( ) , Accessin g messag e h ead ers

, Wrap p in g t h e

INDEX

685

Red Hat JBoss Fuse 6 .2 Apache Camel Development G uide exch an g e accesso rs

g et Man d at o ryIn Bo d y( ) , Wrap p in g t h e exch an g e accesso rs g et Man d at o ryO u t Bo d y( ) , Wrap p in g t h e exch an g e accesso rs g et Man d at o ryPro p ert y( ) , Wrap p in g t h e exch an g e accesso rs

isIn Cap ab le( ) ,

isO u t Cap ab le( ) ,