Component Appendix

There now follows the documentation on each Camel component.

ActiveMQ Component

The ActiveMQ component allows messages to be sent to a JMS Queue or Topic or messages to be consumed from a JMS Queue or Topic using Apache ActiveMQ.

This component is based on JMS Component and uses Spring's JMS support for declarative transactions, using Spring's JmsTemplate for sending and a MessageListenerContainer for consuming. All the options from the JMS component also applies for this component.

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

Transacted and caching

Icon

See section Transactions and Cache Levels below on JMS page if you are using transactions with JMS as it can impact performance.

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:

Icon

Notice the init and destroy methods on the pooled connection factory. This is important to ensure the connection pool is properly started and shutdown.

Important information about when using transactions

Icon

If you are using transactions then see more details at JMS. And remember to set cacheLevelName to CACHE_CONSUMER if you are not using XA transactions. This can dramatically improve performance.

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 onwards 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

and containing string:

Getting Component JAR

You will need this dependency

  • activemq-camel

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

See Also

Unable to render {include} The included page could not be found.

AMQP

Available as of Camel X.X

The amqp: component supports the AMQP protocol using the Client API of the Qpid project. In case you want to use AMQP with RabbitMQ you might also be interested in the Camel RabbitMQ component.

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

URI format

AMQP Options

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

See Also

SQS Component

Available as of Camel 2.6

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

Prerequisites

Icon

You must have a valid Amazon Web Services developer account, and be signed up to use Amazon SQS. More information are available at Amazon SQS.

URI Format

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

URI Options

Name

Default Value

Context

Description

amazonSQSClient

null

Shared

Reference to a com.amazonaws.services.sqs.AmazonSQS in the Registry.

accessKey

null

Shared

Amazon AWS Access Key

secretKey

null

Shared

Amazon AWS Secret Key

amazonSQSEndpoint

null

Shared

The region with which the AWS-SQS client wants to work with. Only works if Camel creates the AWS-SQS client, i.e., if you explicitly set amazonSQSClient, then this setting will have no effect. You would have to set it on the client you create directly

attributeNames

null

Consumer

A list of attributes to set in the com.amazonaws.services.sqs.model.ReceiveMessageRequest.

defaultVisibilityTimeout

null

Shared

The visibility timeout (in seconds) to set in the com.amazonaws.services.sqs.model.CreateQueueRequest.

deleteAfterRead

true

Consumer

Delete message from SQS after it has been read

deleteIfFiltered

true

Consumer

Camel 2.12.2,2.13.0 Whether or not to send the DeleteMessage to the SQS queue if an exchange fails to get through a filter. If 'false' and exchange does not make it through a Camel filter upstream in the route, then don't send DeleteMessage.

maxMessagesPerPoll

null

Consumer

The maximum number of messages which can be received in one poll to set in the com.amazonaws.services.sqs.model.ReceiveMessageRequest.

visibilityTimeout

null

Shared

The duration (in seconds) that the received messages are hidden from subsequent retrieve requests after being retrieved by a ReceiveMessage request to set in the com.amazonaws.services.sqs.model.SetQueueAttributesRequest. This only make sense if its different from defaultVisibilityTimeout. It changes the queue visibility timeout attribute permanently.

messageVisibilityTimeout

null

Consumer

Camel 2.8: The duration (in seconds) that the received messages are hidden from subsequent retrieve requests after being retrieved by a ReceiveMessage request to set in the com.amazonaws.services.sqs.model.ReceiveMessageRequest. It does NOT change the queue visibility timeout attribute permanently.

extendMessageVisibility

false

Consumer

Camel 2.10: If enabled then a scheduled background task will keep extending the message visibility on SQS. This is needed if it taks a long time to process the message. If set to true defaultVisibilityTimeout must be set. See details at Amazon docs.

maximumMessageSize

null

Shared

Camel 2.8: The maximumMessageSize (in bytes) an SQS message can contain for this queue, to set in the com.amazonaws.services.sqs.model.SetQueueAttributesRequest.

messageRetentionPeriod

null

Shared

Camel 2.8: The messageRetentionPeriod (in seconds) a message will be retained by SQS for this queue, to set in the com.amazonaws.services.sqs.model.SetQueueAttributesRequest.

policy

null

Shared

Camel 2.8: The policy for this queue to set in the com.amazonaws.services.sqs.model.SetQueueAttributesRequest.

delaySeconds

null

Producer

Camel 2.9.3: Delay sending messages for a number of seconds.

waitTimeSeconds

0

Producer

Camel 2.11: Duration in seconds (0 to 20) that the ReceiveMessage action call will wait until a message is in the queue to include in the response.

receiveMessageWaitTimeSeconds

0

Shared

Camel 2.11: If you do not specify WaitTimeSeconds in the request, the queue attribute ReceiveMessageWaitTimeSeconds is used to determine how long to wait.

queueOwnerAWSAccountId

null

Shared

Camel 2.12: Specify the queue owner aws account id when you need to connect the queue with different account owner.

region

null

Shared

Camel 2.12.3: Specify the queue region which could be used with queueOwnerAWSAccountId to build the service URL.

Required SQS component options

Icon

You have to provide the amazonSQSClient in the Registry or your accessKey and secretKey to access the Amazon's SQS.

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

Header

Type

Description

CamelAwsSqsMD5OfBody

String

The MD5 checksum of the Amazon SQS message.

CamelAwsSqsMessageId

String

The Amazon SQS message ID.

CamelAwsSqsDelaySeconds

Integer

Since Camel 2.11, the delay seconds that the Amazon SQS message can be see by others.

Message headers set by the SQS consumer

Header

Type

Description

CamelAwsSqsMD5OfBody

String

The MD5 checksum of the Amazon SQS message.

CamelAwsSqsMessageId

String

The Amazon SQS message ID.

CamelAwsSqsReceiptHandle

String

The Amazon SQS message receipt handle.

CamelAwsSqsAttributes

Map<String, String>

The Amazon SQS message attributes.

Advanced 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:

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

Dependencies

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

pom.xml

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:

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.

See Also

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

Property

Default

Description

splitEntries

true

If true Camel will poll the feed and for the subsequent polls return each entry poll by poll. If the feed contains 7 entries then Camel will return the first entry on the first poll, the 2nd entry on the next poll, until no more entries where as Camel will do a new update on the feed. If false then Camel will poll a fresh feed on every invocation.

filter

true

Is only used by the split entries to filter the entries to return. Camel will default use the UpdateDateFilter that only return new entries from the feed. So the client consuming from the feed never receives the same entry more than once. The filter will return the entries ordered by the newest last.

lastUpdate

null

Is only used by the filter, as the starting timestamp for selection never entries (uses the entry.updated timestamp). Syntax format is: yyyy-MM-ddTHH:MM:ss. Example: 2007-12-24T17:45:59.

throttleEntries

true

Camel 2.5: Sets whether all entries identified in a single feed poll should be delivered immediately. If true, only one entry is processed per consumer.delay. Only applicable when splitEntries is set to true.

feedHeader

true

Sets whether to add the Abdera Feed object as a header.

sortEntries

false

If splitEntries is true, this sets whether to sort those entries by updated date.

consumer.delay

60000

Delay in millis between each poll.

consumer.initialDelay

1000

Millis before polling starts.

consumer.userFixedDelay

false

If true, use fixed delay between pools, otherwise fixed rate is used. See ScheduledExecutorService in JDK for details.

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

Exchange data format

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

Option

Value

Behavior

splitEntries

true

Only a single entry from the currently being processed feed is set: exchange.in.body(Entry)

splitEntries

false

The entire list of entries from the feed is set: exchange.in.body(List<Entry>)

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

Message Headers

Camel atom uses these headers.

Header

Description

CamelAtomFeed

When consuming the org.apache.abdera.model.Feed object is set to this header.

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.

See Also

Bean Component

The bean: component binds beans to Camel message exchanges.

URI format

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

Options

Name

Type

Default

Description

method

String

null

The method name from the bean that will be invoked. If not provided, Camel will try to determine the method itself. In case of ambiguity an exception will be thrown. See Bean Binding for more details. From Camel 2.8 onwards you can specify type qualifiers to pin-point the exact method to use for overloaded methods. From Camel 2.9 onwards you can specify parameter values directly in the method syntax. See more details at Bean Binding.

cache

boolean

false

If enabled, Camel will cache the result of the first Registry look-up. Cache can be enabled if the bean in the Registry is defined as a singleton scope.

multiParameterArray

boolean

false

How to treat the parameters which are passed from the message body; if it is true, the In message body should be an array of parameters.

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

Using

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.

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

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:

And the same route using Spring DSL:

Bean as endpoint

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

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:

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:

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:

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.

See Also

Unable to render {include} The included page could not be found.

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

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:

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

See Also

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:

URI format

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

Options

Name

Default Value

Description

maxElementsInMemory

1000

The number of elements that may be stored in the defined cache

memoryStoreEvictionPolicy

MemoryStoreEvictionPolicy.LFU

The number of elements that may be stored in the defined cache. Options include

  • MemoryStoreEvictionPolicy.LFU - Least frequently used
  • MemoryStoreEvictionPolicy.LRU - Least recently used
  • MemoryStoreEvictionPolicy.FIFO - first in first out, the oldest element by creation time

overflowToDisk

true

Specifies whether cache may overflow to disk

eternal

false

Sets whether elements are eternal. If eternal, timeouts are ignored and the
element never expires.

timeToLiveSeconds

300

The maximum time between creation time and when an element expires.
Is used only if the element is not eternal

timeToIdleSeconds

300

The maximum amount of time between accesses before an element expires

diskPersistent

false

Whether the disk store persists between restarts of the Virtual Machine.

diskExpiryThreadIntervalSeconds

120

The number of seconds between runs of the disk expiry thread.

cacheManagerFactory

null

Camel 2.8: If you want to use a custom factory which instantiates and creates the EHCache net.sf.ehcache.CacheManager.

Type: abstract org.apache.camel.component.cache.CacheManagerFactory

eventListenerRegistry

null

Camel 2.8: Sets a list of EHCache net.sf.ehcache.event.CacheEventListener for all new caches- no need to define it per cache in EHCache xml config anymore.

Type: org.apache.camel.component.cache.CacheEventListenerRegistry

cacheLoaderRegistry

null

Camel 2.8: Sets a list of org.apache.camel.component.cache.CacheLoaderWrapper that extends EHCache net.sf.ehcache.loader.CacheLoader for all new caches- no need to define it per cache in EHCache xml config anymore.

Type: org.apache.camel.component.cache.CacheLoaderRegistry

key

null

Camel 2.10: To configure using a cache key by default. If a key is provided in the message header, then the key from the header takes precedence.

operation

null

Camel 2.10: To configure using an cache operation by default. If an operation in the message header, then the operation from the header takes precedence.

Cache Component options

Name

Default Value

Description

configuration

 

To use a custom org.apache.camel.component.cache.CacheConfiguration configuration.

cacheManagerFactory

 

To use a custom org.apache.camel.component.cache.CacheManagerFactory.

configurationFile

 

Camel 2.13/2.12.3: To configure the location of the ehcache.xml file to use, such as classpath:com/foo/mycache.xml to load from classpath. If no configuration is given, then the default settings from EHCache is used.

Sending/Receiving Messages to/from the cache

Message Headers up to Camel 2.7

Header

Description

CACHE_OPERATION

The operation to be performed on the cache. Valid options are

  • GET
  • CHECK
  • ADD
  • UPDATE
  • DELETE
  • DELETEALL
    GET and CHECK requires Camel 2.3 onwards.

CACHE_KEY

The cache key used to store the Message in the cache. The cache key is optional if the CACHE_OPERATION is DELETEALL

Message Headers Camel 2.8+

Header changes in Camel 2.8

Icon

The header names and supported values have changed to be prefixed with 'CamelCache' and use mixed case. This makes them easier to identify and keep separate from other headers. The CacheConstants variable names remain unchanged, just their values have been changed. Also, these headers are now removed from the exchange after the cache operation is performed.

Header

Description

CamelCacheOperation

The operation to be performed on the cache. The valid options are

  • CamelCacheGet
  • CamelCacheCheck
  • CamelCacheAdd
  • CamelCacheUpdate
  • CamelCacheDelete
  • CamelCacheDeleteAll

CamelCacheKey

The cache key used to store the Message in the cache. The cache key is optional if the CamelCacheOperation is CamelCacheDeleteAll

The CamelCacheAdd and CamelCacheUpdate operations support additional headers:

Header

Type

Description

CamelCacheTimeToLive

Integer

Camel 2.11: Time to live in seconds.

CamelCacheTimeToIdle

Integer

Camel 2.11: Time to idle in seconds.

CamelCacheEternal

Boolean

Camel 2.11: Whether the content is eternal.

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

Example 2: Adding keys to the cache

Example 2: Updating existing keys in a cache

Example 3: Deleting existing keys in a cache

Example 4: Deleting all existing keys in a cache

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

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

Example 7: Getting an entry from the Cache

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.

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:

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

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.

Icon

It might be useful to read the EHCache manual to get a better understanding of the Camel Cache replication mechanism.

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

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

Options

Name

Type

Default

Description

method

String

null

The method name that bean will be invoked. If not provided, Camel will try to pick the method itself. In case of ambiguity an exception is thrown. See Bean Binding for more details.

multiParameterArray

boolean

false

How to treat the parameters which are passed from the message body; if it is true, the In message body should be an array of parameters.

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

Using

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

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

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:

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

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

See more

Icon

See more details at the Bean component as the class component works in much the same way.

See Also

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:

URI format

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.

See this blog entry by David Greco who contributed this component to Apache Camel, for a full sample.

Options

Name

Default Value

Description

resourceBase

 

The root directory for the web resources or classpath. Use the protocol file: or classpath: depending if you want that the component loads the resource from file system or classpath. Classpath is required for OSGI deployment where the resources are packaged in the jar. Notice this option has been renamed to baseResource from Camel 2.7 onwards.

baseResource

 

Camel 2.7: The root directory for the web resources or classpath. Use the protocol file: or classpath: depending if you want that the component loads the resource from file system or classpath. Classpath is required for OSGI deployment where the resources are packaged in the jar

timeout

240000

The server side poll timeout in milliseconds. This is how long the server will hold a reconnect request before responding.

interval

0

The client side poll timeout in milliseconds. How long a client will wait between reconnects

maxInterval

30000

The max client side poll timeout in milliseconds. A client will be removed if a connection is not received in this time.

multiFrameInterval

1500

The client side poll timeout, if multiple connections are detected from the same browser.

jsonCommented

true

If true, the server will accept JSON wrapped in a comment and will generate JSON wrapped in a comment. This is a defence against Ajax Hijacking.

logLevel

1

0=none, 1=info, 2=debug.

sslContextParameters

 

Camel 2.9: Reference to a org.apache.camel.util.jsse.SSLContextParameters in the Registry.  This reference overrides any configured SSLContextParameters at the component level.  See Using the JSSE Configuration Utility.

crossOriginFilterOn

false

Camel 2.10: If true, the server will support for cross-domain filtering

allowedOrigins

*

Camel 2.10: The origins domain that support to cross, if the crosssOriginFilterOn is true

filterPath

 

Camel 2.10: The filterPath will be used by the CrossOriginFilter, if the crosssOriginFilterOn is true

disconnectLocalSession

true

Camel 2.10.5/2.11.1: (Producer only): Whether to disconnect local sessions after publishing a message to its channel. Disconnecting local session is needed as they are not swept by default by CometD, and therefore you can run out of memory.

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.

Programmatic configuration of the component
Spring DSL based configuration of endpoint

See Also

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:

URI format

Or you can omit the "context:" prefix.

  • 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...

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

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...

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 Exchange.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

Name

Type

Default

Description

algorithm

String

SHA1WithDSA

The name of the JCE Signature algorithm that will be used.

alias

String

null

An alias name that will be used to select a key from the keystore.

bufferSize

Integer

2048

the size of the buffer used in the signature process.

certificate

Certificate

null

A Certificate used to verify the signature of the exchange's payload. Either this or a Public Key is required.

keystore

KeyStore

null

A reference to a JCE Keystore that stores keys and certificates used to sign and verify.

provider

String

null

The name of the JCE Security Provider that should be used.

privateKey

PrivateKey

null

The private key used to sign the exchange's payload.

publicKey

PublicKey

null

The public key used to verify the signature of the exchange's payload.

secureRandom

secureRandom

null

A reference to a SecureRandom object that will be used to initialize the Signature service.

password

char[]

null

The password for the keystore.

clearHeaders

String

true

Remove camel crypto headers from Message after a verify operation (value can be "true"/"false").

Using

1) Raw keys

The most basic way to way to sign and verify an exchange is with a KeyPair as follows.

The same can be achieved with the Spring XML Extensions using references to keys

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.

Again in Spring a ref is used to lookup an actual keystore instance.

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.

or

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

or

5) Changing the buffersize

In case you need to update the size of the buffer...

or

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"

or

Even better would be to dynamically supply a keystore alias. Again the alias can be supplied in a message header

  • Exchange.KEYSTORE_ALIAS, "CamelSignatureKeyStoreAlias"

or

The header would be set as follows

See Also

CXF Component

Icon

When using CXF as a consumer, the CXF Bean Component allows you to factor out how message payloads are received from their processing as a RESTful or SOAP web service. This has the potential of using a multitude of transports to consume web services. The bean component's configuration is also simpler and provides the fastest method to implement web services using Camel and CXF.

Icon

When using CXF in streaming modes (see DataFormat option), then also read about Stream caching.

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:

CXF dependencies

Icon

If you want to learn about CXF dependencies you can checkout the WHICH-JARS text file.

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

Name

Required

Description

wsdlURL

No

The location of the WSDL. It is obtained from endpoint address by default.

Example: file://local/wsdl/hello.wsdl or wsdl/hello.wsdl

serviceClass

Yes

The name of the SEI (Service Endpoint Interface) class. This class can have, but does not require, JSR181 annotations.
This option is only required by POJO mode. If the wsdlURL option is provided, serviceClass is not required for PAYLOAD and MESSAGE mode. When wsdlURL option is used without serviceClass, the serviceName and portName (endpointName for Spring configuration) options MUST be provided. It is possible to use # notation to reference a serviceClass object instance from the registry. E.g. serviceClass=#beanName. The serviceClass for a CXF producer (that is, the to endpoint) should be a Java interface.
Since 2.8, it is possible to omit both wsdlURL and serviceClass options for PAYLOAD and MESSAGE mode. When they are omitted, arbitrary XML elements can be put in CxfPayload's body in PAYLOAD mode to facilitate CXF Dispatch Mode.

Please be advised that the referenced object cannot be a Proxy (Spring AOP Proxy is OK) as it relies on Object.getClass().getName() method for non Spring AOP Proxy.

Example: org.apache.camel.Hello

serviceName

No

The service name this service is implementing, it maps to the wsdl:service@name.

Required for camel-cxf consumer since camel-2.2.0 or if more than one serviceName is present in WSDL.

Example: {http:­//org.apache.camel}ServiceName

endpointName

No

The port name this service is implementing, it maps to the wsdl:port@name.

Required for camel-cxf consumer since camel-2.2.0 or if more than one portName is present under serviceName.

Example: {http:­//org.apache.camel}PortName

dataFormat

No

The data type messages supported by the CXF endpoint.

Default: POJO
Example: POJO, PAYLOAD, MESSAGE

relayHeaders

No

Please see the Description of relayHeaders option section for this option. Should a CXF endpoint relay headers along the route. Currently only available when dataFormat=POJO

Default: true
Example: true, false

wrapped

No

Which kind of operation that CXF endpoint producer will invoke

Default: false
Example: true, false

wrappedStyle

No

New in 2.5.0 The WSDL style that describes how parameters are represented in the SOAP body. If the value is false, CXF will chose the document-literal unwrapped style, If the value is true, CXF will chose the document-literal wrapped style

Default: Null
Example: true, false

setDefaultBus

No

Will set the default bus when CXF endpoint create a bus by itself

Default: false
Example: true, false

bus

No

A default bus created by CXF Bus Factory. Use # notation to reference a bus object from the registry. The referenced object must be an instance of org.apache.cxf.Bus.

Example: bus=#busName

cxfBinding

No

Use # notation to reference a CXF binding object from the registry. The referenced object must be an instance of org.apache.camel.component.cxf.CxfBinding (use an instance of org.apache.camel.component.cxf.DefaultCxfBinding).

Example: cxfBinding=#bindingName

headerFilterStrategy

No

Use # notation to reference a header filter strategy object from the registry. The referenced object must be an instance of org.apache.camel.spi.HeaderFilterStrategy (use an instance of org.apache.camel.component.cxf.CxfHeaderFilterStrategy).

Example: headerFilterStrategy=#strategyName

loggingFeatureEnabled

No

New in 2.3. This option enables CXF Logging Feature which writes inbound and outbound SOAP messages to log.

Default: false
Example: loggingFeatureEnabled=true

defaultOperationName

No

New in 2.4, this option will set the default operationName that will be used by the CxfProducer which invokes the remote service.

Default: null
Example: defaultOperationName=greetMe

defaultOperationNamespace

No

New in 2.4. This option will set the default operationNamespace that will be used by the CxfProducer which invokes the remote service.

Default: null
Example: defaultOperationNamespace=http://apache.org/hello_world_soap_http

synchronous

No

New in 2.5. This option will let cxf endpoint decide to use sync or async API to do the underlying work. The default value is false which means camel-cxf endpoint will try to use async API by default.

Default: false
Example: synchronous=true

publishedEndpointUrl

No

New in 2.5. This option can override the endpointUrl that published from the WSDL which can be accessed with service address url plus ?wsdl.

Default: null
Example: publshedEndpointUrl=http://example.com/service

properties.XXX

No

Camel 2.8: Allows to set custom properties to CXF in the endpoint uri. For example setting properties.mtom-enabled=true to enable MTOM.

allowStreaming

No

New in 2.8.2. This option controls whether the CXF component, when running in PAYLOAD mode (see below), will DOM parse the incoming messages into DOM Elements or keep the payload as a javax.xml.transform.Source object that would allow streaming in some cases.

skipFaultLogging

No

New in 2.11. This option controls whether the PhaseInterceptorChain skips logging the Fault that it catches.

username

No

New in Camel 2.12.3 This option is used to set the basic authentication information of username for the CXF client.

password

No

New in Camel 2.12.3 This option is used to set the basic authentication information of password for the CXF client.

continuationTimeout

No

New in Camel 2.14.0 This option is used to set the CXF continuation timeout which could be used in CxfConsumer by default when the CXF server is using Jetty or Servlet transport. (Before Camel 2.14.0, CxfConsumer just set the continuation timeout to be 0, which means the continuation suspend operation never timeout.)

Default: 30000
 Example: continuation=80000

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

DataFormat

Description

POJO

POJOs (Plain old Java objects) are the Java parameters to the method being invoked on the target server. Both Protocol and Logical JAX-WS handlers are supported.

PAYLOAD

PAYLOAD is the message payload (the contents of the soap:body) after message configuration in the CXF endpoint is applied. Only Protocol JAX-WS handler is supported. Logical JAX-WS handler is not supported.

MESSAGE

MESSAGE is the raw message that is received from the transport layer. It is not suppose to touch or change Stream, some of the CXF interceptors will be removed if you are using this kind of DataFormat so you can't see any soap headers after the camel-cxf consumer and JAX-WS handler is not supported.

CXF_MESSAGE

New in Camel 2.8.2, CXF_MESSAGE allows for invoking the full capabilities of CXF interceptors by converting the message from the transport layer into a raw SOAP message

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.

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.

    Then, your endpoint can reference the CxfHeaderFilterStrategy.

  • 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:

  • 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.

    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.

You can add a customer interceptor like this and configure it into you camel-cxf endpont

Or adding a message header for it like this if you are using Camel 2.4.

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.

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 want to get the object array from the message body, you can get the body using message.getbody(Object[].class), as follows:

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.

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:

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.

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

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

Then throw it as you like

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.

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

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

You can produce a Camel message with attachment to send to a CXF endpoint in Payload mode.

You can also consume a Camel message received from a CXF endpoint in Payload mode.

Message Mode: Attachments are not supported as it does not process the message at all.

Streaming Support in PAYLOAD mode

In 2.8.2, the camel-cxf component now supports streaming of incoming messages when using PAYLOAD mode. Previously, the incoming messages would have been completely DOM parsed. For large messages, this is time consuming and uses a 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).

 

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.

Icon

CxfBeanEndpoint is a ProcessorEndpoint so it has no consumers. It works similarly to a Bean component.

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

Name

Description

Example

Required?

Default Value

bus

CXF bus reference specified by the # notation. The referenced object must be an instance of org.apache.cxf.Bus.

bus=#busName

No

Default bus created by CXF Bus Factory

cxfBeanBinding

CXF bean binding specified by the # notation. The referenced object must be an instance of org.apache.camel.component.cxf.cxfbean.CxfBeanBinding.

cxfBinding=#bindingName

No

DefaultCxfBeanBinding

headerFilterStrategy

Header filter strategy specified by the # notation. The referenced object must be an instance of org.apache.camel.spi.HeaderFilterStrategy.

headerFilterStrategy=#strategyName

No

CxfHeaderFilterStrategy

populateFromClass

Since 2.3, the wsdlLocation annotated in the POJO is ignored (by default) unless this option is set to  false. Prior to 2.3, the wsdlLocation annotated in the POJO is always honored and it is not possible to ignore.

true, false

No

true

providers

Since 2.5, setting the providers for the CXFRS endpoint.

providers=#providerRef1,#providerRef2

No

null

setDefaultBus

Will set the default bus when CXF endpoint create a bus by itself.

true, false

No

false

Headers

Name

Description

Type

Required?

Default Value

In/Out

Examples

CamelHttpCharacterEncoding (before 2.0-m2: CamelCxfBeanCharacterEncoding)

Character encoding

String

No

None

In

ISO-8859-1

CamelContentType (before 2.0-m2: CamelCxfBeanContentType)

Content type

String

No

*/*

In

text/xml

CamelHttpBaseUri
(2.0-m3 and before: CamelCxfBeanRequestBasePath)

The value of this header will be set in the CXF message as the Message.BASE_PATH property. It is needed by CXF JAX-RS processing. Basically, it is the scheme, host and port portion of the request URI.

String

Yes

The Endpoint URI of the source endpoint in the Camel exchange

In

http://localhost:9000

CamelHttpPath (before 2.0-m2: CamelCxfBeanRequestPath)

Request URI's path

String

Yes

None

In

consumer/123

CamelHttpMethod (before 2.0-m2: CamelCxfBeanVerb)

RESTful request verb

String

Yes

None

In

GET, PUT, POST, DELETE

CamelHttpResponseCode

HTTP response code

Integer

No

None

Out

200

Icon

Currently, the CXF Bean component has (only) been tested with the Jetty component. It understands headers from Jetty component without requiring conversion.

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

Icon

When using CXF as a consumer, the CXF Bean Component allows you to factor out how message payloads are received from their processing as a RESTful or SOAP web service. This has the potential of using a multitude of transports to consume web services. The bean component's configuration is also simpler and provides the fastest method to implement web services using Camel and CXF.

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

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

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

Name

Description

Example

Required?

default value

resourceClasses

The resource classes which you want to export as REST service. Multiple classes can be separated by comma.

resourceClasses=org.apache.camel.rs.Example1,
org.apache.camel.rs.Exchange2

No

None

resourceClass

Deprecated: Use resourceClasses The resource class which you want to export as REST service.

resourceClass =org.apache.camel.rs.Example1

No

None

httpClientAPI

new to Camel 2.1 If it is true, the CxfRsProducer will use the HttpClientAPI to invoke the service
If it is false, the CxfRsProducer will use the ProxyClientAPI to invoke the service

httpClientAPI=true

No

true

synchronous

New in 2.5, this option will let CxfRsConsumer decide to use sync or async API to do the underlying work. The default value is false which means it will try to use async API by default.

synchronous=true

No

false

throwExceptionOnFailure

New in 2.6, this option tells the CxfRsProducer to inspect return codes and will generate an Exception if the return code is larger than 207.

throwExceptionOnFailure=true

No

true

maxClientCacheSize

New in 2.6, you can set a IN message header CamelDestinationOverrideUrl to dynamically override the target destination Web Service or REST Service defined in your routes.  The implementation caches CXF clients or ClientFactoryBean in CxfProvider and CxfRsProvider.  This option allows you to configure the maximum size of the cache.

maxClientCacheSize=5

No

10

setDefaultBus

New in 2.9.0. Will set the default bus when CXF endpoint create a bus by itself

setDefaultBus=true

No

false

bus

New in 2.9.0. A default bus created by CXF Bus Factory. Use # notation to reference a bus object from the registry. The referenced object must be an instance of org.apache.cxf.Bus.

bus=#busName

No

None

bindingStyle

As of 2.11. Sets how requests and responses will be mapped to/from Camel. Two values are possible:

bindingStyle=SimpleConsumer

No

Default

providers

Since Camel 2.12.2 set custom JAX-RS providers list to the CxfRs endpoint.

providers=#MyProviders

No

None

schemaLocations

Since Camel 2.12.2 Sets the locations of the schemas which can be used to validate the incoming XML or JAXB-driven JSON.

schemaLocations=#MySchemaLocations

No

None

features

Since Camel 2.12.3 Set the feature list to the CxfRs endpoint.

features=#MyFeatures

No

None

properties

Since Camel 2.12.4 Set the properties to the CxfRs endpoint.

properties=#MyProperties

No

None

inInterceptors

Since Camel 2.12.4 Set the inInterceptors to the CxfRs endpoint.

inInterceptors=#MyInterceptors

No

None

outInterceptors

Since Camel 2.12.4 Set the outInterceptor to the CxfRs endpoint.

outInterceptors=#MyInterceptors

No

None

inFaultInterceptors

Since Camel 2.12.4 Set the inFaultInterceptors to the CxfRs endpoint.

inFaultInterceptors=#MyInterceptors

No

None

outFaultIntercetpros

Since Camel 2.12.4 Set the outFaultInterceptors to the CxfRs endpoint.

outFaultInterceptors=#MyInterceptors

No

None

continuationTimeout

Since Camel 2.14.0 This option is used to set the CXF continuation timeout which could be used in CxfConsumer by default when the CXF server is using Jetty or Servlet transport. (Before Camel 2.14.0, CxfConsumer just set the continuation timeout to be 0, which means the continuation suspend operation never timeout.)

continuationTimeout=800000

No

30000

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.

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...

And the corresponding resource class used to configure the endpoint...

Note about resource classes

Icon

Resource classes are only used to configure JAX-RS properties. Methods will not be executed during routing of messages to the endpoint. Instead, it is the responsibility of the route to do all processing.

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:

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.

From Camel 2.1, we also support to specify the query parameters from cxfrs URI for the CXFRS http centric client.

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.

DataSet Component

Testing of distributed and asynchronous processing is notoriously difficult. The Mock, Test and DataSet endpoints work great with the Camel Testing Framework to simplify your unit and integration testing using Enterprise Integration Patterns and Camel's large range of Components together with the powerful Bean Integration.

The DataSet component 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

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 a default implementation, the org.apache.camel.component.dataset.SimpleDataSet that can be used for testing.

Options

Option

Default

Description

produceDelay

3

Allows a delay in ms to be specified, which causes producers to pause in order to simulate slow producers. Uses a minimum of 3 ms delay unless you set this option to -1 to force no delay at all.

consumeDelay

0

Allows a delay in ms to be specified, which causes consumers to pause in order to simulate slow consumers.

preloadSize

0

Sets how many messages should be preloaded (sent) before the route completes its initialization.

initialDelay

1000

Camel 2.1: Time period in millis to wait before starting sending messages.

minRate

0

Wait until the DataSet contains at least this number of messages

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

Configuring DataSet

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

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:

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.

Properties on SimpleDataSet

Property

Type

Default

Description

defaultBody

Object

<hello>world!</hello>

Specifies the default message body. For SimpleDataSet it is a constant payload; though if you want to create custom payloads per message, create your own derivation of DataSetSupport.

reportCount

long

-1

Specifies the number of messages to be received before reporting progress. Useful for showing progress of a large load test. If < 0, then size / 5, if is 0 then size, else set to reportCount value.

size

long

10

Specifies how many messages to send/consume.

See Also

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

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

Options

Name

Default Value

Description

consumeDelete

true

Option for Db4oConsumer only. Specifies whether or not the entity is deleted after it is consumed.

consumer.delay

500

Option for consumer only. Delay in millis between each poll.

consumer.initialDelay

1000

Option for consumer only. Millis before polling starts.

consumer.userFixedDelay

false

Option for consumer only. Set to true to use fixed delay between polls, otherwise fixed rate is used. See ScheduledExecutorService in JDK for details.

See Also

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.

Asynchronous

Icon

The SEDA component provides asynchronous invocation of any consumers when a producer sends a message exchange.

Connection to other camel contexts

Icon

The VM component provides connections between Camel contexts as long they run in the same JVM.

URI format

Where someName can be any string to uniquely identify the endpoint

Options

Name

Default Value

Description

allowMultipleConsumers

true

@deprecated If set to false, then when a second consumer is started on the endpoint, an IllegalStateException is thrown. Will be removed in Camel 2.1: Direct endpoint does not support multiple consumers.

block

false

Camel 2.11.1: If sending a message to a direct endpoint which has no active consumer, then we can tell the producer to block and wait for the consumer to become active.

timeout

30000

Camel 2.11.1: The timeout value to use if block is enabled.

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:

And the sample using spring DSL:

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

See Also

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

Requires SUN JVM

Icon

The DNSJava library requires running on the SUN JVM.
If you use Apache ServiceMix or Apache Karaf, you'll need to adjust the etc/jre.properties file, to add sun.net.spi.nameservice to the list of Java platform packages exported. The server will need restarting before this change takes effect.

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

URI format

The URI scheme for a DNS component is as follows

This component only supports producers.

Options

None.

Headers

Header

Type

Operations

Description

dns.domain

String

ip

The domain name. Mandatory.

dns.name

String

lookup

The name to lookup. Mandatory.

dns.type

lookup, dig

The type of the lookup. Should match the values of org.xbill.dns.Type. Optional.

dns.class

lookup, dig

he DNS class of the lookup. Should match the values of org.xbill.dns.DClass. Optional.

dns.query

String

dig

The query itself. Mandatory.

dns.server

String

dig

The server in particular for the query. If none is given, the default one specified by the OS will be used. Optional.

Examples

IP lookup

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

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.

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

See Also

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:

URI format

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

Options

Name

Type

Default

Description

method

String

null

The method name that bean will be invoked. If not provided, Camel will try to pick the method itself. In case of ambiguity an exception is thrown. See Bean Binding for more details.

multiParameterArray

boolean

false

How to treat the parameters which are passed from the message body; if it is true, the In message body should be an array of parameters.

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

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

Bean Binding

How bean methods to be invoked are chosen (if they are not 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:

GreaterLocal.java

And the implementation

GreaterImpl.java

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:

In a real application server

Icon

In a real application server you most likely do not have to setup a JndiContext on the EJB component as it will create a default JndiContext on the same JVM as the application server, which usually allows it to access the JNDI registry and lookup the EJBs.
However if you need to access a application server on a remote JVM or the likes, you have to prepare the properties beforehand.

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:

See Also

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

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

Pattern example:

EQL example:

Options

Name

Default Value

Description

configured

false

Available as of camel-extra 2.11.3:
If flag is set to 'true' the default Esper configuration file (esper.cfg.xml) will be used. 
To configure Esper via a configuration file, please refer to the Esper documentation

pattern

 

The Esper Pattern expression as a String to filter events

eql

 

The Esper EQL expression as a String to filter events

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:

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

See Also

Unable to render {include} The included page could not be found.

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&...

Only directories

Icon

Camel supports only endpoints configured with a starting directory. So the directoryName must be a directory.
If you want to consume a single file only, you can use the fileName option, e.g. by setting fileName=thefilename.
Also, the starting directory must not contain dynamic expressions with ${ } placeholders. Again use the fileName option to specify the dynamic part of the filename.

Avoid reading files currently being written by another application

Icon

Beware the JDK File IO API is a bit limited in detecting whether another application is currently writing/copying a file. And the implementation can be different depending on OS platform as well. This could lead to that Camel thinks the file is not locked by another process and start consuming it. Therefore you have to do you own investigation what suites your environment. To help with this Camel provides different readLock options and doneFileName option that you can use. See also the section Consuming files from folders where others drop files directly.

URI Options

Common

Name

Default Value

Description

autoCreate

true

Automatically create missing directories in the file's pathname. For the file consumer, that means creating the starting directory. For the file producer, it means the directory the files should be written to.

bufferSize

128kb

Write buffer sized in bytes.

fileName

null

Use Expression such as File Language to dynamically set the filename. For consumers, it's used as a filename filter. For producers, it's used to evaluate the filename to write. If an expression is set, it take precedence over the CamelFileName header. (Note: The header itself can also be an Expression). The expression options support both String and Expression types. If the expression is a String type, it is always evaluated using the File Language. If the expression is an Expression type, the specified Expression type is used - this allows you, for instance, to use OGNL expressions. For the consumer, you can use it to filter filenames, so you can for instance consume today's file using the File Language syntax: mydata-${date:now:yyyyMMdd}.txt. From Camel 2.11 onwards the producers support the CamelOverruleFileName header which takes precedence over any existing CamelFileName header; the CamelOverruleFileName is a header that is used only once, and makes it easier as this avoids to temporary store CamelFileName and have to restore it afterwards.

flatten

false

Flatten is used to flatten the file name path to strip any leading paths, so it's just the file name. This allows you to consume recursively into sub-directories, but when you eg write the files to another directory they will be written in a single directory. Setting this to true on the producer enforces that any file name recived in CamelFileName header will be stripped for any leading paths.

charset

null

Camel 2.9.3: this option is used to specify the encoding of the file, and camel will set the Exchange property with Exchange.CHARSET_NAME with the value of this option. You can use this on the consumer, to specify the encodings of the files, which allow Camel to know the charset it should load the file content in case the file content is being accessed. Likewise when writing a file, you can use this option to specify which charset to write the file as well. See further below for a examples and more important details.

copyAndDeleteOnRenameFail

true

Camel 2.9: whether to fallback and do a copy and delete file, in case the file could not be renamed directly. This option is not available for the FTP component.

renameUsingCopy

false

Camel 2.13.1: Perform rename operations using a copy and delete strategy. This is primarily used in environments where the regular rename operation is unreliable (e.g. across different file systems or networks). This option takes precedence over the copyAndDeleteOnRenameFail parameter that will automatically fall back to the copy and delete strategy, but only after additional delays.

Consumer

Name

Default Value

Description

initialDelay

1000

Milliseconds before polling the file/directory starts.

delay

500

Milliseconds before the next poll of the file/directory.

useFixedDelay

 

Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details. In Camel 2.7.x or older the default value is false. From Camel 2.8 onwards the default value is true.

runLoggingLevel

TRACE

Camel 2.8: The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.

recursive

false

If a directory, will look for files in all the sub-directories as well.

delete

false

If true, the file will be deleted after it is processed

noop

false

If true, the file is not moved or deleted in any way. This option is good for readonly data, or for ETL type requirements. If noop=true, Camel will set idempotent=true as well, to avoid consuming the same files over and over again.

preMove

null

Expression (such as File Language) used to dynamically set the filename when moving it before processing. For example to move in-progress files into the order directory set this value to order.

move

.camel

Expression (such as File Language) used to dynamically set the filename when moving it after processing. To move files into a .done subdirectory just enter .done.

moveFailed

null

Expression (such as File Language) used to dynamically set a different target directory when moving files in case of processing (configured via move defined above) failed. For example, to move files into a .error subdirectory use: .error. Note: When moving the files to the “fail” location Camel will handle the error and will not pick up the file again.

include

null

Is used to include files, if filename matches the regex pattern.

exclude

null

Is used to exclude files, if filename matches the regex pattern.

antInclude

null

Camel 2.10: Ant style filter inclusion, for example antInclude=*/.txt. Multiple inclusions may be specified in comma-delimited format. See below for more details about ant path filters.

antExclude

null

Camel 2.10: Ant style filter exclusion. If both antInclude and antExclude are used, antExclude takes precedence over antInclude. Multiple exclusions may be specified in comma-delimited format. See below for more details about ant path filters.

antFilterCaseSensitive

true

Camel 2.11: Ant style filter which is case sensitive or not.

idempotent

false

Option to use the Idempotent Consumer EIP pattern to let Camel skip already processed files. Will by default use a memory based LRUCache that holds 1000 entries. If noop=true then idempotent will be enabled as well to avoid consuming the same files over and over again.

idempotentKey

Expression

Camel 2.11: To use a custom idempotent key. By default the absolute path of the file is used. You can use the File Language, for example to use the file name and file size, you can do:

.

idempotentRepository

null

A pluggable repository org.apache.camel.spi.IdempotentRepository which by default use MemoryMessageIdRepository if none is specified and idempotent is true.

inProgressRepository

memory

A pluggable in-progress repository org.apache.camel.spi.IdempotentRepository. The in-progress repository is used to account the current in progress files being consumed. By default a memory based repository is used.

filter

null

Pluggable filter as a org.apache.camel.component.file.GenericFileFilter class. Will skip files if filter returns false in its accept() method. More details in section below.

sorter

null

Pluggable sorter as a java.util.Comparator<org.apache.camel.component.file.GenericFile> class.

sortBy

null

Built-in sort using the File Language. Supports nested sorts, so you can have a sort by file name and as a 2nd group sort by modified date. See sorting section below for details.

readLock

markerFile

Used by consumer, to only poll the files if it has exclusive read-lock on the file (i.e. the file is not in-progress or being written). Camel will wait until the file lock is granted.
This option provides the build in strategies:
markerFile Camel creates a marker file (fileName.camelLock) and then holds a lock on it. This option is not available for the FTP component.
changed is using file length/modification timestamp to detect whether the file is currently being copied or not. Will at least use 1 sec. to determine this, so this option cannot consume files as fast as the others, but can be more reliable as the JDK IO API cannot always determine whether a file is currently being used by another process. The option readLockCheckInterval can be used to set the check frequency. This option is only avail for the FTP component from Camel 2.8 onwards. Notice that from Camel 2.10.1 onwards the FTP option fastExistsCheck can be enabled to speedup this readLock strategy, if the FTP server support the LIST operation with a full file name (some servers may not).
fileLock is for using java.nio.channels.FileLock. This option is not avail for the FTP component. This approach should be avoided when accessing a remote file system via a mount/share unless that file system supports distributed file locks.
rename is for using a try to rename the file as a test if we can get exclusive read-lock.
none is for no read locks at all.
Notice from Camel 2.10 onwards the read locks changed, fileLock and rename will also use a markerFile as well, to ensure not picking up files that may be in process by another Camel consumer running on another node (eg cluster). This is only supported by the file component (not the ftp component).

readLockTimeout

10000

Optional timeout in millis for the read-lock, if supported by the read-lock. If the read-lock could not be granted and the timeout triggered, then Camel will skip the file. At next poll Camel, will try the file again, and this time maybe the read-lock could be granted. Use a value of 0 or lower to indicate forever. In Camel 2.0 the default value is 0. Starting with Camel 2.1 the default value is 10000. Currently fileLock, changed and rename support the timeout. Notice: For FTP the default readLockTimeout value is 20000 instead of 10000.

readLockCheckInterval

1000

Camel 2.6: Interval in millis for the read-lock, if supported by the read lock. This interval is used for sleeping between attempts to acquire the read lock. For example when using the changed read lock, you can set a higher interval period to cater for slow writes. The default of 1 sec. may be too fast if the producer is very slow writing the file. For FTP the default readLockCheckInterval is 5000.

readLockMinLength

1

Camel 2.10.1: This option applied only for readLock=changed. This option allows you to configure a minimum file length. By default Camel expects the file to contain data, and thus the default value is 1. You can set this option to zero, to allow consuming zero-length files.

readLockLoggingLevel

WARN

Camel 2.12: Logging level used when a read lock could not be acquired. By default a WARN is logged. You can change this level, for example to OFF to not have any logging. This option is only applicable for readLock of types: changed, fileLock, rename.

directoryMustExist

false

Camel 2.5: Similar to startingDirectoryMustExist but this applies during polling recursive sub directories.

doneFileName

null

Camel 2.6: If provided, Camel will only consume files if a done file exists. This option configures what file name to use. Either you can specify a fixed name. Or you can use dynamic placeholders. The done file is always expected in the same folder as the original file. See using done file and writing done file sections for examples.

exclusiveReadLockStrategy

null

Pluggable read-lock as a org.apache.camel.component.file.GenericFileExclusiveReadLockStrategy implementation.

maxMessagesPerPoll

0

An integer to define a maximum messages to gather per poll. By default no maximum is set. Can be used to set a limit of e.g. 1000 to avoid when starting up the server that there are thousands of files. Set a value of 0 or negative to disabled it. See more details at Batch Consumer. Notice: If this option is in use then the File and FTP components will limit before any sorting. For example if you have 100000 files and use maxMessagesPerPoll=500, then only the first 500 files will be picked up, and then sorted. You can use the eagerMaxMessagesPerPoll option and set this to false to allow to scan all files first and then sort afterwards.

eagerMaxMessagesPerPoll

true

Camel 2.9.3: Allows for controlling whether the limit from maxMessagesPerPoll is eager or not. If eager then the limit is during the scanning of files. Where as false would scan all files, and then perform sorting. Setting this option to false allows for sorting all files first, and then limit the poll. Mind that this requires a higher memory usage as all file details are in memory to perform the sorting.

minDepth

0

Camel 2.8: The minimum depth to start processing when recursively processing a directory. Using minDepth=1 means the base directory. Using minDepth=2 means the first sub directory. This option is supported by FTP consumer from Camel 2.8.2, 2.9 onwards.

maxDepth

Integer.MAX_VALUE

Camel 2.8: The maximum depth to traverse when recursively processing a directory. This option is supported by FTP consumer from Camel 2.8.2, 2.9 onwards.

processStrategy

null

A pluggable org.apache.camel.component.file.GenericFileProcessStrategy allowing you to implement your own readLock option or similar. Can also be used when special conditions must be met before a file can be consumed, such as a special ready file exists. If this option is set then the readLock option does not apply.

startingDirectoryMustExist

false

Camel 2.5: Whether the starting directory must exist. Mind that the autoCreate option is default enabled, which means the starting directory is normally auto created if it doesn't exist. You can disable autoCreate and enable this to ensure the starting directory must exist. Will thrown an exception if the directory doesn't exist.

pollStrategy

null

A pluggable org.apache.camel.spi.PollingConsumerPollStrategy allowing you to provide your custom implementation to control error handling usually occurred during the poll operation before an Exchange have been created and being routed in Camel. In other words the error occurred while the polling was gathering information, for instance access to a file network failed so Camel cannot access it to scan for files. The default implementation will log the caused exception at WARN level and ignore it.

sendEmptyMessageWhenIdle

false

Camel 2.9: If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.

consumer.bridgeErrorHandler

false

Camel 2.10: Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while trying to pickup files, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that by default will be logged at WARN/ERROR level and ignored. See further below on this page fore more details, at section How to use the Camel error handler to deal with exceptions triggered outside the routing engine.

scheduledExecutorService

null

Camel 2.10: Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool. This option allows you to share a thread pool among multiple file consumers.

scheduler

null

Camel 2.12: To use a custom scheduler to trigger the consumer to run. See more details at Polling Consumer, for example there is a Quartz2, and Spring based scheduler that supports CRON expressions.

backoffMultiplier

0

Camel 2.12: To let the scheduled polling consumer backoff if there has been a number of subsequent idles/errors in a row. The multiplier is then the number of polls that will be skipped before the next actual attempt is happening again. When this option is in use then backoffIdleThreshold and/or backoffErrorThreshold must also be configured. See more details at Polling Consumer.

backoffIdleThreshold

0

Camel 2.12: The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.

backoffErrorThreshold

0

Camel 2.12: The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.

Default behavior for file consumer

  • By default the file is 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

Name

Default Value

Description

fileExist

Override

What to do if a file already exists with the same name. The following values can be specified: Override, Append, Fail, Ignore, Move, and TryRename (Camel 2.11.1). Override, which is the default, replaces the existing file. Append adds content to the existing file. Fail throws a GenericFileOperationException, indicating that there is already an existing file. Ignore silently ignores the problem and does not override the existing file, but assumes everything is okay. The Move option requires Camel 2.10.1 onwards, and the corresponding moveExisting option to be configured as well. The option eagerDeleteTargetFile can be used to control what to do if an moving the file, and there exists already an existing file, otherwise causing the move operation to fail. The Move option will move any existing files, before writing the target file. TryRename Camel 2.11.1 is only applicable if tempFileName option is in use. This allows to try renaming the file from the temporary name to the actual name, without doing any exists check. This check may be faster on some file systems and especially FTP servers.

tempPrefix

null

This option is used to write the file using a temporary name and then, after the write is complete, rename it to the real name. Can be used to identify files being written and also avoid consumers (not using exclusive read locks) reading in progress files. Is often used by FTP when uploading big files.

tempFileName

null

Camel 2.1: The same as tempPrefix option but offering a more fine grained control on the naming of the temporary filename as it uses the File Language.

moveExisting

null

Camel 2.10.1: Expression (such as File Language) used to compute file name to use when fileExist=Move is configured. To move files into a backup subdirectory just enter backup. This option only supports the following File Language tokens: "file:name", "file:name.ext", "file:name.noext", "file:onlyname", "file:onlyname.noext", "file:ext", and "file:parent". Notice the "file:parent" is not supported by the FTP component, as the FTP component can only move any existing files to a relative directory based on current dir as base.

keepLastModified

false

Camel 2.2: Will keep the last modified timestamp from the source file (if any). Will use the Exchange.FILE_LAST_MODIFIED header to located the timestamp. This header can contain either a java.util.Date or long with the timestamp. If the timestamp exists and the option is enabled it will set this timestamp on the written file. Note: This option only applies to the file producer. You cannot use this option with any of the ftp producers.

eagerDeleteTargetFile

true

Camel 2.3: Whether or not to eagerly delete any existing target file. This option only applies when you use fileExists=Override and the tempFileName option as well. You can use this to disable (set it to false) deleting the target file before the temp file is written. For example you may write big files and want the target file to exists during the temp file is being written. This ensure the target file is only deleted until the very last moment, just before the temp file is being renamed to the target filename. From Camel 2.10.1 onwards this option is also used to control whether to delete any existing files when fileExist=Move is enabled, and an existing file exists. If this option copyAndDeleteOnRenameFailis false, then an exception will be thrown if an existing file existed, if its true, then the existing file is deleted before the move operation.

doneFileName

null

Camel 2.6: If provided, then Camel will write a 2nd done file when the original file has been written. The done file will be empty. This option configures what file name to use. Either you can specify a fixed name. Or you can use dynamic placeholders. The done file will always be written in the same folder as the original file. See writing done file section for examples.

allowNullBody

false

Camel 2.10.1: Used to specify if a null body is allowed during file writing. If set to true then an empty file will be created, when set to false, and attempting to send a null body to the file component, a GenericFileWriteException of 'Cannot write null body to file.' will be thrown. If the `fileExist` option is set to 'Override', then the file will be truncated, and if set to `append` the file will remain unchanged.

forceWrites

true

Camel 2.10.5/2.11: Whether to force syncing writes to the file system. You can turn this off if you do not want this level of guarantee, for example if writing to logs / audit logs etc; this would yield better performance.

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 preMove options is 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 - eg 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 over Move and PreMove option

The move and preMove option is Expression-based, so we have the full power of the File Language to do advanced 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 succesfully 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

Header

Description

CamelFileName

Specifies the name of the file to write (relative to the endpoint directory). The name can be a String; a String with a File Language or Simple expression; or an Expression object. If it's null then Camel will auto-generate a filename based on the message unique ID.

CamelFileNameProduced

The actual absolute filepath (path + name) for the output file that was written. This header is set by Camel and its purpose is providing end-users with the name of the file that was written.

CamelOverruleFileName

Camel 2.11: Is used for overruling CamelFileName header and use the value instead (but only once, as the producer will remove this header after writing the file). The value can be only be a String. Notice that if the option fileName has been configured, then this is still being evaluated.

File consumer only

Header

Description

CamelFileName

Name of the consumed file as a relative file path with offset from the starting directory configured on the endpoint.

CamelFileNameOnly

Only the file name (the name with no leading paths).

CamelFileAbsolute

A boolean option specifying whether the consumed file denotes an absolute path or not. Should normally be false for relative paths. Absolute paths should normally not be used but we added to the move option to allow moving files to absolute paths. But can be used elsewhere as well.

CamelFileAbsolutePath

The absolute path to the file. For relative files this path holds the relative path instead.

CamelFilePath

The file path. For relative files this is the starting directory + the relative filename. For absolute files this is the absolute path.

CamelFileRelativePath

The relative path.

CamelFileParent

The parent path.

CamelFileLength

A long value containing the file size.

CamelFileLastModified

A Long value containing the last modified timestamp of the file. In Camel 2.10.3 and older the type is Date.

Batch Consumer

This component implements the Batch Consumer.

Exchange Properties, file consumer only

As the file consumer is BatchConsumer it supports batching the files it polls. By batching it means that Camel will add some properties to the Exchange so you know the number of files polled the current index in that order.

Property

Description

CamelBatchSize

The total number of files that was polled in this batch.

CamelBatchIndex

The current index of the batch. Starts from 0.

CamelBatchComplete

A boolean value indicating the last Exchange in the batch. Is only true for the last entry.

This allows you for instance to know how many files exists 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 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 read lock options rely on Java File API that sadly is not always very good at detecting this. You may also want to look at the doneFileName option, which uses a marker file (done) 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 file name done 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 onwards Camel will not automatic delete the done file if noop=true is configured.

However its 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 af file you may want to write an additional done file as a kinda 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 its 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.

Samples

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 written to a directory.

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 expression 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 onwards 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:

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.

Then we need to setup a Spring jpaTemplate in the spring XML file:

And finally we can create our JPA idempotent repository in the spring XML file as well:

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:

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

New options from Camel 2.10 onwards

Icon

There are now antInclude and antExclude options to make it easy to specify ANT style include/exclude without having to define the filter. See the URI options above for more information.

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:

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:

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:

URI options can reference beans using the # syntax

Icon

In the Spring DSL route about notice that we can refer to beans in the Registry by prefixing the id with #. So writing sorter=#mySorter, will instruct Camel to go look in the Registry for a bean with the ID, mySorter.

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 the 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 onwards, 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:

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 (eg 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.

Easier with Camel 2.10

Icon

The new option consumer.bridgeErrorHandler can be set to true, to make this even easier. See further below for more details.

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":

MyExceptionHandler

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"/>:

Camel route with routing engine error handling

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:

Using consumer.bridgeErrorHandler

So all you have to do is to enable this option, and the error handler in the route will take it from there.

Important when using consumer.bridgeErrorHandler

Icon

When using consumer.bridgeErrorHandler, then interceptors, OnCompletions does not apply. The Exchange is processed directly by the Camel Error Handler, and does not allow prior actions such as interceptors, onCompletion to take action.

Debug logging

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

See Also

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:

URI format

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

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

URI Options

Name

Default Value

Description

delimiter

,

The default character delimiter for delimited files.

textQualifier

"

The text qualifier for delimited files.

ignoreFirstRecord

true

Whether the first line is ignored for delimited files (for the column headers).

splitRows

true

The component can either process each row one by one or the entire content at once.

allowShortLines

false

Camel 2.9.7 and 2.10.5 onwards: Allows for lines to be shorter than expected and ignores the extra characters.

ignoreExtraColumns

false

Camel 2.9.7 and 2.10.5 onwards: Allows for lines to be longer than expected and ignores the extra characters.

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:

Header

Description

camelFlatpackCounter

The current row index. For splitRows=false the counter is the total number of rows.

Message Body

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

For example to get the firstname from the sample below:

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

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.

Using the endpoint

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

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

Flatpack DataFormat

The Flatpack component ships with the Flatpack data format that can be used to format between fixed width or delimited text messages to a List of rows as Map.

  • marshal = from List<Map<String, Object>> to OutputStream (can be converted to String)
  • unmarshal = from java.io.InputStream (such as a File or String) to a java.util.List as an org.apache.camel.component.flatpack.DataSetList instance.
    The result of the operation will contain all the data. If you need to process each row one by one you can split the exchange, using Splitter.

Notice: The Flatpack library does currently not support header and trailers for the marshal operation.

Options

The data format has the following options:

Option

Default

Description

definition

null

The flatpack pzmap configuration file. Can be omitted in simpler situations, but its preferred to use the pzmap.

fixed

false

Delimited or fixed.

ignoreFirstRecord

true

Whether the first line is ignored for delimited files (for the column headers).

textQualifier

"

If the text is qualified with a char such as ".

delimiter

,

The delimiter char (could be ; , or similar)

parserFactory

null

Uses the default Flatpack parser factory.

allowShortLines

false

Camel 2.9.7 and 2.10.5 onwards: Allows for lines to be shorter than expected and ignores the extra characters.

ignoreExtraColumns

false

Camel 2.9.7 and 2.10.5 onwards: Allows for lines to be longer than expected and ignores the extra characters.

Usage

To use the data format, simply instantiate an instance and invoke the marshal or unmarshal operation in the route builder:

The sample above will read files from the order/in folder and unmarshal the input using the Flatpack configuration file INVENTORY-Delimited.pzmap.xml that configures the structure of the files. The result is a DataSetList object we store on the SEDA queue.

In the code above we marshal the data from a Object representation as a List of rows as Maps. The rows as Map contains the column name as the key, and the the corresponding value. This structure can be created in Java code from e.g. a processor. We marshal the data according to the Flatpack format and convert the result as a String object and store it on a JMS queue.

Dependencies

To use Flatpack in your camel routes you need to add the a dependency on camel-flatpack which implements this data format.

If you use maven you could just add the following to your pom.xml, substituting the version number for the latest & greatest release (see the download page for the latest versions).

See Also

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

Option

Default

Description

contentCache

true

Cache for the resource content when it's loaded.
Note: as of Camel 2.9 cached resource content can be cleared via JMX using the endpoint's clearContentCache operation.

encoding

null

Character encoding of the resource content.

templateUpdateDelay

5

Camel 2.9: Number of seconds the loaded template resource will remain in the cache.

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:

key

value

exchange

The Exchange itself.

exchange.properties

The Exchange properties.

headers

The headers of the In message.

camelContext

The Camel Context.

request

The In message.

body

The In message body.

response

The Out message (only for InOut message exchange pattern).

Hot reloading

The FreeMarker template resource is by default not hot reloadable for both 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.

Header

Type

Description

Support Version

FreemarkerConstants.FREEMARKER_RESOURCE

org.springframework.core.io.Resource

The template resource

<= 2.1

FreemarkerConstants.FREEMARKER_RESOURCE_URI

String

A URI for the template resource to use instead of the endpoint configured.

>= 2.1

FreemarkerConstants.FREEMARKER_TEMPLATE

String

The template to use instead of the endpoint configured.

>= 2.1

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:

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:

More options

Icon

See File for more options as all the options from File is inherited.

Consuming from remote FTP server

Icon

Make sure you read the section titled Default when consuming files further below for details related to consuming files.

URI format

Where directoryname represents the underlying directory. Can contain nested folders.

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

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

This component uses two 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.

More options

Icon

See File for more options as all the options from File is inherited.

Name

Default Value

Description

username

null

Specifies the username to use to log in to the remote file systen.

password

null

Specifies the password to use to log in to the remote file system.

binary

false

Specifies the file transfer mode, BINARY or ASCII. Default is ASCII (false).

disconnect

false

Camel 2.2: Whether or not to disconnect from remote FTP server right after use. Can be used for both consumer and producer. Disconnect will only disconnect the current connection to the FTP server. If you have a consumer which you want to stop, then you need to stop the consumer/route instead.

localWorkDirectory

null

When consuming, a local work directory can be used to store the remote file content directly in local files, to avoid loading the content into memory. This is beneficial, if you consume a very big remote file and thus can conserve memory. See below for more details.

passiveMode

false

FTP and FTPS only: Specifies whether to use passive mode connections. Default is active mode (false).

securityProtocol

TLS

FTPS only: Sets the underlying security protocol. The following values are defined:
TLS: Transport Layer Security
SSL: Secure Sockets Layer

disableSecureDataChannelDefaults

false

Camel 2.4: FTPS only: Whether or not to disable using default values for execPbsz and execProt when using secure data transfer. You can set this option to true if you want to be in absolute full control what the options execPbsz and execProt should be used.

download

true

Camel 2.11: Whether the FTP consumer should download the file. If this option is set to false, then the message body will be null, but the consumer will still trigger a Camel Exchange that has details about the file such as file name, file size, etc. It's just that the file will not be downloaded.

streamDownload

false

Camel 2.11: Whether the consumer should download the entire file up front, the default behavior, or if it should pass an InputStream read from the remote resource rather than an in-memory array as the in body of the Camel Exchange.  This option is ignored if download is false or is localWorkDirectory is provided.  This option is useful for working with large remote files.

execProt

null

Camel 2.4: FTPS only: Will by default use option P if secure data channel defaults hasn't been disabled. Possible values are:
C: Clear
S: Safe (SSL protocol only)
E: Confidential (SSL protocol only)
P: Private

execPbsz

null

Camel 2.4: FTPS only: This option specifies the buffer size of the secure data channel. If option useSecureDataChannel has been enabled and this option has not been explicit set, then value 0 is used.

isImplicit

false

FTPS only: Sets the security mode(implicit/explicit). Default is explicit (false).

knownHostsFile

null

SFTP only: Sets the known_hosts file, so that the SFTP endpoint can do host key verification.

knownHostsUri

null

SFTP only: Camel 2.11.1: Sets the known_hosts file (loaded from classpath by default), so that the SFTP endpoint can do host key verification.

keyPair

null

SFTP only: Camel 2.12.0: Sets the Java KeyPair for SSH public key authentication, it supports DSA or RSA keys.

privateKeyFile

null

SFTP only: Set the private key file to that the SFTP endpoint can do private key verification.

privateKeyUri

null

SFTP only: Camel 2.11.1: Set the private key file (loaded from classpath by default) to that the SFTP endpoint can do private key verification.

privateKey

null

SFTP only: Camel 2.11.1: Set the private key as byte[] to that the SFTP endpoint can do private key verification.

privateKeyFilePassphrase

null

SFTP only: Deprecated: use privateKeyPassphrase instead. Set the private key file passphrase to that the SFTP endpoint can do private key verification.

privateKeyPassphrase

null

SFTP only: Camel 2.11.1: Set the private key file passphrase to that the SFTP endpoint can do private key verification.

preferredAuthentications

null

SFTP only: Camel 2.10.7, 2.11.2,2.12.0: set the preferred authentications which SFTP endpoint will used. Some example include:password,publickey. If not specified the default list from JSCH will be used.

ciphers

null

Camel 2.8.2, 2.9: SFTP only Set a comma separated list of ciphers that will be used in order of preference. Possible cipher names are defined by JCraft JSCH. Some examples include: aes128-ctr,aes128-cbc,3des-ctr,3des-cbc,blowfish-cbc,aes192-cbc,aes256-cbc. If not specified the default list from JSCH will be used.

fastExistsCheck

false

Camel 2.8.2, 2.9: If set this option to be true, camel-ftp will use the list file directly to check if the file exists. Since some FTP server may not support to list the file directly, if the option is false, camel-ftp will use the old way to list the directory and check if the file exists. Note from Camel 2.10.1 onwards this option also influences readLock=changed to control whether it performs a fast check to update file information or not. This can be used to speed up the process if the FTP server has a lot of files.

strictHostKeyChecking

no

SFTP only: Camel 2.2: Sets whether to use strict host key checking. Possible values are: no, yes and ask. ask does not make sense to use as Camel cannot answer the question for you as its meant for human intervention. Note: The default in Camel 2.1 and below was ask.

maximumReconnectAttempts

3

Specifies the maximum reconnect attempts Camel performs when it tries to connect to the remote FTP server. Use 0 to disable this behavior.

reconnectDelay

1000

Delay in millis Camel will wait before performing a reconnect attempt.

connectTimeout

10000

Camel 2.4: Is the connect timeout in millis. This corresponds to using ftpClient.connectTimeout for the FTP/FTPS. For SFTP this option is also used when attempting to connect.

soTimeout

null

FTP and FTPS Only: Camel 2.4: Is the SocketOptions.SO_TIMEOUT value in millis. Note SFTP will automatic use the connectTimeout as the soTimeout.

timeout

30000

FTP and FTPS Only: Camel 2.4: Is the data timeout in millis. This corresponds to using ftpClient.dataTimeout for the FTP/FTPS. For SFTP there is no data timeout.

throwExceptionOnConnectFailed

false

Camel 2.5: Whether or not to thrown an exception if a successful connection and login could not be establish. This allows a custom pollStrategy to deal with the exception, for example to stop the consumer or the likes.

siteCommand

null

FTP and FTPS Only: Camel 2.5: To execute site commands after successful login. Multiple site commands can be separated using a new line character (\n). Use help site to see which site commands your FTP server supports.

stepwise

true

Camel 2.6: Whether or not stepwise traversing directories should be used or not. Stepwise means that it will CD one directory at a time. See more details below. You can disable this in case you can't use this approach.

separator

Auto

Camel 2.6: Dictates what path separator char to use when uploading files. Auto = Use the path provided without altering it. UNIX = Use unix style path separators. Windows = Use Windows style path separators.

chmod

null

SFTP Producer Only: Camel 2.9: Allows you to set chmod on the stored file. For example chmod=640.

compression

0

SFTP Only: Camel 2.8.3/2.9: To use compression. Specify a level from 1 to 10. Important: You must manually add the needed JSCH zlib JAR to the classpath for compression support.

ftpClient

null

FTP and FTPS Only: Camel 2.1: Allows you to use a custom org.apache.commons.net.ftp.FTPClient instance.

ftpClientConfig

null

FTP and FTPS Only: Camel 2.1: Allows you to use a custom org.apache.commons.net.ftp.FTPClientConfig instance.

serverAliveInterval

0

SFTP Only: Camel 2.8 Allows you to set the serverAliveInterval of the sftp session

serverAliveCountMax

1

SFTP Only: Camel 2.8 Allows you to set the serverAliveCountMax of the sftp session

ftpClient.trustStore.file

null

FTPS Only: Sets the trust store file, so that the FTPS client can look up for trusted certificates.

ftpClient.trustStore.type

JKS

FTPS Only: Sets the trust store type.

ftpClient.trustStore.algorithm

SunX509

FTPS Only: Sets the trust store algorithm.

ftpClient.trustStore.password

null

FTPS Only: Sets the trust store password.

ftpClient.keyStore.file

null

FTPS Only: Sets the key store file, so that the FTPS client can look up for the private certificate.

ftpClient.keyStore.type

JKS

FTPS Only: Sets the key store type.

ftpClient.keyStore.algorithm

SunX509

FTPS Only: Sets the key store algorithm.

ftpClient.keyStore.password

null

FTPS Only: Sets the key store password.

ftpClient.keyStore.keyPassword

null

FTPS Only: Sets the private key password.

sslContextParameters

null

FTPS Only: Camel 2.9: Reference to a org.apache.camel.util.jsse.SSLContextParameters in the Registry.  This reference overrides any configured SSL related options on ftpClient as well as the securityProtocol (SSL, TLS, etc.) set on FtpsConfiguration.  See Using the JSSE Configuration Utility.

proxy

null

SFTP Only: Camel 2.10.7, 2.11.1: Reference to a com.jcraft.jsch.Proxy in the Registry.  This proxy is used to consume/send messages from the target SFTP host.

useList

true

FTP/FTPS Only: Camel 2.12.1: Whether the consumer should use FTP LIST command to retrieve directory listing to see which files exists. If this option is set to false, then stepwise=false must be configured, and also fileName must be configured to a fixed name, so the consumer knows the name of the file to retrieve. When doing this only that single file can be retrieved. See further below for more details.

ignoreFileNotFoundOrPermissionError

false

Camel 2.12.1: Whether the consumer should ignore when a file was attempted to be retrieved but did not exist (for some reason), or failure due insufficient file permission error.

FTPS component default trust store

Icon

When using the ftpClient. properties related to SSL with the FTPS component, the trust store accept all certificates. If you only want trust selective certificates, you have to configure the trust store with the ftpClient.trustStore.xxx options or by configuring a custom ftpClient.

When using sslContextParameters, the trust store is managed by the configuration of the provided SSLContextParameters instance.

You can configure additional options on the ftpClient and ftpClientConfig from the URI directly by using the ftpClient. or ftpClientConfig. prefix.

For example to set the setDataTimeout on the FTPClient to 30 seconds you can do:

You can mix and match and have use both prefixes, for example to configure date format or timezones.

You can have as many of these options as you like.

See the documentation of the Apache Commons FTP FTPClientConfig for possible options and more details.
And as well for Apache Commons FTP FTPClient.

If you do not like having many and long configuration in the url you can refer to the ftpClient or ftpClientConfig to use by letting Camel lookup in the Registry for it.

For example:

And then let Camel lookup this bean when you use the # notation in the url.

More URI options

Icon

See File2 as all the options there also applies for this component.

Examples

ftp://someone@someftpserver.com/public/upload/images/holiday2008?password=secret&binary=true
ftp://someoneelse@someotherftpserver.co.uk:12049/reports/2008/password=secret&binary=false
ftp://publicftpserver.com/download

FTP Consumer does not support concurrency

Icon

The FTP consumer (with the same endpoint) does not support concurrency (the backing FTP client is not thread safe).
You can use multiple FTP consumers to poll from different endpoints. It is only a single endpoint that does not support concurrent consumers.

The FTP producer does not have this issue, it supports concurrency.

More information

Icon

This component is an extension of the File component. So there are more samples and details on the File component page.

Default when consuming files

The FTP consumer will by default leave the consumed files untouched on the remote FTP server. You have to configure it explicitly if you want it to delete the files or move them to another location. For example you can use delete=true to delete the files, or use move=.done to move the files into a hidden done sub directory.

The regular File consumer is different as it will by default move files to a .camel sub directory. The reason Camel does not do this by default for the FTP consumer is that it may lack permissions by default to be able to move or delete files.

limitations

The option readLock can be used to force Camel not to consume files that is currently in the progress of being written. However, this option is turned off by default, as it requires that the user has write access. See the options table at File2 for more details about read locks.
There are other solutions to avoid consuming files that are currently being written over FTP; for instance, you can write to a temporary destination and move the file after it has been written.

When moving files using move or preMove option the files are restricted to the FTP_ROOT folder. That prevents you from moving files outside the FTP area. If you want to move files to another area you can use soft links and move files into a soft linked folder.

Message Headers

The following message headers can be used to affect the behavior of the component

Header

Description

CamelFileName

Specifies the output file name (relative to the endpoint directory) to be used for the output message when sending to the endpoint. If this is not present and no expression either, then a generated message ID is used as the filename instead.

CamelFileNameProduced

The actual absolute filepath (path + name) for the output file that was written. This header is set by Camel and its purpose is providing end-users the name of the file that was written.

CamelFileBatchIndex

Current index out of total number of files being consumed in this batch.

CamelFileBatchSize

Total number of files being consumed in this batch.

CamelFileHost

The remote hostname.

CamelFileLocalWorkPath

Path to the local work file, if local work directory is used.

In addition the FTP/FTPS consumer and producer will enrich the Camel Message with the following headers

Header

Description

CamelFtpReplyCode

Camel 2.11.1: The FTP client reply code (the type is a integer)

CamelFtpReplyString

Camel 2.11.1: The FTP client reply string

About timeouts

The two set of libraries (see top) has different API for setting timeout. You can use the connectTimeout option for both of them to set a timeout in millis to establish a network connection. An individual soTimeout can also be set on the FTP/FTPS, which corresponds to using ftpClient.soTimeout. Notice SFTP will automatically use connectTimeout as its soTimeout. The timeout option only applies for FTP/FTSP as the data timeout, which corresponds to the ftpClient.dataTimeout value. All timeout values are in millis.

Using Local Work Directory

Camel supports consuming from remote FTP servers and downloading the files directly into a local work directory. This avoids reading the entire remote file content into memory as it is streamed directly into the local file using FileOutputStream.

Camel will store to a local file with the same name as the remote file, though with .inprogress as extension while the file is being downloaded. Afterwards, the file is renamed to remove the .inprogress suffix. And finally, when the Exchange is complete the local file is deleted.

So if you want to download files from a remote FTP server and store it as files then you need to route to a file endpoint such as:

Optimization by renaming work file

Icon

The route above is ultra efficient as it avoids reading the entire file content into memory. It will download the remote file directly to a local file stream. The java.io.File handle is then used as the Exchange body. The file producer leverages this fact and can work directly on the work file java.io.File handle and perform a java.io.File.rename to the target filename. As Camel knows it's a local work file, it can optimize and use a rename instead of a file copy, as the work file is meant to be deleted anyway.

Stepwise changing directories

Camel FTP can operate in two modes in terms of traversing directories when consuming files (eg downloading) or producing files (eg uploading)

  • stepwise
  • not stepwise

You may want to pick either one depending on your situation and security issues. Some Camel end users can only download files if they use stepwise, while others can only download if they do not. At least you have the choice to pick (from Camel 2.6 onwards).

In Camel 2.0 - 2.5 there is only one mode and it is:

  • before 2.5 not stepwise
  • 2.5 stepwise

From Camel 2.6 onwards there is now an option stepwise you can use to control the behavior.

Note that stepwise changing of directory will in most cases only work when the user is confined to it's home directory and when the home directory is reported as "/".

The difference between the two of them is best illustrated with an example. Suppose we have the following directory structure on the remote FTP server we need to traverse and download files:

And that we have a file in each of sub-a (a.txt) and sub-b (b.txt) folder.

Using stepwise=true (default mode)

As you can see when stepwise is enabled, it will traverse the directory structure using CD xxx.

Using stepwise=false

As you can see when not using stepwise, there are no CD operation invoked at all.

Samples

In the sample below we set up Camel to download all the reports from the FTP server once every hour (60 min) as BINARY content and store it as files on the local file system.

And the route using Spring DSL:

Consuming a remote FTPS server (implicit SSL) and client authentication

Consuming a remote FTPS server (explicit TLS) and a custom trust store configuration

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

Camel supports pluggable filtering strategies. This strategy it to use the build in org.apache.camel.component.file.GenericFileFilter in Java. You can then configure the endpoint with such a filter to skip certain filters before being processed.

In the sample we have built our own filter that only accepts files starting with report in the filename.

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 a filter that is shipped out-of-the-box in the camel-spring jar. So you need to depend on camel-spring if you are using Maven.
The reason is that we leverage Spring's AntPathMatcher to do the actual matching.

The file paths are matched with the following rules:

  • ? matches one character
  • * matches zero or more characters
  • ** matches zero or more directories in a path

The sample below demonstrates how to use it:

Using a proxy with SFTP

To use an HTTP proxy to connect to your remote host, you can configure your route in the following way:

You can also assign a user name and password to the proxy, if necessary. Please consult the documentation for com.jcraft.jsch.Proxy to discover all options.

Setting preferred SFTP authentication method

If you want to explicitly specify the list of authentication methods that should be used by sftp component, use preferredAuthentications option. If for example you would like Camel to attempt to authenticate with private/public SSH key and fallback to user/password authentication in the case when no public key is available, use the following route configuration:

Consuming a single file using a fixed name

When you want to download a single file and knows the file name, you can use fileName=myFileName.txt to tell Camel the name of the file to download. By default the consumer will still do a FTP LIST command to do a directory listing and then filter these files based on the fileName option. Though in this use-case it may be desirable to turn off the directory listing by setting useList=false. For example the user account used to login to the FTP server may not have permission to do a FTP LIST command. So you can turn off this with useList=false, and then provide the fixed name of the file to download with fileName=myFileName.txt, then the FTP consumer can still download the file. If the file for some reason does not exist, then Camel will by default throw an exception, you can turn this off and ignore this by setting ignoreFileNotFoundOrPermissionError=true.

For example to have a Camel route that pickup a single file, and delete it after use you can do

Notice that we have use all the options we talked above above.

You can also use this with ConsumerTemplate. For example to download a single file (if it exists) and grab the file content as a String type:

Debug logging

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

See Also

Camel Components for Google App Engine

Tutorials

Icon

The Camel components for Google App Engine (GAE) are part of the camel-gae project and provide connectivity to GAE's cloud computing services. They make the GAE cloud computing environment accessible to applications via Camel interfaces. Following this pattern for other cloud computing environments could make it easier to port Camel applications from one cloud computing provider to another. The following table lists the cloud computing services provided by Google and the supporting Camel components. The documentation of each component can be found by following the link in the Camel Component column.

GAE service

Camel component

Component description

URL fetch service

ghttp

Provides connectivity to the GAE URL fetch service but can also be used to receive messages from servlets.

Task queueing service

gtask

Supports asynchronous message processing on GAE by using the task queueing service as message queue.

Mail service

gmail

Supports sending of emails via the GAE mail service. Receiving mails is not supported yet but will be added later.

Memcache service

 

Not supported yet.

XMPP service

 

Not supported yet.

Images service

 

Not supported yet.

Datastore service

 

Not supported yet.

Accounts service

gauth
glogin

These components interact with the Google Accounts API for authentication and authorization. Google Accounts is not specific to Google App Engine but is often used by GAE applications for implementing security. The gauth component is used by web applications to implement a Google-specific OAuth consumer. This component can also be used to OAuth-enable non-GAE web applications. The glogin component is used by Java clients (outside GAE) for programmatic login to GAE applications. For instructions how to protect GAE applications against unauthorized access refer to the Security for Camel GAE applications page.

Camel context

Setting up a SpringCamelContext on Google App Engine differs between Camel 2.1 and higher versions. The problem is that usage of the Camel-specific Spring configuration XML schema from the http://camel.apache.org/schema/spring namespace requires JAXB and Camel 2.1 depends on a Google App Engine SDK version that doesn't support JAXB yet. This limitation has been removed since Camel 2.2.

JMX must be disabled in any case because the javax.management package isn't on the App Engine JRE whitelist.

Camel 2.1

camel-gae 2.1 comes with the following CamelContext implementations.

  • org.apache.camel.component.gae.context.GaeDefaultCamelContext (extends org.apache.camel.impl.DefaultCamelContext)
  • org.apache.camel.component.gae.context.GaeSpringCamelContext (extends org.apache.camel.spring.SpringCamelContext)

Both disable JMX before startup. The GaeSpringCamelContext additionally provides setter methods adding route builders as shown in the next example.

appctx.xml

Alternatively, use the routeBuilders property of the GaeSpringCamelContext for setting a list of route builders. Using this approach, a SpringCamelContext can be configured on GAE without the need for JAXB.

Camel 2.2 or higher

With Camel 2.2 or higher, applications can use the http://camel.apache.org/schema/spring namespace for configuring a SpringCamelContext but still need to disable JMX. Here's an example.

appctx.xml

The web.xml

Running Camel on GAE requires usage of the CamelHttpTransportServlet from camel-servlet. The following example shows how to configure this servlet together with a Spring application context XML file.

web.xml

The location of the Spring application context XML file is given by the contextConfigLocation init parameter. The appctx.xml file must be on the classpath. The servlet mapping makes the Camel application accessible under http://<appname>.appspot.com/camel/... when deployed to Google App Engine where <appname> must be replaced by a real GAE application name. The second servlet mapping is used internally by the task queueing service for background processing via web hooks. This mapping is relevant for the gtask component and is explained there in more detail.

Hazelcast Component

Available as of Camel 2.7

The hazelcast: component allows you to work with the Hazelcast distributed data grid / cache. Hazelcast is a in memory data grid, entirely written in Java (single jar). It offers a great palette of different data stores like map, multi map (same key, n values), queue, list and atomic number. The main reason to use Hazelcast is its simple cluster support. If you have enabled multicast on your network you can run a cluster with hundred nodes with no extra configuration. Hazelcast can simply configured to add additional features like n copies between nodes (default is 1), cache persistence, network configuration (if needed), near cache, enviction and so on. For more information consult the Hazelcast documentation on http://www.hazelcast.com/docs.jsp.

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

URI format

Icon

You have to use the second prefix to define which type of data store you want to use.

Sections

  1. Usage of #map
  2. Usage of #multimap
  3. Usage of #queue
  4. Usage of #list
  5. Usage of #seda
  6. Usage of atomic number
  7. Usage of #cluster support (instance)

Usage of Map

map cache producer - to("hazelcast:map:foo")

If you want to store a value in a map you can use the map cache producer. The map cache producer provides 5 operations (put, get, update, delete, query). For the first 4 you have to provide the operation inside the "hazelcast.operation.type" header variable. In Java DSL you can use the constants from org.apache.camel.component.hazelcast.HazelcastConstants.

Header Variables for the request message:

Name

Type

Description

hazelcast.operation.type

String

valid values are: put, delete, get, update, query

hazelcast.objectId

String

the object id to store / find your object inside the cache (not needed for the query operation)

Icon

Header variables have changed in Camel 2.8

Name

Type

Description

CamelHazelcastOperationType

String

valid values are: put, delete, get, update, query Version 2.8

CamelHazelcastObjectId

String

the object id to store / find your object inside the cache (not needed for the query operation) Version 2.8

You can call the samples with:

Sample for put:

Java DSL:

Spring DSL:

Sample for get:

Java DSL:

Spring DSL:

Sample for update:

Java DSL:

Spring DSL:

Sample for delete:

Java DSL:

Spring DSL:

Sample for query

Java DSL:

Spring DSL:

For the query operation Hazelcast offers a SQL like syntax to query your distributed map.

map cache consumer - from("hazelcast:map:foo")

Hazelcast provides event listeners on their data grid. If you want to be notified if a cache will be manipulated, you can use the map consumer. There're 4 events: put, update, delete and envict. The event type will be stored in the "hazelcast.listener.action" header variable. The map consumer provides some additional information inside these variables:

Header Variables inside the response message:

Name

Type

Description

hazelcast.listener.time

Long

time of the event in millis

hazelcast.listener.type

String

the map consumer sets here "cachelistener"

hazelcast.listener.action

String

type of event - here added, updated, envicted and removed

hazelcast.objectId

String

the oid of the object

hazelcast.cache.name

String

the name of the cache - e.g. "foo"

hazelcast.cache.type

String

the type of the cache - here map

Icon

Header variables have changed in Camel 2.8

Name

Type

Description

CamelHazelcastListenerTime

Long

time of the event in millis Version 2.8

CamelHazelcastListenerType

String

the map consumer sets here "cachelistener" Version 2.8

CamelHazelcastListenerAction

String

type of event - here added, updated, envicted and removed. Version 2.8

CamelHazelcastObjectId

String

the oid of the object Version 2.8

CamelHazelcastCacheName

String

the name of the cache - e.g. "foo" Version 2.8

CamelHazelcastCacheType

String

the type of the cache - here map Version 2.8

The object value will be stored within put and update actions inside the message body.

Here's a sample:

Usage of Multi Map

multimap cache producer - to("hazelcast:multimap:foo")

A multimap is a cache where you can store n values to one key. The multimap producer provides 4 operations (put, get, removevalue, delete).

Header Variables for the request message:

Name

Type

Description

hazelcast.operation.type

String

valid values are: put, get, removevalue, delete

hazelcast.objectId

String

the object id to store / find your object inside the cache

Icon

Header variables have changed in Camel 2.8

Name

Type

Description

CamelHazelcastOperationType

String

valid values are: put, delete, get, update, query Available as of Camel 2.8

CamelHazelcastObjectId

String

the object id to store / find your object inside the cache (not needed for the query operation) Version 2.8

You can call the samples with:

Sample for put:

Java DSL:

Spring DSL:

Sample for get:

Java DSL:

Spring DSL:

Sample for update:

Java DSL:

Spring DSL:

Sample for delete:

Java DSL:

Spring DSL:

Sample for query

Java DSL:

Spring DSL:

For the query operation Hazelcast offers a SQL like syntax to query your distributed map.

map cache consumer - from("hazelcast:map:foo")

Hazelcast provides event listeners on their data grid. If you want to be notified if a cache will be manipulated, you can use the map consumer. There're 4 events: put, update, delete and envict. The event type will be stored in the "hazelcast.listener.action" header variable. The map consumer provides some additional information inside these variables:

Header Variables inside the response message:

Name

Type

Description

hazelcast.listener.time

Long

time of the event in millis

hazelcast.listener.type

String

the map consumer sets here "cachelistener"

hazelcast.listener.action

String

type of event - here added, updated, envicted and removed

hazelcast.objectId

String

the oid of the object

hazelcast.cache.name

String

the name of the cache - e.g. "foo"

hazelcast.cache.type

String

the type of the cache - here map

Icon

Header variables have changed in Camel 2.8

Name

Type

Description

CamelHazelcastListenerTime

Long

time of the event in millis Version 2.8

CamelHazelcastListenerType

String

the map consumer sets here "cachelistener" Version 2.8

CamelHazelcastListenerAction

String

type of event - here added, updated, envicted and removed. Version 2.8

CamelHazelcastObjectId

String

the oid of the object Version 2.8

CamelHazelcastCacheName

String

the name of the cache - e.g. "foo" Version 2.8

CamelHazelcastCacheType

String

the type of the cache - here map Version 2.8

The object value will be stored within put and update actions inside the message body.

Here's a sample:

Usage of Multi Map

multimap cache producer - to("hazelcast:multimap:foo")

A multimap is a cache where you can store n values to one key. The multimap producer provides 4 operations (put, get, removevalue, delete).

Header Variables for the request message:

Name

Type

Description

hazelcast.operation.type

String

valid values are: put, get, removevalue, delete

hazelcast.objectId

String

the object id to store / find your object inside the cache

Icon

Header variables have changed in Camel 2.8

Name

Type

Description

CamelHazelcastOperationType

String

valid values are: put, get, removevalue, delete Version 2.8

CamelHazelcastObjectId

String

the object id to store / find your object inside the cache Version 2.8

Sample for put:

Java DSL:

Spring DSL:

Sample for removevalue:

Java DSL:

Spring DSL:

To remove a value you have to provide the value you want to remove inside the message body. If you have a multimap object {key: "4711" values: { "my-foo", "my-bar"}} you have to put "my-foo" inside the message body to remove the "my-foo" value.

Sample for get:

Java DSL:

Spring DSL:

Sample for delete:

Java DSL:

Spring DSL:

you can call them in your test class with:

multimap cache consumer - from("hazelcast:multimap:foo")

For the multimap cache this component provides the same listeners / variables as for the map cache consumer (except the update and enviction listener). The only difference is the multimap prefix inside the URI. Here is a sample:

Header Variables inside the response message:

Name

Type

Description

hazelcast.listener.time

Long

time of the event in millis

hazelcast.listener.type

String

the map consumer sets here "cachelistener"

hazelcast.listener.action

String

type of event - here added and removed (and soon envicted)

hazelcast.objectId

String

the oid of the object

hazelcast.cache.name

String

the name of the cache - e.g. "foo"

hazelcast.cache.type

String

the type of the cache - here multimap

Eviction will be added as feature, soon (this is a Hazelcast issue).

Icon

Header variables have changed in Camel 2.8

Name

Type

Description

CamelHazelcastListenerTime

Long

time of the event in millis Version 2.8

CamelHazelcastListenerType

String

the map consumer sets here "cachelistener" Version 2.8

CamelHazelcastListenerAction

String

type of event - here added and removed (and soon envicted) Version 2.8

CamelHazelcastObjectId

String

the oid of the object Version 2.8

CamelHazelcastCacheName

String

the name of the cache - e.g. "foo" Version 2.8

CamelHazelcastCacheType

String

the type of the cache - here multimap Version 2.8

Usage of Queue

Queue producer – to(“hazelcast:queue:foo”)

The queue producer provides 6 operations (add, put, poll, peek, offer, removevalue).

Sample for add:
Sample for put:
Sample for poll:
Sample for peek:
Sample for offer:
Sample for removevalue:

Queue consumer – from(“hazelcast:queue:foo”)

The queue consumer provides 2 operations (add, remove).

Usage of List

List producer – to(“hazelcast:list:foo”)

The list producer provides 4 operations (add, set, get, removevalue).

Sample for add:
Sample for get:
Sample for setvalue:
Sample for removevalue:
Icon

Please note that set,get and removevalue and not yet supported by hazelcast, will be added in the future..

List consumer – from(“hazelcast:list:foo”)

The list consumer provides 2 operations (add, remove).

Usage of SEDA

SEDA component differs from the rest components provided. It implements a work-queue in order to support asynchronous SEDA architectures, similar to the core "SEDA" component.

SEDA producer – to(“hazelcast:seda:foo”)

The SEDA producer provides no operations. You only send data to the specified queue.

Name

default value

Description

transferExchange

false

Camel 2.8.0: if set to true the whole Exchange will be transfered. If header or body contains not serializable objects, they will be skipped.

Java DSL :

Spring DSL :

SEDA consumer – from(“hazelcast:seda:foo”)

The SEDA consumer provides no operations. You only retrieve data from the specified queue.

Name

default value

Description

pollInterval

1000

How frequent to poll from the SEDA queue

concurrentConsumers

1

To use concurrent consumers polling from the SEDA queue.

transferExchange

false

Camel 2.8.0: if set to true the whole Exchange will be transfered. If header or body contains not serializable objects, they will be skipped.

transacted

false

Camel 2.10.4: if set to true then the consumer runs in transaction mode, where the messages in the seda queue will only be removed if the transaction commits, which happens when the processing is complete.

Java DSL :

Spring DSL:

Usage of Atomic Number

Icon

There is no consumer for this endpoint!

atomic number producer - to("hazelcast:atomicnumber:foo")

An atomic number is an object that simply provides a grid wide number (long). The operations for this producer are setvalue (set the number with a given value), get, increase (+1), decrease (-1) and destroy.

Header Variables for the request message:

Name

Type

Description

hazelcast.operation.type

String

valid values are: setvalue, get, increase, decrease, destroy

Icon

Header variables have changed in Camel 2.8

Name

Type

Description

CamelHazelcastOperationType

String

valid values are: setvalue, get, increase, decrease, destroy Available as of Camel version 2.8

Sample for set:

Java DSL:

Spring DSL:

Provide the value to set inside the message body (here the value is 10): template.sendBody("direct:set", 10);

Sample for get:

Java DSL:

Spring DSL:

You can get the number with long body = template.requestBody("direct:get", null, Long.class);.

Sample for increment:

Java DSL:

Spring DSL:

The actual value (after increment) will be provided inside the message body.

Sample for decrement:

Java DSL:

Spring DSL:

The actual value (after decrement) will be provided inside the message body.

Sample for destroy
Icon

There's a bug inside Hazelcast. So this feature may not work properly. Will be fixed in 1.9.3.

Java DSL:

Spring DSL:

cluster support

Icon

This endpoint provides no producer!

instance consumer - from("hazelcast:instance:foo")

Hazelcast makes sense in one single "server node", but it's extremly powerful in a clustered environment. The instance consumer fires if a new cache instance will join or leave the cluster.

Here's a sample:

Each event provides the following information inside the message header:

Header Variables inside the response message:

Name

Type

Description

hazelcast.listener.time

Long

time of the event in millis

hazelcast.listener.type

String

the map consumer sets here "instancelistener"

hazelcast.listener.action

String

type of event - here added or removed

hazelcast.instance.host

String

host name of the instance

hazelcast.instance.port

Integer

port number of the instance

Icon

Header variables have changed in Camel 2.8

Name

Type

Description

CamelHazelcastListenerTime

Long

time of the event in millis Version 2.8

CamelHazelcastListenerType

String

the map consumer sets here "instancelistener" Version 2.8

CamelHazelcastListenerActionn

String

type of event - here added or removed. Version 2.8

CamelHazelcastInstanceHost

String

host name of the instance Version 2.8

CamelHazelcastInstancePort

Integer

port number of the instance Version 2.8

HDFS Component

Available as of Camel 2.8

The hdfs component enables you to read and write messages from/to an HDFS file system. HDFS is the distributed file system at the heart of Hadoop.

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

URI format

You can append query options to the URI in the following format, ?option=value&option=value&...
The path is treated in the following way:

  1. as a consumer, if it's a file, it just reads the file, otherwise if it represents a directory it scans all the file under the path satisfying the configured pattern. All the files under that directory must be of the same type.
  2. as a producer, if at least one split strategy is defined, the path is considered a directory and under that directory the producer creates a different file per split named using the configured UuidGenerator.

Options

Name

Default Value

Description

overwrite

true

The file can be overwritten

append

false

Append to existing file. Notice that not all HDFS file systems support the append option.

bufferSize

4096

The buffer size used by HDFS

replication

3

The HDFS replication factor

blockSize

67108864

The size of the HDFS blocks

fileType

NORMAL_FILE

It can be SEQUENCE_FILE, MAP_FILE, ARRAY_FILE, or BLOOMMAP_FILE, see Hadoop

fileSystemType

HDFS

It can be LOCAL for local filesystem

keyType

NULL

The type for the key in case of sequence or map files. See below.

valueType

TEXT

The type for the key in case of sequence or map files. See below.

splitStrategy

 

A string describing the strategy on how to split the file based on different criteria. See below.

openedSuffix

opened

When a file is opened for reading/writing the file is renamed with this suffix to avoid to read it during the writing phase.

readSuffix

read

Once the file has been read is renamed with this suffix to avoid to read it again.

initialDelay

0

For the consumer, how much to wait (milliseconds) before to start scanning the directory.

delay

0

The interval (milliseconds) between the directory scans.

pattern

*

The pattern used for scanning the directory

chunkSize

4096

When reading a normal file, this is split into chunks producing a message per chunk.

connectOnStartup

true

Camel 2.9.3/2.10.1: Whether to connect to the HDFS file system on starting the producer/consumer. If false then the connection is created on-demand. Notice that HDFS may take up till 15 minutes to establish a connection, as it has hardcoded 45 x 20 sec redelivery. By setting this option to false allows your application to startup, and not block for up till 15 minutes.

owner

 

Camel 2.13/2.12.4: The file owner must match this owner for the consumer to pickup the file. Otherwise the file is skipped.

KeyType and ValueType

  • NULL it means that the key or the value is absent
  • BYTE for writing a byte, the java Byte class is mapped into a BYTE
  • BYTES for writing a sequence of bytes. It maps the java ByteBuffer class
  • INT for writing java integer
  • FLOAT for writing java float
  • LONG for writing java long
  • DOUBLE for writing java double
  • TEXT for writing java strings

BYTES is also used with everything else, for example, in Camel a file is sent around as an InputStream, int this case is written in a sequence file or a map file as a sequence of bytes.

Splitting Strategy

In the current version of Hadoop opening a file in append mode is disabled since it's not very reliable. So, for the moment, it's only possible to create new files. The Camel HDFS endpoint tries to solve this problem in this way:

  • If the split strategy option has been defined, the hdfs path will be used as a directory and files will be created using the configured UuidGenerator
  • Every time a splitting condition is met, a new file is created.
    The splitStrategy option is defined as a string with the following syntax:
    splitStrategy=<ST>:<value>,<ST>:<value>,*

where <ST> can be:

  • BYTES a new file is created, and the old is closed when the number of written bytes is more than <value>
  • MESSAGES a new file is created, and the old is closed when the number of written messages is more than <value>
  • IDLE a new file is created, and the old is closed when no writing happened in the last <value> milliseconds
Icon

note that this strategy currently requires either setting an IDLE value or setting the HdfsConstants.HDFS_CLOSE header to false to use the BYTES/MESSAGES configuration...otherwise, the file will be closed with each message

for example:

it means: a new file is created either when it has been idle for more than 1 second or if more than 5 bytes have been written. So, running hadoop fs -ls /tmp/simple-file you'll see that multiple files have been created.

Message Headers

The following headers are supported by this component:

Producer only

Header

Description

CamelFileName

Camel 2.13: Specifies the name of the file to write (relative to the endpoint path). The name can be a String or an Expression object. Only relevant when not using a split strategy.

Controlling to close file stream

Available as of Camel 2.10.4

When using the HDFS producer without a split strategy, then the file output stream is by default closed after the write. However you may want to keep the stream open, and only explicitly close the stream later. For that you can use the header HdfsConstants.HDFS_CLOSE (value = "CamelHdfsClose") to control this. Setting this value to a boolean allows you to explicit control whether the stream should be closed or not.

Notice this does not apply if you use a split strategy, as there are various strategies that can control when the stream is closed.

Using this component in OSGi

This component is fully functional in an OSGi environment, however, it requires some actions from the user. Hadoop uses the thread context class loader in order to load resources. Usually, the thread context classloader will be the bundle class loader of the bundle that contains the routes. So, the default configuration files need to be visible from the bundle class loader. A typical way to deal with it is to keep a copy of core-default.xml in your bundle root. That file can be found in the hadoop-common.jar.

Hibernate Component

The hibernate: component allows you to work with databases using Hibernate as the object relational mapping technology to map POJOs to database tables. The camel-hibernate library is provided by the Camel Extra project which hosts all *GPL related components for Camel.

Icon

Note that Camel also ships with a JPA component. The JPA component abstracts from the underlying persistence provider and allows you to work with Hibernate, OpenJPA or EclipseLink.

Sending to the endpoint

Sending POJOs to the hibernate endpoint inserts entities into the database. The body of the message is assumed to be an entity bean that you have mapped to a relational table using the hibernate .hbm.xml files.

If the body does not contain an entity bean, use a Message Translator in front of the endpoint to perform the necessary conversion first.

Consuming from the endpoint

Consuming messages removes (or updates) entities in the database. This allows you to use a database table as a logical queue; consumers take messages from the queue and then delete/update them to logically remove them from the queue.

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

If you would rather perform some update on the entity to mark it as processed (such as to exclude it from a future query) then you can annotate a method with @Consumed which will be invoked on your entity bean when the entity bean is consumed.

URI format

For sending to the endpoint, the entityClassName is optional. If specified it is used to help use the type conversion to ensure the body is of the correct type.

For consuming the entityClassName is mandatory.

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

Options

Name

Default Value

Description

entityType

entityClassName

Is the provided entityClassName from the URI.

consumeDelete

true

Option for HibernateConsumer only. Specifies whether or not the entity is deleted after it is consumed.

consumeLockEntity

true

Option for HibernateConsumer only. Specifies whether or not to use exclusive locking of each entity while processing the results from the pooling.

flushOnSend

true

Option for HibernateProducer only. Flushes the EntityManager after the entity bean has been persisted.

maximumResults

-1

Option for HibernateConsumer only. Set the maximum number of results to retrieve on the Query.

consumer.delay

500

Option for HibernateConsumer only. Delay in millis between each poll.

consumer.initialDelay

1000

Option for HibernateConsumer only. Millis before polling starts.

consumer.userFixedDelay

false

Option for HibernateConsumer only. Set to true to use fixed delay between polls, otherwise fixed rate is used. See ScheduledExecutorService in JDK for details.

See Also

HL7 Component

The hl7 component is used for working with the HL7 MLLP protocol and HL7 v2 messages using the HAPI library.

This component supports the following:

  • HL7 MLLP codec for Mina
  • Agnostic data format using either plain String objects or HAPI HL7 model objects.
  • Type Converter from/to HAPI and String
  • HL7 DataFormat using HAPI library
  • Even more ease-of-use as it's integrated well with the camel-mina (Camel 2.11: camel-mina2 ) component.

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

HL7 MLLP protocol

HL7 is often used with the HL7 MLLP protocol that is a text based TCP socket based protocol. This component ships with a Mina Codec that conforms to the MLLP protocol so you can easily expose a HL7 listener that accepts HL7 requests over the TCP transport.

To expose a HL7 listener service we reuse the existing mina/mina2 component where we just use the HL7MLLPCodec as codec.

The HL7 MLLP codec has the following options:

Name

Default Value

Description

startByte

0x0b

The start byte spanning the HL7 payload.

endByte1

0x1c

The first end byte spanning the HL7 payload.

endByte2

0x0d

The 2nd end byte spanning the HL7 payload.

charset

JVM Default

The encoding (is a charset name) to use for the codec. If not provided, Camel will use the JVM default Charset.

convertLFtoCR

true (Camel 2.11:false)

Will convert \n to \r (0x0d, 13 decimal) as HL7 stipulates \r as segment terminators. The HAPI library requires the use of \r.

validate

true

Whether HAPI Parser should validate or not.

parser

ca.uhn.hl7v2.parser.PipeParser

Camel 2.11: To use a custom parser. Must be of type ca.uhn.hl7v2.parser.Parser.

Exposing a HL7 listener

In our Spring XML file, we configure an endpoint to listen for HL7 requests using TCP:

Notice that we use TCP on localhost on port 8888. We use sync=true to indicate that this listener is synchronous and therefore will return a HL7 response to the caller. Then we setup mina to use our HL7 codec with codec=#hl7codec. Notice that hl7codec is just a Spring bean ID, so we could have named it mygreatcodecforhl7 or whatever. The codec is also set up in the Spring XML file:

Above we also configure the charset encoding to use (iso-8859-1).

The endpoint hl7listener can then be used in a route as a consumer, as this Java DSL example illustrates:

This is a very simple route that will listen for HL7 and route it to a service named patientLookupService that is also a Spring bean ID we have configured in the Spring XML as:

Another powerful feature of Camel is that we can have our business logic in POJO classes that is not tied to Camel as shown here:

Notice that this class uses just imports from the HAPI library and not from Camel.

HL7 Model using java.lang.String

The HL7MLLP codec uses plain String as its data format. Camel uses its Type Converter to convert to/from strings to the HAPI HL7 model objects. However, you can use plain String objects if you prefer, for instance if you wish to parse the data yourself.

See samples for such an example.

HL7v2 Model using HAPI

The HL7v2 model uses Java objects from the HAPI library. Using this library, we can encode and decode from the EDI format (ER7) that is mostly used with HL7v2.
With this model you can code with Java objects instead of the EDI based HL7 format that can be hard for humans to read and understand.

The sample below is a request to lookup a patient with the patient ID 0101701234.

Using the HL7 model we can work with the data as a ca.uhn.hl7v2.model.Message object.
To retrieve the patient ID in the message above, you can do this in Java code:

If you know the message type in advance, you can be more type-safe:

Camel has built-in type converters, so when this operation is invoked:

Camel will convert the received HL7 data from String to Message. This is powerful when combined with the HL7 listener, then you as the end-user don't have to work with byte[], String or any other simple object formats. You can just use the HAPI HL7v2 model objects.

HL7 DataFormat

The HL7 component ships with a HL7 data format that can be used to format between String and HL7 model objects.

  • marshal = from Message to byte stream (can be used when returning as response using the HL7 MLLP codec)
  • unmarshal = from byte stream to Message (can be used when receiving streamed data from the HL7 MLLP

To use the data format, simply instantiate an instance and invoke the marshal or unmarshal operation in the route builder:

In the sample above, the HL7 is marshalled from a HAPI Message object to a byte stream and put on a JMS queue.
The next example is the opposite:

Here we unmarshal the byte stream into a HAPI Message object that is passed to our patient lookup service.

Segment separators

Icon

As of Camel 2.11, unmarshal does not automatically fix segment separators anymore by converting \n to \r. If you
need this conversion, org.apache.camel.component.hl7.HL7#convertLFToCR provides a handy Expression for this purpose.

Notice there is a shorthand syntax in Camel for well-known data formats that is commonly used.
Then you don't need to create an instance of the HL7DataFormat object:

Serializable messages

Icon

As of HAPI 2.0 (used by Camel 2.11), the HL7v2 model classes are fully serializable. So you can put HL7v2 messages directly into a JMS queue (i.e. without calling marshal() and read them again directly from the queue (i.e. without calling unmarshal().

Message Headers

The unmarshal operation adds these MSH fields as headers on the Camel message:

Key

MSH field

Example

CamelHL7SendingApplication

MSH-3

MYSERVER

CamelHL7SendingFacility

MSH-4

MYSERVERAPP

CamelHL7ReceivingApplication

MSH-5

MYCLIENT

CamelHL7ReceivingFacility

MSH-6

MYCLIENTAPP

CamelHL7Timestamp

MSH-7

20071231235900

CamelHL7Security

MSH-8

null

CamelHL7MessageType

MSH-9-1

ADT

CamelHL7TriggerEvent

MSH-9-2

A01

CamelHL7MessageControl

MSH-10

1234

CamelHL7ProcessingId

MSH-11

P

CamelHL7VersionId

MSH-12

2.4

All headers are String types. If a header value is missing, its value is null.

Options

The HL7 Data Format supports the following options:

Option

Default

Description

validate

true

Whether the HAPI Parser should validate using the default validation rules. Camel 2.11: better use the parser option and initialize the parser with the desired HAPI ValidationContext

parser

ca.uhn.hl7v2.parser.GenericParser

Camel 2.11: To use a custom parser. Must be of type ca.uhn.hl7v2.parser.Parser. Note that GenericParser also allows to parse XML-encoded HL7v2 messages.

Dependencies

To use HL7 in your Camel routes you'll need to add a dependency on camel-hl7 listed above, which implements this data format.

The HAPI library since Version 0.6 has been split into a base library and several structure libraries, one for each HL7v2 message version:

By default camel-hl7 only references the HAPI base library. Applications are responsible for including structure libraries themselves. For example, if a application works with HL7v2 message versions 2.4 and 2.5 then the following dependencies must be added:

Alternatively, an OSGi bundle containing the base library, all structures libraries and required dependencies (on the bundle classpath) can be downloaded from the central Maven repository.

Terser language (Camel 2.11)

HAPI provides a Terser class that provides access to fields using a commonly used terse location specification syntax. The Terser language allows to use this syntax to extract values from messages and to use them as expressions and predicates for filtering, content-based routing etc.

Sample:

HL7 Validation predicate (Camel 2.11)

Often it is preferable to parse a HL7v2 message and validate it against a HAPI ValidationContext in a separate step afterwards.

Sample:

HL7 Acknowledgement expression (Camel 2.11)

A common task in HL7v2 processing is to generate an acknowledgement message as response to an incoming HL7v2 message, e.g. based on a validation result. The ack expression lets us accomplish this very elegantly:

More Samples

In the following example we send a HL7 request to a HL7 listener and retrieves a response. We use plain String types in this example:

In the next sample, we want to route HL7 requests from our HL7 listener to our business logic. We have our business logic in a plain POJO that we have registered in the registry as hl7service = for instance using Spring and letting the bean id = hl7service.

Our business logic is a plain POJO only using the HAPI library so we have these operations defined:

Then we set up the Camel routes using the RouteBuilder as follows:

Notice that we use the HL7 DataFormat to enrich our Camel Message with the MSH fields preconfigured on the Camel Message. This lets us much more easily define our routes using the fluent builders.
If we do not use the HL7 DataFormat, then we do not gains these headers and we must resort to a different technique for computing the MSH trigger event (= what kind of HL7 message it is). This is a big advantage of the HL7 DataFormat over the plain HL7 type converters.

Sample using plain String objects

In this sample we use plain String objects as the data format, that we send, process and receive. As the sample is part of a unit test, there is some code for assertions, but you should be able to understand what happens. First we send the plain string, Hello World, to the HL7MLLPCodec and receive the response as a plain string, Bye World.

Here we process the incoming data as plain String and send the response also as plain String:

See Also

HTTP Component

The http: component provides HTTP based endpoints for consuming external HTTP resources (as a client to call external servers using HTTP).

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

URI format

Will by default use port 80 for HTTP and 443 for HTTPS.

camel-http vs camel-jetty

Icon

You can only produce to endpoints generated by the HTTP component. Therefore it should never be used as input into your camel Routes. To bind/expose an HTTP endpoint via a HTTP server as input to a camel route, you can use the Jetty Component or the Servlet Component

Examples

Call the url with the body using POST and return response as out message. If body is null call URL using GET and return response as out message

Java DSL

Spring DSL

You can override the HTTP endpoint URI by adding a header. Camel will call the http://newhost. This is very handy for e.g. REST urls.

Java DSL

URI parameters can either be set directly on the endpoint URI or as a header

Java DSL

Set the HTTP request method to POST

Java DSL

Spring DSL

HttpEndpoint Options

Name

Default Value

Description

throwExceptionOnFailure

true

Option to disable throwing the HttpOperationFailedException in case of failed responses from the remote server. This allows you to get all responses regardless of the HTTP status code.

bridgeEndpoint

false

If the option is true , HttpProducer will ignore the Exchange.HTTP_URI header, and use the endpoint's URI for request. You may also set the * throwExceptionOnFailure* to be false to let the HttpProducer send all the fault response back.
Camel 2.3: If the option is true, HttpProducer and CamelServlet will skip the gzip processing if the content-encoding is "gzip".

disableStreamCache

false

DefaultHttpBinding will copy the request input stream into a stream cache and put it into message body if this option is false to support read it twice, otherwise DefaultHttpBinding will set the request input stream direct into the message body.

httpBindingRef

null

Deprecated and will be removed in Camel 3.0: Reference to a org.apache.camel.component.http.HttpBinding in the Registry. Use the httpBinding option instead.

httpBinding

null

Camel 2.3: Reference to a org.apache.camel.component.http.HttpBinding in the Registry.

httpClientConfigurerRef

null

Deprecated and will be removed in Camel 3.0: Reference to a org.apache.camel.component.http.HttpClientConfigurer in the Registry. Use the httpClientConfigurer option instead.

httpClientConfigurer

null

Camel 2.3: Reference to a org.apache.camel.component.http.HttpClientConfigurer in the Registry.

httpClient.XXX

null

Setting options on the HttpClientParams. For instance httpClient.soTimeout=5000 will set the SO_TIMEOUT to 5 seconds.

clientConnectionManager

null

To use a custom org.apache.http.conn.ClientConnectionManager.

transferException

false

Camel 2.6: If enabled and an Exchange failed processing on the consumer side, and if the caused Exception was send back serialized in the response as a application/x-java-serialized-object content type (for example using Jetty or SERVLET Camel components). On the producer side the exception will be deserialized and thrown as is, instead of the HttpOperationFailedException. The caused exception is required to be serialized.

headerFilterStrategy

null

Camel 2.11: Reference to a instance of org.apache.camel.spi.HeaderFilterStrategy in the Registry. It will be used to apply the custom headerFilterStrategy on the new create HttpEndpoint.

urlRewrite

null

Camel 2.11: Producer only Refers to a custom org.apache.camel.component.http.UrlRewrite which allows you to rewrite urls when you bridge/proxy endpoints. See more details at UrlRewrite and How to use Camel as a HTTP proxy between a client and server.

Authentication and Proxy

The following authentication options can also be set on the HttpEndpoint:

Name

Default Value

Description

authMethod

null

Authentication method, either as Basic, Digest or NTLM.

authMethodPriority

null

Priority of authentication methods. Is a list separated with comma. For example: Basic,Digest to exclude NTLM.

authUsername

null

Username for authentication

authPassword

null

Password for authentication

authDomain

null

Domain for NTML authentication

authHost

null

Optional host for NTML authentication

proxyHost

null

The proxy host name

proxyPort

null

The proxy port number

proxyAuthMethod

null

Authentication method for proxy, either as Basic, Digest or NTLM.

proxyAuthUsername

null

Username for proxy authentication

proxyAuthPassword

null

Password for proxy authentication

proxyAuthDomain

null

Domain for proxy NTML authentication

proxyAuthHost

null

Optional host for proxy NTML authentication

When using authentication you must provide the choice of method for the authMethod or authProxyMethod options.
You can configure the proxy and authentication details on either the HttpComponent or the HttpEndoint. Values provided on the HttpEndpoint will take precedence over HttpComponent. Its most likely best to configure this on the HttpComponent which allows you to do this once.

The HTTP component uses convention over configuration which means that if you have not explicit set a authMethodPriority then it will fallback and use the select(ed) authMethod as priority as well. So if you use authMethod.Basic then the auhtMethodPriority will be Basic only.

HttpComponent Options

Name

Default Value

Description

httpBinding

null

To use a custom org.apache.camel.component.http.HttpBinding.

httpClientConfigurer

null

To use a custom org.apache.camel.component.http.HttpClientConfigurer.

httpConnectionManager

null

To use a custom org.apache.commons.httpclient.HttpConnectionManager.

httpConfiguration

null

To use a custom org.apache.camel.component.http.HttpConfiguration

HttpConfiguration contains all the options listed in the table above under the section HttpConfiguration - Setting Authentication and Proxy.

Message Headers

Name

Type

Description

Exchange.HTTP_URI

String

URI to call. Will override existing URI set directly on the endpoint.

Exchange.HTTP_METHOD

String

HTTP Method / Verb to use (GET/POST/PUT/DELETE/HEAD/OPTIONS/TRACE)

Exchange.HTTP_PATH

String

Request URI's path, the header will be used to build the request URI with the HTTP_URI. Camel 2.3.0: If the path is start with "/", http producer will try to find the relative path based on the Exchange.HTTP_BASE_URI header or the exchange.getFromEndpoint().getEndpointUri();

Exchange.HTTP_QUERY

String

URI parameters. Will override existing URI parameters set directly on the endpoint.

Exchange.HTTP_RESPONSE_CODE

int

The HTTP response code from the external server. Is 200 for OK.

Exchange.HTTP_CHARACTER_ENCODING

String

Character encoding.

Exchange.CONTENT_TYPE

String

The HTTP content type. Is set on both the IN and OUT message to provide a content type, such as text/html.

Exchange.CONTENT_ENCODING

String

The HTTP content encoding. Is set on both the IN and OUT message to provide a content encoding, such as gzip.

Exchange.HTTP_SERVLET_REQUEST

HttpServletRequest

The HttpServletRequest object.

Exchange.HTTP_SERVLET_RESPONSE

HttpServletResponse

The HttpServletResponse object.

Exchange.HTTP_PROTOCOL_VERSION

String

Camel 2.5: You can set the http protocol version with this header, eg. "HTTP/1.0". If you didn't specify the header, HttpProducer will use the default value "HTTP/1.1"

The header name above are constants. For the spring DSL you have to use the value of the constant instead of the name.

Message Body

Camel will store the HTTP response from the external server on the OUT body. All headers from the IN message will be copied to the OUT message, so headers are preserved during routing. Additionally Camel will add the HTTP response headers as well to the OUT message headers.

Response code

Camel will handle according to the HTTP response code:

  • Response code is in the range 100..299, Camel regards it as a success response.
  • Response code is in the range 300..399, Camel regards it as a redirection response and will throw a HttpOperationFailedException with the information.
  • Response code is 400+, Camel regards it as an external server failure and will throw a HttpOperationFailedException with the information.

    throwExceptionOnFailure

    Icon

    The option, throwExceptionOnFailure, can be set to false to prevent the HttpOperationFailedException from being thrown for failed response codes. This allows you to get any response from the remote server.
    There is a sample below demonstrating this.

HttpOperationFailedException

This exception contains the following information:

  • The HTTP status code
  • The HTTP status line (text of the status code)
  • Redirect location, if server returned a redirect
  • Response body as a java.lang.String, if server provided a body as response

Calling using GET or POST

The following algorithm is used to determine if either GET or POST HTTP method should be used:
1. Use method provided in header.
2. GET if query string is provided in header.
3. GET if endpoint is configured with a query string.
4. POST if there is data to send (body is not null).
5. GET otherwise.

How to get access to HttpServletRequest and HttpServletResponse

You can get access to these two using the Camel type converter system using

Using client timeout - SO_TIMEOUT

See the unit test in this link

More Examples

Configuring a Proxy

Java DSL

There is also support for proxy authentication via the proxyUsername and proxyPassword options.

Using proxy settings outside of URI

Java DSL

Spring DSL

Options on Endpoint will override options on the context.

Configuring charset

If you are using POST to send data you can configure the charset

Sample with scheduled poll

The sample polls the Google homepage every 10 seconds and write the page to the file message.html:

Getting the Response Code

You can get the HTTP response code from the HTTP component by getting the value from the Out message header with Exchange.HTTP_RESPONSE_CODE.

Using throwExceptionOnFailure=false to get any response back

In the route below we want to route a message that we enrich with data returned from a remote HTTP call. As we want any response from the remote server, we set the throwExceptionOnFailure option to false so we get any response in the AggregationStrategy. As the code is based on a unit test that simulates a HTTP status code 404, there is some assertion code etc.

Disabling Cookies

To disable cookies you can set the HTTP Client to ignore cookies by adding this URI option:
httpClient.cookiePolicy=ignoreCookies

Advanced Usage

If you need more control over the HTTP producer you should use the HttpComponent where you can set various classes to give you custom behavior.

Setting MaxConnectionsPerHost

The HTTP Component has a org.apache.commons.httpclient.HttpConnectionManager where you can configure various global configuration for the given component.
By global, we mean that any endpoint the component creates has the same shared HttpConnectionManager. So, if we want to set a different value for the max connection per host, we need to define it on the HTTP component and not on the endpoint URI that we usually use. So here comes:

First, we define the http component in Spring XML. Yes, we use the same scheme name, http, because otherwise Camel will auto-discover and create the component with default settings. What we need is to overrule this so we can set our options. In the sample below we set the max connection to 5 instead of the default of 2.

And then we can just use it as we normally do in our routes:

Using preemptive authentication

An end user reported that he had problem with authenticating with HTTPS. The problem was eventually resolved when he discovered the HTTPS server did not return a HTTP code 401 Authorization Required. The solution was to set the following URI option: httpClient.authenticationPreemptive=true

Accepting self signed certificates from remote server

See this link from a mailing list discussion with some code to outline how to do this with the Apache Commons HTTP API.

Setting up SSL for HTTP Client

Using the JSSE Configuration Utility

As of Camel 2.8, the HTTP4 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 HTTP4 component.

The version of the Apache HTTP client used in this component resolves SSL/TLS information from a global "protocol" registry.  This component provides an implementation, org.apache.camel.component.http.SSLContextParametersSecureProtocolSocketFactory, of the HTTP client's protocol socket factory in order to support the use of the Camel JSSE Configuration utility.  The following example demonstrates how to configure the protocol registry and use the registered protocol information in a route.

Configuring Apache HTTP Client Directly

Basically camel-http component is built on the top of Apache HTTP client, and you can implement a custom org.apache.camel.component.http.HttpClientConfigurer to do some configuration on the http client if you need full control of it.

However if you just want to specify the keystore and truststore you can do this with Apache HTTP HttpClientConfigurer, for example:

And then you need to create a class that implements HttpClientConfigurer, and registers https protocol providing a keystore or truststore per example above. Then, from your camel route builder class you can hook it up like so:

If you are doing this using the Spring DSL, you can specify your HttpClientConfigurer using the URI. For example:

As long as you implement the HttpClientConfigurer and configure your keystore and truststore as described above, it will work fine.

See Also

iBATIS

The ibatis: component allows you to query, poll, insert, update and delete data in a relational database using Apache iBATIS.

Prefer MyBatis

Icon

The Apache iBatis project is no longer active. The project is moved outside Apache and is now know as the MyBatis project.
Therefore we encourage users to use MyBatis instead. This camel-ibatis component will be removed in Camel 3.0.

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

URI format

Where statementName is the name in the iBATIS XML configuration file which maps to the query, insert, update or delete operation you wish to evaluate.

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

This component will by default load the iBatis SqlMapConfig file from the root of the classpath and expected named as SqlMapConfig.xml.
It uses Spring resource loading so you can define it using classpath, file or http as prefix to load resources with those schemes.
In Camel 2.2 you can configure this on the iBatisComponent with the setSqlMapConfig(String) method.

Options

Option

Type

Default

Description

consumer.onConsume

String

null

Statements to run after consuming. Can be used, for example, to update rows after they have been consumed and processed in Camel. See sample later. Multiple statements can be separated with comma.

consumer.useIterator

boolean

true

If true each row returned when polling will be processed individually. If false the entire List of data is set as the IN body.

consumer.routeEmptyResultSet

boolean

false

Sets whether empty result set should be routed or not. By default, empty result sets are not routed.

statementType

StatementType

null

Mandatory to specify for IbatisProducer to control which iBatis SqlMapClient method to invoke. The enum values are: QueryForObject, QueryForList, Insert, Update, Delete.

maxMessagesPerPoll

int

0

An integer to define a maximum messages to gather per poll. By default, no maximum is set. Can be used to set a limit of e.g. 1000 to avoid when starting up the server that there are thousands of files. Set a value of 0 or negative to disabled it.

isolation

String

TRANSACTION_REPEATABLE_READ

Camel 2.9: A String the defines the transaction isolation level of the will be used. Allowed values are TRANSACTION_NONE, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_READ_COMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE

isolation

String

TRANSACTION_REPEATABLE_READ

Camel 2.9: A String the defines the transaction isolation level of the will be used. Allowed values are TRANSACTION_NONE, TRANSACTION_READ_UNCOMMITTED, TRANSACTION_READ_COMMITTED, TRANSACTION_REPEATABLE_READ, TRANSACTION_SERIALIZABLE

Message Headers

Camel will populate the result message, either IN or OUT with a header with the operationName used:

Header

Type

Description

CamelIBatisStatementName

String

The statementName used (for example: insertAccount).

CamelIBatisResult

Object

The response returned from iBatis in any of the operations. For instance an INSERT could return the auto-generated key, or number of rows etc.

Message Body

The response from iBatis will only be set as body if it's a SELECT statement. That means, for example, for INSERT statements Camel will not replace the body. This allows you to continue routing and keep the original body. The response from iBatis is always stored in the header with the key CamelIBatisResult.

Samples

For example if you wish to consume beans from a JMS queue and insert them into a database you could do the following:

Notice we have to specify the statementType, as we need to instruct Camel which SqlMapClient operation to invoke.

Where insertAccount is the iBatis ID in the SQL map file:

Using StatementType for better control of IBatis

When routing to an iBatis endpoint you want more fine grained control so you can control whether the SQL statement to be executed is a SELEECT, UPDATE, DELETE or INSERT etc. So for instance if we want to route to an iBatis endpoint in which the IN body contains parameters to a SELECT statement we can do:

In the code above we can invoke the iBatis statement selectAccountById and the IN body should contain the account id we want to retrieve, such as an Integer type.

We can do the same for some of the other operations, such as QueryForList:

And the same for UPDATE, where we can send an Account object as IN body to iBatis:

Scheduled polling example

Since this component does not support scheduled polling, you need to use another mechanism for triggering the scheduled polls, such as the Timer or Quartz components.

In the sample below we poll the database, every 30 seconds using the Timer component and send the data to the JMS queue:

And the iBatis SQL map file used:

Using onConsume

This component supports executing statements after data have been consumed and processed by Camel. This allows you to do post updates in the database. Notice all statements must be UPDATE statements. Camel supports executing multiple statements whose name should be separated by comma.

The route below illustrates we execute the consumeAccount statement data is processed. This allows us to change the status of the row in the database to processed, so we avoid consuming it twice or more.

And the statements in the sqlmap file:

See Also

IRC Component

The irc component implements an IRC (Internet Relay Chat) transport.

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

URI format

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

Options

Name

Description

Example

Default Value

channels

Comma separated list of IRC channels to join.

channels=#channel1,#channel2

null

nickname

The nickname used in chat.

irc:MyNick@irc.server.org#channel or irc:irc.server.org#channel?nickname=MyUser

null

username

The IRC server user name.

irc:MyUser@irc.server.org#channel or irc:irc.server.org#channel?username=MyUser

Same as nickname.

password

The IRC server password.

password=somepass

None

realname

The IRC user's actual name.

realname=MyName

None

colors

Whether or not the server supports color codes.

true, false

true

onReply

Whether or not to handle general responses to commands or informational messages.

true, false

false

onNick

Handle nickname change events.

true, false

true

onQuit

Handle user quit events.

true, false

true

onJoin

Handle user join events.

true, false

true

onKick

Handle kick events.

true, false

true

onMode

Handle mode change events.

true, false

true

onPart

Handle user part events.

true, false

true

onTopic

Handle topic change events.

true, false

true

onPrivmsg

Handle message events.

true, false

true

trustManager

The trust manager used to verify the SSL server's certificate.

trustManager=#referenceToTrustManagerBean

The default trust manager, which accepts all certificates, will be used.

keys

Camel 2.2: Comma separated list of IRC channel keys. Important to be listed in same order as channels. When joining multiple channels with only some needing keys just insert an empty value for that channel.

irc:MyNick@irc.server.org/#channel?keys=chankey

null

sslContextParameters

Camel 2.9: Reference to a org.apache.camel.util.jsse.SSLContextParameters in the Registry.  This reference overrides any configured SSLContextParameters at the component level.  See Using the JSSE Configuration Utility.  Note that this setting overrides the trustManager option.

#mySslContextParameters

null

SSL Support

Using the JSSE Configuration Utility

As of Camel 2.9, the IRC 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 IRC component.

Programmatic configuration of the endpoint
Spring DSL based configuration of endpoint

Using the legacy basic configuration options

You can also connect to an SSL enabled IRC server, as follows:

By default, the IRC transport uses SSLDefaultTrustManager. If you need to provide your own custom trust manager, use the trustManager parameter as follows:

Using keys

Available as of Camel 2.2

Some irc rooms requires you to provide a key to be able to join that channel. The key is just a secret word.

For example we join 3 channels where as only channel 1 and 3 uses a key.

See Also

Jasypt component

Available as of Camel 2.5

Jasypt is a simplified encryption library which makes encryption and decryption easy. Camel integrates with Jasypt to allow sensitive information in Properties files to be encrypted. By dropping camel-jasypt on the classpath those encrypted values will automatically be decrypted on-the-fly by Camel. This ensures that human eyes can't easily spot sensitive information such as usernames and passwords.

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

Tooling

The Jasypt component provides a little command line tooling to encrypt or decrypt values.

The console output the syntax and which options it provides:

For example to encrypt the value tiger you run with the following parameters. In the apache camel kit, you cd into the lib folder and run the following java cmd, where <CAMEL_HOME> is where you have downloaded and extract the Camel distribution.

Which outputs the following result

This means the encrypted representation qaEEacuW7BUti8LcMgyjKw== can be decrypted back to tiger if you know the master password which was secret.
If you run the tool again then the encrypted value will return a different result. But decrypting the value will always return the correct original value.

So you can test it by running the tooling using the following parameters:

Which outputs the following result:

The idea is then to use those encrypted values in your Properties files. Notice how the password value is encrypted and the value has the tokens surrounding ENC(value here)

Tooling dependencies for Camel 2.5 and 2.6

The tooling requires the following JARs in the classpath, which has been enlisted in the MANIFEST.MF file of camel-jasypt with optional/ as prefix. Hence why the java cmd above can pickup the needed JARs from the Apache Distribution in the optional directory.

Java 1.5 users

Icon

The icu4j-4.0.1.jar is only needed when running on JDK 1.5.

This JAR is not distributed by Apache Camel and you have to download it manually and copy it to the lib/optional directory of the Camel distribution.
You can download it from Apache Central Maven repo.

Tooling dependencies for Camel 2.7 or better

Jasypt 1.7 onwards is now fully standalone so no additional JARs is needed.

URI Options

The options below are exclusive for the Jasypt component.

Name

Default Value

Type

Description

password

null

String

Specifies the master password to use for decrypting. This option is mandatory. See below for more details.

algorithm

null

String

Name of an optional algorithm to use.

Protecting the master password

The master password used by Jasypt must be provided, so that it's capable of decrypting the values. However having this master password out in the open may not be an ideal solution. Therefore you could for example provide it as a JVM system property or as a OS environment setting. If you decide to do so then the password option supports prefixes which dictates this. sysenv: means to lookup the OS system environment with the given key. sys: means to lookup a JVM system property.

For example you could provided the password before you start the application

Then start the application, such as running the start script.

When the application is up and running you can unset the environment

The password option is then a matter of defining as follows: password=sysenv:CAMEL_ENCRYPTION_PASSWORD.

Example with Java DSL

In Java DSL you need to configure Jasypt as a JasyptPropertiesParser instance and set it on the Properties component as show below:

The properties file myproperties.properties then contain the encrypted value, such as shown below. Notice how the password value is encrypted and the value has the tokens surrounding ENC(value here)

Example with Spring XML

In Spring XML you need to configure the JasyptPropertiesParser which is shown below. Then the Camel Properties component is told to use jasypt as the properties parser, which means Jasypt has its chance to decrypt values looked up in the properties.

The Properties component can also be inlined inside the <camelContext> tag which is shown below. Notice how we use the propertiesParserRef attribute to refer to Jasypt.

See Also

JavaSpace Component

Available as of Camel 2.1

The javaspace component is a transport for working with any JavaSpace compliant implementation and this component has been tested with both the Blitz implementation and the GigaSpace implementation .
This component can be used for sending and receiving any object inheriting from the Jini net.jini.core.entry.Entry class. It is also possible to pass the bean ID of a template that can be used for reading/taking the entries from the space.
This component can be used for sending/receiving any serializable object acting as a sort of generic transport. The JavaSpace component contains a special optimization for dealing with the BeanExchange. It can be used to invoke a POJO remotely, using a JavaSpace as a transport.
This latter feature can provide a simple implementation of the master/worker pattern, where a POJO provides the business logic for the worker.
Look at the test cases for examples of various use cases for this component.

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

URI format

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

Options

Name

Default Value

Description

spaceName

null

Specifies the JavaSpace name.

verb

take

Specifies the verb for getting JavaSpace entries. The values can be: take or read.

transactional

false

If true, sending and receiving entries is performed within a transaction.

transactionalTimeout

Long.MAX_VALUE

Specifies the transaction timeout.

concurrentConsumers

1

Specifies the number of concurrent consumers getting entries from the JavaSpace.

templateId

null

If present, this option specifies the Spring bean ID of the template to use for reading/taking entries.

Examples

Sending and Receiving Entries

In this case the payload can be any object that inherits from the Jini Entry type.

Sending and receiving serializable objects

Using the preceding routes, it is also possible to send and receive any serializable object. The JavaSpace component detects that the payload is not a Jini Entry and then it automatically wraps the payload with a Camel Jini Entry. In this way, a JavaSpace can be used as a generic transport mechanism.

Using JavaSpace as a remote invocation transport

The JavaSpace component has been tailored to work in combination with the Camel bean component. It is therefore possible to call a remote POJO using JavaSpace as the transport:

In the code there are two test cases showing how to use a POJO to realize the master/worker pattern. The idea is to use the POJO to provide the business logic and rely on Camel for sending/receiving requests/replies with the proper correlation.

See Also

JBI Component

The jbi component is implemented by the ServiceMix Camel module and provides integration with a JBI Normalized Message Router, such as the one provided by Apache ServiceMix.

Icon

See below for information about how to use StreamSource types from ServiceMix in Camel.

The following code:

Automatically exposes a new endpoint to the bus, where the service QName is {http://foo.bar.org}MyService and the endpoint name is MyEndpoint (see #URI-format).

When a JBI endpoint appears at the end of a route, for example:

The messages sent by this producer endpoint are sent to the already deployed JBI endpoint.

URI format

The separator that should be used in the endpoint URL is:

  • / (forward slash), if serviceNamespace starts with http://, or
  • : (colon), if serviceNamespace starts with urn:foo:bar.

For more details of valid JBI URIs see the ServiceMix URI Guide.

Using the jbi:service: or jbi:endpoint: URI formats sets the service QName on the JBI endpoint to the one specified. Otherwise, the default Camel JBI Service QName is used, which is:

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

Examples

URI options

Name

Default value

Description

mep

MEP of the Camel Exchange

Allows users to override the MEP set on the Exchange object. Valid values for this option are in-only, in-out, robust-in-out and in-optional-out.

operation

Value of the jbi.operation header property

Specifies the JBI operation for the MessageExchange. If no value is supplied, the JBI binding will use the value of the jbi.operation header property.

serialization

basic

Default value (basic) will check if headers are serializable by looking at the type, setting this option to strict will detect objects that can not be serialized although they implement the Serializable interface. Set to nocheck to disable this check altogether, note that this should only be used for in-memory transports like SEDAFlow, otherwise you can expect to get NotSerializableException thrown at runtime.

convertException

false

false: send any exceptions thrown from the Camel route back unmodified
true: convert all exceptions to a JBI FaultException (can be used to avoid non-serializable exceptions or to implement generic error handling

Examples

Using Stream bodies

If you are using a stream type as the message body, you should be aware that a stream is only capable of being read once. So if you enable DEBUG logging, the body is usually logged and thus read. To deal with this, Camel has a streamCaching option that can cache the stream, enabling you to read it multiple times.

The stream caching is default enabled, so it is not necessary to set the streamCaching() option.
We store big input streams (by default, over 64K) in a temp file using CachedOutputStream. When you close the input stream, the temp file will be deleted.

Creating a JBI Service Unit

If you have some Camel routes that you want to deploy inside JBI as a Service Unit, you can use the JBI Service Unit Archetype to create a new Maven project for the Service Unit.

If you have an existing Maven project that you need to convert into a JBI Service Unit, you may want to consult ServiceMix Maven JBI Plugins for further help. The key steps are as follows:

  • Create a Spring XML file at src/main/resources/camel-context.xml to bootstrap your routes inside the JBI Service Unit.
  • Change the POM file's packaging to jbi-service-unit.

Your pom.xml should look something like this to enable the jbi-service-unit packaging:

See Also

JCR Component

The jcr component allows you to add/read nodes to/from a JCR compliant content repository (for example, Apache Jackrabbit) with its producer, or register an EventListener with the consumer.

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

URI format

Consumer added

Icon

From Camel 2.10 onwards you can use consumer as an EventListener in JCR or a producer to read a node by identifier.

Usage

The repository element of the URI is used to look up the JCR Repository object in the Camel context registry.

Producer

Name

Default Value

Description

CamelJcrOperation

CamelJcrInsert

CamelJcrInsert or CamelJcrGetById operation to use

CamelJcrNodeName

null

Used to determine the node name to use.

When a message is sent to a JCR producer endpoint:

  • If the operation is CamelJcrInsert: A new node is created in the content repository, all the message headers of the IN message are transformed to javax.jcr.Value instances and added to the new node and the node's UUID is returned in the OUT message.
  • If the operation is CamelJcrGetById: A new node is retrieved from the repository using the message body as node identifier.
Icon

Please note that the JCR Producer used message properties instead of message headers in Camel versions earlier than 2.12.3. See https://issues.apache.org/jira/browse/CAMEL-7067 for more details.

 

Consumer

The consumer will connect to JCR periodically and return a List<javax.jcr.observation.Event> in the message body.

Name

Default Value

Description

eventTypes

0

A combination of one or more event types encoded as a bit mask value such as javax.jcr.observation.Event.NODE_ADDED, javax.jcr.observation.Event.NODE_REMOVED, etc.

deep

false

When it is true, events whose associated parent node is at current path or within its subgraph are received.

uuids

null

Only events whose associated parent node has one of the identifiers in the comma separated uuid list will be received.

nodeTypeNames

null

Only events whose associated parent node has one of the node types (or a subtype of one of the node types) in this list will be received.

noLocal

false

If noLocal is true, then events generated by the session through which the listener was registered are ignored. Otherwise, they are not ignored.

sessionLiveCheckInterval

60000

Interval in milliseconds to wait before each session live checking.

sessionLiveCheckIntervalOnStart

3000

Interval in milliseconds to wait before the first session live checking.

Example

The snippet below creates a node named node under the /home/test node in the content repository. One additional property is added to the node as well: my.contents.property which will contain the body of the message being sent.

 

The following code will register an EventListener under the path import-application/inbox for Event.NODE_ADDED and Event.NODE_REMOVED events (event types 1 and 2, both masked as 3) and listening deep for all the children.

See Also

JDBC Component

The jdbc component enables you to access databases through JDBC, where SQL queries and operations are sent in the message body. This component uses the standard JDBC API, unlike the SQL Component component, which uses spring-jdbc.

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

Icon

This component can only be used to define producer endpoints, which means that you cannot use the JDBC component in a from() statement.

URI format

This component only supports producer endpoints.

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

Options

Name

Default Value

Description

readSize

0

The default maximum number of rows that can be read by a polling query. The default value is 0.

statement.<xxx>

null

Camel 2.1: Sets additional options on the java.sql.Statement that is used behind the scenes to execute the queries. For instance, statement.maxRows=10. For detailed documentation, see the java.sql.Statement javadoc documentation.

useJDBC4ColumnNameAndLabelSemantics

true

Camel 2.2: Sets whether to use JDBC 4/3 column label/name semantics. You can use this option to turn it false in case you have issues with your JDBC driver to select data. This only applies when using SQL SELECT using aliases (e.g. SQL SELECT id as identifier, name as given_name from persons).

resetAutoCommit

true

Camel 2.9: Camel will set the autoCommit on the JDBC connection to be false, commit the change after executed the statement and reset the autoCommit flag of the connection at the end, if the resetAutoCommit is true. If the JDBC connection doesn't support to reset the autoCommit flag, you can set the resetAutoCommit flag to be false, and Camel will not try to reset the autoCommit flag.

allowNamedParameters

true

Camel 2.12: Whether to allow using named parameters in the queries.

prepareStatementStrategy

 

Camel 2.12: Allows to plugin to use a custom org.apache.camel.component.jdbc.JdbcPrepareStatementStrategy to control preparation of the query and prepared statement.

useHeadersAsParameters

false

Camel 2.12: Set this option to true to use the prepareStatementStrategy with named parameters. This allows to define queries with named placeholders, and use headers with the dynamic values for the query placeholders.

outputType

SelectList

Camel 2.12.1: Make the output of the producer to SelectList as List of Map, or SelectOne as single Java object in the following way:
a) If the query has only single column, then that JDBC Column object is returned. (such as SELECT COUNT( * ) FROM PROJECT will return a Long object.
b) If the query has more than one column, then it will return a Map of that result.
c) If the outputClass is set, then it will convert the query result into an Java bean object by calling all the setters that match the column names. It will assume your class has a default constructor to create instance with.
d) If the query resulted in more than one rows, it throws an non-unique result exception.
Camel 2.14.0: New StreamList output type value that streams the result of the query using an Iterator<Map<String, Object>>, it can be used along with the Splitter EIP.

outputClass

null

Camel 2.12.1: Specify the full package and class name to use as conversion when outputType=SelectOne.

beanRowMapper

 

Camel 2.12.1: To use a custom org.apache.camel.component.jdbc.BeanRowMapper when using outputClass. The default implementation will lower case the row names and skip underscores, and dashes. For example "CUST_ID" is mapped as "custId".

Result

By default the result is returned in the OUT body as an ArrayList<HashMap<String, Object>>. The List object contains the list of rows and the Map objects contain each row with the String key as the column name. You can use the option outputType to control the result.

Note: This component fetches ResultSetMetaData to be able to return the column name as the key in the Map.

Message Headers

Header

Description

CamelJdbcRowCount

If the query is a SELECT, query the row count is returned in this OUT header.

CamelJdbcUpdateCount

If the query is an UPDATE, query the update count is returned in this OUT header.

CamelGeneratedKeysRows

Camel 2.10: Rows that contains the generated kets.

CamelGeneratedKeysRowCount

Camel 2.10: The number of rows in the header that contains generated keys.

CamelJdbcColumnNames

Camel 2.11.1: The column names from the ResultSet as a java.util.Set type.

CamelJdbcParametes

Camel 2.12: A java.util.Map which has the headers to be used if useHeadersAsParameters has been enabled.

Generated keys

Available as of Camel 2.10

If you insert data using SQL INSERT, then the RDBMS may support auto generated keys. You can instruct the JDBC producer to return the generated keys in headers.
To do that set the header CamelRetrieveGeneratedKeys=true. Then the generated keys will be provided as headers with the keys listed in the table above.

You can see more details in this unit test.

Icon

Using generated keys does not work with together with named parameters.

Using named parameters

Available as of Camel 2.12

In the given route below, we want to get all the projects from the projects table. Notice the SQL query has 2 named parameters, :?lic and :?min.
Camel will then lookup these parameters from the message headers. Notice in the example above we set two headers with constant value
for the named parameters:

You can also store the header values in a java.util.Map and store the map on the headers with the key CamelJdbcParameters.

Samples

In the following example, we fetch the rows from the customer table.

First we register our datasource in the Camel registry as testdb:

Then we configure a route that routes to the JDBC component, so the SQL will be executed. Note how we refer to the testdb datasource that was bound in the previous step:

Or you can create a DataSource in Spring like this:

We create an endpoint, add the SQL query to the body of the IN message, and then send the exchange. The result of the query is returned in the OUT body:

If you want to work on the rows one by one instead of the entire ResultSet at once you need to use the Splitter EIP such as:

In Camel 2.13.x or older

In Camel 2.14.x or newer


Sample - Polling the database every minute

If we want to poll a database using the JDBC component, we need to combine it with a polling scheduler such as the Timer or Quartz etc. In the following example, we retrieve data from the database every 60 seconds:

 

See Also

Jetty Component

The jetty component provides HTTP-based endpoints for consuming and producing HTTP requests. That is, the Jetty component behaves as a simple Web server.
Jetty can also be used as a http client which mean you can also use it with Camel as a producer.

Stream

Icon

Jetty is stream based, which means the input it receives is submitted to Camel as a stream. That means you will only be able to read the content of the stream once.
If you find a situation where the message body appears to be empty or you need to access the Exchange.HTTP_RESPONSE_CODE data multiple times (e.g.: doing multicasting, or redelivery error handling), you should use Stream caching or convert the message body to a String which is safe to be re-read multiple times.

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

URI format

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

Options

Name

Default Value

Description

sessionSupport

false

Specifies whether to enable the session manager on the server side of Jetty.

httpClient.XXX

null

Configuration of Jetty's HttpClient. For example, setting httpClient.idleTimeout=30000 sets the idle timeout to 30 seconds. And httpClient.timeout=30000 sets the request timeout to 30 seconds, in case you want to timeout sooner if you have long running request/response calls.

httpClient

null

To use a shared org.eclipse.jetty.client.HttpClient for all producers created by this endpoint. This option should only be used in special circumstances.

httpClientMinThreads

null

Camel 2.11: Producer only: To set a value for minimum number of threads in HttpClient thread pool. This setting override any setting configured on component level. Notice that both a min and max size must be configured. If not set it default to min 8 threads used in Jettys thread pool.

httpClientMaxThreads

null

Camel 2.11: Producer only: To set a value for maximum number of threads in HttpClient thread pool. This setting override any setting configured on component level. Notice that both a min and max size must be configured. If not set it default to max 254 threads used in Jettys thread pool.

httpBindingRef

null

Reference to an org.apache.camel.component.http.HttpBinding in the Registry. HttpBinding can be used to customize how a response should be written for the consumer.

jettyHttpBindingRef

null

Camel 2.6.0+: Reference to an org.apache.camel.component.jetty.JettyHttpBinding in the Registry. JettyHttpBinding can be used to customize how a response should be written for the producer.

matchOnUriPrefix

false

Whether or not the CamelServlet should try to find a target consumer by matching the URI prefix if no exact match is found. See here How do I let Jetty match wildcards.

handlers

null

Specifies a comma-delimited set of org.mortbay.jetty.Handler instances in your Registry (such as your Spring ApplicationContext). These handlers are added to the Jetty servlet context (for example, to add security). Important: You can not use different handlers with different Jetty endpoints using the same port number. The handlers is associated to the port number. If you need different handlers, then use different port numbers.

chunked

true

Camel 2.2: If this option is false Jetty servlet will disable the HTTP streaming and set the content-length header on the response

enableJmx

false

Camel 2.3: If this option is true, Jetty JMX support will be enabled for this endpoint. See Jetty JMX support for more details.

disableStreamCache

false

Camel 2.3: Determines whether or not the raw input stream from Jetty is cached or not (Camel will read the stream into a in memory/overflow to file, Stream caching) cache. By default Camel will cache the Jetty input stream to support reading it multiple times to ensure it Camel can retrieve all data from the stream. However you can set this option to true when you for example need to access the raw stream, such as streaming it directly to a file or other persistent store. DefaultHttpBinding will copy the request input stream into a stream cache and put it into message body if this option is false to support reading the stream multiple times. If you use Jetty to bridge/proxy an endpoint then consider enabling this option to improve performance, in case you do not need to read the message payload multiple times.

throwExceptionOnFailure

true

Option to disable throwing the HttpOperationFailedException in case of failed responses from the remote server. This allows you to get all responses regardles of the HTTP status code.

transferException

false

Camel 2.6: If enabled and an Exchange failed processing on the consumer side, and if the caused Exception was send back serialized in the response as a application/x-java-serialized-object content type. On the producer side the exception will be deserialized and thrown as is, instead of the HttpOperationFailedException. The caused exception is required to be serialized.

bridgeEndpoint

false

Camel 2.1: If the option is true , HttpProducer will ignore the Exchange.HTTP_URI header, and use the endpoint's URI for request. You may also set the throwExceptionOnFailure to be false to let the HttpProducer send all the fault response back.
Camel 2.3: If the option is true, HttpProducer and CamelServlet will skip the gzip processing if the content-encoding is "gzip". Also consider setting disableStreamCache to true to optimize when bridging.

enableMultipartFilter

true

Camel 2.5: Whether Jetty org.eclipse.jetty.servlets.MultiPartFilter is enabled or not. You should set this value to false when bridging endpoints, to ensure multipart requests is proxied/bridged as well.

multipartFilterRef

null

Camel 2.6: Allows using a custom multipart filter. Note: setting multipartFilterRef forces the value of enableMultipartFilter to true.

filtersRef

null

Camel 2.9: Allows using a custom filters which is putted into a list and can be find in the Registry

continuationTimeout

null

Camel 2.6: Allows to set a timeout in millis when using Jetty as consumer (server). By default Jetty uses 30000. You can use a value of <= 0 to never expire. If a timeout occurs then the request will be expired and Jetty will return back a http error 503 to the client. This option is only in use when using Jetty with the Asynchronous Routing Engine.

useContinuation

true

Camel 2.6: Whether or not to use Jetty continuations for the Jetty Server.

sslContextParametersRef

null

Camel 2.8: Reference to a org.apache.camel.util.jsse.SSLContextParameters in the Registry.  This reference overrides any configured SSLContextParameters at the component level.  See Using the JSSE Configuration Utility.

traceEnabled

false

Specifies whether to enable HTTP TRACE for this Jetty consumer. By default TRACE is turned off.

headerFilterStrategy

null

Camel 2.11: Reference to a instance of org.apache.camel.spi.HeaderFilterStrategy in the Registry. It will be used to apply the custom headerFilterStrategy on the new create HttpJettyEndpoint.

urlRewrite

null

Camel 2.11: Producer only Refers to a custom org.apache.camel.component.http.UrlRewrite which allows you to rewrite urls when you bridge/proxy endpoints. See more details at UrlRewrite and How to use Camel as a HTTP proxy between a client and server.

responseBufferSize

null

Camel 2.12: To use a custom buffer size on the javax.servlet.ServletResponse.

proxyHost

null

Camel 2.11: Producer only The http proxy Host url which will be used by Jetty client.

proxyPort

null

Camel 2.11: Producer only The http proxy port which will be used by Jetty client.

sendServerVersion

true

Camel 2.13: if the option is true, jetty will send the server header with the jetty version information to the client which sends the request. NOTE please make sure there is no any other camel-jetty endpoint is share the same port, otherwise this option may not work as expected.

SendDateHeader

false

Camel 2.14: if the option is true, jetty server will send the date header to the client which sends the request. NOTE please make sure there is no any other camel-jetty endpoint is share the same port, otherwise this option may not work as expected.

Message Headers

Camel uses the same message headers as the HTTP component.
From Camel 2.2, it also uses (Exchange.HTTP_CHUNKED,CamelHttpChunked) header to turn on or turn off the chuched encoding on the camel-jetty consumer.

Camel also populates all request.parameter and request.headers. For example, given a client request with the URL, http://myserver/myserver?orderid=123, the exchange will contain a header named orderid with the value 123.

Starting with Camel 2.2.0, you can get the request.parameter from the message header not only from Get Method, but also other HTTP method.

Usage

The Jetty component supports both consumer and producer endpoints. Another option for producing to other HTTP endpoints, is to use the HTTP Component

Component Options

The JettyHttpComponent provides the following options:

Name

Default Value

Description

enableJmx

false

Camel 2.3: If this option is true, Jetty JMX support will be enabled for this endpoint. See Jetty JMX support for more details.

sslKeyPassword

null

Consumer only: The password for the keystore when using SSL.

sslPassword

null

Consumer only: The password when using SSL.

sslKeystore

null

Consumer only: The path to the keystore.

minThreads

null

Camel 2.5 Consumer only: To set a value for minimum number of threads in server thread pool. Notice that both a min and max size must be configured.

maxThreads

null

Camel 2.5 Consumer only: To set a value for maximum number of threads in server thread pool. Notice that both a min and max size must be configured.

threadPool

null

Camel 2.5 Consumer only: To use a custom thread pool for the server. This option should only be used in special circumstances.

sslSocketConnectors

null

Camel 2.3 Consumer only: A map which contains per port number specific SSL connectors. See section SSL support for more details.

socketConnectors

null

Camel 2.5 Consumer only: A map which contains per port number specific HTTP connectors. Uses the same principle as sslSocketConnectors and therefore see section SSL support for more details.

sslSocketConnectorProperties

null

Camel 2.5 Consumer only. A map which contains general SSL connector properties. See section SSL support for more details.

socketConnectorProperties

null

Camel 2.5 Consumer only. A map which contains general HTTP connector properties. Uses the same principle as sslSocketConnectorProperties and therefore see section SSL support for more details.

httpClient

null

Deprecated: Producer only: To use a custom HttpClient with the jetty producer. This option is removed from Camel 2.11 onwards, instead you can set the option on the endpoint instead.

httpClientMinThreads

null

Producer only: To set a value for minimum number of threads in HttpClient thread pool. Notice that both a min and max size must be configured.

httpClientMaxThreads

null

Producer only: To set a value for maximum number of threads in HttpClient thread pool. Notice that both a min and max size must be configured.

httpClientThreadPool

null

Deprecated: Producer only: To use a custom thread pool for the client. This option is removed from Camel 2.11 onwards.

sslContextParameters

null

Camel 2.8: To configure a custom SSL/TLS configuration options at the component level.  See  Using the JSSE Configuration Utility for more details.

requestBufferSize

null

Camel 2.11.2: Allows to configure a custom value of the request buffer size on the Jetty connectors.

requestHeaderSize

null

Camel 2.11.2: Allows to configure a custom value of the request header size on the Jetty connectors.

responseBufferSize

null

Camel 2.11.2: Allows to configure a custom value of the response buffer size on the Jetty connectors.

responseHeaderSize

null

Camel 2.11.2: Allows to configure a custom value of the response header size on the Jetty connectors.

proxyHost

null

Camel 2.12.2/2.11.3 To use a http proxy.

proxyPort

null

Camel 2.12.2/2.11.3: To use a http proxy.

Producer Example

The following is a basic example of how to send an HTTP request to an existing HTTP endpoint.

in Java DSL

or in Spring XML

Consumer Example

In this sample we define a route that exposes a HTTP service at http://localhost:8080/myapp/myservice:

Usage of localhost

Icon

When you specify localhost in a URL, Camel exposes the endpoint only on the local TCP/IP network interface, so it cannot be accessed from outside the machine it operates on.

If you need to expose a Jetty endpoint on a specific network interface, the numerical IP address of this interface should be used as the host. If you need to expose a Jetty endpoint on all network interfaces, the 0.0.0.0 address should be used.

Our business logic is implemented in the MyBookService class, which accesses the HTTP request contents and then returns a response.
Note: The assert call appears in this example, because the code is part of an unit test.

The following sample shows a content-based route that routes all requests containing the URI parameter, one, to the endpoint, mock:one, and all others to mock:other.

So if a client sends the HTTP request, http://serverUri?one=hello, the Jetty component will copy the HTTP request parameter, one to the exchange's in.header. We can then use the simple language to route exchanges that contain this header to a specific endpoint and all others to another. If we used a language more powerful than Simple (such as EL or OGNL) we could also test for the parameter value and do routing based on the header value as well.

Session Support

The session support option, sessionSupport, can be used to enable a HttpSession object and access the session object while processing the exchange. For example, the following route enables sessions:

The myCode Processor can be instantiated by a Spring bean element:

Where the processor implementation can access the HttpSession as follows:

SSL Support (HTTPS)

Using the JSSE Configuration Utility

As of Camel 2.8, the Jetty 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 Jetty component.

Programmatic configuration of the component
Spring DSL based configuration of endpoint
Configuring Jetty Directly

Jetty provides SSL support out of the box. To enable Jetty to run in SSL mode, simply format the URI with the https:// prefix---for example:

Jetty also needs to know where to load your keystore from and what passwords to use in order to load the correct SSL certificate. Set the following JVM System Properties:

until Camel 2.2

  • jetty.ssl.keystore specifies the location of the Java keystore file, which contains the Jetty server's own X.509 certificate in a key entry. A key entry stores the X.509 certificate (effectively, the public key) and also its associated private key.
  • jetty.ssl.password the store password, which is required to access the keystore file (this is the same password that is supplied to the keystore command's -storepass option).
  • jetty.ssl.keypassword the key password, which is used to access the certificate's key entry in the keystore (this is the same password that is supplied to the keystore command's -keypass option).

from Camel 2.3 onwards

  • org.eclipse.jetty.ssl.keystore specifies the location of the Java keystore file, which contains the Jetty server's own X.509 certificate in a key entry. A key entry stores the X.509 certificate (effectively, the public key) and also its associated private key.
  • org.eclipse.jetty.ssl.password the store password, which is required to access the keystore file (this is the same password that is supplied to the keystore command's -storepass option).
  • org.eclipse.jetty.ssl.keypassword the key password, which is used to access the certificate's key entry in the keystore (this is the same password that is supplied to the keystore command's -keypass option).

For details of how to configure SSL on a Jetty endpoint, read the following documentation at the Jetty Site: http://docs.codehaus.org/display/JETTY/How+to+configure+SSL

Some SSL properties aren't exposed directly by Camel, however Camel does expose the underlying SslSocketConnector, which will allow you to set properties like needClientAuth for mutual authentication requiring a client certificate or wantClientAuth for mutual authentication where a client doesn't need a certificate but can have one. There's a slight difference between the various Camel versions:

Up to Camel 2.2

Camel 2.3, 2.4

*From Camel 2.5 we switch to use SslSelectChannelConnector *

The value you use as keys in the above map is the port you configure Jetty to listen on.

Configuring general SSL properties

Available as of Camel 2.5

Instead of a per port number specific SSL socket connector (as shown above) you can now configure general properties which applies for all SSL socket connectors (which is not explicit configured as above with the port number as entry).

How to obtain reference to the X509Certificate

Jetty stores a reference to the certificate in the HttpServletRequest which you can access from code as follows:

Configuring general HTTP properties

Available as of Camel 2.5

Instead of a per port number specific HTTP socket connector (as shown above) you can now configure general properties which applies for all HTTP socket connectors (which is not explicit configured as above with the port number as entry).

Default behavior for returning HTTP status codes

The default behavior of HTTP status codes is defined by the org.apache.camel.component.http.DefaultHttpBinding class, which handles how a response is written and also sets the HTTP status code.

If the exchange was processed successfully, the 200 HTTP status code is returned.
If the exchange failed with an exception, the 500 HTTP status code is returned, and the stacktrace is returned in the body. If you want to specify which HTTP status code to return, set the code in the Exchange.HTTP_RESPONSE_CODE header of the OUT message.

Customizing HttpBinding

By default, Camel uses the org.apache.camel.component.http.DefaultHttpBinding to handle how a response is written. If you like, you can customize this behavior either by implementing your own HttpBinding class or by extending DefaultHttpBinding and overriding the appropriate methods.

The following example shows how to customize the DefaultHttpBinding in order to change how exceptions are returned:

We can then create an instance of our binding and register it in the Spring registry as follows:

And then we can reference this binding when we define the route:

Jetty handlers and security configuration

You can configure a list of Jetty handlers on the endpoint, which can be useful for enabling advanced Jetty security features. These handlers are configured in Spring XML as follows:

And from Camel 2.3 onwards you can configure a list of Jetty handlers as follows:

You can then define the endpoint as:

If you need more handlers, set the handlers option equal to a comma-separated list of bean IDs.

How to return a custom HTTP 500 reply message

You may want to return a custom reply message when something goes wrong, instead of the default reply message Camel Jetty replies with.
You could use a custom HttpBinding to be in control of the message mapping, but often it may be easier to use Camel's Exception Clause to construct the custom reply message. For example as show here, where we return Dude something went wrong with HTTP error code 500:

Multi-part Form support

From Camel 2.3.0, camel-jetty support to multipart form post out of box. The submitted form-data are mapped into the message header. Camel-jetty creates an attachment for each uploaded file. The file name is mapped to the name of the attachment. The content type is set as the content type of the attachment file name. You can find the example here.

Note: getName() functions as shown below in versions 2.5 and higher. In earlier versions you receive the temporary file name for the attachment instead

Jetty JMX support

From Camel 2.3.0, camel-jetty supports the enabling of Jetty's JMX capabilities at the component and endpoint level with the endpoint configuration taking priority. Note that JMX must be enabled within the Camel context in order to enable JMX support in this component as the component provides Jetty with a reference to the MBeanServer registered with the Camel context. Because the camel-jetty component caches and reuses Jetty resources for a given protocol/host/port pairing, this configuration option will only be evaluated during the creation of the first endpoint to use a protocol/host/port pairing. For example, given two routes created from the following XML fragments, JMX support would remain enabled for all endpoints listening on "https://0.0.0.0".

The camel-jetty component also provides for direct configuration of the Jetty MBeanContainer. Jetty creates MBean names dynamically. If you are running another instance of Jetty outside of the Camel context and sharing the same MBeanServer between the instances, you can provide both instances with a reference to the same MBeanContainer in order to avoid name collisions when registering Jetty MBeans.

See Also

Jing Component

The Jing component uses the Jing Library to perform XML validation of the message body using either

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

Note that the MSV component can also support RelaxNG XML syntax.

URI format

Where rng means use the RelaxNG XML Syntax whereas rnc means use RelaxNG Compact Syntax. The following examples show possible URI values

Example

Description

rng:foo/bar.rng

References the XML file foo/bar.rng on the classpath

rnc:

http://foo.com/bar.rnc

References the RelaxNG Compact Syntax file from the URL,

http://foo.com/bar.rnc

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

Options

Option

Default

Description

useDom

false

Specifies whether DOMSource/DOMResult or SaxSource/SaxResult should be used by the validator.

Example

The following example shows how to configure a route from the endpoint direct:start which then goes to one of two endpoints, either mock:valid or mock:invalid based on whether or not the XML matches the given RelaxNG Compact Syntax schema (which is supplied on the classpath).

See Also

JMS Component

Using ActiveMQ

Icon

If you are using Apache ActiveMQ, you should prefer the ActiveMQ component as it has been optimized for ActiveMQ. All of the options and samples on this page are also valid for the ActiveMQ component.

Transacted and caching

Icon

See section Transactions and Cache Levels below if you are using transactions with JMS as it can impact performance.

Request/Reply over JMS

Icon

Make sure to read the section Request-reply over JMS further below on this page for important notes about request/reply, as Camel offers a number of options to configure for performance, and clustered environments.

The JMS component allows messages to be sent to (or consumed from) a JMS Queue or Topic. The implementation of the JMS Component uses Spring's JMS support for declarative transactions, using Spring's JmsTemplate for sending and a MessageListenerContainer for consuming.

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

URI format

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

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:

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

Notes

Using ActiveMQ

The JMS component reuses Spring 2's JmsTemplate for sending messages. This is not ideal for use in a non-J2EE container and typically requires some caching in the JMS provider to avoid poor performance.

If you intend to use Apache ActiveMQ as your Message Broker - which is a good choice as ActiveMQ rocks (smile) , then we recommend that you either:

  • Use the ActiveMQ component, which is already optimized to use ActiveMQ efficiently
  • Use the PoolingConnectionFactory in ActiveMQ.

Transactions and Cache Levels


If you are consuming messages and using transactions (transacted=true) then the default settings for cache level can impact performance.
If you are using XA transactions then you cannot cache as it can cause the XA transaction to not work properly.

If you are not using XA, then you should consider caching as it speeds up performance, such as setting cacheLevelName=CACHE_CONSUMER.

Through Camel 2.7.x, the default setting for cacheLevelName is CACHE_CONSUMER. You will need to explicitly set cacheLevelName=CACHE_NONE.
In Camel 2.8 onwards, the default setting for cacheLevelName is CACHE_AUTO. This default auto detects the mode and sets the cache level accordingly to:

  • CACHE_CONSUMER = if transacted=false
  • CACHE_NONE = if transacted=true

So you can say the default setting is conservative. Consider using cacheLevelName=CACHE_CONSUMER if you are using non-XA transactions.

Durable Subscriptions

If you wish to use durable topic subscriptions, you need to specify both clientId and durableSubscriptionName. The value of the clientId must be unique and can only be used by a single JMS connection instance in your entire network. You may prefer to use Virtual Topics instead to avoid this limitation. More background on durable messaging here.

Message Header Mapping

When using message headers, the JMS specification states that header names must be valid Java identifiers. So try to name your headers to be valid Java identifiers. One benefit of doing this is that you can then use your headers inside a JMS Selector (whose SQL92 syntax mandates Java identifier syntax for headers).

A simple strategy for mapping header names is used by default. The strategy is to replace any dots and hyphens in the header name as shown below and to reverse the replacement when the header name is restored from a JMS message sent over the wire. What does this mean? No more losing method names to invoke on a bean component, no more losing the filename header for the File Component, and so on.

The current header name strategy for accepting header names in Camel is as follows:

  • Dots are replaced by _DOT_ and the replacement is reversed when Camel consume the message
  • Hyphen is replaced by _HYPHEN_ and the replacement is reversed when Camel consumes the message

Options

You can configure many different properties on the JMS endpoint which map to properties on the JMSConfiguration POJO.

Mapping to Spring JMS

Icon

Many of these properties map to properties on Spring JMS, which Camel uses for sending and receiving messages. So you can get more information about these properties by consulting the relevant Spring documentation.

The options are divided into two tables, the first one with the most common options used. The latter contains the rest.

Most commonly used options

Option

Default Value

Description

clientId

null

Sets the JMS client ID to use. Note that this value, if specified, must be unique and can only be used by a single JMS connection instance. It is typically only required for durable topic subscriptions. You may prefer to use Virtual Topics instead.

concurrentConsumers

1

Specifies the default number of concurrent consumers. From Camel 2.10.3 onwards this option can also be used when doing request/reply over JMS. See also the maxMessagesPerTask option to control dynamic scaling up/down of threads.

disableReplyTo

false

If true, a producer will behave like a InOnly exchange with the exception that JMSReplyTo header is sent out and not be suppressed like in the case of InOnly. Like InOnly the producer will not wait for a reply. A consumer with this flag will behave like InOnly. This feature can be used to bridge InOut requests to another queue so that a route on the other queue will send it´s response directly back to the original JMSReplyTo.

durableSubscriptionName

null

The durable subscriber name for specifying durable topic subscriptions. The clientId option must be configured as well.

maxConcurrentConsumers

1

Specifies the maximum number of concurrent consumers. From Camel 2.10.3 onwards this option can also be used when doing request/reply over JMS. See also the maxMessagesPerTask option to control dynamic scaling up/down of threads.

maxMessagesPerTask

-1

The number of messages per task. -1 is unlimited. If you use a range for concurrent consumers (eg min < max), then this option can be used to set a value to eg 100 to control how fast the consumers will shrink when less work is required.

preserveMessageQos

false

Set to true, if you want to send message using the QoS settings specified on the message, instead of the QoS settings on the JMS endpoint. The following three headers are considered JMSPriority, JMSDeliveryMode, and JMSExpiration. You can provide all or only some of them. If not provided, Camel will fall back to use the values from the endpoint instead. So, when using this option, the headers override the values from the endpoint. The explicitQosEnabled option, by contrast, will only use options set on the endpoint, and not values from the message header.

replyTo

null

Provides an explicit ReplyTo destination, which overrides any incoming value of Message.getJMSReplyTo(). If you do Request Reply over JMS then make sure to read the section Request-reply over JMS further below for more details, and the replyToType option as well.

replyToType

null

Camel 2.9: Allows for explicitly specifying which kind of strategy to use for replyTo queues when doing request/reply over JMS. Possible values are: Temporary, Shared, or Exclusive. By default Camel will use temporary queues. However if replyTo has been configured, then Shared is used by default. This option allows you to use exclusive queues instead of shared ones. See further below for more details, and especially the notes about the implications if running in a clustered environment, and the fact that Shared reply queues has lower performance than its alternatives Temporary and Exclusive.

requestTimeout

20000

Producer only: The timeout for waiting for a reply when using the InOut Exchange Pattern (in milliseconds). The default is 20 seconds. From Camel 2.13/2.12.3 onwards you can include the header "CamelJmsRequestTimeout" to override this endpoint configured timeout value, and thus have per message individual timeout values. See below in section About time to live for more details. See also the requestTimeoutCheckerInterval option.

selector

null

Sets the JMS Selector, which is an SQL 92 predicate that is used to filter messages within the broker. You may have to encode special characters such as = as %3D Before Camel 2.3.0, we don't support this option in CamelConsumerTemplate

timeToLive

null

When sending messages, specifies the time-to-live of the message (in milliseconds). See below in section About time to live for more details.

transacted

false

Specifies whether to use transacted mode for sending/receiving messages using the InOnly Exchange Pattern.

testConnectionOnStartup

false

Camel 2.1: Specifies whether to test the connection on startup. This ensures that when Camel starts that all the JMS consumers have a valid connection to the JMS broker. If a connection cannot be granted then Camel throws an exception on startup. This ensures that Camel is not started with failed connections. From Camel 2.8 onwards also the JMS producers is tested as well.

All the other options

Option

Default Value

Description

acceptMessagesWhileStopping

false

Specifies whether the consumer accept messages while it is stopping. You may consider enabling this option, if you start and stop JMS routes at runtime, while there are still messages enqued on the queue. If this option is false, and you stop the JMS route, then messages may be rejected, and the JMS broker would have to attempt redeliveries, which yet again may be rejected, and eventually the message may be moved at a dead letter queue on the JMS broker. To avoid this its recommended to enable this option.

acknowledgementModeName

AUTO_ACKNOWLEDGE

The JMS acknowledgement name, which is one of: SESSION_TRANSACTED, CLIENT_ACKNOWLEDGE, AUTO_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE

acknowledgementMode

-1

The JMS acknowledgement mode defined as an Integer. Allows you to set vendor-specific extensions to the acknowledgment mode. For the regular modes, it is preferable to use the acknowledgementModeName instead.

allowNullBody

true

Camel 2.9.3/2.10.1: Whether to allow sending messages with no body. If this option is false and the message body is null, then an JMSException is thrown.

alwaysCopyMessage

false

If true, Camel will always make a JMS message copy of the message when it is passed to the producer for sending. Copying the message is needed in some situations, such as when a replyToDestinationSelectorName is set (incidentally, Camel will set the alwaysCopyMessage option to true, if a replyToDestinationSelectorName is set)

asyncConsumer

false

Camel 2.9: Whether the JmsConsumer processes the Exchange asynchronously. If enabled then the JmsConsumer may pickup the next message from the JMS queue, while the previous message is being processed asynchronously (by the Asynchronous Routing Engine). This means that messages may be processed not 100% strictly in order. If disabled (as default) then the Exchange is fully processed before the JmsConsumer will pickup the next message from the JMS queue. Note if transacted has been enabled, then asyncConsumer=true does not run asynchronously, as transactions must be executed synchronously (Camel 3.0 may support async transactions).

asyncStartListener

false

Camel 2.10: Whether to startup the JmsConsumer message listener asynchronously, when starting a route. For example if a JmsConsumer cannot get a connection to a remote JMS broker, then it may block while retrying and/or failover. This will cause Camel to block while starting routes. By setting this option to true, you will let routes startup, while the JmsConsumer connects to the JMS broker using a dedicated thread in asynchronous mode. If this option is used, then beware that if the connection could not be established, then an exception is logged at WARN level, and the consumer will not be able to receive messages; You can then restart the route to retry.

asyncStopListener

false

Camel 2.10: Whether to stop the JmsConsumer message listener asynchronously, when stopping a route.

autoStartup

true

Specifies whether the consumer container should auto-startup.

cacheLevelName

CACHE_AUTO (Camel >= 2.8.0)
CACHE_CONSUMER (Camel <= 2.7.1)

Sets the cache level by name for the underlying JMS resources. Possible values are: CACHE_AUTO, CACHE_CONNECTION, CACHE_CONSUMER, CACHE_NONE, and CACHE_SESSION. The default setting for Camel 2.8 and newer is CACHE_AUTO. For Camel 2.7.1 and older the default is CACHE_CONSUMER. See the Spring documentation and Transactions Cache Levels for more information.

cacheLevel

 

Sets the cache level by ID for the underlying JMS resources. See cacheLevelName option for more details.

consumerType

Default

The consumer type to use, which can be one of: Simple, Default, or Custom. The consumer type determines which Spring JMS listener to use. Default will use org.springframework.jms.listener.DefaultMessageListenerContainer, Simple will use org.springframework.jms.listener.SimpleMessageListenerContainer. When Custom is specified, the MessageListenerContainerFactory defined by the messageListenerContainerFactoryRef option will determine what org.springframework.jms.listener.AbstractMessageListenerContainer to use (new option in Camel 2.10.2 onwards). This option was temporary removed in Camel 2.7 and 2.8. But has been added back from Camel 2.9 onwards.

connectionFactory

null

The default JMS connection factory to use for the listenerConnectionFactory and templateConnectionFactory, if neither is specified.

defaultTaskExecutorType

(see description)

Camel 2.10.4: Specifies what default TaskExecutor type to use in the DefaultMessageListenerContainer, for both consumer endpoints and the ReplyTo consumer of producer endpoints. Possible values: SimpleAsync (uses Spring's SimpleAsyncTaskExecutor) or ThreadPool (uses Spring's ThreadPoolTaskExecutor with optimal values - cached threadpool-like). If not set, it defaults to the previous behaviour, which uses a cached thread pool for consumer endpoints and SimpleAsync for reply consumers. The use of ThreadPool is recommended to reduce "thread trash" in elastic configurations with dynamically increasing and decreasing concurrent consumers.

deliveryMode

null

Camel 2.12.2/2.13: Specifies the delivery mode to be used. Possibles values are those defined by javax.jms.DeliveryMode.

deliveryPersistent

true

Specifies whether persistent delivery is used by default.

destination

null

Specifies the JMS Destination object to use on this endpoint.

destinationName

null

Specifies the JMS destination name to use on this endpoint.

destinationResolver

null

A pluggable org.springframework.jms.support.destination.DestinationResolver that allows you to use your own resolver (for example, to lookup the real destination in a JNDI registry).

disableTimeToLive

false

Camel 2.8: Use this option to force disabling time to live. For example when you do request/reply over JMS, then Camel will by default use the requestTimeout value as time to live on the message being sent. The problem is that the sender and receiver systems have to have their clocks synchronized, so they are in sync. This is not always so easy to archive. So you can use disableTimeToLive=true to not set a time to live value on the sent message. Then the message will not expire on the receiver system. See below in section About time to live for more details.

eagerLoadingOfProperties

false

Enables eager loading of JMS properties as soon as a message is received, which is generally inefficient, because the JMS properties might not be required. But this feature can sometimes catch early any issues with the underlying JMS provider and the use of JMS properties. This feature can also be used for testing purposes, to ensure JMS properties can be understood and handled correctly.

exceptionListener

null

Specifies the JMS Exception Listener that is to be notified of any underlying JMS exceptions.

errorHandler

null

Camel 2.8.2, 2.9: Specifies a org.springframework.util.ErrorHandler to be invoked in case of any uncaught exceptions thrown while processing a Message. By default these exceptions will be logged at the WARN level, if no errorHandler has been configured. From Camel 2.9.1: onwards you can configure logging level and whether stack traces should be logged using the below two options. This makes it much easier to configure, than having to code a custom errorHandler.

errorHandlerLoggingLevel

WARN

Camel 2.9.1: Allows to configure the default errorHandler logging level for logging uncaught exceptions.

errorHandlerLogStackTrace

true

Camel 2.9.1: Allows to control whether stacktraces should be logged or not, by the default errorHandler.

explicitQosEnabled

false

Set if the deliveryMode, priority or timeToLive qualities of service should be used when sending messages. This option is based on Spring's JmsTemplate. The deliveryMode, priority and timeToLive options are applied to the current endpoint. This contrasts with the preserveMessageQos option, which operates at message granularity, reading QoS properties exclusively from the Camel In message headers.

exposeListenerSession

true

Specifies whether the listener session should be exposed when consuming messages.

forceSendOriginalMessage

false

Camel 2.7: When using mapJmsMessage=false Camel will create a new JMS message to send to a new JMS destination if you touch the headers (get or set) during the route. Set this option to true to force Camel to send the original JMS message that was received.

idleTaskExecutionLimit

1

Specifies the limit for idle executions of a receive task, not having received any message within its execution. If this limit is reached, the task will shut down and leave receiving to other executing tasks (in the case of dynamic scheduling; see the maxConcurrentConsumers setting). There is additional doc available from Spring.

idleConsumerLimit

1

Camel 2.8.2, 2.9: Specify the limit for the number of consumers that are allowed to be idle at any given time.

includeSentJMSMessageID

false

Camel 2.10.3: Only applicable when sending to JMS destination using InOnly (eg fire and forget). Enabling this option will enrich the Camel Exchange with the actual JMSMessageID that was used by the JMS client when the message was sent to the JMS destination.

includeAllJMSXProperties

false

Camel 2.11.2/2.12: Whether to include all JMSXxxx properties when mapping from JMS to Camel Message. Setting this to true will include properties such as JMSXAppID, and JMSXUserID etc. Note: If you are using a custom headerFilterStrategy then this option does not apply.

jmsMessageType

null

Allows you to force the use of a specific javax.jms.Message implementation for sending JMS messages. Possible values are: Bytes, Map, Object, Stream, Text. By default, Camel would determine which JMS message type to use from the In body type. This option allows you to specify it.

jmsKeyFormatStrategy

default

Pluggable strategy for encoding and decoding JMS keys so they can be compliant with the JMS specification. Camel provides two implementations out of the box: default and passthrough. The default strategy will safely marshal dots and hyphens (. and -). The passthrough strategy leaves the key as is. Can be used for JMS brokers which do not care whether JMS header keys contain illegal characters. You can provide your own implementation of the org.apache.camel.component.jms.JmsKeyFormatStrategy and refer to it using the # notation.

jmsOperations

null

Allows you to use your own implementation of the org.springframework.jms.core.JmsOperations interface. Camel uses JmsTemplate as default. Can be used for testing purpose, but not used much as stated in the spring API docs.

lazyCreateTransactionManager

true

If true, Camel will create a JmsTransactionManager, if there is no transactionManager injected when option transacted=true.

listenerConnectionFactory

null

The JMS connection factory used for consuming messages.

mapJmsMessage

true

Specifies whether Camel should auto map the received JMS message to an appropiate payload type, such as javax.jms.TextMessage to a String etc. See section about how mapping works below for more details.

maximumBrowseSize

-1

Limits the number of messages fetched at most, when browsing endpoints using Browse or JMX API.

messageConverter

null

To use a custom Spring org.springframework.jms.support.converter.MessageConverter so you can be 100% in control how to map to/from a javax.jms.Message.

messageIdEnabled

true

When sending, specifies whether message IDs should be added.

messageListenerContainerFactoryRef

null

Camel 2.10.2: Registry ID of the MessageListenerContainerFactory used to determine what org.springframework.jms.listener.AbstractMessageListenerContainer to use to consume messages. Setting this will automatically set consumerType to Custom.

messageTimestampEnabled

true

Specifies whether timestamps should be enabled by default on sending messages.

password

null

The password for the connector factory.

priority

4

Values greater than 1 specify the message priority when sending (where 0 is the lowest priority and 9 is the highest). The explicitQosEnabled option must also be enabled in order for this option to have any effect.

pubSubNoLocal

false

Specifies whether to inhibit the delivery of messages published by its own connection.

receiveTimeout

None

The timeout for receiving messages (in milliseconds).

recoveryInterval

5000

Specifies the interval between recovery attempts, i.e. when a connection is being refreshed, in milliseconds. The default is 5000 ms, that is, 5 seconds.

replyToCacheLevelName

CACHE_CONSUMER

Camel 2.9.1: Sets the cache level by name for the reply consumer when doing request/reply over JMS. This option only applies when using fixed reply queues (not temporary). Camel will by default use: CACHE_CONSUMER for exclusive or shared w/ replyToSelectorName. And CACHE_SESSION for shared without replyToSelectorName. Some JMS brokers such as IBM WebSphere may require to set the replyToCacheLevelName=CACHE_NONE to work. Note: If using temporary queues then CACHE_NONE is not allowed, and you must use a higher value such as CACHE_CONSUMER or CACHE_SESSION.

replyToDestinationSelectorName

null

Sets the JMS Selector using the fixed name to be used so you can filter out your own replies from the others when using a shared queue (that is, if you are not using a temporary reply queue).

replyToDeliveryPersistent

true

Specifies whether to use persistent delivery by default for replies.

requestTimeoutCheckerInterval

1000

Camel 2.9.2: Configures how often Camel should check for timed out Exchanges when doing request/reply over JMS.By default Camel checks once per second. But if you must react faster when a timeout occurs, then you can lower this interval, to check more frequently. The timeout is determined by the option requestTimeout.

subscriptionDurable

false

@deprecated: Enabled by default, if you specify a durableSubscriptionName and a clientId.

taskExecutor

null

Allows you to specify a custom task executor for consuming messages.

taskExecutorSpring2

null

Camel 2.6: To use when using Spring 2.x with Camel. Allows you to specify a custom task executor for consuming messages.

templateConnectionFactory

null

The JMS connection factory used for sending messages.

transactedInOut

false

@deprecated: Specifies whether to use transacted mode for sending messages using the InOut Exchange Pattern. Applies only to producer endpoints. See section Enabling Transacted Consumption for more details.

transactionManager

null

The Spring transaction manager to use.

transactionName

"JmsConsumer[destinationName]"

The name of the transaction to use.

transactionTimeout

null

The timeout value of the transaction (in seconds), if using transacted mode.

transferException

false

If enabled and you are using Request Reply messaging (InOut) and an Exchange failed on the consumer side, then the caused Exception will be send back in response as a javax.jms.ObjectMessage. If the client is Camel, the returned Exception is rethrown. This allows you to use Camel JMS as a bridge in your routing - for example, using persistent queues to enable robust routing. Notice that if you also have transferExchange enabled, this option takes precedence. The caught exception is required to be serializable. The original Exception on the consumer side can be wrapped in an outer exception such as org.apache.camel.RuntimeCamelException when returned to the producer.

transferExchange

false

You can transfer the exchange over the wire instead of just the body and headers. The following fields are transferred: In body, Out body, Fault body, In headers, Out headers, Fault headers, exchange properties, exchange exception. This requires that the objects are serializable. Camel will exclude any non-serializable objects and log it at WARN level. You must enable this option on both the producer and consumer side, so Camel knows the payloads is an Exchange and not a regular payload.

username

null

The username for the connector factory.

useMessageIDAsCorrelationID

false

Specifies whether JMSMessageID should always be used as JMSCorrelationID for InOut messages.

useVersion102

false

@deprecated (removed from Camel 2.5 onwards): Specifies whether the old JMS API should be used.

Message Mapping between JMS and Camel

Camel automatically maps messages between javax.jms.Message and org.apache.camel.Message.

When sending a JMS message, Camel converts the message body to the following JMS message types:

Body Type

JMS Message

Comment

String

javax.jms.TextMessage

 

org.w3c.dom.Node

javax.jms.TextMessage

The DOM will be converted to String.

Map

javax.jms.MapMessage

 

java.io.Serializable

javax.jms.ObjectMessage

 

byte[]

javax.jms.BytesMessage

 

java.io.File

javax.jms.BytesMessage

 

java.io.Reader

javax.jms.BytesMessage

 

java.io.InputStream

javax.jms.BytesMessage

 

java.nio.ByteBuffer

javax.jms.BytesMessage

 

When receiving a JMS message, Camel converts the JMS message to the following body type:

JMS Message

Body Type

javax.jms.TextMessage

String

javax.jms.BytesMessage

byte[]

javax.jms.MapMessage

Map<String, Object>

javax.jms.ObjectMessage

Object

Disabling auto-mapping of JMS messages

You can use the mapJmsMessage option to disable the auto-mapping above. If disabled, Camel will not try to map the received JMS message, but instead uses it directly as the payload. This allows you to avoid the overhead of mapping and let Camel just pass through the JMS message. For instance, it even allows you to route javax.jms.ObjectMessage JMS messages with classes you do not have on the classpath.

Using a custom MessageConverter

You can use the messageConverter option to do the mapping yourself in a Spring org.springframework.jms.support.converter.MessageConverter class.

For example, in the route below we use a custom message converter when sending a message to the JMS order queue:

You can also use a custom message converter when consuming from a JMS destination.

Controlling the mapping strategy selected

You can use the jmsMessageType option on the endpoint URL to force a specific message type for all messages.
In the route below, we poll files from a folder and send them as javax.jms.TextMessage as we have forced the JMS producer endpoint to use text messages:

You can also specify the message type to use for each messabe by setting the header with the key CamelJmsMessageType. For example:

The possible values are defined in the enum class, org.apache.camel.jms.JmsMessageType.

Message format when sending

The exchange that is sent over the JMS wire must conform to the JMS Message spec.

For the exchange.in.header the following rules apply for the header keys:

  • Keys starting with JMS or JMSX are reserved.
  • exchange.in.headers keys must be literals and all be valid Java identifiers (do not use dots in the key name).
  • Camel replaces dots & hyphens and the reverse when when consuming JMS messages:
    . is replaced by _DOT_ and the reverse replacement when Camel consumes the message.
    - is replaced by _HYPHEN_ and the reverse replacement when Camel consumes the message.
  • See also the option jmsKeyFormatStrategy, which allows use of your own custom strategy for formatting keys.

For the exchange.in.header, the following rules apply for the header values:

  • The values must be primitives or their counter objects (such as Integer, Long, Character). The types, String, CharSequence, Date, BigDecimal and BigInteger are all converted to their toString() representation. All other types are dropped.

Camel will log with category org.apache.camel.component.jms.JmsBinding at DEBUG level if it drops a given header value. For example:

Message format when receiving

Camel adds the following properties to the Exchange when it receives a message:

Property

Type

Description

org.apache.camel.jms.replyDestination

javax.jms.Destination

The reply destination.

Camel adds the following JMS properties to the In message headers when it receives a JMS message:

Header

Type

Description

JMSCorrelationID

String

The JMS correlation ID.

JMSDeliveryMode

int

The JMS delivery mode.

JMSDestination

javax.jms.Destination

The JMS destination.

JMSExpiration

long

The JMS expiration.

JMSMessageID

String

The JMS unique message ID.

JMSPriority

int

The JMS priority (with 0 as the lowest priority and 9 as the highest).

JMSRedelivered

boolean

Is the JMS message redelivered.

JMSReplyTo

javax.jms.Destination

The JMS reply-to destination.

JMSTimestamp

long

The JMS timestamp.

JMSType

String

The JMS type.

JMSXGroupID

String

The JMS group ID.

As all the above information is standard JMS you can check the JMS documentation for further details.

About using Camel to send and receive messages and JMSReplyTo

The JMS component is complex and you have to pay close attention to how it works in some cases. So this is a short summary of some of the areas/pitfalls to look for.

When Camel sends a message using its JMSProducer, it checks the following conditions:

  • The message exchange pattern,
  • Whether a JMSReplyTo was set in the endpoint or in the message headers,
  • Whether any of the following options have been set on the JMS endpoint: disableReplyTo, preserveMessageQos, explicitQosEnabled.

All this can be a tad complex to understand and configure to support your use case.

JmsProducer

The JmsProducer behaves as follows, depending on configuration:

Exchange Pattern

Other options

Description

InOut

-

Camel will expect a reply, set a temporary JMSReplyTo, and after sending the message, it will start to listen for the reply message on the temporary queue.

InOut

JMSReplyTo is set

Camel will expect a reply and, after sending the message, it will start to listen for the reply message on the specified JMSReplyTo queue.

InOnly

-

Camel will send the message and not expect a reply.

InOnly

JMSReplyTo is set

By default, Camel discards the JMSReplyTo destination and clears the JMSReplyTo header before sending the message. Camel then sends the message and does not expect a reply. Camel logs this in the log at WARN level (changed to DEBUG level from Camel 2.6 onwards. You can use preserveMessageQuo=true to instruct Camel to keep the JMSReplyTo. In all situations the JmsProducer does not expect any reply and thus continue after sending the message.

JmsConsumer

The JmsConsumer behaves as follows, depending on configuration:

Exchange Pattern

Other options

Description

InOut

-

Camel will send the reply back to the JMSReplyTo queue.

InOnly

-

Camel will not send a reply back, as the pattern is InOnly.

-

disableReplyTo=true

This option suppresses replies.

So pay attention to the message exchange pattern set on your exchanges.

If you send a message to a JMS destination in the middle of your route you can specify the exchange pattern to use, see more at Request Reply.
This is useful if you want to send an InOnly message to a JMS topic:

Reuse endpoint and send to different destinations computed at runtime

If you need to send messages to a lot of different JMS destinations, it makes sense to reuse a JMS endpoint and specify the real destination in a message header. This allows Camel to reuse the same endpoint, but send to different destinations. This greatly reduces the number of endpoints created and economizes on memory and thread resources.

You can specify the destination in the following headers:

Header

Type

Description

CamelJmsDestination

javax.jms.Destination

A destination object.

CamelJmsDestinationName

String

The destination name.

For example, the following route shows how you can compute a destination at run time and use it to override the destination appearing in the JMS URL:

The queue name, dummy, is just a placeholder. It must be provided as part of the JMS endpoint URL, but it will be ignored in this example.

In the computeDestination bean, specify the real destination by setting the CamelJmsDestinationName header as follows:

Then Camel will read this header and use it as the destination instead of the one configured on the endpoint. So, in this example Camel sends the message to activemq:queue:order:2, assuming the id value was 2.

If both the CamelJmsDestination and the CamelJmsDestinationName headers are set, CamelJmsDestination takes priority. Keep in mind that the JMS producer removes both CamelJmsDestination and CamelJmsDestinationName headers from the exchange and do not propagate them to the created JMS message in order to avoid the accidental loops in the routes (in scenarios when the message will be forwarded to the another JMS endpoint).

Configuring different JMS providers

You can configure your JMS provider in Spring XML as follows:

Basically, you can configure as many JMS component instances as you wish and give them a unique name using the id attribute. The preceding example configures an activemq component. You could do the same to configure MQSeries, TibCo, BEA, Sonic and so on.

Once you have a named JMS component, you can then refer to endpoints within that component using URIs. For example for the component name, activemq, you can then refer to destinations using the URI format, activemq:[queue:|topic:]destinationName. You can use the same approach for all other JMS providers.

This works by the SpringCamelContext lazily fetching components from the spring context for the scheme name you use for Endpoint URIs and having the Component resolve the endpoint URIs.

Using JNDI to find the ConnectionFactory

If you are using a J2EE container, you might need to look up JNDI to find the JMS ConnectionFactory rather than use the usual <bean> mechanism in Spring. You can do this using Spring's factory bean or the new Spring XML namespace. For example:

See The jee schema in the Spring reference documentation for more details about JNDI lookup.

Concurrent Consuming

A common requirement with JMS is to consume messages concurrently in multiple threads in order to make an application more responsive. You can set the concurrentConsumers option to specify the number of threads servicing the JMS endpoint, as follows:

You can configure this option in one of the following ways:

  • On the JmsComponent,
  • On the endpoint URI or,
  • By invoking setConcurrentConsumers() directly on the JmsEndpoint.

Concurrent Consuming with async consumer

Notice that each concurrent consumer will only pickup the next available message from the JMS broker, when the current message has been fully processed. You can set the option asyncConsumer=true to let the consumer pickup the next message from the JMS queue, while the previous message is being processed asynchronously (by the Asynchronous Routing Engine). See more details in the table on top of the page about the asyncConsumer option.

Request-reply over JMS

Camel supports Request Reply over JMS. In essence the MEP of the Exchange should be InOut when you send a message to a JMS queue.

Camel offers a number of options to configure request/reply over JMS that influence performance and clustered environments. The table below summaries the options.

Option

Performance

Cluster

Description

Temporary

Fast

Yes

A temporary queue is used as reply queue, and automatic created by Camel. To use this do not specify a replyTo queue name. And you can optionally configure replyToType=Temporary to make it stand out that temporary queues are in use.

Shared

Slow

Yes

A shared persistent queue is used as reply queue. The queue must be created beforehand, although some brokers can create them on the fly such as Apache ActiveMQ. To use this you must specify the replyTo queue name. And you can optionally configure replyToType=Shared to make it stand out that shared queues are in use. A shared queue can be used in a clustered environment with multiple nodes running this Camel application at the same time. All using the same shared reply queue. This is possible because JMS Message selectors are used to correlate expected reply messages; this impacts performance though. JMS Message selectors is slower, and therefore not as fast as Temporary or Exclusive queues. See further below how to tweak this for better performance.

Exclusive

Fast

No (*Yes)

An exclusive persistent queue is used as reply queue. The queue must be created beforehand, although some brokers can create them on the fly such as Apache ActiveMQ. To use this you must specify the replyTo queue name. And you must configure replyToType=Exclusive to instruct Camel to use exclusive queues, as Shared is used by default, if a replyTo queue name was configured. When using exclusive reply queues, then JMS Message selectors are not in use, and therefore other applications must not use this queue as well. An exclusive queue cannot be used in a clustered environment with multiple nodes running this Camel application at the same time; as we do not have control if the reply queue comes back to the same node that sent the request message; that is why shared queues use JMS Message selectors to make sure of this. Though if you configure each Exclusive reply queue with an unique name per node, then you can run this in a clustered environment. As then the reply message will be sent back to that queue for the given node, that awaits the reply message.

concurrentConsumers

Fast

Yes

Camel 2.10.3: Allows to process reply messages concurrently using concurrent message listeners in use. You can specify a range using the concurrentConsumers and maxConcurrentConsumers options. Notice: That using Shared reply queues may not work as well with concurrent listeners, so use this option with care.

maxConcurrentConsumers

Fast

Yes

Camel 2.10.3: Allows to process reply messages concurrently using concurrent message listeners in use. You can specify a range using the concurrentConsumers and maxConcurrentConsumers options. Notice: That using Shared reply queues may not work as well with concurrent listeners, so use this option with care.

The JmsProducer detects the InOut and provides a JMSReplyTo header with the reply destination to be used. By default Camel uses a temporary queue, but you can use the replyTo option on the endpoint to specify a fixed reply queue (see more below about fixed reply queue).

Camel will automatic setup a consumer which listen on the reply queue, so you should not do anything.
This consumer is a Spring DefaultMessageListenerContainer which listen for replies. However it's fixed to 1 concurrent consumer.
That means replies will be processed in sequence as there are only 1 thread to process the replies. If you want to process replies faster, then we need to use concurrency. But not using the concurrentConsumer option. We should use the threads from the Camel DSL instead, as shown in the route below:

Icon

Instead of using threads, then use concurrentConsumers option if using Camel 2.10.3 or better. See further below.

In this route we instruct Camel to route replies asynchronously using a thread pool with 5 threads.

From Camel 2.10.3 onwards you can now configure the listener to use concurrent threads using the concurrentConsumers and maxConcurrentConsumers options. This allows you to easier configure this in Camel as shown below:

Request-reply over JMS and using a shared fixed reply queue

If you use a fixed reply queue when doing Request Reply over JMS as shown in the example below, then pay attention.

In this example the fixed reply queue named "bar" is used. By default Camel assumes the queue is shared when using fixed reply queues, and therefore it uses a JMSSelector to only pickup the expected reply messages (eg based on the JMSCorrelationID). See next section for exclusive fixed reply queues. That means its not as fast as temporary queues. You can speedup how often Camel will pull for reply messages using the receiveTimeout option. By default its 1000 millis. So to make it faster you can set it to 250 millis to pull 4 times per second as shown:

Notice this will cause the Camel to send pull requests to the message broker more frequent, and thus require more network traffic.
It is generally recommended to use temporary queues if possible.

Request-reply over JMS and using an exclusive fixed reply queue

Available as of Camel 2.9

In the previous example, Camel would anticipate the fixed reply queue named "bar" was shared, and thus it uses a JMSSelector to only consume reply messages which it expects. However there is a drawback doing this as JMS selectos is slower. Also the consumer on the reply queue is slower to update with new JMS selector ids. In fact it only updates when the receiveTimeout option times out, which by default is 1 second. So in theory the reply messages could take up till about 1 sec to be detected. On the other hand if the fixed reply queue is exclusive to the Camel reply consumer, then we can avoid using the JMS selectors, and thus be more performant. In fact as fast as using temporary queues. So in Camel 2.9 onwards we introduced the ReplyToType option which you can configure to Exclusive
to tell Camel that the reply queue is exclusive as shown in the example below:

Mind that the queue must be exclusive to each and every endpoint. So if you have two routes, then they each need an unique reply queue as shown in the next example:

The same applies if you run in a clustered environment. Then each node in the cluster must use an unique reply queue name. As otherwise each node in the cluster may pickup messages which was intended as a reply on another node. For clustered environments its recommended to use shared reply queues instead.

Synchronizing clocks between senders and receivers

When doing messaging between systems, its desirable that the systems have synchronized clocks. For example when sending a JMS message, then you can set a time to live value on the message. Then the receiver can inspect this value, and determine if the message is already expired, and thus drop the message instead of consume and process it. However this requires that both sender and receiver have synchronized clocks. If you are using ActiveMQ then you can use the timestamp plugin to synchronize clocks.

About time to live

Read first above about synchronized clocks.

When you do request/reply (InOut) over JMS with Camel then Camel uses a timeout on the sender side, which is default 20 seconds from the requestTimeout option. You can control this by setting a higher/lower value. However the time to live value is still set on the JMS message being send. So that requires the clocks to be synchronized between the systems. If they are not, then you may want to disable the time to live value being set. This is now possible using the disableTimeToLive option from Camel 2.8 onwards. So if you set this option to disableTimeToLive=true, then Camel does not set any time to live value when sending JMS messages. But the request timeout is still active. So for example if you do request/reply over JMS and have disabled time to live, then Camel will still use a timeout by 20 seconds (the requestTimeout option). That option can of course also be configured. So the two options requestTimeout and disableTimeToLive gives you fine grained control when doing request/reply.

From Camel 2.13/2.12.3 onwards you can provide a header in the message to override and use as the request timeout value instead of the endpoint configured value. For example:

In the route above we have a endpoint configured requestTimeout of 30 seconds. So Camel will wait up till 30 seconds for that reply message to come back on the bar queue. If no reply message is received then a org.apache.camel.ExchangeTimedOutException is set on the Exchange and Camel continues routing the message, which would then fail due the exception, and Camel's error handler reacts.

If you want to use a per message timeout value, you can set the header with key org.apache.camel.component.jms.JmsConstants#JMS_REQUEST_TIMEOUT which has constant value "CamelJmsRequestTimeout" with a timeout value as long type.

For example we can use a bean to compute the timeout value per individual message, such as calling the "whatIsTheTimeout" method on the service bean as shown below:

When you do fire and forget (InOut) over JMS with Camel then Camel by default does not set any time to live value on the message. You can configure a value by using the timeToLive option. For example to indicate a 5 sec., you set timeToLive=5000. The option disableTimeToLive can be used to force disabling the time to live, also for InOnly messaging. The requestTimeout option is not being used for InOnly messaging.

Enabling Transacted Consumption

A common requirement is to consume from a queue in a transaction and then process the message using the Camel route. To do this, just ensure that you set the following properties on the component/endpoint:

  • transacted = true
  • transactionManager = a Transsaction Manager - typically the JmsTransactionManager

See the Transactional Client EIP pattern for further details.

Transactions and [Request Reply] over JMS

Icon

When using Request Reply over JMS you cannot use a single transaction; JMS will not send any messages until a commit is performed, so the server side won't receive anything at all until the transaction commits. Therefore to use Request Reply you must commit a transaction after sending the request and then use a separate transaction for receiving the response.

To address this issue the JMS component uses different properties to specify transaction use for oneway messaging and request reply messaging:

The transacted property applies only to the InOnly message Exchange Pattern (MEP).

The transactedInOut property applies to the InOut(Request Reply) message Exchange Pattern (MEP).

If you want to use transactions for Request Reply(InOut MEP), you must set transactedInOut=true.

Available as of Camel 2.10

You can leverage the DMLC transacted session API using the following properties on component/endpoint:

  • transacted = true
  • lazyCreateTransactionManager = false

The benefit of doing so is that the cacheLevel setting will be honored when using local transactions without a configured TransactionManager. When a TransactionManager is configured, no caching happens at DMLC level and its necessary to rely on a pooled connection factory. For more details about this kind of setup see here and here.

Using JMSReplyTo for late replies

When using Camel as a JMS listener, it sets an Exchange property with the value of the ReplyTo javax.jms.Destination object, having the key ReplyTo. You can obtain this Destination as follows:

And then later use it to send a reply using regular JMS or Camel.

A different solution to sending a reply is to provide the replyDestination object in the same Exchange property when sending. Camel will then pick up this property and use it for the real destination. The endpoint URI must include a dummy destination, however. For example:

Using a request timeout

In the sample below we send a Request Reply style message Exchange (we use the requestBody method = InOut) to the slow queue for further processing in Camel and we wait for a return reply:

Samples

JMS is used in many examples for other components as well. But we provide a few samples below to get started.

Receiving from JMS

In the following sample we configure a route that receives JMS messages and routes the message to a POJO:

You can of course use any of the EIP patterns so the route can be context based. For example, here's how to filter an order topic for the big spenders:

Sending to a JMS

In the sample below we poll a file folder and send the file content to a JMS topic. As we want the content of the file as a TextMessage instead of a BytesMessage, we need to convert the body to a String:

Using Annotations

Camel also has annotations so you can use POJO Consuming and POJO Producing.

Spring DSL sample

The preceding examples use the Java DSL. Camel also supports Spring XML DSL. Here is the big spender sample using Spring DSL:

Other samples

JMS appears in many of the examples for other components and EIP patterns, as well in this Camel documentation. So feel free to browse the documentation. If you have time, check out the this tutorial that uses JMS but focuses on how well Spring Remoting and Camel works together Tutorial-JmsRemoting.

Using JMS as a Dead Letter Queue storing Exchange

Normally, when using JMS as the transport, it only transfers the body and headers as the payload. If you want to use JMS with a Dead Letter Channel, using a JMS queue as the Dead Letter Queue, then normally the caused Exception is not stored in the JMS message. You can, however, use the transferExchange option on the JMS dead letter queue to instruct Camel to store the entire Exchange in the queue as a javax.jms.ObjectMessage that holds a org.apache.camel.impl.DefaultExchangeHolder. This allows you to consume from the Dead Letter Queue and retrieve the caused exception from the Exchange property with the key Exchange.EXCEPTION_CAUGHT. The demo below illustrates this:

Then you can consume from the JMS queue and analyze the problem:

Using JMS as a Dead Letter Channel storing error only

You can use JMS to store the cause error message or to store a custom body, which you can initialize yourself. The following example uses the Message Translator EIP to do a transformation on the failed exchange before it is moved to the JMS dead letter queue:

Here we only store the original cause error message in the transform. You can, however, use any Expression to send whatever you like. For example, you can invoke a method on a Bean or use a custom processor.

Sending an InOnly message and keeping the JMSReplyTo header

When sending to a JMS destination using camel-jms the producer will use the MEP to detect if its InOnly or InOut messaging. However there can be times where you want to send an InOnly message but keeping the JMSReplyTo header. To do so you have to instruct Camel to keep it, otherwise the JMSReplyTo header will be dropped.

For example to send an InOnly message to the foo queue, but with a JMSReplyTo with bar queue you can do as follows:

Notice we use preserveMessageQos=true to instruct Camel to keep the JMSReplyTo header.

Setting JMS provider options on the destination

Some JMS providers, like IBM's WebSphere MQ need options to be set on the JMS destination. For example, you may need to specify the targetClient option. Since targetClient is a WebSphere MQ option and not a Camel URI option, you need to set that on the JMS destination name like so:

Some versions of WMQ won't accept this option on the destination name and you will get an exception like:

com.ibm.msg.client.jms.DetailedJMSException: JMSCC0005: The specified value 'MY_QUEUE?targetClient=1' is not allowed for 'XMSC_DESTINATION_NAME'

A workaround is to use a custom DestinationResolver:

See Also

CamelJmsDestination

JMX Component

Available as of Camel 2.6

Standard JMX Consumer Configuration

Component allows consumers to subscribe to an mbean's Notifications. The component supports passing the Notification object directly through the Exchange or serializing it to XML according to the schema provided within this project. This is a consumer only component. Exceptions are thrown if you attempt to create a producer for it.

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

URI Format

The component can connect to the local platform mbean server with the following URI:

A remote mbean server url can be provided following the initial JMX scheme like so:

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

URI Options

Property

Required

Default

Description

format

 

xml

Format for the message body. Either "xml" or "raw". If xml, the notification is serialized to xml. If raw, then the raw java object is set as the body.

user

 

 

Credentials for making a remote connection.

password

 

 

Credentials for making a remote connection.

objectDomain

yes

 

The domain for the mbean you're connecting to.

objectName

 

 

The name key for the mbean you're connecting to. This value is mutually exclusive with the object properties that get passed. (see below)

notificationFilter

 

 

Reference to a bean that implements the NotificationFilter. The #ref syntax should be used to reference the bean via the Registry.

handback

 

 

Value to handback to the listener when a notification is received. This value will be put in the message header with the key "jmx.handback"

testConnectionOnStartup

 

true

Camel 2.11 If true, the consumer will throw an exception when unable to establish the JMX connection upon startup. If false, the consumer will attempt to establish the JMX connection every 'x' seconds until the connection is made – where 'x' is the configured reconnectDelay.

reconnectOnConnectionFailure

 

false

Camel 2.11 If true, the consumer will attempt to reconnect to the JMX server when any connection failure occurs. The consumer will attempt to re-establish the JMX connection every 'x' seconds until the connection is made-- where 'x' is the configured reconnectDelay.

reconnectDelay

 

10 seconds

Camel 2.11 The number of seconds to wait before retrying creation of the initial connection or before reconnecting a lost connection.

ObjectName Construction

The URI must always have the objectDomain property. In addition, the URI must contain either objectName or one or more properties that start with "key."

Domain with Name property

When the objectName property is provided, the following constructor is used to build the ObjectName? for the mbean:

The key value in the above will be "name" and the value will be the value of the objectName property.

Domain with Hashtable

The Hashtable is constructed by extracting properties that start with "key." The properties will have the "key." prefixed stripped prior to building the Hashtable. This allows the URI to contain a variable number of properties to identify the mbean.

Example

Full example

Monitor Type Consumer

Available as of Camel 2.8
One popular use case for JMX is creating a monitor bean to monitor an attribute on a deployed bean. This requires writing a few lines of Java code to create the JMX monitor and deploy it. As shown below:

The 2.8 version introduces a new type of consumer that automatically creates and registers a monitor bean for the specified objectName and attribute. Additional endpoint attributes allow the user to specify the attribute to monitor, type of monitor to create, and any other required properties. The code snippet above is condensed into a set of endpoint properties. The consumer uses these properties to create the CounterMonitor, register it, and then subscribe to its changes. All of the JMX monitor types are supported.

Example

The example above will cause a new Monitor Bean to be created and depoyed to the local mbean server that monitors the "MonitorNumber" attribute on the "simpleBean." Additional types of monitor beans and options are detailed below. The newly deployed monitor bean is automatically undeployed when the consumer is stopped.

URI Options for Monitor Type

property

type

applies to

description

monitorType

enum

all

one of counter, guage, string

observedAttribute

string

all

the attribute being observed

granualityPeriod

long

all

granularity period (in millis) for the attribute being observed. As per JMX, default is 10 seconds

initThreshold

number

counter

initial threshold value

offset

number

counter

offset value

modulus

number

counter

modulus value

differenceMode

boolean

counter, gauge

true if difference should be reported, false for actual value

notifyHigh

boolean

gauge

high notification on/off switch

notifyLow

boolean

gauge

low notification on/off switch

highThreshold

number

gauge

threshold for reporting high notification

lowThreshold

number

gauge

threshold for reporting low notificaton

notifyDiffer

boolean

string

true to fire notification when string differs

notifyMatch

boolean

string

true to fire notification when string matches

stringToCompare

string

string

string to compare against the attribute value

The monitor style consumer is only supported for the local mbean server. JMX does not currently support remote deployment of mbeans without either having the classes already remotely deployed or an adapter library on both the client and server to facilitate a proxy deployment.

See Also

JPA Component

The jpa component enables you to store and retrieve Java objects from persistent storage using EJB 3's Java Persistence Architecture (JPA), which is a standard interface layer that wraps Object/Relational Mapping (ORM) products such as OpenJPA, Hibernate, TopLink, and so on.

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

Sending to the endpoint

You can store a Java entity bean in a database by sending it to a JPA producer endpoint. The body of the In message is assumed to be an entity bean (that is, a POJO with an @Entity annotation on it) or a collection or array of entity beans.

If the body does not contain one of the previous listed types, put a Message Translator in front of the endpoint to perform the necessary conversion first.

Consuming from the endpoint

Consuming messages from a JPA consumer endpoint removes (or updates) entity beans in the database. This allows you to use a database table as a logical queue: consumers take messages from the queue and then delete/update them to logically remove them from the queue.

If you do not wish to delete the entity bean when it has been processed (and when routing is done), you can specify consumeDelete=false on the URI. This will result in the entity being processed each poll.

If you would rather perform some update on the entity to mark it as processed (such as to exclude it from a future query) then you can annotate a method with @Consumed which will be invoked on your entity bean when the entity bean when it has been processed (and when routing is done).

From Camel 2.13 onwards you can use @PreConsumed which will be invoked on your entity bean before it has been processed (before routing).

URI format

For sending to the endpoint, the entityClassName is optional. If specified, it helps the Type Converter to ensure the body is of the correct type.

For consuming, the entityClassName is mandatory.

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

Options

Name

Default Value

Description

entityType

entityClassName

Overrides the entityClassName from the URI.

persistenceUnit

camel

The JPA persistence unit used by default.

consumeDelete

true

JPA consumer only: If true, the entity is deleted after it is consumed; if false, the entity is not deleted.

consumeLockEntity

true

JPA consumer only: Specifies whether or not to set an exclusive lock on each entity bean while processing the results from polling.

flushOnSend

true

JPA producer only: Flushes the EntityManager after the entity bean has been persisted.

maximumResults

-1

JPA consumer only: Set the maximum number of results to retrieve on the Query.

transactionManager

null

This option is Registry based which requires the # notation so that the given transactionManager being specified can be looked up properly, e.g. transactionManager=#myTransactionManager. It specifies the transaction manager to use. If none provided, Camel will use a JpaTransactionManager by default. Can be used to set a JTA transaction manager (for integration with an EJB container).

consumer.delay

500

JPA consumer only: Delay in milliseconds between each poll.

consumer.initialDelay

1000

JPA consumer only: Milliseconds before polling starts.

consumer.useFixedDelay

false

JPA consumer only: Set to true to use fixed delay between polls, otherwise fixed rate is used. See ScheduledExecutorService in JDK for details.

maxMessagesPerPoll

0

JPA consumer only: An integer value to define the maximum number of messages to gather per poll. By default, no maximum is set. Can be used to avoid polling many thousands of messages when starting up the server. Set a value of 0 or negative to disable.

consumer.query

 

JPA consumer only: To use a custom query when consuming data.

consumer.namedQuery

 

JPA consumer only: To use a named query when consuming data.

consumer.nativeQuery

 

JPA consumer only: To use a custom native query when consuming data. You may want to use the option consumer.resultClass also when using native queries.

consumer.parameters

 

Camel 2.12: JPA consumer only: This option is Registry based which requires the # notation. This key/value mapping is used for building the query parameters. It's is expected to be of the generic type java.util.Map<String, Object> where the keys are the named parameters of a given JPA query and the values are their corresponding effective values you want to select for.

consumer.resultClass

 

Camel 2.7: JPA consumer only: Defines the type of the returned payload (we will call entityManager.createNativeQuery(nativeQuery, resultClass) instead of entityManager.createNativeQuery(nativeQuery)). Without this option, we will return an object array. Only has an affect when using in conjunction with native query when consuming data.

consumer.transacted

false

Camel 2.7.5/2.8.3/2.9: JPA consumer only: Whether to run the consumer in transacted mode, by which all messages will either commit or rollback, when the entire batch has been processed. The default behavior (false) is to commit all the previously successfully processed messages, and only rollback the last failed message.

consumer.lockModeType

WRITE

Camel 2.11.2/2.12: To configure the lock mode on the consumer. The possible values is defined in the enum javax.persistence.LockModeType. The default value is changed to PESSIMISTIC_WRITE since Camel 2.13.

consumer.SkipLockedEntity

false

Camel 2.13: To configure whether to use NOWAIT on lock and silently skip the entity.

usePersist

false

Camel 2.5: JPA producer only: Indicates to use entityManager.persist(entity) instead of entityManager.merge(entity). Note: entityManager.persist(entity) doesn't work for detached entities (where the EntityManager has to execute an UPDATE instead of an INSERT query)!

joinTransaction

true

Camel 2.12.3: camel-jpa will join transaction by default from Camel 2.12 onwards. You can use this option to turn this off, for example if you use LOCAL_RESOURCE and join transaction doesn't work with your JPA provider. This option can also be set globally on the JpaComponent, instead of having to set it on all endpoints.

usePassedInEntityManager

falseCamel 2.12.4/2.13.1 JPA producer only: If set to true, then Camel will use the EntityManager from the header

JpaConstants.ENTITYMANAGER instead of the configured entity manager on the component/endpoint. This allows end users to control which entity manager will be in use.

Message Headers

Camel adds the following message headers to the exchange:

Header

Type

Description

CamelJpaTemplate

JpaTemplate

Not supported anymore since Camel 2.12: The JpaTemplate object that is used to access the entity bean. You need this object in some situations, for instance in a type converter or when you are doing some custom processing. See CAMEL-5932 for the reason why the support for this header has been dropped.

CamelEntityManager

EntityManager

Camel 2.12: JPA consumer / Camel 2.12.2: JPA producer: The JPA EntityManager object being used by JpaConsumer or JpaProducer.

Configuring EntityManagerFactory

Its strongly advised to configure the JPA component to use a specific EntityManagerFactory instance. If failed to do so each JpaEndpoint will auto create their own instance of EntityManagerFactory which most often is not what you want.

For example, you can instantiate a JPA component that references the myEMFactory entity manager factory, as follows:

In Camel 2.3 the JpaComponent will auto lookup the EntityManagerFactory from the Registry which means you do not need to configure this on the JpaComponent as shown above. You only need to do so if there is ambiguity, in which case Camel will log a WARN.

Configuring TransactionManager

Since Camel 2.3 the JpaComponent will auto lookup the TransactionManager from the Registry. If Camel won't find any TransactionManager instance registered, it will also look up for the TransactionTemplate and try to extract TransactionManager from it.

If none TransactionTemplate is available in the registry, JpaEndpoint will auto create their own instance of TransactionManager which most often is not what you want.

If more than single instance of the TransactionManager is found, Camel will log a WARN. In such cases you might want to instantiate and explicitly configure a JPA component that references the myTransactionManager transaction manager, as follows:

Using a consumer with a named query

For consuming only selected entities, you can use the consumer.namedQuery URI query option. First, you have to define the named query in the JPA Entity class:

After that you can define a consumer uri like this one:

Using a consumer with a query

For consuming only selected entities, you can use the consumer.query URI query option. You only have to define the query option:

Using a consumer with a native query

For consuming only selected entities, you can use the consumer.nativeQuery URI query option. You only have to define the native query option:

If you use the native query option, you will receive an object array in the message body.

Example

See Tracer Example for an example using JPA to store traced messages into a database.

Using the JPA based idempotent repository

In this section we will use the JPA based idempotent repository.

First we need to setup a persistence-unit in the persistence.xml file:

Second we have to setup a org.springframework.orm.jpa.JpaTemplate which is used by the org.apache.camel.processor.idempotent.jpa.JpaMessageIdRepository:

Afterwards we can configure our org.apache.camel.processor.idempotent.jpa.JpaMessageIdRepository:

And finally we can create our JPA idempotent repository in the spring XML file as well:

When running this Camel component tests inside your IDE

Icon

In case you run the tests of this component directly inside your IDE (and not necessarily through Maven itself) then you could spot exceptions like:

The problem here is that the source has been compiled/recompiled through your IDE and not through Maven itself which would enhance the byte-code at build time. To overcome this you would need to enable dynamic byte-code enhancement of OpenJPA. As an example assuming the current OpenJPA version being used in Camel itself is 2.2.1, then as running the tests inside your favorite IDE you would need to pass the following argument to the JVM:

Then it will all become green again (smile)

See Also

JT/400 Component

The jt400 component allows you to exchanges messages with an AS/400 system using data queues.

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

URI format

To call remote program (Camel 2.7)

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

URI options

For the data queue message exchange:

Name

Default value

Description

ccsid

default system CCSID

Specifies the CCSID to use for the connection with the AS/400 system.

format

text

Specifies the data format for sending messages
valid options are: text (represented by String) and binary (represented by byte[])

consumer.delay

500

Delay in milliseconds between each poll.

consumer.initialDelay

1000

Milliseconds before polling starts.

consumer.userFixedDelay

false

true to use fixed delay between polls, otherwise fixed rate is used. See ScheduledExecutorService in JDK for details.

guiAvailable

false

Camel 2.8: Specifies whether AS/400 prompting is enabled in the environment running Camel.

keyed

false

Camel 2.10: Whether to use keyed or non-keyed data queues.

searchKey

null

Camel 2.10: Search key for keyed data queues.

searchType

EQ

Camel 2.10: Search type which can be a value of EQ, NE, LT, LE, GT, or GE.

connectionPool

AS400ConnectionPool instance

Camel 2.10: Reference to an com.ibm.as400.access.AS400ConnectionPool instance in the Registry. This is used for obtaining connections to the AS/400 system. The look up notation ('#' character) should be used.

For the remote program call (Camel 2.7)

Name

Default value

Description

outputFieldsIdx

 

Specifies which fields (program parameters) are output parameters.

fieldsLength

 

Specifies the fields (program parameters) length as in the AS/400 program definition.

format

text

Camel 2.10: Specifies the data format for sending messages
valid options are: text (represented by String) and binary (represented by byte[])

guiAvailable

false

Camel 2.8: Specifies whether AS/400 prompting is enabled in the environment running Camel.

connectionPool

AS400ConnectionPool instance

Camel 2.10: Reference to an com.ibm.as400.access.AS400ConnectionPool instance in the Registry. This is used for obtaining connections to the AS/400 system. The look up notation ('#' character) should be used.

Usage

When configured as a consumer endpoint, the endpoint will poll a data queue on a remote system. For every entry on the data queue, a new Exchange is sent with the entry's data in the In message's body, formatted either as a String or a byte[], depending on the format. For a provider endpoint, the In message body contents will be put on the data queue as either raw bytes or text.

Connection pool

Available as of Camel 2.10

Connection pooling is in use from Camel 2.10 onwards. You can explicit configure a connection pool on the Jt400Component, or as an uri option on the endpoint.

Remote program call (Camel 2.7)

This endpoint expects the input to be either a String array or byte[] array (depending on format) and handles all the CCSID handling through the native jt400 library mechanisms. A parameter can be omitted by passing null as the value in its position (the remote program has to support it). After the program execution the endpoint returns either a String array or byte[] array with the values as they were returned by the program (the input only parameters will contain the same data as the beginning of the invocation)
This endpoint does not implement a provider endpoint!

Example

In the snippet below, the data for an exchange sent to the direct:george endpoint will be put in the data queue PENNYLANE in library BEATLES on a system named LIVERPOOL.
Another user connects to the same data queue to receive the information from the data queue and forward it to the mock:ringo endpoint.

Remote program call example (Camel 2.7)

In the snippet below, the data Exchange sent to the direct:work endpoint will contain three string that will be used as the arguments for the program “compute” in the library “assets”. This program will write the output values in the 2nd and 3rd parameters. All the parameters will be sent to the direct:play endpoint.

Writing to keyed data queues

Reading from keyed data queues

See Also

Language

Available as of Camel 2.5

The language component allows you to send Exchange to an endpoint which executes a script by any of the supported Languages in Camel.
By having a component to execute language scripts, it allows more dynamic routing capabilities. For example by using the Routing Slip or Dynamic Router EIPs you can send messages to language endpoints where the script is dynamic defined as well.

This component is provided out of the box in camel-core and hence no additional JARs is needed. You only have to include additional Camel components if the language of choice mandates it, such as using Groovy or JavaScript languages.

URI format

And from Camel 2.11 onwards you can refer to an external resource for the script using same notation as supported by the other Languages in Camel

URI Options

The component supports the following options.

Name

Default Value

Type

Description

languageName

null

String

The name of the Language to use, such as simple, groovy, javascript etc. This option is mandatory.

script

null

String

The script to execute.

transform

true

boolean

Whether or not the result of the script should be used as the new message body. By setting to false the script is executed but the result of the script is discarded.

contentCache

true

boolean

Camel 2.9: Whether to cache the script if loaded from a resource.
Note: from Camel 2.10.3 a cached script can be forced to reload at runtime via JMX using the clearContentCache operation.

cacheScript

false

boolean

Camel 2.13/2.12.2/2.11.3: Whether to cache the compiled script. Turning this option on can gain performance as the script is only compiled/created once, and reuse when processing Camel messages. But this may cause side-effects with data left from previous evaluation spills into the next, and concurrency issues as well. If the script being evaluated is idempotent then this option can be turned on.

Message Headers

The following message headers can be used to affect the behavior of the component

Header

Description

CamelLanguageScript

The script to execute provided in the header. Takes precedence over script configured on the endpoint.

Examples

For example you can use the Simple language to Message Translator a message:

In case you want to convert the message body type you can do this as well:

You can also use the Groovy language, such as this example where the input message will by multiplied with 2:

You can also provide the script as a header as shown below. Here we use XPath language to extract the text from the <foo> tag.

Loading scripts from resources

Available as of Camel 2.9

You can specify a resource uri for a script to load in either the endpoint uri, or in the Exchange.LANGUAGE_SCRIPT header.
The uri must start with one of the following schemes: file:, classpath:, or http:

For example to load a script from the classpath:

By default the script is loaded once and cached. However you can disable the contentCache option and have the script loaded on each evaluation.
For example if the file myscript.txt is changed on disk, then the updated script is used:

From Camel 2.11 onwards you can refer to the resource similar to the other Languages in Camel by prefixing with "resource:" as shown below:

See Also

LDAP Component

The ldap component allows you to perform searches in LDAP servers using filters as the message payload.
This component uses standard JNDI (javax.naming package) to access the server.

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

URI format

The ldapServerBean portion of the URI refers to a DirContext bean in the registry. The LDAP component only supports producer endpoints, which means that an ldap URI cannot appear in the from at the start of a route.

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

Options

Name

Default Value

Description

base

ou=system

The base DN for searches.

scope

subtree

Specifies how deeply to search the tree of entries, starting at the base DN. Value can be object, onelevel, or subtree.

pageSize

no paging used

Camel 2.6: When specified the ldap module uses paging to retrieve all results (most LDAP Servers throw an exception when trying to retrieve more than 1000 entries in one query). To be able to use this a LdapContext (subclass of DirContext) has to be passed in as ldapServerBean (otherwise an exception is thrown)

returnedAttributes

depends on LDAP Server (could be all or none)

Camel 2.6: Comma-se