Component Appendix

ActiveMQ Component

The ActiveMQ component allows messages to be sent to a JMS Queue or Topic or messages to be consumed from a JMS Queue or Topic using Apache ActiveMQ. This component is based on JMS Component and uses Spring's JMS support for declarative transactions, using Spring's JmsTemplate for sending and a MessageListenerContainer for consuming. All the options from the JMS component also applies for this component.

To use this component make sure you have the activemq.jar or activemq-core.jar on your classpath along with any Camel dependencies such as camel-core.jar, camel-spring.jar and camel-jms.jar.

URI format

Where destinationName is an ActiveMQ queue or topic name. By default, the destinationName is interpreted as a queue name. For example, to connect to the queue, FOO.BAR, use:

You can include the optional queue: prefix, if you prefer:

To connect to a topic, you must include the topic: prefix. For example, to connect to the topic, Stocks.Prices, use:

Options

See Options on the JMS component as all these options also apply for this component.

Configuring the Connection Factory

This test case shows how to add an ActiveMQComponent to the CamelContext using the activeMQComponent() method while specifying the brokerURL used to connect to ActiveMQ.

Configuring the Connection Factory using Spring XML

You can configure the ActiveMQ broker URL on the ActiveMQComponent as follows

Using Connection Pooling

When sending to an ActiveMQ broker using Camel it's recommended to use a pooled connection factory to efficiently handle pooling of JMS connections, sessions and producers. This is documented on the ActiveMQ Spring Support page.

You can grab ActiveMQ's org.apache.activemq.pool.PooledConnectionFactory with Maven:

And then setup the activemq Camel component as follows:

The PooledConnectionFactory will then create a connection pool with up to 8 connections in use at the same time. Each connection can be shared by many sessions. There is an option named maximumActive you can use to configure the maximum number of sessions per connection; the default value is 500. From ActiveMQ 5.7: the option has been renamed to better reflect its purpose, being named as maximumActiveSessionPerConnection. Notice the concurrentConsumers is set to a higher value than maxConnections is. This is okay, as each consumer is using a session, and as a session can share the same connection, we are in the safe. In this example we can have 8 * 500 = 4000 active sessions at the same time.

Invoking MessageListener POJOs in a Camel route

The ActiveMQ component also provides a helper Type Converter from a JMS MessageListener to a Processor. This means that the Bean component is capable of invoking any JMS MessageListener bean directly inside any route.

So for example you can create a MessageListener in JMS like this:

Then use it in your Camel route as follows

That is, you can reuse any of the Camel Components and easily integrate them into your JMS MessageListener POJO!

Using ActiveMQ Destination Options

Available as of ActiveMQ 5.6

You can configure the Destination Options in the endpoint URI, using the destination. prefix. For example to mark a consumer as exclusive, and set its prefetch size to 50, you can do as follows:

Consuming Advisory Messages

ActiveMQ can generate Advisory messages which are put in topics that you can consume. Such messages can help you send alerts in case you detect slow consumers or to build statistics (number of messages/produced per day, etc.) The following Spring DSL example shows you how to read messages from a topic.

The below route starts by reading the topic ActiveMQ.Advisory.Connection. To watch another topic, simply change the name according to the name provided in ActiveMQ Advisory Messages documentation. The parameter mapJmsMessage=false allows for converting the org.apache.activemq.command.ActiveMqMessage object from the JMS queue. Next, the body received is converted into a String for the purposes of this example and a carriage return is added. Finally, the string is added to a file

If you consume a message on a queue, you should see the following files under the data/activemq folder :

advisoryConnection-20100312.txt
advisoryProducer-20100312.txt

containing the following string:

Getting Component JAR

You will need this dependency

• activemq-camel

ActiveMQ is an extension of the JMS component released with the ActiveMQ project.

Endpoint See Also

AMQP

The amqp: component supports the AMQP 1.0 protocol using the JMS Client API of the Qpid project. In case you want to use AMQP 0.9 (in particular RabbitMQ) you might also be interested in the Camel RabbitMQ component. Please keep in mind that prior to the Camel 2.17.0 AMQP component supported AMQP 0.9 and above, however since Camel 2.17.0 it supports only AMQP 1.0.

Maven users will need to add the following dependency to their pom.xml for this component:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-amqp</artifactId>
    <version>${camel.version}</version> <!-- use the same version as your Camel core version -->
</dependency>

URI format

amqp:[queue:|topic:]destinationName[?options]

AMQP Options

You can specify all of the various configuration options of the JMS component after the destination name.

Usage

As AMQP component inherits from the JMS component. The usage of the former is almost identical to the latter:

// Consuming from AMQP queue
from("amqp:queue:incoming")
  .to(...);
 
// Sending message to the AMQP topic
from(...)
  .to("amqp:topic:notify");

Configuring AMQP component

Starting from the Camel 2.16.1 you can also use the AMQPComponent#amqp10Component(String connectionURI) factory method to return the AMQP 1.0 component with the pre-configured topic prefix: 

 AMQPComponent amqp = AMQPComponent.amqp10Component("amqp://guest:guest@localhost:5672");

Keep in mind that starting from the Camel 2.17 the AMQPComponent#amqp10Component(String connectionURI) factory method has been deprecated on the behalf of the AMQPComponent#amqpComponent(String connectionURI): 

AMQPComponent amqp = AMQPComponent.amqpComponent("amqp://localhost:5672");
 
AMQPComponent authorizedAmqp = AMQPComponent.amqpComponent("amqp://localhost:5672", "user", "password");

Starting from Camel 2.17, in order to automatically configure the AMQP component, you can also add an instance of org.apache.camel.component.amqp.AMQPConnectionDetails to the registry. For example for Spring Boot you just have to define bean:

@Bean
AMQPConnectionDetails amqpConnection() {
  return new AMQPConnectionDetails("amqp://lcoalhost:5672"); 
}
 
@Bean
AMQPConnectionDetails securedAmqpConnection() {
  return new AMQPConnectionDetails("amqp://lcoalhost:5672", "username", "password"); 
}

You can also rely on the Camel properties to read the AMQP connection details. The factory method AMQPConnectionDetails.discoverAMQP() attempts to read Camel properties in a Kubernetes-like convention, just as demonstrated on the snippet below:

export AMQP_SERVICE_HOST = "mybroker.com"
export AMQP_SERVICE_PORT = "6666"
export AMQP_SERVICE_USERNAME = "username"
export AMQP_SERVICE_PASSWORD = "password"
 
...
 
@Bean
AMQPConnectionDetails amqpConnection() {
  return AMQPConnectionDetails.discoverAMQP(); 
}

Configuring Connection Factory

Like with any other JMS-based component, usually it's important to configure JMS connection factory. For example, you'd like to set your broker URL or set proper connection credentials. Additionally, you would always want to set some kind of pooling (or caching) on the connection factory. An example of how to do both of these tasks is shown below.

<bean id="jmsConnectionFactory" class="org.apache.qpid.jms.JmsConnectionFactory">
  <property name="remoteURI" value="amqp://localhost:5672" />
  <property name="username" value="admin"/>
  <property name="password" value="admin"/>
</bean>

<bean id="jmsCachingConnectionFactory" class="org.springframework.jms.connection.CachingConnectionFactory">
  <property name="targetConnectionFactory" ref="jmsConnectionFactory" />
</bean>

<bean id="jmsConfig" class="org.apache.camel.component.jms.JmsConfiguration" >
  <property name="connectionFactory" ref="jmsCachingConnectionFactory" /> 
  <property name="cacheLevelName" value="CACHE_CONSUMER" />
</bean>    

<bean id="amqp" class="org.apache.camel.component.amqp.AMQPComponent">
    <property name="configuration" ref="jmsConfig" />
</bean>    

<camelContext xmlns="http://camel.apache.org/schema/blueprint" id="simple">
  <route>
    <from uri="timer:simple?period=5000"/>
    <setBody>
        <simple>Hello World</simple>
    </setBody>
    <to uri="amqp:test"/>
  </route>
</camelContext>

Using amqp inside Karaf

To use the amqp component inside Karaf use the predefined feature called camel-amqp to install the necessary bundles.

Example:

karaf@root()> repo-add camel
karaf@root()> feature:install camel-amqp

and the environment would be set.

Use the camel-blueprint or camel-spring features to define routes in those contexts.

SQS Component

Available as of Camel 2.6

The sqs component supports sending and receiving messages to Amazon's SQS service.

URI Format

aws-sqs://queueName[?options]
aws-sqs://queueNameOrArn[?options] (from Camel 2.18)

The queue will be created if they don't already exists. You can append query options to the URI in the following format: ?options=value&option2=value&...

URI Options

Batch Consumer

This component implements the Batch Consumer.

This allows you for instance to know how many messages exists in this batch and for instance let the Aggregator aggregate this number of messages.

Usage

Message headers set by the SQS producer

Message headers set by the SQS consumer

Advanced AmazonSQS configuration

If your Camel Application is running behind a firewall or if you need to have more control over the AmazonSQS instance configuration, you can create your own instance:

AWSCredentials awsCredentials = new BasicAWSCredentials("myAccessKey", "mySecretKey");

ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setProxyHost("http://myProxyHost");
clientConfiguration.setProxyPort(8080);

AmazonSQS client = new AmazonSQSClient(awsCredentials, clientConfiguration);

registry.bind("client", client);

and refer to it in your Camel aws-sqs component configuration:

from("aws-sqs://MyQueue?amazonSQSClient=#client&delay=5000&maxMessagesPerPoll=5")
  .to("mock:result");

Dependencies

Maven users will need to add the following dependency to their pom.xml.

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-aws</artifactId>
    <version>${camel-version}</version>
</dependency>

where ${camel-version} must be replaced by the actual version of Camel (2.6 or higher).

JMS-style Selectors

SQS does not allow selectors, but you can effectively achieve this by using the Camel Filter EIP and setting an appropriate visibilityTimeout. When SQS dispatches a message, it will wait up to the visibility timeout before it will try to dispatch the message to a different consumer unless a DeleteMessage is received. By default, Camel will always send the DeleteMessage at the end of the route, unless the route ended in failure. To achieve appropriate filtering and not send the DeleteMessage even on successful completion of the route, use a Filter:

from("aws-sqs://MyQueue?amazonSQSClient=#client&defaultVisibilityTimeout=5000&deleteIfFiltered=false")
  .filter("${header.login} == true")
  .to("mock:result");

In the above code, if an exchange doesn't have an appropriate header, it will not make it through the filter AND also not be deleted from the SQS queue. After 5000 miliseconds, the message will become visible to other consumers.

• AWS Component

Atom Component

The atom: component is used for polling Atom feeds.

Camel will poll the feed every 60 seconds by default.
Note: The component currently only supports polling (consuming) feeds.

Maven users will need to add the following dependency to their pom.xml for this component:

URI format

Where atomUri is the URI to the Atom feed to poll.

Options

You can append query options to the URI in the following format, ?option=value&option=value&...

Exchange data format

Camel will set the In body on the returned Exchange with the entries. Depending on the splitEntries flag Camel will either return one Entry or a List<Entry>.

Camel can set the Feed object on the In header (see feedHeader option to disable this):

Message Headers

Camel atom uses these headers.

Samples

In this sample we poll James Strachan's blog.

In this sample we want to filter only good blogs we like to a SEDA queue. The sample also shows how to setup Camel standalone, not running in any Container or using Spring.{snippet:id=e1|lang=java|url=camel/trunk/components/camel-atom/src/test/java/org/apache/camel/component/atom/AtomGoodBlogsTest.java}Endpoint See Also

• RSS

Bean Component

The bean: component binds beans to Camel message exchanges.

URI format

bean:beanID[?options]

Where beanID can be any string which is used to look up the bean in the Registry

Options

confluenceTableSmall

You can append query options to the URI in the following format, ?option=value&option=value&...

Using

The object instance that is used to consume messages must be explicitly registered with the Registry. For example, if you are using Spring you must define the bean in the Spring configuration, spring.xml; or if you don't use Spring, by registering the bean in JNDI.

// lets populate the context with the services we need
// note that we could just use a spring.xml file to avoid this step
JndiContext context = new JndiContext();
context.bind("bye", new SayService("Good Bye!"));

CamelContext camelContext = new DefaultCamelContext(context);

{snippet:id=register|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/component/pojo/PojoRouteTest.java}

Once an endpoint has been registered, you can build Camel routes that use it to process exchanges.

camelContext.addRoutes(new RouteBuilder() {
    public void configure() {
        from("direct:hello").to("bean:bye");
    }
});

A bean: endpoint cannot be defined as the input to the route; i.e. you cannot consume from it, you can only route from some inbound message Endpoint to the bean endpoint as output. So consider using a direct: or queue: endpoint as the input.

You can use the createProxy() methods on ProxyHelper to create a proxy that will generate BeanExchanges and send them to any endpoint:

Endpoint endpoint = camelContext.getEndpoint("direct:hello");
ISay proxy = PojoComponent.createProxy(endpoint, ISay.class);
String rc = proxy.say();
assertEquals("Good Bye!", rc);

And the same route using Spring DSL:

<route> 
 <from uri="direct:hello">
 <to uri="bean:bye"/>
</route>

Bean as endpoint

Camel also supports invoking Bean as an Endpoint. In the route below:

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <to uri="myBean"/>
    <to uri="mock:results"/>
  </route>
</camelContext>

<bean id="myBean" class="org.apache.camel.spring.bind.ExampleBean"/>

What happens is that when the exchange is routed to the myBean Camel will use the Bean Binding to invoke the bean.
The source for the bean is just a plain POJO:

public class ExampleBean {
    public String sayHello(String name) {
        return "Hello " + name + "!";
    }
}

Camel will use Bean Binding to invoke the sayHello method, by converting the Exchange's In body to the String type and storing the output of the method on the Exchange Out body.

Java DSL bean syntax

Java DSL comes with syntactic sugar for the Bean component. Instead of specifying the bean explicitly as the endpoint (i.e. to("bean:beanName")) you can use the following syntax:

//Send message to the bean endpoint 
// and invoke method resolved using Bean Binding. 
from("direct:start").beanRef("beanName"); 
 
// Send message to the bean endpoint 
// and invoke given method. 
from("direct:start").beanRef("beanName", "methodName");

Instead of passing name of the reference to the bean (so that Camel will lookup for it in the registry), you can specify the bean itself:

// Send message to the given bean instance. 
from("direct:start").bean(new ExampleBean());
// Explicit selection of bean method to be invoked.
from("direct:start").bean(new ExampleBean(), "methodName");
// Camel will create the instance of bean and cache it for you.
from("direct:start").bean(ExampleBean.class);

Bean Binding

How bean methods to be invoked are chosen (if they are not specified explicitly through the method parameter) and how parameter values are constructed from the Message are all defined by the Bean Binding mechanism which is used throughout all of the various Bean Integration mechanisms in Camel.

Endpoint See Also

• Class component
• Bean Binding
• Bean Integration

Browse Component

The Browse component provides a simple BrowsableEndpoint which can be useful for testing, visualisation tools or debugging. The exchanges sent to the endpoint are all available to be browsed.

URI format

browse:someName[?options]

Where someName can be any string to uniquely identify the endpoint.

Sample

In the route below, we insert a browse: component to be able to browse the Exchanges that are passing through:

  from("activemq:order.in").to("browse:orderReceived").to("bean:processOrder");

We can now inspect the received exchanges from within the Java code:

    private CamelContext context;

    public void inspectRecievedOrders() {
        BrowsableEndpoint browse = context.getEndpoint("browse:orderReceived", BrowsableEndpoint.class);
        List<Exchange> exchanges = browse.getExchanges();
        ...
        // then we can inspect the list of received exchanges from Java
        for (Exchange exchange : exchanges) {
            String payload = exchange.getIn().getBody();
            ...
        }
   }

Cache Component

Available as of Camel 2.1

The cache component enables you to perform caching operations using EHCache as the Cache Implementation. The cache itself is created on demand or if a cache of that name already exists then it is simply utilized with its original settings.

This component supports producer and event based consumer endpoints.

The Cache consumer is an event based consumer and can be used to listen and respond to specific cache activities. If you need to perform selections from a pre-existing cache, use the processors defined for the cache component.

Maven users will need to add the following dependency to their pom.xml for this component:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-cache</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

URI format

cache://cacheName[?options]

You can append query options to the URI in the following format, ?option=value&option=#beanRef&...

Options

Cache Component options

Sending/Receiving Messages to/from the cache

Message Headers up to Camel 2.7

Message Headers Camel 2.8+

The CamelCacheAdd and CamelCacheUpdate operations support additional headers:

Cache Producer

Sending data to the cache involves the ability to direct payloads in exchanges to be stored in a pre-existing or created-on-demand cache. The mechanics of doing this involve

• setting the Message Exchange Headers shown above.
• ensuring that the Message Exchange Body contains the message directed to the cache

Cache Consumer

Receiving data from the cache involves the ability of the CacheConsumer to listen on a pre-existing or created-on-demand Cache using an event Listener and receive automatic notifications when any cache activity take place (i.e CamelCacheGet/CamelCacheUpdate/CamelCacheDelete/CamelCacheDeleteAll). Upon such an activity taking place

• an exchange containing Message Exchange Headers and a Message Exchange Body containing the just added/updated payload is placed and sent.
• in case of a CamelCacheDeleteAll operation, the Message Exchange Header CamelCacheKey and the Message Exchange Body are not populated.

Cache Processors

There are a set of nice processors with the ability to perform cache lookups and selectively replace payload content at the

• body
• token
• xpath level

Cache Usage Samples

Example 1: Configuring the cache

from("cache://MyApplicationCache" +
          "?maxElementsInMemory=1000" +
          "&memoryStoreEvictionPolicy=" +
              "MemoryStoreEvictionPolicy.LFU" +
          "&overflowToDisk=true" +
          "&eternal=true" +
          "&timeToLiveSeconds=300" +
          "&timeToIdleSeconds=true" +
          "&diskPersistent=true" +
          "&diskExpiryThreadIntervalSeconds=300")

Example 2: Adding keys to the cache

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
     from("direct:start")
     .setHeader(CacheConstants.CACHE_OPERATION, constant(CacheConstants.CACHE_OPERATION_ADD))
     .setHeader(CacheConstants.CACHE_KEY, constant("Ralph_Waldo_Emerson"))
     .to("cache://TestCache1")
   }
};

Example 2: Updating existing keys in a cache

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
     from("direct:start")
     .setHeader(CacheConstants.CACHE_OPERATION, constant(CacheConstants.CACHE_OPERATION_UPDATE))
     .setHeader(CacheConstants.CACHE_KEY, constant("Ralph_Waldo_Emerson"))
     .to("cache://TestCache1")
   }
};

Example 3: Deleting existing keys in a cache

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
     from("direct:start")
     .setHeader(CacheConstants.CACHE_OPERATION, constant(CacheConstants.CACHE_DELETE))
     .setHeader(CacheConstants.CACHE_KEY", constant("Ralph_Waldo_Emerson"))
     .to("cache://TestCache1")
   }
};

Example 4: Deleting all existing keys in a cache

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
     from("direct:start")
     .setHeader(CacheConstants.CACHE_OPERATION, constant(CacheConstants.CACHE_DELETEALL))
     .to("cache://TestCache1");
    }
};

Example 5: Notifying any changes registering in a Cache to Processors and other Producers

RouteBuilder builder = new RouteBuilder() {
    public void configure() {
     from("cache://TestCache1")
     .process(new Processor() {
        public void process(Exchange exchange)
               throws Exception {
           String operation = (String) exchange.getIn().getHeader(CacheConstants.CACHE_OPERATION);
           String key = (String) exchange.getIn().getHeader(CacheConstants.CACHE_KEY);
           Object body = exchange.getIn().getBody();
           // Do something
        }
     })
   }
};

Example 6: Using Processors to selectively replace payload with cache values

RouteBuilder builder = new RouteBuilder() {
   public void configure() {
     //Message Body Replacer
     from("cache://TestCache1")
     .filter(header(CacheConstants.CACHE_KEY).isEqualTo("greeting"))
     .process(new CacheBasedMessageBodyReplacer("cache://TestCache1","farewell"))
     .to("direct:next");

    //Message Token replacer
    from("cache://TestCache1")
    .filter(header(CacheConstants.CACHE_KEY).isEqualTo("quote"))
    .process(new CacheBasedTokenReplacer("cache://TestCache1","novel","#novel#"))
    .process(new CacheBasedTokenReplacer("cache://TestCache1","author","#author#"))
    .process(new CacheBasedTokenReplacer("cache://TestCache1","number","#number#"))
    .to("direct:next");

    //Message XPath replacer
    from("cache://TestCache1").
    .filter(header(CacheConstants.CACHE_KEY).isEqualTo("XML_FRAGMENT"))
    .process(new CacheBasedXPathReplacer("cache://TestCache1","book1","/books/book1"))
    .process (new CacheBasedXPathReplacer("cache://TestCache1","book2","/books/book2"))
    .to("direct:next");
   }
};

Example 7: Getting an entry from the Cache

from("direct:start")
    // Prepare headers
    .setHeader(CacheConstants.CACHE_OPERATION, constant(CacheConstants.CACHE_OPERATION_GET))
    .setHeader(CacheConstants.CACHE_KEY, constant("Ralph_Waldo_Emerson")).
    .to("cache://TestCache1").
    // Check if entry was not found
    .choice().when(header(CacheConstants.CACHE_ELEMENT_WAS_FOUND).isNull()).
        // If not found, get the payload and put it to cache
        .to("cxf:bean:someHeavyweightOperation").
        .setHeader(CacheConstants.CACHE_OPERATION, constant(CacheConstants.CACHE_OPERATION_ADD))
        .setHeader(CacheConstants.CACHE_KEY, constant("Ralph_Waldo_Emerson"))
        .to("cache://TestCache1")
    .end()
    .to("direct:nextPhase");

Example 8: Checking for an entry in the Cache

Note: The CHECK command tests existence of an entry in the cache but doesn't place a message in the body.

from("direct:start")
    // Prepare headers
    .setHeader(CacheConstants.CACHE_OPERATION, constant(CacheConstants.CACHE_OPERATION_CHECK))
    .setHeader(CacheConstants.CACHE_KEY, constant("Ralph_Waldo_Emerson")).
    .to("cache://TestCache1").
    // Check if entry was not found
    .choice().when(header(CacheConstants.CACHE_ELEMENT_WAS_FOUND).isNull()).
        // If not found, get the payload and put it to cache
        .to("cxf:bean:someHeavyweightOperation").
        .setHeader(CacheConstants.CACHE_OPERATION, constant(CacheConstants.CACHE_OPERATION_ADD))
        .setHeader(CacheConstants.CACHE_KEY, constant("Ralph_Waldo_Emerson"))
        .to("cache://TestCache1")
    .end();

Management of EHCache

EHCache has its own statistics and management from JMX.

Here's a snippet on how to expose them via JMX in a Spring application context:

<bean id="ehCacheManagementService" class="net.sf.ehcache.management.ManagementService" init-method="init" lazy-init="false">
  <constructor-arg>
    <bean class="net.sf.ehcache.CacheManager" factory-method="getInstance"/>
  </constructor-arg>
  <constructor-arg>
    <bean class="org.springframework.jmx.support.JmxUtils" factory-method="locateMBeanServer"/>
  </constructor-arg>
  <constructor-arg value="true"/>
  <constructor-arg value="true"/>
  <constructor-arg value="true"/>
  <constructor-arg value="true"/>
</bean>

Of course you can do the same thing in straight Java:

ManagementService.registerMBeans(CacheManager.getInstance(), mbeanServer, true, true, true, true);

You can get cache hits, misses, in-memory hits, disk hits, size stats this way. You can also change CacheConfiguration parameters on the fly.

Cache replication Camel 2.8+

The Camel Cache component is able to distribute a cache across server nodes using several different replication mechanisms including: RMI, JGroups, JMS and Cache Server.

There are two different ways to make it work:

1. You can configure ehcache.xml manually

OR

2. You can configure these three options:

• cacheManagerFactory
• eventListenerRegistry
• cacheLoaderRegistry

Configuring Camel Cache replication using the first option is a bit of hard work as you have to configure all caches separately. So in a situation when the all names of caches are not known, using ehcache.xml is not a good idea.

The second option is much better when you want to use many different caches as you do not need to define options per cache. This is because replication options are set per CacheManager and per CacheEndpoint. Also it is the only way when cache names are not know at the development phase.

Example: JMS cache replication

JMS replication is the most powerful and secured replication method. Used together with Camel Cache replication makes it also rather simple.
An example is available on a separate page.

Class Component

Available as of Camel 2.4

The class: component binds beans to Camel message exchanges. It works in the same way as the Bean component but instead of looking up beans from a Registry it creates the bean based on the class name.

URI format

class:className[?options]

Where className is the fully qualified class name to create and use as bean.

Options

You can append query options to the URI in the following format, ?option=value&option=value&...

Using

You simply use the class component just as the Bean component but by specifying the fully qualified classname instead.
For example to use the MyFooBean you have to do as follows:

    from("direct:start").to("class:org.apache.camel.component.bean.MyFooBean").to("mock:result");

You can also specify which method to invoke on the MyFooBean, for example hello:

    from("direct:start").to("class:org.apache.camel.component.bean.MyFooBean?method=hello").to("mock:result");

Setting properties on the created instance

In the endpoint uri you can specify properties to set on the created instance, for example if it has a setPrefix method:

   // Camel 2.17 onwards
   from("direct:start")
        .to("class:org.apache.camel.component.bean.MyPrefixBean?bean.prefix=Bye")
        .to("mock:result");
 
   // Camel 2.16 and older 
   from("direct:start")
        .to("class:org.apache.camel.component.bean.MyPrefixBean?prefix=Bye")
        .to("mock:result");

And you can also use the # syntax to refer to properties to be looked up in the Registry.

    // Camel 2.17 onwards
    from("direct:start")
        .to("class:org.apache.camel.component.bean.MyPrefixBean?bean.cool=#foo")
        .to("mock:result");

    // Camel 2.16 and older
    from("direct:start")
        .to("class:org.apache.camel.component.bean.MyPrefixBean?cool=#foo")
        .to("mock:result");

Which will lookup a bean from the Registry with the id foo and invoke the setCool method on the created instance of the MyPrefixBean class.

• Bean
• Bean Binding
• Bean Integration

Cometd Component

The cometd: component is a transport for working with the jetty implementation of the cometd/bayeux protocol.
Using this component in combination with the dojo toolkit library it's possible to push Camel messages directly into the browser using an AJAX based mechanism.

Maven users will need to add the following dependency to their pom.xml for this component:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-cometd</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

URI format

cometd://host:port/channelName[?options]

The channelName represents a topic that can be subscribed to by the Camel endpoints.

Examples

cometd://localhost:8080/service/mychannel
cometds://localhost:8443/service/mychannel

where cometds: represents an SSL configured endpoint.

Options

You can append query options to the URI in the following format, ?option=value&option=value&...

Here is some examples on How to pass the parameters

For file (for webapp resources located in the Web Application directory --> cometd://localhost:8080?resourceBase=file./webapp
For classpath (when by example the web resources are packaged inside the webapp folder --> cometd://localhost:8080?resourceBase=classpath:webapp

Authentication

Available as of Camel 2.8

You can configure custom SecurityPolicy and Extension's to the CometdComponent which allows you to use authentication as documented here

Setting up SSL for Cometd Component

Using the JSSE Configuration Utility

As of Camel 2.9, the Cometd component supports SSL/TLS configuration through the Camel JSSE Configuration Utility.  This utility greatly decreases the amount of component specific code you need to write and is configurable at the endpoint and component levels.  The following examples demonstrate how to use the utility with the Cometd component. You need to configure SSL on the CometdComponent.

Programmatic configuration of the component

KeyStoreParameters ksp = new KeyStoreParameters();
ksp.setResource("/users/home/server/keystore.jks");
ksp.setPassword("keystorePassword");

KeyManagersParameters kmp = new KeyManagersParameters();
kmp.setKeyStore(ksp);
kmp.setKeyPassword("keyPassword");

TrustManagersParameters tmp = new TrustManagersParameters();
tmp.setKeyStore(ksp);

SSLContextParameters scp = new SSLContextParameters();
scp.setKeyManagers(kmp);
scp.setTrustManagers(tmp);

CometdComponent commetdComponent = getContext().getComponent("cometds", CometdComponent.class);
commetdComponent.setSslContextParameters(scp);

Spring DSL based configuration of endpoint

...
  <camel:sslContextParameters
      id="sslContextParameters">
    <camel:keyManagers
        keyPassword="keyPassword">
      <camel:keyStore
          resource="/users/home/server/keystore.jks"
          password="keystorePassword"/>
    </camel:keyManagers>
    <camel:trustManagers>
      <camel:keyStore
          resource="/users/home/server/keystore.jks"
          password="keystorePassword"/>
    </camel:keyManagers>
  </camel:sslContextParameters>...
 
  <bean id="cometd" class="org.apache.camel.component.cometd.CometdComponent">
    <property name="sslContextParameters" ref="sslContextParameters"/>
  </bean>
...
  <to uri="cometds://127.0.0.1:443/service/test?baseResource=file:./target/test-classes/webapp&timeout=240000&interval=0&maxInterval=30000&multiFrameInterval=1500&jsonCommented=true&logLevel=2"/>...

Context Component

Available as of Camel 2.7

The context component allows you to create new Camel Components from a CamelContext with a number of routes which is then treated as a black box, allowing you to refer to the local endpoints within the component from other CamelContexts.

It is similar to the Routebox component in idea, though the Context component tries to be really simple for end users; just a simple convention over configuration approach to refer to local endpoints inside the CamelContext Component.

Maven users will need to add the following dependency to their pom.xml for this component:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-context</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

URI format

context:camelContextId:localEndpointName[?options]

Or you can omit the "context:" prefix.

camelContextId:localEndpointName[?options]

• camelContextId is the ID you used to register the CamelContext into the Registry.
• localEndpointName can be a valid Camel URI evaluated within the black box CamelContext. Or it can be a logical name which is mapped to any local endpoints. For example if you locally have endpoints like direct:invoices and seda:purchaseOrders inside a CamelContext of id supplyChain, then you can just use the URIs supplyChain:invoices or supplyChain:purchaseOrders to omit the physical endpoint kind and use pure logical URIs.

You can append query options to the URI in the following format, ?option=value&option=value&...

Example

In this example we'll create a black box context, then we'll use it from another CamelContext.

Defining the context component

First you need to create a CamelContext, add some routes in it, start it and then register the CamelContext into the Registry (JNDI, Spring, Guice or OSGi etc).

This can be done in the usual Camel way from this test case (see the createRegistry() method); this example shows Java and JNDI being used...

// lets create our black box as a camel context and a set of routes
DefaultCamelContext blackBox = new DefaultCamelContext(registry);
blackBox.setName("blackBox");
blackBox.addRoutes(new RouteBuilder() {
    @Override
    public void configure() throws Exception {
        // receive purchase orders, lets process it in some way then send an invoice
        // to our invoice endpoint
        from("direct:purchaseOrder").
          setHeader("received").constant("true").
          to("direct:invoice");
    }
});
blackBox.start();

registry.bind("accounts", blackBox);

Notice in the above route we are using pure local endpoints (direct and seda). Also note we expose this CamelContext using the accounts ID. We can do the same thing in Spring via

<camelContext id="accounts" xmlns="http://camel.apache.org/schema/spring">
  <route> 
    <from uri="direct:purchaseOrder"/>
    ...
    <to uri="direct:invoice"/>
  </route>
</camelContext>

Using the context component

Then in another CamelContext we can then refer to this "accounts black box" by just sending to accounts:purchaseOrder and consuming from accounts:invoice.

If you prefer to be more verbose and explicit you could use context:accounts:purchaseOrder or even context:accounts:direct://purchaseOrder if you prefer. But using logical endpoint URIs is preferred as it hides the implementation detail and provides a simple logical naming scheme.

For example if we wish to then expose this accounts black box on some middleware (outside of the black box) we can do things like...

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route> 
    <!-- consume from an ActiveMQ into the black box -->
    <from uri="activemq:Accounts.PurchaseOrders"/>
    <to uri="accounts:purchaseOrders"/>
  </route>
  <route> 
    <!-- lets send invoices from the black box to a different ActiveMQ Queue -->
    <from uri="accounts:invoice"/>
    <to uri="activemq:UK.Accounts.Invoices"/>
  </route>
</camelContext>

Naming endpoints

A context component instance can have many public input and output endpoints that can be accessed from outside it's CamelContext. When there are many it is recommended that you use logical names for them to hide the middleware as shown above.

However when there is only one input, output or error/dead letter endpoint in a component we recommend using the common posix shell names in, out and err

Crypto component for Digital Signatures

Available as of Camel 2.3

With Camel cryptographic endpoints and Java's Cryptographic extension it is easy to create Digital Signatures for Exchanges. Camel provides a pair of flexible endpoints which get used in concert to create a signature for an exchange in one part of the exchange's workflow and then verify the signature in a later part of the workflow.

Maven users will need to add the following dependency to their pom.xml for this component:

Introduction

Digital signatures make use of Asymmetric Cryptographic techniques to sign messages. From a (very) high level, the algorithms use pairs of complimentary keys with the special property that data encrypted with one key can only be decrypted with the other. One, the private key, is closely guarded and used to 'sign' the message while the other, public key, is shared around to anyone interested in verifying the signed messages. Messages are signed by using the private key to encrypting a digest of the message. This encrypted digest is transmitted along with the message. On the other side the verifier recalculates the message digest and uses the public key to decrypt the the digest in the signature. If both digests match the verifier knows only the holder of the private key could have created the signature.

Camel uses the Signature service from the Java Cryptographic Extension to do all the heavy cryptographic lifting required to create exchange signatures. The following are some excellent resources for explaining the mechanics of Cryptography, Message digests and Digital Signatures and how to leverage them with the JCE.

• Bruce Schneier's Applied Cryptography
• Beginning Cryptography with Java by David Hook
• The ever insightful Wikipedia Digital_signatures

URI format

As mentioned Camel provides a pair of crypto endpoints to create and verify signatures

• crypto:sign creates the signature and stores it in the Header keyed by the constant org.apache.camel.component.crypto.DigitalSignatureConstants.SIGNATURE, i.e. "CamelDigitalSignature".
• crypto:verify will read in the contents of this header and do the verification calculation.

In order to correctly function, the sign and verify process needs a pair of keys to be shared, signing requiring a PrivateKey and verifying a PublicKey (or a Certificate containing one). Using the JCE it is very simple to generate these key pairs but it is usually most secure to use a KeyStore to house and share your keys. The DSL is very flexible about how keys are supplied and provides a number of mechanisms.

Note a crypto:sign endpoint is typically defined in one route and the complimentary crypto:verify in another, though for simplicity in the examples they appear one after the other. It goes without saying that both signing and verifying should be configured identically.

Options

Using

1) Raw keys

The most basic way to way to sign and verify an exchange is with a KeyPair as follows.{snippet:id=basic|lang=java|url=camel/trunk/components/camel-crypto/src/test/java/org/apache/camel/component/crypto/SignatureTests.java}The same can be achieved with the Spring XML Extensions using references to keys{snippet:id=basic|lang=xml|url=camel/trunk/components/camel-crypto/src/test/resources/org/apache/camel/component/crypto/SpringSignatureTests.xml}

2) KeyStores and Aliases.

The JCE provides a very versatile keystore concept for housing pairs of private keys and certificates, keeping them encrypted and password protected. They can be retrieved by applying an alias to the retrieval APIs. There are a number of ways to get keys and Certificates into a keystore, most often this is done with the external 'keytool' application. This is a good example of using keytool to create a KeyStore with a self signed Cert and Private key.

The examples use a Keystore with a key and cert aliased by 'bob'. The password for the keystore and the key is 'letmein'

The following shows how to use a Keystore via the Fluent builders, it also shows how to load and initialize the keystore.{snippet:id=keystore|lang=java|url=camel/trunk/components/camel-crypto/src/test/java/org/apache/camel/component/crypto/SignatureTests.java}Again in Spring a ref is used to lookup an actual keystore instance.{snippet:id=keystore|lang=xml|url=camel/trunk/components/camel-crypto/src/test/resources/org/apache/camel/component/crypto/SpringSignatureTests.xml}

3) Changing JCE Provider and Algorithm

Changing the Signature algorithm or the Security provider is a simple matter of specifying their names. You will need to also use Keys that are compatible with the algorithm you choose.{snippet:id=algorithm|lang=java|url=camel/trunk/components/camel-crypto/src/test/java/org/apache/camel/component/crypto/SignatureTests.java}{snippet:id=provider|lang=java|url=camel/trunk/components/camel-crypto/src/test/java/org/apache/camel/component/crypto/SignatureTests.java}or{snippet:id=algorithm|lang=xml|url=camel/trunk/components/camel-crypto/src/test/resources/org/apache/camel/component/crypto/SpringSignatureTests.xml}{snippet:id=provider|lang=xml|url=camel/trunk/components/camel-crypto/src/test/resources/org/apache/camel/component/crypto/SpringSignatureTests.xml}

4) Changing the Signature Message Header

It may be desirable to change the message header used to store the signature. A different header name can be specified in the route definition as follows{snippet:id=signature-header|lang=java|url=camel/trunk/components/camel-crypto/src/test/java/org/apache/camel/component/crypto/SignatureTests.java}or{snippet:id=signature-header|lang=xml|url=camel/trunk/components/camel-crypto/src/test/resources/org/apache/camel/component/crypto/SpringSignatureTests.xml}

5) Changing the buffersize

In case you need to update the size of the buffer...{snippet:id=buffersize|lang=java|url=camel/trunk/components/camel-crypto/src/test/java/org/apache/camel/component/crypto/SignatureTests.java}or{snippet:id=buffersize|lang=xml|url=camel/trunk/components/camel-crypto/src/test/resources/org/apache/camel/component/crypto/SpringSignatureTests.xml}

6) Supplying Keys dynamically.

When using a Recipient list or similar EIP the recipient of an exchange can vary dynamically. Using the same key across all recipients may be neither feasible nor desirable. It would be useful to be able to specify signature keys dynamically on a per-exchange basis. The exchange could then be dynamically enriched with the key of its target recipient prior to signing. To facilitate this the signature mechanisms allow for keys to be supplied dynamically via the message headers below

• Exchange.SIGNATURE_PRIVATE_KEY, "CamelSignaturePrivateKey"
• Exchange.SIGNATURE_PUBLIC_KEY_OR_CERT, "CamelSignaturePublicKeyOrCert"

{snippet:id=headerkey|lang=java|url=camel/trunk/components/camel-crypto/src/test/java/org/apache/camel/component/crypto/SignatureTests.java}or{snippet:id=headerkey|lang=xml|url=camel/trunk/components/camel-crypto/src/test/resources/org/apache/camel/component/crypto/SpringSignatureTests.xml}Even better would be to dynamically supply a keystore alias. Again the alias can be supplied in a message header

• Exchange.KEYSTORE_ALIAS, "CamelSignatureKeyStoreAlias"

{snippet:id=alias|lang=java|url=camel/trunk/components/camel-crypto/src/test/java/org/apache/camel/component/crypto/SignatureTests.java}or{snippet:id=alias|lang=xml|url=camel/trunk/components/camel-crypto/src/test/resources/org/apache/camel/component/crypto/SpringSignatureTests.xml}The header would be set as follows

Endpoint See Also

• Crypto Crypto is also available as a Data Format

CXF Component

The cxf: component provides integration with Apache CXF for connecting to JAX-WS services hosted in CXF.

Maven users will need to add the following dependency to their pom.xml for this component:

URI format

Where cxfEndpoint represents a bean ID that references a bean in the Spring bean registry. With this URI format, most of the endpoint details are specified in the bean definition.

Where someAddress specifies the CXF endpoint's address. With this URI format, most of the endpoint details are specified using options.

For either style above, you can append options to the URI as follows:

Options

The serviceName and portName are QNames, so if you provide them be sure to prefix them with their {namespace} as shown in the examples above.

The descriptions of the dataformats

You can determine the data format mode of an exchange by retrieving the exchange property, CamelCXFDataFormat. The exchange key constant is defined in org.apache.camel.component.cxf.CxfConstants.DATA_FORMAT_PROPERTY.

How to enable CXF's LoggingOutInterceptor in MESSAGE mode

CXF's LoggingOutInterceptor outputs outbound message that goes on the wire to logging system (Java Util Logging). Since the LoggingOutInterceptor is in PRE_STREAM phase (but PRE_STREAM phase is removed in MESSAGE mode), you have to configure LoggingOutInterceptor to be run during the WRITE phase. The following is an example.{snippet:id=enableLoggingOutInterceptor|lang=xml|url=camel/trunk/components/camel-cxf/src/test/resources/org/apache/camel/component/cxf/LoggingInterceptorInMessageModeTest-context.xml}

Description of relayHeaders option

There are in-band and out-of-band on-the-wire headers from the perspective of a JAXWS WSDL-first developer.

The in-band headers are headers that are explicitly defined as part of the WSDL binding contract for an endpoint such as SOAP headers.

The out-of-band headers are headers that are serialized over the wire, but are not explicitly part of the WSDL binding contract.

Headers relaying/filtering is bi-directional.

When a route has a CXF endpoint and the developer needs to have on-the-wire headers, such as SOAP headers, be relayed along the route to be consumed say by another JAXWS endpoint, then relayHeaders should be set to true, which is the default value.

Available only in POJO mode

The relayHeaders=true express an intent to relay the headers. The actual decision on whether a given header is relayed is delegated to a pluggable instance that implements the MessageHeadersRelay interface. A concrete implementation of MessageHeadersRelay will be consulted to decide if a header needs to be relayed or not. There is already an implementation of SoapMessageHeadersRelay which binds itself to well-known SOAP name spaces. Currently only out-of-band headers are filtered, and in-band headers will always be relayed when relayHeaders=true. If there is a header on the wire, whose name space is unknown to the runtime, then a fall back DefaultMessageHeadersRelay will be used, which simply allows all headers to be relayed.

The relayHeaders=false setting asserts that all headers in-band and out-of-band will be dropped.

You can plugin your own MessageHeadersRelay implementations overriding or adding additional ones to the list of relays. In order to override a preloaded relay instance just make sure that your MessageHeadersRelay implementation services the same name spaces as the one you looking to override. Also note, that the overriding relay has to service all of the name spaces as the one you looking to override, or else a runtime exception on route start up will be thrown as this would introduce an ambiguity in name spaces to relay instance mappings.

Take a look at the tests that show how you'd be able to relay/drop headers here:

https://svn.apache.org/repos/asf/camel/branches/camel-1.x/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/soap/headers/CxfMessageHeadersRelayTest.java

Changes since Release 2.0

• POJO and PAYLOAD modes are supported. In POJO mode, only out-of-band message headers are available for filtering as the in-band headers have been processed and removed from header list by CXF. The in-band headers are incorporated into the MessageContentList in POJO mode. The camel-cxf component does make any attempt to remove the in-band headers from the MessageContentList. If filtering of in-band headers is required, please use PAYLOAD mode or plug in a (pretty straightforward) CXF interceptor/JAXWS Handler to the CXF endpoint.

• The Message Header Relay mechanism has been merged into CxfHeaderFilterStrategy. The relayHeaders option, its semantics, and default value remain the same, but it is a property of CxfHeaderFilterStrategy.
  Here is an example of configuring it.{snippet:id=dropAllMessageHeadersStrategy|lang=xml|url=camel/trunk/components/camel-cxf/src/test/resources/org/apache/camel/component/cxf/soap/headers/CxfMessageHeadersRelayTest-context.xml}Then, your endpoint can reference the CxfHeaderFilterStrategy.{snippet:id=noRelayRoute|lang=xml|url=camel/trunk/components/camel-cxf/src/test/resources/org/apache/camel/component/cxf/soap/headers/CxfMessageHeadersRelayTest-context.xml}

• The MessageHeadersRelay interface has changed slightly and has been renamed to MessageHeaderFilter. It is a property of CxfHeaderFilterStrategy. Here is an example of configuring user defined Message Header Filters:{snippet:id=customMessageFilterStrategy|lang=xml|url=camel/trunk/components/camel-cxf/src/test/resources/org/apache/camel/component/cxf/soap/headers/CxfMessageHeadersRelayTest-context.xml}

• Other than relayHeaders, there are new properties that can be configured in CxfHeaderFilterStrategy.

  Name	Required	Description
  relayHeaders	No	All message headers will be processed by Message Header Filters Type: boolean Default: true
  relayAllMessageHeaders	No	All message headers will be propagated (without processing by Message Header Filters) Type: boolean Default: false
  allowFilterNamespaceClash	No	If two filters overlap in activation namespace, the property control how it should be handled. If the value is true, last one wins. If the value is false, it will throw an exception Type: boolean Default: false

  Configure the CXF endpoints with Spring

  You can configure the CXF endpoint with the Spring configuration file shown below, and you can also embed the endpoint into the camelContext tags. When you are invoking the service endpoint, you can set the operationName and operationNamespace headers to explicitly state which operation you are calling.

  xml<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:cxf="http://camel.apache.org/schema/cxf" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://camel.apache.org/schema/cxf http://camel.apache.org/schema/cxf/camel-cxf.xsd http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd"> <cxf:cxfEndpoint id="routerEndpoint" address="http://localhost:9003/CamelContext/RouterPort" serviceClass="org.apache.hello_world_soap_http.GreeterImpl"/> <cxf:cxfEndpoint id="serviceEndpoint" address="http://localhost:9000/SoapContext/SoapPort" wsdlURL="testutils/hello_world.wsdl" serviceClass="org.apache.hello_world_soap_http.Greeter" endpointName="s:SoapPort" serviceName="s:SOAPService" xmlns:s="http://apache.org/hello_world_soap_http" /> <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring"> <route> <from uri="cxf:bean:routerEndpoint" /> <to uri="cxf:bean:serviceEndpoint" /> </route> </camelContext> </beans>

  Be sure to include the JAX-WS schemaLocation attribute specified on the root beans element. This allows CXF to validate the file and is required. Also note the namespace declarations at the end of the <cxf:cxfEndpoint/> tag--these are required because the combined {namespace}localName syntax is presently not supported for this tag's attribute values.

  The cxf:cxfEndpoint element supports many additional attributes:

  Name	Value
  PortName	The endpoint name this service is implementing, it maps to the wsdl:port@name. In the format of ns:PORT_NAME where ns is a namespace prefix valid at this scope.
  serviceName	The service name this service is implementing, it maps to the wsdl:service@name. In the format of ns:SERVICE_NAME where ns is a namespace prefix valid at this scope.
  wsdlURL	The location of the WSDL. Can be on the classpath, file system, or be hosted remotely.
  bindingId	The bindingId for the service model to use.
  address	The service publish address.
  bus	The bus name that will be used in the JAX-WS endpoint.
  serviceClass	The class name of the SEI (Service Endpoint Interface) class which could have JSR181 annotation or not.

  It also supports many child elements:

  Name	Value
  cxf:inInterceptors	The incoming interceptors for this endpoint. A list of <bean> or <ref>.
  cxf:inFaultInterceptors	The incoming fault interceptors for this endpoint. A list of <bean> or <ref>.
  cxf:outInterceptors	The outgoing interceptors for this endpoint. A list of <bean> or <ref>.
  cxf:outFaultInterceptors	The outgoing fault interceptors for this endpoint. A list of <bean> or <ref>.
  cxf:properties	A properties map which should be supplied to the JAX-WS endpoint. See below.
  cxf:handlers	A JAX-WS handler list which should be supplied to the JAX-WS endpoint. See below.
  cxf:dataBinding	You can specify the which DataBinding will be use in the endpoint. This can be supplied using the Spring <bean class="MyDataBinding"/> syntax.
  cxf:binding	You can specify the BindingFactory for this endpoint to use. This can be supplied using the Spring <bean class="MyBindingFactory"/> syntax.
  cxf:features	The features that hold the interceptors for this endpoint. A list of {{<bean>}}s or {{<ref>}}s
  cxf:schemaLocations	The schema locations for endpoint to use. A list of {{<schemaLocation>}}s
  cxf:serviceFactory	The service factory for this endpoint to use. This can be supplied using the Spring <bean class="MyServiceFactory"/> syntax

   

You can find more advanced examples that show how to provide interceptors, properties and handlers on the CXF JAX-WS Configuration page.

NOTE
You can use cxf:properties to set the camel-cxf endpoint's dataFormat and setDefaultBus properties from spring configuration file.

Configuring the CXF Endpoints with Apache Aries Blueprint.

Since camel 2.8 there is support for utilizing aries blueprint dependency injection for your CXF endpoints.
The schema utilized is very similar to the spring schema so the transition is fairly transparent.

Example

Currently the endpoint element is the first supported CXF namespacehandler.

You can also use the bean references just as in spring

How to make the camel-cxf component use log4j instead of java.util.logging

CXF's default logger is java.util.logging. If you want to change it to log4j, proceed as follows. Create a file, in the classpath, named META-INF/cxf/org.apache.cxf.logger. This file should contain the fully-qualified name of the class, org.apache.cxf.common.logging.Log4jLogger, with no comments, on a single line.

How to let camel-cxf response message with xml start document

If you are using some SOAP client such as PHP, you will get this kind of error, because CXF doesn't add the XML start document "<?xml version="1.0" encoding="utf-8"?>"

To resolved this issue, you just need to tell StaxOutInterceptor to write the XML start document for you.{snippet:id=example|lang=xml|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/WriteXmlDeclarationInterceptor.java}You can add a customer interceptor like this and configure it into you camel-cxf endpont{snippet:id=example|lang=xml|url=camel/trunk/components/camel-cxf/src/test/resources/org/apache/camel/component/cxf/GreeterEndpointsRouterContext.xml}Or adding a message header for it like this if you are using Camel 2.4.

How to override the CXF producer address from message header

The camel-cxf producer supports to override the services address by setting the message with the key of "CamelDestinationOverrideUrl".

How to consume a message from a camel-cxf endpoint in POJO data format

The camel-cxf endpoint consumer POJO data format is based on the cxf invoker, so the message header has a property with the name of CxfConstants.OPERATION_NAME and the message body is a list of the SEI method parameters.{snippet:id=personProcessor|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/wsdl_first/PersonProcessor.java}

How to prepare the message for the camel-cxf endpoint in POJO data format

The camel-cxf endpoint producer is based on the cxf client API. First you need to specify the operation name in the message header, then add the method parameters to a list, and initialize the message with this parameter list. The response message's body is a messageContentsList, you can get the result from that list.

If you don't specify the operation name in the message header, CxfProducer will try to use the defaultOperationName from CxfEndpoint, if there is no defaultOperationName set on CxfEndpoint, it will pickup the first operationName from the Operation list.

If you want to get the object array from the message body, you can get the body using message.getbody(Object[].class), as follows:{snippet:id=sending|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/CxfProducerRouterTest.java}

How to deal with the message for a camel-cxf endpoint in PAYLOAD data format

PAYLOAD means that you process the payload message from the SOAP envelope. You can use the Header.HEADER_LIST as the key to set or get the SOAP headers and use the List<Element> to set or get SOAP body elements.
Message.getBody() will return an org.apache.camel.component.cxf.CxfPayload object, which has getters for SOAP message headers and Body elements. This change enables decoupling the native CXF message from the Camel message.{snippet:id=payload|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/CxfConsumerPayloadTest.java}

How to get and set SOAP headers in POJO mode

POJO means that the data format is a "list of Java objects" when the Camel-cxf endpoint produces or consumes Camel exchanges. Even though Camel expose message body as POJOs in this mode, Camel-cxf still provides access to read and write SOAP headers. However, since CXF interceptors remove in-band SOAP headers from Header list after they have been processed, only out-of-band SOAP headers are available to Camel-cxf in POJO mode.

The following example illustrate how to get/set SOAP headers. Suppose we have a route that forwards from one Camel-cxf endpoint to another. That is, SOAP Client -> Camel -> CXF service. We can attach two processors to obtain/insert SOAP headers at (1) before request goes out to the CXF service and (2) before response comes back to the SOAP Client. Processor (1) and (2) in this example are InsertRequestOutHeaderProcessor and InsertResponseOutHeaderProcessor. Our route looks like this:{snippet:id=processSoapHeaderRoute|lang=xml|url=camel/trunk/components/camel-cxf/src/test/resources/org/apache/camel/component/cxf/soap/headers/CxfMessageHeadersRelayTest-context.xml}SOAP headers are propagated to and from Camel Message headers. The Camel message header name is "org.apache.cxf.headers.Header.list" which is a constant defined in CXF (org.apache.cxf.headers.Header.HEADER_LIST). The header value is a List of CXF SoapHeader objects (org.apache.cxf.binding.soap.SoapHeader). The following snippet is the InsertResponseOutHeaderProcessor (that insert a new SOAP header in the response message). The way to access SOAP headers in both InsertResponseOutHeaderProcessor and InsertRequestOutHeaderProcessor are actually the same. The only difference between the two processors is setting the direction of the inserted SOAP header.{snippet:id=InsertResponseOutHeaderProcessor|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/soap/headers/CxfMessageHeadersRelayTest.java}

How to get and set SOAP headers in PAYLOAD mode

We've already shown how to access SOAP message (CxfPayload object) in PAYLOAD mode (See "How to deal with the message for a camel-cxf endpoint in PAYLOAD data format").

Once you obtain a CxfPayload object, you can invoke the CxfPayload.getHeaders() method that returns a List of DOM Elements (SOAP headers).{snippet:id=payload|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/CxfPayLoadSoapHeaderTest.java}Since Camel 2.16.0, you can also use the same way as described in sub-chapter "How to get and set SOAP headers in POJO mode" to set or get the SOAP headers. So, you can use now the header "org.apache.cxf.headers.Header.list" to get and set a list of SOAP headers.This does also mean that if you have a route that forwards from one Camel-cxf endpoint to another (SOAP Client -> Camel -> CXF service), now also the SOAP headers sent by the SOAP client are forwarded to the CXF service. If you do not want that these headers are forwarded you have to remove them in the Camel header "org.apache.cxf.headers.Header.list".

SOAP headers are not available in MESSAGE mode

SOAP headers are not available in MESSAGE mode as SOAP processing is skipped.

How to throw a SOAP Fault from Camel

If you are using a camel-cxf endpoint to consume the SOAP request, you may need to throw the SOAP Fault from the camel context.
Basically, you can use the throwFault DSL to do that; it works for POJO, PAYLOAD and MESSAGE data format.
You can define the soap fault like this{snippet:id=FaultDefine|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/CxfCustomizedExceptionTest.java}Then throw it as you like{snippet:id=ThrowFault|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/CxfCustomizedExceptionTest.java}If your CXF endpoint is working in the MESSAGE data format, you could set the the SOAP Fault message in the message body and set the response code in the message header.{snippet:id=MessageStreamFault|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/CxfMessageStreamExceptionTest.java}Same for using POJO data format. You can set the SOAPFault on the out body and also indicate it's a fault by calling Message.setFault(true):{snippet:id=onException|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/CxfMessageStreamExceptionTest.java}

How to propagate a camel-cxf endpoint's request and response context

cxf client API provides a way to invoke the operation with request and response context. If you are using a camel-cxf endpoint producer to invoke the outside web service, you can set the request context and get response context with the following code:

Attachment Support

POJO Mode: Both SOAP with Attachment and MTOM are supported (see example in Payload Mode for enabling MTOM).  However, SOAP with Attachment is not tested.  Since attachments are marshalled and unmarshalled into POJOs, users typically do not need to deal with the attachment themself.  Attachments are propagated to Camel message's attachments if the MTOM is not enabled, since 2.12.3.  So, it is possible to retreive attachments by Camel Message API

.

Payload Mode: MTOM is supported since 2.1. Attachments can be retrieved by Camel Message APIs mentioned above. SOAP with Attachment (SwA) is supported and attachments can be retrieved since 2.5. SwA is the default (same as setting the CXF endpoint property "mtom-enabled" to false). 

To enable MTOM, set the CXF endpoint property "mtom-enabled" to true. (I believe you can only do it with Spring.){snippet:id=enableMtom|lang=xml|url=camel/trunk/components/camel-cxf/src/test/resources/org/apache/camel/component/cxf/mtom/CxfMtomRouterPayloadModeTest-context.xml}You can produce a Camel message with attachment to send to a CXF endpoint in Payload mode.{snippet:id=producer|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/mtom/CxfMtomProducerPayloadModeTest.java}You can also consume a Camel message received from a CXF endpoint in Payload mode.{snippet:id=consumer|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/mtom/CxfMtomConsumerPayloadModeTest.java}Message Mode: Attachments are not supported as it does not process the message at all.

CXF_MESSAGE Mode: MTOM is supported, and Attachments can be retrieved by Camel Message APIs mentioned above. Note that when receiving a multipart (i.e. MTOM) message the default SOAPMessage to String converter will provide the complete multipart payload on the body. If you require just the SOAP XML as a String, you can set the message body with message.getSOAPPart(), and Camel convert can do the rest of work for you.

Streaming Support in PAYLOAD mode

In 2.8.2, the camel-cxf component now supports streaming of incoming messages when using PAYLOAD mode. Previously, the incoming messages would have been completely DOM parsed. For large messages, this is time consuming and uses a significant amount of memory. Starting in 2.8.2, the incoming messages can remain as a javax.xml.transform.Source while being routed and, if nothing modifies the payload, can then be directly streamed out to the target destination. For common "simple proxy" use cases (example: from("cxf:...").to("cxf:...")), this can provide very significant performance increases as well as significantly lowered memory requirements.

However, there are cases where streaming may not be appropriate or desired. Due to the streaming nature, invalid incoming XML may not be caught until later in the processing chain. Also, certain actions may require the message to be DOM parsed anyway (like WS-Security or message tracing and such) in which case the advantages of the streaming is limited. At this point, there are two ways to control the streaming:

• Endpoint property: you can add "allowStreaming=false" as an endpoint property to turn the streaming on/off.

• Component property: the CxfComponent object also has an allowStreaming property that can set the default for endpoints created from that component.

Global system property: you can add a system property of "org.apache.camel.component.cxf.streaming" to "false" to turn if off. That sets the global default, but setting the endpoint property above will override this value for that endpoint.

Using the generic CXF Dispatch mode

From 2.8.0, the camel-cxf component supports the generic CXF dispatch mode that can transport messages of arbitrary structures (i.e., not bound to a specific XML schema). To use this mode, you simply omit specifying the wsdlURL and serviceClass attributes of the CXF endpoint.

It is noted that the default CXF dispatch client does not send a specific SOAPAction header. Therefore, when the target service requires a specific SOAPAction value, it is supplied in the Camel header using the key SOAPAction (case-insensitive).

Endpoint See Also

CXF Bean Component

The cxfbean: component allows other Camel endpoints to send exchange and invoke Web service bean objects. Currently, it only supports JAX-RS and JAX-WS (new to Camel 2.1) annotated service beans.

Maven users need to add the following dependency to their pom.xml to use the CXF Bean Component:

URI format

Where serviceBeanRef is a registry key to look up the service bean object. If serviceBeanRef references a List object, elements of the List are the service bean objects accepted by the endpoint.

Options

Headers

A Working Sample

This sample shows how to create a route that starts an embedded Jetty HTTP server. The route sends requests to a CXF Bean and invokes a JAX-RS annotated service.

First, create a route as follows: The from endpoint is a Jetty HTTP endpoint that is listening on port 9000. Notice that the matchOnUriPrefix option must be set to true because the RESTful request URI will not exactly match the endpoint's URI http:­//localhost:9000.

The to endpoint is a CXF Bean with bean name customerServiceBean. The name will be looked up from the registry. Next, we make sure our service bean is available in Spring registry. We create a bean definition in the Spring configuration. In this example, we create a List of service beans (of one element). We could have created just a single bean without a List.

That's it. Once the route is started, the web service is ready for business. A HTTP client can make a request and receive response.

CXFRS Component

The cxfrs: component provides integration with Apache CXF for connecting to JAX-RS 1.1 and 2.0 services hosted in CXF.

Maven users will need to add the following dependency to their pom.xml for this component:

URI format

Where address represents the CXF endpoint's address

Where rsEndpoint represents the spring bean's name which presents the CXFRS client or server

For either style above, you can append options to the URI as follows:

Options

You can also configure the CXF REST endpoint through the spring configuration. Since there are lots of difference between the CXF REST client and CXF REST Server, we provide different configuration for them.
Please check out the schema file and CXF JAX-RS documentation for more information.

How to configure the REST endpoint in Camel

In camel-cxf schema file, there are two elements for the REST endpoint definition. cxf:rsServer for REST consumer, cxf:rsClient for REST producer.
You can find a Camel REST service route configuration example here.{snippet:id=cxfRsExample|lang=xml|url=camel/trunk/components/camel-cxf/src/test/resources/org/apache/camel/component/cxf/jaxrs/CxfRsSpringRouter.xml}

How to override the CXF producer address from message header

The camel-cxfrs producer supports to override the services address by setting the message with the key of "CamelDestinationOverrideUrl".

Consuming a REST Request - Simple Binding Style

Available as of Camel 2.11

The Default binding style is rather low-level, requiring the user to manually process the MessageContentsList object coming into the route. Thus, it tightly couples the route logic with the method signature and parameter indices of the JAX-RS operation. Somewhat inelegant, difficult and error-prone.

In contrast, the SimpleConsumer binding style performs the following mappings, in order to make the request data more accessible to you within the Camel Message:

• JAX-RS Parameters (@HeaderParam, @QueryParam, etc.) are injected as IN message headers. The header name matches the value of the annotation.
• The request entity (POJO or other type) becomes the IN message body. If a single entity cannot be identified in the JAX-RS method signature, it falls back to the original MessageContentsList.
• Binary @Multipart body parts become IN message attachments, supporting DataHandler, InputStream, DataSource and CXF's Attachment class.
• Non-binary @Multipart body parts are mapped as IN message headers. The header name matches the Body Part name.

Additionally, the following rules apply to the Response mapping:

• If the message body type is different to javax.ws.rs.core.Response (user-built response), a new Response is created and the message body is set as the entity (so long it's not null). The response status code is taken from the Exchange.HTTP_RESPONSE_CODE header, or defaults to 200 OK if not present.
• If the message body type is equal to javax.ws.rs.core.Response, it means that the user has built a custom response, and therefore it is respected and it becomes the final response.
• In all cases, Camel headers permitted by custom or default HeaderFilterStrategy are added to the HTTP response.

Enabling the Simple Binding Style

This binding style can be activated by setting the bindingStyle parameter in the consumer endpoint to value SimpleConsumer:

Examples of request binding with different method signatures

Below is a list of method signatures along with the expected result from the Simple binding.

public Response doAction(BusinessObject request);
Request payload is placed in IN message body, replacing the original MessageContentsList.

public Response doAction(BusinessObject request, @HeaderParam("abcd") String abcd, @QueryParam("defg") String defg);
Request payload placed in IN message body, replacing the original MessageContentsList. Both request params mapped as IN message headers with names abcd and defg.

public Response doAction(@HeaderParam("abcd") String abcd, @QueryParam("defg") String defg);
Both request params mapped as IN message headers with names abcd and defg. The original MessageContentsList is preserved, even though it only contains the 2 parameters.

public Response doAction(@Multipart(value="body1") BusinessObject request, @Multipart(value="body2") BusinessObject request2);
The first parameter is transferred as a header with name body1, and the second one is mapped as header body2. The original MessageContentsList is preserved as the IN message body.

public Response doAction(InputStream abcd);
The InputStream is unwrapped from the MessageContentsList and preserved as the IN message body.

public Response doAction(DataHandler abcd);
The DataHandler is unwrapped from the MessageContentsList and preserved as the IN message body.

More examples of the Simple Binding Style

Given a JAX-RS resource class with this method:

Serviced by the following route:

The following HTTP request with XML payload (given that the Customer DTO is JAXB-annotated):

Will print the message:

For more examples on how to process requests and write responses can be found here.

Consuming a REST Request - Default Binding Style

The CXF JAXRS front end implements the JAX-RS (JSR-311) API, so we can export the resources classes as a REST service. And we leverage the CXF Invoker API to turn a REST request into a normal Java object method invocation.
Unlike the Camel Restlet component, you don't need to specify the URI template within your endpoint, CXF takes care of the REST request URI to resource class method mapping according to the JSR-311 specification. All you need to do in Camel is delegate this method request to a right processor or endpoint.

Here is an example of a CXFRS route...{snippet:id=example|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/jaxrs/CxfRsConsumerTest.java}And the corresponding resource class used to configure the endpoint...

{snippet:id=example|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/jaxrs/testbean/CustomerServiceResource.java}

How to invoke the REST service through camel-cxfrs producer

The CXF JAXRS front end implements a proxy-based client API, with this API you can invoke the remote REST service through a proxy. The camel-cxfrs producer is based on this proxy API.
You just need to specify the operation name in the message header and prepare the parameter in the message body, the camel-cxfrs producer will generate right REST request for you.

Here is an example:{snippet:id=ProxyExample|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/jaxrs/CxfRsProducerTest.java}The CXF JAXRS front end also provides a http centric client API. You can also invoke this API from camel-cxfrs producer. You need to specify the HTTP_PATH and the HTTP_METHOD and let the producer use the http centric client API by using the URI option httpClientAPI or by setting the message header CxfConstants.CAMEL_CXF_RS_USING_HTTP_API. You can turn the response object to the type class specified with the message header CxfConstants.CAMEL_CXF_RS_RESPONSE_CLASS.{snippet:id=HttpExample|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/jaxrs/CxfRsProducerTest.java}From Camel 2.1, we also support to specify the query parameters from cxfrs URI for the CXFRS http centric client.{snippet:id=QueryExample|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/jaxrs/CxfRsProducerTest.java}To support the Dynamical routing, you can override the URI's query parameters by using the CxfConstants.CAMEL_CXF_RS_QUERY_MAP header to set the parameter map for it.{snippet:id=QueryMapExample|lang=java|url=camel/trunk/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/jaxrs/CxfRsProducerTest.java}

DataSet Component

The DataSet component provides a mechanism to easily perform load & soak testing of your system. It works by allowing you to create DataSet instances both as a source of messages and as a way to assert that the data set is received.

Camel will use the throughput logger when sending dataset's.

URI format

dataset:name[?options]

Where name is used to find the DataSet instance in the Registry

Camel ships with a support implementation of org.apache.camel.component.dataset.DataSet, the org.apache.camel.component.dataset.DataSetSupport class, that can be used as a base for implementing your own DataSet.

Camel also ships with some implementations that can be used for testing:  

• org.apache.camel.component.dataset.SimpleDataSet
• org.apache.camel.component.dataset.ListDataSet
  
• org.apache.camel.component.dataset.FileDataSet
  

all of which extend DataSetSupport.

Options

You can append query options to the URI in the following format: ?option=value&option=value&...

Configuring DataSet

Camel will lookup in the Registry for a bean implementing the DataSet interface. So you can register your own DataSet as:

<bean id="myDataSet" class="com.mycompany.MyDataSet">
  <property name="size" value="100"/>
</bean>

Example

For example, to test that a set of messages are sent to a queue and then consumed from the queue without losing any messages:

// Send the dataset to a queue
from("dataset:foo")
  .to("activemq:SomeQueue");

// Now lets test that the messages are consumed correctly
from("activemq:SomeQueue")
  .to("dataset:foo");

The above would look in the Registry to find the foo DataSet instance which is used to create the messages. Then you create a DataSet implementation, such as using the SimpleDataSet as described below, configuring things like how big the data set is and what the messages look like etc.  

DataSetSupport (abstract class)

The DataSetSupport abstract class is a nice starting point for new DataSets, and provides some useful features to derived classes.

Properties on DataSetSupport

SimpleDataSet

The SimpleDataSet extends DataSetSupport, and adds a default body.

Additional Properties on SimpleDataSet

ListDataSet (Camel 2.17)

The ListDataSet extends DataSetSupport, and adds a list of default bodies.

Additional Properties on ListDataSet

FileDataSet (Camel 2.17)

The SimpleDataSet extends ListDataSet, and adds support for loading the bodies from a file.

Additional Properties on FileDataSet

• Spring Testing

Db4o Component

Available as of Camel 2.5

The db4o: component allows you to work with db4o NoSQL database. The camel-db4o library is provided by the Camel Extra project which hosts all *GPL related components for Camel.

Sending to the endpoint

Sending POJO object to the db4o endpoint adds and saves object into the database. The body of the message is assumed to be a POJO that has to be saved into the db40 database store.

Consuming from the endpoint

Consuming messages removes (or updates) POJO objects in the database. This allows you to use a Db4o datastore as a logical queue; consumers take messages from the queue and then delete them to logically remove them from the queue.

If you do not wish to delete the object when it has been processed, you can specify consumeDelete=false on the URI. This will result in the POJO being processed each poll.

URI format

db4o:className[?options]

You can append query options to the URI in the following format, ?option=value&option=value&...

Options

Direct Component

The direct: component provides direct, synchronous invocation of any consumers when a producer sends a message exchange. This endpoint can be used to connect existing routes in the same camel context.

URI format

direct:someName[?options]

Where someName can be any string that uniquely identifies the endpoint.

Options

You can append query options to the URI in the following format: ?option=value&option=value&...

Samples

In the route below we use the direct component to link the two routes together:

from("activemq:queue:order.in")
    .to("bean:orderServer?method=validate")
    .to("direct:processOrder?block=true&timeout=5000");

from("direct:processOrder")
    .to("bean:orderService?method=process")
    .to("activemq:queue:order.out");

And the sample using spring DSL:

   <route>
     <from uri="activemq:queue:order.in"/>
     <to uri="bean:orderService?method=validate"/>
     <to uri="direct:processOrder?failIfNoConsumers=false"/>
  </route>

  <route>
     <from uri="direct:processOrder"/>
     <to uri="bean:orderService?method=process"/>
     <to uri="activemq:queue:order.out"/>
  </route>    

See also samples from the SEDA component, how they can be used together.

• SEDA
• VM

DNS

Available as of Camel 2.7

This is an additional component for Camel to run DNS queries, using DNSJava. The component is a thin layer on top of DNSJava.
The component offers the following operations:

• ip, to resolve a domain by its ip
• lookup, to lookup information about the domain
• dig, to run DNS queries

Maven users will need to add the following dependency to their pom.xml for this component:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-dns</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

URI format

The URI scheme for a DNS component is as follows

dns://operation[?options]

This component only supports producers.

Options

None.

Headers

Examples

IP lookup

        <route id="IPCheck">
            <from uri="direct:start"/>
            <to uri="dns:ip"/>
        </route>

This looks up a domain's IP. For example, www.example.com resolves to 192.0.32.10.
The IP address to lookup must be provided in the header with key "dns.domain".

DNS lookup

        <route id="IPCheck">
            <from uri="direct:start"/>
            <to uri="dns:lookup"/>
        </route>

This returns a set of DNS records associated with a domain.
The name to lookup must be provided in the header with key "dns.name".

DNS Dig

Dig is a Unix command-line utility to run DNS queries.

        <route id="IPCheck">
            <from uri="direct:start"/>
            <to uri="dns:dig"/>
        </route>

The query must be provided in the header with key "dns.query".

EJB Component

Available as of Camel 2.4

The ejb: component binds EJBs to Camel message exchanges.

Maven users will need to add the following dependency to their pom.xml for this component:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-ejb</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

URI format

ejb:ejbName[?options]

Where ejbName can be any string which is used to look up the EJB in the Application Server JNDI Registry

Options

You can append query options to the URI in the following format, ?option=value&option=value&...

The EJB component extends the Bean component in which most of the details from the Bean component applies to this component as well.

Bean Binding

How bean methods to be invoked are chosen (if they are not specified explicitly through the method parameter) and how parameter values are constructed from the Message are all defined by the Bean Binding mechanism which is used throughout all of the various Bean Integration mechanisms in Camel.

Examples

In the following examples we use the Greater EJB which is defined as follows:

And the implementation

Using Java DSL

In this example we want to invoke the hello method on the EJB. Since this example is based on an unit test using Apache OpenEJB we have to set a JndiContext on the EJB component with the OpenEJB settings.

Then we are ready to use the EJB in the Camel route:

Using Spring XML

And this is the same example using Spring XML instead:

Again since this is based on an unit test we need to setup the EJB component:

Before we are ready to use EJB in the Camel routes:

• Bean
• Bean Binding
• Bean Integration

Esper

The Esper component supports the Esper Library for Event Stream Processing. The camel-esper library is provided by the Camel Extra project which hosts all *GPL related components for Camel.

URI format

esper:name[?options]

When consuming from an Esper endpoint you must specify a pattern or eql statement to query the event stream.

Pattern example:

from("esper://cheese?pattern=every event=MyEvent(bar=5)")
  .to("activemq:Foo");

EQL example:

from("esper://esper-dom?eql=insert into DomStream select * from org.w3c.dom.Document")
  .to("log://esper-dom?level=INFO");
from("esper://esper-dom?eql=select childNodes from DomStream")
  .to("mock:results");

Options

You can append query options to the URI in the following format, ?option=value&option=value&...

EsperMessage

From Camel 2.12 onwards the esper consumer stores new and old events in the org.apacheextras.camel.component.esper.EsperMessage message as the input Message on the Exchange. You can get access to the esper event beans from java code with:

  EventBean newEvent = exchange.getIn(EsperMessage.class).getNewEvent();
  EventBean oldEvent = exchange.getIn(EsperMessage.class).getOldEvent();

By default if you get the body of org.apacheextras.camel.component.esper.EsperMessage it returns the new EventBean as in previous versions.

Demo

There is a demo which shows how to work with ActiveMQ, Camel and Esper in the Camel Extra project

• Esper Camel Demo

File Component

The File component provides access to file systems, allowing files to be processed by any other Camel Components or messages from other components to be saved to disk.

URI format

or

Where directoryName represents the underlying file directory.

You can append query options to the URI in the following format, ?option=value&option=value&...

URI Options

Common

Consumer

Default behavior for file consumer

• By default the file is not locked for the duration of the processing.

• After the route has completed, files are moved into the .camel subdirectory, so that they appear to be deleted.

• The File Consumer will always skip any file whose name starts with a dot, such as ., .camel, .m2 or .groovy.

• Only files (not directories) are matched for valid filename, if options such as: include or exclude are used.

Producer

Default behavior for file producer

• By default it will override any existing file, if one exist with the same name.

Move and Delete operations

Any move or delete operations is executed after (post command) the routing has completed; so during processing of the Exchange the file is still located in the inbox folder.

Lets illustrate this with an example:

When a file is dropped in the inbox folder, the file consumer notices this and creates a new FileExchange that is routed to the handleOrder bean. The bean then processes the File object. At this point in time the file is still located in the inbox folder. After the bean completes, and thus the route is completed, the file consumer will perform the move operation and move the file to the .done sub-folder.

The move and the preMove options are considered as a directory name though if you use an expression such as File Language, or Simple then the result of the expression evaluation is the file name to be used e.g., if you set

then that's using the File Language which we use return the file name to be used), which can be either relative or absolute. If relative, the directory is created as a sub-folder from within the folder where the file was consumed.

By default, Camel will move consumed files to the .camel sub-folder relative to the directory where the file was consumed.

If you want to delete the file after processing, the route should be:

We have introduced a pre move operation to move files before they are processed. This allows you to mark which files have been scanned as they are moved to this sub folder before being processed.

You can combine the pre move and the regular move:

So in this situation, the file is in the inprogress folder when being processed and after it's processed, it's moved to the .done folder.

Fine Grained Control Using The move and preMove Options

The move and preMove options are Expression-based, so we have the full power of the File Language to do advanced configuration of the directory and name pattern.
Camel will, in fact, internally convert the directory name you enter into a File Language expression. So when we enter move=.done Camel will convert this into: ${file:parent}/.done/${file:onlyname}. This is only done if Camel detects that you have not provided a ${} in the option value yourself. So when you enter a ${} Camel will not convert it and thus you have the full power.

So if we want to move the file into a backup folder with today's date as the pattern, we can do:

About moveFailed

The moveFailed option allows you to move files that could not be processed successfully to another location such as a error folder of your choice. For example to move the files in an error folder with a timestamp you can use moveFailed=/error/${file:name.noext}-${date:now:yyyyMMddHHmmssSSS}.${file:ext}.

See more examples at File Language

Message Headers

The following headers are supported by this component:

File producer only

File consumer only

Batch Consumer

This component implements the Batch Consumer.

Exchange Properties, file consumer only

As the file consumer implements the BatchConsumer it supports batching the files it polls. By batching we mean that Camel will add the following additional properties to the Exchange, so you know the number of files polled, the current index, and whether the batch is already completed.

This allows you for instance to know how many files exist in this batch and for instance let the Aggregator2 aggregate this number of files.

Using charset

Available as of Camel 2.9.3
The charset option allows for configuring an encoding of the files on both the consumer and producer endpoints. For example if you read utf-8 files, and want to convert the files to iso-8859-1, you can do:

You can also use the convertBodyTo in the route. In the example below we have still input files in utf-8 format, but we want to convert the file content to a byte array in iso-8859-1 format. And then let a bean process the data. Before writing the content to the outbox folder using the current charset.

If you omit the charset on the consumer endpoint, then Camel does not know the charset of the file, and would by default use "UTF-8". However you can configure a JVM system property to override and use a different default encoding with the key org.apache.camel.default.charset.

In the example below this could be a problem if the files is not in UTF-8 encoding, which would be the default encoding for read the files.
In this example when writing the files, the content has already been converted to a byte array, and thus would write the content directly as is (without any further encodings).

You can also override and control the encoding dynamic when writing files, by setting a property on the exchange with the key Exchange.CHARSET_NAME. For example in the route below we set the property with a value from a message header.

We suggest to keep things simpler, so if you pickup files with the same encoding, and want to write the files in a specific encoding, then favor to use the charset option on the endpoints.

Notice that if you have explicit configured a charset option on the endpoint, then that configuration is used, regardless of the Exchange.CHARSET_NAME property.

If you have some issues then you can enable DEBUG logging on org.apache.camel.component.file, and Camel logs when it reads/write a file using a specific charset.
For example the route below will log the following:

And the logs:

Common gotchas with folder and filenames

When Camel is producing files (writing files) there are a few gotchas affecting how to set a filename of your choice. By default, Camel will use the message ID as the filename, and since the message ID is normally a unique generated ID, you will end up with filenames such as: ID-MACHINENAME-2443-1211718892437-1-0. If such a filename is not desired, then you must provide a filename in the CamelFileName message header. The constant, Exchange.FILE_NAME, can also be used.

The sample code below produces files using the message ID as the filename:

To use report.txt as the filename you have to do:

... the same as above, but with CamelFileName:

And a syntax where we set the filename on the endpoint with the fileName URI option.

Filename Expression

Filename can be set either using the expression option or as a string-based File Language expression in the CamelFileName header. See the File Language for syntax and samples.

Consuming files from folders where others drop files directly

Beware if you consume files from a folder where other applications write files to directly. Take a look at the different readLock options to see what suits your use cases. The best approach is however to write to another folder and after the write move the file in the drop folder. However if you write files directly to the drop folder then the option changed could better detect whether a file is currently being written/copied as it uses a file changed algorithm to see whether the file size / modification changes over a period of time. The other readLock options rely on Java File API that sadly is not always very good at detecting this. You may also want to look at the doneFileName option, which uses a marker file (done file) to signal when a file is done and ready to be consumed.

Using 'done' Files

Available as of Camel 2.6

See also section writing done files below.

If you want only to consume files when a done file exists, then you can use the doneFileName option on the endpoint.

Will only consume files from the bar folder, if a done file exists in the same directory as the target files. Camel will automatically delete the done file when it's done consuming the files. From Camel 2.9.3 onward Camel will not automatically delete the done file if noop=true is configured.

However it is more common to have one done file per target file. This means there is a 1:1 correlation. To do this you must use dynamic placeholders in the doneFileName option. Currently Camel supports the following two dynamic tokens: file:name and file:name.noext which must be enclosed in ${}. The consumer only supports the static part of the done file name as either prefix or suffix (not both).

In this example only files will be polled if there exists a done file with the name file name.done. For example

• hello.txt - is the file to be consumed

• hello.txt.done - is the associated done file

You can also use a prefix for the done file, such as:

• hello.txt - is the file to be consumed

• ready-hello.txt - is the associated done file

Writing 'done' Files

Available as of Camel 2.6

After you have written a file you may want to write an additional done file as a kind of marker, to indicate to others that the file is finished and has been written. To do that you can use the doneFileName option on the file producer endpoint.

Will simply create a file named done in the same directory as the target file.

However it is more common to have one done file per target file. This means there is a 1:1 correlation. To do this you must use dynamic placeholders in the doneFileName option. Currently Camel supports the following two dynamic tokens: file:name and file:name.noext which must be enclosed in ${}.

Will for example create a file named done-foo.txt if the target file was foo.txt in the same directory as the target file.

Will for example create a file named foo.txt.done if the target file was foo.txt in the same directory as the target file.

Will for example create a file named foo.done if the target file was foo.txt in the same directory as the target file.

Examples

Read from a directory and write to another directory

Read from a directory and write to another directory using a overrule dynamic name

Listen on a directory and create a message for each file dropped there. Copy the contents to the outputdir and delete the file in the inputdir.

Reading recursively from a directory and writing to another

Listen on a directory and create a message for each file dropped there. Copy the contents to the outputdir and delete the file in the inputdir. Will scan recursively into sub-directories. Will lay out the files in the same directory structure in the outputdir as the inputdir, including any sub-directories.

Will result in the following output layout:

Using flatten

If you want to store the files in the outputdir directory in the same directory, disregarding the source directory layout e.g., to flatten out the path, you just add the flatten=true option on the file producer side:

Will result in the following output layout:

Reading from a directory and the default move operation

Camel will by default move any processed file into a .camel subdirectory in the directory the file was consumed from.

Affects the layout as follows:
before

after

Read from a directory and process the message in java

The body will be a File object that points to the file that was just dropped into the inputdir directory.

Writing to files

Camel is of course also able to write files, i.e. produce files. In the sample below we receive some reports on the SEDA queue that we process before they are being written to a directory.{snippet:id=e1|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/component/file/ToFileRouteTest.java}

Write to subdirectory using Exchange.FILE_NAME

Using a single route, it is possible to write a file to any number of subdirectories. If you have a route setup as such:

You can have myBean set the header Exchange.FILE_NAME to values such as:

This allows you to have a single route to write files to multiple destinations.

Writing file through the temporary directory relative to the final destination

Sometime you need to temporarily write the files to some directory relative to the destination directory. Such situation usually happens when some external process with limited filtering capabilities is reading from the directory you are writing to. In the example below files will be written to the  /var/myapp/filesInProgress directory and after data transfer is done, they will be atomically moved to the /var/myapp/finalDirectory directory.

Using Expressions for Filenames

In this sample we want to move consumed files to a backup folder using today's date as a sub-folder name:

See File Language for more samples.

Avoiding reading the same file more than once (idempotent consumer)

Camel supports Idempotent Consumer directly within the component so it will skip already processed files. This feature can be enabled by setting the idempotent=true option.

Camel uses the absolute file name as the idempotent key, to detect duplicate files. From Camel 2.11 onward you can customize this key by using an expression in the idempotentKey option. For example to use both the name and the file size as the key

By default Camel uses a in memory based store for keeping track of consumed files, it uses a least recently used cache holding up to 1000 entries. You can plugin your own implementation of this store by using the idempotentRepository option using the # sign in the value to indicate it's a referring to a bean in the Registry with the specified id.

Camel will log at DEBUG level if it skips a file because it has been consumed before:

Using a file based idempotent repository

In this section we will use the file based idempotent repository org.apache.camel.processor.idempotent.FileIdempotentRepository instead of the in-memory based that is used as default.
This repository uses a 1st level cache to avoid reading the file repository. It will only use the file repository to store the content of the 1st level cache. Thereby the repository can survive server restarts. It will load the content of the file into the 1st level cache upon startup. The file structure is very simple as it stores the key in separate lines in the file. By default, the file store has a size limit of 1mb. When the file grows larger Camel will truncate the file store, rebuilding the content by flushing the 1st level cache into a fresh empty file.

We configure our repository using Spring XML creating our file idempotent repository and define our file consumer to use our repository with the idempotentRepository using # sign to indicate Registry lookup:{snippet:id=example|lang=xml|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/processor/idempotent/fileConsumerIdempotentTest.xml}

Using a JPA based idempotent repository

In this section we will use the JPA based idempotent repository instead of the in-memory based that is used as default.

First we need a persistence-unit in META-INF/persistence.xml where we need to use the class org.apache.camel.processor.idempotent.jpa.MessageProcessed as model.{snippet:id=e1|lang=xml|url=camel/trunk/components/camel-jpa/src/test/resources/META-INF/persistence.xml}Next, we can create our JPA idempotent repository in the spring XML file as well:{snippet:id=jpaStore|lang=xml|url=camel/trunk/components/camel-jpa/src/test/resources/org/apache/camel/processor/jpa/fileConsumerJpaIdempotentTest-config.xml}And yes then we just need to refer to the jpaStore bean in the file consumer endpoint using the idempotentRepository using the # syntax option:

Filter using org.apache.camel.component.file.GenericFileFilter

Camel supports pluggable filtering strategies. You can then configure the endpoint with such a filter to skip certain files being processed.

In the sample we have built our own filter that skips files starting with skip in the filename:{snippet:id=e1|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/component/file/FileConsumerFileFilterTest.java}And then we can configure our route using the filter attribute to reference our filter (using # notation) that we have defined in the spring XML file:

Filtering using ANT path matcher

The ANT path matcher is shipped out-of-the-box in the camel-spring jar. So you need to depend on camel-spring if you are using Maven.
The reasons is that we leverage Spring's AntPathMatcher to do the actual matching.

The file paths is matched with the following rules:

• ? matches one character

• * matches zero or more characters

• ** matches zero or more directories in a path

The sample below demonstrates how to use it:{snippet:id=example|lang=xml|url=camel/trunk/components/camel-spring/src/test/resources/org/apache/camel/spring/file/SpringFileAntPathMatcherFileFilterTest-context.xml}

Sorting using Comparator

Camel supports pluggable sorting strategies. This strategy it to use the build in java.util.Comparator in Java. You can then configure the endpoint with such a comparator and have Camel sort the files before being processed.

In the sample we have built our own comparator that just sorts by file name:{snippet:id=e1|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/component/file/FileSorterRefTest.java}And then we can configure our route using the sorter option to reference to our sorter (mySorter) we have defined in the spring XML file:

Sorting using sortBy

Camel supports pluggable sorting strategies. This strategy it to use the File Language to configure the sorting. The sortBy option is configured as follows:

Where each group is separated with semi colon. In the simple situations you just use one group, so a simple example could be:

This will sort by file name, you can reverse the order by prefixing reverse: to the group, so the sorting is now Z..A:

As we have the full power of File Language we can use some of the other parameters, so if we want to sort by file size we do:

You can configure to ignore the case, using ignoreCase: for string comparison, so if you want to use file name sorting but to ignore the case then we do:

You can combine ignore case and reverse, however reverse must be specified first:

In the sample below we want to sort by last modified file, so we do:

And then we want to group by name as a 2nd option so files with same modifcation is sorted by name:

Now there is an issue here, can you spot it? Well the modified timestamp of the file is too fine as it will be in milliseconds, but what if we want to sort by date only and then subgroup by name?
Well as we have the true power of File Language we can use its date command that supports patterns. So this can be solved as:

Yeah, that is pretty powerful, oh by the way you can also use reverse per group, so we could reverse the file names:

Using GenericFileProcessStrategy

The option processStrategy can be used to use a custom GenericFileProcessStrategy that allows you to implement your own begin, commit and rollback logic.
For instance lets assume a system writes a file in a folder you should consume. But you should not start consuming the file before another ready file has been written as well.

So by implementing our own GenericFileProcessStrategy we can implement this as:

• In the begin() method we can test whether the special ready file exists. The begin method returns a boolean to indicate if we can consume the file or not.

• In the abort() method (Camel 2.10) special logic can be executed in case the begin operation returned false, for example to cleanup resources etc.

• In the commit() method we can move the actual file and also delete the ready file.

Using filter

The filter option allows you to implement a custom filter in Java code by implementing the org.apache.camel.component.file.GenericFileFilter interface. This interface has an accept method that returns a boolean. Return true to include the file, and false to skip the file. From Camel 2.10 onward, there is a isDirectory method on GenericFile whether the file is a directory. This allows you to filter unwanted directories, to avoid traversing down unwanted directories.

For example to skip any directories which starts with "skip" in the name, can be implemented as follows:{snippet:id=e1|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/component/file/FileConsumerDirectoryFilterTest.java}

How to use the Camel error handler to deal with exceptions triggered outside the routing engine

The file and ftp consumers, will by default try to pickup files. Only if that is successful then a Camel Exchange can be created and passed in the Camel routing engine. When the Exchange is processed by the routing engine, then the Camel Error Handling takes over e.g., the onException / errorHandler in the routes. However outside the scope of the routing engine, any exceptions handling is component specific. Camel offers a org.apache.camel.spi.ExceptionHandler that allows components to use that as a pluggable hook for end users to use their own implementation. Camel offers a default LoggingExceptionHandler that will log the exception at ERROR/WARN level.

For the file and ftp components this would be the case. However if you want to bridge the ExceptionHandler so it uses the Camel Error Handling, then you need to implement a custom ExceptionHandler that will handle the exception by creating a Camel Exchange and send it to the routing engine; then the error handling of the routing engine can get triggered.

Here is such an example based upon an unit test.

First we have a custom ExceptionHandler where you can see we deal with the exception by sending it to a Camel Endpoint named direct:file-error:{snippet:id=e1|title=MyExceptionHandler|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/component/file/FileConsumerCustomExceptionHandlerTest.java} 

Then we have a Camel route that uses the Camel routing error handler, which is the onException where we handle any IOException being thrown. We then send the message to the same direct:file-error endpoint, where we handle it by transforming it to a message, and then being sent to a Mock endpoint. This is just for testing purpose. You can handle the exception in any custom way you want, such as using a Bean or sending an email, etc.

Notice how we configure our custom MyExceptionHandler by using the consumer.exceptionHandler option to refer to #myExceptionHandler which is a id of the bean registered in the Registry. If using Spring XML or OSGi Blueprint, then that would be a <bean id="myExceptionHandler" class="com.foo.MyExceptionHandler"/>:{snippet:id=e2|title=Camel route with routing engine error handling|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/component/file/FileConsumerCustomExceptionHandlerTest.java} 

The source code for this example can be seen here

Using consumer.bridgeErrorHandler

Available as of Camel 2.10

If you want to use the Camel Error Handler to deal with any exception occurring in the file consumer, then you can enable the consumer.bridgeErrorHandler option as shown below:{snippet:id=e2|title=Using consumer.bridgeErrorHandler|lang=java|url=camel/trunk/camel-core/src/test/java/org/apache/camel/component/file/FileConsumerBridgeRouteExceptionHandlerTest.java}So all you have to do is to enable this option, and the error handler in the route will take it from there.

Debug logging

This component has log level TRACE that can be helpful if you have problems.

Endpoint See Also

• File Language
• FTP
• Polling Consumer

Flatpack Component

The Flatpack component supports fixed width and delimited file parsing via the FlatPack library.
Notice: This component only supports consuming from flatpack files to Object model. You can not (yet) write from Object model to flatpack format.

Maven users will need to add the following dependency to their pom.xml for this component:

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-flatpack</artifactId>
    <version>x.x.x</version>
    <!-- use the same version as your Camel core version -->
</dependency>

URI format

flatpack:[delim|fixed]:flatPackConfig.pzmap.xml[?options]

Or for a delimited file handler with no configuration file just use

flatpack:someName[?options]

You can append query options to the URI in the following format, ?option=value&option=value&...

URI Options

Examples

• flatpack:fixed:foo.pzmap.xml creates a fixed-width endpoint using the foo.pzmap.xml file configuration.
• flatpack:delim:bar.pzmap.xml creates a delimited endpoint using the bar.pzmap.xml file configuration.
• flatpack:foo creates a delimited endpoint called foo with no file configuration.

Message Headers

Camel will store the following headers on the IN message:

Message Body

The component delivers the data in the IN message as a org.apache.camel.component.flatpack.DataSetList object that has converters for java.util.Map or java.util.List.
Usually you want the Map if you process one row at a time (splitRows=true). Use List for the entire content (splitRows=false), where each element in the list is a Map.
Each Map contains the key for the column name and its corresponding value.

For example to get the firstname from the sample below:

  Map row = exchange.getIn().getBody(Map.class);
  String firstName = row.get("FIRSTNAME");

However, you can also always get it as a List (even for splitRows=true). The same example:

  List data = exchange.getIn().getBody(List.class);
  Map row = (Map)data.get(0);
  String firstName = row.get("FIRSTNAME");

Header and Trailer records

The header and trailer notions in Flatpack are supported. However, you must use fixed record IDs:

• header for the header record (must be lowercase)
• trailer for the trailer record (must be lowercase)

The example below illustrates this fact that we have a header and a trailer. You can omit one or both of them if not needed.

    <RECORD id="header" startPosition="1" endPosition="3" indicator="HBT">
        <COLUMN name="INDICATOR" length="3"/>
        <COLUMN name="DATE" length="8"/>
    </RECORD>

    <COLUMN name="FIRSTNAME" length="35" />
    <COLUMN name="LASTNAME" length="35" />
    <COLUMN name="ADDRESS" length="100" />
    <COLUMN name="CITY" length="100" />
    <COLUMN name="STATE" length="2" />
    <COLUMN name="ZIP" length="5" />

    <RECORD id="trailer" startPosition="1" endPosition="3" indicator="FBT">
        <COLUMN name="INDICATOR" length="3"/>
        <COLUMN name="STATUS" length="7"/>
    </RECORD>

Using the endpoint

A common use case is sending a file to this endpoint for further processing in a separate route. For example:

  <camelContext xmlns="http://activemq.apache.org/camel/schema/spring">
    <route>
      <from uri="file://someDirectory"/>
      <to uri="flatpack:foo"/>
    </route>

    <route>
      <from uri="flatpack:foo"/>
      ...
    </route>
  </camelContext>

You can also convert the payload of each message created to a Map for easy Bean Integration

  FlatpackDataFormat fp = new FlatpackDataFormat();
  fp.setDefinition(new ClassPathResource("INVENTORY-Delimited.pzmap.xml"));
  ...
  from("file:order/in").unmarshal(df).to("seda:queue:neworder");

FlatpackDataFormat df = new FlatpackDataFormat();
df.setDefinition(new ClassPathResource("PEOPLE-FixedLength.pzmap.xml"));
df.setFixed(true);
df.setIgnoreFirstRecord(false);

from("seda:people").marshal(df).convertBodyTo(String.class).to("jms:queue:people");

<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-flatpack</artifactId>
  <version>x.x.x</version>
</dependency>

FreeMarker

The freemarker: component allows for processing a message using a FreeMarker template. This can be ideal when using Templating to generate responses for requests.

Maven users will need to add the following dependency to their pom.xml for this component:

URI format

Where templateName is the classpath-local URI of the template to invoke; or the complete URL of the remote template (eg: file://folder/myfile.ftl).

You can append query options to the URI in the following format, ?option=value&option=value&...

Options

Headers

Headers set during the FreeMarker evaluation are returned to the message and added as headers. This provides a mechanism for the FreeMarker component to return values to the Message.

An example: Set the header value of fruit in the FreeMarker template:

The header, fruit, is now accessible from the message.out.headers.

FreeMarker Context

Camel will provide exchange information in the FreeMarker context (just a Map). The Exchange is transferred as:

From Camel 2.14, you can setup your custom FreeMarker context in the message header with the key "CamelFreemarkerDataModel" just like this

Hot reloading

The FreeMarker template resource is by default not hot reloadable for both file and classpath resources (expanded jar). If you set contentCache=false, then Camel will not cache the resource and hot reloading is thus enabled. This scenario can be used in development.

Dynamic templates

Camel provides two headers by which you can define a different resource location for a template or the template content itself. If any of these headers is set then Camel uses this over the endpoint configured resource. This allows you to provide a dynamic template at runtime.

Samples

For example you could use something like:

To use a FreeMarker template to formulate a response for a message for InOut message exchanges (where there is a JMSReplyTo header).

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

And to disable the content cache, e.g. for development usage where the .ftl template should be hot reloaded:

And a file-based resource:

In Camel 2.1 it's possible to specify what template the component should use dynamically via a header, so for example:

The Email Sample

In this sample we want to use FreeMarker templating for an order confirmation email. The email template is laid out in FreeMarker as:

And the java code:

Endpoint See Also

FTP/SFTP/FTPS Component

This component provides access to remote file systems over the FTP and SFTP protocols.

Maven users will need to add the following dependency to their pom.xml for this component:

URI format

Where directoryname represents the underlying directory. The directory name is a relative path. Absolute paths are not supported. The relative path can contain nested folders, such as /inbox/us.

For Camel versions before Camel 2.16, the directoryName must exist already as this component does not support the autoCreate option (which the file component does). The reason is that its the FTP administrator (FTP server) task to properly setup user accounts, and home directories with the right file permissions etc.

For Camel 2.16, autoCreate option is supported. When consumer starts, before polling is scheduled, there's additional FTP operation performed to create the directory configured for endpoint. The default value for autoCreate is true.

If no username is provided, then anonymous login is attempted using no password.
If no port number is provided, Camel will provide default values according to the protocol (ftp = 21, sftp = 22, ftps = 2222).

You can append query options to the URI in the following format, ?option=value&option=value&...

This component uses two different libraries for the actual FTP work. FTP and FTPS uses Apache Commons Net while SFTP uses JCraft JSCH.

The FTPS component is only available in Camel 2.2 or newer.
FTPS (also known as FTP Secure) is an extension to FTP that adds support for the Transport Layer Security (TLS) and the Secure Sockets Layer (SSL) cryptographic protocols.

URI Options

The options below are exclusive for the FTP component.