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:

  • SimpleConsumer => see the Consuming a REST Request with the Simple Binding Style below.
  • Default => the default style. For consumers this passes on a MessageContentsList to the route, requiring low-level processing in the route.
  • Custom => allows you to specify a custom binding through the binding option.

bindingStyle=SimpleConsumer

No

Default

bindingAllows you to specify a custom CxfRsBinding implementation to perform low-level processing of the raw CXF request and response objects. The implementation must be bound in the Camel registry, and you must use the hash (#) notation to refer to it.binding=#myBindingNoDefaultCxfRsBinding

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

      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.

      readLockMarkerFile

      true

      Camel 2.14: Whether to use marker file with the changed, rename, or exclusive read lock types. By default a marker file is used as well to guard against other processes picking up the same files. This behavior can be turned off by setting this option to false. For example if you do not want to write marker files to the file systems by the Camel application.

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

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

      Hot reloading

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

      Dynamic templates

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

      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

       

      Options

      Name

      Required

      Description

      hazelcastInstanceNoSince Camel 2.14 The hazelcast instance reference name which can be used for hazelcast endpoint. If you don't specify the instance reference, camel use the default hazelcast instance from the camel-hazelcast instance.

       

       

      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

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

      false

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

      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

      CamelHL7Context
      -

      (Camel 2.14) contains the HapiContext that
      was used to parse the message

      All headers except CamelHL7Context 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. Better use the parser or hapiContext option and initialize it with the desired HAPI ValidationContext

      parser

      ca.uhn.hl7v2.parser.GenericParser

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

      hapiContextca.uhn.hl7v2.DefaultHapiContextCamel 2.14: Use a custom HAPI context that can define a custom parser, custom ValidationContext etc. This gives you full control over the HL7 parsing and rendering process.

      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

      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

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

      Sample:

      HL7 Validation predicate using the HapiContext (Camel 2.14)

      The HAPI Context is always configured with a ValidationContext (or a ValidationRuleBuilder), so you can access the validation rules indirectly. Furthermore, when unmarshalling the HL7DataFormat forwards the configured  HAPI context  in the CamelHL7Context header, and the validation rules of this context can be easily reused:

       

      HL7 Acknowledgement expression

      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.

      iBatis do not support Spring 4.x. So you can only use Spring 3.x or older with iBatis.

      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.

      Example with Blueprint XML

      In Blueprint 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. From Camel 2.14 onwards then SelectList is also supported.
      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. From Camel 2.14 onwards then SelectList is also supported.

      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.

      httpMethodRestrict

      null

      Camel 2.11: Consumer only: Used to only allow consuming if the HttpMethod matches, such as GET/POST/PUT etc.

      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

      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: