1.5. Processors

Overview

To enable the router to do something more interesting than simply connecting a consumer endpoint to a producer endpoint, you can add processors to your route. A processor is a command you can insert into a routing rule to perform arbitrary processing of messages that flow through the rule. Apache Camel provides a wide variety of different processors, as shown in Table 1.1, “Apache Camel Processors”.

Table 1.1. Apache Camel Processors

 
 
 
 
 
 
 
 
 
 

Some sample processors

To get some idea of how to use processors in a route, see the following examples:

the section called “Choice”.the section called “Filter”.the section called “Throttler”.the section called “Custom processor”. 

Choice

The choice() processor is a conditional statement that is used to route incoming messages to alternative producer endpoints. Each alternative producer endpoint is preceded by a when() method, which takes a predicate argument. If the predicate is true, the following target is selected, otherwise processing proceeds to the next when() method in the rule. For example, the following choice() processor directs incoming messages to either Target1, Target2, or Target3, depending on the values of Predicate1 and Predicate2:

from("SourceURL")    .choice()        .when(Predicate1).to("Target1")        .when(Predicate2).to("Target2")        .otherwise().to("Target3");

Or equivalently in Spring XML:

<camelContext id="buildSimpleRouteWithChoice" xmlns="http://camel.apache.org/schema/spring">  <route>    <from uri="SourceURL"/>    <choice>      <when>        <!-- First predicate -->        <simple>header.foo = 'bar'</simple>        <to uri="Target1"/>      </when>      <when>        <!-- Second predicate -->        <simple>header.foo = 'manchu'</simple>        <to uri="Target2"/>      </when>      <otherwise>        <to uri="Target3"/>      </otherwise>    </choice>  </route></camelContext>

In the Java DSL, there is a special case where you might need to use the endChoice() command. Some of the standard Apache Camel processors enable you to specify extra parameters using special sub-clauses, effectively opening an extra level of nesting which is usually terminated by the end() command.

For example, you could specify a load balancer clause as loadBalance().roundRobin().to(“mock:foo”).to(“mock:bar”).end(), which load balances messages between the mock:foo and mock:bar endpoints. If the load balancer clause is embedded in a choice condition, however, it is necessary to terminate the clause using the endChoice() command, as follows:

from("direct:start")    .choice()        .when(bodyAs(String.class).contains("Camel"))            .loadBalance().roundRobin().to("mock:foo").to("mock:bar").endChoice()        .otherwise()            .to("mock:result");

Filter

The filter() processor can be used to prevent uninteresting messages from reaching the producer endpoint. It takes a single predicate argument: if the predicate is true, the message exchange is allowed through to the producer; if the predicate is false, the message exchange is blocked. For example, the following filter blocks a message exchange, unless the incoming message contains a header, foo, with value equal to bar:

from("SourceURL").filter(header("foo").isEqualTo("bar")).to("TargetURL");

Or equivalently in Spring XML:

<camelContext id="filterRoute" xmlns="http://camel.apache.org/schema/spring">  <route>    <from uri="SourceURL"/>    <filter>      <simple>header.foo = 'bar'</simple>      <to uri="TargetURL"/>    </filter>  </route></camelContext>

Throttler

The throttle() processor ensures that a producer endpoint does not get overloaded. The throttler works by limiting the number of messages that can pass through per second. If the incoming messages exceed the specified rate, the throttler accumulates excess messages in a buffer and transmits them more slowly to the producer endpoint. For example, to limit the rate of throughput to 100 messages per second, you can define the following rule:

from("SourceURL").throttle(100).to("TargetURL");

Or equivalently in Spring XML:

<camelContext id="throttleRoute" xmlns="http://camel.apache.org/schema/spring">  <route>    <from uri="SourceURL"/>    <throttle maximumRequestsPerPeriod="100" timePeriodMillis="1000">      <to uri="TargetURL"/>    </throttle>  </route></camelContext>

Custom processor

If none of the standard processors described here provide the functionality you need, you can always define your own custom processor. To create a custom processor, define a class that implements the org.apache.camel.Processor interface and overrides the process() method. The following custom processor, MyProcessor, removes the header named foo from incoming messages:

Example 1.3. Implementing a Custom Processor Class

public class MyProcessor implements org.apache.camel.Processor {public void process(org.apache.camel.Exchange exchange) {  inMessage = exchange.getIn();  if (inMessage != null) {      inMessage.removeHeader("foo");  }}};

To insert the custom processor into a router rule, invoke the process() method, which provides a generic mechanism for inserting processors into rules. For example, the following rule invokes the processor defined in Example 1.3, “Implementing a Custom Processor Class”:

org.apache.camel.Processor myProc = new MyProcessor();from("SourceURL").process(myProc).to("TargetURL");