Apache Camel Component Reference

Chapter 1. Components Overview

This chapter provides a summary of all the components available for Apache Camel.

1.1. Container types

Red Hat Fuse provides a variety of container types, into which you can deploy your Camel applications:

Spring Boot
Apache Karaf
JBoss Enterprise Application Platform (JBoss EAP)

In addition, a Camel application can run as containerless: that is, where a Camel application runs directly in the JVM, without any special container.

In some cases, Fuse might support a Camel component in one container, but not in the others. There are various reasons for this, but in some cases a component is not suitable for all container types. For example, the camel-ejb component is designed spcifically for Java EE (that is, JBoss EAP), and cannot be supported in the other container types.

1.2. Supported components

Note the following key:

Symbol	Description
✔	Supported
❌	Unsupported or not yet supported
Deprecated	Likely to be removed in a future release

Table 1.1, “Apache Camel Component Support Matrix” provides comprehensive details about which Camel components are supported in which containers.

Table 1.1. Apache Camel Component Support Matrix
Component	Type	Containerless	Spring Boot	Karaf	JBoss EAP
`activemq-camel`	Endpoint	✔	✔	✔	✔
`camel-ahc`	Endpoint	✔	✔	✔	✔
`camel-ahc-ws`	Endpoint	✔	✔	✔	✔
`camel-ahc-wss`	Endpoint	✔	✔	✔	✔
`camel-amqp`	Endpoint	✔	✔	✔	✔
`camel-apns`	Endpoint	✔	✔	✔	✔
`camel-asn1`	Data Format	✔	✔	✔	✔
`camel-asterisk`	Endpoint	✔	✔	✔	✔
`camel-atmos`	Endpoint	✔	✔	❌	❌
`camel-atmosphere-websocket`	Endpoint	✔	✔	✔	✔
`camel-atom`	Endpoint	✔	✔	✔	✔
`camel-atomix`	Endpoint	✔	✔	✔	✔
`camel-avro`	Endpoint	✔	✔	✔	✔
`camel-avro`	Data Format	✔	✔	✔	✔
`camel-aws`	Endpoint	✔	✔	✔	✔
`camel-azure`	Endpoint	✔	✔	✔	✔
`camel-bam`	Endpoint	Deprecated	✔	✔	❌
`camel-barcode`	Data Format	✔	✔	✔	✔
`camel-base64`	Data Format	✔	✔	✔	✔
`camel-bean`	Endpoint	✔	✔	✔	✔
`camel-bean`	Language	✔	✔	✔	✔
`camel-bean-validator`	Endpoint	✔	✔	✔	✔
`camel-beanio`	Data Format	✔	✔	✔	✔
`camel-beanstalk`	Endpoint	✔	✔	✔	❌
`camel-binding`	Endpoint	Deprecated	✔	✔	✔
`camel-bindy`	Endpoint	✔	✔	✔	✔
`camel-bindy`	Data Format	✔	✔	✔	✔
`camel-blueprint`	Endpoint	✔	❌	✔	❌
`camel-bonita`	Endpoint	✔	❌	❌	❌
`camel-boon`	Data Format	✔	✔	✔	✔
`camel-box`	Endpoint	✔	✔	✔	✔
`camel-braintree`	Endpoint	✔	✔	✔	✔
`camel-browse`	Endpoint	✔	✔	✔	✔
`camel-cache`	Endpoint	Deprecated	✔	✔	❌
`camel-caffeine`	Endpoint	✔	✔	✔	✔
`camel-castor`	Data Format	Deprecated	✔	✔	✔
`camel-cdi`	Endpoint	✔	❌	Deprecated	✔
`camel-chronicle-engine`	Endpoint	✔	✔	✔	✔
`camel-chunk`	Endpoint	✔	✔	✔	✔
`camel-class`	Endpoint	✔	✔	✔	✔
`camel-cm-sms`	Endpoint	✔	✔	✔	✔
`camel-cmis`	Endpoint	✔	✔	✔	❌
`camel-coap`	Endpoint	✔	✔	✔	✔
`camel-cometd`	Endpoint	✔	✔	✔	✔
`camel-constant`	Language	✔	✔	✔	✔
`camel-context`	Endpoint	Deprecated	❌	❌	❌
`camel-consul`	Endpoint	✔	✔	✔	✔
`camel-controlbus`	Endpoint	✔	✔	✔	✔
`camel-couchbase`	Endpoint	✔	✔	✔	✔
`camel-couchdb`	Endpoint	✔	✔	✔	✔
`camel-cql`	Endpoint	✔	✔	✔	✔
`camel-crypto`	Endpoint	✔	✔	✔	✔
`camel-crypto`	Data Format	✔	✔	✔	✔
`camel-crypto-cms`	Endpoint	✔	✔	✔	✔
`camel-csv`	Data Format	✔	✔	✔	✔
`camel-cxf`	Endpoint	✔	✔	✔	✔
`camel-cxf-transport`	Endpoint	✔	✔	✔	✔
`camel-dataformat`	Endpoint	✔	✔	✔	✔
`camel-dataset`	Endpoint	✔	✔	✔	✔
`camel-digitalocean`	Endpoint	✔	✔	✔	✔
`camel-direct`	Endpoint	✔	✔	✔	✔
`camel-direct-vm`	Endpoint	✔	✔	✔	✔
`camel-disruptor`	Endpoint	✔	✔	✔	✔
`camel-dns`	Endpoint	✔	✔	✔	✔
`camel-docker`	Endpoint	✔	✔	✔	✔
`camel-dozer`	Endpoint	✔	✔	✔	✔
`camel-drill`	Endpoint	✔	✔	✔	❌
`camel-dropbox`	Endpoint	✔	✔	✔	✔
`camel-eclipse`		Deprecated	❌	❌	❌
`camel-ehcache`	Endpoint	✔	✔	✔	✔
`camel-ejb`	Endpoint	✔	❌	❌	✔
`camel-el`	Language	Deprecated	❌	❌	❌
`camel-elasticsearch`	Endpoint	✔	✔	✔	✔
`camel-elasticsearch5`	Endpoint	✔	✔	✔	✔
`camel-elasticsearch-rest`	Endpoint	✔	✔	✔	❌
`camel-elsql`	Endpoint	✔	✔	✔	✔
`camel-etcd`	Endpoint	✔	✔	✔	✔
`camel-eventadmin`	Endpoint	✔	❌	✔	❌
`camel-exchangeProperty`	Language	✔	✔	✔	✔
`camel-exec`	Endpoint	✔	✔	✔	✔
`camel-facebook`	Endpoint	✔	✔	✔	✔
`camel-fhir`	Data Format	✔	✔	✔	❌
`camel-file`	Endpoint	✔	✔	✔	✔
`camel-file`	Language	✔	✔	✔	✔
`camel-flatpack`	Endpoint	✔	✔	✔	✔
`camel-flatpack`	Data Format	✔	✔	✔	✔
`camel-flink`	Endpoint	✔	✔	❌	✔
`camel-fop`	Endpoint	✔	✔	✔	✔
`camel-freemarker`	Endpoint	✔	✔	✔	✔
`camel-ftp`	Endpoint	✔	✔	✔	✔
`camel-gae`	Endpoint	Deprecated	❌	❌	❌
`camel-ganglia`	Endpoint	✔	✔	✔	❌
`camel-geocoder`	Endpoint	✔	✔	✔	✔
`camel-git`	Endpoint	✔	✔	✔	✔
`camel-github`	Endpoint	✔	✔	✔	✔
`camel-google-bigquery`	Endpoint	✔	✔	❌	✔
`camel-google-calendar`	Endpoint	✔	✔	✔	✔
`camel-google-drive`	Endpoint	✔	✔	✔	✔
`camel-google-mail`	Endpoint	✔	✔	✔	✔
`camel-google-pubsub`	Endpoint	✔	✔	✔	✔
`camel-grape`	Endpoint	✔	✔	✔	❌
`camel-groovy`	Language	✔	✔	✔	✔
`camel-groovy-dsl`		Deprecated	❌	❌	❌
`camel-grpc`	Endpoint	✔	✔	✔	✔
`camel-guava-eventbus`	Endpoint	✔	✔	✔	✔
`camel-guice`	Endpoint	Deprecated	✔	❌	❌
`camel-gzip`	Data Format	✔	✔	✔	✔
`camel-hawtdb`	Endpoint	Deprecated	✔	✔	❌
`camel-hazelcast`	Endpoint	✔	✔	✔	✔
`camel-hbase`	Endpoint	✔	✔	❌	✔
`camel-hdfs`	Endpoint	Deprecated	✔	❌	❌
`camel-hdfs2`	Endpoint	✔	✔	✔	✔
`camel-header`	Language	✔	✔	✔	✔
`camel-headersmap`		✔	✔	✔	✔
`camel-hessian`	Data Format	Deprecated	✔	✔	✔
`camel-hipchat`	Endpoint	✔	✔	✔	✔
`camel-hl7`	Data Format	✔	✔	✔	✔
`camel-http`	Endpoint	Deprecated	✔	✔	❌
`camel-http4`	Endpoint	✔	✔	✔	✔
`camel-hystrix`	Endpoint	✔	✔	✔	✔
`camel-ibatis`	Endpoint	Deprecated	❌	❌	❌
`camel-ical`	Data Format	✔	✔	✔	✔
`camel-iec60870`	Endpoint	✔	✔	✔	✔
`camel-ignite`	Endpoint	❌	❌	❌	❌
`camel-imap`	Endpoint	✔	✔	✔	✔
`camel-infinispan`	Endpoint	❌	❌	❌	❌
`camel-influxdb`	Endpoint	✔	✔	✔	✔
`camel-irc`	Endpoint	✔	✔	✔	✔
`camel-ironmq`	Endpoint	❌	❌	❌	❌
`camel-jacksonxml`	Data Format	✔	✔	✔	✔
`camel-jasypt`	Endpoint	✔	✔	✔	✔
`camel-javaspace`	Endpoint	Deprecated	❌	❌	❌
`camel-jaxb`	Data Format	✔	✔	✔	✔
`camel-jbpm`	Endpoint	❌	❌	❌	❌
`camel-jcache`	Endpoint	✔	✔	✔	✔
`camel-jclouds`	Endpoint	✔	❌	✔	✔
`camel-jcr`	Endpoint	✔	✔	✔	✔
`camel-jdbc`	Endpoint	✔	✔	✔	✔
`camel-jetty`	Endpoint	Deprecated	Deprecated	Deprecated	❌
`camel-jetty8`	Endpoint	❌	❌	❌	❌
`camel-jetty9`	Endpoint	✔	✔	✔	❌
`camel-jgroups`	Endpoint	✔	✔	✔	✔
`camel-jibx`	Data Format	✔	✔	✔	✔
`camel-jing`	Endpoint	✔	✔	✔	✔
`camel-jira`	Endpoint	✔	❌	❌	❌
`camel-jms`	Endpoint	✔	✔	✔	✔
`camel-jmx`	Endpoint	✔	✔	✔	✔
`camel-jolt`	Endpoint	✔	✔	✔	✔
`camel-josql`	Endpoint	Deprecated	✔	✔	❌
`camel-jpa`	Endpoint	✔	✔	✔	✔
`camel-jsch`	Endpoint	✔	✔	✔	✔
`camel-json-fastjson`	Data Format	✔	✔	✔	✔
`camel-json-gson`	Data Format	✔	✔	✔	✔
`camel-json-jackson`	Data Format	✔	✔	✔	✔
`camel-json-johnzon`	Data Format	✔	✔	✔	✔
`camel-json-validator`	Endpoint	✔	✔	✔	❌
`camel-json-xstream`	Data Format	✔	✔	✔	✔
`camel-jsonpath`	Language	✔	✔	✔	✔
`camel-jt400`	Endpoint	✔	✔	✔	✔
`camel-juel`	Endpoint	Deprecated	✔	✔	❌
`camel-jxpath`	Language	Deprecated	❌	❌	❌
`camel-kafka`	Endpoint	✔	✔	✔	✔
`camel-kestrel`	Endpoint	Deprecated	✔	✔	❌
`camel-krati`	Endpoint	Deprecated	✔	✔	❌
`camel-kubernetes`	Endpoint	✔	✔	✔	✔
`camel-kura`		✔	❌	✔	❌
`camel-ldap`	Endpoint	✔	✔	✔	✔
`camel-ldif`	Endpoint	✔	✔	✔	❌
`camel-leveldb`	Endpoint	✔	✔	✔	✔
`camel-linkedin`	Endpoint	✔	✔	✔	✔
`camel-log`	Endpoint	✔	✔	✔	✔
`camel-lpr`	Endpoint	✔	✔	✔	✔
`camel-lra`		❌	❌	❌	❌
`camel-lucene`	Endpoint	✔	✔	✔	✔
`camel-lumberjack`	Endpoint	✔	✔	✔	✔
`camel-lzf`	Data Format	✔	✔	✔	✔
`camel-master`		✔	✔	✔	❌
`camel-mail`	Endpoint	✔	✔	✔	✔
`camel-metrics`	Endpoint	✔	✔	✔	✔
`camel-milo`	Endpoint	✔	✔	✔	✔
`camel-mime-multipart`	Data Format	✔	✔	✔	✔
`camel-mina`	Endpoint	Deprecated	❌	✔	❌
`camel-mina2`	Endpoint	✔	✔	✔	✔
`camel-mllp`	Endpoint	✔	✔	✔	✔
`camel-mock`	Endpoint	✔	✔	✔	✔
`camel-mongodb`	Endpoint	✔	✔	✔	✔
`camel-mongodb-gridfs`	Endpoint	✔	✔	✔	✔
`camel-mongodb3`	Endpoint	✔	✔	✔	✔
`camel-mqtt`	Endpoint	✔	✔	✔	✔
`camel-msv`	Endpoint	✔	✔	✔	✔
`camel-mustache`	Endpoint	✔	✔	✔	✔
`camel-mvel`	Endpoint	✔	✔	✔	✔
`camel-mvel`	Language	✔	✔	✔	✔
`camel-mybatis`	Endpoint	✔	✔	✔	✔
`camel-nagios`	Endpoint	✔	✔	✔	❌
`camel-nats`	Endpoint	✔	✔	✔	✔
`camel-netty`	Endpoint	Deprecated	✔	✔	❌
`camel-netty-http`	Endpoint	Deprecated	✔	✔	❌
`camel-netty4`	Endpoint	✔	✔	✔	✔
`camel-netty4-http`	Endpoint	✔	✔	✔	❌
`camel-ognl`	Language	✔	✔	✔	✔
`camel-olingo2`	Endpoint	✔	✔	✔	✔
`camel-olingo4`	Endpoint	✔	✔	✔	✔
`camel-openshift`	Endpoint	Deprecated	✔	✔	❌
`camel-openstack`	Endpoint	✔	✔	✔	✔
`camel-opentracing`		✔	✔	✔	✔
`camel-optaplanner`	Endpoint	✔	✔	✔	✔
`camel-paho`	Endpoint	✔	✔	✔	✔
`camel-paxlogging`	Endpoint	✔	❌	✔	❌
`camel-pdf`	Endpoint	✔	✔	✔	✔
`camel-pgevent`	Endpoint	✔	✔	✔	❌
`camel-pgp`	Data Format	✔	✔	✔	✔
`camel-php`	Language	Deprecated	❌	❌	✔
`camel-pop3`	Endpoint	✔	✔	✔	✔
`camel-printer`	Endpoint	✔	✔	✔	✔
`camel-properties`	Endpoint	✔	✔	✔	✔
`camel-protobuf`	Data Format	✔	✔	✔	✔
`camel-pubnub`	Endpoint	✔	✔	✔	✔
`camel-python`	Language	Deprecated	❌	❌	❌
`camel-quartz`	Endpoint	Deprecated	✔	✔	❌
`camel-quartz2`	Endpoint	✔	✔	✔	✔
`camel-quickfix`	Endpoint	✔	✔	✔	✔
`camel-rabbitmq`	Endpoint	✔	✔	✔	✔
`camel-reactive-streams`	Endpoint	✔	✔	✔	✔
`camel-reactor`		✔	✔	✔	✔
`camel-ref`	Endpoint	✔	✔	✔	✔
`camel-ref`	Language	✔	✔	✔	✔
`camel-rest`	Endpoint	✔	✔	✔	✔
`camel-rest-api`	Endpoint	✔	✔	✔	✔
`camel-rest-swagger`	Endpoint	✔	✔	✔	✔
`camel-restlet`	Endpoint	✔	✔	✔	❌
`camel-ribbon`		✔	✔	❌	✔
`camel-rmi`	Endpoint	✔	✔	✔	✔
`camel-routebox`	Endpoint	Deprecated	✔	✔	❌
`camel-rss`	Endpoint	✔	✔	✔	✔
`camel-rss`	Data Format	✔	✔	✔	✔
`camel-ruby`	Language	Deprecated	❌	❌	❌
`camel-rx`	Endpoint	Deprecated	✔	✔	❌
`camel-saga`	Endpoint	❌	❌	❌	❌
`camel-salesforce`	Endpoint	✔	✔	✔	✔
`camel-sap`	Endpoint	✔	✔	✔	✔
`camel-sap-netweaver`	Endpoint	✔	✔	✔	✔
`camel-saxon`	Endpoint	✔	✔	✔	✔
`camel-scala`	Endpoint	Deprecated	✔	✔	❌
`camel-scheduler`	Endpoint	✔	✔	✔	✔
`camel-schematron`	Endpoint	✔	✔	✔	✔
`camel-scp`	Endpoint	✔	✔	✔	✔
`camel-scr`	Endpoint	Deprecated	✔	Deprecated	❌
`camel-script`	Endpoint	✔	✔	✔	✔
`camel-seda`	Endpoint	✔	✔	✔	✔
`camel-serialization`	Data Format	✔	✔	✔	✔
`camel-servicenow`	Endpoint	✔	✔	✔	✔
`camel-servlet`	Endpoint	✔	✔	✔	✔
`camel-servletlistener`	Endpoint	Deprecated	✔	✔	❌
`camel-sftp`	Endpoint	✔	✔	✔	✔
`camel-shiro`	Endpoint	✔	✔	✔	✔
`camel-simple`	Language	✔	✔	✔	✔
`camel-sip`	Endpoint	✔	✔	✔	✔
`camel-sjms`	Endpoint	✔	✔	✔	✔
`camel-sjms2`	Endpoint	✔	✔	✔	✔
`camel-slack`	Endpoint	✔	✔	✔	✔
`camel-smpp`	Endpoint	✔	✔	✔	✔
`camel-snakeyaml`	Endpoint	✔	✔	✔	✔
`camel-snmp`	Endpoint	✔	✔	✔	✔
`camel-soapjaxb`	Data Format	✔	✔	✔	✔
`camel-solr`	Endpoint	✔	✔	✔	❌
`camel-spark`	Endpoint	✔	✔	❌	❌
`camel-spark-rest`	Endpoint	✔	✔	❌	❌
`camel-spel`	Language	✔	✔	❌	✔
`camel-splunk`	Endpoint	✔	✔	✔	✔
`camel-spring`	Endpoint	✔	✔	✔	✔
`camel-spring-batch`	Endpoint	✔	✔	✔	✔
`camel-spring-boot`	Endpoint	✔	✔	❌	❌
`camel-spring-cloud`		✔	✔	❌	❌
`camel-spring-cloud-netflix`		✔	✔	❌	❌
`camel-spring-event`	Endpoint	✔	✔	❌	✔
`camel-spring-integration`	Endpoint	✔	❌	❌	✔
`camel-spring-javaconfig`	Endpoint	✔	✔	❌	✔
`camel-spring-ldap`	Endpoint	✔	✔	✔	✔
`camel-spring-redis`	Endpoint	✔	✔	✔	✔
`camel-spring-security`	Endpoint	✔	✔	✔	✔
`camel-spring-ws`	Endpoint	✔	✔	✔	✔
`camel-sql`	Endpoint	✔	✔	✔	✔
`camel-sql-stored`	Endpoint	✔	✔	✔	✔
`camel-ssh`	Endpoint	✔	✔	✔	✔
`camel-stax`	Endpoint	✔	✔	✔	✔
`camel-stomp`	Endpoint	✔	✔	✔	✔
`camel-stream`	Endpoint	✔	✔	✔	✔
`camel-string`	Data Format	✔	✔	✔	✔
`camel-string-template`	Endpoint	✔	✔	✔	✔
`camel-stub`	Endpoint	✔	✔	✔	✔
`camel-swagger`	Endpoint	Deprecated	✔	Deprecated	❌
`camel-swagger-java`	Endpoint	✔	✔	✔	✔
`camel-syslog`	Data Format	✔	✔	✔	✔
`camel-tagsoup`	Endpoint	✔	✔	✔	✔
`camel-tarfile`	Data Format	✔	✔	✔	✔
`camel-telegram`	Endpoint	✔	✔	✔	✔
`camel-thrift`	Endpoint	✔	✔	✔	✔
`camel-thrift`	Data Format	✔	✔	✔	✔
`camel-tika`	Endpoint	✔	✔	✔	❌
`camel-timer`	Endpoint	✔	✔	✔	✔
`camel-tokenize`	Language	✔	✔	✔	✔
`camel-twilio`	Endpoint	✔	✔	✔	✔
`camel-twitter`	Endpoint	✔	✔	✔	✔
`camel-undertow`	Endpoint	✔	✔	✔	✔
`camel-univocity-csv`	Data Format	✔	✔	✔	✔
`camel-univocity-fixed`	Data Format	✔	✔	✔	✔
`camel-univocity-tsv`	Data Format	✔	✔	✔	✔
`camel-urlrewrite`	Endpoint	Deprecated	✔	✔	❌
`camel-validator`	Endpoint	✔	✔	✔	✔
`camel-velocity`	Endpoint	✔	✔	✔	✔
`camel-vertx`	Endpoint	✔	✔	✔	✔
`camel-vm`	Endpoint	✔	✔	✔	✔
`camel-weather`	Endpoint	✔	✔	✔	✔
`camel-websocket`	Endpoint	✔	✔	✔	❌
`camel-wordpress`	Endpoint	✔	✔	✔	❌
`camel-xchange`	Endpoint	✔	✔	✔	❌
`camel-xmlbeans`	Data Format	Deprecated	Deprecated	Deprecated	✔
`camel-xmljson`	Data Format	✔	✔	✔	✔
`camel-xmlrpc`	Endpoint	❌	❌	❌	❌
`camel-xmlrpc`	Data Format	❌	❌	❌	❌
`camel-xmlsecurity`	Endpoint	✔	✔	✔	✔
`camel-xmpp`	Endpoint	✔	✔	✔	✔
`camel-xpath`	Language	✔	✔	✔	✔
`camel-xquery`	Endpoint	✔	✔	✔	✔
`camel-xquery`	Language	✔	✔	✔	✔
`camel-xslt`	Endpoint	✔	✔	✔	✔
`camel-xstream`	Data Format	✔	✔	✔	✔
`camel-xtokenize`	Language	✔	✔	✔	✔
`camel-yaml-snakeyaml`	Data Format	✔	✔	✔	✔
`camel-yammer`	Endpoint	✔	✔	✔	✔
`camel-yql`	Endpoint	✔	✔	✔	❌
`camel-zendesk`	Endpoint	✔	✔	❌	✔
`camel-zip`	Data Format	✔	✔	✔	✔
`camel-zipfile`	Data Format	✔	✔	✔	✔
`camel-zipkin`	Endpoint	✔	✔	✔	✔
`camel-zookeeper`	Endpoint	✔	✔	✔	✔
`camel-zookeeper-master`	Endpoint	✔	✔	✔	✔

Chapter 2. ActiveMQ

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 the Chapter 165, 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 Chapter 165, JMS Component component also apply for this component.

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

Transacted and caching

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

URI format

activemq:[queue:|topic:]destinationName

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:

activemq:FOO.BAR

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

activemq:queue:FOO.BAR

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

activemq:topic:Stocks.Prices

Options

See Options on the Chapter 165, JMS Component component as all these options also apply for this component.

Camel on EAP deployment

This component is supported by the Camel on EAP (Wildfly Camel) framework, which offers a simplified deployment model on the Red Hat JBoss Enterprise Application Platform (JBoss EAP) container.

You can configure the ActiveMQ Camel component to work either with an embedded broker or an external broker. To embed a broker in the JBoss EAP container, configure the ActiveMQ Resource Adapter in the EAP container configuration file — for details, see ActiveMQ Resource Adapter Configuration.

Configuring the Connection Factory

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

camelContext.addComponent("activemq", activeMQComponent("vm://localhost?broker.persistent=false"));

Configuring the Connection Factory using Spring XML

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

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
       http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">

  <camelContext xmlns="http://camel.apache.org/schema/spring">
  </camelContext>

  <bean id="activemq" class="org.apache.activemq.camel.component.ActiveMQComponent">
    <property name="brokerURL" value="tcp://somehost:61616"/>
  </bean>

</beans>

Using connection pooling

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

You can grab Jencks AMQ pool with Maven:

    <dependency>
      <groupId>org.apache.activemq</groupId>
      <artifactId>activemq-pool</artifactId>
      <version>5.3.2</version>
    </dependency>

And then setup the activemq component as follows:

    <bean id="jmsConnectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL" value="tcp://localhost:61616" />
    </bean>

    <bean id="pooledConnectionFactory"    class="org.apache.activemq.pool.PooledConnectionFactory" init-method="start" destroy-method="stop">
        <property name="maxConnections" value="8" />
        <property name="connectionFactory" ref="jmsConnectionFactory" />
    </bean>

    <bean id="jmsConfig" class="org.apache.camel.component.jms.JmsConfiguration">
        <property name="connectionFactory" ref="pooledConnectionFactory"/>
        <property name="concurrentConsumers" value="10"/>
    </bean>

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

Note

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

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 maxActive 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 maxActiveSessionPerConnection. 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 route

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

So for example you can create a MessageListener in JMS as follows:

public class MyListener implements MessageListener {
   public void onMessage(Message jmsMessage) {
       // ...
   }
}

Then use it in your route as follows

from("file://foo/bar").
  bean(MyListener.class);

That is, you can reuse any of the Apache 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:

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="file://src/test/data?noop=true"/>
    <to uri="activemq:queue:foo"/>
  </route>
  <route>
    <!-- use consumer.exclusive ActiveMQ destination option, notice we have to prefix with destination. -->
    <from uri="activemq:foo?destination.consumer.exclusive=true&amp;destination.consumer.prefetchSize=50"/>
    <to uri="mock:results"/>
  </route>
</camelContext>

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.

<route>
	<from uri="activemq:topic:ActiveMQ.Advisory.Connection?mapJmsMessage=false" />
	<convertBodyTo type="java.lang.String"/>
	<transform>
	     <simple>${in.body}&#13;</simple>
	</transform>
	<to uri="file://data/activemq/?fileExist=Append&ileName=advisoryConnection-${date:now:yyyyMMdd}.txt" />
</route>

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

advisoryConnection-20100312.txt advisoryProducer-20100312.txt

and containing string:

      ActiveMQMessage {commandId = 0, responseRequired = false, messageId = ID:dell-charles-3258-1268399815140
      -1:0:0:0:221, originalDestination = null, originalTransactionId = null, producerId = ID:dell-charles-
      3258-1268399815140-1:0:0:0, destination = topic://ActiveMQ.Advisory.Connection, transactionId = null,
      expiration = 0, timestamp = 0, arrival = 0, brokerInTime = 1268403383468, brokerOutTime = 1268403383468,
      correlationId = null, replyTo = null, persistent = false, type = Advisory, priority = 0, groupID = null,
      groupSequence = 0, targetConsumerId = null, compressed = false, userID = null, content = null,
      marshalledProperties = org.apache.activemq.util.ByteSequence@17e2705, dataStructure = ConnectionInfo
      {commandId = 1, responseRequired = true, connectionId = ID:dell-charles-3258-1268399815140-2:50,
      clientId = ID:dell-charles-3258-1268399815140-14:0, userName = , password = *****,
      brokerPath = null, brokerMasterConnector = false, manageable = true, clientMaster = true},
      redeliveryCounter = 0, size = 0, properties = {originBrokerName=master, originBrokerId=ID:dell-charles-
      3258-1268399815140-0:0, originBrokerURL=vm://master}, readOnlyProperties = true, readOnlyBody = true,
      droppable = false}

Getting Component JAR

You need this dependency:

activemq-camel

ActiveMQ is an extension of the Chapter 165, JMS Component component released with the ActiveMQ project.

<dependency>
  <groupId>org.apache.activemq</groupId>
  <artifactId>activemq-camel</artifactId>
  <version>5.6.0</version>
</dependency>

Chapter 3. AHC Component

Available as of Camel version 2.8

The ahc: component provides HTTP based endpoints for consuming external HTTP resources (as a client to call external servers using HTTP).
The component uses the Async Http Client library.

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

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

3.1. URI format

ahc:http://hostname[:port][/resourceUri][?options]
ahc:https://hostname[:port][/resourceUri][?options]

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

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

3.2. AhcEndpoint Options

The AHC endpoint is configured using URI syntax:

ahc:httpUri

with the following path and query parameters:

3.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
httpUri	Required The URI to use such as http://hostname:port/path		URI

3.2.2. Query Parameters (13 parameters):

Name	Description	Default	Type
bridgeEndpoint (producer)	If the option is true, then the Exchange.HTTP_URI header is ignored, and use the endpoint’s URI for request. You may also set the throwExceptionOnFailure to be false to let the AhcProducer send all the fault response back.	false	boolean
bufferSize (producer)	The initial in-memory buffer size used when transferring data between Camel and AHC Client.	4096	int
connectionClose (producer)	Define if the Connection Close header has to be added to HTTP Request. This parameter is false by default	false	boolean
cookieHandler (producer)	Configure a cookie handler to maintain a HTTP session		CookieHandler
headerFilterStrategy (producer)	To use a custom HeaderFilterStrategy to filter header to and from Camel message.		HeaderFilterStrategy
throwExceptionOnFailure (producer)	Option to disable throwing the AhcOperationFailedException in case of failed responses from the remote server. This allows you to get all responses regardless of the HTTP status code.	true	boolean
transferException (producer)	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 AhcOperationFailedException. The caused exception is required to be serialized. This is by default turned off. If you enable this then be aware that Java will deserialize the incoming data from the request to Java and that can be a potential security risk.	false	boolean
binding (advanced)	To use a custom AhcBinding which allows to control how to bind between AHC and Camel.		AhcBinding
clientConfig (advanced)	To configure the AsyncHttpClient to use a custom com.ning.http.client.AsyncHttpClientConfig instance.		AsyncHttpClientConfig
clientConfigOptions (advanced)	To configure the AsyncHttpClientConfig using the key/values from the Map.		Map
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
clientConfigRealmOptions (security)	To configure the AsyncHttpClientConfig Realm using the key/values from the Map.		Map
sslContextParameters (security)	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 configuring this option will override any SSL/TLS configuration options provided through the clientConfig option at the endpoint or component level.		SSLContextParameters

3.3. AhcComponent Options

The AHC component supports 8 options which are listed below.

Name	Description	Default	Type
client (advanced)	To use a custom AsyncHttpClient		AsyncHttpClient
binding (advanced)	To use a custom AhcBinding which allows to control how to bind between AHC and Camel.		AhcBinding
clientConfig (advanced)	To configure the AsyncHttpClient to use a custom com.ning.http.client.AsyncHttpClientConfig instance.		AsyncHttpClientConfig
sslContextParameters (security)	Reference to a org.apache.camel.util.jsse.SSLContextParameters in the Registry. Note that configuring this option will override any SSL/TLS configuration options provided through the clientConfig option at the endpoint or component level.		SSLContextParameters
allowJavaSerialized Object (advanced)	Whether to allow java serialization when a request uses context-type=application/x-java-serialized-object This is by default turned off. If you enable this then be aware that Java will deserialize the incoming data from the request to Java and that can be a potential security risk.	false	boolean
useGlobalSslContext Parameters (security)	Enable usage of global SSL context parameters.	false	boolean
headerFilterStrategy (filter)	To use a custom org.apache.camel.spi.HeaderFilterStrategy to filter header to and from Camel message.		HeaderFilterStrategy
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

Notice that setting any of the options on the AhcComponent will propagate those options to AhcEndpoints being created. However the AhcEndpoint can also configure/override a custom option. Options set on endpoints will always take precedence over options from the AhcComponent.

3.4. Message Headers

Name	Type	Description
`Exchange.HTTP_URI`	`String`	URI to call. Will override existing URI set directly on the endpoint.
`Exchange.HTTP_PATH`	`String`	Request URI’s path, the header will be used to build the request URI with the HTTP_URI. 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`	Camel 2.11 onwards: 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`.

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

3.6. 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 AhcOperationFailedException with the information.
Response code is 400+, Camel regards it as an external server failure and will throw a AhcOperationFailedException with the information.
throwExceptionOnFailure
The option, throwExceptionOnFailure, can be set to false to prevent the AhcOperationFailedException from being thrown for failed response codes. This allows you to get any response from the remote server.

3.7. AhcOperationFailedException

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

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

3.9. Configuring URI to call

You can set the HTTP producer’s URI directly form the endpoint URI. In the route below, Camel will call out to the external server, oldhost, using HTTP.

from("direct:start")
        .to("ahc:http://oldhost");

And the equivalent Spring sample:

<camelContext xmlns="http://activemq.apache.org/camel/schema/spring">
  <route>
    <from uri="direct:start"/>
    <to uri="ahc:http://oldhost"/>
  </route>
</camelContext>

You can override the HTTP endpoint URI by adding a header with the key, Exchange.HTTP_URI, on the message.

from("direct:start")
    .setHeader(Exchange.HTTP_URI, constant("http://newhost"))
    .to("ahc:http://oldhost");

3.10. Configuring URI Parameters

The ahc producer supports URI parameters to be sent to the HTTP server. The URI parameters can either be set directly on the endpoint URI or as a header with the key Exchange.HTTP_QUERY on the message.

from("direct:start")
        .to("ahc:http://oldhost?order=123&detail=short");

Or options provided in a header:

from("direct:start")
            .setHeader(Exchange.HTTP_QUERY, constant("order=123&detail=short"))
        .to("ahc:http://oldhost");

3.11. How to set the http method to the HTTP producer

The HTTP component provides a way to set the HTTP request method by setting the message header. Here is an example;

from("direct:start")
            .setHeader(Exchange.HTTP_METHOD, constant("POST"))
        .to("ahc:http://www.google.com")
            .to("mock:results");

And the equivalent Spring sample:

<camelContext xmlns="http://activemq.apache.org/camel/schema/spring">
  <route>
    <from uri="direct:start"/>
    <setHeader headerName="CamelHttpMethod">
        <constant>POST</constant>
    </setHeader>
    <to uri="ahc:http://www.google.com"/>
    <to uri="mock:results"/>
  </route>
</camelContext>

3.12. Configuring charset

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

exchange.setProperty(Exchange.CHARSET_NAME, "iso-8859-1");

3.12.1. URI Parameters from the endpoint URI

In this sample we have the complete URI endpoint that is just what you would have typed in a web browser. Multiple URI parameters can of course be set using the & character as separator, just as you would in the web browser. Camel does no tricks here.

// we query for Camel at the Google page
template.sendBody("ahc:http://www.google.com/search?q=Camel", null);

3.12.2. URI Parameters from the Message

Map headers = new HashMap();
headers.put(Exchange.HTTP_QUERY, "q=Camel&lr=lang_en");
// we query for Camel and English language at Google
template.sendBody("ahc:http://www.google.com/search", null, headers);

In the header value above notice that it should not be prefixed with ? and you can separate parameters as usual with the & char.

3.12.3. Getting the Response Code

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

Exchange exchange = template.send("ahc:http://www.google.com/search", new Processor() {
            public void process(Exchange exchange) throws Exception {
                exchange.getIn().setHeader(Exchange.HTTP_QUERY, constant("hl=en&q=activemq"));
            }
   });
   Message out = exchange.getOut();
   int responseCode = out.getHeader(Exchange.HTTP_RESPONSE_CODE, Integer.class);

3.13. Configuring AsyncHttpClient

The AsyncHttpClient client uses a AsyncHttpClientConfig to configure the client. See the documentation at
Async Http Client for more details.

In Camel 2.8, configuration is limited to using the builder pattern provided by AsyncHttpClientConfig.Builder. In Camel 2.8, the AsyncHttpClientConfig doesn’t support getters/setters so its not easy to create/configure using a Spring bean style (eg the <bean> tag in the XML file).

The example below shows how to use a builder to create the AsyncHttpClientConfig which we configure on the AhcComponent.

In Camel 2.9, the AHC component uses Async HTTP library 1.6.4. This newer version provides added support for plain bean style configuration. The AsyncHttpClientConfigBean class provides getters and setters for the configuration options available in AsyncHttpClientConfig. An instance of AsyncHttpClientConfigBean may be passed directly to the AHC component or referenced in an endpoint URI using the clientConfig URI parameter.

Also available in Camel 2.9 is the ability to set configuration options directly in the URI. URI parameters starting with "clientConfig." can be used to set the various configurable properties of AsyncHttpClientConfig. The properties specified in the endpoint URI are merged with those specified in the configuration referenced by the "clientConfig" URI parameter with those being set using the "clientConfig." parameter taking priority. The AsyncHttpClientConfig instance referenced is always copied for each endpoint such that settings on one endpoint will remain independent of settings on any previously created endpoints. The example below shows how to configure the AHC component using the "clientConfig." type URI parameters.

from("direct:start")
    .to("ahc:http://localhost:8080/foo?clientConfig.maxRequestRetry=3&clientConfig.followRedirects=true")

3.14. SSL Support (HTTPS)

Using the JSSE Configuration Utility

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

Programmatic configuration of the component

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

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

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

AhcComponent component = context.getComponent("ahc", AhcComponent.class);
component.setSslContextParameters(scp));

Spring DSL based configuration of endpoint

...
  <camel:sslContextParameters
      id="sslContextParameters">
    <camel:keyManagers
        keyPassword="keyPassword">
      <camel:keyStore
          resource="/users/home/server/keystore.jks"
          password="keystorePassword"/>
    </camel:keyManagers>
  </camel:sslContextParameters>...
...
  <to uri="ahc:https://localhost/foo?sslContextParameters=#sslContextParameters"/>
...

3.15. See Also

Configuring Camel
Component
Endpoint
Getting Started
Jetty
HTTP
HTTP4

Chapter 4. AHC Websocket Component

Available as of Camel version 2.14

The ahc-ws component provides Websocket based endpoints for a client communicating with external servers over Websocket (as a client opening a websocket connection to an external server).
The component uses the AHC component that in turn uses the https://github.com/AsyncHttpClient/async-http-client[Async Http Client] library.

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

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

4.1. URI Format

ahc-ws://hostname[:port][/resourceUri][?options]
ahc-wss://hostname[:port][/resourceUri][?options]

Will by default use port 80 for ahc-ws and 443 for ahc-wss.

4.2. AHC-WS Options

As the AHC-WS component is based on the AHC component, you can use the various configuration options of the AHC component.

The AHC Websocket component supports 8 options which are listed below.

Name	Description	Default	Type
client (advanced)	To use a custom AsyncHttpClient		AsyncHttpClient
binding (advanced)	To use a custom AhcBinding which allows to control how to bind between AHC and Camel.		AhcBinding
clientConfig (advanced)	To configure the AsyncHttpClient to use a custom com.ning.http.client.AsyncHttpClientConfig instance.		AsyncHttpClientConfig
sslContextParameters (security)	Reference to a org.apache.camel.util.jsse.SSLContextParameters in the Registry. Note that configuring this option will override any SSL/TLS configuration options provided through the clientConfig option at the endpoint or component level.		SSLContextParameters
allowJavaSerialized Object (advanced)	Whether to allow java serialization when a request uses context-type=application/x-java-serialized-object This is by default turned off. If you enable this then be aware that Java will deserialize the incoming data from the request to Java and that can be a potential security risk.	false	boolean
useGlobalSslContext Parameters (security)	Enable usage of global SSL context parameters.	false	boolean
headerFilterStrategy (filter)	To use a custom org.apache.camel.spi.HeaderFilterStrategy to filter header to and from Camel message.		HeaderFilterStrategy
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AHC Websocket endpoint is configured using URI syntax:

ahc-ws:httpUri

with the following path and query parameters:

4.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
httpUri	Required The URI to use such as http://hostname:port/path		URI

4.2.2. Query Parameters (18 parameters):

Name	Description	Default	Type
bridgeEndpoint (common)	If the option is true, then the Exchange.HTTP_URI header is ignored, and use the endpoint’s URI for request. You may also set the throwExceptionOnFailure to be false to let the AhcProducer send all the fault response back.	false	boolean
bufferSize (common)	The initial in-memory buffer size used when transferring data between Camel and AHC Client.	4096	int
headerFilterStrategy (common)	To use a custom HeaderFilterStrategy to filter header to and from Camel message.		HeaderFilterStrategy
throwExceptionOnFailure (common)	Option to disable throwing the AhcOperationFailedException in case of failed responses from the remote server. This allows you to get all responses regardless of the HTTP status code.	true	boolean
transferException (common)	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 AhcOperationFailedException. The caused exception is required to be serialized. This is by default turned off. If you enable this then be aware that Java will deserialize the incoming data from the request to Java and that can be a potential security risk.	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
sendMessageOnError (consumer)	Whether to send an message if the web-socket listener received an error.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
connectionClose (producer)	Define if the Connection Close header has to be added to HTTP Request. This parameter is false by default	false	boolean
cookieHandler (producer)	Configure a cookie handler to maintain a HTTP session		CookieHandler
useStreaming (producer)	To enable streaming to send data as multiple text fragments.	false	boolean
binding (advanced)	To use a custom AhcBinding which allows to control how to bind between AHC and Camel.		AhcBinding
clientConfig (advanced)	To configure the AsyncHttpClient to use a custom com.ning.http.client.AsyncHttpClientConfig instance.		AsyncHttpClientConfig
clientConfigOptions (advanced)	To configure the AsyncHttpClientConfig using the key/values from the Map.		Map
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
clientConfigRealmOptions (security)	To configure the AsyncHttpClientConfig Realm using the key/values from the Map.		Map
sslContextParameters (security)	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 configuring this option will override any SSL/TLS configuration options provided through the clientConfig option at the endpoint or component level.		SSLContextParameters

4.3. Writing and Reading Data over Websocket

An ahc-ws endpoint can either write data to the socket or read from the socket, depending on whether the endpoint is configured as the producer or the consumer, respectively.

4.4. Configuring URI to Write or Read Data

In the route below, Camel will write to the specified websocket connection.

from("direct:start")
        .to("ahc-ws://targethost");

And the equivalent Spring sample:

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <to uri="ahc-ws://targethost"/>
  </route>
</camelContext>

In the route below, Camel will read from the specified websocket connection.

from("ahc-ws://targethost")
        .to("direct:next");

And the equivalent Spring sample:

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="ahc-ws://targethost"/>
    <to uri="direct:next"/>
  </route>
</camelContext>

4.5. See Also

Configuring Camel
Component
Endpoint
Getting Started
AHC
Atmosphere-Websocket

Chapter 5. AMQP Component

Available as of Camel version 1.2

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

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

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

5.1. URI format

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

5.2. AMQP Options

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

The AMQP component supports 80 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	To use a shared JMS configuration		JmsConfiguration
acceptMessagesWhile Stopping (consumer)	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 enqueued 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.	false	boolean
allowReplyManagerQuick Stop (consumer)	Whether the DefaultMessageListenerContainer used in the reply managers for request-reply messaging allow the DefaultMessageListenerContainer.runningAllowed flag to quick stop in case JmsConfigurationisAcceptMessagesWhileStopping is enabled, and org.apache.camel.CamelContext is currently being stopped. This quick stop ability is enabled by default in the regular JMS consumers but to enable for reply managers you must enable this flag.	false	boolean
acknowledgementMode (consumer)	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.		int
eagerLoadingOf Properties (consumer)	Enables eager loading of JMS properties as soon as a message is loaded which generally is inefficient as the JMS properties may not be required but sometimes can catch early any issues with the underlying JMS provider and the use of JMS properties	false	boolean
acknowledgementModeName (consumer)	The JMS acknowledgement name, which is one of: SESSION_TRANSACTED, CLIENT_ACKNOWLEDGE, AUTO_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE	AUTO_ ACKNOWLEDGE	String
autoStartup (consumer)	Specifies whether the consumer container should auto-startup.	true	boolean
cacheLevel (consumer)	Sets the cache level by ID for the underlying JMS resources. See cacheLevelName option for more details.		int
cacheLevelName (consumer)	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 is CACHE_AUTO. See the Spring documentation and Transactions Cache Levels for more information.	CACHE_AUTO	String
replyToCacheLevelName (producer)	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.		String
clientId (common)	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. If using Apache ActiveMQ you may prefer to use Virtual Topics instead.		String
concurrentConsumers (consumer)	Specifies the default number of concurrent consumers when consuming from JMS (not for request/reply over JMS). See also the maxMessagesPerTask option to control dynamic scaling up/down of threads. When doing request/reply over JMS then the option replyToConcurrentConsumers is used to control number of concurrent consumers on the reply message listener.	1	int
replyToConcurrent Consumers (producer)	Specifies the default number of concurrent consumers when doing request/reply over JMS. See also the maxMessagesPerTask option to control dynamic scaling up/down of threads.	1	int
connectionFactory (common)	The connection factory to be use. A connection factory must be configured either on the component or endpoint.		ConnectionFactory
username (security)	Username to use with the ConnectionFactory. You can also configure username/password directly on the ConnectionFactory.		String
password (security)	Password to use with the ConnectionFactory. You can also configure username/password directly on the ConnectionFactory.		String
deliveryPersistent (producer)	Specifies whether persistent delivery is used by default.	true	boolean
deliveryMode (producer)	Specifies the delivery mode to be used. Possibles values are those defined by javax.jms.DeliveryMode. NON_PERSISTENT = 1 and PERSISTENT = 2.		Integer
durableSubscriptionName (common)	The durable subscriber name for specifying durable topic subscriptions. The clientId option must be configured as well.		String
exceptionListener (advanced)	Specifies the JMS Exception Listener that is to be notified of any underlying JMS exceptions.		ExceptionListener
errorHandler (advanced)	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. You can configure logging level and whether stack traces should be logged using errorHandlerLoggingLevel and errorHandlerLogStackTrace options. This makes it much easier to configure, than having to code a custom errorHandler.		ErrorHandler
errorHandlerLogging Level (logging)	Allows to configure the default errorHandler logging level for logging uncaught exceptions.	WARN	LoggingLevel
errorHandlerLogStack Trace (logging)	Allows to control whether stacktraces should be logged or not, by the default errorHandler.	true	boolean
explicitQosEnabled (producer)	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.	false	boolean
exposeListenerSession (consumer)	Specifies whether the listener session should be exposed when consuming messages.	false	boolean
idleTaskExecutionLimit (advanced)	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.	1	int
idleConsumerLimit (advanced)	Specify the limit for the number of consumers that are allowed to be idle at any given time.	1	int
maxConcurrentConsumers (consumer)	Specifies the maximum number of concurrent consumers when consuming from JMS (not for request/reply over JMS). See also the maxMessagesPerTask option to control dynamic scaling up/down of threads. When doing request/reply over JMS then the option replyToMaxConcurrentConsumers is used to control number of concurrent consumers on the reply message listener.		int
replyToMaxConcurrent Consumers (producer)	Specifies the maximum number of concurrent consumers when using request/reply over JMS. See also the maxMessagesPerTask option to control dynamic scaling up/down of threads.		int
replyOnTimeoutToMax ConcurrentConsumers (producer)	Specifies the maximum number of concurrent consumers for continue routing when timeout occurred when using request/reply over JMS.	1	int
maxMessagesPerTask (advanced)	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.	-1	int
messageConverter (advanced)	To use a custom Spring org.springframework.jms.support.converter.MessageConverter so you can be in control how to map to/from a javax.jms.Message.		MessageConverter
mapJmsMessage (advanced)	Specifies whether Camel should auto map the received JMS message to a suited payload type, such as javax.jms.TextMessage to a String etc.	true	boolean
messageIdEnabled (advanced)	When sending, specifies whether message IDs should be added. This is just an hint to the JMS broker.If the JMS provider accepts this hint, these messages must have the message ID set to null; if the provider ignores the hint, the message ID must be set to its normal unique value	true	boolean
messageTimestampEnabled (advanced)	Specifies whether timestamps should be enabled by default on sending messages. This is just an hint to the JMS broker.If the JMS provider accepts this hint, these messages must have the timestamp set to zero; if the provider ignores the hint the timestamp must be set to its normal value	true	boolean
alwaysCopyMessage (producer)	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)	false	boolean
useMessageIDAs CorrelationID (advanced)	Specifies whether JMSMessageID should always be used as JMSCorrelationID for InOut messages.	false	boolean
priority (producer)	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.	4	int
pubSubNoLocal (advanced)	Specifies whether to inhibit the delivery of messages published by its own connection.	false	boolean
receiveTimeout (advanced)	The timeout for receiving messages (in milliseconds).	1000	long
recoveryInterval (advanced)	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.	5000	long
taskExecutor (consumer)	Allows you to specify a custom task executor for consuming messages.		TaskExecutor
timeToLive (producer)	When sending messages, specifies the time-to-live of the message (in milliseconds).	-1	long
transacted (transaction)	Specifies whether to use transacted mode	false	boolean
lazyCreateTransaction Manager (transaction)	If true, Camel will create a JmsTransactionManager, if there is no transactionManager injected when option transacted=true.	true	boolean
transactionManager (transaction)	The Spring transaction manager to use.		PlatformTransaction Manager
transactionName (transaction)	The name of the transaction to use.		String
transactionTimeout (transaction)	The timeout value of the transaction (in seconds), if using transacted mode.	-1	int
testConnectionOn Startup (common)	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. The JMS producers is tested as well.	false	boolean
asyncStartListener (advanced)	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.	false	boolean
asyncStopListener (advanced)	Whether to stop the JmsConsumer message listener asynchronously, when stopping a route.	false	boolean
forceSendOriginal Message (producer)	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.	false	boolean
requestTimeout (producer)	The timeout for waiting for a reply when using the InOut Exchange Pattern (in milliseconds). The default is 20 seconds. You can include the header CamelJmsRequestTimeout to override this endpoint configured timeout value, and thus have per message individual timeout values. See also the requestTimeoutCheckerInterval option.	20000	long
requestTimeoutChecker Interval (advanced)	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.	1000	long
transferExchange (advanced)	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.	false	boolean
transferException (advanced)	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.	false	boolean
transferFault (advanced)	If enabled and you are using Request Reply messaging (InOut) and an Exchange failed with a SOAP fault (not exception) on the consumer side, then the fault flag on MessageisFault() will be send back in the response as a JMS header with the key org.apache.camel.component.jms.JmsConstantsJMS_TRANSFER_FAULTJMS_TRANSFER_FAULT. If the client is Camel, the returned fault flag will be set on the link org.apache.camel.MessagesetFault(boolean). You may want to enable this when using Camel components that support faults such as SOAP based such as cxf or spring-ws.	false	boolean
jmsOperations (advanced)	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.		JmsOperations
destinationResolver (advanced)	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).		DestinationResolver
replyToType (producer)	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 Camel JMS documentation 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.		ReplyToType
preserveMessageQos (producer)	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.	false	boolean
asyncConsumer (consumer)	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 transaction must be executed synchronously (Camel 3.0 may support async transactions).	false	boolean
allowNullBody (producer)	Whether to allow sending messages with no body. If this option is false and the message body is null, then an JMSException is thrown.	true	boolean
includeSentJMS MessageID (producer)	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.	false	boolean
includeAllJMSX Properties (advanced)	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.	false	boolean
defaultTaskExecutor Type (consumer)	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.		DefaultTaskExecutor Type
jmsKeyFormatStrategy (advanced)	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.		JmsKeyFormatStrategy
allowAdditionalHeaders (producer)	This option is used to allow additional headers which may have values that are invalid according to JMS specification. For example some message systems such as WMQ do this with header names using prefix JMS_IBM_MQMD_ containing values with byte array or other invalid types. You can specify multiple header names separated by comma, and use as suffix for wildcard matching.		String
queueBrowseStrategy (advanced)	To use a custom QueueBrowseStrategy when browsing queues		QueueBrowseStrategy
messageCreatedStrategy (advanced)	To use the given MessageCreatedStrategy which are invoked when Camel creates new instances of javax.jms.Message objects when Camel is sending a JMS message.		MessageCreatedStrategy
waitForProvision CorrelationToBeUpdated Counter (advanced)	Number of times to wait for provisional correlation id to be updated to the actual correlation id when doing request/reply over JMS and when the option useMessageIDAsCorrelationID is enabled.	50	int
waitForProvision CorrelationToBeUpdated ThreadSleepingTime (advanced)	Interval in millis to sleep each time while waiting for provisional correlation id to be updated.	100	long
correlationProperty (producer)	Use this JMS property to correlate messages in InOut exchange pattern (request-reply) instead of JMSCorrelationID property. This allows you to exchange messages with systems that do not correlate messages using JMSCorrelationID JMS property. If used JMSCorrelationID will not be used or set by Camel. The value of here named property will be generated if not supplied in the header of the message under the same name.		String
subscriptionDurable (consumer)	Set whether to make the subscription durable. The durable subscription name to be used can be specified through the subscriptionName property. Default is false. Set this to true to register a durable subscription, typically in combination with a subscriptionName value (unless your message listener class name is good enough as subscription name). Only makes sense when listening to a topic (pub-sub domain), therefore this method switches the pubSubDomain flag as well.	false	boolean
subscriptionShared (consumer)	Set whether to make the subscription shared. The shared subscription name to be used can be specified through the subscriptionName property. Default is false. Set this to true to register a shared subscription, typically in combination with a subscriptionName value (unless your message listener class name is good enough as subscription name). Note that shared subscriptions may also be durable, so this flag can (and often will) be combined with subscriptionDurable as well. Only makes sense when listening to a topic (pub-sub domain), therefore this method switches the pubSubDomain flag as well. Requires a JMS 2.0 compatible message broker.	false	boolean
subscriptionName (consumer)	Set the name of a subscription to create. To be applied in case of a topic (pub-sub domain) with a shared or durable subscription. The subscription name needs to be unique within this client’s JMS client id. Default is the class name of the specified message listener. Note: Only 1 concurrent consumer (which is the default of this message listener container) is allowed for each subscription, except for a shared subscription (which requires JMS 2.0).		String
streamMessageType Enabled (producer)	Sets whether StreamMessage type is enabled or not. Message payloads of streaming kind such as files, InputStream, etc will either by sent as BytesMessage or StreamMessage. This option controls which kind will be used. By default BytesMessage is used which enforces the entire message payload to be read into memory. By enabling this option the message payload is read into memory in chunks and each chunk is then written to the StreamMessage until no more data.	false	boolean
formatDateHeadersTo Iso8601 (producer)	Sets whether date headers should be formatted according to the ISO 8601 standard.	false	boolean
headerFilterStrategy (filter)	To use a custom org.apache.camel.spi.HeaderFilterStrategy to filter header to and from Camel message.		HeaderFilterStrategy
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AMQP endpoint is configured using URI syntax:

amqp:destinationType:destinationName

with the following path and query parameters:

5.2.1. Path Parameters (2 parameters):

Name	Description	Default	Type
destinationType	The kind of destination to use	queue	String
destinationName	Required Name of the queue or topic to use as destination		String

5.2.2. Query Parameters (91 parameters):

Name	Description	Default	Type
clientId (common)	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. If using Apache ActiveMQ you may prefer to use Virtual Topics instead.		String
connectionFactory (common)	The connection factory to be use. A connection factory must be configured either on the component or endpoint.		ConnectionFactory
disableReplyTo (common)	Specifies whether Camel ignores the JMSReplyTo header in messages. If true, Camel does not send a reply back to the destination specified in the JMSReplyTo header. You can use this option if you want Camel to consume from a route and you do not want Camel to automatically send back a reply message because another component in your code handles the reply message. You can also use this option if you want to use Camel as a proxy between different message brokers and you want to route message from one system to another.	false	boolean
durableSubscriptionName (common)	The durable subscriber name for specifying durable topic subscriptions. The clientId option must be configured as well.		String
jmsMessageType (common)	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.		JmsMessageType
testConnectionOnStartup (common)	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. The JMS producers is tested as well.	false	boolean
acknowledgementModeName (consumer)	The JMS acknowledgement name, which is one of: SESSION_TRANSACTED, CLIENT_ACKNOWLEDGE, AUTO_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE	AUTO_ ACKNOWLEDGE	String
asyncConsumer (consumer)	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 transaction must be executed synchronously (Camel 3.0 may support async transactions).	false	boolean
autoStartup (consumer)	Specifies whether the consumer container should auto-startup.	true	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
cacheLevel (consumer)	Sets the cache level by ID for the underlying JMS resources. See cacheLevelName option for more details.		int
cacheLevelName (consumer)	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 is CACHE_AUTO. See the Spring documentation and Transactions Cache Levels for more information.	CACHE_AUTO	String
concurrentConsumers (consumer)	Specifies the default number of concurrent consumers when consuming from JMS (not for request/reply over JMS). See also the maxMessagesPerTask option to control dynamic scaling up/down of threads. When doing request/reply over JMS then the option replyToConcurrentConsumers is used to control number of concurrent consumers on the reply message listener.	1	int
maxConcurrentConsumers (consumer)	Specifies the maximum number of concurrent consumers when consuming from JMS (not for request/reply over JMS). See also the maxMessagesPerTask option to control dynamic scaling up/down of threads. When doing request/reply over JMS then the option replyToMaxConcurrentConsumers is used to control number of concurrent consumers on the reply message listener.		int
replyTo (consumer)	Provides an explicit ReplyTo destination, which overrides any incoming value of Message.getJMSReplyTo().		String
replyToDeliveryPersistent (consumer)	Specifies whether to use persistent delivery by default for replies.	true	boolean
selector (consumer)	Sets the JMS selector to use		String
subscriptionDurable (consumer)	Set whether to make the subscription durable. The durable subscription name to be used can be specified through the subscriptionName property. Default is false. Set this to true to register a durable subscription, typically in combination with a subscriptionName value (unless your message listener class name is good enough as subscription name). Only makes sense when listening to a topic (pub-sub domain), therefore this method switches the pubSubDomain flag as well.	false	boolean
subscriptionName (consumer)	Set the name of a subscription to create. To be applied in case of a topic (pub-sub domain) with a shared or durable subscription. The subscription name needs to be unique within this client’s JMS client id. Default is the class name of the specified message listener. Note: Only 1 concurrent consumer (which is the default of this message listener container) is allowed for each subscription, except for a shared subscription (which requires JMS 2.0).		String
subscriptionShared (consumer)	Set whether to make the subscription shared. The shared subscription name to be used can be specified through the subscriptionName property. Default is false. Set this to true to register a shared subscription, typically in combination with a subscriptionName value (unless your message listener class name is good enough as subscription name). Note that shared subscriptions may also be durable, so this flag can (and often will) be combined with subscriptionDurable as well. Only makes sense when listening to a topic (pub-sub domain), therefore this method switches the pubSubDomain flag as well. Requires a JMS 2.0 compatible message broker.	false	boolean
acceptMessagesWhileStopping (consumer)	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 enqueued 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.	false	boolean
allowReplyManagerQuickStop (consumer)	Whether the DefaultMessageListenerContainer used in the reply managers for request-reply messaging allow the DefaultMessageListenerContainer.runningAllowed flag to quick stop in case JmsConfigurationisAcceptMessagesWhileStopping is enabled, and org.apache.camel.CamelContext is currently being stopped. This quick stop ability is enabled by default in the regular JMS consumers but to enable for reply managers you must enable this flag.	false	boolean
consumerType (consumer)	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 messageListenerContainerFactory option will determine what org.springframework.jms.listener.AbstractMessageListenerContainer to use.	Default	ConsumerType
defaultTaskExecutorType (consumer)	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.		DefaultTaskExecutor Type
eagerLoadingOfProperties (consumer)	Enables eager loading of JMS properties and payload as soon as a message is loaded which generally is inefficient as the JMS properties may not be required but sometimes can catch early any issues with the underlying JMS provider and the use of JMS properties	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
exposeListenerSession (consumer)	Specifies whether the listener session should be exposed when consuming messages.	false	boolean
replyToSameDestination Allowed (consumer)	Whether a JMS consumer is allowed to send a reply message to the same destination that the consumer is using to consume from. This prevents an endless loop by consuming and sending back the same message to itself.	false	boolean
taskExecutor (consumer)	Allows you to specify a custom task executor for consuming messages.		TaskExecutor
deliveryMode (producer)	Specifies the delivery mode to be used. Possibles values are those defined by javax.jms.DeliveryMode. NON_PERSISTENT = 1 and PERSISTENT = 2.		Integer
deliveryPersistent (producer)	Specifies whether persistent delivery is used by default.	true	boolean
explicitQosEnabled (producer)	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.	false	Boolean
formatDateHeadersToIso8601 (producer)	Sets whether JMS date properties should be formatted according to the ISO 8601 standard.	false	boolean
preserveMessageQos (producer)	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.	false	boolean
priority (producer)	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.	4	int
replyToConcurrentConsumers (producer)	Specifies the default number of concurrent consumers when doing request/reply over JMS. See also the maxMessagesPerTask option to control dynamic scaling up/down of threads.	1	int
replyToMaxConcurrent Consumers (producer)	Specifies the maximum number of concurrent consumers when using request/reply over JMS. See also the maxMessagesPerTask option to control dynamic scaling up/down of threads.		int
replyToOnTimeoutMax ConcurrentConsumers (producer)	Specifies the maximum number of concurrent consumers for continue routing when timeout occurred when using request/reply over JMS.	1	int
replyToOverride (producer)	Provides an explicit ReplyTo destination in the JMS message, which overrides the setting of replyTo. It is useful if you want to forward the message to a remote Queue and receive the reply message from the ReplyTo destination.		String
replyToType (producer)	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 Camel JMS documentation 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.		ReplyToType
requestTimeout (producer)	The timeout for waiting for a reply when using the InOut Exchange Pattern (in milliseconds). The default is 20 seconds. You can include the header CamelJmsRequestTimeout to override this endpoint configured timeout value, and thus have per message individual timeout values. See also the requestTimeoutCheckerInterval option.	20000	long
timeToLive (producer)	When sending messages, specifies the time-to-live of the message (in milliseconds).	-1	long
allowAdditionalHeaders (producer)	This option is used to allow additional headers which may have values that are invalid according to JMS specification. For example some message systems such as WMQ do this with header names using prefix JMS_IBM_MQMD_ containing values with byte array or other invalid types. You can specify multiple header names separated by comma, and use as suffix for wildcard matching.		String
allowNullBody (producer)	Whether to allow sending messages with no body. If this option is false and the message body is null, then an JMSException is thrown.	true	boolean
alwaysCopyMessage (producer)	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)	false	boolean
correlationProperty (producer)	When using InOut exchange pattern use this JMS property instead of JMSCorrelationID JMS property to correlate messages. If set messages will be correlated solely on the value of this property JMSCorrelationID property will be ignored and not set by Camel.		String
disableTimeToLive (producer)	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.	false	boolean
forceSendOriginalMessage (producer)	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.	false	boolean
includeSentJMSMessageID (producer)	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.	false	boolean
replyToCacheLevelName (producer)	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.		String
replyToDestinationSelector Name (producer)	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).		String
streamMessageTypeEnabled (producer)	Sets whether StreamMessage type is enabled or not. Message payloads of streaming kind such as files, InputStream, etc will either by sent as BytesMessage or StreamMessage. This option controls which kind will be used. By default BytesMessage is used which enforces the entire message payload to be read into memory. By enabling this option the message payload is read into memory in chunks and each chunk is then written to the StreamMessage until no more data.	false	boolean
allowSerializedHeaders (advanced)	Controls whether or not to include serialized headers. Applies only when transferExchange is true. This requires that the objects are serializable. Camel will exclude any non-serializable objects and log it at WARN level.	false	boolean
asyncStartListener (advanced)	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.	false	boolean
asyncStopListener (advanced)	Whether to stop the JmsConsumer message listener asynchronously, when stopping a route.	false	boolean
destinationResolver (advanced)	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).		DestinationResolver
errorHandler (advanced)	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. You can configure logging level and whether stack traces should be logged using errorHandlerLoggingLevel and errorHandlerLogStackTrace options. This makes it much easier to configure, than having to code a custom errorHandler.		ErrorHandler
exceptionListener (advanced)	Specifies the JMS Exception Listener that is to be notified of any underlying JMS exceptions.		ExceptionListener
headerFilterStrategy (advanced)	To use a custom HeaderFilterStrategy to filter header to and from Camel message.		HeaderFilterStrategy
idleConsumerLimit (advanced)	Specify the limit for the number of consumers that are allowed to be idle at any given time.	1	int
idleTaskExecutionLimit (advanced)	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.	1	int
includeAllJMSXProperties (advanced)	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.	false	boolean
jmsKeyFormatStrategy (advanced)	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.		String
mapJmsMessage (advanced)	Specifies whether Camel should auto map the received JMS message to a suited payload type, such as javax.jms.TextMessage to a String etc.	true	boolean
maxMessagesPerTask (advanced)	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.	-1	int
messageConverter (advanced)	To use a custom Spring org.springframework.jms.support.converter.MessageConverter so you can be in control how to map to/from a javax.jms.Message.		MessageConverter
messageCreatedStrategy (advanced)	To use the given MessageCreatedStrategy which are invoked when Camel creates new instances of javax.jms.Message objects when Camel is sending a JMS message.		MessageCreatedStrategy
messageIdEnabled (advanced)	When sending, specifies whether message IDs should be added. This is just an hint to the JMS broker.If the JMS provider accepts this hint, these messages must have the message ID set to null; if the provider ignores the hint, the message ID must be set to its normal unique value	true	boolean
messageListenerContainer Factory (advanced)	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.		MessageListener ContainerFactory
messageTimestampEnabled (advanced)	Specifies whether timestamps should be enabled by default on sending messages. This is just an hint to the JMS broker.If the JMS provider accepts this hint, these messages must have the timestamp set to zero; if the provider ignores the hint the timestamp must be set to its normal value	true	boolean
pubSubNoLocal (advanced)	Specifies whether to inhibit the delivery of messages published by its own connection.	false	boolean
receiveTimeout (advanced)	The timeout for receiving messages (in milliseconds).	1000	long
recoveryInterval (advanced)	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.	5000	long
requestTimeoutChecker Interval (advanced)	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.	1000	long
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
transferException (advanced)	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.	false	boolean
transferExchange (advanced)	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.	false	boolean
transferFault (advanced)	If enabled and you are using Request Reply messaging (InOut) and an Exchange failed with a SOAP fault (not exception) on the consumer side, then the fault flag on MessageisFault() will be send back in the response as a JMS header with the key org.apache.camel.component.jms.JmsConstantsJMS_TRANSFER_FAULTJMS_TRANSFER_FAULT. If the client is Camel, the returned fault flag will be set on the link org.apache.camel.MessagesetFault(boolean). You may want to enable this when using Camel components that support faults such as SOAP based such as cxf or spring-ws.	false	boolean
useMessageIDAsCorrelation ID (advanced)	Specifies whether JMSMessageID should always be used as JMSCorrelationID for InOut messages.	false	boolean
waitForProvisionCorrelation ToBeUpdatedCounter (advanced)	Number of times to wait for provisional correlation id to be updated to the actual correlation id when doing request/reply over JMS and when the option useMessageIDAsCorrelationID is enabled.	50	int
waitForProvisionCorrelation ToBeUpdatedThreadSleeping Time (advanced)	Interval in millis to sleep each time while waiting for provisional correlation id to be updated.	100	long
errorHandlerLoggingLevel (logging)	Allows to configure the default errorHandler logging level for logging uncaught exceptions.	WARN	LoggingLevel
errorHandlerLogStackTrace (logging)	Allows to control whether stacktraces should be logged or not, by the default errorHandler.	true	boolean
password (security)	Password to use with the ConnectionFactory. You can also configure username/password directly on the ConnectionFactory.		String
username (security)	Username to use with the ConnectionFactory. You can also configure username/password directly on the ConnectionFactory.		String
transacted (transaction)	Specifies whether to use transacted mode	false	boolean
lazyCreateTransaction Manager (transaction)	If true, Camel will create a JmsTransactionManager, if there is no transactionManager injected when option transacted=true.	true	boolean
transactionManager (transaction)	The Spring transaction manager to use.		PlatformTransaction Manager
transactionName (transaction)	The name of the transaction to use.		String
transactionTimeout (transaction)	The timeout value of the transaction (in seconds), if using transacted mode.	-1	int

5.3. Usage

As AMQP component is inherited from JMS component, the usage of the former is almost identical to the latter:

Using AMQP component

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

5.4. Configuring AMQP component

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

Creating AMQP 1.0 component

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

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

Creating AMQP 1.0 component

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

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

AMQP connection details auto-configuration

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

Likewise, you can also use CDI producer methods when using Camel-CDI

AMQP connection details auto-configuration for CDI

@Produces
AMQPConnectionDetails amqpConnection() {
  return new AMQPConnectionDetails("amqp://localhost:5672");
}

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

AMQP connection details auto-configuration

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

Enabling AMQP specific options

If you, for example, need to enable amqp.traceFrames you can do that by appending the option to your URI, like the following example:

AMQPComponent amqp = AMQPComponent.amqpComponent("amqp://localhost:5672?amqp.traceFrames=true");

For reference take a look at the QPID JMS client configuration

5.5. Using topics

To have using topics working with camel-amqp you need to configure the component to use topic:// as topic prefix, as shown below:

 <bean id="amqp" class="org.apache.camel.component.amqp.AmqpComponent">
   <property name="connectionFactory">
     <bean class="org.apache.qpid.jms.JmsConnectionFactory" factory-method="createFromURL">
       <property name="remoteURI" value="amqp://localhost:5672" />
       <property name="topicPrefix" value="topic://" />  <!-- only necessary when connecting to ActiveMQ over AMQP 1.0 -->
     </bean>
   </property>
 </bean>

Keep in mind that both AMQPComponent#amqpComponent() methods and AMQPConnectionDetails pre-configure the component with the topic prefix, so you don’t have to configure it explicitly.

5.6. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 6. APNS Component

Available as of Camel version 2.8

The apns component is used for sending notifications to iOS devices. The apns components use javapns library.
The component supports sending notifications to Apple Push Notification Servers (APNS) and consuming feedback from the servers.

The consumer is configured with 3600 seconds for polling by default because it is a best practice to consume feedback stream from Apple Push Notification Servers only from time to time. For example: every 1 hour to avoid flooding the servers.

The feedback stream gives informations about inactive devices. You only need to get this informations every some hours if your mobile application is not a heavily used one.

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

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

6.1. URI format

To send notifications:

apns:notify[?options]

To consume feedback:

apns:consumer[?options]

6.2. Options

The APNS component supports 2 options which are listed below.

Name	Description	Default	Type
apnsService (common)	Required The ApnsService to use. The org.apache.camel.component.apns.factory.ApnsServiceFactory can be used to build a ApnsService		ApnsService
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The APNS endpoint is configured using URI syntax:

apns:name

with the following path and query parameters:

6.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
name	Name of the endpoint		String

6.2.2. Query Parameters (20 parameters):

Name	Description	Default	Type
tokens (common)	Configure this property in case you want to statically declare tokens related to devices you want to notify. Tokens are separated by comma.		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean

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

6.2.3. Component

The ApnsComponent must be configured with a com.notnoop.apns.ApnsService. The service can be created and configured using the org.apache.camel.component.apns.factory.ApnsServiceFactory. See further below for an example. And as well in the test source code.

6.2.3.1. SSL Setting

In order to use secure connection, an instance of org.apache.camel.util.jsse.SSLContextParameters should be injected to org.apache.camel.component.apns.factory.ApnsServiceFactory which is used to configure the component. See the test resources for an example. ssl example

6.3. Exchange data format

When Camel will fetch feedback data corresponding to inactive devices, it will retrieve a List of InactiveDevice objects. Each InactiveDevice object of the retrieved list will be setted as the In body, and then processed by the consumer endpoint.

6.4. Message Headers

Camel Apns uses these headers.

Property	Default	Description
`CamelApnsTokens`		Empty by default.
`CamelApnsMessageType`	`STRING, PAYLOAD, APNS_NOTIFICATION`	In case you choose PAYLOAD for the message type, then the message will be considered as a APNS payload and sent as is. In case you choose STRING, message will be converted as a APNS payload. From Camel 2.16 onwards APNS_NOTIFICATION is used for sending message body as com.notnoop.apns.ApnsNotification types.

6.5. ApnsServiceFactory builder callback

ApnsServiceFactory comes with the empty callback method that could be used to configure (or even replace) the default ApnsServiceBuilder instance. The signature of the method could look as follows:

protected ApnsServiceBuilder configureServiceBuilder(ApnsServiceBuilder serviceBuilder);

And could be used like as follows:

ApnsServiceFactory proxiedApnsServiceFactory = new ApnsServiceFactory(){
  
  @Override
  protected ApnsServiceBuilder configureServiceBuilder(ApnsServiceBuilder serviceBuilder) {
    return serviceBuilder.withSocksProxy("my.proxy.com", 6666);
  }

};

6.6. Samples

6.6.1. Camel Xml route

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:camel="http://camel.apache.org/schema/spring"
       xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
        http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">

    <!-- Replace by desired values -->
    <bean id="apnsServiceFactory" class="org.apache.camel.component.apns.factory.ApnsServiceFactory">

        <!-- Optional configuration of feedback host and port -->
        <!-- <property name="feedbackHost" value="localhost" /> -->
        <!-- <property name="feedbackPort" value="7843" /> -->

        <!-- Optional configuration of gateway host and port -->
        <!-- <property name="gatewayHost" value="localhost" /> -->
        <!-- <property name="gatewayPort" value="7654" /> -->

        <!-- Declaration of certificate used -->
                <!-- from Camel 2.11 onwards you can use prefix: classpath:, file: to refer to load the certificate from classpath or file. Default it classpath -->
        <property name="certificatePath" value="certificate.p12" />
        <property name="certificatePassword" value="MyCertPassword" />

        <!-- Optional connection strategy - By Default: No need to configure -->
        <!-- Possible options: NON_BLOCKING, QUEUE, POOL or Nothing -->
        <!-- <property name="connectionStrategy" value="POOL" /> -->
        <!-- Optional pool size -->
        <!-- <property name="poolSize" value="15" /> -->

        <!-- Optional connection strategy - By Default: No need to configure -->
        <!-- Possible options: EVERY_HALF_HOUR, EVERY_NOTIFICATION or Nothing (Corresponds to NEVER javapns option) -->
        <!-- <property name="reconnectionPolicy" value="EVERY_HALF_HOUR" /> -->
    </bean>

    <bean id="apnsService" factory-bean="apnsServiceFactory" factory-method="getApnsService" />

    <!-- Replace this declaration by wanted configuration -->
    <bean id="apns" class="org.apache.camel.component.apns.ApnsComponent">
        <property name="apnsService" ref="apnsService" />
    </bean>

    <camelContext id="camel-apns-test" xmlns="http://camel.apache.org/schema/spring">
            <route id="apns-test">
                    <from uri="apns:consumer?initialDelay=10&amp;delay=3600&amp;timeUnit=SECONDS" />
                    <to uri="log:org.apache.camel.component.apns?showAll=true&amp;multiline=true" />
                    <to uri="mock:result" />
            </route>
    </camelContext>

</beans>

6.6.2. Camel Java route

Create camel context and declare apns component programmatically

    protected CamelContext createCamelContext() throws Exception {
        CamelContext camelContext = super.createCamelContext();

        ApnsServiceFactory apnsServiceFactory = new ApnsServiceFactory();
        apnsServiceFactory.setCertificatePath("classpath:/certificate.p12");
        apnsServiceFactory.setCertificatePassword("MyCertPassword");

        ApnsService apnsService = apnsServiceFactory.getApnsService(camelContext);

        ApnsComponent apnsComponent = new ApnsComponent(apnsService);
        camelContext.addComponent("apns", apnsComponent);

        return camelContext;
    }

[[APNS-ApnsProducer-iOStargetdevicedynamicallyconfiguredviaheader:"CamelApnsTokens"]] ApnsProducer - iOS target device dynamically configured via header: "CamelApnsTokens"

    protected RouteBuilder createRouteBuilder() throws Exception {
        return new RouteBuilder() {
            public void configure() throws Exception {
                from("direct:test")
                    .setHeader(ApnsConstants.HEADER_TOKENS, constant(IOS_DEVICE_TOKEN))
                    .to("apns:notify");
                }
        }
    }

ApnsProducer - iOS target device statically configured via uri

    protected RouteBuilder createRouteBuilder() throws Exception {
        return new RouteBuilder() {
            public void configure() throws Exception {
                from("direct:test").
                to("apns:notify?tokens=" + IOS_DEVICE_TOKEN);
            }
        };
    }

ApnsConsumer

from("apns:consumer?initialDelay=10&delay=3600&timeUnit=SECONDS")
    .to("log:com.apache.camel.component.apns?showAll=true&multiline=true")
    .to("mock:result");

6.7. See Also

Chapter 7. ASN.1 File DataFormat

Available as of Camel version 2.20

The ASN.1 Data Format Data Format [Intoduction to ASN.1](https://www.itu.int/en/ITU-T/asn1/Pages/introduction.aspx) is a Camel Frameworks’s data format implementation based on Bouncy Castle’s bcprov-jdk15on library and jASN.1’s java compiler for the formal notation used for describing data transmitted by telecommunications protocols, regardless of language implementation and physical representation of these data, whatever the application, whether complex or very simple. Messages can be unmarshalled (conversion to simple Java POJO(s)) to plain Java objects. By the help of Camel’s routing engine and data transformations you can then play with POJO(s) and apply customised formatting and call other Camel Component’s to convert and send messages to upstream systems.

7.1. ASN.1 Data Format Options

The ASN.1 File dataformat supports 3 options which are listed below.

Name	Default	Java Type	Description
usingIterator	`false`	`Boolean`	If the asn1 file has more then one entry, the setting this option to true, allows to work with the splitter EIP, to split the data using an iterator in a streaming mode.
clazzName		`String`	Name of class to use when unmarshalling
contentTypeHeader	`false`	`Boolean`	Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.

7.2. Unmarshal

There are 3 different ways to unmarshal ASN.1 structured messages. (Usually binary files)

In this first example we unmarshal BER file payload to OutputStream and send it to mock endpoint.

from("direct:unmarshal").unmarshal(asn1).to("mock:unmarshal");

In the second example we unmarshal BER file payload to byte array using Split EIP. The reason for applying Split EIP is that usually each BER file or (ASN.1 structured file) contains multiple records to process and Split EIP helps us to get each record in a file as byte arrays which is actually ASN1Primitive’s instance (by the use of Bouncy Castle’s ASN.1 support in bcprov-jdk15on library) Byte arrays then may be converted to ASN1Primitive by the help of public static method in (ASN1Primitive.fromByteArray) In such example, note that you need to set usingIterator=true

from("direct:unmarshal").unmarshal(asn1).split(body(Iterator.class)).streaming().to("mock:unmarshal");

In the last example we unmarshal BER file payload to plain old Java Objects using Split EIP. The reason for applying Split EIP is already mentioned in the previous example. Please note and keep in mind that reason. In such example we also need to set the fully qualified name of the class or <YourObject>.class reference through data format. The important thing to note here is that your object should have been generated by jasn1 compiler which is a nice tool to generate java object representations of your ASN.1 structure. For the reference usage of jasn1 compiler see [JASN.1 Project Page](https://www.openmuc.org/asn1/) and please also see how the compiler is invoked with the help of maven’s exec plugin. For example, in this data format’s unit tests an example ASN.1 structure(TestSMSBerCdr.asn1) is added in src/test/resources/asn1_structure. jasn1 compiler is invoked and java object’s representations are generated in ${basedir}/target/generated/src/test/java The nice thing about this example, you will get POJO instance at the mock endpoint or at whatever your endpoint is.

from("direct:unmarshaldsl")
         .unmarshal()
         .asn1("org.apache.camel.dataformat.asn1.model.testsmscbercdr.SmsCdr")
         .split(body(Iterator.class)).streaming()
.to("mock:unmarshaldsl");

7.3. Dependencies

To use ASN.1 data format in your camel routes you need to add a dependency on camel-asn1 which implements this data format.

If you use Maven you can 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).

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

Chapter 8. Asterisk Component

Available as of Camel version 2.18

The asterisk: component allows you to work easily with an Asterisk PBX Server http://www.asterisk.org/ using asterisk-java

This component help to interface with Asterisk Manager Interface

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

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

8.1. URI format

asterisk:name[?options]

8.2. Options

The Asterisk component has no options.

The Asterisk endpoint is configured using URI syntax:

asterisk:name

with the following path and query parameters:

8.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
name	Required Logical name		String

8.2.2. Query Parameters (8 parameters):

Name	Description	Default	Type
hostname (common)	Required The hostname of the asterisk server		String
password (common)	Required Login password		String
username (common)	Required Login username		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
action (producer)	What action to perform such as getting queue status, sip peers or extension state.		AsteriskAction
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

8.3. Action

Supported actions are:

QUEUE_STATUS, Queue Status
SIP_PEERS, List SIP Peers
EXTENSION_STATE, Check Extension Status

Chapter 9. Atmos Component

Available as of Camel version 2.15

Camel-Atmos is an Apache Camel component that allows you to work with ViPR object data services using the Atmos Client.

from("atmos:foo/get?remotePath=/path").to("mock:test");

9.1. Options

The Atmos component supports 5 options which are listed below.

Name	Description	Default	Type
fullTokenId (security)	The token id to pass to the Atmos client		String
secretKey (security)	The secret key to pass to the Atmos client		String
uri (advanced)	The URI of the server for the Atmos client to connect to		String
sslValidation (security)	Whether the Atmos client should perform SSL validation	false	boolean
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Atmos endpoint is configured using URI syntax:

atmos:name/operation

with the following path and query parameters:

9.1.1. Path Parameters (2 parameters):

Name	Description	Default	Type
name	Atmos name		String
operation	Required Operation to perform		AtmosOperation

9.1.2. Query Parameters (12 parameters):

Name	Description	Default	Type
enableSslValidation (common)	Atmos SSL validation	false	boolean
fullTokenId (common)	Atmos client fullTokenId		String
localPath (common)	Local path to put files		String
newRemotePath (common)	New path on Atmos when moving files		String
query (common)	Search query on Atmos		String
remotePath (common)	Where to put files on Atmos		String
secretKey (common)	Atmos shared secret		String
uri (common)	Atomos server uri		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

9.2. Dependencies

To use Atmos in your camel routes you need to add the dependency on camel-atmos 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).

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

9.3. Integrations

When you look at atmos integrations, there is one type of consumer, GetConsumer, which is a type of ScheduledPollConsumer.

Get

Whereas there are 4 types of producers which are

Get
Del
Move
Put

9.4. Examples

These example are taken from tests:

from("atmos:foo/get?remotePath=/path").to("mock:test");

Here, this is a consumer example. remotePath represents the path from where the data will be read and passes the camel exchange to regarding producer Underneath, this component uses atmos client API for this and every other operations.

from("direct:start")
.to("atmos://get?remotePath=/dummy/dummy.txt")
.to("mock:result");

Here, this a producer sample. remotePath represents the path where the operations occur on ViPR object data service. In producers, operations(Get,Del, Move,Put) run on ViPR object data services and results are set on headers of camel exchange.

Regarding the operations, the following headers are set on camel exhange

DOWNLOADED_FILE, DOWNLOADED_FILES, UPLOADED_FILE, UPLOADED_FILES, FOUND_FILES, DELETED_PATH, MOVED_PATH;

9.5. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 10. Atmosphere Websocket Component

Available as of Camel version 2.14

The atmosphere-websocket: component provides Websocket based endpoints for a servlet communicating with external clients over Websocket (as a servlet accepting websocket connections from external clients).
The component uses the SERVLET component and uses the https://github.com/Atmosphere/atmosphere[Atmosphere] library to support the Websocket transport in various Servlet containers (e..g., Jetty, Tomcat, …).

Unlike the Websocket component that starts the embedded Jetty server, this component uses the servlet provider of the container.

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

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

10.1. Atmosphere-Websocket Options

The Atmosphere Websocket component supports 8 options which are listed below.

Name	Description	Default	Type
servletName (common)	Default name of servlet to use. The default name is CamelServlet.		String
httpRegistry (common)	To use a custom org.apache.camel.component.servlet.HttpRegistry.		HttpRegistry
attachmentMultipart Binding (common)	Whether to automatic bind multipart/form-data as attachments on the Camel Exchange. The options attachmentMultipartBinding=true and disableStreamCache=false cannot work together. Remove disableStreamCache to use AttachmentMultipartBinding. This is turn off by default as this may require servlet specific configuration to enable this when using Servlet’s.	false	boolean
httpBinding (advanced)	To use a custom HttpBinding to control the mapping between Camel message and HttpClient.		HttpBinding
httpConfiguration (advanced)	To use the shared HttpConfiguration as base configuration.		HttpConfiguration
allowJavaSerialized Object (advanced)	Whether to allow java serialization when a request uses context-type=application/x-java-serialized-object. This is by default turned off. If you enable this then be aware that Java will deserialize the incoming data from the request to Java and that can be a potential security risk.	false	boolean
headerFilterStrategy (filter)	To use a custom org.apache.camel.spi.HeaderFilterStrategy to filter header to and from Camel message.		HeaderFilterStrategy
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Atmosphere Websocket endpoint is configured using URI syntax:

atmosphere-websocket:servicePath

with the following path and query parameters:

10.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
servicePath	Required Name of websocket endpoint		String

10.1.2. Query Parameters (37 parameters):

Name	Description	Default	Type
chunked (common)	If this option is false the Servlet will disable the HTTP streaming and set the content-length header on the response	true	boolean
disableStreamCache (common)	Determines whether or not the raw input stream from Servlet 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 Servlet 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 Servlet 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. The http/http4 producer will by default cache the response body stream. If setting this option to true, then the producers will not cache the response body stream but use the response stream as-is as the message body.	false	boolean
headerFilterStrategy (common)	To use a custom HeaderFilterStrategy to filter header to and from Camel message.		HeaderFilterStrategy
sendToAll (common)	Whether to send to all (broadcast) or send to a single receiver.	false	boolean
transferException (common)	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. This is by default turned off. If you enable this then be aware that Java will deserialize the incoming data from the request to Java and that can be a potential security risk.	false	boolean
useStreaming (common)	To enable streaming to send data as multiple text fragments.	false	boolean
httpBinding (common)	To use a custom HttpBinding to control the mapping between Camel message and HttpClient.		HttpBinding
async (consumer)	Configure the consumer to work in async mode	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
httpMethodRestrict (consumer)	Used to only allow consuming if the HttpMethod matches, such as GET/POST/PUT etc. Multiple methods can be specified separated by comma.		String
matchOnUriPrefix (consumer)	Whether or not the consumer should try to find a target consumer by matching the URI prefix if no exact match is found.	false	boolean
responseBufferSize (consumer)	To use a custom buffer size on the javax.servlet.ServletResponse.		Integer
servletName (consumer)	Name of the servlet to use	CamelServlet	String
attachmentMultipartBinding (consumer)	Whether to automatic bind multipart/form-data as attachments on the Camel Exchange. The options attachmentMultipartBinding=true and disableStreamCache=false cannot work together. Remove disableStreamCache to use AttachmentMultipartBinding. This is turn off by default as this may require servlet specific configuration to enable this when using Servlet’s.	false	boolean
eagerCheckContentAvailable (consumer)	Whether to eager check whether the HTTP requests has content if the content-length header is 0 or not present. This can be turned on in case HTTP clients do not send streamed data.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
optionsEnabled (consumer)	Specifies whether to enable HTTP OPTIONS for this Servlet consumer. By default OPTIONS is turned off.	false	boolean
traceEnabled (consumer)	Specifies whether to enable HTTP TRACE for this Servlet consumer. By default TRACE is turned off.	false	boolean
bridgeEndpoint (producer)	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 option throwExceptionOnFailure to be false to let the HttpProducer send all the fault response back.	false	boolean
connectionClose (producer)	Specifies whether a Connection Close header must be added to HTTP Request. By default connectionClose is false.	false	boolean
copyHeaders (producer)	If this option is true then IN exchange headers will be copied to OUT exchange headers according to copy strategy. Setting this to false, allows to only include the headers from the HTTP response (not propagating IN headers).	true	boolean
httpMethod (producer)	Configure the HTTP method to use. The HttpMethod header cannot override this option if set.		HttpMethods
ignoreResponseBody (producer)	If this option is true, The http producer won’t read response body and cache the input stream	false	boolean
preserveHostHeader (producer)	If the option is true, HttpProducer will set the Host header to the value contained in the current exchange Host header, useful in reverse proxy applications where you want the Host header received by the downstream server to reflect the URL called by the upstream client, this allows applications which use the Host header to generate accurate URL’s for a proxied service	false	boolean
throwExceptionOnFailure (producer)	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.	true	boolean
cookieHandler (producer)	Configure a cookie handler to maintain a HTTP session		CookieHandler
okStatusCodeRange (producer)	The status codes which are considered a success response. The values are inclusive. Multiple ranges can be defined, separated by comma, e.g. 200-204,209,301-304. Each range must be a single number or from-to with the dash included.	200-299	String
urlRewrite (producer)	Deprecated 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 http://camel.apache.org/urlrewrite.html		UrlRewrite
mapHttpMessageBody (advanced)	If this option is true then IN exchange Body of the exchange will be mapped to HTTP body. Setting this to false will avoid the HTTP mapping.	true	boolean
mapHttpMessageFormUrl EncodedBody (advanced)	If this option is true then IN exchange Form Encoded body of the exchange will be mapped to HTTP. Setting this to false will avoid the HTTP Form Encoded body mapping.	true	boolean
mapHttpMessageHeaders (advanced)	If this option is true then IN exchange Headers of the exchange will be mapped to HTTP headers. Setting this to false will avoid the HTTP Headers mapping.	true	boolean
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
proxyAuthScheme (proxy)	Proxy authentication scheme to use		String
proxyHost (proxy)	Proxy hostname to use		String
proxyPort (proxy)	Proxy port to use		int
authHost (security)	Authentication host to use with NTML		String

10.2. URI Format

atmosphere-websocket:///relative path[?options]

10.3. Reading and Writing Data over Websocket

An atmopshere-websocket endpoint can either write data to the socket or read from the socket, depending on whether the endpoint is configured as the producer or the consumer, respectively.

10.4. Configuring URI to Read or Write Data

In the route below, Camel will read from the specified websocket connection.

from("atmosphere-websocket:///servicepath")
        .to("direct:next");

And the equivalent Spring sample:

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="atmosphere-websocket:///servicepath"/>
    <to uri="direct:next"/>
  </route>
</camelContext>

In the route below, Camel will read from the specified websocket connection.

from("direct:next")
        .to("atmosphere-websocket:///servicepath");

And the equivalent Spring sample:

<camelContext xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:next"/>
    <to uri="atmosphere-websocket:///servicepath"/>
  </route>
</camelContext>

10.5. See Also

Configuring Camel
Component
Endpoint
Getting Started
SERVLET
AHC-WS * Websocket

Chapter 11. Atom Component

Available as of Camel version 1.2

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:

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

11.1. URI format

atom://atomUri[?options]

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

11.2. Options

The Atom component has no options.

The Atom endpoint is configured using URI syntax:

atom:feedUri

with the following path and query parameters:

11.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
feedUri	Required The URI to the feed to poll.		String

11.2.2. Query Parameters (27 parameters):

Name	Description	Default	Type
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
feedHeader (consumer)	Sets whether to add the feed object as a header	true	boolean
filter (consumer)	Sets whether to use filtering or not of the entries.	true	boolean
lastUpdate (consumer)	Sets the timestamp to be used for filtering entries from the atom feeds. This options is only in conjunction with the splitEntries.		Date
password (consumer)	Sets the password to be used for basic authentication when polling from a HTTP feed		String
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
sortEntries (consumer)	Sets whether to sort entries by published date. Only works when splitEntries = true.	false	boolean
splitEntries (consumer)	Sets whether or not entries should be sent individually or whether the entire feed should be sent as a single message	true	boolean
throttleEntries (consumer)	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 = true.	true	boolean
username (consumer)	Sets the username to be used for basic authentication when polling from a HTTP feed		String
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean

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

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

11.4. Message Headers

Camel atom uses these headers.

Header	Description
`CamelAtomFeed`	When consuming the `org.apache.abdera.model.Feed` object is set to this header.

11.5. Samples

In this sample we poll James Strachan’s blog.

from("atom://http://macstrac.blogspot.com/feeds/posts/default").to("seda:feeds");

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.

11.6. See Also

Configuring Camel
Component
Endpoint
Getting Started
RSS

Chapter 12. Atomix Map Component

Available as of Camel version 2.20

The camel atomix-map component allows you to work with Atomix’s Distributed Map collection.

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

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

12.1. URI format

    atomix-map:mapName

12.2. Options

The Atomix Map component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (common)	The shared component configuration		AtomixMapConfiguration
atomix (common)	The shared AtomixClient instance		AtomixClient
nodes (common)	The nodes the AtomixClient should connect to		List
configurationUri (common)	The path to the AtomixClient configuration		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Atomix Map endpoint is configured using URI syntax:

atomix-map:resourceName

with the following path and query parameters:

12.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
resourceName	Required The distributed resource name		String

12.2.2. Query Parameters (18 parameters):

Name	Description	Default	Type
atomix (common)	The Atomix instance to use		Atomix
configurationUri (common)	The Atomix configuration uri.		String
defaultAction (common)	The default action.	PUT	Action
key (common)	The key to use if none is set in the header or to listen for events for a specific key.		Object
nodes (common)	The address of the nodes composing the cluster.		String
resultHeader (common)	The header that wil carry the result.		String
transport (common)	Sets the Atomix transport.	io.atomix.catalyst.transport.netty.NettyTransport	Transport
ttl (common)	The resource ttl.		long
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
defaultResourceConfig (advanced)	The cluster wide default resource configuration.		Properties
defaultResourceOptions (advanced)	The local default resource options.		Properties
ephemeral (advanced)	Sets if the local member should join groups as PersistentMember or not. If set to ephemeral the local member will receive an auto generated ID thus the local one is ignored.	false	boolean
readConsistency (advanced)	The read consistency level.		ReadConsistency
resourceConfigs (advanced)	Cluster wide resources configuration.		Map
resourceOptions (advanced)	Local resources configurations		Map
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

12.3. Headers

Name	Type	Values	Description
CamelAtomixResourceAction	AtomixMap.Action	PUT PUT_IF_ABSENT GET CLEAR SIZE CONTAINS_KEY CONTAINS_VALUE IS_EMPTY ENTRY_SET REMOVE REPLACE VALUES	The action to perform
CamelAtomixResourceKey	Object	-	The key to operate on
CamelAtomixResourceValue	Object	-	The value, if missing In Body is used
CamelAtomixResourceOldValue	Object	-	The old value
CamelAtomixResourceTTL	String / long	-	The entry TTL
CamelAtomixResourceReadConsistency	ReadConsistency	ATOMIC ATOMIC_LEASE SEQUENTIAL LOCAL	The read consistency level

12.4. Configuring the component to connect to an Atomix cluster

The nodes of the Atomix cluster you want to join can be se at Endpoint or component level (recommended), below some examples:

Endpoint:

<beans xmlns="...">
    <camelContext xmlns="http://camel.apache.org/schema/spring">
        <from uri="direct:start"/>
            <to uri="atomix-map:myMap?nodes=node-1.atomix.cluster:8700,node-2.atomix.cluster:8700"/>
        </route>
    </camelContext>
</beans>

Component:

<beans xmlns="...">
    <bean id="atomix-map" class="org.apache.camel.component.atomix.client.map.AtomixMapComponent">
        <property name="nodes" value="nodes=node-1.atomix.cluster:8700,node-2.atomix.cluster:8700"/>
    </bean>

    <camelContext xmlns="http://camel.apache.org/schema/spring">
        <from uri="direct:start"/>
            <to uri="atomix-map:myMap"/>
        </route>
    </camelContext>
</beans>

12.5. Usage examples:

PUT an element with TTL of 1 second:

FluentProducerTemplate.on(context)
    .withHeader(AtomixClientConstants.RESOURCE_ACTION, AtomixMap.Action.PUT)
    .withHeader(AtomixClientConstants.RESOURCE_KEY, key)
    .withHeader(AtomixClientConstants.RESOURCE_TTL, "1s")
    .withBody(val)
    .to("direct:start")
    .send();

Chapter 13. Atomix Messaging Component

Available as of Camel version 2.20

The camel atomix-messaging component allows you to work with Atomix’s Group Messaging.

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

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

13.1. URI format

    atomix-messaging:group

The Atomix Messaging component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (common)	The shared component configuration		AtomixMessaging Configuration
atomix (common)	The shared AtomixClient instance		AtomixClient
nodes (common)	The nodes the AtomixClient should connect to		List
configurationUri (common)	The path to the AtomixClient configuration		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Atomix Messaging endpoint is configured using URI syntax:

atomix-messaging:resourceName

with the following path and query parameters:

13.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
resourceName	Required The distributed resource name		String

13.1.2. Query Parameters (19 parameters):

Name	Description	Default	Type
atomix (common)	The Atomix instance to use		Atomix
broadcastType (common)	The broadcast type.	ALL	BroadcastType
channelName (common)	The messaging channel name		String
configurationUri (common)	The Atomix configuration uri.		String
defaultAction (common)	The default action.	DIRECT	Action
memberName (common)	The Atomix Group member name		String
nodes (common)	The address of the nodes composing the cluster.		String
resultHeader (common)	The header that wil carry the result.		String
transport (common)	Sets the Atomix transport.	io.atomix.catalyst.transport.netty.NettyTransport	Transport
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
defaultResourceConfig (advanced)	The cluster wide default resource configuration.		Properties
defaultResourceOptions (advanced)	The local default resource options.		Properties
ephemeral (advanced)	Sets if the local member should join groups as PersistentMember or not. If set to ephemeral the local member will receive an auto generated ID thus the local one is ignored.	false	boolean
readConsistency (advanced)	The read consistency level.		ReadConsistency
resourceConfigs (advanced)	Cluster wide resources configuration.		Map
resourceOptions (advanced)	Local resources configurations		Map
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

Chapter 14. Atomix MultiMap Component

Available as of Camel version 2.20

The camel atomix-multimap component allows you to work with Atomix’s Distributed MultiMap collection.

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

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

14.1. URI format

    atomix-multimap:multiMapName

The Atomix MultiMap component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (consumer)	The shared component configuration		AtomixMultiMap Configuration
atomix (consumer)	The shared AtomixClient instance		AtomixClient
nodes (consumer)	The nodes the AtomixClient should connect to		List
configurationUri (consumer)	The path to the AtomixClient configuration		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Atomix MultiMap endpoint is configured using URI syntax:

atomix-multimap:resourceName

with the following path and query parameters:

14.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
resourceName	Required The distributed resource name		String

14.1.2. Query Parameters (18 parameters):

Name	Description	Default	Type
atomix (consumer)	The Atomix instance to use		Atomix
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
configurationUri (consumer)	The Atomix configuration uri.		String
defaultAction (consumer)	The default action.	PUT	Action
key (consumer)	The key to use if none is set in the header or to listen for events for a specific key.		Object
nodes (consumer)	The address of the nodes composing the cluster.		String
resultHeader (consumer)	The header that wil carry the result.		String
transport (consumer)	Sets the Atomix transport.	io.atomix.catalyst.transport.netty.NettyTransport	Transport
ttl (consumer)	The resource ttl.		long
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
defaultResourceConfig (advanced)	The cluster wide default resource configuration.		Properties
defaultResourceOptions (advanced)	The local default resource options.		Properties
ephemeral (advanced)	Sets if the local member should join groups as PersistentMember or not. If set to ephemeral the local member will receive an auto generated ID thus the local one is ignored.	false	boolean
readConsistency (advanced)	The read consistency level.		ReadConsistency
resourceConfigs (advanced)	Cluster wide resources configuration.		Map
resourceOptions (advanced)	Local resources configurations		Map
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

Chapter 15. Atomix Queue Component

Available as of Camel version 2.20

The camel atomix-queue component allows you to work with Atomix’s Distributed Queue collection.

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

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

15.1. URI format

    atomix-queue:queueName

The Atomix Queue component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (common)	The shared component configuration		AtomixQueue Configuration
atomix (common)	The shared AtomixClient instance		AtomixClient
nodes (common)	The nodes the AtomixClient should connect to		List
configurationUri (common)	The path to the AtomixClient configuration		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Atomix Queue endpoint is configured using URI syntax:

atomix-queue:resourceName

with the following path and query parameters:

15.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
resourceName	Required The distributed resource name		String

15.1.2. Query Parameters (16 parameters):

Name	Description	Default	Type
atomix (common)	The Atomix instance to use		Atomix
configurationUri (common)	The Atomix configuration uri.		String
defaultAction (common)	The default action.	ADD	Action
nodes (common)	The address of the nodes composing the cluster.		String
resultHeader (common)	The header that wil carry the result.		String
transport (common)	Sets the Atomix transport.	io.atomix.catalyst.transport.netty.NettyTransport	Transport
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
defaultResourceConfig (advanced)	The cluster wide default resource configuration.		Properties
defaultResourceOptions (advanced)	The local default resource options.		Properties
ephemeral (advanced)	Sets if the local member should join groups as PersistentMember or not. If set to ephemeral the local member will receive an auto generated ID thus the local one is ignored.	false	boolean
readConsistency (advanced)	The read consistency level.		ReadConsistency
resourceConfigs (advanced)	Cluster wide resources configuration.		Map
resourceOptions (advanced)	Local resources configurations		Map
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

Chapter 16. Atomix Set Component

Available as of Camel version 2.20

The camel atomix-set component allows you to work with Atomix’s Distributed Set collection.

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

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

16.1. URI format

    atomix-set:setName

The Atomix Set component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (common)	The shared component configuration		AtomixSetConfiguration
atomix (common)	The shared AtomixClient instance		AtomixClient
nodes (common)	The nodes the AtomixClient should connect to		List
configurationUri (common)	The path to the AtomixClient configuration		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Atomix Set endpoint is configured using URI syntax:

atomix-set:resourceName

with the following path and query parameters:

16.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
resourceName	Required The distributed resource name		String

16.1.2. Query Parameters (17 parameters):

Name	Description	Default	Type
atomix (common)	The Atomix instance to use		Atomix
configurationUri (common)	The Atomix configuration uri.		String
defaultAction (common)	The default action.	ADD	Action
nodes (common)	The address of the nodes composing the cluster.		String
resultHeader (common)	The header that wil carry the result.		String
transport (common)	Sets the Atomix transport.	io.atomix.catalyst.transport.netty.NettyTransport	Transport
ttl (common)	The resource ttl.		long
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
defaultResourceConfig (advanced)	The cluster wide default resource configuration.		Properties
defaultResourceOptions (advanced)	The local default resource options.		Properties
ephemeral (advanced)	Sets if the local member should join groups as PersistentMember or not. If set to ephemeral the local member will receive an auto generated ID thus the local one is ignored.	false	boolean
readConsistency (advanced)	The read consistency level.		ReadConsistency
resourceConfigs (advanced)	Cluster wide resources configuration.		Map
resourceOptions (advanced)	Local resources configurations		Map
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

Chapter 17. Atomix Value Component

Available as of Camel version 2.20

The camel atomix-value component allows you to work with Atomix’s Distributed Value.

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

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

17.1. URI format

    atomix-value:valueName

The Atomix Value component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (common)	The shared component configuration		AtomixValue Configuration
atomix (common)	The shared AtomixClient instance		AtomixClient
nodes (common)	The nodes the AtomixClient should connect to		List
configurationUri (common)	The path to the AtomixClient configuration		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Atomix Value endpoint is configured using URI syntax:

atomix-value:resourceName

with the following path and query parameters:

17.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
resourceName	Required The distributed resource name		String

17.1.2. Query Parameters (17 parameters):

Name	Description	Default	Type
atomix (common)	The Atomix instance to use		Atomix
configurationUri (common)	The Atomix configuration uri.		String
defaultAction (common)	The default action.	SET	Action
nodes (common)	The address of the nodes composing the cluster.		String
resultHeader (common)	The header that wil carry the result.		String
transport (common)	Sets the Atomix transport.	io.atomix.catalyst.transport.netty.NettyTransport	Transport
ttl (common)	The resource ttl.		long
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
defaultResourceConfig (advanced)	The cluster wide default resource configuration.		Properties
defaultResourceOptions (advanced)	The local default resource options.		Properties
ephemeral (advanced)	Sets if the local member should join groups as PersistentMember or not. If set to ephemeral the local member will receive an auto generated ID thus the local one is ignored.	false	boolean
readConsistency (advanced)	The read consistency level.		ReadConsistency
resourceConfigs (advanced)	Cluster wide resources configuration.		Map
resourceOptions (advanced)	Local resources configurations		Map
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

Chapter 18. Avro Component

Available as of Camel version 2.10

This component provides a dataformat for avro, which allows serialization and deserialization of messages using Apache Avro’s binary dataformat. Moreover, it provides support for Apache Avro’s rpc, by providing producers and consumers endpoint for using avro over netty or http.

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

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

18.1. Apache Avro Overview

Avro allows you to define message types and a protocol using a json like format and then generate java code for the specified types and messages. An example of how a schema looks like is below.

{"namespace": "org.apache.camel.avro.generated",
 "protocol": "KeyValueProtocol",

 "types": [
     {"name": "Key", "type": "record",
      "fields": [
          {"name": "key",   "type": "string"}
      ]
     },
     {"name": "Value", "type": "record",
      "fields": [
          {"name": "value",   "type": "string"}
      ]
     }
 ],

 "messages": {
     "put": {
         "request": [{"name": "key", "type": "Key"}, {"name": "value", "type": "Value"} ],
         "response": "null"
     },
     "get": {
         "request": [{"name": "key", "type": "Key"}],
         "response": "Value"
     }
 }
}

You can easily generate classes from a schema, using maven, ant etc. More details can be found at the Apache Avro documentation.

However, it doesn’t enforce a schema first approach and you can create schema for your existing classes. Since 2.12 you can use existing protocol interfaces to make RCP calls. You should use interface for the protocol itself and POJO beans or primitive/String classes for parameter and result types. Here is an example of the class that corresponds to schema above:

package org.apache.camel.avro.reflection;

public interface KeyValueProtocol {
    void put(String key, Value value);
    Value get(String key);
}

class Value {
    private String value;
    public String getValue() { return value; }
    public void setValue(String value) { this.value = value; }
}

Note: Existing classes can be used only for RPC (see below), not in data format.

18.2. Using the Avro data format

Using the avro data format is as easy as specifying that the class that you want to marshal or unmarshal in your route.

    <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
        <route>
            <from uri="direct:in"/>
            <marshal>
                <avro instanceClass="org.apache.camel.dataformat.avro.Message"/>
            </marshal>
            <to uri="log:out"/>
        </route>
    </camelContext>

An alternative can be to specify the dataformat inside the context and reference it from your route.

    <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
         <dataFormats>
            <avro id="avro" instanceClass="org.apache.camel.dataformat.avro.Message"/>
        </dataFormats>
        <route>
            <from uri="direct:in"/>
            <marshal ref="avro"/>
            <to uri="log:out"/>
        </route>
    </camelContext>

In the same manner you can umarshal using the avro data format.

18.3. Using Avro RPC in Camel

As mentioned above Avro also provides RPC support over multiple transports such as http and netty. Camel provides consumers and producers for these two transports.

avro:[transport]:[host]:[port][?options]

The supported transport values are currently http or netty.

Since 2.12 you can specify message name right in the URI:

avro:[transport]:[host]:[port][/messageName][?options]

For consumers this allows you to have multiple routes attached to the same socket. Dispatching to correct route will be done by the avro component automatically. Route with no messageName specified (if any) will be used as default.

When using camel producers for avro ipc, the "in" message body needs to contain the parameters of the operation specified in the avro protocol. The response will be added in the body of the "out" message.

In a similar manner when using camel avro consumers for avro ipc, the requests parameters will be placed inside the "in" message body of the created exchange and once the exchange is processed the body of the "out" message will be send as a response.

Note: By default consumer parameters are wrapped into array. If you’ve got only one parameter, since 2.12 you can use singleParameter URI option to receive it direcly in the "in" message body without array wrapping.

18.4. Avro RPC URI Options

The Avro component supports 2 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	To use a shared AvroConfiguration to configure options once		AvroConfiguration
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Avro endpoint is configured using URI syntax:

avro:transport:host:port/messageName

with the following path and query parameters:

18.4.1. Path Parameters (4 parameters):

Name	Description	Type
transport	Required Transport to use	AvroTransport
port	Required Port number to use	int
host	Required Hostname to use	String
messageName	The name of the message to send.	String

18.4.2. Query Parameters (10 parameters):

Name	Description	Default	Type
protocol (common)	Avro protocol to use		Protocol
protocolClassName (common)	Avro protocol to use defined by the FQN class name		String
protocolLocation (common)	Avro protocol location		String
reflectionProtocol (common)	If protocol object provided is reflection protocol. Should be used only with protocol parameter because for protocolClassName protocol type will be auto detected	false	boolean
singleParameter (common)	If true, consumer parameter won’t be wrapped into array. Will fail if protocol specifies more then 1 parameter for the message	false	boolean
uriAuthority (common)	Authority to use (username and password)		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

18.5. Avro RPC Headers

Name	Description
`CamelAvroMessageName`	The name of the message to send. In consumer overrides message name from URI (if any)

18.6. Examples

An example of using camel avro producers via http:

        <route>
            <from uri="direct:start"/>
            <to uri="avro:http:localhost:{{avroport}}?protocolClassName=org.apache.camel.avro.generated.KeyValueProtocol"/>
            <to uri="log:avro"/>
        </route>

In the example above you need to fill CamelAvroMessageName header. Since 2.12 you can use following syntax to call constant messages:

        <route>
            <from uri="direct:start"/>
            <to uri="avro:http:localhost:{{avroport}}/put?protocolClassName=org.apache.camel.avro.generated.KeyValueProtocol"/>
            <to uri="log:avro"/>
        </route>

An example of consuming messages using camel avro consumers via netty:

        <route>
            <from uri="avro:netty:localhost:{{avroport}}?protocolClassName=org.apache.camel.avro.generated.KeyValueProtocol"/>
            <choice>
                <when>
                    <el>${in.headers.CamelAvroMessageName == 'put'}</el>
                    <process ref="putProcessor"/>
                </when>
                <when>
                    <el>${in.headers.CamelAvroMessageName == 'get'}</el>
                    <process ref="getProcessor"/>
                </when>
            </choice>
        </route>

Since 2.12 you can set up two distinct routes to perform the same task:

        <route>
            <from uri="avro:netty:localhost:{{avroport}}/put?protocolClassName=org.apache.camel.avro.generated.KeyValueProtocol">
            <process ref="putProcessor"/>
        </route>
        <route>
            <from uri="avro:netty:localhost:{{avroport}}/get?protocolClassName=org.apache.camel.avro.generated.KeyValueProtocol&singleParameter=true"/>
            <process ref="getProcessor"/>
        </route>

In the example above, get takes only one parameter, so singleParameter is used and getProcessor will receive Value class directly in body, while putProcessor will receive an array of size 2 with String key and Value value filled as array contents.

Chapter 19. AWS CloudWatch Component

Available as of Camel version 2.11

The CW component allows messages to be sent to an Amazon CloudWatch metrics. The implementation of the Amazon API is provided by the http://aws.amazon.com/sdkforjava/[AWS SDK].

Prerequisites

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

19.1. URI Format

aws-cw://namespace[?options]

The metrics 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&…

19.2. URI Options

The AWS CloudWatch component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	The AWS CW default configuration		CwConfiguration
accessKey (producer)	Amazon AWS Access Key		String
secretKey (producer)	Amazon AWS Secret Key		String
region (producer)	The region in which CW client needs to work		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AWS CloudWatch endpoint is configured using URI syntax:

aws-cw:namespace

with the following path and query parameters:

19.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
namespace	Required The metric namespace		String

19.2.2. Query Parameters (11 parameters):

Name	Description	Default	Type
amazonCwClient (producer)	To use the AmazonCloudWatch as the client		AmazonCloudWatch
name (producer)	The metric name		String
proxyHost (producer)	To define a proxy host when instantiating the CW client		String
proxyPort (producer)	To define a proxy port when instantiating the CW client		Integer
region (producer)	The region in which CW client needs to work		String
timestamp (producer)	The metric timestamp		Date
unit (producer)	The metric unit		String
value (producer)	The metric value		Double
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
accessKey (security)	Amazon AWS Access Key		String
secretKey (security)	Amazon AWS Secret Key		String

Required CW component options

You have to provide the amazonCwClient in the Registry or your accessKey and secretKey to access the Amazon’s CloudWatch.

19.3. Usage

19.3.1. Message headers evaluated by the CW producer

Header	Type	Description
`CamelAwsCwMetricName`	`String`	The Amazon CW metric name.
`CamelAwsCwMetricValue`	`Double`	The Amazon CW metric value.
`CamelAwsCwMetricUnit`	`String`	The Amazon CW metric unit.
`CamelAwsCwMetricNamespace`	`String`	The Amazon CW metric namespace.
`CamelAwsCwMetricTimestamp`	`Date`	The Amazon CW metric timestamp.
`CamelAwsCwMetricDimensionName`	`String`	Camel 2.12: The Amazon CW metric dimension name.
`CamelAwsCwMetricDimensionValue`	`String`	Camel 2.12: The Amazon CW metric dimension value.
`CamelAwsCwMetricDimensions`	`Map<String, String>`	Camel 2.12: A map of dimension names and dimension values.

19.3.2. Advanced AmazonCloudWatch configuration

If you need more control over the AmazonCloudWatch instance configuration you can create your own instance and refer to it from the URI:

from("direct:start")
.to("aws-cw://namepsace?amazonCwClient=#client");

The #client refers to a AmazonCloudWatch in the Registry.

For example if your Camel Application is running behind a firewall:

AWSCredentials awsCredentials = new BasicAWSCredentials("myAccessKey", "mySecretKey");
ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setProxyHost("http://myProxyHost");
clientConfiguration.setProxyPort(8080);

AmazonCloudWatch client = new AmazonCloudWatchClient(awsCredentials, clientConfiguration);

registry.bind("client", client);

19.4. Dependencies

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

pom.xml

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

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

19.5. See Also

Configuring Camel
Component
Endpoint
Getting Started
AWS Component

Chapter 20. AWS DynamoDB Component

Available as of Camel version 2.10

The DynamoDB component supports storing and retrieving data from/to Amazon’s DynamoDB service.

Prerequisites

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

20.1. URI Format

aws-ddb://domainName[?options]

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

20.2. URI Options

The AWS DynamoDB component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	The AWS DDB default configuration		DdbConfiguration
accessKey (producer)	Amazon AWS Access Key		String
secretKey (producer)	Amazon AWS Secret Key		String
region (producer)	The region in which DDB client needs to work		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AWS DynamoDB endpoint is configured using URI syntax:

aws-ddb:tableName

with the following path and query parameters:

20.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
tableName	Required The name of the table currently worked with.		String

20.2.2. Query Parameters (13 parameters):

Name	Description	Default	Type
amazonDDBClient (producer)	To use the AmazonDynamoDB as the client		AmazonDynamoDB
consistentRead (producer)	Determines whether or not strong consistency should be enforced when data is read.	false	boolean
keyAttributeName (producer)	Attribute name when creating table		String
keyAttributeType (producer)	Attribute type when creating table		String
operation (producer)	What operation to perform	PutItem	DdbOperations
proxyHost (producer)	To define a proxy host when instantiating the DDB client		String
proxyPort (producer)	To define a proxy port when instantiating the DDB client		Integer
readCapacity (producer)	The provisioned throughput to reserve for reading resources from your table		Long
region (producer)	The region in which DDB client needs to work		String
writeCapacity (producer)	The provisioned throughput to reserved for writing resources to your table		Long
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
accessKey (security)	Amazon AWS Access Key		String
secretKey (security)	Amazon AWS Secret Key		String

Required DDB component options

You have to provide the amazonDDBClient in the Registry or your accessKey and secretKey to access the Amazon’s DynamoDB.

20.3. Usage

20.3.1. Message headers evaluated by the DDB producer

Header	Type	Description
`CamelAwsDdbBatchItems`	`Map<String, KeysAndAttributes>`	A map of the table name and corresponding items to get by primary key.
`CamelAwsDdbTableName`	`String`	Table Name for this operation.
`CamelAwsDdbKey`	`Key`	The primary key that uniquely identifies each item in a table. From Camel 2.16.0 the type of this header is Map<String, AttributeValue> and not Key
`CamelAwsDdbReturnValues`	`String`	Use this parameter if you want to get the attribute name-value pairs before or after they are modified(NONE, ALL_OLD, UPDATED_OLD, ALL_NEW, UPDATED_NEW).
`CamelAwsDdbUpdateCondition`	`Map<String, ExpectedAttributeValue>`	Designates an attribute for a conditional modification.
`CamelAwsDdbAttributeNames`	`Collection<String>`	If attribute names are not specified then all attributes will be returned.
`CamelAwsDdbConsistentRead`	`Boolean`	If set to true, then a consistent read is issued, otherwise eventually consistent is used.
`CamelAwsDdbIndexName`	`String`	If set will be used as Secondary Index for Query operation.
`CamelAwsDdbItem`	`Map<String, AttributeValue>`	A map of the attributes for the item, and must include the primary key values that define the item.
`CamelAwsDdbExactCount`	`Boolean`	If set to true, Amazon DynamoDB returns a total number of items that match the query parameters, instead of a list of the matching items and their attributes. From Camel 2.16.0 this header doesn’t exist anymore.
`CamelAwsDdbKeyConditions`	`Map<String, Condition>`	From Camel 2.16.0. This header specify the selection criteria for the query, and merge together the two old headers CamelAwsDdbHashKeyValue and CamelAwsDdbScanRangeKeyCondition
`CamelAwsDdbStartKey`	`Key`	Primary key of the item from which to continue an earlier query.
`CamelAwsDdbHashKeyValue`	`AttributeValue`	Value of the hash component of the composite primary key. From Camel 2.16.0 this header doesn’t exist anymore.
`CamelAwsDdbLimit`	`Integer`	The maximum number of items to return.
`CamelAwsDdbScanRangeKeyCondition`	`Condition`	A container for the attribute values and comparison operators to use for the query.From Camel 2.16.0 this header doesn’t exist anymore.
`CamelAwsDdbScanIndexForward`	`Boolean`	Specifies forward or backward traversal of the index.
`CamelAwsDdbScanFilter`	`Map<String, Condition>`	Evaluates the scan results and returns only the desired values.
`CamelAwsDdbUpdateValues`	`Map<String, AttributeValueUpdate>`	Map of attribute name to the new value and action for the update.

20.3.2. Message headers set during BatchGetItems operation

Header	Type	Description
`CamelAwsDdbBatchResponse`	`Map<String,BatchResponse>`	Table names and the respective item attributes from the tables.
`CamelAwsDdbUnprocessedKeys`	`Map<String,KeysAndAttributes>`	Contains a map of tables and their respective keys that were not processed with the current response.

20.3.3. Message headers set during DeleteItem operation

Header	Type	Description
`CamelAwsDdbAttributes`	`Map<String, AttributeValue>`	The list of attributes returned by the operation.

20.3.4. Message headers set during DeleteTable operation

Header	Type	Description
`CamelAwsDdbProvisionedThroughput`
`ProvisionedThroughputDescription`		The value of the ProvisionedThroughput property for this table
`CamelAwsDdbCreationDate`	`Date`	Creation DateTime of this table.
`CamelAwsDdbTableItemCount`	`Long`	Item count for this table.
`CamelAwsDdbKeySchema`	`KeySchema`	The KeySchema that identifies the primary key for this table. From Camel 2.16.0 the type of this header is List<KeySchemaElement> and not KeySchema
`CamelAwsDdbTableName`	`String`	The table name.
`CamelAwsDdbTableSize`	`Long`	The table size in bytes.
`CamelAwsDdbTableStatus`	`String`	The status of the table: CREATING, UPDATING, DELETING, ACTIVE

20.3.5. Message headers set during DescribeTable operation

Header	Type	Description
`CamelAwsDdbProvisionedThroughput`	{{ProvisionedThroughputDescription}}	The value of the ProvisionedThroughput property for this table
`CamelAwsDdbCreationDate`	`Date`	Creation DateTime of this table.
`CamelAwsDdbTableItemCount`	`Long`	Item count for this table.
`CamelAwsDdbKeySchema`	{{KeySchema}}	The KeySchema that identifies the primary key for this table. From Camel 2.16.0 the type of this header is List<KeySchemaElement> and not KeySchema
`CamelAwsDdbTableName`	`String`	The table name.
`CamelAwsDdbTableSize`	`Long`	The table size in bytes.
`CamelAwsDdbTableStatus`	`String`	The status of the table: CREATING, UPDATING, DELETING, ACTIVE
`CamelAwsDdbReadCapacity`	`Long`	ReadCapacityUnits property of this table.
`CamelAwsDdbWriteCapacity`	`Long`	WriteCapacityUnits property of this table.

20.3.6. Message headers set during GetItem operation

Header	Type	Description
`CamelAwsDdbAttributes`	`Map<String, AttributeValue>`	The list of attributes returned by the operation.

20.3.7. Message headers set during PutItem operation

Header	Type	Description
`CamelAwsDdbAttributes`	`Map<String, AttributeValue>`	The list of attributes returned by the operation.

20.3.8. Message headers set during Query operation

Header	Type	Description
`CamelAwsDdbItems`	`List<java.util.Map<String,AttributeValue>>`	The list of attributes returned by the operation.
`CamelAwsDdbLastEvaluatedKey`	`Key`	Primary key of the item where the query operation stopped, inclusive of the previous result set.
`CamelAwsDdbConsumedCapacity`	`Double`	The number of Capacity Units of the provisioned throughput of the table consumed during the operation.
`CamelAwsDdbCount`	`Integer`	Number of items in the response.

20.3.9. Message headers set during Scan operation

Header	Type	Description
`CamelAwsDdbItems`	`List<java.util.Map<String,AttributeValue>>`	The list of attributes returned by the operation.
`CamelAwsDdbLastEvaluatedKey`	`Key`	Primary key of the item where the query operation stopped, inclusive of the previous result set.
`CamelAwsDdbConsumedCapacity`	`Double`	The number of Capacity Units of the provisioned throughput of the table consumed during the operation.
`CamelAwsDdbCount`	`Integer`	Number of items in the response.
`CamelAwsDdbScannedCount`	`Integer`	Number of items in the complete scan before any filters are applied.

20.3.10. Message headers set during UpdateItem operation

Header	Type	Description
`CamelAwsDdbAttributes`	`Map<String, AttributeValue>`	The list of attributes returned by the operation.

20.3.11. Advanced AmazonDynamoDB configuration

If you need more control over the AmazonDynamoDB instance configuration you can create your own instance and refer to it from the URI:

from("direct:start")
.to("aws-ddb://domainName?amazonDDBClient=#client");

The #client refers to a AmazonDynamoDB in the Registry.

For example if your Camel Application is running behind a firewall:

AWSCredentials awsCredentials = new BasicAWSCredentials("myAccessKey", "mySecretKey");
ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setProxyHost("http://myProxyHost");
clientConfiguration.setProxyPort(8080);

AmazonDynamoDB client = new AmazonDynamoDBClient(awsCredentials, clientConfiguration);

registry.bind("client", client);

20.4. Dependencies

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

pom.xml

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

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

20.5. See Also

Configuring Camel
Component
Endpoint
Getting Started
AWS Component

Chapter 21. AWS DynamoDB Streams Component

Available as of Camel version 2.17

The DynamoDB Stream component supports receiving messages from Amazon DynamoDB Stream service.

Prerequisites

You must have a valid Amazon Web Services developer account, and be signed up to use Amazon DynamoDB Streams. More information are available at http://aws.amazon.com/dynamodb/[AWS DynamoDB]

21.1. URI Format

aws-ddbstream://table-name[?options]

The stream needs to be created prior to it being used.
You can append query options to the URI in the following format, ?options=value&option2=value&…

21.2. URI Options

The AWS DynamoDB Streams component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	The AWS DDB stream default configuration		DdbStreamConfiguration
accessKey (consumer)	Amazon AWS Access Key		String
secretKey (consumer)	Amazon AWS Secret Key		String
region (consumer)	Amazon AWS Region		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AWS DynamoDB Streams endpoint is configured using URI syntax:

aws-ddbstream:tableName

with the following path and query parameters:

21.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
tableName	Required Name of the dynamodb table		String

21.2.2. Query Parameters (28 parameters):

Name	Description	Default	Type
amazonDynamoDbStreams Client (consumer)	Amazon DynamoDB client to use for all requests for this endpoint		AmazonDynamoDBStreams
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
iteratorType (consumer)	Defines where in the DynaboDB stream to start getting records. Note that using TRIM_HORIZON can cause a significant delay before the stream has caught up to real-time. if AT,AFTER_SEQUENCE_NUMBER are used, then a sequenceNumberProvider MUST be supplied.	LATEST	ShardIteratorType
maxResultsPerRequest (consumer)	Maximum number of records that will be fetched in each poll		int
proxyHost (consumer)	To define a proxy host when instantiating the DDBStreams client		String
proxyPort (consumer)	To define a proxy port when instantiating the DDBStreams client		Integer
region (consumer)	The region in which DDBStreams client needs to work		String
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
sequenceNumberProvider (consumer)	Provider for the sequence number when using one of the two ShardIteratorType.AT,AFTER_SEQUENCE_NUMBER iterator types. Can be a registry reference or a literal sequence number.		SequenceNumberProvider
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean
accessKey (security)	Amazon AWS Access Key		String
secretKey (security)	Amazon AWS Secret Key		String

Required DynampDBStream component options

You have to provide the amazonDynamoDbStreamsClient in the Registry with proxies and relevant credentials configured.

21.3. Sequence Numbers

You can provide a literal string as the sequence number or provide a bean in the registry. An example of using the bean would be to save your current position in the change feed and restore it on Camel startup.

It is an error to provide a sequence number that is greater than the largest sequence number in the describe-streams result, as this will lead to the AWS call returning an HTTP 400.

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

21.5. Usage

21.5.1. AmazonDynamoDBStreamsClient configuration

You will need to create an instance of AmazonDynamoDBStreamsClient and bind it to the registry

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

Region region = Region.getRegion(Regions.fromName(region));
region.createClient(AmazonDynamoDBStreamsClient.class, null, clientConfiguration);
// the 'null' here is the AWSCredentialsProvider which defaults to an instance of DefaultAWSCredentialsProviderChain

registry.bind("kinesisClient", client);

21.5.2. Providing AWS Credentials

It is recommended that the credentials are obtained by using the DefaultAWSCredentialsProviderChain that is the default when creating a new ClientConfiguration instance, however, a different http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWSCredentialsProvider.html[AWSCredentialsProvider] can be specified when calling createClient(…).

21.6. Coping with Downtime

21.6.1. AWS DynamoDB Streams outage of less than 24 hours

The consumer will resume from the last seen sequence number (as implemented for https://issues.apache.org/jira/browse/CAMEL-9515[CAMEL-9515]), so you should receive a flood of events in quick succession, as long as the outage did not also include DynamoDB itself.

21.6.2. AWS DynamoDB Streams outage of more than 24 hours

Given that AWS only retain 24 hours worth of changes, you will have missed change events no matter what mitigations are in place.

21.7. Dependencies

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

pom.xml

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

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

21.8. See Also

Configuring Camel
Component
Endpoint
Getting Started
AWS Component
+

Chapter 22. AWS EC2 Component

Available as of Camel version 2.16

The EC2 component supports create, run, start, stop and terminate AWS EC2 instances.

Prerequisites

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

22.1. URI Format

aws-ec2://label[?options]

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

22.2. URI Options

The AWS EC2 component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	The AWS EC2 default configuration		EC2Configuration
region (producer)	The region in which EC2 client needs to work		String
accessKey (producer)	Amazon AWS Access Key		String
secretKey (producer)	Amazon AWS Secret Key		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AWS EC2 endpoint is configured using URI syntax:

aws-ec2:label

with the following path and query parameters:

22.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
label	Required Logical name		String

22.2.2. Query Parameters (8 parameters):

Name	Description	Default	Type
accessKey (producer)	Amazon AWS Access Key		String
amazonEc2Client (producer)	To use a existing configured AmazonEC2Client as client		AmazonEC2Client
operation (producer)	Required The operation to perform. It can be createAndRunInstances, startInstances, stopInstances, terminateInstances, describeInstances, describeInstancesStatus, rebootInstances, monitorInstances, unmonitorInstances, createTags or deleteTags		EC2Operations
proxyHost (producer)	To define a proxy host when instantiating the EC2 client		String
proxyPort (producer)	To define a proxy port when instantiating the EC2 client		Integer
region (producer)	The region in which EC2 client needs to work		String
secretKey (producer)	Amazon AWS Secret Key		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

Required EC2 component options

You have to provide the amazonEc2Client in the Registry or your accessKey and secretKey to access the Amazon EC2 service.

22.3. Usage

22.3.1. Message headers evaluated by the EC2 producer

Header	Type	Description
`CamelAwsEC2ImageId`	`String`	An image ID of the AWS marketplace
`CamelAwsEC2InstanceType`	com.amazonaws.services.ec2.model.InstanceType	The instance type we want to create and run
`CamelAwsEC2Operation`	`String`	The operation we want to perform
`CamelAwsEC2InstanceMinCount`	`Int`	The mininum number of instances we want to run.
`CamelAwsEC2InstanceMaxCount`	`Int`	The maximum number of instances we want to run.
`CamelAwsEC2InstanceMonitoring`	Boolean	Define if we want the running instances to be monitored
`CamelAwsEC2InstanceEbsOptimized`	`Boolean`	Define if the creating instance is optimized for EBS I/O.
`CamelAwsEC2InstanceSecurityGroups`	Collection	The security groups to associate to the instances
`CamelAwsEC2InstancesIds`	`Collection`	A collection of instances IDS to execute start, stop, describe and terminate operations on.
`CamelAwsEC2InstancesTags`	`Collection`	A collection of tags to add or remove from EC2 resources

Dependencies

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

pom.xml

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

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

22.4. See Also

Configuring Camel
Component
Endpoint
Getting Started
AWS Component

Chapter 23. AWS Kinesis Component

Available as of Camel version 2.17

The Kinesis component supports receiving messages from and sending messages to Amazon Kinesis service.

Prerequisites

You must have a valid Amazon Web Services developer account, and be signed up to use Amazon Kinesis. More information are available at http://aws.amazon.com/kinesis/[AWS Kinesis]

23.1. URI Format

aws-kinesis://stream-name[?options]

The stream needs to be created prior to it being used.
You can append query options to the URI in the following format, ?options=value&option2=value&…

23.2. URI Options

The AWS Kinesis component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	The AWS S3 default configuration		KinesisConfiguration
accessKey (common)	Amazon AWS Access Key		String
secretKey (common)	Amazon AWS Secret Key		String
region (common)	Amazon AWS Region		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AWS Kinesis endpoint is configured using URI syntax:

aws-kinesis:streamName

with the following path and query parameters:

23.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
streamName	Required Name of the stream		String

23.2.2. Query Parameters (30 parameters):

Name	Description	Default	Type
amazonKinesisClient (common)	Amazon Kinesis client to use for all requests for this endpoint		AmazonKinesis
proxyHost (common)	To define a proxy host when instantiating the DDBStreams client		String
proxyPort (common)	To define a proxy port when instantiating the DDBStreams client		Integer
region (common)	The region in which Kinesis client needs to work		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
iteratorType (consumer)	Defines where in the Kinesis stream to start getting records	TRIM_HORIZON	ShardIteratorType
maxResultsPerRequest (consumer)	Maximum number of records that will be fetched in each poll	1	int
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
sequenceNumber (consumer)	The sequence number to start polling from. Required if iteratorType is set to AFTER_SEQUENCE_NUMBER or AT_SEQUENCE_NUMBER		String
shardClosed (consumer)	Define what will be the behavior in case of shard closed. Possible value are ignore, silent and fail.In case of ignore a message will be logged and the consumer will restart from the beginning,in case of silent there will be no logging and the consumer will start from the beginning,in case of fail a ReachedClosedStateException will be raised	ignore	KinesisShardClosed StrategyEnum
shardId (consumer)	Defines which shardId in the Kinesis stream to get records from		String
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean
accessKey (security)	Amazon AWS Access Key		String
secretKey (security)	Amazon AWS Secret Key		String

Required Kinesis component options

You have to provide the amazonKinesisClient in the Registry with proxies and relevant credentials configured.

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

23.4. Usage

23.4.1. Message headers set by the Kinesis consumer

Header	Type	Description
`CamelAwsKinesisSequenceNumber`	`String`	The sequence number of the record. This is represented as a String as it size is not defined by the API. If it is to be used as a numerical type then use
`CamelAwsKinesisApproximateArrivalTimestamp`	`String`	The time AWS assigned as the arrival time of the record.
`CamelAwsKinesisPartitionKey`	`String`	Identifies which shard in the stream the data record is assigned to.

23.4.2. AmazonKinesis configuration

You will need to create an instance of AmazonKinesisClient and bind it to the registry

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

Region region = Region.getRegion(Regions.fromName(region));
region.createClient(AmazonKinesisClient.class, null, clientConfiguration);
// the 'null' here is the AWSCredentialsProvider which defaults to an instance of DefaultAWSCredentialsProviderChain

registry.bind("kinesisClient", client);

You then have to reference the AmazonKinesisClient in the amazonKinesisClient URI option.

from("aws-kinesis://mykinesisstream?amazonKinesisClient=#kinesisClient")
  .to("log:out?showAll=true");

23.4.3. Providing AWS Credentials

It is recommended that the credentials are obtained by using the DefaultAWSCredentialsProviderChain that is the default when creating a new ClientConfiguration instance, however, a different http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWSCredentialsProvider.html[AWSCredentialsProvider] can be specified when calling createClient(…).

23.4.4. Message headers used by the Kinesis producer to write to Kinesis. The producer expects that the message body is a `ByteBuffer`.

Header	Type	Description
`CamelAwsKinesisPartitionKey`	`String`	The PartitionKey to pass to Kinesis to store this record.
`CamelAwsKinesisSequenceNumber`	`String`	Optional paramter to indicate the sequence number of this record.

23.4.5. Message headers set by the Kinesis producer on successful storage of a Record

Header	Type	Description
`CamelAwsKinesisSequenceNumber`	`String`	The sequence number of the record, as defined in Response Syntax
`CamelAwsKinesisShardId`	`String`	The shard ID of where the Record was stored

23.5. Dependencies

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

pom.xml

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

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

23.6. See Also

Configuring Camel
Component
Endpoint
Getting Started
AWS Component

Chapter 24. AWS Kinesis Firehose Component

Available as of Camel version 2.19

The Kinesis Firehose component supports sending messages to Amazon Kinesis Firehose service.

Prerequisites

You must have a valid Amazon Web Services developer account, and be signed up to use Amazon Kinesis Firehose. More information are available at https://aws.amazon.com/kinesis/firehose/[AWS Kinesis Firehose]

24.1. URI Format

aws-kinesis-firehose://delivery-stream-name[?options]

The stream needs to be created prior to it being used.
You can append query options to the URI in the following format, ?options=value&option2=value&…

24.2. URI Options

The AWS Kinesis Firehose component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	The AWS Kinesis Firehose default configuration		KinesisFirehose Configuration
accessKey (producer)	Amazon AWS Access Key		String
secretKey (producer)	Amazon AWS Secret Key		String
region (producer)	Amazon AWS Region		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AWS Kinesis Firehose endpoint is configured using URI syntax:

aws-kinesis-firehose:streamName

with the following path and query parameters:

24.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
streamName	Required Name of the stream		String

24.2.2. Query Parameters (7 parameters):

Name	Description	Default	Type
amazonKinesisFirehoseClient (producer)	Amazon Kinesis Firehose client to use for all requests for this endpoint		AmazonKinesisFirehose
proxyHost (producer)	To define a proxy host when instantiating the DDBStreams client		String
proxyPort (producer)	To define a proxy port when instantiating the DDBStreams client		Integer
region (producer)	The region in which Kinesis client needs to work		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
accessKey (security)	Amazon AWS Access Key		String
secretKey (security)	Amazon AWS Secret Key		String

Required Kinesis Firehose component options

You have to provide the amazonKinesisClient in the Registry with proxies and relevant credentials configured.

24.3. Usage

24.3.1. Amazon Kinesis Firehose configuration

You will need to create an instance of AmazonKinesisClient and bind it to the registry

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

Region region = Region.getRegion(Regions.fromName(region));
region.createClient(AmazonKinesisClient.class, null, clientConfiguration);
// the 'null' here is the AWSCredentialsProvider which defaults to an instance of DefaultAWSCredentialsProviderChain

registry.bind("kinesisFirehoseClient", client);

You then have to reference the AmazonKinesisFirehoseClient in the amazonKinesisFirehoseClient URI option.

from("aws-kinesis-firehose://mykinesisdeliverystream?amazonKinesisFirehoseClient=#kinesisClient")
  .to("log:out?showAll=true");

24.3.2. Providing AWS Credentials

It is recommended that the credentials are obtained by using the DefaultAWSCredentialsProviderChain that is the default when creating a new ClientConfiguration instance, however, a different http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWSCredentialsProvider.html[AWSCredentialsProvider] can be specified when calling createClient(…).

24.3.3. Message headers set by the Kinesis producer on successful storage of a Record

Header	Type	Description
`CamelAwsKinesisFirehoseRecordId`	`String`	The record ID, as defined in Response Syntax

24.4. Dependencies

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

pom.xml

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

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

24.5. See Also

Configuring Camel
Component
Endpoint
Getting Started
AWS Component

Chapter 25. AWS KMS Component

Available as of Camel version 2.21

The KMS component supports create, run, start, stop and terminate AWS KMS instances.

Prerequisites

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

25.1. URI Format

aws-kms://label[?options]

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

25.2. URI Options

The AWS KMS component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	The AWS MQ default configuration		KMSConfiguration
accessKey (producer)	Amazon AWS Access Key		String
secretKey (producer)	Amazon AWS Secret Key		String
region (producer)	The region in which MQ client needs to work		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AWS KMS endpoint is configured using URI syntax:

aws-kms:label

with the following path and query parameters:

25.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
label	Required Logical name		String

25.2.2. Query Parameters (8 parameters):

Name	Description	Default	Type
accessKey (producer)	Amazon AWS Access Key		String
kmsClient (producer)	To use a existing configured AWS KMS as client		AWSKMS
operation (producer)	Required The operation to perform		KMSOperations
proxyHost (producer)	To define a proxy host when instantiating the KMS client		String
proxyPort (producer)	To define a proxy port when instantiating the KMS client		Integer
region (producer)	The region in which KMS client needs to work		String
secretKey (producer)	Amazon AWS Secret Key		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

Required KMS component options

You have to provide the amazonKmsClient in the Registry or your accessKey and secretKey to access the Amazon KMS service.

25.3. Usage

25.3.1. Message headers evaluated by the MQ producer

Header	Type	Description
`CamelAwsKMSLimit`	`Integer`	The limit number of keys to return while performing a listKeys operation
`CamelAwsKMSOperation`	`String`	The operation we want to perform
`CamelAwsKMSDescription`	`String`	A key description to use while performing a createKey operation
`CamelAwsKMSKeyId`	`String`	The key Id

Dependencies

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

pom.xml

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

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

25.4. See Also

Configuring Camel
Component
Endpoint
Getting Started
AWS Component

Chapter 26. AWS Lambda Component

Available as of Camel version 2.20

The Lambda component supports create, get, list, delete and invoke AWS Lambda functions.

Prerequisites

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

When creating a Lambda function, you need to specify a IAM role which has at least the AWSLambdaBasicExecuteRole policy attached.

Warning

Lambda is regional service. Unlike S3 bucket, Lambda function created in a given region is not available on other regions.

26.1. URI Format

aws-lambda://functionName[?options]

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

26.2. URI Options

The AWS Lambda component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	The AWS Lambda default configuration		LambdaConfiguration
accessKey (producer)	Amazon AWS Access Key		String
secretKey (producer)	Amazon AWS Secret Key		String
region (producer)	Amazon AWS Region		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AWS Lambda endpoint is configured using URI syntax:

aws-lambda:function

with the following path and query parameters:

26.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
function	Required Name of the Lambda function.		String

26.2.2. Query Parameters (8 parameters):

Name	Description	Default	Type
operation (producer)	Required The operation to perform. It can be listFunctions, getFunction, createFunction, deleteFunction or invokeFunction		LambdaOperations
region (producer)	Amazon AWS Region		String
awsLambdaClient (advanced)	To use a existing configured AwsLambdaClient as client		AWSLambda
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
proxyHost (proxy)	To define a proxy host when instantiating the Lambda client		String
proxyPort (proxy)	To define a proxy port when instantiating the Lambda client		Integer
accessKey (security)	Amazon AWS Access Key		String
secretKey (security)	Amazon AWS Secret Key		String

Required Lambda component options

You have to provide the awsLambdaClient in the Registry or your accessKey and secretKey to access the Amazon Lambda service.

26.3. Usage

26.3.1. Message headers evaluated by the Lambda producer

Operation	Header	Type	Description	Required
All	`CamelAwsLambdaOperation`	`String`	The operation we want to perform. Override operation passed as query parameter	Yes
createFunction	`CamelAwsLambdaS3Bucket`	`String`	Amazon S3 bucket name where the .zip file containing your deployment package is stored. This bucket must reside in the same AWS region where you are creating the Lambda function.	No
createFunction	`CamelAwsLambdaS3Key`	`String`	The Amazon S3 object (the deployment package) key name you want to upload.	No
createFunction	`CamelAwsLambdaS3ObjectVersion`	String	The Amazon S3 object (the deployment package) version you want to upload.	No
createFunction	`CamelAwsLambdaZipFile`	`String`	The local path of the zip file (the deployment package). Content of zip file can also be put in Message body.	No
createFunction	`CamelAwsLambdaRole`	`String`	The Amazon Resource Name (ARN) of the IAM role that Lambda assumes when it executes your function to access any other Amazon Web Services (AWS) resources.	Yes
createFunction	`CamelAwsLambdaRuntime`	String	The runtime environment for the Lambda function you are uploading. (nodejs, nodejs4.3, nodejs6.10, java8, python2.7, python3.6, dotnetcore1.0, odejs4.3-edge)	Yes
createFunction	`CamelAwsLambdaHandler`	`String`	The function within your code that Lambda calls to begin execution. For Node.js, it is the module-name.export value in your function. For Java, it can be package.class-name::handler or package.class-name.	Yes
createFunction	`CamelAwsLambdaDescription`	`String`	The user-provided description.	No
createFunction	`CamelAwsLambdaTargetArn`	`String`	The parent object that contains the target ARN (Amazon Resource Name) of an Amazon SQS queue or Amazon SNS topic.	No
createFunction	`CamelAwsLambdaMemorySize`	`Integer`	The memory size, in MB, you configured for the function. Must be a multiple of 64 MB.	No
createFunction	`CamelAwsLambdaKMSKeyArn`	`String`	The Amazon Resource Name (ARN) of the KMS key used to encrypt your function’s environment variables. If not provided, AWS Lambda will use a default service key.	No
createFunction	`CamelAwsLambdaPublish`	`Boolean`	This boolean parameter can be used to request AWS Lambda to create the Lambda function and publish a version as an atomic operation.	No
createFunction	`CamelAwsLambdaTimeout`	`Integer`	The function execution time at which Lambda should terminate the function. The default is 3 seconds.	No
createFunction	`CamelAwsLambdaTracingConfig`	`String`	Your function’s tracing settings (Active or PassThrough).	No
createFunction	`CamelAwsLambdaEnvironmentVariables`	`Map<String, String>`	The key-value pairs that represent your environment’s configuration settings.	No
createFunction	`CamelAwsLambdaEnvironmentTags`	`Map<String, String>`	The list of tags (key-value pairs) assigned to the new function.	No
createFunction	`CamelAwsLambdaSecurityGroupIds`	`List<String>`	If your Lambda function accesses resources in a VPC, a list of one or more security groups IDs in your VPC.	No
createFunction	`CamelAwsLambdaSubnetIds`	`List<String>`	If your Lambda function accesses resources in a VPC, a list of one or more subnet IDs in your VPC.	No

Dependencies

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

pom.xml

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

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

26.4. See Also

Configuring Camel
Component
Endpoint
Getting Started
AWS Component

Chapter 27. AWS MQ Component

Available as of Camel version 2.21

The EC2 component supports create, run, start, stop and terminate AWS MQ instances.

Prerequisites

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

27.1. URI Format

aws-mq://label[?options]

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

27.2. URI Options

The AWS MQ component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	The AWS MQ default configuration		MQConfiguration
accessKey (producer)	Amazon AWS Access Key		String
secretKey (producer)	Amazon AWS Secret Key		String
region (producer)	The region in which MQ client needs to work		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AWS MQ endpoint is configured using URI syntax:

aws-mq:label

with the following path and query parameters:

27.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
label	Required Logical name		String

27.2.2. Query Parameters (8 parameters):

Name	Description	Default	Type
accessKey (producer)	Amazon AWS Access Key		String
amazonMqClient (producer)	To use a existing configured AmazonMQClient as client		AmazonMQ
operation (producer)	Required The operation to perform. It can be listBrokers,createBroker,deleteBroker		MQOperations
proxyHost (producer)	To define a proxy host when instantiating the MQ client		String
proxyPort (producer)	To define a proxy port when instantiating the MQ client		Integer
region (producer)	The region in which MQ client needs to work		String
secretKey (producer)	Amazon AWS Secret Key		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

Required EC2 component options

You have to provide the amazonEc2Client in the Registry or your accessKey and secretKey to access the Amazon EC2 service.

27.3. Usage

27.3.1. Message headers evaluated by the MQ producer

Header	Type	Description
`CamelAwsMQMaxResults`	`String`	The number of results that must be retrieved from listBrokers operation
`CamelAwsMQBrokerName`	`String`	The broker name
`CamelAwsMQOperation`	`String`	The operation we want to perform
`CamelAwsMQBrokerId`	`String`	The broker id
`CamelAwsMQBrokerDeploymentMode`	`String`	The deployment mode for the broker in the createBroker operation

Dependencies

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

pom.xml

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

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

27.4. See Also

Configuring Camel
Component
Endpoint
Getting Started
AWS Component

Chapter 28. AWS S3 Storage Service Component

Available as of Camel version 2.8

The S3 component supports storing and retrieving objetcs from/to Amazon’s S3 service.

Prerequisites

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

28.1. URI Format

aws-s3://bucketNameOrArn[?options]

The bucket will be created if it don’t already exists.
You can append query options to the URI in the following format, ?options=value&option2=value&…

For example in order to read file hello.txt from bucket helloBucket, use the following snippet:

from("aws-s3:helloBucket?accessKey=yourAccessKey&secretKey=yourSecretKey&prefix=hello.txt")
  .to("file:/var/downloaded");

28.2. URI Options

The AWS S3 Storage Service component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	The AWS S3 default configuration		S3Configuration
accessKey (common)	Amazon AWS Access Key		String
secretKey (common)	Amazon AWS Secret Key		String
region (common)	The region where the bucket is located. This option is used in the com.amazonaws.services.s3.model.CreateBucketRequest.		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AWS S3 Storage Service endpoint is configured using URI syntax:

aws-s3:bucketNameOrArn

with the following path and query parameters:

28.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
bucketNameOrArn	Required Bucket name or ARN		String

28.2.2. Query Parameters (50 parameters):

Name	Description	Default	Type
amazonS3Client (common)	Reference to a com.amazonaws.services.sqs.AmazonS3 in the link:registry.htmlRegistry.		AmazonS3
pathStyleAccess (common)	Whether or not the S3 client should use path style access	false	boolean
policy (common)	The policy for this queue to set in the com.amazonaws.services.s3.AmazonS3setBucketPolicy() method.		String
proxyHost (common)	To define a proxy host when instantiating the SQS client		String
proxyPort (common)	Specify a proxy port to be used inside the client definition.		Integer
region (common)	The region in which S3 client needs to work		String
useIAMCredentials (common)	Set whether the S3 client should expect to load credentials on an EC2 instance or to expect static credentials to be passed in.	false	boolean
encryptionMaterials (common)	The encryption materials to use in case of Symmetric/Asymmetric client usage		EncryptionMaterials
useEncryption (common)	Define if encryption must be used or not	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
deleteAfterRead (consumer)	Delete objects from S3 after they have been retrieved. The delete is only performed if the Exchange is committed. If a rollback occurs, the object is not deleted. If this option is false, then the same objects will be retrieve over and over again on the polls. Therefore you need to use the Idempotent Consumer EIP in the route to filter out duplicates. You can filter using the link S3ConstantsBUCKET_NAME and link S3ConstantsKEY headers, or only the link S3ConstantsKEY header.	true	boolean
fileName (consumer)	To get the object from the bucket with the given file name		String
includeBody (consumer)	If it is true, the exchange body will be set to a stream to the contents of the file. If false, the headers will be set with the S3 object metadata, but the body will be null. This option is strongly related to autocloseBody option. In case of setting includeBody to true and autocloseBody to false, it will be up to the caller to close the S3Object stream. Setting autocloseBody to true, will close the S3Object stream automatically.	true	boolean
maxConnections (consumer)	Set the maxConnections parameter in the S3 client configuration	60	int
maxMessagesPerPoll (consumer)	Gets the maximum number of messages as a limit to poll at each polling. Is default unlimited, but use 0 or negative number to disable it as unlimited.	10	int
prefix (consumer)	The prefix which is used in the com.amazonaws.services.s3.model.ListObjectsRequest to only consume objects we are interested in.		String
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
autocloseBody (consumer)	If this option is true and includeBody is true, then the S3Object.close() method will be called on exchange completion. This option is strongly related to includeBody option. In case of setting includeBody to true and autocloseBody to false, it will be up to the caller to close the S3Object stream. Setting autocloseBody to true, will close the S3Object stream automatically.	true	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
deleteAfterWrite (producer)	Delete file object after the S3 file has been uploaded	false	boolean
multiPartUpload (producer)	If it is true, camel will upload the file with multi part format, the part size is decided by the option of partSize	false	boolean
operation (producer)	The operation to do in case the user don’t want to do only an upload		S3Operations
partSize (producer)	Setup the partSize which is used in multi part upload, the default size is 25M.	26214400	long
serverSideEncryption (producer)	Sets the server-side encryption algorithm when encrypting the object using AWS-managed keys. For example use AES256.		String
storageClass (producer)	The storage class to set in the com.amazonaws.services.s3.model.PutObjectRequest request.		String
awsKMSKeyId (producer)	Define the id of KMS key to use in case KMS is enabled		String
useAwsKMS (producer)	Define if KMS must be used or not	false	boolean
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
accelerateModeEnabled ( advanced)	Define if Accelerate Mode enabled is true or false	false	boolean
chunkedEncodingDisabled ( advanced)	Define if disabled Chunked Encoding is true or false	false	boolean
dualstackEnabled ( advanced)	Define if Dualstack enabled is true or false	false	boolean
forceGlobalBucketAccess Enabled ( advanced)	Define if Force Global Bucket Access enabled is true or false	false	boolean
payloadSigningEnabled ( advanced)	Define if Payload Signing enabled is true or false	false	boolean
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean
accessKey (security)	Amazon AWS Access Key		String
secretKey (security)	Amazon AWS Secret Key		String

Required S3 component options

You have to provide the amazonS3Client in the Registry or your accessKey and secretKey to access the Amazon’s S3.

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

28.4. Usage

28.4.1. Message headers evaluated by the S3 producer

Header	Type	Description
`CamelAwsS3BucketName`	`String`	The bucket Name which this object will be stored or which will be used for the current operation
`CamelAwsS3BucketDestinationName`	`String`	Camel 2.18: The bucket Destination Name which will be used for the current operation
`CamelAwsS3ContentLength`	`Long`	The content length of this object.
`CamelAwsS3ContentType`	`String`	The content type of this object.
`CamelAwsS3ContentControl`	`String`	Camel 2.8.2: The content control of this object.
`CamelAwsS3ContentDisposition`	`String`	Camel 2.8.2: The content disposition of this object.
`CamelAwsS3ContentEncoding`	`String`	Camel 2.8.2: The content encoding of this object.
`CamelAwsS3ContentMD5`	`String`	Camel 2.8.2: The md5 checksum of this object.
`CamelAwsS3DestinationKey`	`String`	Camel 2.18:The Destination key which will be used for the current operation
`CamelAwsS3Key`	`String`	The key under which this object will be stored or which will be used for the current operation
`CamelAwsS3LastModified`	`java.util.Date`	Camel 2.8.2: The last modified timestamp of this object.
`CamelAwsS3Operation`	`String`	Camel 2.18: The operation to perform. Permitted values are copyObject, listBuckets, deleteBucket, downloadLink
`CamelAwsS3StorageClass`	`String`	Camel 2.8.4: The storage class of this object.
`CamelAwsS3CannedAcl`	`String`	Camel 2.11.0: The canned acl that will be applied to the object. see `com.amazonaws.services.s3.model.CannedAccessControlList` for allowed values.
`CamelAwsS3Acl`	`com.amazonaws.services.s3.model.AccessControlList`	Camel 2.11.0: a well constructed Amazon S3 Access Control List object. see `com.amazonaws.services.s3.model.AccessControlList` for more details
`CamelAwsS3Headers`	`Map<String,String>`	Camel 2.15.0: support to get or set custom objectMetadata headers.
`CamelAwsS3ServerSideEncryption`	String	Camel 2.16: Sets the server-side encryption algorithm when encrypting the object using AWS-managed keys. For example use AES256.
`CamelAwsS3VersionId`	`String`	The version Id of the object to be stored or returned from the current operation

28.4.2. Message headers set by the S3 producer

Header	Type	Description
`CamelAwsS3ETag`	`String`	The ETag value for the newly uploaded object.
`CamelAwsS3VersionId`	`String`	The optional version ID of the newly uploaded object.
`CamelAwsS3DownloadLinkExpiration`	`String`	The expiration (millis) of URL download link. The link will be stored into CamelAwsS3DownloadLink response header.

28.4.3. Message headers set by the S3 consumer

Header	Type	Description
`CamelAwsS3Key`	`String`	The key under which this object is stored.
`CamelAwsS3BucketName`	`String`	The name of the bucket in which this object is contained.
`CamelAwsS3ETag`	`String`	The hex encoded 128-bit MD5 digest of the associated object according to RFC 1864. This data is used as an integrity check to verify that the data received by the caller is the same data that was sent by Amazon S3.
`CamelAwsS3LastModified`	`Date`	The value of the Last-Modified header, indicating the date and time at which Amazon S3 last recorded a modification to the associated object.
`CamelAwsS3VersionId`	`String`	The version ID of the associated Amazon S3 object if available. Version IDs are only assigned to objects when an object is uploaded to an Amazon S3 bucket that has object versioning enabled.
`CamelAwsS3ContentType`	`String`	The Content-Type HTTP header, which indicates the type of content stored in the associated object. The value of this header is a standard MIME type.
`CamelAwsS3ContentMD5`	`String`	The base64 encoded 128-bit MD5 digest of the associated object (content - not including headers) according to RFC 1864. This data is used as a message integrity check to verify that the data received by Amazon S3 is the same data that the caller sent.
`CamelAwsS3ContentLength`	`Long`	The Content-Length HTTP header indicating the size of the associated object in bytes.
`CamelAwsS3ContentEncoding`	`String`	The optional Content-Encoding HTTP header specifying what content encodings have been applied to the object and what decoding mechanisms must be applied in order to obtain the media-type referenced by the Content-Type field.
`CamelAwsS3ContentDisposition`	`String`	The optional Content-Disposition HTTP header, which specifies presentational information such as the recommended filename for the object to be saved as.
`CamelAwsS3ContentControl`	`String`	The optional Cache-Control HTTP header which allows the user to specify caching behavior along the HTTP request/reply chain.
`CamelAwsS3ServerSideEncryption`	String	Camel 2.16: The server-side encryption algorithm when encrypting the object using AWS-managed keys.

28.4.4. Advanced AmazonS3 configuration

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

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

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

AmazonS3 client = new AmazonS3Client(awsCredentials, clientConfiguration);

registry.bind("client", client);

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

from("aws-s3://MyBucket?amazonS3Client=#client&delay=5000&maxMessagesPerPoll=5")
.to("mock:result");

28.4.5. Use KMS with the S3 component

To use AWS KMS to encrypt/decrypt data by using AWS infrastructure you can use the options introduced in 2.21.x like in the following example

from("file:tmp/test?fileName=test.txt")
     .setHeader(S3Constants.KEY, constant("testFile"))
     .to("aws-s3://mybucket?amazonS3Client=#client&useAwsKMS=true&awsKMSKeyId=3f0637ad-296a-3dfe-a796-e60654fb128c");

In this way you’ll ask to S3, to use the KMS key 3f0637ad-296a-3dfe-a796-e60654fb128c, to encrypt the file test.txt. When you’ll ask to download this file, the decryption will be done directly before the download.

28.4.6. Use "useIAMCredentials" with the s3 component

To use AWS IAM credentials, you must first verify that the EC2 in which you are launching the Camel application on has an IAM role associated with it containing the appropriate policies attached to run effectively. Keep in mind that this feature should only be set to "true" on remote instances. To clarify even further, you must still use static credentials locally since IAM is an AWS specific component, but AWS environments should now be easier to manage. After this is implemented and understood, you can set the query parameter "useIAMCredentials" to "true" for AWS environments! To effectively toggle this on and off based on local and remote environments, you can consider enabling this query parameter with system environment variables. For example, your code could set the "useIAMCredentials" query parameter to "true", when the system environment variable called "isRemote" is set to true (there are many other ways to do this and this should act as a simple example). Although it doesn’t take away the need for static credentials completely, using IAM credentials on AWS environments takes away the need to refresh on remote environments and adds a major security boost (IAM credentials are refreshed automatically every 6 hours and update when their policies are updated). This is the AWS recommended way to manage credentials and therefore should be used as often as possible.

28.5. Dependencies

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

pom.xml

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

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

28.6. See Also

Configuring Camel
Component
Endpoint
Getting Started
AWS Component

Chapter 29. AWS SimpleDB Component

Available as of Camel version 2.9

The sdb component supports storing and retrieving data from/to Amazon’s SDB service.

Prerequisites

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

29.1. URI Format

aws-sdb://domainName[?options]

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

29.2. URI Options

The AWS SimpleDB component has no options.

The AWS SimpleDB endpoint is configured using URI syntax:

aws-sdb:domainName

with the following path and query parameters:

29.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
domainName	Required The name of the domain currently worked with.		String

29.2.2. Query Parameters (10 parameters):

Name	Description	Default	Type
accessKey (producer)	Amazon AWS Access Key		String
amazonSDBClient (producer)	To use the AmazonSimpleDB as the client		AmazonSimpleDB
consistentRead (producer)	Determines whether or not strong consistency should be enforced when data is read.	false	boolean
maxNumberOfDomains (producer)	The maximum number of domain names you want returned. The range is 1 to 100.		Integer
operation (producer)	Operation to perform	PutAttributes	SdbOperations
proxyHost (producer)	To define a proxy host when instantiating the SDB client		String
proxyPort (producer)	To define a proxy port when instantiating the SDB client		Integer
region (producer)	The region in which SDB client needs to work		String
secretKey (producer)	Amazon AWS Secret Key		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

Required SDB component options

You have to provide the amazonSDBClient in the Registry or your accessKey and secretKey to access the Amazon’s SDB.

29.3. Usage

29.3.1. Message headers evaluated by the SDB producer

Header	Type	Description
`CamelAwsSdbAttributes`	`Collection<Attribute>`	List of attributes to be acted upon.
`CamelAwsSdbAttributeNames`	`Collection<String>`	The names of the attributes to be retrieved.
`CamelAwsSdbConsistentRead`	`Boolean`	Determines whether or not strong consistency should be enforced when data is read.
`CamelAwsSdbDeletableItems`	`Collection<DeletableItem>`	A list of items on which to perform the delete operation in a batch.
`CamelAwsSdbDomainName`	`String`	The name of the domain currently worked with.
`CamelAwsSdbItemName`	`String`	The unique key for this item
`CamelAwsSdbMaxNumberOfDomains`	`Integer`	The maximum number of domain names you want returned. The range is 1 * to 100.
`CamelAwsSdbNextToken`	`String`	A string specifying where to start the next list of domain/item names.
`CamelAwsSdbOperation`	`String`	To override the operation from the URI options.
`CamelAwsSdbReplaceableAttributes`	`Collection<ReplaceableAttribute>`	List of attributes to put in an Item.
`CamelAwsSdbReplaceableItems`	`Collection<ReplaceableItem>`	A list of items to put in a Domain.
`CamelAwsSdbSelectExpression`	`String`	The expression used to query the domain.
`CamelAwsSdbUpdateCondition`	`UpdateCondition`	The update condition which, if specified, determines whether the specified attributes will be updated/deleted or not.

29.3.2. Message headers set during DomainMetadata operation

Header	Type	Description
`CamelAwsSdbTimestamp`	`Integer`	The data and time when metadata was calculated, in Epoch (UNIX) seconds.
`CamelAwsSdbItemCount`	`Integer`	The number of all items in the domain.
`CamelAwsSdbAttributeNameCount`	`Integer`	The number of unique attribute names in the domain.
`CamelAwsSdbAttributeValueCount`	`Integer`	The number of all attribute name/value pairs in the domain.
`CamelAwsSdbAttributeNameSize`	`Long`	The total size of all unique attribute names in the domain, in bytes.
`CamelAwsSdbAttributeValueSize`	`Long`	The total size of all attribute values in the domain, in bytes.
`CamelAwsSdbItemNameSize`	`Long`	The total size of all item names in the domain, in bytes.

29.3.3. Message headers set during GetAttributes operation

Header	Type	Description
`CamelAwsSdbAttributes`	`List<Attribute>`	The list of attributes returned by the operation.

29.3.4. Message headers set during ListDomains operation

Header	Type	Description
`CamelAwsSdbDomainNames`	`List<String>`	A list of domain names that match the expression.
`CamelAwsSdbNextToken`	`String`	An opaque token indicating that there are more domains than the specified MaxNumberOfDomains still available.

29.3.5. Message headers set during Select operation

Header	Type	Description
`CamelAwsSdbItems`	`List<Item>`	A list of items that match the select expression.
`CamelAwsSdbNextToken`	`String`	An opaque token indicating that more items than MaxNumberOfItems were matched, the response size exceeded 1 megabyte, or the execution time exceeded 5 seconds.

29.3.6. Advanced AmazonSimpleDB configuration

If you need more control over the AmazonSimpleDB instance configuration you can create your own instance and refer to it from the URI:

from("direct:start")
.to("aws-sdb://domainName?amazonSDBClient=#client");

The #client refers to a AmazonSimpleDB in the Registry.

For example if your Camel Application is running behind a firewall:

AWSCredentials awsCredentials = new BasicAWSCredentials("myAccessKey", "mySecretKey");
ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setProxyHost("http://myProxyHost");
clientConfiguration.setProxyPort(8080);

AmazonSimpleDB client = new AmazonSimpleDBClient(awsCredentials, clientConfiguration);

registry.bind("client", client);

29.4. Dependencies

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

pom.xml

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

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

29.5. See Also

Configuring Camel
Component
Endpoint
Getting Started
AWS Component

Chapter 30. AWS Simple Email Service Component

Available as of Camel version 2.9

The ses component supports sending emails with Amazon’s SES service.

Prerequisites

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

30.1. URI Format

aws-ses://from[?options]

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

30.2. URI Options

The AWS Simple Email Service component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	The AWS SES default configuration		SesConfiguration
accessKey (producer)	Amazon AWS Access Key		String
secretKey (producer)	Amazon AWS Secret Key		String
region (producer)	The region in which SES client needs to work		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AWS Simple Email Service endpoint is configured using URI syntax:

aws-ses:from

with the following path and query parameters:

30.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
from	Required The sender’s email address.		String

30.2.2. Query Parameters (11 parameters):

Name	Description	Default	Type
amazonSESClient (producer)	To use the AmazonSimpleEmailService as the client		AmazonSimpleEmail Service
proxyHost (producer)	To define a proxy host when instantiating the SES client		String
proxyPort (producer)	To define a proxy port when instantiating the SES client		Integer
region (producer)	The region in which SES client needs to work		String
replyToAddresses (producer)	List of reply-to email address(es) for the message, override it using 'CamelAwsSesReplyToAddresses' header.		List
returnPath (producer)	The email address to which bounce notifications are to be forwarded, override it using 'CamelAwsSesReturnPath' header.		String
subject (producer)	The subject which is used if the message header 'CamelAwsSesSubject' is not present.		String
to (producer)	List of destination email address. Can be overriden with 'CamelAwsSesTo' header.		List
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
accessKey (security)	Amazon AWS Access Key		String
secretKey (security)	Amazon AWS Secret Key		String

Required SES component options

You have to provide the amazonSESClient in the Registry or your accessKey and secretKey to access the Amazon’s SES.

30.3. Usage

30.3.1. Message headers evaluated by the SES producer

Header	Type	Description
`CamelAwsSesFrom`	`String`	The sender’s email address.
`CamelAwsSesTo`	`List<String>`	The destination(s) for this email.
`CamelAwsSesSubject`	`String`	The subject of the message.
`CamelAwsSesReplyToAddresses`	`List<String>`	The reply-to email address(es) for the message.
`CamelAwsSesReturnPath`	`String`	The email address to which bounce notifications are to be forwarded.
`CamelAwsSesHtmlEmail`	`Boolean`	Since Camel 2.12.3 The flag to show if email content is HTML.

30.3.2. Message headers set by the SES producer

Header	Type	Description
`CamelAwsSesMessageId`	`String`	The Amazon SES message ID.

30.3.3. Advanced AmazonSimpleEmailService configuration

If you need more control over the AmazonSimpleEmailService instance configuration you can create your own instance and refer to it from the URI:

from("direct:start")
.to("aws-ses://example@example.com?amazonSESClient=#client");

The #client refers to a AmazonSimpleEmailService in the Registry.

For example if your Camel Application is running behind a firewall:

AWSCredentials awsCredentials = new BasicAWSCredentials("myAccessKey", "mySecretKey");
ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setProxyHost("http://myProxyHost");
clientConfiguration.setProxyPort(8080);
AmazonSimpleEmailService client = new AmazonSimpleEmailServiceClient(awsCredentials, clientConfiguration);

registry.bind("client", client);

30.4. Dependencies

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

pom.xml

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

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

30.5. See Also

Configuring Camel
Component
Endpoint
Getting Started
AWS Component

Chapter 31. AWS Simple Notification System Component

Available as of Camel version 2.8

The SNS component allows messages to be sent to an Amazon Simple Notification Topic. The implementation of the Amazon API is provided by the http://aws.amazon.com/sdkforjava/[AWS SDK].

Prerequisites

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

31.1. URI Format

aws-sns://topicNameOrArn[?options]

The topic 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&…

31.2. URI Options

The AWS Simple Notification System component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	The AWS SNS default configuration		SnsConfiguration
accessKey (producer)	Amazon AWS Access Key		String
secretKey (producer)	Amazon AWS Secret Key		String
region (producer)	The region in which SNS client needs to work		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AWS Simple Notification System endpoint is configured using URI syntax:

aws-sns:topicNameOrArn

with the following path and query parameters:

31.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
topicNameOrArn	Required Topic name or ARN		String

31.2.2. Query Parameters (11 parameters):

Name	Description	Default	Type
amazonSNSClient (producer)	To use the AmazonSNS as the client		AmazonSNS
headerFilterStrategy (producer)	To use a custom HeaderFilterStrategy to map headers to/from Camel.		HeaderFilterStrategy
messageStructure (producer)	The message structure to use such as json		String
policy (producer)	The policy for this queue		String
proxyHost (producer)	To define a proxy host when instantiating the SNS client		String
proxyPort (producer)	To define a proxy port when instantiating the SNS client		Integer
region (producer)	The region in which SNS client needs to work		String
subject (producer)	The subject which is used if the message header 'CamelAwsSnsSubject' is not present.		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
accessKey (security)	Amazon AWS Access Key		String
secretKey (security)	Amazon AWS Secret Key		String

Required SNS component options

You have to provide the amazonSNSClient in the Registry or your accessKey and secretKey to access the Amazon’s SNS.

31.3. Usage

31.3.1. Message headers evaluated by the SNS producer

Header	Type	Description
`CamelAwsSnsSubject`	`String`	The Amazon SNS message subject. If not set, the subject from the `SnsConfiguration` is used.

31.3.2. Message headers set by the SNS producer

Header	Type	Description
`CamelAwsSnsMessageId`	`String`	The Amazon SNS message ID.

31.3.3. Advanced AmazonSNS configuration

If you need more control over the AmazonSNS instance configuration you can create your own instance and refer to it from the URI:

from("direct:start")
.to("aws-sns://MyTopic?amazonSNSClient=#client");

The #client refers to a AmazonSNS in the Registry.

For example if your Camel Application is running behind a firewall:

AWSCredentials awsCredentials = new BasicAWSCredentials("myAccessKey", "mySecretKey");
ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setProxyHost("http://myProxyHost");
clientConfiguration.setProxyPort(8080);
AmazonSNS client = new AmazonSNSClient(awsCredentials, clientConfiguration);

registry.bind("client", client);

31.4. Dependencies

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

pom.xml

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

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

31.5. See Also

Configuring Camel
Component
Endpoint
Getting Started
AWS Component

Chapter 32. AWS Simple Queue Service Component

Available as of Camel version 2.6

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

Prerequisites

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.

32.1. URI Format

aws-sqs://queueNameOrArn[?options]

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

32.2. URI Options

The AWS Simple Queue Service component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	The AWS SQS default configuration		SqsConfiguration
accessKey (common)	Amazon AWS Access Key		String
secretKey (common)	Amazon AWS Secret Key		String
region (common)	Specify the queue region which could be used with queueOwnerAWSAccountId to build the service URL.		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AWS Simple Queue Service endpoint is configured using URI syntax:

aws-sqs:queueNameOrArn

with the following path and query parameters:

32.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
queueNameOrArn	Required Queue name or ARN		String

32.2.2. Query Parameters (46 parameters):

Name	Description	Default	Type
amazonAWSHost (common)	The hostname of the Amazon AWS cloud.	amazonaws.com	String
amazonSQSClient (common)	To use the AmazonSQS as client		AmazonSQS
headerFilterStrategy (common)	To use a custom HeaderFilterStrategy to map headers to/from Camel.		HeaderFilterStrategy
queueOwnerAWSAccountId (common)	Specify the queue owner aws account id when you need to connect the queue with different account owner.		String
region (common)	Specify the queue region which could be used with queueOwnerAWSAccountId to build the service URL.		String
attributeNames (consumer)	A list of attribute names to receive when consuming. Multiple names can be separated by comma.		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
concurrentConsumers (consumer)	Allows you to use multiple threads to poll the sqs queue to increase throughput	1	int
defaultVisibilityTimeout (consumer)	The default visibility timeout (in seconds)		Integer
deleteAfterRead (consumer)	Delete message from SQS after it has been read	true	boolean
deleteIfFiltered (consumer)	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.	true	boolean
extendMessageVisibility (consumer)	If enabled then a scheduled background task will keep extending the message visibility on SQS. This is needed if it takes a long time to process the message. If set to true defaultVisibilityTimeout must be set. See details at Amazon docs.	false	boolean
maxMessagesPerPoll (consumer)	Gets the maximum number of messages as a limit to poll at each polling. Is default unlimited, but use 0 or negative number to disable it as unlimited.		int
messageAttributeNames (consumer)	A list of message attribute names to receive when consuming. Multiple names can be separated by comma.		String
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
visibilityTimeout (consumer)	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.		Integer
waitTimeSeconds (consumer)	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.		Integer
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
delaySeconds (producer)	Delay sending messages for a number of seconds.		Integer
messageDeduplicationId Strategy (producer)	Only for FIFO queues. Strategy for setting the messageDeduplicationId on the message. Can be one of the following options: useExchangeId, useContentBasedDeduplication. For the useContentBasedDeduplication option, no messageDeduplicationId will be set on the message.	useExchangeId	MessageDeduplicationId Strategy
messageGroupIdStrategy (producer)	Only for FIFO queues. Strategy for setting the messageGroupId on the message. Can be one of the following options: useConstant, useExchangeId, usePropertyValue. For the usePropertyValue option, the value of property CamelAwsMessageGroupId will be used.		MessageGroupIdStrategy
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean
proxyHost (proxy)	To define a proxy host when instantiating the SQS client		String
proxyPort (proxy)	To define a proxy port when instantiating the SQS client		Integer
maximumMessageSize (queue)	The maximumMessageSize (in bytes) an SQS message can contain for this queue.		Integer
messageRetentionPeriod (queue)	The messageRetentionPeriod (in seconds) a message will be retained by SQS for this queue.		Integer
policy (queue)	The policy for this queue		String
receiveMessageWaitTime Seconds (queue)	If you do not specify WaitTimeSeconds in the request, the queue attribute ReceiveMessageWaitTimeSeconds is used to determine how long to wait.		Integer
redrivePolicy (queue)	Specify the policy that send message to DeadLetter queue. See detail at Amazon docs.		String
accessKey (security)	Amazon AWS Access Key		String
secretKey (security)	Amazon AWS Secret Key		String

Required SQS component options

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

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

32.4. Usage

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

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

32.4.3. Advanced AmazonSQS configuration

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

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

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

AmazonSQS client = new AmazonSQSClient(awsCredentials, clientConfiguration);

registry.bind("client", client);

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

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

32.5. Dependencies

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

pom.xml

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

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

32.6. JMS-style Selectors

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

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

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

32.7. See Also

Configuring Camel
Component
Endpoint
Getting Started
AWS Component

Chapter 33. AWS Simple Workflow Component

Available as of Camel version 2.13

The Simple Workflow component supports managing workflows from Amazon’s Simple Workflow service.

Prerequisites

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

33.1. URI Format

aws-swf://<workflow|activity>[?options]

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

33.2. URI Options

The AWS Simple Workflow component supports 5 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	The AWS SWF default configuration		SWFConfiguration
accessKey (common)	Amazon AWS Access Key.		String
secretKey (common)	Amazon AWS Secret Key.		String
region (common)	Amazon AWS Region.		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The AWS Simple Workflow endpoint is configured using URI syntax:

aws-swf:type

with the following path and query parameters:

33.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
type	Required Activity or workflow		String

33.2.2. Query Parameters (30 parameters):

Name	Description	Default	Type
amazonSWClient (common)	To use the given AmazonSimpleWorkflowClient as client		AmazonSimpleWorkflow Client
dataConverter (common)	An instance of com.amazonaws.services.simpleworkflow.flow.DataConverter to use for serializing/deserializing the data.		DataConverter
domainName (common)	The workflow domain to use.		String
eventName (common)	The workflow or activity event name to use.		String
region (common)	Amazon AWS Region.		String
version (common)	The workflow or activity event version to use.		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
clientConfiguration Parameters (advanced)	To configure the ClientConfiguration using the key/values from the Map.		Map
startWorkflowOptions Parameters (advanced)	To configure the StartWorkflowOptions using the key/values from the Map.		Map
sWClientParameters (advanced)	To configure the AmazonSimpleWorkflowClient using the key/values from the Map.		Map
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
activityList (activity)	The list name to consume activities from.		String
activitySchedulingOptions (activity)	Activity scheduling options		ActivityScheduling Options
activityThreadPoolSize (activity)	Maximum number of threads in work pool for activity.	100	int
activityTypeExecution Options (activity)	Activity execution options		ActivityTypeExecution Options
activityTypeRegistration Options (activity)	Activity registration options		ActivityType RegistrationOptions
childPolicy (workflow)	The policy to use on child workflows when terminating a workflow.		String
executionStartToClose Timeout (workflow)	Set the execution start to close timeout.	3600	String
operation (workflow)	Workflow operation	START	String
signalName (workflow)	The name of the signal to send to the workflow.		String
stateResultType (workflow)	The type of the result when a workflow state is queried.		String
taskStartToCloseTimeout (workflow)	Set the task start to close timeout.	600	String
terminationDetails (workflow)	Details for terminating a workflow.		String
terminationReason (workflow)	The reason for terminating a workflow.		String
workflowList (workflow)	The list name to consume workflows from.		String
workflowTypeRegistration Options (workflow)	Workflow registration options		WorkflowType RegistrationOptions
accessKey (security)	Amazon AWS Access Key.		String
secretKey (security)	Amazon AWS Secret Key.		String

Required SWF component options

You have to provide the amazonSWClient in the Registry or your accessKey and secretKey to access the Amazon’s Simple Workflow Service.

33.3. Usage

33.3.1. Message headers evaluated by the SWF Workflow Producer

A workflow producer allows interacting with a workflow. It can start a new workflow execution, query its state, send signals to a running workflow, or terminate and cancel it.

Header	Type	Description
`CamelSWFOperation`	`String`	The operation to perform on the workflow. Supported operations are: SIGNAL, CANCEL, TERMINATE, GET_STATE, START, DESCRIBE, GET_HISTORY.
`CamelSWFWorkflowId`	`String`	A workflow ID to use.
`CamelAwsDdbKeyCamelSWFRunId`	`String`	A worfklow run ID to use.
`CamelSWFStateResultType`	`String`	The type of the result when a workflow state is queried.
`CamelSWFEventName`	`String`	The workflow or activity event name to use.
`CamelSWFVersion`	`String`	The workflow or activity event version to use.
`CamelSWFReason`	`String`	The reason for terminating a workflow.
`CamelSWFDetails`	`String`	Details for terminating a workflow.
`CamelSWFChildPolicy`	`String`	The policy to use on child workflows when terminating a workflow.

33.3.2. Message headers set by the SWF Workflow Producer

Header	Type	Description
`CamelSWFWorkflowId`	`String`	The worfklow ID used or newly generated.
`CamelAwsDdbKeyCamelSWFRunId`	`String`	The worfklow run ID used or generated.

33.3.3. Message headers set by the SWF Workflow Consumer

A workflow consumer represents the workflow logic. When it is started, it will start polling workflow decision tasks and process them. In addition to processing decision tasks, a workflow consumer route, will also receive signals (send from a workflow producer) or state queries. The primary purpose of a workflow consumer is to schedule activity tasks for execution using activity producers. Actually activity tasks can be scheduled only from a thread started by a workflow consumer.

Header	Type	Description
`CamelSWFAction`	`String`	Indicates what type is the current event: CamelSWFActionExecute, CamelSWFSignalReceivedAction or CamelSWFGetStateAction.
`CamelSWFWorkflowReplaying`	`boolean`	Indicates whether the current decision task is a replay or not.
`CamelSWFWorkflowStartTime`	`long`	The time of the start event for this decision task.

33.3.4. Message headers set by the SWF Activity Producer

An activity producer allows scheduling activity tasks. An activity producer can be used only from a thread started by a workflow consumer ie, it can process synchronous exchanges started by a workflow consumer.

Header	Type	Description
`CamelSWFEventName`	`String`	The activity name to schedule.
`CamelSWFVersion`	`String`	The activity version to schedule.

33.3.5. Message headers set by the SWF Activity Consumer

Header	Type	Description
`CamelSWFTaskToken`	`String`	The task token that is required to report task completion for manually completed tasks.

33.3.6. Advanced amazonSWClient configuration

If you need more control over the AmazonSimpleWorkflowClient instance configuration you can create your own instance and refer to it from the URI:

The #client refers to a AmazonSimpleWorkflowClient in the Registry.

For example if your Camel Application is running behind a firewall:

AWSCredentials awsCredentials = new BasicAWSCredentials("myAccessKey", "mySecretKey");
ClientConfiguration clientConfiguration = new ClientConfiguration();
clientConfiguration.setProxyHost("http://myProxyHost");
clientConfiguration.setProxyPort(8080);

AmazonSimpleWorkflowClient client = new AmazonSimpleWorkflowClient(awsCredentials, clientConfiguration);

registry.bind("client", client);

33.4. Dependencies

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

pom.xml

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

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

33.5. See Also

Configuring Camel
Component
Endpoint
Getting Started

AWS Component

Chapter 34. AWS XRay Component

Available as of Camel 2.21

The camel-aws-xray component is used for tracing and timing incoming and outgoing Camel messages using AWS XRay.

Events (subsegments) are captured for incoming and outgoing messages being sent to/from Camel.

34.1. Dependency

In order to include AWS XRay support into Camel, the archive containing the Camel related AWS XRay related classes need to be added to the project. In addition to that, AWS XRay libraries also need to be available.

To include both, AWS XRay and Camel, dependencies use the following Maven imports:

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-xray-recorder-sdk-bom</artifactId>
        <version>1.3.1</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <dependencies>
      <dependency>
        <groupId>org.apache.camel</groupId>
        <artifactId>camel-aws-xray</artifactId>
      </dependency>

      <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-xray-recorder-sdk-core</artifactId>
      </dependency>
      <dependency>
        <groupId>com.amazonaws</groupId>
        <artifactId>aws-xray-recorder-sdk-aws-sdk</artifactId>
      </dependency>
  <dependencies>

34.2. Configuration

The configuration properties for the AWS XRay tracer are:

Option	Default	Description
addExcludePatterns		Sets exclude pattern(s) that will disable tracing for Camel messages that matches the pattern. The content is a Set<String> where the key is a pattern matching routeId’s. The pattern uses the rules from Intercept.
setTracingStrategy	NoopTracingStrategy	Allows a custom Camel `InterceptStrategy` to be provided in order to track invoked processor definitions like `BeanDefinition` or `ProcessDefinition`. `TraceAnnotatedTracingStrategy` will track any classes invoked via `.bean(…)` or `.process(…)` that contain a `@XRayTrace` annotation at class level.

There is currently only one way an AWS XRay tracer can be configured to provide distributed tracing for a Camel application:

34.2.1. Explicit

Include the camel-aws-xray component in your POM, along with any specific dependencies associated with the AWS XRay Tracer.

To explicitly configure AWS XRay support, instantiate the XRayTracer and initialize the camel context. You can optionally specify a Tracer, or alternatively it can be implicitly discovered using the Registry or ServiceLoader.

XRayTracer xrayTracer = new XRayTracer();
// By default it uses a NoopTracingStrategy, but you can override it with a specific InterceptStrategy implementation.
xrayTracer.setTracingStrategy(...);
// And then initialize the context
xrayTracer.init(camelContext);

To use XRayTracer in XML, all you need to do is to define the AWS XRay tracer bean. Camel will automatically discover and use it.

  <bean id="tracingStrategy" class="..."/>
  <bean id="aws-xray-tracer" class="org.apache.camel.component.aws.xray.XRayTracer" />
    <property name="tracer" ref="tracingStrategy"/>
  </bean>

In case of the default NoopTracingStrategy only the creation and deletion of exchanges is tracked but not the invocation of certain beans or EIP patterns.

34.2.2. Tracking of comprehensive route execution

In order to track the execution of an exchange among multiple routes, on exchange creation a unique trace ID is generated and stored in the headers if no corresponding value was yet available. This trace ID is copied over to new exchanges in order to keep a consistent view of the processed exchange.

As AWS XRay traces work on a thread-local basis the current sub/segment should be copied over to the new thread and set as explained in in the AWS XRay documentation. The Camel AWS XRay component therefore provides an additional header field that the component will use in order to set the passed AWS XRay Entity to the new thread and thus keep the tracked data to the route rather than exposing a new segment which seems uncorrelated with any of the executed routes.

The component will use the following constants found in the headers of the exchange:

Header	Description
Camel-AWS-XRay-Trace-ID	Contains a reference to the AWS XRay `TraceID` object to provide a comprehensive view of the invoked routes
Camel-AWS-XRay-Trace-Entity	Contains a reference to the actual AWS XRay `Segment` or `Subsegment` which is copied over to the new thread. This header should be set in case a new thread is spawned and the performed tasks should be exposed as part of the executed route instead of creating a new unrelated segment.

Note that the AWS XRay Entity (i.e., Segment and Subsegment) are not serializable and therefore should not get passed to other JVM processes.

34.3. Example

You can find an example demonstrating the way to configure AWS XRay tracing within the tests accompanying this project.

Chapter 35. Camel Components for Windows Azure Services

The Camel Components for Windows Azure Services provide connectivity to Azure services from Camel.

Azure Service	Camel Component	Camel Version	Component Description
Storage Blob Service	Azure-Blob	2.9.0	Supports storing and retrieving of blobs
Storage Queue Service	Azure-Queue	2.9.0	Supports storing and retrieving of messages in the queues

Chapter 36. Azure Storage Blob Service Component

Available as of Camel version 2.19

The Azure Blob component supports storing and retrieving the blobs to/from Azure Storage Blob service.

Prerequisites

You must have a valid Windows Azure Storage account. More information is available at Azure Documentation Portal.

36.1. URI Format

azure-blob://accountName/containerName[/blobName][?options]

In most cases a blobName is required and the blob will be created if it does not already exist.
You can append query options to the URI in the following format, ?options=value&option2=value&…

For example in order to download a blob content from the public block blob blockBlob located on the container1 in the camelazure storage account, use the following snippet:

from("azure-blob:/camelazure/container1/blockBlob").
to("file://blobdirectory");

36.2. URI Options

The Azure Storage Blob Service component has no options.

The Azure Storage Blob Service endpoint is configured using URI syntax:

azure-blob:containerOrBlobUri

with the following path and query parameters:

36.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
containerOrBlobUri	Required Container or Blob compact Uri		String

36.2.2. Query Parameters (19 parameters):

Name	Description	Default	Type
azureBlobClient (common)	The blob service client		CloudBlob
blobOffset (common)	Set the blob offset for the upload or download operations, default is 0	0	Long
blobType (common)	Set a blob type, 'blockblob' is default	blockblob	BlobType
closeStreamAfterRead (common)	Close the stream after read or keep it open, default is true	true	boolean
credentials (common)	Set the storage credentials, required in most cases		StorageCredentials
dataLength (common)	Set the data length for the download or page blob upload operations		Long
fileDir (common)	Set the file directory where the downloaded blobs will be saved to		String
publicForRead (common)	Storage resources can be public for reading their content, if this property is enabled then the credentials do not have to be set	false	boolean
streamReadSize (common)	Set the minimum read size in bytes when reading the blob content		int
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
blobMetadata (producer)	Set the blob meta-data		Map
blobPrefix (producer)	Set a prefix which can be used for listing the blobs		String
closeStreamAfterWrite (producer)	Close the stream after write or keep it open, default is true	true	boolean
operation (producer)	Blob service operation hint to the producer	listBlobs	BlobServiceOperations
streamWriteSize (producer)	Set the size of the buffer for writing block and page blocks		int
useFlatListing (producer)	Specify if the flat or hierarchical blob listing should be used	true	boolean
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

Required Azure Storage Blob Service component options

You have to provide the containerOrBlob name and the credentials if the private blob needs to be accessed.

36.3. Usage

36.3.1. Message headers evaluated by the Azure Storage Blob Service producer

Header	Type	Description

36.3.2. Message headers set by the Azure Storage Blob Service producer

Header	Type	Description
`CamelFileName`	`String`	The file name for the downloaded blob content.

36.3.3. Message headers set by the Azure Storage Blob Service producer consumer

Header	Type	Description
`CamelFileName`	`String`	The file name for the downloaded blob content.

36.3.4. Azure Blob Client configuration

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

StorageCredentials credentials = new StorageCredentialsAccountAndKey("camelazure", "thekey");

CloudBlob client = new CloudBlob("camelazure", credentials);

registry.bind("azureBlobClient", client);

and refer to it in your Camel azure-blob component configuration:

from("azure-blob:/camelazure/container1/blockBlob?azureBlobClient=#client")
.to("mock:result");

36.4. Dependencies

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

pom.xml

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

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

36.5. See Also

Configuring Camel
Component
Endpoint
Getting Started
Azure Component

Chapter 37. Azure Storage Queue Service Component

Available as of Camel version 2.19

The Azure Queue component supports storing and retrieving the messages to/from Azure Storage Queue service.

Prerequisites

You must have a valid Windows Azure Storage account. More information is available at Azure Documentation Portal.

37.1. URI Format

azure-queue://accountName/queueName[?options]

The queue will be created if it does not already exist.
You can append query options to the URI in the following format, ?options=value&option2=value&…

For example in order to get a message content from the queue messageQueue in the camelazure storage account and, use the following snippet:

from("azure-queue:/camelazure/messageQueue").
to("file://queuedirectory");

37.2. URI Options

The Azure Storage Queue Service component has no options.

The Azure Storage Queue Service endpoint is configured using URI syntax:

azure-queue:containerAndQueueUri

with the following path and query parameters:

37.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
containerAndQueueUri	Required Container Queue compact Uri		String

37.2.2. Query Parameters (10 parameters):

Name	Description	Default	Type
azureQueueClient (common)	The queue service client		CloudQueue
credentials (common)	Set the storage credentials, required in most cases		StorageCredentials
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
messageTimeToLive (producer)	Message Time To Live in seconds		int
messageVisibilityDelay (producer)	Message Visibility Delay in seconds		int
operation (producer)	Queue service operation hint to the producer	listQueues	QueueServiceOperations
queuePrefix (producer)	Set a prefix which can be used for listing the queues		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

Required Azure Storage Queue Service component options

You have to provide the containerAndQueue URI and the credentials.

37.3. Usage

37.3.1. Message headers evaluated by the Azure Storage Queue Service producer

Header	Type	Description

37.3.2. Message headers set by the Azure Storage Queue Service producer

Header	Type	Description

37.3.3. Message headers set by the Azure Storage Queue Service producer consumer

Header	Type	Description

37.3.4. Azure Queue Client configuration

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

StorageCredentials credentials = new StorageCredentialsAccountAndKey("camelazure", "thekey");

CloudQueue client = new CloudQueue("camelazure", credentials);

registry.bind("azureQueueClient", client);

and refer to it in your Camel azure-queue component configuration:

from("azure-queue:/camelazure/messageQueue?azureQueueClient=#client")
.to("mock:result");

37.4. Dependencies

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

pom.xml

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

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

37.5. See Also

Configuring Camel
Component
Endpoint
Getting Started
Azure Component

Chapter 38. Barcode DataFormat

Available as of Camel version 2.14

The barcode data format is based on the zxing library. The goal of this component is to create a barcode image from a String (marshal) and a String from a barcode image (unmarshal). You’re free to use all features that zxing offers.

38.1. Dependencies

To use the barcode data format in your camel routes you need to add the a dependency on camel-barcode 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).

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

38.2. Barcode Options

The Barcode dataformat supports 5 options which are listed below.

Name	Default	Java Type	Description
width		`Integer`	Width of the barcode
height		`Integer`	Height of the barcode
imageType		`String`	Image type of the barcode such as png
barcodeFormat		`String`	Barcode format such as QR-Code
contentTypeHeader	`false`	`Boolean`	Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.

38.3. Using the Java DSL

First you have to initialize the barcode data fomat class. You can use the default constructor, or one of parameterized (see JavaDoc). The default values are:

Parameter	Default Value
image type (BarcodeImageType)	PNG
width	100 px
height	100 px
encoding	UTF-8
barcode format (BarcodeFormat)	QR-Code

// QR-Code default
DataFormat code = new BarcodeDataFormat();

If you want to use zxing hints, you can use the 'addToHintMap' method of your BarcodeDataFormat instance:

code.addToHintMap(DecodeHintType.TRY_HARDER, Boolean.true);

For possible hints, please consult the xzing documentation.

38.3.1. Marshalling

from("direct://code")
  .marshal(code)
  .to("file://barcode_out");

You can call the route from a test class with:

template.sendBody("direct://code", "This is a testmessage!");

You should find inside the 'barcode_out' folder this image:

38.3.2. Unmarshalling

The unmarshaller is generic. For unmarshalling you can use any BarcodeDataFormat instance. If you’ve two instances, one for (generating) QR-Code and one for PDF417, it doesn’t matter which one will be used.

from("file://barcode_in?noop=true")
  .unmarshal(code) // for unmarshalling, the instance doesn't matter
  .to("mock:out");

If you’ll paste the QR-Code image above into the 'barcode_in' folder, you should find ‘This is a testmessage!’ inside the mock. You can find the barcode data format as header variable:

Name	Type	Description
BarcodeFormat	String	Value of com.google.zxing.BarcodeFormat.

Chapter 39. Base64 DataFormat

Available as of Camel version 2.11

The Base64 data format is used for base64 encoding and decoding.

39.1. Options

The Base64 dataformat supports 4 options which are listed below.

Name	Default	Java Type	Description
lineLength	`76`	`Integer`	To specific a maximum line length for the encoded data. By default 76 is used.
lineSeparator		`String`	The line separators to use. Uses new line characters (CRLF) by default.
urlSafe	`false`	`Boolean`	Instead of emitting '' and '/' we emit '-' and '_' respectively. urlSafe is only applied to encode operations. Decoding seamlessly handles both modes. Is by default false.
contentTypeHeader	`false`	`Boolean`	Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.

In Spring DSL, you configure the data format using this tag:

<camelContext>
    <dataFormats>
        <!-- for a newline character (\n), use the HTML entity notation coupled with the ASCII code. -->
        <base64 lineSeparator="&#10;" id="base64withNewLine" />
        <base64 lineLength="64" id="base64withLineLength64" />
    </dataFormats>
    ...
</camelContext>

Then you can use it later by its reference:

<route>
     <from uri="direct:startEncode" />
     <marshal ref="base64withLineLength64" />
     <to uri="mock:result" />
</route>

Most of the time, you won’t need to declare the data format if you use the default options. In that case, you can declare the data format inline as shown below.

39.2. Marshal

In this example we marshal the file content to base64 object.

from("file://data.bin")
    .marshal().base64()
    .to("jms://myqueue");

In Spring DSL:

 <from uri="file://data.bin">
 <marshal>
     <base64/>
 </marshal>
 <to uri="jms://myqueue"/>

39.3. Unmarshal

In this example we unmarshal the payload from the JMS queue to a byte[] object, before its processed by the newOrder processor.

from("jms://queue/order")
    .unmarshal().base64()
    .process("newOrder");

In Spring DSL:

 <from uri="jms://queue/order">
 <marshal>
     <base64/>
 </marshal>
 <to uri="bean:newOrder"/>

39.4. Dependencies

To use Base64 in your Camel routes you need to add a dependency on camel-base64 which implements this data format.

If you use Maven you can just add the following to your pom.xml:

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

Chapter 40. Bean Component

Available as of Camel version 1.0

The bean: component binds beans to Camel message exchanges.

40.1. URI format

bean:beanName[?options]

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

40.2. Options

The Bean component has no options.

The Bean endpoint is configured using URI syntax:

bean:beanName

with the following path and query parameters:

40.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
beanName	Required Sets the name of the bean to invoke		String

40.2.2. Query Parameters (5 parameters):

Name	Description	Default	Type
method (producer)	Sets the name of the method to invoke on the bean		String
cache (advanced)	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.	false	boolean
multiParameterArray (advanced)	Deprecated How to treat the parameters which are passed from the message body; if it is true, the message body should be an array of parameters. Note: This option is used internally by Camel, and is not intended for end users to use. Deprecation note: This option is used internally by Camel, and is not intended for end users to use.	false	boolean
parameters (advanced)	Used for configuring additional properties on the bean		Map
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

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

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

Error formatting macro: snippet: java.lang.IndexOutOfBoundsException: Index: 20, Size: 20

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:

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

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

40.5. Java DSL bean syntax

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

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

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

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

// Send message to the given bean instance.
from("direct:start").bean(new ExampleBean());

// Explicit selection of bean method to be invoked.
from("direct:start").bean(new ExampleBean(), "methodName");

// Camel will create the instance of bean and cache it for you.
from("direct:start").bean(ExampleBean.class);

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

40.7. See Also

Configuring Camel
Component
Endpoint
Getting Started
Class component
Bean Binding
Bean Integration

Chapter 41. BeanIO DataFormat

Available as of Camel version 2.10

The BeanIO Data Format uses BeanIO to handle flat payloads (such as XML, CSV, delimited, or fixed length formats).

BeanIO is configured using a mappings XML file where you define the mapping from the flat format to Objects (POJOs). This mapping file is mandatory to use.

41.1. Options

The BeanIO dataformat supports 9 options which are listed below.

Name	Default	Java Type	Description
mapping		`String`	The BeanIO mapping file. Is by default loaded from the classpath. You can prefix with file:, http:, or classpath: to denote from where to load the mapping file.
streamName		`String`	The name of the stream to use.
ignoreUnidentifiedRecords	`false`	`Boolean`	Whether to ignore unidentified records.
ignoreUnexpectedRecords	`false`	`Boolean`	Whether to ignore unexpected records.
ignoreInvalidRecords	`false`	`Boolean`	Whether to ignore invalid records.
encoding		`String`	The charset to use. Is by default the JVM platform default charset.
beanReaderErrorHandlerType		`String`	To use a custom org.apache.camel.dataformat.beanio.BeanIOErrorHandler as error handler while parsing. Configure the fully qualified class name of the error handler. Notice the options ignoreUnidentifiedRecords, ignoreUnexpectedRecords, and ignoreInvalidRecords may not be in use when you use a custom error handler.
unmarshalSingleObject	`false`	`Boolean`	This options controls whether to unmarshal as a list of objects or as a single object only. The former is the default mode, and the latter is only intended in special use-cases where beanio maps the Camel message to a single POJO bean.
contentTypeHeader	`false`	`Boolean`	Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.

41.2. Usage

An example of a mapping file is here.

41.2.1. Using Java DSL

To use the BeanIODataFormat you need to configure the data format with the mapping file, as well the name of the stream.
In Java DSL this can be done as shown below. The streamName is "employeeFile".

Then we have two routes. The first route is for transforming CSV data into a List<Employee> Java objects. Which we then split, so the mock endpoint
receives a message for each row.

The 2nd route is for the reverse operation, to transform a List<Employee> into a stream of CSV data.

The CSV data could for example be as below:

41.2.2. Using XML DSL

To use the BeanIO data format in XML, you need to configure it using the <beanio> XML tag as shown below. The routes is similar to the example above.

41.3. Dependencies

To use BeanIO in your Camel routes you need to add a dependency on camel-beanio which implements this data format.

If you use Maven you can 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).

<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-beanio</artifactId>
  <version>2.10.0</version>
</dependency>

Chapter 42. Beanstalk Component

Available as of Camel version 2.15

camel-beanstalk project provides a Camel component for job retrieval and post-processing of Beanstalk jobs.

You can find the detailed explanation of Beanstalk job lifecycle at http://github.com/kr/beanstalkd/blob/v1.3/doc/protocol.txt[Beanstalk protocol].

42.1. Dependencies

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

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

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

42.2. URI format

beanstalk://[host[:port]][/tube][?options]

You may omit either port or both host and port: for the Beanstalk defaults to be used (“localhost” and 11300). If you omit tube, Beanstalk component will use the tube with name “default”.

When listening, you may probably want to watch for jobs from several tubes. Just separate them with plus sign, e.g.

beanstalk://localhost:11300/tube1+tube2

Tube name will be URL decoded, so if your tube names include special characters like + or ?, you need to URL-encode them appropriately, or use the RAW syntax, see more details here.

By the way, you cannot specify several tubes when you are writing jobs into Beanstalk.

42.3. Beanstalk options

The Beanstalk component supports 2 options which are listed below.

Name	Description	Default	Type
connectionSettings Factory (common)	Custom ConnectionSettingsFactory. Specify which ConnectionSettingsFactory to use to make connections to Beanstalkd. Especially useful for unit testing without beanstalkd daemon (you can mock ConnectionSettings)		ConnectionSettings Factory
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Beanstalk endpoint is configured using URI syntax:

beanstalk:connectionSettings

with the following path and query parameters:

42.3.1. Path Parameters (1 parameters):

Name	Description	Default	Type
connectionSettings	Connection settings host:port/tube		String

42.3.2. Query Parameters (26 parameters):

Name	Description	Default	Type
command (common)	put means to put the job into Beanstalk. Job body is specified in the Camel message body. Job ID will be returned in beanstalk.jobId message header. delete, release, touch or bury expect Job ID in the message header beanstalk.jobId. Result of the operation is returned in beanstalk.result message header kick expects the number of jobs to kick in the message body and returns the number of jobs actually kicked out in the message header beanstalk.result.		BeanstalkCommand
jobDelay (common)	Job delay in seconds.	0	int
jobPriority (common)	Job priority. (0 is the highest, see Beanstalk protocol)	1000	long
jobTimeToRun (common)	Job time to run in seconds. (when 0, the beanstalkd daemon raises it to 1 automatically, see Beanstalk protocol)	60	int
awaitJob (consumer)	Whether to wait for job to complete before ack the job from beanstalk	true	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
onFailure (consumer)	Command to use when processing failed.		BeanstalkCommand
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
useBlockIO (consumer)	Whether to use blockIO.	true	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean

Producer behavior is affected by the command parameter which tells what to do with the job, it can be

The consumer may delete the job immediately after reserving it or wait until Camel routes process it. While the first scenario is more like a “message queue”, the second is similar to “job queue”. This behavior is controlled by consumer.awaitJob parameter, which equals true by default (following Beanstalkd nature).

When synchronous, the consumer calls delete on successful job completion and calls bury on failure. You can choose which command to execute in the case of failure by specifying consumer.onFailure parameter in the URI. It can take values of bury, delete or release.

There is a boolean parameter consumer.useBlockIO which corresponds to the same parameter in JavaBeanstalkClient library. By default it is true.

Be careful when specifying release, as the failed job will immediately become available in the same tube and your consumer will try to acquire it again. You can release and specify jobDelay though.

The beanstalk consumer is a Scheduled Polling Consumer which means there is more options you can configure, such as how frequent the consumer should poll. For more details see Polling Consumer.

42.4. Consumer Headers

The consumer stores a number of job headers in the Exchange message:

Property	Type	Description
beanstalk.jobId	long	Job ID
beanstalk.tube	string	the name of the tube that contains this job
beanstalk.state	string	“ready” or “delayed” or “reserved” or “buried” (must be “reserved”)
beanstalk.priority	long	the priority value set
beanstalk.age	int	the time in seconds since the put command that created this job
beanstalk.time-left	int	the number of seconds left until the server puts this job into the ready queue
beanstalk.timeouts	int	the number of times this job has timed out during a reservation
beanstalk.releases	int	the number of times a client has released this job from a reservation
beanstalk.buries	int	the number of times this job has been buried
beanstalk.kicks	int	the number of times this job has been kicked

42.5. Examples

This Camel component lets you both request the jobs for processing and supply them to Beanstalkd daemon. Our simple demo routes may look like

from("beanstalk:testTube").
   log("Processing job #${property.beanstalk.jobId} with body ${in.body}").
   process(new Processor() {
     @Override
     public void process(Exchange exchange) {
       // try to make integer value out of body
       exchange.getIn().setBody( Integer.valueOf(exchange.getIn().getBody(classOf[String])) );
     }
   }).
   log("Parsed job #${property.beanstalk.jobId} to body ${in.body}");

from("timer:dig?period=30seconds").
   setBody(constant(10)).log("Kick ${in.body} buried/delayed tasks").
   to("beanstalk:testTube?command=kick");

In the first route we are listening for new jobs in tube “testTube”. When they are arriving, we are trying to parse integer value from the message body. If done successful, we log it and this successful exchange completion makes Camel component to delete this job from Beanstalk automatically. Contrary, when we cannot parse the job data, the exchange failed and the Camel component buries it by default, so that it can be processed later or probably we are going to inspect failed jobs manually.

So the second route periodically requests Beanstalk to kick 10 jobs out of buried and/or delayed state to the normal queue.

42.6. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 43. Bean Validator Component

Available as of Camel version 2.3

The Validator component performs bean validation of the message body using the Java Bean Validation API (JSR 303). Camel uses the reference implementation, which is Hibernate Validator.

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

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

43.1. URI format

bean-validator:label[?options]

or

bean-validator://label[?options]

Where label is an arbitrary text value describing the endpoint.
You can append query options to the URI in the following format, ?option=value&option=value&…

43.2. URI Options

The Bean Validator component has no options.

The Bean Validator endpoint is configured using URI syntax:

bean-validator:label

with the following path and query parameters:

43.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
label	Required Where label is an arbitrary text value describing the endpoint		String

43.2.2. Query Parameters (6 parameters):

Name	Description	Default	Type
constraintValidatorFactory (producer)	To use a custom ConstraintValidatorFactory		ConstraintValidator Factory
group (producer)	To use a custom validation group	javax.validation.groups.Default	String
messageInterpolator (producer)	To use a custom MessageInterpolator		MessageInterpolator
traversableResolver (producer)	To use a custom TraversableResolver		TraversableResolver
validationProviderResolver (producer)	To use a a custom ValidationProviderResolver		ValidationProvider Resolver
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

43.3. OSGi deployment

To use Hibernate Validator in the OSGi environment use dedicated ValidationProviderResolver implementation, just as org.apache.camel.component.bean.validator.HibernateValidationProviderResolver. The snippet below demonstrates this approach. Keep in mind that you can use HibernateValidationProviderResolver starting from the Camel 2.13.0.

Using HibernateValidationProviderResolver

from("direct:test").
  to("bean-validator://ValidationProviderResolverTest?validationProviderResolver=#myValidationProviderResolver");

...

<bean id="myValidationProviderResolver" class="org.apache.camel.component.bean.validator.HibernateValidationProviderResolver"/>

If no custom ValidationProviderResolver is defined and the validator component has been deployed into the OSGi environment, the HibernateValidationProviderResolver will be automatically used.

43.4. Example

Assumed we have a java bean with the following annotations

Car.java

public class Car {

    @NotNull
    private String manufacturer;

    @NotNull
    @Size(min = 5, max = 14, groups = OptionalChecks.class)
    private String licensePlate;

    // getter and setter
}

and an interface definition for our custom validation group

OptionalChecks.java

public interface OptionalChecks {
}

with the following Camel route, only the @NotNull constraints on the attributes manufacturer and licensePlate will be validated (Camel uses the default group javax.validation.groups.Default).

from("direct:start")
.to("bean-validator://x")
.to("mock:end")

If you want to check the constraints from the group OptionalChecks, you have to define the route like this

from("direct:start")
.to("bean-validator://x?group=OptionalChecks")
.to("mock:end")

If you want to check the constraints from both groups, you have to define a new interface first

AllChecks.java

@GroupSequence({Default.class, OptionalChecks.class})
public interface AllChecks {
}

and then your route definition should looks like this

from("direct:start")
.to("bean-validator://x?group=AllChecks")
.to("mock:end")

And if you have to provide your own message interpolator, traversable resolver and constraint validator factory, you have to write a route like this

<bean id="myMessageInterpolator" class="my.ConstraintValidatorFactory" />
<bean id="myTraversableResolver" class="my.TraversableResolver" />
<bean id="myConstraintValidatorFactory" class="my.ConstraintValidatorFactory" />

from("direct:start")
.to("bean-validator://x?group=AllChecks&messageInterpolator=#myMessageInterpolator
&traversableResolver=#myTraversableResolver&constraintValidatorFactory=#myConstraintValidatorFactory")
.to("mock:end")

It’s also possible to describe your constraints as XML and not as Java annotations. In this case, you have to provide the file META-INF/validation.xml which could looks like this

validation.xml

<?xml version="1.0" encoding="UTF-8"?>
<validation-config
    xmlns="http://jboss.org/xml/ns/javax/validation/configuration"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/configuration">
    <default-provider>org.hibernate.validator.HibernateValidator</default-provider>
    <message-interpolator>org.hibernate.validator.engine.ResourceBundleMessageInterpolator</message-interpolator>
    <traversable-resolver>org.hibernate.validator.engine.resolver.DefaultTraversableResolver</traversable-resolver>
    <constraint-validator-factory>org.hibernate.validator.engine.ConstraintValidatorFactoryImpl</constraint-validator-factory>

    <constraint-mapping>/constraints-car.xml</constraint-mapping>
</validation-config>

and the constraints-car.xml file

constraints-car.xml

<?xml version="1.0" encoding="UTF-8"?>
<constraint-mappings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/mapping validation-mapping-1.0.xsd"
    xmlns="http://jboss.org/xml/ns/javax/validation/mapping">
    <default-package>org.apache.camel.component.bean.validator</default-package>

    <bean class="CarWithoutAnnotations" ignore-annotations="true">
        <field name="manufacturer">
            <constraint annotation="javax.validation.constraints.NotNull" />
        </field>

        <field name="licensePlate">
            <constraint annotation="javax.validation.constraints.NotNull" />

            <constraint annotation="javax.validation.constraints.Size">
                <groups>
                    <value>org.apache.camel.component.bean.validator.OptionalChecks</value>
                </groups>
                <element name="min">5</element>
                <element name="max">14</element>
            </constraint>
        </field>
    </bean>
</constraint-mappings>

Here is the XML syntax for the example route definition where OrderedChecks can be https://github.com/apache/camel/blob/master/components/camel-bean-validator/src/test/java/org/apache/camel/component/bean/validator/OrderedChecks.java

Note that the body should include an instance of a class to validate.

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="
    http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
    http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">

    <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
        <route>
            <from uri="direct:start"/>
            <to uri="bean-validator://x?group=org.apache.camel.component.bean.validator.OrderedChecks"/>
        </route>
    </camelContext>
</beans>

43.5. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 44. Binding Component (deprecated)

Available as of Camel version 2.11

In Camel terms a binding is a way of wrapping an Endpoint in a contract; such as a Data Format, a Content Enricher or validation step. Bindings are completely optional and you can choose to use them on any camel endpoint.

Bindings are inspired by the work of SwitchYard project adding service contracts to various technologies like Camel and many others. But rather than the SwitchYard approach of wrapping Camel in SCA, Camel Bindings provide a way of wrapping Camel endpoints with contracts inside the Camel framework itself; so you can use them easily inside any Camel route.

44.1. Options

The Binding component has no options.

The Binding endpoint is configured using URI syntax:

binding:bindingName:delegateUri

with the following path and query parameters:

44.1.1. Path Parameters (2 parameters):

Name	Description	Default	Type
bindingName	Required Name of the binding to lookup in the Camel registry.		String
delegateUri	Required Uri of the delegate endpoint.		String

44.1.2. Query Parameters (4 parameters):

Name	Description	Default	Type
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN/ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN/ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the default exchange pattern when creating an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

44.2. Using Bindings

A Binding is currently a bean which defines the contract (though we’ll hopefully add bindings to the Camel DSL).

There are a few approaches to defining a bound endpoint (i.e. an endpoint bound with a Binding).

44.3. Using the binding URI

You can prefix any endpoint URI with binding:nameOfBinding: where nameOfBinding is the name of the Binding bean in your registry.

from("binding:jaxb:activemq:myQueue").to("binding:jaxb:activemq:anotherQueue")

Here we are using the "jaxb" binding which may, for example, use the JAXB Data Format to marshal and unmarshal messages.

44.4. Using a BindingComponent

There is a Component called BindingComponent which can be configured in your Registry by dependency injection which allows the creation of endpoints which are already bound to some binding.

For example if you registered a new component called "jsonmq" in your registry using code like this

JacksonDataFormat format = new JacksonDataFormat(MyBean.class);
context.bind("jsonmq", new BindingComponent(new DataFormatBinding(format), "activemq:foo."));

Then you could use the endpoint as if it were any other endpoint.

from("jsonmq:myQueue").to("jsonmq:anotherQueue")

which would be using the queueus "foo.myQueue" and "foo.anotherQueue" and would use the given Jackson Data Format to marshal on and off the queue.

44.5. When to use Bindings

If you only use an endpoint once in a single route; a binding may actually be more complex and more work than just using the 'raw' endpoint directly and using explicit marshalling and validation in the camel route as normal.

However bindings can help when you are composing many routes together; or using a single route as a 'template' that is configured input and output endpoints; bindings then provide a nice way to wrap up a contract and endpoint together.

Another good use case for bindings is when you are using many endpoints which use the same binding; rather than always having to mention a specific data format or validation rule, you can just use the BindingComponent to wrap the endpoints in the binding of your choice.

So bindings are a composition tool really; only use them when they make sense - the extra complexity may not be worth it unless you have lots of routes or endpoints.

Chapter 45. Bindy DataFormat

Available as of Camel version 2.0

The goal of this component is to allow the parsing/binding of non-structured data (or to be more precise non-XML data)
to/from Java Beans that have binding mappings defined with annotations. Using Bindy, you can bind data from sources such as :

CSV records,
Fixed-length records,
FIX messages,
or almost any other non-structured data

to one or many Plain Old Java Object (POJO). Bindy converts the data according to the type of the java property. POJOs can be linked together with one-to-many relationships available in some cases. Moreover, for data type like Date, Double, Float, Integer, Short, Long and BigDecimal, you can provide the pattern to apply during the formatting of the property.

For the BigDecimal numbers, you can also define the precision and the decimal or grouping separators.

Type	Format Type	Pattern example	Link
Date	DateFormat	`dd-MM-yyyy`	http://java.sun.com/j2se/1.5.0/docs/api/java/text/SimpleDateFormat.html
Decimal*	Decimalformat	`..##`	http://java.sun.com/j2se/1.5.0/docs/api/java/text/DecimalFormat.html

Decimal* = Double, Integer, Float, Short, Long

*Format supported*

This first release only support comma separated values fields and key value pair fields (e.g. : FIX messages).

To work with camel-bindy, you must first define your model in a package (e.g. com.acme.model) and for each model class (e.g. Order, Client, Instrument, …) add the required annotations (described hereafter) to the Class or field.

*Multiple models*

If you use multiple models, each model has to be placed in it’s own package to prevent unpredictable results.

From Camel 2.16 onwards this is no longer the case, as you can safely have multiple models in the same package, as you configure bindy using class names instead of package names now.

45.1. Options

The Bindy dataformat supports 5 options which are listed below.

Name	Default	Java Type	Description
type		`BindyType`	Whether to use csv, fixed or key value pairs mode. The default value is either Csv or KeyValue depending on chosen dataformat.
classType		`String`	Name of model class to use.
locale		`String`	To configure a default locale to use, such as us for united states. To use the JVM platform default locale then use the name default
unwrapSingleInstance	`true`	`Boolean`	When unmarshalling should a single instance be unwrapped and returned instead of wrapped in a java.util.List.
contentTypeHeader	`false`	`Boolean`	Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.

45.2. Annotations

The annotations created allow to map different concept of your model to the POJO like :

Type of record (csv, key value pair (e.g. FIX message), fixed length …),
Link (to link object in another object),
DataField and their properties (int, type, …),
KeyValuePairField (for key = value format like we have in FIX financial messages),
Section (to identify header, body and footer section),
OneToMany,
BindyConverter (since 2.18.0),
FormatFactories (since 2.18.0)

This section will describe them :

45.3. 1. CsvRecord

The CsvRecord annotation is used to identified the root class of the model. It represents a record = a line of a CSV file and can be linked to several children model classes.

Annotation name	Record type	Level
CsvRecord	csv	Class

Parameter name	type	Info
separator	string	mandatory - can be ',' or ';' or 'anything'. This value is interpreted as a regular expression. If you want to use a sign which has a special meaning in regular expressions, e.g. the '\|' sign, than you have to mask it, like '\|'
skipFirstLine	boolean	optional - default value = false - allow to skip the first line of the CSV file
crlf	string	optional - possible values = WINDOWS,UNIX,MAC, or custom; default value. WINDOWS - allow to define the carriage return character to use. If you specify a value other than the three listed before, the value you enter (custom) will be used as the CRLF character(s)
generateHeaderColumns	boolean	optional - default value = false - uses to generate the header columns of the CSV generates
autospanLine	boolean	Camel 2.13/2.12.2: optional - default value = false - if enabled then the last column is auto spanned to end of line, for example if its a comment, etc this allows the line to contain all characters, also the delimiter char.
isOrdered	boolean	optional - default value = false - allow to change the order of the fields when CSV is generated
quote	String	Camel 2.8.3/2.9: option - allow to specify a quote character of the fields when CSV is generated. This annotation is associated to the root class of the model and must be declared one time.
quoting	boolean	Camel 2.11:optional - default value = false - Indicate if the values (and headers) must be quoted when marshaling when CSV is generated.
endWithLineBreak	boolean	Camel 2.21: optional - default value = true - Indicate if the CSV generated file should end with a line break.

case 1 : separator = ','

The separator used to segregate the fields in the CSV record is ',' :

10, J, Pauline, M, XD12345678, Fortis Dynamic 15/15, 2500,
USD,08-01-2009

@CsvRecord( separator = "," )
public Class Order {

}

case 2 : separator = ';'

Compare to the previous case, the separator here is ';' instead of ',' :

10; J; Pauline; M; XD12345678; Fortis Dynamic 15/15; 2500; USD; 08-01-2009

@CsvRecord( separator = ";" )
public Class Order {

}

case 3 : separator = '|'

Compare to the previous case, the separator here is '|' instead of ';' :

10| J| Pauline| M| XD12345678| Fortis Dynamic 15/15| 2500| USD|
08-01-2009

@CsvRecord( separator = "\\|" )
public Class Order {

}

case 4 : separator = '\",\"'

Applies for Camel 2.8.2 or older

When the field to be parsed of the CSV record contains ',' or ';' which is also used as separator, we whould find another strategy
to tell camel bindy how to handle this case. To define the field containing the data with a comma, you will use simple or double quotes
as delimiter (e.g : '10', 'Street 10, NY', 'USA' or "10", "Street 10, NY", "USA").
Remark : In this case, the first and last character of the line which are a simple or double quotes will removed by bindy

"10","J","Pauline"," M","XD12345678","Fortis Dynamic 15,15"
2500","USD","08-01-2009"

@CsvRecord( separator = "\",\"" )
public Class Order {

}

From Camel 2.8.3/2.9 or never bindy will automatic detect if the record is enclosed with either single or double quotes and automatic remove those quotes when unmarshalling from CSV to Object. Therefore do not include the quotes in the separator, but simple do as below:

"10","J","Pauline"," M","XD12345678","Fortis Dynamic 15,15"
2500","USD","08-01-2009"

@CsvRecord( separator = "," )
public Class Order {

}

Notice that if you want to marshal from Object to CSV and use quotes, then you need to specify which quote character to use, using the quote attribute on the @CsvRecord as shown below:

@CsvRecord( separator = ",", quote = "\"" )
public Class Order {

}

case 5 : separator & skipfirstline

The feature is interesting when the client wants to have in the first line of the file, the name of the data fields :

order id, client id, first name, last name, isin code, instrument name, quantity, currency, date

To inform bindy that this first line must be skipped during the parsing process, then we use the attribute :

@CsvRecord(separator = ",", skipFirstLine = true)
public Class Order {

}

case 6 : generateHeaderColumns

To add at the first line of the CSV generated, the attribute generateHeaderColumns must be set to true in the annotation like this :

@CsvRecord( generateHeaderColumns = true )
public Class Order {

}

As a result, Bindy during the unmarshaling process will generate CSV like this :

order id, client id, first name, last name, isin code, instrument name, quantity, currency, date

10, J, Pauline, M, XD12345678, Fortis Dynamic 15/15, 2500, USD,08-01-2009

case 7 : carriage return

If the platform where camel-bindy will run is not Windows but Macintosh or Unix, than you can change the crlf property like this. Three values are available : WINDOWS, UNIX or MAC

@CsvRecord(separator = ",", crlf="MAC")
public Class Order {

}

Additionally, if for some reason you need to add a different line ending character, you can opt to specify it using the crlf parameter. In the following example, we can end the line with a comma followed by the newline character:

@CsvRecord(separator = ",", crlf=",\n")
public Class Order {

}

case 8 : isOrdered

Sometimes, the order to follow during the creation of the CSV record from the model is different from the order used during the parsing. Then, in this case, we can use the attribute isOrdered = true to indicate this in combination with attribute 'position' of the DataField annotation.

@CsvRecord(isOrdered = true)
public Class Order {

   @DataField(pos = 1, position = 11)
   private int orderNr;

   @DataField(pos = 2, position = 10)
   private String clientNr;

}

Remark : pos is used to parse the file, stream while positions is used to generate the CSV

45.4. 2. Link

The link annotation will allow to link objects together.

Annotation name	Record type	Level
Link	all	Class & Property

Parameter name	type	Info
linkType	LinkType	optional - by default the value is LinkType.oneToOne - so you are not obliged to mention it

Only one-to-one relation is allowed.

e.g : If the model Class Client is linked to the Order class, then use annotation Link in the Order class like this :

Property Link

@CsvRecord(separator = ",")
public class Order {

    @DataField(pos = 1)
    private int orderNr;

    @Link
    private Client client;
}

AND for the class Client :

Class Link

@Link
public class Client {

}

45.5. 3. DataField

The DataField annotation defines the property of the field. Each datafield is identified by its position in the record, a type (string, int, date, …) and optionally of a pattern

Annotation name	Record type	Level
DataField	all	Property

Parameter name	type	Info
pos	int	mandatory - The input position of the field. digit number starting from 1 to … - See the position parameter.
pattern	string	optional - default value = "" - will be used to format Decimal, Date,
length	int	optional - represents the length of the field for fixed length format
precision	int	optional - represents the precision to be used when the Decimal number will be formatted/parsed
pattern	string	optional - default value = "" - is used by the Java formatter (SimpleDateFormat by example) to format/validate data. If using pattern, then setting locale on bindy data format is recommended. Either set to a known locale such as "us" or use "default" to use platform default locale. Notice that "default" requires Camel 2.14/2.13.3/2.12.5.
position	int	optional - must be used when the position of the field in the CSV generated (output message) must be different compare to input position (pos). See the pos parameter.
required	boolean	optional - default value = "false"
trim	boolean	optional - default value = "false"
defaultValue	string	Camel 2.10: optional - default value = "" - defines the field’s default value when the respective CSV field is empty/not available
impliedDecimalSeparator	boolean	Camel 2.11: optional - default value = "false" - Indicates if there is a decimal point implied at a specified location
lengthPos	int	Camel 2.11: optional - can be used to identify a data field in a fixed-length record that defines the fixed length for this field
align	string	optional - default value = "R" - Align the text to the right or left within a fixed-length field. Use values 'R' or 'L'
delimiter	string	Camel 2.11: optional - can be used to demarcate the end of a variable-length field within a fixed-length record

case 1 : pos

This parameter/attribute represents the position of the field in the csv record

Position

@CsvRecord(separator = ",")
public class Order {

    @DataField(pos = 1)
    private int orderNr;

    @DataField(pos = 5)
    private String isinCode;

}

As you can see in this example the position starts at '1' but continues at '5' in the class Order. The numbers from '2' to '4' are defined in the class Client (see here after).

Position continues in another model class

public class Client {

    @DataField(pos = 2)
    private String clientNr;

    @DataField(pos = 3)
    private String firstName;

    @DataField(pos = 4)
    private String lastName;
}

case 2 : pattern

The pattern allows to enrich or validates the format of your data

Pattern

@CsvRecord(separator = ",")
public class Order {

    @DataField(pos = 1)
    private int orderNr;

    @DataField(pos = 5)
    private String isinCode;

    @DataField(name = "Name", pos = 6)
    private String instrumentName;

    @DataField(pos = 7, precision = 2)
    private BigDecimal amount;

    @DataField(pos = 8)
    private String currency;

    // pattern used during parsing or when the date is created
    @DataField(pos = 9, pattern = "dd-MM-yyyy")
    private Date orderDate;
}

case 3 : precision

The precision is helpful when you want to define the decimal part of your number

Precision

@CsvRecord(separator = ",")
public class Order {

    @DataField(pos = 1)
    private int orderNr;

    @Link
    private Client client;

    @DataField(pos = 5)
    private String isinCode;

    @DataField(name = "Name", pos = 6)
    private String instrumentName;

    @DataField(pos = 7, precision = 2)
    private BigDecimal amount;

    @DataField(pos = 8)
    private String currency;

    @DataField(pos = 9, pattern = "dd-MM-yyyy")
    private Date orderDate;
}

case 4 : Position is different in output

The position attribute will inform bindy how to place the field in the CSV record generated. By default, the position used corresponds to the position defined with the attribute 'pos'. If the position is different (that means that we have an asymetric processus comparing marshaling from unmarshaling) than we can use 'position' to indicate this.

Here is an example

Position is different in output

@CsvRecord(separator = ",", isOrdered = true)
public class Order {

    // Positions of the fields start from 1 and not from 0

    @DataField(pos = 1, position = 11)
    private int orderNr;

    @DataField(pos = 2, position = 10)
    private String clientNr;

    @DataField(pos = 3, position = 9)
    private String firstName;

    @DataField(pos = 4, position = 8)
    private String lastName;

    @DataField(pos = 5, position = 7)
    private String instrumentCode;

    @DataField(pos = 6, position = 6)
    private String instrumentNumber;
}

This attribute of the annotation @DataField must be used in combination with attribute isOrdered = true of the annotation @CsvRecord

case 5 : required

If a field is mandatory, simply use the attribute 'required' setted to true

Required

@CsvRecord(separator = ",")
public class Order {

    @DataField(pos = 1)
    private int orderNr;

    @DataField(pos = 2, required = true)
    private String clientNr;

    @DataField(pos = 3, required = true)
    private String firstName;

    @DataField(pos = 4, required = true)
    private String lastName;
}

If this field is not present in the record, than an error will be raised by the parser with the following information :

Some fields are missing (optional or mandatory), line :

case 6 : trim

If a field has leading and/or trailing spaces which should be removed before they are processed, simply use the attribute 'trim' setted to true

Trim

@CsvRecord(separator = ",")
public class Order {

    @DataField(pos = 1, trim = true)
    private int orderNr;

    @DataField(pos = 2, trim = true)
    private Integer clientNr;

    @DataField(pos = 3, required = true)
    private String firstName;

    @DataField(pos = 4)
    private String lastName;
}

case 7 : defaultValue

If a field is not defined then uses the value indicated by the defaultValue attribute

Default value

@CsvRecord(separator = ",")
public class Order {

    @DataField(pos = 1)
    private int orderNr;

    @DataField(pos = 2)
    private Integer clientNr;

    @DataField(pos = 3, required = true)
    private String firstName;

    @DataField(pos = 4, defaultValue = "Barin")
    private String lastName;
}

This attribute is only applicable to optional fields.

45.6. 4. FixedLengthRecord

The FixedLengthRecord annotation is used to identified the root class of the model. It represents a record = a line of a file/message containing data fixed length formatted and can be linked to several children model classes. This format is a bit particular beause data of a field can be aligned to the right or to the left.
When the size of the data does not fill completely the length of the field, we can then add 'padd' characters.

Annotation name	Record type	Level
FixedLengthRecord	fixed	Class

Parameter name	type	Info
crlf	string	optional - possible values = WINDOWS,UNIX,MAC, or custom; default value. WINDOWS - allow to define the carriage return character to use. If you specify a value other than the three listed before, the value you enter (custom) will be used as the CRLF character(s). This option is used only during marshalling, whereas unmarshalling uses system default JDK provided line delimiter unless eol is customized
eol	string	optional - default="" which is empty string. Character to be used to process considering end of line after each record while unmarshalling (optional - default = "" which help default JDK provided line delimiter to be used unless any other line delimiter provided). This option is used only during unmarshalling, where marshalling uses system default provided line delimiter as "WINDOWS" unless any other value is provided
paddingChar	char	mandatory - default value = ' '
length	int	mandatory = size of the fixed length record
hasHeader	boolean	Camel 2.11 - optional - Indicates that the record(s) of this type may be preceded by a single header record at the beginning of the file / stream
hasFooter	boolean	Camel 2.11 - optional - Indicates that the record(s) of this type may be followed by a single footer record at the end of the file / stream
skipHeader	boolean	Camel 2.11 - optional - Configures the data format to skip marshalling / unmarshalling of the header record. Configure this parameter on the primary record (e.g., not the header or footer).
skipFooter	boolean	Camel 2.11 - optional - Configures the data format to skip marshalling / unmarshalling of the footer record Configure this parameter on the primary record (e.g., not the header or footer)..
isHeader	boolean	Camel 2.11 - optional - Identifies this FixedLengthRecord as a header record
isFooter	boolean	Camel 2.11 - optional - Identifies this FixedLengthRecords as a footer record
ignoreTrailingChars	boolean	Camel 2.11.1 - optional - Indicates that characters beyond the last mapped filed can be ignored when unmarshalling / parsing. This annotation is associated to the root class of the model and must be declared one time.

The hasHeader/hasFooter parameters are mutually exclusive with isHeader/isFooter. A record may not be both a header/footer and a primary fixed-length record.

case 1 : Simple fixed length record

This simple example shows how to design the model to parse/format a fixed message

10A9PaulineMISINXD12345678BUYShare2500.45USD01-08-2009

Fixed-simple

@FixedLengthRecord(length=54, paddingChar=' ')
public static class Order {

    @DataField(pos = 1, length=2)
    private int orderNr;

    @DataField(pos = 3, length=2)
    private String clientNr;

    @DataField(pos = 5, length=7)
    private String firstName;

    @DataField(pos = 12, length=1, align="L")
    private String lastName;

    @DataField(pos = 13, length=4)
    private String instrumentCode;

    @DataField(pos = 17, length=10)
    private String instrumentNumber;

    @DataField(pos = 27, length=3)
    private String orderType;

    @DataField(pos = 30, length=5)
    private String instrumentType;

    @DataField(pos = 35, precision = 2, length=7)
    private BigDecimal amount;

    @DataField(pos = 42, length=3)
    private String currency;

    @DataField(pos = 45, length=10, pattern = "dd-MM-yyyy")
    private Date orderDate;
}

case 2 : Fixed length record with alignment and padding

This more elaborated example show how to define the alignment for a field and how to assign a padding character which is ' ' here''

10A9 PaulineM ISINXD12345678BUYShare2500.45USD01-08-2009

Fixed-padding-align

@FixedLengthRecord(length=60, paddingChar=' ')
public static class Order {

    @DataField(pos = 1, length=2)
    private int orderNr;

    @DataField(pos = 3, length=2)
    private String clientNr;

    @DataField(pos = 5, length=9)
    private String firstName;

    @DataField(pos = 14, length=5, align="L")   // align text to the LEFT zone of the block
    private String lastName;

    @DataField(pos = 19, length=4)
    private String instrumentCode;

    @DataField(pos = 23, length=10)
    private String instrumentNumber;

    @DataField(pos = 33, length=3)
    private String orderType;

    @DataField(pos = 36, length=5)
    private String instrumentType;

    @DataField(pos = 41, precision = 2, length=7)
    private BigDecimal amount;

    @DataField(pos = 48, length=3)
    private String currency;

    @DataField(pos = 51, length=10, pattern = "dd-MM-yyyy")
    private Date orderDate;
}

case 3 : Field padding

Sometimes, the default padding defined for record cannnot be applied to the field as we have a number format where we would like to padd with '0' instead of ' '. In this case, you can use in the model the attribute paddingField to set this value.

10A9 PaulineM ISINXD12345678BUYShare000002500.45USD01-08-2009

Fixed-padding-field

@FixedLengthRecord(length = 65, paddingChar = ' ')
public static class Order {

    @DataField(pos = 1, length = 2)
    private int orderNr;

    @DataField(pos = 3, length = 2)
    private String clientNr;

    @DataField(pos = 5, length = 9)
    private String firstName;

    @DataField(pos = 14, length = 5, align = "L")
    private String lastName;

    @DataField(pos = 19, length = 4)
    private String instrumentCode;

    @DataField(pos = 23, length = 10)
    private String instrumentNumber;

    @DataField(pos = 33, length = 3)
    private String orderType;

    @DataField(pos = 36, length = 5)
    private String instrumentType;

    @DataField(pos = 41, precision = 2, length = 12, paddingChar = '0')
    private BigDecimal amount;

    @DataField(pos = 53, length = 3)
    private String currency;

    @DataField(pos = 56, length = 10, pattern = "dd-MM-yyyy")
    private Date orderDate;
}

case 4: Fixed length record with delimiter

Fixed-length records sometimes have delimited content within the record. The firstName and lastName fields are delimited with the '^' character in the following example:

10A9Pauline^M^ISINXD12345678BUYShare000002500.45USD01-08-2009

Fixed-delimited

@FixedLengthRecord()
public static class Order {

    @DataField(pos = 1, length = 2)
    private int orderNr;

    @DataField(pos = 2, length = 2)
    private String clientNr;

    @DataField(pos = 3, delimiter = "^")
    private String firstName;

    @DataField(pos = 4, delimiter = "^")
    private String lastName;

    @DataField(pos = 5, length = 4)
    private String instrumentCode;

    @DataField(pos = 6, length = 10)
    private String instrumentNumber;

    @DataField(pos = 7, length = 3)
    private String orderType;

    @DataField(pos = 8, length = 5)
    private String instrumentType;

    @DataField(pos = 9, precision = 2, length = 12, paddingChar = '0')
    private BigDecimal amount;

    @DataField(pos = 10, length = 3)
    private String currency;

    @DataField(pos = 11, length = 10, pattern = "dd-MM-yyyy")
    private Date orderDate;
}

As of Camel 2.11 the 'pos' value(s) in a fixed-length record may optionally be defined using ordinal, sequential values instead of precise column numbers.

case 5 : Fixed length record with record-defined field length

Occasionally a fixed-length record may contain a field that define the expected length of another field within the same record. In the following example the length of the instrumentNumber field value is defined by the value of instrumentNumberLen field in the record.

10A9Pauline^M^ISIN10XD12345678BUYShare000002500.45USD01-08-2009

Fixed-delimited

@FixedLengthRecord()
public static class Order {

    @DataField(pos = 1, length = 2)
    private int orderNr;

    @DataField(pos = 2, length = 2)
    private String clientNr;

    @DataField(pos = 3, delimiter = "^")
    private String firstName;

    @DataField(pos = 4, delimiter = "^")
    private String lastName;

    @DataField(pos = 5, length = 4)
    private String instrumentCode;

    @DataField(pos = 6, length = 2, align = "R", paddingChar = '0')
    private int instrumentNumberLen;

    @DataField(pos = 7, lengthPos=6)
    private String instrumentNumber;

    @DataField(pos = 8, length = 3)
    private String orderType;

    @DataField(pos = 9, length = 5)
    private String instrumentType;

    @DataField(pos = 10, precision = 2, length = 12, paddingChar = '0')
    private BigDecimal amount;

    @DataField(pos = 11, length = 3)
    private String currency;

    @DataField(pos = 12, length = 10, pattern = "dd-MM-yyyy")
    private Date orderDate;
}

case 6 : Fixed length record with header and footer

Bindy will discover fixed-length header and footer records that are configured as part of the model – provided that the annotated classes exist either in the same package as the primary @FixedLengthRecord class, or within one of the configured scan packages. The following text illustrates two fixed-length records that are bracketed by a header record and footer record.

101-08-2009
10A9 PaulineM ISINXD12345678BUYShare000002500.45USD01-08-2009
10A9 RichN ISINXD12345678BUYShare000002700.45USD01-08-2009
9000000002

Fixed-header-and-footer-main-class

@FixedLengthRecord(hasHeader = true, hasFooter = true)
public class Order {

    @DataField(pos = 1, length = 2)
    private int orderNr;

    @DataField(pos = 2, length = 2)
    private String clientNr;

    @DataField(pos = 3, length = 9)
    private String firstName;

    @DataField(pos = 4, length = 5, align = "L")
    private String lastName;

    @DataField(pos = 5, length = 4)
    private String instrumentCode;

    @DataField(pos = 6, length = 10)
    private String instrumentNumber;

    @DataField(pos = 7, length = 3)
    private String orderType;

    @DataField(pos = 8, length = 5)
    private String instrumentType;

    @DataField(pos = 9, precision = 2, length = 12, paddingChar = '0')
    private BigDecimal amount;

    @DataField(pos = 10, length = 3)
    private String currency;

    @DataField(pos = 11, length = 10, pattern = "dd-MM-yyyy")
    private Date orderDate;
}

@FixedLengthRecord(isHeader = true)
public  class OrderHeader {
    @DataField(pos = 1, length = 1)
    private int recordType = 1;

    @DataField(pos = 2, length = 10, pattern = "dd-MM-yyyy")
    private Date recordDate;
}

@FixedLengthRecord(isFooter = true)
public class OrderFooter {

    @DataField(pos = 1, length = 1)
    private int recordType = 9;

    @DataField(pos = 2, length = 9, align = "R", paddingChar = '0')
    private int numberOfRecordsInTheFile;
}

case 7 : Skipping content when parsing a fixed length record. (Camel 2.11.1)

It is common to integrate with systems that provide fixed-length records containing more information than needed for the target use case. It is useful in this situation to skip the declaration and parsing of those fields that we do not need. To accomodate this, Bindy will skip forward to the next mapped field within a record if the 'pos' value of the next declared field is beyond the cursor position of the last parsed field. Using absolute 'pos' locations for the fields of interest (instead of ordinal values) causes Bindy to skip content between two fields.

Similarly, it is possible that none of the content beyond some field is of interest. In this case, you can tell Bindy to skip parsing of everything beyond the last mapped field by setting the ignoreTrailingChars property on the @FixedLengthRecord declaration.

@FixedLengthRecord(ignoreTrailingChars = true)
public static class Order {

    @DataField(pos = 1, length = 2)
    private int orderNr;

    @DataField(pos = 3, length = 2)
    private String clientNr;

    // any characters that appear beyond the last mapped field will be ignored

}

45.7. 5. Message

The Message annotation is used to identified the class of your model who will contain key value pairs fields. This kind of format is used mainly in Financial Exchange Protocol Messages (FIX). Nevertheless, this annotation can be used for any other format where data are identified by keys. The key pair values are separated each other by a separator which can be a special character like a tab delimitor (unicode representation : \u0009) or a start of heading (unicode representation : \u0001)

*"FIX information"*

More information about FIX can be found on this web site : http://www.fixprotocol.org/. To work with FIX messages, the model must contain a Header and Trailer classes linked to the root message class which could be a Order class. This is not mandatory but will be very helpful when you will use camel-bindy in combination with camel-fix which is a Fix gateway based on quickFix project http://www.quickfixj.org/.

Annotation name	Record type	Level
Message	key value pair	Class

Parameter name	type	Info
pairSeparator	string	mandatory - can be '=' or ';' or 'anything'
keyValuePairSeparair	string	mandatory - can be '\u0001', '\u0009', '#' or 'anything'
crlf	string	optional - possible values = WINDOWS,UNIX,MAC, or custom; default value = WINDOWS - allow to define the carriage return character to use. If you specify a value other than the three listed before, the value you enter (custom) will be used as the CRLF character(s)
type	string	optional - define the type of message (e.g. FIX, EMX, …)
version	string	optional - version of the message (e.g. 4.1)
isOrdered	boolean	optional - default value = false - allow to change the order of the fields when FIX message is generated. This annotation is associated to the message class of the model and must be declared one time.

case 1 : separator = 'u0001'

The separator used to segregate the key value pair fields in a FIX message is the ASCII '01' character or in unicode format '\u0001'. This character must be escaped a second time to avoid a java runtime error. Here is an example :

8=FIX.4.1 9=20 34=1 35=0 49=INVMGR 56=BRKR 1=BE.CHM.001 11=CHM0001-01
22=4 ...

and how to use the annotation

FIX - message

@Message(keyValuePairSeparator = "=", pairSeparator = "\u0001", type="FIX", version="4.1")
public class Order {

}

*Look at test cases*

The ASCII character like tab, … cannot be displayed in WIKI page. So, have a look to the test case of camel-bindy to see exactly how the FIX message looks like (src\test\data\fix\fix.txt) and the Order, Trailer, Header classes (src\test\java\org\apache\camel\dataformat\bindy\model\fix\simple\Order.java)

45.8. 6. KeyValuePairField

The KeyValuePairField annotation defines the property of a key value pair field. Each KeyValuePairField is identified by a tag (= key) and its value associated, a type (string, int, date, …), optionaly a pattern and if the field is required

Annotation name	Record type	Level
KeyValuePairField	Key Value Pair - FIX	Property

Parameter name	type	Info
tag	int	mandatory - digit number identifying the field in the message - must be unique
pattern	string	optional - default value = "" - will be used to format Decimal, Date, …
precision	int	optional - digit number - represents the precision to be used when the Decimal number will be formatted/parsed
position	int	optional - must be used when the position of the key/tag in the FIX message must be different
required	boolean	optional - default value = "false"
impliedDecimalSeparator	boolean	Camel 2.11: optional - default value = "false" - Indicates if there is a decimal point implied at a specified location

case 1 : tag

This parameter represents the key of the field in the message

FIX message - Tag

@Message(keyValuePairSeparator = "=", pairSeparator = "\u0001", type="FIX", version="4.1")
public class Order {

    @Link Header header;

    @Link Trailer trailer;

    @KeyValuePairField(tag = 1) // Client reference
    private String Account;

    @KeyValuePairField(tag = 11) // Order reference
    private String ClOrdId;

    @KeyValuePairField(tag = 22) // Fund ID type (Sedol, ISIN, ...)
    private String IDSource;

    @KeyValuePairField(tag = 48) // Fund code
    private String SecurityId;

    @KeyValuePairField(tag = 54) // Movement type ( 1 = Buy, 2 = sell)
    private String Side;

    @KeyValuePairField(tag = 58) // Free text
    private String Text;
}

case 2 : Different position in output

If the tags/keys that we will put in the FIX message must be sorted according to a predefine order, then use the attribute 'position' of the annotation @KeyValuePairField

FIX message - Tag - sort

@Message(keyValuePairSeparator = "=", pairSeparator = "\\u0001", type = "FIX", version = "4.1", isOrdered = true)
public class Order {

    @Link Header header;

    @Link Trailer trailer;

    @KeyValuePairField(tag = 1, position = 1) // Client reference
    private String account;

    @KeyValuePairField(tag = 11, position = 3) // Order reference
    private String clOrdId;
}

45.9. 7. Section

In FIX message of fixed length records, it is common to have different sections in the representation of the information : header, body and section. The purpose of the annotation @Section is to inform bindy about which class of the model represents the header (= section 1), body (= section 2) and footer (= section 3)

Only one attribute/parameter exists for this annotation.

Annotation name	Record type	Level
Section	FIX	Class

Parameter name	type	Info
number	int	digit number identifying the section position

case 1 : Section

Definition of the header section

FIX message - Section - Header

@Section(number = 1)
public class Header {

    @KeyValuePairField(tag = 8, position = 1) // Message Header
    private String beginString;

    @KeyValuePairField(tag = 9, position = 2) // Checksum
    private int bodyLength;
}

Definition of the body section

FIX message - Section - Body

@Section(number = 2)
@Message(keyValuePairSeparator = "=", pairSeparator = "\\u0001", type = "FIX", version = "4.1", isOrdered = true)
public class Order {

    @Link Header header;

    @Link Trailer trailer;

    @KeyValuePairField(tag = 1, position = 1) // Client reference
    private String account;

    @KeyValuePairField(tag = 11, position = 3) // Order reference
    private String clOrdId;

Definition of the footer section

FIX message - Section - Footer

@Section(number = 3)
public class Trailer {

    @KeyValuePairField(tag = 10, position = 1)
    // CheckSum
    private int checkSum;

    public int getCheckSum() {
        return checkSum;
    }

45.10. 8. OneToMany

The purpose of the annotation @OneToMany is to allow to work with a List<?> field defined a POJO class or from a record containing repetitive groups.

*Restrictions OneToMany*

Be careful, the one to many of bindy does not allow to handle repetitions defined on several levels of the hierarchy

The relation OneToMany ONLY WORKS in the following cases :

Reading a FIX message containing repetitive groups (= group of tags/keys)
Generating a CSV with repetitive data

Annotation name	Record type	Level
OneToMany	all	property

Parameter name	type	Info
mappedTo	string	optional - string - class name associated to the type of the List<Type of the Class>

case 1 : Generating CSV with repetitive data

Here is the CSV output that we want :

Claus,Ibsen,Camel in Action 1,2010,35
Claus,Ibsen,Camel in Action 2,2012,35
Claus,Ibsen,Camel in Action 3,2013,35
Claus,Ibsen,Camel in Action 4,2014,35

Remark : the repetitive data concern the title of the book and its publication date while first, last name and age are common

and the classes used to modeling this. The Author class contains a List of Book.

Generate CSV with repetitive data

@CsvRecord(separator=",")
public class Author {

    @DataField(pos = 1)
    private String firstName;

    @DataField(pos = 2)
    private String lastName;

    @OneToMany
    private List<Book> books;

    @DataField(pos = 5)
    private String Age;
}

public class Book {

    @DataField(pos = 3)
    private String title;

    @DataField(pos = 4)
    private String year;
}

Very simple isn’t it !!!

case 2 : Reading FIX message containing group of tags/keys

Here is the message that we would like to process in our model :

8=FIX 4.19=2034=135=049=INVMGR56=BRKR
1=BE.CHM.00111=CHM0001-0158=this is a camel - bindy test
22=448=BE000124567854=1
22=548=BE000987654354=2
22=648=BE000999999954=3
10=220

tags 22, 48 and 54 are repeated

and the code

Reading FIX message containing group of tags/keys

public class Order {

    @Link Header header;

    @Link Trailer trailer;

    @KeyValuePairField(tag = 1) // Client reference
    private String account;

    @KeyValuePairField(tag = 11) // Order reference
    private String clOrdId;

    @KeyValuePairField(tag = 58) // Free text
    private String text;

    @OneToMany(mappedTo = "org.apache.camel.dataformat.bindy.model.fix.complex.onetomany.Security")
    List<Security> securities;
}

public class Security {

    @KeyValuePairField(tag = 22) // Fund ID type (Sedol, ISIN, ...)
    private String idSource;

    @KeyValuePairField(tag = 48) // Fund code
    private String securityCode;

    @KeyValuePairField(tag = 54) // Movement type ( 1 = Buy, 2 = sell)
    private String side;
}

45.11. 9. BindyConverter

The purpose of the annotation @BindyConverter is define a converter to be used on field level. The provided class must implement the Format interface.

@FixedLengthRecord(length = 10, paddingChar = ' ')
public static class DataModel {
    @DataField(pos =  1, length = 10, trim = true)
    @BindyConverter(CustomConverter.class)
    public String field1;
}

public static class CustomConverter implements Format<String> {
    @Override
    public String format(String object) throws Exception {
        return (new StringBuilder(object)).reverse().toString();
    }

    @Override
    public String parse(String string) throws Exception {
        return (new StringBuilder(string)).reverse().toString();
    }
}

45.12. 10. FormatFactories

The purpose of the annotation @FormatFactories is to define a set of converters at record-level. The provided classes must implement the FormatFactoryInterface interface.

@CsvRecord(separator = ",")
@FormatFactories({OrderNumberFormatFactory.class})
public static class Order {

    @DataField(pos = 1)
    private OrderNumber orderNr;

    @DataField(pos = 2)
    private String firstName;
}

public static class OrderNumber {
    private int orderNr;

    public static OrderNumber ofString(String orderNumber) {
        OrderNumber result = new OrderNumber();
        result.orderNr = Integer.valueOf(orderNumber);
        return result;
    }
}

public static class OrderNumberFormatFactory extends AbstractFormatFactory {

    {
        supportedClasses.add(OrderNumber.class);
    }

    @Override
    public Format<?> build(FormattingOptions formattingOptions) {
        return new Format<OrderNumber>() {
            @Override
            public String format(OrderNumber object) throws Exception {
                return String.valueOf(object.orderNr);
            }

            @Override
            public OrderNumber parse(String string) throws Exception {
                return OrderNumber.ofString(string);
            }
        };
    }
}

45.13. Supported Datatypes

The DefaultFormatFactory makes formatting of the following datatype available by returning an instance of the interface FormatFactoryInterface based on the provided FormattingOptions:

BigDecimal
BigInteger
Boolean
Byte
Character
Date
Double
Enums
Float
Integer
LocalDate (java 8, since 2.18.0)
LocalDateTime (java 8, since 2.18.0)
LocalTime (java 8, since 2.18.0)
Long
Short
String

The DefaultFormatFactory can be overridden by providing an instance of FactoryRegistry in the registry in use (e.g. spring or JNDI).

45.14. Using the Java DSL

The next step consists in instantiating the DataFormat bindy class associated with this record type and providing Java package name(s) as parameter.

For example the following uses the class BindyCsvDataFormat (who correspond to the class associated with the CSV record type) which is configured with com.acme.model package name to initialize the model objects configured in this package.

// Camel 2.15 or older (configure by package name)
DataFormat bindy = new BindyCsvDataFormat("com.acme.model");

 
// Camel 2.16 onwards (configure by class name)
DataFormat bindy = new BindyCsvDataFormat(com.acme.model.MyModel.class);

45.14.1. Setting locale

Bindy supports configuring the locale on the dataformat, such as

// Camel 2.15 or older (configure by package name)
BindyCsvDataFormat bindy = new BindyCsvDataFormat("com.acme.model");
// Camel 2.16 onwards (configure by class name)
BindyCsvDataFormat bindy = new BindyCsvDataFormat(com.acme.model.MyModel.class);

bindy.setLocale("us");

Or to use the platform default locale then use "default" as the locale name. Notice this requires Camel 2.14/2.13.3/2.12.5.

// Camel 2.15 or older (configure by package name)
BindyCsvDataFormat bindy = new BindyCsvDataFormat("com.acme.model");
// Camel 2.16 onwards (configure by class name)
BindyCsvDataFormat bindy = new BindyCsvDataFormat(com.acme.model.MyModel.class);

bindy.setLocale("default");

for older releases you can set it using Java code as shown

// Camel 2.15 or older (configure by package name)
BindyCsvDataFormat bindy = new BindyCsvDataFormat("com.acme.model");
// Camel 2.16 onwards (configure by class name)
BindyCsvDataFormat bindy = new BindyCsvDataFormat(com.acme.model.MyModel.class);

bindy.setLocale(Locale.getDefault().getISO3Country());

45.14.2. Unmarshaling

from("file://inbox")
  .unmarshal(bindy)
  .to("direct:handleOrders");

Alternatively, you can use a named reference to a data format which can then be defined in your Registry e.g. your Spring XML file:

from("file://inbox")
  .unmarshal("myBindyDataFormat")
  .to("direct:handleOrders");

The Camel route will pick-up files in the inbox directory, unmarshall CSV records into a collection of model objects and send the collection
to the route referenced by 'handleOrders'.

The collection returned is a List of Map objects. Each Map within the list contains the model objects that were marshalled out of each line of the CSV. The reason behind this is that each line can correspond to more than one object. This can be confusing when you simply expect one object to be returned per line.

Each object can be retrieve using its class name.

List<Map<String, Object>> unmarshaledModels = (List<Map<String, Object>>) exchange.getIn().getBody();

int modelCount = 0;
for (Map<String, Object> model : unmarshaledModels) {
  for (String className : model.keySet()) {
     Object obj = model.get(className);
     LOG.info("Count : " + modelCount + ", " + obj.toString());
  }
 modelCount++;
}

LOG.info("Total CSV records received by the csv bean : " + modelCount);

Assuming that you want to extract a single Order object from this map for processing in a route, you could use a combination of a Splitter and a Processor as per the following:

from("file://inbox")
    .unmarshal(bindy)
    .split(body())
        .process(new Processor() {
            public void process(Exchange exchange) throws Exception {
                Message in = exchange.getIn();
                Map<String, Object> modelMap = (Map<String, Object>) in.getBody();
                in.setBody(modelMap.get(Order.class.getCanonicalName()));
            }
        })
        .to("direct:handleSingleOrder")
    .end();

Take care of the fact that Bindy uses CHARSET_NAME property or the CHARSET_NAME header as define in the Exchange interface to do a characterset conversion of the inputstream received for unmarshalling. In some producers (e.g. file-endpoint) you can define a characterset. The characterset conversion can already been done by this producer. Sometimes you need to remove this property or header from the exchange before sending it to the unmarshal. If you don’t remove it the conversion might be done twice which might lead to unwanted results.

from("file://inbox?charset=Cp922")
  .removeProperty(Exchange.CHARSET_NAME)
  .unmarshal("myBindyDataFormat")
  .to("direct:handleOrders");

45.14.3. Marshaling

To generate CSV records from a collection of model objects, you create the following route :

from("direct:handleOrders")
   .marshal(bindy)
   .to("file://outbox")

45.15. Using Spring XML

This is really easy to use Spring as your favorite DSL language to declare the routes to be used for camel-bindy. The following example shows two routes where the first will pick-up records from files, unmarshal the content and bind it to their model. The result is then send to a pojo (doing nothing special) and place them into a queue.

The second route will extract the pojos from the queue and marshal the content to generate a file containing the csv record. The example above is for using Camel 2.16 onwards.

spring dsl

<?xml version="1.0" encoding="UTF-8"?>

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
       http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans.xsd
       http://camel.apache.org/schema/spring
       http://camel.apache.org/schema/spring/camel-spring.xsd">

    <!-- Queuing engine - ActiveMq - work locally in mode virtual memory -->
    <bean id="activemq" class="org.apache.activemq.camel.component.ActiveMQComponent">
        <property name="brokerURL" value="vm://localhost:61616"/>
    </bean>

    <camelContext xmlns="http://camel.apache.org/schema/spring">
        <dataFormats>
          <bindy id="bindyDataformat" type="Csv" classType="org.apache.camel.bindy.model.Order"/>
        </dataFormats>

        <route>
            <from uri="file://src/data/csv/?noop=true" />
            <unmarshal ref="bindyDataformat" />
            <to uri="bean:csv" />
            <to uri="activemq:queue:in" />
        </route>

        <route>
            <from uri="activemq:queue:in" />
            <marshal ref="bindyDataformat" />
            <to uri="file://src/data/csv/out/" />
        </route>
    </camelContext>
</beans>

Note

Please verify that your model classes implements serializable otherwise the queue manager will raise an error

45.16. Dependencies

To use Bindy in your camel routes you need to add the a dependency on camel-bindy 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).

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

Chapter 46. Using OSGi blueprint with Camel

A custom XML namespace for Blueprint has been created to let you leverage the nice XML dialect. Given Blueprint custom namespaces are not standardized yet, this namespace can only be used on the Apache Aries Blueprint implementation, which is the one used by Apache Karaf.

46.1. Overview

The XML schema is mostly the same as the one for Spring, so all the xml snippets throughout the documentation referring to Spring XML also apply to Blueprint routes.

Here is a very simple route definition using blueprint:

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

    <camelContext xmlns="http://camel.apache.org/schema/blueprint">
        <route>
            <from uri="timer:test" />
            <to uri="log:test" />
        </route>
    </camelContext>

</blueprint>

There are a few limitations at this point about the supported xml elements (compared to the Spring xml syntax):

beanPostProcessor are specific to Spring and aren’t allowed

However, using blueprint when you deploy your applications in an OSGi enviroment has several advantages:

when upgrading to a new camel version, you don’t have to change the namespace, as the correct version will be selected based on the camel packages that are imported by your bundle
no startup ordering issue with respect to the custom namespaces and your bundles
you can use Blueprint property placeholders

46.2. Using camel-blueprint

To leverage camel-blueprint in OSGi, you only need the Aries Blueprint bundle and the camel-blueprint bundle, in addition to camel-core and its dependencies.

If you use Karaf, you can use the feature named camel-blueprint which will install all the required bundles.

Chapter 47. Bonita Component

Available as of Camel version 2.19

Used for communicating with a remote Bonita BPM process engine.

47.1. URI format

bonita://[operation]?[options]

Where operation is the specific action to perform on Bonita.

47.2. General Options

The Bonita component has no options.

The Bonita endpoint is configured using URI syntax:

bonita:operation

with the following path and query parameters:

47.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
operation	Required Operation to use		BonitaOperation

47.2.2. Query Parameters (9 parameters):

Name	Description	Default	Type
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
hostname (consumer)	Hostname where Bonita engine runs	localhost	String
port (consumer)	Port of the server hosting Bonita engine	8080	String
processName (consumer)	Name of the process involved in the operation		String
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
password (security)	Password to authenticate to Bonita engine.		String
username (security)	Username to authenticate to Bonita engine.		String

47.3. Body content

For the startCase operation, the input variables are retrieved from the body message. This one has to contains a Map<String,Serializable>.

47.4. Examples

The following example start a new case in Bonita:

from("direct:start").to("bonita:startCase?hostname=localhost&amp;port=8080&amp;processName=TestProcess&amp;username=install&amp;password=install")

47.5. Dependencies

To use Bonita in your Camel routes you need to add a dependency on camel-bonita, which implements the component.

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

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

Chapter 48. Boon DataFormat

Available as of Camel version 2.16

Boon is a Data Format which uses the Boon JSON marshalling library to unmarshal an JSON payload into Java objects or to marshal Java objects into an JSON payload. Boon aims to be a simple and https://github.com/RichardHightower/json-parsers-benchmark[fast parser] than other common parsers currently used.

48.1. Options

The Boon dataformat supports 3 options which are listed below.

Name	Default	Java Type	Description
unmarshalTypeName		`String`	Class name of the java type to use when unarmshalling
useList	`false`	`Boolean`	To unarmshal to a List of Map or a List of Pojo.
contentTypeHeader	`false`	`Boolean`	Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.

48.2. Using the Java DSL

DataFormat boonDataFormat = new BoonDataFormat("com.acme.model.Person");

from("activemq:My.Queue")
  .unmarshal(boonDataFormat)
  .to("mqseries:Another.Queue");

48.3. Using Blueprint XML

<bean id="boonDataFormat" class="org.apache.camel.component.boon.BoonDataFormat">
  <argument value="com.acme.model.Person"/>
</bean>

<camelContext id="camel" xmlns="http://camel.apache.org/schema/blueprint">
  <route>
    <from uri="activemq:My.Queue"/>
    <unmarshal ref="boonDataFormat"/>
    <to uri="mqseries:Another.Queue"/>
  </route>
</camelContext>

48.4. Dependencies

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

Chapter 49. Box Component

Available as of Camel version 2.14

The Box component provides access to all of the Box.com APIs accessible using https://github.com/box/box-java-sdk. It allows producing messages to upload and download files, create, edit, and manage folders, etc. It also supports APIs that allow polling for updates to user accounts and even changes to enterprise accounts, etc.

Box.com requires the use of OAuth2.0 for all client application authentication. In order to use camel-box with your account, you’ll need to create a new application within Box.com at https://developer.box.com. The Box application’s client id and secret will allow access to Box APIs which require a current user. A user access token is generated and managed by the API for an end user.

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

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

49.1. Connection Authentication Types

The Box component supports three different types of authenticated connections.

49.1.1. Standard Authentication

Standard Authentication uses the OAuth 2.0 three-legged authentication process to authenticate its connections with Box.com. This type of authentication enables Box managed users and external users to access, edit, and save their Box content through the Box component.

49.1.2. App Enterprise Authentication

App Enterprise Authentication uses the OAuth 2.0 with JSON Web Tokens (JWT) to authenticate its connections as a Service Account for a Box Application. This type of authentication enables a service account to access, edit, and save the Box content of its Box Application through the Box component.

49.1.3. App User Authentication

App User Authentication uses the OAuth 2.0 with JSON Web Tokens (JWT) to authenticate its connections as an App User for a Box Application. This type of authentication enables app users to access, edit, and save their Box content in its Box Application through the Box component.

49.2. Box Options

The Box component supports 2 options which are listed below.

Name	Description	Default	Type
configuration (common)	To use the shared configuration		BoxConfiguration
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Box endpoint is configured using URI syntax:

box:apiName/methodName

with the following path and query parameters:

49.2.1. Path Parameters (2 parameters):

Name	Description	Default	Type
apiName	Required What kind of operation to perform		BoxApiName
methodName	Required What sub operation to use for the selected operation		String

49.2.2. Query Parameters (20 parameters):

Name	Description	Default	Type
clientId (common)	Box application client ID		String
enterpriseId (common)	The enterprise ID to use for an App Enterprise.		String
inBody (common)	Sets the name of a parameter to be passed in the exchange In Body		String
userId (common)	The user ID to use for an App User.		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
httpParams (advanced)	Custom HTTP params for settings like proxy host		Map
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
accessTokenCache (security)	Custom Access Token Cache for storing and retrieving access tokens.		IAccessTokenCache
clientSecret (security)	Box application client secret		String
encryptionAlgorithm (security)	The type of encryption algorithm for JWT. Supported Algorithms: RSA_SHA_256 RSA_SHA_384 RSA_SHA_512	RSA_SHA_256	EncryptionAlgorithm
maxCacheEntries (security)	The maximum number of access tokens in cache.	100	int
authenticationType (authentication)	The type of authentication for connection. Types of Authentication: STANDARD_AUTHENTICATION - OAuth 2.0 (3-legged) SERVER_AUTHENTICATION - OAuth 2.0 with JSON Web Tokens	APP_USER_AUTHENTICATION	String
privateKeyFile (security)	The private key for generating the JWT signature.		String
privateKeyPassword (security)	The password for the private key.		String
publicKeyId (security)	The ID for public key for validating the JWT signature.		String
sslContextParameters (security)	To configure security using SSLContextParameters.		SSLContextParameters
userName (security)	Box user name, MUST be provided		String
userPassword (security)	Box user password, MUST be provided if authSecureStorage is not set, or returns null on first call		String

49.3. URI format

box:apiName/methodName

apiName can be one of:

collaborations
comments
event-logs
files
folders
groups
events
search
tasks
users

49.4. Producer Endpoints:

Producer endpoints can use endpoint prefixes followed by endpoint names and associated options described next. A shorthand alias can be used for some endpoints. The endpoint URI MUST contain a prefix.

Endpoint options that are not mandatory are denoted by []. When there are no mandatory options for an endpoint, one of the set of [] options MUST be provided. Producer endpoints can also use a special option inBody that in turn should contain the name of the endpoint option whose value will be contained in the Camel Exchange In message.

Any of the endpoint options can be provided in either the endpoint URI, or dynamically in a message header. The message header name must be of the format CamelBox.<option>. Note that the inBody option overrides message header, i.e. the endpoint option inBody=option would override a CamelBox.option header.

If a value is not provided for the option defaultRequest either in the endpoint URI or in a message header, it will be assumed to be null. Note that the null value will only be used if other options do not satisfy matching endpoints.

In case of Box API errors the endpoint will throw a RuntimeCamelException with a com.box.sdk.BoxAPIException derived exception cause.

49.4.1. Endpoint Prefix collaborations

For more information on Box collaborations see https://developer.box.com/reference#collaboration-object. The following endpoints can be invoked with the prefix collaborations as follows:

box:collaborations/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
addFolderCollaboration	add	folderId, collaborator, role	com.box.sdk.BoxCollaboration
addFolderCollaborationByEmail	addByEmail	folderId, email, role	com.box.sdk.BoxCollaboration
deleteCollaboration	delete	collaborationId
getFolderCollaborations	collaborations	folderId	java.util.Collection
getPendingCollaborations	pendingCollaborations		java.util.Collection
getCollaborationInfo	info	collaborationId	com.box.sdk.BoxCollaboration.Info
updateCollaborationInfo	updateInfo	collaborationId, info	com.box.sdk.BoxCollaboration

URI Options for collaborations

Name	Type
collaborationId	String
collaborator	com.box.sdk.BoxCollaborator
role	com.box.sdk.BoxCollaboration.Role
folderId	String
email	String
info	com.box.sdk.BoxCollaboration.Info

49.4.2. Endpoint Prefix comments

For more information on Box comments see https://developer.box.com/reference#comment-object. The following endpoints can be invoked with the prefix comments as follows:

box:comments/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
addFileComment	add	fileId, message	com.box.sdk.BoxFile
changeCommentMessage	updateMessage	commentId, message	com.box.sdk.BoxComment
deleteComment	delete	commentId
getCommentInfo	info	commentId	com.box.sdk.BoxComment.Info
getFileComments	comments	fileId	java.util.List
replyToComment	reply	commentId, message	com.box.sdk.BoxComment

URI Options for collaborations

Name	Type
commentId	String
fileId	String
message	String

49.4.3. Endpoint Prefix events-logs

For more information on Box event logs see https://developer.box.com/reference#events. The following endpoints can be invoked with the prefix events as follows:

box:event-logs/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
getEnterpriseEvents	events	position, after, before, [types]	java.util.List

URI Options for event-logs

Name	Type
position	String
after	Date
before	Date
types	com.box.sdk.BoxEvent.Types[]

49.4.4. Endpoint Prefix files

For more information on Box files see https://developer.box.com/reference#file-object. The following endpoints can be invoked with the prefix files as follows.

box:files/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
uploadFile	upload	parentFolderId, content, fileName, [created], [modified], [size], [listener]	com.box.sdk.BoxFile
downloadFile	download	fileId, output, [rangeStart], [rangeEnd], [listener]	java.io.OutputStream
copyFile	copy	fileId, destinationFolderId, [newName]	com.box.sdk.BoxFile
moveFile	move	fileId, destinationFolderId, [newName]	com.box.sdk.BoxFile
renameFile	rename	fileId, newFileName	com.box.sdk.BoxFile
createFileSharedLink	link	fileId, access, [unshareDate], [permissions]	com.box.sdk.BoxSharedLink
deleteFile	delete	fileId
uploadNewFileVersion	uploadVersion	fileId, fileContent, [modified], [fileSize], [listener]	com.box.boxsdk.BoxFile
promoteFileVersion	promoteVersion	fileId, version	com.box.sdk.BoxFileVersion
getFileVersions	versions	fileId	java.util.Collection
downloadPreviousFileVersions	downloadVersion	fileId, version, output, [listener]	java.io.OutputStream
deleteFileVersion	deleteVersion	fileId, version
getFileInfo	info	fileId, fields	com.box.sdk.BoxFile.Info
updateFileInfo	updateInfo	fileId, info	com.box.sdk.BoxFile
createFileMetadata	createMetadata	fileId, metadata, [typeName]	com.box.sdk.Metadata
getFileMetadata	metadata	fileId, [typeName]	com.box.sdk.Metadata
updateFileMetadata	updateMetadata	fileId, metadata	com.box.sdk.Metadata
deleteFileMetadata	deleteMetadata	fileId
getDownloadUrl	url	fileId	java.net.URL
getPreviewLink	preview	fileId	java.net.URL
getFileThumbnail	thumbnail	fileId, fileType, minWidth, minHeight, maxWidth, maxHeight	byte[]

URI Options for files

Name	Type
parentFolderId	String
content	java.io.InputStream
fileName	String
created	Date
modified	Date
size	Long
listener	com.box.sdk.ProgressListener
output	java.io.OutputStream
rangeStart	Long
rangeEnd	Long
outputStreams	java.io.OutputStream[]
destinationFolderId	String
newName	String
fields	String[]
info	com.box.sdk.BoxFile.Info
fileSize	Long
version	Integer
access	com.box.sdk.BoxSharedLink.Access
unshareDate	Date
permissions	com.box.sdk.BoxSharedLink.Permissions
fileType	com.box.sdk.BoxFile.ThumbnailFileType
minWidth	Integer
minHeight	Integer
maxWidth	Integer
maxHeight	Integer
metadata	com.box.sdk.Metadata
typeName	String

49.4.5. Endpoint Prefix folders

For more information on Box folders see https://developer.box.com/reference#folder-object. The following endpoints can be invoked with the prefix folders as follows.

box:folders/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
getRootFolder	root		com.box.sdk.BoxFolder
createFolder	create	parentFolderId, folderName	com.box.sdk.BoxFolder
createFolder	create	parentFolderId, path	com.box.sdk.BoxFolder
copyFolder	copy	folderId, destinationfolderId, [newName]	com.box.sdk.BoxFolder
moveFolder	move	folderId, destinationFolderId, newName	com.box.sdk.BoxFolder
renameFolder	rename	folderId, newFolderName	com.box.sdk.BoxFolder
createFolderSharedLink	link	folderId, access, [unsharedDate], [permissions]	java.util.List
deleteFolder	delete	folderId
getFolder	folder	path	com.box.sdk.BoxFolder
getFolderInfo	info	folderId, fields	com.box.sdk.BoxFolder.Info
getFolderItems	items	folderId, offset, limit, fields	com.box.sdk.BoxFolder
updateFolderInfo	updateInfo	folderId, info	com.box.sdk.BoxFolder

URI Options for folders

Name	Type
path	String[]
folderId	String
offset	Long
limit	Long
fields	String[]
parentFolderId	String
folderName	String
destinationFolderId	String
newName	String
newFolderName	String
info	String
access	com.box.sdk.BoxSharedLink.Access
unshareDate	Date
permissions	com.box.sdk.BoxSharedLink.Permissions

49.4.6. Endpoint Prefix groups

For more information on Box groups see https://developer.box.com/reference#group-object. The following endpoints can be invoked with the prefix groups as follows:

box:groups/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
createGroup	create	name, [provenance, externalSyncIdentifier, description, invitabilityLevel, memberViewabilityLevel]	com.box.sdk.BoxGroup
addGroupMembership	createMembership	groupId, userId, role	com.box.sdk.BoxGroupMembership
deleteGroup	delete	groupId
getAllGroups	groups		java.util.Collection
getGroupInfo	info	groupId	com.box.sdk.BoxGroup.Info
updateGroupInfo	updateInfo	groupId, groupInfo	com.box.sdk.BoxGroup
addGroupMembership	addMembership	groupId, userId, role	com.box.sdk.BoxGroupMembership
deleteGroupMembership	deleteMembership	groupMembershipId
getGroupMemberships	memberships	groupId	java.uti.Collection
getGroupMembershipInfo	membershipInfo	groupMemebershipId	com.box.sdk.BoxGroup.Info
updateGroupMembershipInfo	updateMembershipInfo	groupMemebershipId, info	com.box.sdk.BoxGroupMembership

URI Options for groups

Name	Type
name	String
groupId	String
userId	String
role	com.box.sdk.BoxGroupMembership.Role
groupMembershipId	String
info	com.box.sdk.BoxGroupMembership.Info

49.4.7. Endpoint Prefix search

For more information on Box search API see https://developer.box.com/reference#searching-for-content. The following endpoints can be invoked with the prefix search as follows:

box:search/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
searchFolder	search	folderId, query	java.util.Collection

URI Options for search

Name	Type
folderId	String
query	String

49.4.8. Endpoint Prefix tasks

For information on Box tasks see https://developer.box.com/reference#task-object-1. The following endpoints can be invoked with the prefix tasks as follows:

box:tasks/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
addFileTask	add	fileId, action, dueAt, [message]	com.box.sdk.BoxUser
deleteTask	delete	taskId
getFileTasks	tasks	fileId	java.util.List
getTaskInfo	info	taskId	com.box.sdk.BoxTask.Info
updateTaskInfo	updateInfo	taskId, info	com.box.sdk.BoxTask
addAssignmentToTask	addAssignment	taskId, assignTo	com.box.sdk.BoxTask
deleteTaskAssignment	deleteAssignment	taskAssignmentId
getTaskAssignments	assignments	taskId	java.util.List
getTaskAssignmentInfo	assignmentInfo	taskAssignmentId	com.box.sdk.BoxTaskAssignment.Info

URI Options for tasks

Name	Type
fileId	String
action	com.box.sdk.BoxTask.Action
dueAt	Date
message	String
taskId	String
info	com.box.sdk.BoxTask.Info
assignTo	com.box.sdk.BoxUser
taskAssignmentId	String

49.4.9. Endpoint Prefix users

For information on Box users see https://developer.box.com/reference#user-object. The following endpoints can be invoked with the prefix users as follows:

box:users/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
getCurrentUser	currentUser		com.box.sdk.BoxUser
getAllEnterpriseOrExternalUsers	users	filterTerm, [fields]	com.box.sdk.BoxUser
createAppUser	create	name, [params]	com.box.sdk.BoxUser
createEnterpriseUser	create	login, name, [params]	com.box.sdk.BoxUser
deleteUser	delete	userId, notifyUser, force
getUserEmailAlias	emailAlias	userId	com.box.sdk.BoxUser
deleteUserEmailAlias	deleteEmailAlias	userId, emailAliasId	java.util.List
getUserInfo	info	userId	com.box.sdk.BoxUser.Info
updateUserInfo	updateInfo	userId, info	com.box.sdk.BoxUser
moveFolderToUser	-	userId, sourceUserId	com.box.sdk.BoxFolder.Info

URI Options for users

Name	Type
defaultRequest	com.box.restclientv2.requestsbase.BoxDefaultRequestObject
emailAliasRequest	com.box.boxjavalibv2.requests.requestobjects.BoxEmailAliasRequestObject
emailId	String
filterTerm	String
folderId	String
simpleUserRequest	com.box.boxjavalibv2.requests.requestobjects.BoxSimpleUserRequestObject
userDeleteRequest	com.box.boxjavalibv2.requests.requestobjects.BoxUserDeleteRequestObject
userId	String
userRequest	com.box.boxjavalibv2.requests.requestobjects.BoxUserRequestObject
userUpdateLoginRequest	com.box.boxjavalibv2.requests.requestobjects.BoxUserUpdateLoginRequestObject

49.5. Consumer Endpoints:

For more information on Box events see https://developer.box.com/reference#events. Consumer endpoints can only use the endpoint prefix events as shown in the example next.

box:events/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
events		[startingPosition]	com.box.sdk.BoxEvent

URI Options for events

Name	Type
startingPosition	Long

49.6. Message header

Any of the options can be provided in a message header for producer endpoints with CamelBox. prefix.

49.7. Message body

All result message bodies utilize objects provided by the Box Java SDK. Producer endpoints can specify the option name for incoming message body in the inBody endpoint parameter.

49.8. Samples

The following route uploads new files to the user’s root folder:

from("file:...")
    .to("box://files/upload/inBody=fileUploadRequest");

The following route polls user’s account for updates:

from("box://events/listen?startingPosition=-1")
    .to("bean:blah");

The following route uses a producer with dynamic header options. The fileId property has the Box file id and the output property has the output stream of the file contents, so they are assigned to the CamelBox.fileId header and CamelBox.output header respectively as follows:

from("direct:foo")
    .setHeader("CamelBox.fileId", header("fileId"))
    .setHeader("CamelBox.output", header("output"))
    .to("box://files/download")
    .to("file://...");

Chapter 50. Braintree Component

Available as of Camel version 2.17

The Braintree component provides access to Braintree Payments trough through theirs Java SDK.

All client applications need API credential in order to process payments. In order to use camel-braintree with your account, you’ll need to create a new Sandbox or https://www.braintreepayments.com/signup[Production] account.

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

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

50.1. Braintree Options

The Braintree component supports 2 options which are listed below.

Name	Description	Default	Type
configuration (common)	To use the shared configuration		BraintreeConfiguration
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Braintree endpoint is configured using URI syntax:

braintree:apiName/methodName

with the following path and query parameters:

50.1.1. Path Parameters (2 parameters):

Name	Description	Default	Type
apiName	Required What kind of operation to perform		BraintreeApiName
methodName	What sub operation to use for the selected operation		String

50.1.2. Query Parameters (14 parameters):

Name	Description	Default	Type
environment (common)	The environment Either SANDBOX or PRODUCTION		String
inBody (common)	Sets the name of a parameter to be passed in the exchange In Body		String
merchantId (common)	The merchant id provided by Braintree.		String
privateKey (common)	The private key provided by Braintree.		String
publicKey (common)	The public key provided by Braintree.		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
accessToken (advanced)	The access token granted by a merchant to another in order to process transactions on their behalf. Used in place of environment, merchant id, public key and private key fields.		String
httpReadTimeout (advanced)	Set read timeout for http calls.		Integer
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
httpLogLevel (logging)	Set logging level for http calls, see java.util.logging.Level		String
proxyHost (proxy)	The proxy host		String
proxyPort (proxy)	The proxy port		Integer

50.2. URI format

braintree://endpoint-prefix/endpoint?[options]

Endpoint prefix can be one of:

addOn
address
clientToken
creditCardverification
customer
discount
merchantAccount
paymentmethod
paymentmethodNonce
plan
settlementBatchSummary
subscription
transaction
webhookNotification
```
 
```

50.3. BraintreeComponent

The Braintree Component can be configured with the options below. These options can be provided using the component’s bean property configuration of type org.apache.camel.component.braintree.BraintreeConfiguration.

Option	Type	Description
environment	String	Value that specifies where requests should be directed – sandbox or production
merchantId	String	A unique identifier for your gateway account, which is different than your merchant account ID
publicKey	String	User-specific public identifier
privateKey	String	User-specific secure identifier that should not be shared – even with us!
accessToken	String	Token granted to a merchant using Braintree Auth allowing them to process transactions on another’s behalf. Used in place of the environment, merchantId, publicKey and privateKey options.

All the options above are provided by Braintree Payments

50.4. Producer Endpoints:

Producer endpoints can use endpoint prefixes followed by endpoint names and associated options described next. A shorthand alias can be used for some endpoints. The endpoint URI MUST contain a prefix.

Endpoint options that are not mandatory are denoted by []. When there are no mandatory options for an endpoint, one of the set of [] options MUST be provided. Producer endpoints can also use a special option inBody that in turn should contain the name of the endpoint option whose value will be contained in the Camel Exchange In message.

Any of the endpoint options can be provided in either the endpoint URI, or dynamically in a message header. The message header name must be of the format CamelBraintree.<option>. Note that the inBody option overrides message header, i.e. the endpoint option inBody=option would override a CamelBraintree.option header.

For more information on the endpoints and options see Braintree references at https://developers.braintreepayments.com/reference/overview[https://developers.braintreepayments.com/reference/overview]

50.4.1. Endpoint prefix addOn

The following endpoints can be invoked with the prefix addOn as follows:

braintree://addOn/endpoint

Endpoint	Shorthand Alias	Options	Result Body Type
all			List<com.braintreegateway.Addon>

50.4.2. Endpoint prefix address

The following endpoints can be invoked with the prefix address as follows:

braintree://address/endpoint?[options]

Endpoint	Options	Result Body Type
create	customerId, request	com.braintreegateway.Result<com.braintreegateway.Address>
delete	customerId, id	com.braintreegateway.Result<com.braintreegateway.Address>
find	customerId, id	com.braintreegateway.Address
update	customerId, id, request	com.braintreegateway.Result<com.braintreegateway.Address>

URI Options for address

Name	Type
customerId	String
request	com.braintreegateway.AddressRequest
id	String

50.4.3. Endpoint prefix clientToken

The following endpoints can be invoked with the prefix clientToken as follows:

braintree://clientToken/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
generate		request	String

URI Options for clientToken

Name	Type
request	com.braintreegateway.ClientTokenrequest

50.4.4. Endpoint prefix creditCardVerification

The following endpoints can be invoked with the prefix creditCardverification as follows:

braintree://creditCardVerification/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
find		id	com.braintreegateway.CreditCardVerification
search		query	com.braintreegateway.ResourceCollection<com.braintreegateway.CreditCardVerification>

URI Options for creditCardVerification

Name	Type
id	String
query	com.braintreegateway.CreditCardVerificationSearchRequest

50.4.5. Endpoint prefix customer

The following endpoints can be invoked with the prefix customer as follows:

braintree://customer/endpoint?[options]

Endpoint	Options	Result Body Type
all
create	request	com.braintreegateway.Result<com.braintreegateway.Customer>
delete	id	com.braintreegateway.Result<com.braintreegateway.Customer>
find	id	com.braintreegateway.Customer
search	query	com.braintreegateway.ResourceCollection<com.braintreegateway.Customer>
update	id, request	com.braintreegateway.Result<com.braintreegateway.Customer>

URI Options for customer

Name	Type
id	String
request	com.braintreegateway.CustomerRequest
query	com.braintreegateway.CustomerSearchRequest

50.4.6. Endpoint prefix discount

The following endpoints can be invoked with the prefix discount as follows:

braintree://discount/endpoint

Endpoint	Shorthand Alias	Options	Result Body Type
all			List<com.braintreegateway.Discount>

50.4.7. Endpoint prefix merchantAccount

The following endpoints can be invoked with the prefix merchantAccount as follows:

braintree://merchantAccount/endpoint?[options]

Endpoint	Options	Result Body Type
create	request	com.braintreegateway.Result<com.braintreegateway.MerchantAccount>
createForCurrency	currencyRequest	com.braintreegateway.Result<com.braintreegateway.MerchantAccount>
find	id	com.braintreegateway.MerchantAccount
update	id, request	com.braintreegateway.Result<com.braintreegateway.MerchantAccount>

URI Options for merchantAccount

Name	Type
id	String
request	com.braintreegateway.MerchantAccountRequest
currencyRequest	com.braintreegateway.MerchantAccountCreateForCurrencyRequest

50.4.8. Endpoint prefix paymentMethod

The following endpoints can be invoked with the prefix paymentMethod as follows:

braintree://paymentMethod/endpoint?[options]

Endpoint	Options	Result Body Type
create	request	com.braintreegateway.Result<com.braintreegateway.PaymentMethod>
delete	token, deleteRequest	com.braintreegateway.Result<com.braintreegateway.PaymentMethod>
find	token	com.braintreegateway.PaymentMethod
update	token, request	com.braintreegateway.Result<com.braintreegateway.PaymentMethod>

URI Options for paymentMethod

Name	Type
token	String
request	com.braintreegateway.PaymentMethodRequest
deleteRequest	com.braintreegateway.PaymentMethodDeleteRequest

50.4.9. Endpoint prefix paymentMethodNonce

The following endpoints can be invoked with the prefix paymentMethodNonce as follows:

braintree://paymentMethodNonce/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
create		paymentMethodToken	com.braintreegateway.Result<com.braintreegateway.PaymentMethodNonce>
find		paymentMethodNonce	com.braintreegateway.PaymentMethodNonce

URI Options for paymentMethodNonce

Name	Type
paymentMethodToken	String
paymentMethodNonce	String

50.4.10. Endpoint prefix plan

The following endpoints can be invoked with the prefix plan as follows:

braintree://plan/endpoint

Endpoint	Shorthand Alias	Options	Result Body Type
all			List<com.braintreegateway.Plan>

50.4.11. Endpoint prefix settlementBatchSummary

The following endpoints can be invoked with the prefix settlementBatchSummary as follows:

braintree://settlementBatchSummary/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
generate		request	com.braintreegateway.Result<com.braintreegateway.SettlementBatchSummary>

URI Options for settlementBatchSummary

Name	Type
settlementDate	Calendar
groupByCustomField	String

50.4.12. Endpoint prefix subscription

The following endpoints can be invoked with the prefix subscription as follows:

braintree://subscription/endpoint?[options]

Endpoint	Options	Result Body Type
cancel	id	com.braintreegateway.Result<com.braintreegateway.Subscription>
create	request	com.braintreegateway.Result<com.braintreegateway.Subscription>
delete	customerId, id	com.braintreegateway.Result<com.braintreegateway.Subscription>
find	id	com.braintreegateway.Subscription
retryCharge	subscriptionId, amount	com.braintreegateway.Result<com.braintreegateway.Transaction>
search	searchRequest	com.braintreegateway.ResourceCollection<com.braintreegateway.Subscription>
update	id, request	com.braintreegateway.Result<com.braintreegateway.Subscription>

URI Options for subscription

Name	Type
id	String
request	com.braintreegateway.SubscriptionRequest
customerId	String
subscriptionId	String
amount	BigDecimal
searchRequest	com.braintreegateway.SubscriptionSearchRequest.

50.4.13. Endpoint prefix transaction

The following endpoints can be invoked with the prefix transaction as follows:

braintree://transaction/endpoint?[options]

Endpoint	Options	Result Body Type
cancelRelease	id	com.braintreegateway.Result<com.braintreegateway.Transaction>
cloneTransaction	id, cloneRequest	com.braintreegateway.Result<com.braintreegateway.Transaction>
credit	request	com.braintreegateway.Result<com.braintreegateway.Transaction>
find	id	com.braintreegateway.Transaction
holdInEscrow	id	com.braintreegateway.Result<com.braintreegateway.Transaction>
releaseFromEscrow	id	com.braintreegateway.Result<com.braintreegateway.Transaction>
refund	id, amount, refundRequest	com.braintreegateway.Result<com.braintreegateway.Transaction>
sale	request	com.braintreegateway.Result<com.braintreegateway.Transaction>
search	query	com.braintreegateway.ResourceCollection<com.braintreegateway.Transaction>
submitForPartialSettlement	id, amount	com.braintreegateway.Result<com.braintreegateway.Transaction>
submitForSettlement	id, amount, request	com.braintreegateway.Result<com.braintreegateway.Transaction>
voidTransaction	id	com.braintreegateway.Result<com.braintreegateway.Transaction>

URI Options for transaction

Name	Type
id	String
request	com.braintreegateway.TransactionCloneRequest
cloneRequest	com.braintreegateway.TransactionCloneRequest
refundRequest	com.braintreegateway.TransactionRefundRequest
amount	BigDecimal
query	com.braintreegateway.TransactionSearchRequest

50.4.14. Endpoint prefix webhookNotification

The following endpoints can be invoked with the prefix webhookNotification as follows:

braintree://webhookNotification/endpoint?[options]

Endpoint	Shorthand Alias	Options	Result Body Type
parse		signature, payload	com.braintreegateway.WebhookNotification
verify		challenge	String

URI Options for webhookNotification

Name	Type
signature	String
payload	String
challenge	String

50.5. Consumer Endpoints

Any of the producer endpoints can be used as a consumer endpoint. Consumer endpoints can use http://camel.apache.org/polling-consumer.html#PollingConsumer-ScheduledPollConsumerOptions[Scheduled Poll Consumer Options] with a consumer. prefix to schedule endpoint invocation. By default Consumer endpoints that return an array or collection will generate one exchange per element, and their routes will be executed once for each exchange. To change this behavior use the property consumer.splitResults=true to return a single exchange for the entire list or array.

50.6. Message Headers

Any URI option can be provided in a message header for producer endpoints with a CamelBraintree. prefix.

50.7. Message body

All result message bodies utilize objects provided by the Braintree Java SDK. Producer endpoints can specify the option name for incoming message body in the inBody endpoint parameter.

50.8. Examples

Blueprint

<?xml version="1.0"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0"
           xsi:schemaLocation="
             http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0 http://aries.apache.org/schemas/blueprint-cm/blueprint-cm-1.0.0.xsd
             http://www.osgi.org/xmlns/blueprint/v1.0.0 https://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
             http://camel.apache.org/schema/blueprint http://camel.apache.org/schema/blueprint/camel-blueprint.xsd">


    <cm:property-placeholder id="placeholder" persistent-id="camel.braintree">
    </cm:property-placeholder>

    <bean id="braintree" class="org.apache.camel.component.braintree.BraintreeComponent">
        <property name="configuration">
            <bean class="org.apache.camel.component.braintree.BraintreeConfiguration">
                <property name="environment" value="${environment}"/>
                <property name="merchantId" value="${merchantId}"/>
                <property name="publicKey" value="${publicKey}"/>
                <property name="privateKey" value="${privateKey}"/>
            </bean>
        </property>
    </bean>

    <camelContext trace="true" xmlns="http://camel.apache.org/schema/blueprint" id="braintree-example-context">
        <route id="braintree-example-route">
            <from uri="direct:generateClientToken"/>
            <to uri="braintree://clientToken/generate"/>
            <to uri="stream:out"/>
        </route>
    </camelContext>

</blueprint>

Chapter 51. Browse Component

Available as of Camel version 1.3

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.

51.1. URI format

browse:someName[?options]

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

51.2. Options

The Browse component has no options.

The Browse endpoint is configured using URI syntax:

browse:name

with the following path and query parameters:

51.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
name	Required A name which can be any string to uniquely identify the endpoint		String

51.2.2. Query Parameters (4 parameters):

Name	Description	Default	Type
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN/ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN/ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the default exchange pattern when creating an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

51.3. Sample

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

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

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

private CamelContext context;

public void inspectRecievedOrders() {
    BrowsableEndpoint browse = context.getEndpoint("browse:orderReceived", BrowsableEndpoint.class);
    List<Exchange> exchanges = browse.getExchanges();

    // then we can inspect the list of received exchanges from Java
    for (Exchange exchange : exchanges) {
        String payload = exchange.getIn().getBody();
        // do something with payload
    }
}

51.4. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 52. EHCache Component (deprecated)

Available as of Camel version 2.1

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

This component supports producer and event based consumer endpoints.

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

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

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

52.1. URI format

cache://cacheName[?options]

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

52.2. Options

The EHCache component supports 4 options which are listed below.

Name	Description	Default	Type
cacheManagerFactory (advanced)	To use the given CacheManagerFactory for creating the CacheManager. By default the DefaultCacheManagerFactory is used.		CacheManagerFactory
configuration (common)	Sets the Cache configuration		CacheConfiguration
configurationFile (common)	Sets the location of the ehcache.xml file to load from classpath or file system. By default the file is loaded from classpath:ehcache.xml	classpath:ehcache.xml	String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The EHCache endpoint is configured using URI syntax:

cache:cacheName

with the following path and query parameters:

52.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cacheName	Required Name of the cache		String

52.2.2. Query Parameters (19 parameters):

Name	Description	Default	Type
diskExpiryThreadInterval Seconds (common)	The number of seconds between runs of the disk expiry thread.		long
diskPersistent (common)	Whether the disk store persists between restarts of the application.	false	boolean
diskStorePath (common)	Deprecated This parameter is ignored. CacheManager sets it using setter injection.		String
eternal (common)	Sets whether elements are eternal. If eternal, timeouts are ignored and the element never expires.	false	boolean
key (common)	The default key to use. If a key is provided in the message header, then the key from the header takes precedence.		String
maxElementsInMemory (common)	The number of elements that may be stored in the defined cache in memory.	1000	int
memoryStoreEvictionPolicy (common)	Which eviction strategy to use when maximum number of elements in memory is reached. The strategy defines which elements to be removed. LRU - Lest Recently Used LFU - Lest Frequently Used FIFO - First In First Out	LFU	MemoryStoreEviction Policy
objectCache (common)	Whether to turn on allowing to store non serializable objects in the cache. If this option is enabled then overflow to disk cannot be enabled as well.	false	boolean
operation (common)	The default cache operation to use. If an operation in the message header, then the operation from the header takes precedence.		String
overflowToDisk (common)	Specifies whether cache may overflow to disk	true	boolean
timeToIdleSeconds (common)	The maximum amount of time between accesses before an element expires	300	long
timeToLiveSeconds (common)	The maximum time between creation time and when an element expires. Is used only if the element is not eternal	300	long
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
cacheLoaderRegistry (advanced)	To configure cache loader using the CacheLoaderRegistry		CacheLoaderRegistry
cacheManagerFactory (advanced)	To use a custom CacheManagerFactory for creating the CacheManager to be used by this endpoint. By default the CacheManagerFactory configured on the component is used.		CacheManagerFactory
eventListenerRegistry (advanced)	To configure event listeners using the CacheEventListenerRegistry		CacheEventListener Registry
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

52.3. Sending/Receiving Messages to/from the cache

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

52.3.2. Message Headers Camel 2.8+

Header changes in Camel 2.8

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.

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

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

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

52.4. Cache Usage Samples

52.4.1. Example 1: Configuring the cache

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

52.4.2. Example 2: Adding keys to the cache

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

52.4.3. Example 2: Updating existing keys in a cache

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

52.4.4. Example 3: Deleting existing keys in a cache

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

52.4.5. Example 4: Deleting all existing keys in a cache

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

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

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

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

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

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

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

52.4.8. Example 7: Getting an entry from the Cache

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

52.4.9. Example 8: Checking for an entry in the Cache

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

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

52.5. Management of EHCache

EHCache has its own statistics and management from JMX.

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

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

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

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

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

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

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

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

Chapter 53. Caffeine Cache Component

Available as of Camel version 2.20

The caffeine-cache component enables you to perform caching operations using The simple cache from Caffeine.

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

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

53.1. URI format

caffeine-cache://cacheName[?options]

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

53.2. Options

The Caffeine Cache component supports 2 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	Sets the global component configuration		CaffeineConfiguration
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Caffeine Cache endpoint is configured using URI syntax:

caffeine-cache:cacheName

with the following path and query parameters:

53.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cacheName	Required the cache name		String

53.2.2. Query Parameters (19 parameters):

Name	Description	Default	Type
createCacheIfNotExist (common)	Configure if a cache need to be created if it does exist or can’t be pre-configured.	true	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
action (producer)	To configure the default cache action. If an action is set in the message header, then the operation from the header takes precedence.		String
cache (producer)	To configure the default an already instantianted cache to be used		Cache
cacheLoader (producer)	To configure a CacheLoader in case of a LoadCache use		CacheLoader
evictionType (producer)	Set the eviction Type for this cache	SIZE_BASED	EvictionType
expireAfterAccessTime (producer)	Set the expire After Access Time in case of time based Eviction (in seconds)	300	int
expireAfterWriteTime (producer)	Set the expire After Access Write in case of time based Eviction (in seconds)	300	int
initialCapacity (producer)	Set the initial Capacity for the cache	10000	int
key (producer)	To configure the default action key. If a key is set in the message header, then the key from the header takes precedence.		Object
maximumSize (producer)	Set the maximum size for the cache	10000	int
removalListener (producer)	Set a specific removal Listener for the cache		RemovalListener
statsCounter (producer)	Set a specific Stats Counter for the cache stats		StatsCounter
statsEnabled (producer)	To enable stats on the cache	false	boolean
keyType (advanced)	The cache key type, default java.lang.Object	java.lang.Object	String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
valueType (advanced)	The cache value type, default java.lang.Object	java.lang.Object	String

Chapter 54. Caffeine LoadCache Component

Available as of Camel version 2.20

The caffeine-loadcache component enables you to perform caching operations using The Load cache from Caffeine.

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

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

54.1. URI format

caffeine-loadcache://cacheName[?options]

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

54.2. Options

The Caffeine LoadCache component supports 2 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	Sets the global component configuration		CaffeineConfiguration
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Caffeine LoadCache endpoint is configured using URI syntax:

caffeine-loadcache:cacheName

with the following path and query parameters:

54.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cacheName	Required the cache name		String

54.2.2. Query Parameters (19 parameters):

Name	Description	Default	Type
createCacheIfNotExist (common)	Configure if a cache need to be created if it does exist or can’t be pre-configured.	true	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
action (producer)	To configure the default cache action. If an action is set in the message header, then the operation from the header takes precedence.		String
cache (producer)	To configure the default an already instantianted cache to be used		Cache
cacheLoader (producer)	To configure a CacheLoader in case of a LoadCache use		CacheLoader
evictionType (producer)	Set the eviction Type for this cache	SIZE_BASED	EvictionType
expireAfterAccessTime (producer)	Set the expire After Access Time in case of time based Eviction (in seconds)	300	int
expireAfterWriteTime (producer)	Set the expire After Access Write in case of time based Eviction (in seconds)	300	int
initialCapacity (producer)	Set the initial Capacity for the cache	10000	int
key (producer)	To configure the default action key. If a key is set in the message header, then the key from the header takes precedence.		Object
maximumSize (producer)	Set the maximum size for the cache	10000	int
removalListener (producer)	Set a specific removal Listener for the cache		RemovalListener
statsCounter (producer)	Set a specific Stats Counter for the cache stats		StatsCounter
statsEnabled (producer)	To enable stats on the cache	false	boolean
keyType (advanced)	The cache key type, default java.lang.Object	java.lang.Object	String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
valueType (advanced)	The cache value type, default java.lang.Object	java.lang.Object	String

Chapter 55. Castor DataFormat (deprecated)

Available as of Camel version 2.1

Castor is a Data Format which uses the Castor XML library to unmarshal an XML payload into Java objects or to marshal Java objects into an XML payload.

As usually you can use either Java DSL or Spring XML to work with Castor Data Format.

55.1. Using the Java DSL

from("direct:order").
  marshal().castor().
  to("activemq:queue:order");

For example the following uses a named DataFormat of Castor which uses default Castor data binding features.

CastorDataFormat castor = new CastorDataFormat ();

from("activemq:My.Queue").
  unmarshal(castor).
  to("mqseries:Another.Queue");

If you prefer to use a named reference to a data format which can then be defined in your Registry such as via your Spring XML file. e.g.

from("activemq:My.Queue").
  unmarshal("mycastorType").
  to("mqseries:Another.Queue");

If you want to override default mapping schema by providing a mapping file you can set it as follows.

CastorDataFormat castor = new CastorDataFormat ();
castor.setMappingFile("mapping.xml");

Also if you want to have more control on Castor Marshaller and Unmarshaller you can access them as below.

castor.getMarshaller();
castor.getUnmarshaller();

55.2. Using Spring XML

The following example shows how to use Castor to unmarshal using Spring configuring the castor data type

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="direct:start"/>
    <unmarshal>
      <castor validation="true" />
    </unmarshal>
    <to uri="mock:result"/>
  </route>
</camelContext>

This example shows how to configure the data type just once and reuse it on multiple routes. You have to set the <castor> element directly in <camelContext>.

<camelContext>
<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
  <dataFormats>
    <castor id="myCastor"/>
  </dataFormats>

  <route>
    <from uri="direct:start"/>
    <marshal ref="myCastor"/>
    <to uri="direct:marshalled"/>
  </route>
  <route>
    <from uri="direct:marshalled"/>
    <unmarshal ref="myCastor"/>
    <to uri="mock:result"/>
  </route>

</camelContext>

55.3. Options

The Castor dataformat supports 9 options which are listed below.

Name	Default	Java Type	Description
mappingFile		`String`	Path to a Castor mapping file to load from the classpath.
whitelistEnabled	`true`	`Boolean`	Define if Whitelist feature is enabled or not
allowedUnmarshallObjects		`String`	Define the allowed objects to be unmarshalled. You can specify the FQN class name of allowed objects, and you can use comma to separate multiple entries. It is also possible to use wildcards and regular expression which is based on the pattern defined by link org.apache.camel.util.EndpointHelpermatchPattern(String, String). Denied objects takes precedence over allowed objects.
deniedUnmarshallObjects		`String`	Define the denied objects to be unmarshalled. You can specify the FQN class name of deined objects, and you can use comma to separate multiple entries. It is also possible to use wildcards and regular expression which is based on the pattern defined by link org.apache.camel.util.EndpointHelpermatchPattern(String, String). Denied objects takes precedence over allowed objects.
validation	`true`	`Boolean`	Whether validation is turned on or off. Is by default true.
encoding	`UTF-8`	`String`	Encoding to use when marshalling an Object to XML. Is by default UTF-8
packages		`String[]`	Add additional packages to Castor XmlContext
classes		`String[]`	Add additional class names to Castor XmlContext
contentTypeHeader	`false`	`Boolean`	Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.

55.4. Dependencies

To use Castor in your camel routes you need to add the a dependency on camel-castor 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).

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

Chapter 56. Camel CDI

The Camel CDI component provides auto-configuration for Apache Camel using CDI as dependency injection framework based on convention-over-configuration. It auto-detects Camel routes available in the application and provides beans for common Camel primitives like Endpoint, FluentProducerTemplate, ProducerTemplate or TypeConverter. It implements standard Camel bean integration so that Camel annotations like @Consume, @Produce and @PropertyInject can be used seamlessly in CDI beans. Besides, it bridges Camel events (e.g. RouteAddedEvent, CamelContextStartedEvent, ExchangeCompletedEvent, …) as CDI events and provides a CDI events endpoint that can be used to consume / produce CDI events from / to Camel routes.

While the Camel CDI component is available as of Camel 2.10, it’s been rewritten in Camel 2.17 to better fit into the CDI programming model. Hence some of the features like the Camel events to CDI events bridge and the CDI events endpoint only apply starting Camel 2.17.

More details on how to test Camel CDI applications are available in Camel CDI testing.

Caution

camel-cdi is deprecated in OSGi and not supported. Use OSGi Blueprint if using Camel with OSGi.

56.1. Auto-configured Camel context

Camel CDI automatically deploys and configures a CamelContext bean. That CamelContext bean is automatically instantiated, configured and started (resp. stopped) when the CDI container initializes (resp. shuts down). It can be injected in the application, e.g.:

@Inject
CamelContext context;

That default CamelContext bean is qualified with the built-in @Default qualifier, is scoped @ApplicationScoped and is of type DefaultCamelContext.

Note that this bean can be customized programmatically and other Camel context beans can be deployed in the application as well.

56.2. Auto-detecting Camel routes

Camel CDI automatically collects all the RoutesBuilder beans in the application, instantiates and add them to the CamelContext bean instance when the CDI container initializes. For example, adding a Camel route is as simple as declaring a class, e.g.:

class MyRouteBean extends RouteBuilder {
 
    @Override
    public void configure() {
        from("jms:invoices").to("file:/invoices");
    }
}

Note that you can declare as many RoutesBuilder beans as you want. Besides, RouteContainer beans are also automatically collected, instantiated and added to the CamelContext bean instance managed by Camel CDI when the container initializes.

Available as of Camel 2.19

In some situations, it may be necessary to disable the auto-configuration of the RouteBuilder and RouteContainer beans. That can be achieved by observing for the CdiCamelConfiguration event, e.g.:

static void configuration(@Observes CdiCamelConfiguration configuration) {
    configuration.autoConfigureRoutes(false);
}

Similarly, it is possible to deactivate the automatic starting of the configured CamelContext beans, e.g.:

static void configuration(@Observes CdiCamelConfiguration configuration) {
    configuration.autoStartContexts(false);
}

56.3. Auto-configured Camel primitives

Camel CDI provides beans for common Camel primitives that can be injected in any CDI beans, e.g.:

@Inject
@Uri("direct:inbound")
ProducerTemplate producerTemplate;

@Inject
@Uri("direct:inbound")
FluentProducerTemplate fluentProducerTemplate;

@Inject
MockEndpoint outbound; // URI defaults to the member name, i.e. mock:outbound

@Inject
@Uri("direct:inbound")
Endpoint endpoint;

@Inject
TypeConverter converter;

56.4. Camel context configuration

If you just want to change the name of the default CamelContext bean, you can used the @ContextName qualifier provided by Camel CDI, e.g.:

@ContextName("camel-context")
class MyRouteBean extends RouteBuilder {
 
    @Override
    public void configure() {
        from("jms:invoices").to("file:/invoices");
    }
}

Else, if more customization is needed, any CamelContext class can be used to declare a custom Camel context bean. Then, the @PostConstruct and @PreDestroy lifecycle callbacks can be done to do the customization, e.g.:

@ApplicationScoped
class CustomCamelContext extends DefaultCamelContext {

    @PostConstruct
    void customize() {
        // Set the Camel context name
        setName("custom");
        // Disable JMX
        disableJMX();
    }

    @PreDestroy
    void cleanUp() {
        // ...
    }
}

Producer and disposer methods can also be used as well to customize the Camel context bean, e.g.:

class CamelContextFactory {

    @Produces
    @ApplicationScoped
    CamelContext customize() {
        DefaultCamelContext context = new DefaultCamelContext();
        context.setName("custom");
        return context;
    }

    void cleanUp(@Disposes CamelContext context) {
        // ...
    }
}

Similarly, producer fields can be used, e.g.:

@Produces
@ApplicationScoped
CamelContext context = new CustomCamelContext();

class CustomCamelContext extends DefaultCamelContext {

    CustomCamelContext() {
        setName("custom");
    }
}

This pattern can be used for example to avoid having the Camel context routes started automatically when the container initializes by calling the setAutoStartup method, e.g.:

@ApplicationScoped
class ManualStartupCamelContext extends DefaultCamelContext {

    @PostConstruct
    void manual() {
        setAutoStartup(false);
    }
}

56.5. Multiple Camel contexts

Any number of CamelContext beans can actually be declared in the application as documented above. In that case, the CDI qualifiers declared on these CamelContext beans are used to bind the Camel routes and other Camel primitives to the corresponding Camel contexts. From example, if the following beans get declared:

@ApplicationScoped
@ContextName("foo")
class FooCamelContext extends DefaultCamelContext {
}

@ApplicationScoped
@BarContextQualifier
class BarCamelContext extends DefaultCamelContext {
}
 
@ContextName("foo")
class RouteAddedToFooCamelContext extends RouteBuilder {

    @Override
    public void configure() {
        // ...
    }
}
 
@BarContextQualifier
class RouteAddedToBarCamelContext extends RouteBuilder {

    @Override
    public void configure() {
        // ...
    }
}
 
@ContextName("baz")
class RouteAddedToBazCamelContext extends RouteBuilder {

    @Override
    public void configure() {
        // ...
    }
}
 
@MyOtherQualifier
class RouteNotAddedToAnyCamelContext extends RouteBuilder {

    @Override
    public void configure() {
        // ...
    }
}

The RoutesBuilder beans qualified with @ContextName are automatically added to the corresponding CamelContext beans by Camel CDI. If no such CamelContext bean exists, it gets automatically created, as for the RouteAddedToBazCamelContext bean. Note this only happens for the @ContextName qualifier provided by Camel CDI. Hence the RouteNotAddedToAnyCamelContext bean qualified with the user-defined @MyOtherQualifier qualifier does not get added to any Camel contexts. That may be useful, for example, for Camel routes that may be required to be added later during the application execution.

Note

Since Camel version 2.17.0, Camel CDI is capable of managing any kind of CamelContext beans (e.g. DefaultCamelContext). In previous versions, it is only capable of managing beans of type CdiCamelContext so it is required to extend it.

The CDI qualifiers declared on the CamelContext beans are also used to bind the corresponding Camel primitives, e.g.:

@Inject
@ContextName("foo")
@Uri("direct:inbound")
ProducerTemplate producerTemplate;

@Inject
@ContextName("foo")
@Uri("direct:inbound")
FluentProducerTemplate fluentProducerTemplate;

@Inject
@BarContextQualifier
MockEndpoint outbound; // URI defaults to the member name, i.e. mock:outbound

@Inject
@ContextName("baz")
@Uri("direct:inbound")
Endpoint endpoint;

56.6. Configuration properties

To configure the sourcing of the configuration properties used by Camel to resolve properties placeholders, you can declare a PropertiesComponent bean qualified with @Named("properties"), e.g.:

@Produces
@ApplicationScoped
@Named("properties")
PropertiesComponent propertiesComponent() {
    Properties properties = new Properties();
    properties.put("property", "value");
    PropertiesComponent component = new PropertiesComponent();
    component.setInitialProperties(properties);
    component.setLocation("classpath:placeholder.properties");
    return component;
}

If you want to use DeltaSpike configuration mechanism you can declare the following PropertiesComponent bean:

@Produces
@ApplicationScoped
@Named("properties")
PropertiesComponent properties(PropertiesParser parser) {
    PropertiesComponent component = new PropertiesComponent();
    component.setPropertiesParser(parser);
    return component;
}

// PropertiesParser bean that uses DeltaSpike to resolve properties
static class DeltaSpikeParser extends DefaultPropertiesParser {
    @Override
    public String parseProperty(String key, String value, Properties properties) {
        return ConfigResolver.getPropertyValue(key);
    }
}

You can see the camel-example-cdi-properties example for a working example of a Camel CDI application using DeltaSpike configuration mechanism.

56.7. Auto-configured type converters

CDI beans annotated with the @Converter annotation are automatically registered into the deployed Camel contexts, e.g.:

@Converter
public class MyTypeConverter {

    @Converter
    public Output convert(Input input) {
        //...
    }
}

Note that CDI injection is supported within the type converters.

56.8. Camel bean integration

56.8.1. Camel annotations

As part of the Camel bean integration, Camel comes with a set of annotations that are seamlessly supported by Camel CDI. So you can use any of these annotations in your CDI beans, e.g.:

	Camel annotation	CDI equivalent
Configuration property	@PropertyInject("key") String value;	If using DeltaSpike configuration mechanism: @Inject @ConfigProperty(name = "key") String value; See configuration properties for more details.
Producer template injection (default Camel context)	@Produce(uri = "mock:outbound") ProducerTemplate producer; @Produce(uri = "mock:outbound") FluentProducerTemplate producer;	@Inject @Uri("direct:outbound") ProducerTemplate producer; @Produce(uri = "direct:outbound") FluentProducerTemplate producer;
Endpoint injection (default Camel context)	@EndpointInject(uri = "direct:inbound") Endpoint endpoint;	@Inject @Uri("direct:inbound") Endpoint endpoint;
Endpoint injection (Camel context by name)	@EndpointInject(uri = "direct:inbound", context = "foo") Endpoint contextEndpoint;	@Inject @ContextName("foo") @Uri("direct:inbound") Endpoint contextEndpoint;
Bean injection (by type)	@BeanInject MyBean bean;	@Inject MyBean bean;
Bean injection (by name)	@BeanInject("foo") MyBean bean;	@Inject @Named("foo") MyBean bean;
POJO consuming	@Consume(uri = "seda:inbound") void consume(@Body String body) { //... }

56.8.2. Bean component

You can refer to CDI beans, either by type or name, From the Camel DSL, e.g. with the Java Camel DSL:

class MyBean {
    //...
}

from("direct:inbound").bean(MyBean.class);

Or to lookup a CDI bean by name from the Java DSL:

@Named("foo")
class MyNamedBean {
    //...
}

from("direct:inbound").bean("foo");

56.8.3. Referring beans from Endpoint URIs

When configuring endpoints using the URI syntax you can refer to beans in the Registry using the # notation. If the URI parameter value starts with a # sign then Camel CDI will lookup for a bean of the given type by name, e.g.:

from("jms:queue:{{destination}}?transacted=true&transactionManager=#jtaTransactionManager").to("...");

Having the following CDI bean qualified with @Named("jtaTransactionManager"):

@Produces
@Named("jtaTransactionManager")
PlatformTransactionManager createTransactionManager(TransactionManager transactionManager, UserTransaction userTransaction) {
    JtaTransactionManager jtaTransactionManager = new JtaTransactionManager();
    jtaTransactionManager.setUserTransaction(userTransaction);
    jtaTransactionManager.setTransactionManager(transactionManager);
    jtaTransactionManager.afterPropertiesSet();
    return jtaTransactionManager;
}

56.9. Camel events to CDI events

Available as of Camel 2.17

Camel provides a set of management events that can be subscribed to for listening to Camel context, service, route and exchange events. Camel CDI seamlessly translates these Camel events into CDI events that can be observed using CDI observer methods, e.g.:

void onContextStarting(@Observes CamelContextStartingEvent event) {
    // Called before the default Camel context is about to start
}

As of Camel 2.18, it is possible to observe events for a particular route (RouteAddedEvent, RouteStartedEvent, RouteStoppedEvent and RouteRemovedEvent) should it have an explicit defined, e.g.:

from("...").routeId("foo").to("...");

void onRouteStarted(@Observes @Named("foo") RouteStartedEvent event) {
    // Called after the route "foo" has started
}

When multiple Camel contexts exist in the CDI container, the Camel context bean qualifiers, like @ContextName, can be used to refine the observer method resolution to a particular Camel context as specified in observer resolution, e.g.:

void onRouteStarted(@Observes @ContextName("foo") RouteStartedEvent event) {
    // Called after the route 'event.getRoute()' for the Camel context 'foo' has started
}
 
void onContextStarted(@Observes @Manual CamelContextStartedEvent event) {
    // Called after the the Camel context qualified with '@Manual' has started
}

Similarly, the @Default qualifier can be used to observe Camel events for the default Camel context if multiples contexts exist, e.g.:

void onExchangeCompleted(@Observes @Default ExchangeCompletedEvent event) {
    // Called after the exchange 'event.getExchange()' processing has completed
}

In that example, if no qualifier is specified, the @Any qualifier is implicitly assumed, so that corresponding events for all the Camel contexts get received.

Note that the support for Camel events translation into CDI events is only activated if observer methods listening for Camel events are detected in the deployment, and that per Camel context.

56.10. CDI events endpoint

Available as of Camel 2.17

The CDI event endpoint bridges the CDI events with the Camel routes so that CDI events can be seamlessly observed / consumed (resp. produced / fired) from Camel consumers (resp. by Camel producers).

The CdiEventEndpoint<T> bean provided by Camel CDI can be used to observe / consume CDI events whose event type is T, for example:

@Inject
CdiEventEndpoint<String> cdiEventEndpoint;

from(cdiEventEndpoint).log("CDI event received: ${body}");

This is equivalent to writing:

@Inject
@Uri("direct:event")
ProducerTemplate producer;

void observeCdiEvents(@Observes String event) {
    producer.sendBody(event);
}

from("direct:event").log("CDI event received: ${body}");

Conversely, the CdiEventEndpoint<T> bean can be used to produce / fire CDI events whose event type is T, for example:

@Inject
CdiEventEndpoint<String> cdiEventEndpoint;

from("direct:event").to(cdiEventEndpoint).log("CDI event sent: ${body}");

This is equivalent to writing:

@Inject
Event<String> event;

from("direct:event").process(new Processor() {
    @Override
    public void process(Exchange exchange) {
        event.fire(exchange.getBody(String.class));
    }
}).log("CDI event sent: ${body}");

Or using a Java 8 lambda expression:

@Inject
Event<String> event;

from("direct:event")
    .process(exchange -> event.fire(exchange.getIn().getBody(String.class)))
    .log("CDI event sent: ${body}");

The type variable T (resp. the qualifiers) of a particular CdiEventEndpoint<T> injection point are automatically translated into the parameterized event type (resp. into the event qualifiers) e.g.:

@Inject
@FooQualifier
CdiEventEndpoint<List<String>> cdiEventEndpoint;

from("direct:event").to(cdiEventEndpoint);

void observeCdiEvents(@Observes @FooQualifier List<String> event) {
    logger.info("CDI event: {}", event);
}

When multiple Camel contexts exist in the CDI container, the Camel context bean qualifiers, like @ContextName, can be used to qualify the CdiEventEndpoint<T> injection points, e.g.:

@Inject
@ContextName("foo")
CdiEventEndpoint<List<String>> cdiEventEndpoint;
// Only observes / consumes events having the @ContextName("foo") qualifier
from(cdiEventEndpoint).log("Camel context (foo) > CDI event received: ${body}");
// Produces / fires events with the @ContextName("foo") qualifier
from("...").to(cdiEventEndpoint);

void observeCdiEvents(@Observes @ContextName("foo") List<String> event) {
    logger.info("Camel context (foo) > CDI event: {}", event);
}

Note that the CDI event Camel endpoint dynamically adds an observer method for each unique combination of event type and event qualifiers and solely relies on the container typesafe observer resolution, which leads to an implementation as efficient as possible.

Besides, as the impedance between the typesafe nature of CDI and the dynamic nature of the Camel component model is quite high, it is not possible to create an instance of the CDI event Camel endpoint via URIs. Indeed, the URI format for the CDI event component is:

cdi-event://PayloadType<T1,...,Tn>[?qualifiers=QualifierType1[,...[,QualifierTypeN]...]]

With the authority PayloadType (resp. the QualifierType) being the URI escaped fully qualified name of the payload (resp. qualifier) raw type followed by the type parameters section delimited by angle brackets for payload parameterized type. Which leads to unfriendly URIs, e.g.:

cdi-event://org.apache.camel.cdi.example.EventPayload%3Cjava.lang.Integer%3E?qualifiers=org.apache.camel.cdi.example.FooQualifier%2Corg.apache.camel.cdi.example.BarQualifier

But more fundamentally, that would prevent efficient binding between the endpoint instances and the observer methods as the CDI container doesn’t have any ways of discovering the Camel context model during the deployment phase.

56.11. Camel XML configuration import

Available as of Camel 2.18

While CDI favors a typesafe dependency injection mechanism, it may be useful to reuse existing Camel XML configuration files into a Camel CDI application. In other use cases, it might be handy to rely on the Camel XML DSL to configure its Camel context(s).

You can use the @ImportResource annotation that’s provided by Camel CDI on any CDI beans and Camel CDI will automatically load the Camel XML configuration at the specified locations, e.g.:

@ImportResource("camel-context.xml")
class MyBean {
}

Camel CDI will load the resources at the specified locations from the classpath (other protocols may be added in the future).

Every CamelContext elements and other Camel primitives from the imported resources are automatically deployed as CDI beans during the container bootstrap so that they benefit from the auto-configuration provided by Camel CDI and become available for injection at runtime. If such an element has an explicit id attribute set, the corresponding CDI bean is qualified with the @Named qualifier, e.g., given the following Camel XML configuration:

<camelContext id="foo">
    <endpoint id="bar" uri="seda:inbound">
        <property key="queue" value="#queue"/>
        <property key="concurrentConsumers" value="10"/>
    </endpoint>
<camelContext/>

The corresponding CDI beans are automatically deployed and can be injected, e.g.:

@Inject
@ContextName("foo")
CamelContext context;

@Inject
@Named("bar")
Endpoint endpoint;

Note that the CamelContext beans are automatically qualified with both the @Named and @ContextName qualifiers. If the imported CamelContext element doesn’t have an id attribute, the corresponding bean is deployed with the built-in @Default qualifier.

Conversely, CDI beans deployed in the application can be referred to from the Camel XML configuration, usually using the ref attribute, e.g., given the following bean declared:

@Produces
@Named("baz")
Processor processor = exchange -> exchange.getIn().setHeader("qux", "quux");

A reference to that bean can be declared in the imported Camel XML configuration, e.g.:

<camelContext id="foo">
    <route>
        <from uri="..."/>
        <process ref="baz"/>
    </route>
<camelContext/>

56.12. Transaction support

Available as of Camel 2.19

Camel CDI provides support for Camel transactional client using JTA.

That support is optional hence you need to have JTA in your application classpath, e.g., by explicitly add JTA as a dependency when using Maven:

<dependency>
    <groupId>javax.transaction</groupId>
    <artifactId>javax.transaction-api</artifactId>
    <scope>runtime</scope>
</dependency>

You’ll have to have your application deployed in a JTA capable container or provide a standalone JTA implementation.

Caution

Note that, for the time being, the transaction manager is looked up as JNDI resource with the java:/TransactionManager key.

More flexible strategies will be added in the future to support a wider range of deployment scenarios.

56.12.1. Transaction policies

Camel CDI provides implementation for the typically supported Camel TransactedPolicy as CDI beans. It is possible to have these policies looked up by name using the transacted EIP, e.g.:

class MyRouteBean extends RouteBuilder {

    @Override
    public void configure() {
        from("activemq:queue:foo")
            .transacted("PROPAGATION_REQUIRED")
            .bean("transformer")
            .to("jpa:my.application.entity.Bar")
            .log("${body.id} inserted");
    }
}

This would be equivalent to:

class MyRouteBean extends RouteBuilder {

    @Inject
    @Named("PROPAGATION_REQUIRED")
    Policy required;

    @Override
    public void configure() {
        from("activemq:queue:foo")
            .policy(required)
            .bean("transformer")
            .to("jpa:my.application.entity.Bar")
            .log("${body.id} inserted");
    }
}

The list of supported transaction policy names is:

PROPAGATION_NEVER,
PROPAGATION_NOT_SUPPORTED,
PROPAGATION_SUPPORTS,
PROPAGATION_REQUIRED,
PROPAGATION_REQUIRES_NEW,
PROPAGATION_NESTED,
PROPAGATION_MANDATORY.

56.12.2. Transactional error handler

Camel CDI provides a transactional error handler that extends the redelivery error handler, forces a rollback whenever an exception occurs and creates a new transaction for each redelivery.

Camel CDI provides the CdiRouteBuilder class that exposes the transactionErrorHandler helper method to enable quick access to the configuration, e.g.:

class MyRouteBean extends CdiRouteBuilder {

    @Override
    public void configure() {
        errorHandler(transactionErrorHandler()
            .setTransactionPolicy("PROPAGATION_SUPPORTS")
            .maximumRedeliveries(5)
            .maximumRedeliveryDelay(5000)
            .collisionAvoidancePercent(10)
            .backOffMultiplier(1.5));
    }
}

56.13. Auto-configured OSGi integration

Available as of Camel 2.17

The Camel context beans are automatically adapted by Camel CDI so that they are registered as OSGi services and the various resolvers (like ComponentResolver and DataFormatResolver) integrate with the OSGi registry. That means that the Karaf Camel commands can be used to operate the Camel contexts auto-configured by Camel CDI, e.g.:

karaf@root()> camel:context-list
 Context        Status              Total #       Failed #     Inflight #   Uptime
 -------        ------              -------       --------     ----------   ------
 camel-cdi      Started                   1              0              0   1 minute

See the camel-example-cdi-osgi example for a working example of the Camel CDI OSGi integration.

56.14. Lazy Injection / Programmatic Lookup

While the CDI programmatic model favors a typesafe resolution mechanism that occurs at application initialization time, it is possible to perform dynamic / lazy injection later during the application execution using the programmatic lookup mechanism.

Camel CDI provides for convenience the annotation literals corresponding to the CDI qualifiers that you can use for standard injection of Camel primitives. These annotation literals can be used in conjunction with the javax.enterprise.inject.Instance interface which is the CDI entry point to perform lazy injection / programmatic lookup.

For example, you can use the provided annotation literal for the @Uri qualifier to lazily lookup for Camel primitives, e.g. for ProducerTemplate beans:

@Any
@Inject
Instance<ProducerTemplate> producers;

ProducerTemplate inbound = producers
    .select(Uri.Literal.of("direct:inbound"))
    .get();

Or for Endpoint beans, e.g.:

@Any
@Inject
Instance<Endpoint> endpoints;

MockEndpoint outbound = endpoints
    .select(MockEndpoint.class, Uri.Literal.of("mock:outbound"))
    .get();

Similarly, you can use the provided annotation literal for the @ContextName qualifier to lazily lookup for CamelContext beans, e.g.:

@Any
@Inject
Instance<CamelContext> contexts;

CamelContext context = contexts
    .select(ContextName.Literal.of("foo"))
    .get();

You can also refined the selection based on the Camel context type, e.g.:

@Any
@Inject
Instance<CamelContext> contexts;

// Refine the selection by type
Instance<DefaultCamelContext> context = contexts.select(DefaultCamelContext.class);

// Check if such a bean exists then retrieve a reference
if (!context.isUnsatisfied())
    context.get();

Or even iterate over a selection of Camel contexts, e.g.:

@Any
@Inject
Instance<CamelContext> contexts;

for (CamelContext context : contexts)
    context.setUseBreadcrumb(true);

56.15. Maven Archetype

Among the available Camel Maven archetypes, you can use the provided camel-archetype-cdi to generate a Camel CDI Maven project, e.g.:

mvn archetype:generate -DarchetypeGroupId=org.apache.camel.archetypes -DarchetypeArtifactId=camel-archetype-cdi

56.16. Supported containers

The Camel CDI component is compatible with any CDI 1.0, CDI 1.1 and CDI 1.2 compliant runtime. It’s been successfully tested against the following runtimes:

Container	Version	Runtime
Weld SE	`1.1.28.Final`	CDI 1.0 / Java SE 7
OpenWebBeans	`1.2.7`	CDI 1.0 / Java SE 7
Weld SE	`2.4.2.Final`	CDI 1.2 / Java SE 7
OpenWebBeans	`1.7.2`	CDI 1.2 / Java SE 7
WildFly	`8.2.1.Final`	CDI 1.2 / Java EE 7
WildFly	`9.0.1.Final`	CDI 1.2 / Java EE 7
WildFly	`10.1.0.Final`	CDI 1.2 / Java EE 7

56.17. Examples

The following examples are available in the examples directory of the Camel project:

Example	Description
`camel-example-cdi`	Illustrates how to work with Camel using CDI to configure components, endpoints and beans
`camel-example-cdi-kubernetes`	Illustrates the integration between Camel, CDI and Kubernetes
`camel-example-cdi-metrics`	Illustrates the integration between Camel, Dropwizard Metrics and CDI
`camel-example-cdi-properties`	Illustrates the integration between Camel, DeltaSpike and CDI for configuration properties
`camel-example-cdi-osgi`	A CDI application using the SJMS component that can be executed inside an OSGi container using PAX CDI
`camel-example-cdi-rest-servlet`	Illustrates the Camel REST DSL being used in a Web application that uses CDI as dependency injection framework
`camel-example-cdi-test`	Demonstrates the testing features that are provided as part of the integration between Camel and CDI
`camel-example-cdi-xml`	Illustrates the use of Camel XML configuration files into a Camel CDI application
`camel-example-swagger-cdi`	An example using REST DSL and Swagger Java with CDI
`camel-example-widget-gadget-cdi`	The Widget and Gadget use-case from the EIP book implemented in Java with CDI dependency Injection

56.18. See Also

Camel CDI testing
CDI specification Web site
CDI ecosystem
Weld home page
OpenWebBeans home page
Going further with CDI and Camel (See Camel CDI section)

Chapter 57. Chronicle Engine Component

Available as of Camel version 2.18

The camel chronicle-engine component let you leverage the power of OpenHFT’s Chronicle-Engine

57.1. URI Format

chronicle-engine:addresses/path[?options]

57.2. URI Options

The Chronicle Engine component has no options.

The Chronicle Engine endpoint is configured using URI syntax:

chronicle-engine:addresses/path

with the following path and query parameters:

57.2.1. Path Parameters (2 parameters):

Name	Description	Default	Type
addresses	Required Engine addresses. Multiple addresses can be separated by comma.		String
path	Required Engine path		String

57.2.2. Query Parameters (12 parameters):

Name	Description	Default	Type
action (common)	The default action to perform, valid values are: - PUBLISH - PPUBLISH_AND_INDEX - PPUT - PGET_AND_PUT - PPUT_ALL - PPUT_IF_ABSENT - PGET - PGET_AND_REMOVE - PREMOVE - PIS_EMPTY - PSIZE		String
clusterName (common)	Cluster name for queue		String
filteredMapEvents (common)	A comma separated list of Map event type to filer, valid values are: INSERT, UPDATE, REMOVE.		String
persistent (common)	Enable/disable data persistence	true	boolean
subscribeMapEvents (common)	Set if consumer should subscribe to Map events, default true.	true	boolean
subscribeTopicEvents (common)	Set if consumer should subscribe to TopicEvents,d efault false.	false	boolean
subscribeTopologicalEvents (common)	Set if consumer should subscribe to TopologicalEvents,d efault false.	false	boolean
wireType (common)	The Wire type to use, default to binary wire.	BINARY	String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

Chapter 58. Chunk Component

Available as of Camel version 2.15

The chunk: component allows for processing a message using a Chunk 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:

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

58.1. URI format

chunk:templateName[?options]

Where templateName is the classpath-local URI of the template to invoke.

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

58.2. Options

The Chunk component has no options.

The Chunk endpoint is configured using URI syntax:

chunk:resourceUri

with the following path and query parameters:

58.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
resourceUri	Required Path to the resource. You can prefix with: classpath, file, http, ref, or bean. classpath, file and http loads the resource using these protocols (classpath is default). ref will lookup the resource in the registry. bean will call a method on a bean to be used as the resource. For bean you can specify the method name after dot, eg bean:myBean.myMethod.		String

58.2.2. Query Parameters (7 parameters):

Name	Description	Default	Type
contentCache (producer)	Sets whether to use resource content cache or not	false	boolean
encoding (producer)	Define the encoding of the body		String
extension (producer)	Define the file extension of the template		String
themeFolder (producer)	Define the themes folder to scan		String
themeLayer (producer)	Define the theme layer to elaborate		String
themeSubfolder (producer)	Define the themes subfolder to scan		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

Chunk component will look for a specific template in themes folder with extensions .chtml or _.cxml. _If you need to specify a different folder or extensions, you will need to use the specific options listed above.

58.3. Chunk Context

Camel will provide exchange information in the Chunk 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).

58.4. 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
ChunkConstants.CHUNK_RESOURCE_URI	String	A URI for the template resource to use instead of the endpoint configured.
ChunkConstants.CHUNK_TEMPLATE	String	The template to use instead of the endpoint configured.

58.5. Samples

For example you could use something like:

from("activemq:My.Queue").
to("chunk:template");

To use a Chunk 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:

from("activemq:My.Queue").
to("chunk:template").
to("activemq:Another.Queue");

It’s possible to specify what template the component should use dynamically via a header, so for example:

from("direct:in").
setHeader(ChunkConstants.CHUNK_RESOURCE_URI).constant("template").
to("chunk:dummy");

An example of Chunk component options use:

from("direct:in").
to("chunk:file_example?themeFolder=template&themeSubfolder=subfolder&extension=chunk");

In this example Chunk component will look for the file file_example.chunk in the folder template/subfolder.

58.6. The Email Sample

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

 
Dear {$headers.lastName}, {$headers.firstName}

Thanks for the order of {$headers.item}.

Regards Camel Riders Bookstore
{$body}

58.7. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 59. Class Component

Available as of Camel version 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.

59.1. URI format

class:className[?options]

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

59.2. Options

The Class component has no options.

The Class endpoint is configured using URI syntax:

class:beanName

with the following path and query parameters:

59.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
beanName	Required Sets the name of the bean to invoke		String

59.2.2. Query Parameters (5 parameters):

Name	Description	Default	Type
method (producer)	Sets the name of the method to invoke on the bean		String
cache (advanced)	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.	false	boolean
multiParameterArray (advanced)	Deprecated How to treat the parameters which are passed from the message body; if it is true, the message body should be an array of parameters. Note: This option is used internally by Camel, and is not intended for end users to use. Deprecation note: This option is used internally by Camel, and is not intended for end users to use.	false	boolean
parameters (advanced)	Used for configuring additional properties on the bean		Map
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

59.3. Using

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

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

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

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

59.4. Setting properties on the created instance

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

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

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

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

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

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

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

59.5. See Also

Configuring Camel
Component
Endpoint
Getting Started
Bean
Bean Binding
Bean Integration

Chapter 60. CMIS Component

Available as of Camel version 2.11

The cmis component uses the Apache Chemistry client API and allows you to add/read nodes to/from a CMIS compliant content repositories.

60.1. URI Format

cmis://cmisServerUrl[?options]

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

60.2. CMIS Options

The CMIS component supports 2 options which are listed below.

Name	Description	Default	Type
sessionFacadeFactory (common)	To use a custom CMISSessionFacadeFactory to create the CMISSessionFacade instances		CMISSessionFacade Factory
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The CMIS endpoint is configured using URI syntax:

cmis:cmsUrl

with the following path and query parameters:

60.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cmsUrl	Required URL to the cmis repository		String

60.2.2. Query Parameters (13 parameters):

Name	Description	Default	Type
pageSize (common)	Number of nodes to retrieve per page	100	int
readContent (common)	If set to true, the content of document node will be retrieved in addition to the properties	false	boolean
readCount (common)	Max number of nodes to read		int
repositoryId (common)	The Id of the repository to use. If not specified the first available repository is used		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
query (consumer)	The cmis query to execute against the repository. If not specified, the consumer will retrieve every node from the content repository by iterating the content tree recursively		String
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
queryMode (producer)	If true, will execute the cmis query from the message body and return result, otherwise will create a node in the cmis repository	false	boolean
sessionFacadeFactory (advanced)	To use a custom CMISSessionFacadeFactory to create the CMISSessionFacade instances		CMISSessionFacade Factory
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
password (security)	Password for the cmis repository		String
username (security)	Username for the cmis repository		String

60.3. Usage

60.3.1. Message headers evaluated by the producer

Header	Default Value	Description
`CamelCMISFolderPath`	`/`	The current folder to use during the execution. If not specified will use the root folder
`CamelCMISRetrieveContent`	`false`	In `queryMode` this header will force the producer to retrieve the content of document nodes.
`CamelCMISReadSize`	`0`	Max number of nodes to read.
`cmis:path`	`null`	If `CamelCMISFolderPath` is not set, will try to find out the path of the node from this cmis property and it is name
`cmis:name`	`null`	If `CamelCMISFolderPath` is not set, will try to find out the path of the node from this cmis property and it is path
`cmis:objectTypeId`	`null`	The type of the node
`cmis:contentStreamMimeType`	`null`	The mimetype to set for a document

60.3.2. Message headers set during querying Producer operation

Header	Type	Description
`CamelCMISResultCount`	`Integer`	Number of nodes returned from the query.

The message body will contain a list of maps, where each entry in the map is cmis property and its value. If CamelCMISRetrieveContent header is set to true, one additional entry in the map with key CamelCMISContent will contain InputStream of the document type of nodes.

60.4. Dependencies

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

pom.xml

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

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

60.5. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 61. CM SMS Gateway Component

Available as of Camel version 2.18

Camel-Cm-Sms is an Apache Camel component for the [CM SMS Gateway](https://www.cmtelecom.com).

It allows to integrate CM SMS APIin an application as a camel component.

You must have a valid account. More information are available at CM Telecom.

cm-sms://sgw01.cm.nl/gateway.ashx?defaultFrom=DefaultSender&defaultMaxNumberOfParts=8&productToken=xxxxx

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

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

61.1. Options

The CM SMS Gateway component has no options.

The CM SMS Gateway endpoint is configured using URI syntax:

cm-sms:host

with the following path and query parameters:

61.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
host	Required SMS Provider HOST with scheme		String

61.1.2. Query Parameters (5 parameters):

Name	Description	Default	Type
defaultFrom (producer)	This is the sender name. The maximum length is 11 characters.		String
defaultMaxNumberOfParts (producer)	If it is a multipart message forces the max number. Message can be truncated. Technically the gateway will first check if a message is larger than 160 characters, if so, the message will be cut into multiple 153 characters parts limited by these parameters.	8	int
productToken (producer)	Required The unique token to use		String
testConnectionOnStartup (producer)	Whether to test the connection to the SMS Gateway on startup	false	boolean
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

61.2. Sample

You can try this project to see how camel-cm-sms can be integrated in a camel route.

Chapter 62. CoAP Component

Available as of Camel version 2.16

Camel-CoAP is an Apache Camel component that allows you to work with CoAP, a lightweight REST-type protocol for machine-to-machine operation. CoAP, Constrained Application Protocol is a specialized web transfer protocol for use with constrained nodes and constrained networks and it is based on RFC 7252.

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

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

62.1. Options

The CoAP component has no options.

The CoAP endpoint is configured using URI syntax:

coap:uri

with the following path and query parameters:

62.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
uri	The URI for the CoAP endpoint		URI

62.1.2. Query Parameters (5 parameters):

Name	Description	Default	Type
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
coapMethodRestrict (consumer)	Comma separated list of methods that the CoAP consumer will bind to. The default is to bind to all methods (DELETE, GET, POST, PUT).		String
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

62.2. Message Headers

Name	Type	Description
`CamelCoapMethod`	`String`	The request method that the CoAP producer should use when calling the target CoAP server URI. Valid options are DELETE, GET, PING, POST & PUT.
`CamelCoapResponseCode`	`String`	The CoAP response code sent by the external server. See RFC 7252 for details of what each code means.
`CamelCoapUri`	`String`	The URI of a CoAP server to call. Will override any existing URI configured directly on the endpoint.

62.2.1. Configuring the CoAP producer request method

The following rules determine which request method the CoAP producer will use to invoke the target URI:

The value of the CamelCoapMethod header
GET if a query string is provided on the target CoAP server URI.
POST if the message exchange body is not null.
GET otherwise.

Chapter 63. Constant Language

Available as of Camel version 1.5

The Constant Expression Language is really just a way to specify constant strings as a type of expression.

Note

This is a fixed constant value that is only set once during starting up the route, do not use this if you want dynamic values during routing.

63.1. Constant Options

The Constant language supports 1 options which are listed below.

Name	Default	Java Type	Description
trim	`true`	`Boolean`	Whether to trim the value to remove leading and trailing whitespaces and line breaks

63.2. Example usage

The setHeader element of the Spring DSL can utilize a constant expression like:

<route>
  <from uri="seda:a"/>
  <setHeader headerName="theHeader">
    <constant>the value</constant>
  </setHeader>
  <to uri="mock:b"/>
</route>

in this case, the Message coming from the seda:a Endpoint will have 'theHeader' header set to the constant value 'the value'.

And the same example using Java DSL:

from("seda:a")
  .setHeader("theHeader", constant("the value"))
  .to("mock:b");

63.3. Dependencies

The Constant language is part of camel-core.

Chapter 64. CometD Component

Available as of Camel version 2.0

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

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

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

64.1. URI format

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

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

64.2. Examples

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

where cometds: represents an SSL configured endpoint.

64.3. Options

The CometD component supports 8 options which are listed below.

Name	Description	Default	Type
sslKeyPassword (security)	The password for the keystore when using SSL.		String
sslPassword (security)	The password when using SSL.		String
sslKeystore (security)	The path to the keystore.		String
securityPolicy (security)	To use a custom configured SecurityPolicy to control authorization		SecurityPolicy
extensions (common)	To use a list of custom BayeuxServer.Extension that allows modifying incoming and outgoing requests.		List
sslContextParameters (security)	To configure security using SSLContextParameters		SSLContextParameters
useGlobalSslContext Parameters (security)	Enable usage of global SSL context parameters.	false	boolean
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The CometD endpoint is configured using URI syntax:

cometd:host:port/channelName

with the following path and query parameters:

64.3.1. Path Parameters (3 parameters):

Name	Description	Type
host	Required Hostname	String
port	Required Host port number	int
channelName	Required The channelName represents a topic that can be subscribed to by the Camel endpoints.	String

64.3.2. Query Parameters (16 parameters):

Name	Description	Default	Type
allowedOrigins (common)	The origins domain that support to cross, if the crosssOriginFilterOn is true	*	String
baseResource (common)	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		String
crossOriginFilterOn (common)	If true, the server will support for cross-domain filtering	false	boolean
filterPath (common)	The filterPath will be used by the CrossOriginFilter, if the crosssOriginFilterOn is true		String
interval (common)	The client side poll timeout in milliseconds. How long a client will wait between reconnects		int
jsonCommented (common)	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.	true	boolean
logLevel (common)	Logging level. 0=none, 1=info, 2=debug.	1	int
maxInterval (common)	The max client side poll timeout in milliseconds. A client will be removed if a connection is not received in this time.	30000	int
multiFrameInterval (common)	The client side poll timeout, if multiple connections are detected from the same browser.	1500	int
timeout (common)	The server side poll timeout in milliseconds. This is how long the server will hold a reconnect request before responding.	240000	int
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
sessionHeadersEnabled (consumer)	Whether to include the server session headers in the Camel message when creating a Camel Message for incoming requests.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
disconnectLocalSession (producer)	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.	false	boolean
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

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

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

64.5. Setting up SSL for Cometd Component

64.5.1. Using the JSSE Configuration Utility

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

Programmatic configuration of the component

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

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

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

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

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

Spring DSL based configuration of endpoint

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

64.6. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 65. Consul Component

Available as of Camel version 2.18

The Consul component is a component for integrating your application with Consul.

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

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

65.1. URI format

    consul://domain?[options]

You can append query options to the URI in the following format:

    ?option=value&option=value&...

65.2. Options

The Consul component supports 9 options which are listed below.

Name	Description	Default	Type
url (common)	The Consul agent URL		String
datacenter (common)	The data center		String
sslContextParameters (common)	SSL configuration using an org.apache.camel.util.jsse.SSLContextParameters instance.		SSLContextParameters
useGlobalSslContext Parameters (security)	Enable usage of global SSL context parameters.	false	boolean
aclToken (common)	Sets the ACL token to be used with Consul		String
userName (common)	Sets the username to be used for basic authentication		String
password (common)	Sets the password to be used for basic authentication		String
configuration (advanced)	Sets the common configuration shared among endpoints		ConsulConfiguration
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Consul endpoint is configured using URI syntax:

consul:apiEndpoint

with the following path and query parameters:

65.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
apiEndpoint	Required The API endpoint		String

65.2.2. Query Parameters (4 parameters):

Name	Description	Default	Type
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

65.3. Headers

Name	Type	Description
CamelConsulAction	String	The Producer action
CamelConsulKey	String	The Key on which the action should applied
CamelConsulEventId	String	The event id (consumer only)
CamelConsulEventName	String	The event name (consumer only)
CamelConsulEventLTime	Long	The event LTime
CamelConsulNodeFilter	String	The Node filter
CamelConsulTagFilter	String	The tag filter
CamelConsulSessionFilter	String	The session filter
CamelConsulVersion	int	The data version
CamelConsulFlags	Long	Flags associated with a value
CamelConsulCreateIndex	Long	The internal index value that represents when the entry was created
CamelConsulLockIndex	Long	The number of times this key has successfully been acquired in a lock
CamelConsulModifyIndex	Long	The last index that modified this key
CamelConsulOptions	Object	Options associated to the request
CamelConsulResult	boolean	true if the response has a result
CamelConsulSession	String	The session id
CamelConsulValueAsString	boolean	To transform values retrieved from Consul i.e. on KV endpoint to string.

Chapter 66. Control Bus Component

Available as of Camel version 2.11

The Control Bus from the EIP patterns allows for the integration system to be monitored and managed from within the framework.

Use a Control Bus to manage an enterprise integration system. The Control Bus uses the same messaging mechanism used by the application data, but uses separate channels to transmit data that is relevant to the management of components involved in the message flow.

In Camel you can manage and monitor using JMX, or by using a Java API from the CamelContext, or from the org.apache.camel.api.management package,
or use the event notifier which has an example here.

From Camel 2.11 onwards we have introduced a new ControlBus Component that allows you to send messages to a control bus Endpoint that reacts accordingly.

66.1. ControlBus Component

Available as of Camel 2.11

The controlbus: component provides easy management of Camel applications based on the Control Bus EIP pattern. For example, by sending a message to an Endpoint you can control the lifecycle of routes, or gather performance statistics.

controlbus:command[?options]

Where command can be any string to identify which type of command to use.

66.2. Commands

Command	Description
`route`	To control routes using the `routeId` and `action` parameter.
`language`	Allows you to specify a Language to use for evaluating the message body. If there is any result from the evaluation, then the result is put in the message body.

66.3. Options

The Control Bus component has no options.

The Control Bus endpoint is configured using URI syntax:

controlbus:command:language

with the following path and query parameters:

66.3.1. Path Parameters (2 parameters):

Name	Description	Default	Type
command	Required Command can be either route or language		String
language	Allows you to specify the name of a Language to use for evaluating the message body. If there is any result from the evaluation, then the result is put in the message body.		Language

66.3.2. Query Parameters (6 parameters):

Name	Description	Default	Type
action (producer)	To denote an action that can be either: start, stop, or status. To either start or stop a route, or to get the status of the route as output in the message body. You can use suspend and resume from Camel 2.11.1 onwards to either suspend or resume a route. And from Camel 2.11.1 onwards you can use stats to get performance statics returned in XML format; the routeId option can be used to define which route to get the performance stats for, if routeId is not defined, then you get statistics for the entire CamelContext. The restart action will restart the route.		String
async (producer)	Whether to execute the control bus task asynchronously. Important: If this option is enabled, then any result from the task is not set on the Exchange. This is only possible if executing tasks synchronously.	false	boolean
loggingLevel (producer)	Logging level used for logging when task is done, or if any exceptions occurred during processing the task.	INFO	LoggingLevel
restartDelay (producer)	The delay in millis to use when restarting a route.	1000	int
routeId (producer)	To specify a route by its id. The special keyword current indicates the current route.		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

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

66.4. Using route command

The route command allows you to do common tasks on a given route very easily, for example to start a route, you can send an empty message to this endpoint:

template.sendBody("controlbus:route?routeId=foo&action=start", null);

To get the status of the route, you can do:

String status = template.requestBody("controlbus:route?routeId=foo&action=status", null, String.class);

66.5. Getting performance statistics

Available as of Camel 2.11.1

This requires JMX to be enabled (is by default) then you can get the performance statics per route, or for the CamelContext. For example to get the statics for a route named foo, we can do:

String xml = template.requestBody("controlbus:route?routeId=foo&action=stats", null, String.class);

The returned statics is in XML format. Its the same data you can get from JMX with the dumpRouteStatsAsXml operation on the ManagedRouteMBean.

To get statics for the entire CamelContext you just omit the routeId parameter as shown below:

String xml = template.requestBody("controlbus:route?action=stats", null, String.class);

66.6. Using Simple language

You can use the Simple language with the control bus, for example to stop a specific route, you can send a message to the "controlbus:language:simple" endpoint containing the following message:

template.sendBody("controlbus:language:simple", "${camelContext.stopRoute('myRoute')}");

As this is a void operation, no result is returned. However, if you want the route status you can do:

String status = template.requestBody("controlbus:language:simple", "${camelContext.getRouteStatus('myRoute')}", String.class);

It’s easier to use the route command to control lifecycle of routes. The language command allows you to execute a language script that has stronger powers such as Groovy or to some extend the Simple language.

For example to shutdown Camel itself you can do:

template.sendBody("controlbus:language:simple?async=true", "${camelContext.stop()}");

We use async=true to stop Camel asynchronously as otherwise we would be trying to stop Camel while it was in-flight processing the message we sent to the control bus component.

Tip

You can also use other languages such as Groovy, etc.

Chapter 67. Couchbase Component

Available as of Camel version 2.19

The couchbase: component allows you to treat CouchBase instances as a producer or consumer of messages.

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

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

67.1. URI format

couchbase:url

67.2. Options

The Couchbase component has no options.

The Couchbase endpoint is configured using URI syntax:

couchbase:protocol:hostname:port

with the following path and query parameters:

67.2.1. Path Parameters (3 parameters):

Name	Description	Default	Type
protocol	Required The protocol to use		String
hostname	Required The hostname to use		String
port	The port number to use	8091	int

67.2.2. Query Parameters (47 parameters):

Name	Description	Default	Type
bucket (common)	The bucket to use		String
key (common)	The key to use		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
consumerProcessedStrategy (consumer)	Define the consumer Processed strategy to use	none	String
descending (consumer)	Define if this operation is descending or not	false	boolean
designDocumentName (consumer)	The design document name to use	beer	String
limit (consumer)	The output limit to use	-1	int
rangeEndKey (consumer)	Define a range for the end key		String
rangeStartKey (consumer)	Define a range for the start key		String
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
skip (consumer)	Define the skip to use	-1	int
viewName (consumer)	The view name to use	brewery_beers	String
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
autoStartIdForInserts (producer)	Define if we want an autostart Id when we are doing an insert operation	false	boolean
operation (producer)	The operation to do	CCB_PUT	String
persistTo (producer)	Where to persist the data	0	int
producerRetryAttempts (producer)	Define the number of retry attempts	2	int
producerRetryPause (producer)	Define the retry pause between different attempts	5000	int
replicateTo (producer)	Where to replicate the data	0	int
startingIdForInsertsFrom (producer)	Define the starting Id where we are doing an insert operation		long
additionalHosts (advanced)	The additional hosts		String
maxReconnectDelay (advanced)	Define the max delay during a reconnection	30000	long
obsPollInterval (advanced)	Define the observation polling interval	400	long
obsTimeout (advanced)	Define the observation timeout	-1	long
opQueueMaxBlockTime (advanced)	Define the max time an operation can be in queue blocked	10000	long
opTimeOut (advanced)	Define the operation timeout	2500	long
readBufferSize (advanced)	Define the buffer size	16384	int
shouldOptimize (advanced)	Define if we want to use optimization or not where possible	false	boolean
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
timeoutExceptionThreshold (advanced)	Define the threshold for throwing a timeout Exception	998	int
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean
password (security)	The password to use		String
username (security)	The username to use		String

Chapter 68. CouchDB Component

Available as of Camel version 2.11

The couchdb: component allows you to treat CouchDB instances as a producer or consumer of messages. Using the lightweight LightCouch API, this camel component has the following features:

As a consumer, monitors couch changesets for inserts, updates and deletes and publishes these as messages into camel routes.
As a producer, can save, update and from Camel 2.18 delete (by using CouchDbMethod with DELETE value) documents into couch.
Can support as many endpoints as required, eg for multiple databases across multiple instances.
Ability to have events trigger for only deletes, only inserts/updates or all (default).
Headers set for sequenceId, document revision, document id, and HTTP method type.

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

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

68.1. URI format

couchdb:http://hostname[:port]/database?[options]

Where hostname is the hostname of the running couchdb instance. Port is optional and if not specified then defaults to 5984.

68.2. Options

The CouchDB component has no options.

The CouchDB endpoint is configured using URI syntax:

couchdb:protocol:hostname:port/database

with the following path and query parameters:

68.2.1. Path Parameters (4 parameters):

Name	Description	Default	Type
protocol	Required The protocol to use for communicating with the database.		String
hostname	Required Hostname of the running couchdb instance		String
port	Port number for the running couchdb instance	5984	int
database	Required Name of the database to use		String

68.2.2. Query Parameters (12 parameters):

Name	Description	Default	Type
createDatabase (common)	Creates the database if it does not already exist	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
deletes (consumer)	Document deletes are published as events	true	boolean
heartbeat (consumer)	How often to send an empty message to keep socket alive in millis	30000	long
since (consumer)	Start tracking changes immediately after the given update sequence. The default, null, will start monitoring from the latest sequence.		String
style (consumer)	Specifies how many revisions are returned in the changes array. The default, main_only, will only return the current winning revision; all_docs will return all leaf revisions (including conflicts and deleted former conflicts.)	main_only	String
updates (consumer)	Document inserts/updates are published as events	true	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
password (security)	Password for authenticated databases		String
username (security)	Username in case of authenticated databases		String

68.3. Headers

The following headers are set on exchanges during message transport.

Property	Value
`CouchDbDatabase`	the database the message came from
`CouchDbSeq`	the couchdb changeset sequence number of the update / delete message
`CouchDbId`	the couchdb document id
`CouchDbRev`	the couchdb document revision
`CouchDbMethod`	the method (delete / update)

Headers are set by the consumer once the message is received. The producer will also set the headers for downstream processors once the insert/update has taken place. Any headers set prior to the producer are ignored. That means for example, if you set CouchDbId as a header, it will not be used as the id for insertion, the id of the document will still be used.

68.4. Message Body

The component will use the message body as the document to be inserted. If the body is an instance of String, then it will be marshalled into a GSON object before insert. This means that the string must be valid JSON or the insert / update will fail. If the body is an instance of a com.google.gson.JsonElement then it will be inserted as is. Otherwise the producer will throw an exception of unsupported body type.

68.5. Samples

For example if you wish to consume all inserts, updates and deletes from a CouchDB instance running locally, on port 9999 then you could use the following:

from("couchdb:http://localhost:9999").process(someProcessor);

If you were only interested in deletes, then you could use the following

from("couchdb:http://localhost:9999?updates=false").process(someProcessor);

If you wanted to insert a message as a document, then the body of the exchange is used

from("someProducingEndpoint").process(someProcessor).to("couchdb:http://localhost:9999")

Chapter 69. Cassandra CQL Component

Available as of Camel version 2.15

Apache Cassandra is an open source NoSQL database designed to handle large amounts on commodity hardware. Like Amazon’s DynamoDB, Cassandra has a peer-to-peer and master-less architecture to avoid single point of failure and garanty high availability. Like Google’s BigTable, Cassandra data is structured using column families which can be accessed through the Thrift RPC API or a SQL-like API called CQL.

This component aims at integrating Cassandra 2.0+ using the CQL3 API (not the Thrift API). It’s based on Cassandra Java Driver provided by DataStax.

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

pom.xml

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

69.1. URI format

The endpoint can initiate the Cassandra connection or use an existing one.

URI	Description
`cql:localhost/keyspace`	Single host, default port, usual for testing
`cql:host1,host2/keyspace`	Multi host, default port
`cql:host1,host2:9042/keyspace`	Multi host, custom port
`cql:host1,host2`	Default port and keyspace
`cql:bean:sessionRef`	Provided Session reference
`cql:bean:clusterRef/keyspace`	Provided Cluster reference

To fine tune the Cassandra connection (SSL options, pooling options, load balancing policy, retry policy, reconnection policy…), create your own Cluster instance and give it to the Camel endpoint.

69.2. Cassandra Options

The Cassandra CQL component has no options.

The Cassandra CQL endpoint is configured using URI syntax:

cql:beanRef:hosts:port/keyspace

with the following path and query parameters:

69.2.1. Path Parameters (4 parameters):

Name	Description	Type
beanRef	beanRef is defined using bean:id	String
hosts	Hostname(s) cassansdra server(s). Multiple hosts can be separated by comma.	String
port	Port number of cassansdra server(s)	Integer
keyspace	Keyspace to use	String

69.2.2. Query Parameters (29 parameters):

Name	Description	Default	Type
cluster (common)	To use the Cluster instance (you would normally not use this option)		Cluster
clusterName (common)	Cluster name		String
consistencyLevel (common)	Consistency level to use		ConsistencyLevel
cql (common)	CQL query to perform. Can be overridden with the message header with key CamelCqlQuery.		String
loadBalancingPolicy (common)	To use a specific LoadBalancingPolicy		String
password (common)	Password for session authentication		String
prepareStatements (common)	Whether to use PreparedStatements or regular Statements	true	boolean
resultSetConversionStrategy (common)	To use a custom class that implements logic for converting ResultSet into message body ALL, ONE, LIMIT_10, LIMIT_100…		String
session (common)	To use the Session instance (you would normally not use this option)		Session
username (common)	Username for session authentication		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean

69.3. Messages

69.3.1. Incoming Message

The Camel Cassandra endpoint expects a bunch of simple objects (Object or Object[] or Collection<Object>) which will be bound to the CQL statement as query parameters. If message body is null or empty, then CQL query will be executed without binding parameters.

Headers:

CamelCqlQuery (optional, String or RegularStatement): CQL query either as a plain String or built using the QueryBuilder.

69.3.2. Outgoing Message

The Camel Cassandra endpoint produces one or many a Cassandra Row objects depending on the resultSetConversionStrategy:

List<Row> if resultSetConversionStrategy is ALL or LIMIT_[0-9]+
Single` Row` if resultSetConversionStrategy is ONE
Anything else, if resultSetConversionStrategy is a custom implementation of the ResultSetConversionStrategy

69.4. Repositories

Cassandra can be used to store message keys or messages for the idempotent and aggregation EIP.

Cassandra might not be the best tool for queuing use cases yet, read Cassandra anti-patterns queues and queue like datasets. It’s advised to use LeveledCompaction and a small GC grace setting for these tables to allow tombstoned rows to be removed quickly.

69.5. Idempotent repository

The NamedCassandraIdempotentRepository stores messages keys in a Cassandra table like this:

CAMEL_IDEMPOTENT.cql

CREATE TABLE CAMEL_IDEMPOTENT (
  NAME varchar,   -- Repository name
  KEY varchar,    -- Message key
  PRIMARY KEY (NAME, KEY)
) WITH compaction = {'class':'LeveledCompactionStrategy'}
  AND gc_grace_seconds = 86400;

This repository implementation uses lightweight transactions (also known as Compare and Set) and requires Cassandra 2.0.7+.

Alternatively, the CassandraIdempotentRepository does not have a NAME column and can be extended to use a different data model.

Option	Default	Description
`table`	`CAMEL_IDEMPOTENT`	Table name
`pkColumns`	`NAME`,` KEY`	Primary key columns
`name`		Repository name, value used for `NAME` column
`ttl`		Key time to live
`writeConsistencyLevel`		Consistency level used to insert/delete key: `ANY`, `ONE`, `TWO`, `QUORUM`, `LOCAL_QUORUM`…
`readConsistencyLevel`		Consistency level used to read/check key: `ONE`, `TWO`, `QUORUM`, `LOCAL_QUORUM`…

69.6. Aggregation repository

The NamedCassandraAggregationRepository stores exchanges by correlation key in a Cassandra table like this:

CAMEL_AGGREGATION.cql

CREATE TABLE CAMEL_AGGREGATION (
  NAME varchar,        -- Repository name
  KEY varchar,         -- Correlation id
  EXCHANGE_ID varchar, -- Exchange id
  EXCHANGE blob,       -- Serialized exchange
  PRIMARY KEY (NAME, KEY)
) WITH compaction = {'class':'LeveledCompactionStrategy'}
  AND gc_grace_seconds = 86400;

Alternatively, the CassandraAggregationRepository does not have a NAME column and can be extended to use a different data model.

Option	Default	Description
`table`	`CAMEL_AGGREGATION`	Table name
`pkColumns`	`NAME`,`KEY`	Primary key columns
`exchangeIdColumn`	`EXCHANGE_ID`	Exchange Id column
`exchangeColumn`	`EXCHANGE`	Exchange content column
`name`		Repository name, value used for `NAME` column
`ttl`		Exchange time to live
`writeConsistencyLevel`		Consistency level used to insert/delete exchange: `ANY`, `ONE`, `TWO`, `QUORUM`, `LOCAL_QUORUM`…
`readConsistencyLevel`		Consistency level used to read/check exchange: `ONE`, `TWO`, `QUORUM`, `LOCAL_QUORUM`…

Chapter 70. Crypto (JCE) Component

Available as of Camel version 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:

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

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

70.2. URI format

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

crypto:sign:name[?options]
crypto:verify:name[?options]

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

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

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

70.3. Options

The Crypto (JCE) component supports 2 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	To use the shared DigitalSignatureConfiguration as configuration		DigitalSignature Configuration
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Crypto (JCE) endpoint is configured using URI syntax:

crypto:cryptoOperation:name

with the following path and query parameters:

70.3.1. Path Parameters (2 parameters):

Name	Description	Default	Type
cryptoOperation	Required Set the Crypto operation from that supplied after the crypto scheme in the endpoint uri e.g. crypto:sign sets sign as the operation.		CryptoOperation
name	Required The logical name of this operation.		String

70.3.2. Query Parameters (19 parameters):

Name	Description	Default	Type
algorithm (producer)	Sets the JCE name of the Algorithm that should be used for the signer.	SHA1WithDSA	String
alias (producer)	Sets the alias used to query the KeyStore for keys and link java.security.cert.Certificate Certificates to be used in signing and verifying exchanges. This value can be provided at runtime via the message header link org.apache.camel.component.crypto.DigitalSignatureConstantsKEYSTORE_ALIAS		String
certificateName (producer)	Sets the reference name for a PrivateKey that can be fond in the registry.		String
keystore (producer)	Sets the KeyStore that can contain keys and Certficates for use in signing and verifying exchanges. A KeyStore is typically used with an alias, either one supplied in the Route definition or dynamically via the message header CamelSignatureKeyStoreAlias. If no alias is supplied and there is only a single entry in the Keystore, then this single entry will be used.		KeyStore
keystoreName (producer)	Sets the reference name for a Keystore that can be fond in the registry.		String
privateKey (producer)	Set the PrivateKey that should be used to sign the exchange		PrivateKey
privateKeyName (producer)	Sets the reference name for a PrivateKey that can be fond in the registry.		String
provider (producer)	Set the id of the security provider that provides the configured Signature algorithm.		String
publicKeyName (producer)	references that should be resolved when the context changes		String
secureRandomName (producer)	Sets the reference name for a SecureRandom that can be fond in the registry.		String
signatureHeaderName (producer)	Set the name of the message header that should be used to store the base64 encoded signature. This defaults to 'CamelDigitalSignature'		String
bufferSize (advanced)	Set the size of the buffer used to read in the Exchange payload data.	2048	Integer
certificate (advanced)	Set the Certificate that should be used to verify the signature in the exchange based on its payload.		Certificate
clearHeaders (advanced)	Determines if the Signature specific headers be cleared after signing and verification. Defaults to true, and should only be made otherwise at your extreme peril as vital private information such as Keys and passwords may escape if unset.	true	boolean
keyStoreParameters (advanced)	Sets the KeyStore that can contain keys and Certficates for use in signing and verifying exchanges based on the given KeyStoreParameters. A KeyStore is typically used with an alias, either one supplied in the Route definition or dynamically via the message header CamelSignatureKeyStoreAlias. If no alias is supplied and there is only a single entry in the Keystore, then this single entry will be used.		KeyStoreParameters
publicKey (advanced)	Set the PublicKey that should be used to verify the signature in the exchange.		PublicKey
secureRandom (advanced)	Set the SecureRandom used to initialize the Signature service		SecureRandom
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
password (security)	Sets the password used to access an aliased PrivateKey in the KeyStore.		String

70.4. Using

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

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

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

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

70.4.5. Changing the buffersize

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

or

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

Exchange unsigned = getMandatoryEndpoint("direct:alias-sign").createExchange();
unsigned.getIn().setBody(payload);
unsigned.getIn().setHeader(DigitalSignatureConstants.KEYSTORE_ALIAS, "bob");
unsigned.getIn().setHeader(DigitalSignatureConstants.KEYSTORE_PASSWORD, "letmein".toCharArray());
template.send("direct:alias-sign", unsigned);
Exchange signed = getMandatoryEndpoint("direct:alias-sign").createExchange();
signed.getIn().copyFrom(unsigned.getOut());
signed.getIn().setHeader(KEYSTORE_ALIAS, "bob");
template.send("direct:alias-verify", signed);

70.5. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 71. Crypto CMS Component

Available as of Camel version 2.20

Cryptographic Message Syntax (CMS) is a well established standard for signing and encrypting messages. The Apache Crypto CMS component supports the following parts of this standard: * Content Type "Enveloped Data" with Key Transport (asymmetric key), * Content Type "Signed Data". You can create CMS Enveloped Data instances, decrypt CMS Enveloped Data instances, create CMS Signed Data instances, and validate CMS Signed Data instances.

The component uses the Bouncy Castle libraries bcprov-jdk15on and bcpkix-jdk15on.

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

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

We recommend to register the Bouncy Castle security provider in your application before you call an endpoint of this component:

Security.addProvider(new BouncyCastleProvider());

If the Bouncy Castle security provider is not registered then the Crypto CMS component will register the provider.

71.1. Options

The Crypto CMS component supports 3 options which are listed below.

Name	Description	Default	Type
signedDataVerifier Configuration (advanced)	To configure the shared SignedDataVerifierConfiguration, which determines the uri parameters for the verify operation.		SignedDataVerifier Configuration
envelopedDataDecryptor Configuration (advanced)	To configure the shared EnvelopedDataDecryptorConfiguration, which determines the uri parameters for the decrypt operation.		EnvelopedDataDecryptor Configuration
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Crypto CMS endpoint is configured using URI syntax:

crypto-cms:cryptoOperation:name

with the following path and query parameters:

71.1.1. Path Parameters (2 parameters):

Name	Description	Default	Type
cryptoOperation	Required Set the Crypto operation from that supplied after the crypto scheme in the endpoint uri e.g. crypto-cms:sign sets sign as the operation. Possible values: sign, verify, encrypt, or decrypt.		CryptoOperation
name	Required The name part in the URI can be chosen by the user to distinguish between different signer/verifier/encryptor/decryptor endpoints within the camel context.		String

71.1.2. Query Parameters (15 parameters):

Name	Description	Default	Type
keyStore (common)	Keystore which contains signer private keys, verifier public keys, encryptor public keys, decryptor private keys depending on the operation. Use either this parameter or the parameter 'keyStoreParameters'.		KeyStore
keyStoreParameters (common)	Keystore containing signer private keys, verifier public keys, encryptor public keys, decryptor private keys depending on the operation. Use either this parameter or the parameter 'keystore'.		KeyStoreParameters
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
password (decrypt)	Sets the password of the private keys. It is assumed that all private keys in the keystore have the same password. If not set then it is assumed that the password of the private keys is given by the keystore password given in the KeyStoreParameters.		Char[]
fromBase64 (decrypt_verify)	If true then the CMS message is base 64 encoded and must be decoded during the processing. Default value is false.	false	Boolean
contentEncryptionAlgorithm (encrypt)	Encryption algorithm, for example DESede/CBC/PKCS5Padding. Further possible values: DESede/CBC/PKCS5Padding, AES/CBC/PKCS5Padding, Camellia/CBC/PKCS5Padding, CAST5/CBC/PKCS5Padding.		String
originatorInformation Provider (encrypt)	Provider for the originator info. See https://tools.ietf.org/html/rfc5652section-6.1. The default value is null.		OriginatorInformation Provider
recipient (encrypt)	Recipient Info: reference to a bean which implements the interface org.apache.camel.component.crypto.cms.api.TransRecipientInfo		List
secretKeyLength (encrypt)	Key length for the secret symmetric key used for the content encryption. Only used if the specified content-encryption algorithm allows keys of different sizes. If contentEncryptionAlgorithm=AES/CBC/PKCS5Padding or Camellia/CBC/PKCS5Padding then 128; if contentEncryptionAlgorithm=DESede/CBC/PKCS5Padding then 192, 128; if strong encryption is enabled then for AES/CBC/PKCS5Padding and Camellia/CBC/PKCS5Padding also the key lengths 192 and 256 are possible.		int
unprotectedAttributes GeneratorProvider (encrypt)	Provider of the generator for the unprotected attributes. The default value is null which means no unprotected attribute is added to the Enveloped Data object. See https://tools.ietf.org/html/rfc5652section-6.1.		AttributesGenerator Provider
toBase64 (encrypt_sign)	Indicates whether the Signed Data or Enveloped Data instance shall be base 64 encoded. Default value is false.	false	Boolean
includeContent (sign)	Indicates whether the signed content should be included into the Signed Data instance. If false then a detached Signed Data instance is created in the header CamelCryptoCmsSignedData.	true	Boolean
signer (sign)	Signer information: reference to a bean which implements org.apache.camel.component.crypto.cms.api.SignerInfo		List
signedDataHeaderBase64 (verify)	Indicates whether the value in the header CamelCryptoCmsSignedData is base64 encoded. Default value is false. Only relevant for detached signatures. In the detached signature case, the header contains the Signed Data object.	false	Boolean
verifySignaturesOfAll Signers (verify)	If true then the signatures of all signers contained in the Signed Data object are verified. If false then only one signature whose signer info matches with one of the specified certificates is verified. Default value is true.	true	Boolean

71.2. Enveloped Data

Note, that a crypto-cms:encypt endpoint is typically defined in one route and the complimentary crypto-cms:decrypt in another, though for simplicity in the examples they appear one after the other.

The following example shows how you can create an Enveloped Data message and how you can decrypt an Enveloped Data message.

Basic Example in Java DSL

import org.apache.camel.util.jsse.KeyStoreParameters;
import org.apache.camel.component.crypto.cms.crypt.DefaultKeyTransRecipientInfo;
...
KeyStoreParameters keystore  = new KeyStoreParameters();
keystore.setType("JCEKS");
keystore.setResource("keystore/keystore.jceks);
keystore.setPassword("some_password"); // this password will also be used for accessing the private key if not specified in the crypto-cms:decrypt endpoint

DefaultKeyTransRecipientInfo recipient1 = new DefaultKeyTransRecipientInfo();
recipient1.setCertificateAlias("rsa"); // alias of the public key used for the encryption
recipient1.setKeyStoreParameters(keystore);

simpleReg.put("keyStoreParameters", keystore); // register keystore in the registry
simpleReg.put("recipient1", recipient1); // register recipient info in the registry

from("direct:start")
    .to("crypto-cms:encrypt://testencrpyt?toBase64=true&recipient=#recipient1&contentEncryptionAlgorithm=DESede/CBC/PKCS5Padding&secretKeyLength=128")
    .to("crypto-cms:decrypt://testdecrypt?fromBase64=true&keyStoreParameters=#keyStoreParameters")
    .to("mock:result");

Basic Example in Spring XML

   <keyStoreParameters xmlns="http://camel.apache.org/schema/spring"
        id="keyStoreParameters1" resource="./keystore/keystore.jceks"
        password="some_password" type="JCEKS" />
    <bean id="recipient1"
        class="org.apache.camel.component.crypto.cms.crypt.DefaultKeyTransRecipientInfo">
        <property name="keyStoreParameters" ref="keyStoreParameters1" />
        <property name="certificateAlias" value="rsa" />
    </bean>
...
    <route>
        <from uri="direct:start" />
        <to uri="crypto-cms:encrypt://testencrpyt?toBase64=true&amp;recipient=#recipient1&amp;contentEncryptionAlgorithm=DESede/CBC/PKCS5Padding&amp;secretKeyLength=128" />
        <to uri="crypto-cms:decrypt://testdecrypt?fromBase64=true&amp;keyStoreParameters=#keyStoreParameters1" />
         <to uri="mock:result" />
    </route>

Two Recipients in Java DSL

import org.apache.camel.util.jsse.KeyStoreParameters;
import org.apache.camel.component.crypto.cms.crypt.DefaultKeyTransRecipientInfo;
...
KeyStoreParameters keystore  = new KeyStoreParameters();
keystore.setType("JCEKS");
keystore.setResource("keystore/keystore.jceks);
keystore.setPassword("some_password"); // this password will also be used for accessing the private key if not specified in the crypto-cms:decrypt endpoint

DefaultKeyTransRecipientInfo recipient1 = new DefaultKeyTransRecipientInfo();
recipient1.setCertificateAlias("rsa"); // alias of the public key used for the encryption
recipient1.setKeyStoreParameters(keystore);

DefaultKeyTransRecipientInfo recipient2 = new DefaultKeyTransRecipientInfo();
recipient2.setCertificateAlias("dsa");
recipient2.setKeyStoreParameters(keystore);

simpleReg.put("keyStoreParameters", keystore); // register keystore in the registry
simpleReg.put("recipient1", recipient1); // register recipient info in the registry

from("direct:start")
    .to("crypto-cms:encrypt://testencrpyt?toBase64=true&recipient=#recipient1&recipient=#recipient2&contentEncryptionAlgorithm=DESede/CBC/PKCS5Padding&secretKeyLength=128")
    //the decryptor will automatically choose one of the two private keys depending which one is in the decryptor keystore
    .to("crypto-cms:decrypt://testdecrypt?fromBase64=true&keyStoreParameters=#keyStoreParameters")
    .to("mock:result");

Two Recipients in Spring XML

   <keyStoreParameters xmlns="http://camel.apache.org/schema/spring"
        id="keyStoreParameters1" resource="./keystore/keystore.jceks"
        password="some_password" type="JCEKS" />
    <bean id="recipient1"
        class="org.apache.camel.component.crypto.cms.crypt.DefaultKeyTransRecipientInfo">
        <property name="keyStoreParameters" ref="keyStoreParameters1" />
        <property name="certificateAlias" value="rsa" />
    </bean>
    <bean id="recipient2"
        class="org.apache.camel.component.crypto.cms.crypt.DefaultKeyTransRecipientInfo">
        <property name="keyStoreParameters" ref="keyStoreParameters1" />
        <property name="certificateAlias" value="dsa" />
    </bean>
...
    <route>
        <from uri="direct:start" />
        <to uri="crypto-cms:encrypt://testencrpyt?toBase64=true&amp;recipient=#recipient1&amp;recipient=#recipient2&amp;contentEncryptionAlgorithm=DESede/CBC/PKCS5Padding&amp;secretKeyLength=128" />
        <!-- the decryptor will automatically choose one of the two private keys depending which one is in the decryptor keystore -->
        <to uri="crypto-cms:decrypt://testdecrypt?fromBase64=true&amp;keyStoreParameters=#keyStoreParameters1" />
         <to uri="mock:result" />
    </route>

71.3. Signed Data

Note, that a crypto-cms:sign endpoint is typically defined in one route and the complimentary crypto-cms:verify in another, though for simplicity in the examples they appear one after the other.

The following example shows how you can create a Signed Data message and how you can validate a Signed Data message.

Basic Example in Java DSL

import org.apache.camel.util.jsse.KeyStoreParameters;
import org.apache.camel.component.crypto.cms.sig.DefaultSignerInfo;
...
KeyStoreParameters keystore  = new KeyStoreParameters();
keystore.setType("JCEKS");
keystore.setResource("keystore/keystore.jceks);
keystore.setPassword("some_password"); // this password will also be used for accessing the private key if not specified in the signerInfo1 bean

//Signer Information, by default the following signed attributes are included: contentType, signingTime, messageDigest, and cmsAlgorithmProtect; by default no unsigned attribute is included.
// If you want to add your own signed attributes or unsigned attributes, see methods DefaultSignerInfo.setSignedAttributeGenerator and DefaultSignerInfo.setUnsignedAttributeGenerator.
DefaultSignerInfo signerInfo1 = new DefaultSignerInfo();
signerInfo1.setIncludeCertificates(true); // if set to true then the certificate chain of the private key will be added to the Signed Data object
signerInfo1.setSignatureAlgorithm("SHA256withRSA"); // signature algorithm; attention, the signature algorithm must fit to the signer private key.
signerInfo1.setPrivateKeyAlias("rsa"); // alias of the private key used for the signing
signerInfo1.setPassword("private_key_pw".toCharArray()); // optional parameter, if not set then the password of the KeyStoreParameters will be used for accessing the private key
signerInfo1.setKeyStoreParameters(keystore);

simpleReg.put("keyStoreParameters", keystore); //register keystore in the registry
simpleReg.put("signer1", signerInfo1); //register signer info in the registry

from("direct:start")
    .to("crypto-cms:sign://testsign?signer=#signer1&includeContent=true&toBase64=true")
    .to("crypto-cms:verify://testverify?keyStoreParameters=#keyStoreParameters&fromBase64=true"")
    .to("mock:result");

Basic Example in Spring XML

   <keyStoreParameters xmlns="http://camel.apache.org/schema/spring"
        id="keyStoreParameters1" resource="./keystore/keystore.jceks"
        password="some_password" type="JCEKS" />
    <bean id="signer1"
        class="org.apache.camel.component.crypto.cms.sig.DefaultSignerInfo">
        <property name="keyStoreParameters" ref="keyStoreParameters1" />
        <property name="privateKeyAlias" value="rsa" />
        <property name="signatureAlgorithm" value="SHA256withRSA" />
        <property name="includeCertificates" value="true" />
        <!-- optional parameter 'password', if not set then the password of the KeyStoreParameters will be used for accessing the private key -->
        <property name="password" value="private_key_pw" />
    </bean>
...
    <route>
        <from uri="direct:start" />
        <to uri="crypto-cms:sign://testsign?signer=#signer1&amp;includeContent=true&amp;toBase64=true" />
        <to uri="crypto-cms:verify://testverify?keyStoreParameters=#keyStoreParameters1&amp;fromBase64=true" />
        <to uri="mock:result" />
    </route>

Example with two Signers in Java DSL

import org.apache.camel.util.jsse.KeyStoreParameters;
import org.apache.camel.component.crypto.cms.sig.DefaultSignerInfo;
...
KeyStoreParameters keystore  = new KeyStoreParameters();
keystore.setType("JCEKS");
keystore.setResource("keystore/keystore.jceks);
keystore.setPassword("some_password"); // this password will also be used for accessing the private key if not specified in the signerInfo1 bean

//Signer Information, by default the following signed attributes are included: contentType, signingTime, messageDigest, and cmsAlgorithmProtect; by default no unsigned attribute is included.
// If you want to add your own signed attributes or unsigned attributes, see methods DefaultSignerInfo.setSignedAttributeGenerator and DefaultSignerInfo.setUnsignedAttributeGenerator.
DefaultSignerInfo signerInfo1 = new DefaultSignerInfo();
signerInfo1.setIncludeCertificates(true); // if set to true then the certificate chain of the private key will be added to the Signed Data object
signerInfo1.setSignatureAlgorithm("SHA256withRSA"); // signature algorithm; attention, the signature algorithm must fit to the signer private key.
signerInfo1.setPrivateKeyAlias("rsa"); // alias of the private key used for the signing
signerInfo1.setPassword("private_key_pw".toCharArray()); // optional parameter, if not set then the password of the KeyStoreParameters will be used for accessing the private key
signerInfo1.setKeyStoreParameters(keystore);

DefaultSignerInfo signerInfo2 = new DefaultSignerInfo();
signerInfo2.setIncludeCertificates(true);
signerInfo2.setSignatureAlgorithm("SHA256withDSA");
signerInfo2.setPrivateKeyAlias("dsa");
signerInfo2.setKeyStoreParameters(keystore);


simpleReg.put("keyStoreParameters", keystore); //register keystore in the registry
simpleReg.put("signer1", signerInfo1); //register signer info in the registry
simpleReg.put("signer2", signerInfo2); //register signer info in the registry

from("direct:start")
    .to("crypto-cms:sign://testsign?signer=#signer1&signer=#signer2&includeContent=true")
    .to("crypto-cms:verify://testverify?keyStoreParameters=#keyStoreParameters")
    .to("mock:result");

Example with two Signers in Spring XML

   <keyStoreParameters xmlns="http://camel.apache.org/schema/spring"
        id="keyStoreParameters1" resource="./keystore/keystore.jceks"
        password="some_password" type="JCEKS" />
    <bean id="signer1"
        class="org.apache.camel.component.crypto.cms.sig.DefaultSignerInfo">
        <property name="keyStoreParameters" ref="keyStoreParameters1" />
        <property name="privateKeyAlias" value="rsa" />
        <property name="signatureAlgorithm" value="SHA256withRSA" />
        <property name="includeCertificates" value="true" />
        <!-- optional parameter 'password', if not set then the password of the KeyStoreParameters will be used for accessing the private key -->
        <property name="password" value="private_key_pw" />
    </bean>
    <bean id="signer2"
        class="org.apache.camel.component.crypto.cms.sig.DefaultSignerInfo">
        <property name="keyStoreParameters" ref="keyStoreParameters1" />
        <property name="privateKeyAlias" value="dsa" />
        <property name="signatureAlgorithm" value="SHA256withDSA" />
        <!-- optional parameter 'password', if not set then the password of the KeyStoreParameters will be used for accessing the private key -->
        <property name="password" value="private_key_pw2" />
    </bean>
...
    <route>
        <from uri="direct:start" />
        <to uri="crypto-cms:sign://testsign?signer=#signer1&amp;signer=#signer2&amp;includeContent=true" />
        <to uri="crypto-cms:verify://testverify?keyStoreParameters=#keyStoreParameters1" />
        <to uri="mock:result" />
    </route>

Detached Signature Example in Java DSL

import org.apache.camel.util.jsse.KeyStoreParameters;
import org.apache.camel.component.crypto.cms.sig.DefaultSignerInfo;
...
KeyStoreParameters keystore  = new KeyStoreParameters();
keystore.setType("JCEKS");
keystore.setResource("keystore/keystore.jceks);
keystore.setPassword("some_password"); // this password will also be used for accessing the private key if not specified in the signerInfo1 bean

//Signer Information, by default the following signed attributes are included: contentType, signingTime, messageDigest, and cmsAlgorithmProtect; by default no unsigned attribute is included.
// If you want to add your own signed attributes or unsigned attributes, see methods DefaultSignerInfo.setSignedAttributeGenerator and DefaultSignerInfo.setUnsignedAttributeGenerator.
DefaultSignerInfo signerInfo1 = new DefaultSignerInfo();
signerInfo1.setIncludeCertificates(true); // if set to true then the certificate chain of the private key will be added to the Signed Data object
signerInfo1.setSignatureAlgorithm("SHA256withRSA"); // signature algorithm; attention, the signature algorithm must fit to the signer private key.
signerInfo1.setPrivateKeyAlias("rsa"); // alias of the private key used for the signing
signerInfo1.setPassword("private_key_pw".toCharArray()); // optional parameter, if not set then the password of the KeyStoreParameters will be used for accessing the private key
signerInfo1.setKeyStoreParameters(keystore);

simpleReg.put("keyStoreParameters", keystore); //register keystore in the registry
simpleReg.put("signer1", signerInfo1); //register signer info in the registry

from("direct:start")
     //with the option includeContent=false the SignedData object without the signed text will be written into the header "CamelCryptoCmsSignedData"
    .to("crypto-cms:sign://testsign?signer=#signer1&includeContent=false&toBase64=true")
    //the verifier reads the Signed Data object form the header CamelCryptoCmsSignedData and assumes that the signed content is in the message body
    .to("crypto-cms:verify://testverify?keyStoreParameters=#keyStoreParameters&signedDataHeaderBase64=true")
    .to("mock:result");

Detached Signature Example in Spring XML

   <keyStoreParameters xmlns="http://camel.apache.org/schema/spring"
        id="keyStoreParameters1" resource="./keystore/keystore.jceks"
        password="some_password" type="JCEKS" />
    <bean id="signer1"
        class="org.apache.camel.component.crypto.cms.sig.DefaultSignerInfo">
        <property name="keyStoreParameters" ref="keyStoreParameters1" />
        <property name="privateKeyAlias" value="rsa" />
        <property name="signatureAlgorithm" value="SHA256withRSA" />
        <property name="includeCertificates" value="true" />
        <!-- optional parameter 'password', if not set then the password of the KeyStoreParameters will be used for accessing the private key -->
        <property name="password" value="private_key_pw" />
    </bean>
...
    <route>
        <from uri="direct:start" />
        <!-- with the option includeContent=false the SignedData object without the signed text will be written into the header "CamelCryptoCmsSignedData" -->
        <to uri="crypto-cms:sign://testsign?signer=#signer1&amp;includeContent=false&amp;toBase64=true" />
        <!-- the verifier reads the Signed Data object form the header CamelCryptoCmsSignedData and assumes that the signed content is in the message body -->
        <to uri="crypto-cms:verify://testverify?keyStoreParameters=#keyStoreParameters1&amp;signedDataHeaderBase64=true" />
        <to uri="mock:result" />
    </route>

Chapter 72. Crypto (Java Cryptographic Extension) DataFormat

Available as of Camel version 2.3

The Crypto Data Format integrates the Java Cryptographic Extension into Camel, allowing simple and flexible encryption and decryption of messages using Camel’s familiar marshall and unmarshal formatting mechanism. It assumes marshalling to mean encryption to cyphertext and unmarshalling to mean decryption back to the original plaintext. This data format implements only symmetric (shared-key) encryption and decyption.

72.1. CryptoDataFormat Options

The Crypto (Java Cryptographic Extension) dataformat supports 10 options which are listed below.

Name	Default	Java Type	Description
algorithm	`DES/CBC/PKCS5Padding`	`String`	The JCE algorithm name indicating the cryptographic algorithm that will be used. Is by default DES/CBC/PKCS5Padding.
cryptoProvider		`String`	The name of the JCE Security Provider that should be used.
keyRef		`String`	Refers to the secret key to lookup from the register to use.
initVectorRef		`String`	Refers to a byte array containing the Initialization Vector that will be used to initialize the Cipher.
algorithmParameterRef		`String`	A JCE AlgorithmParameterSpec used to initialize the Cipher. Will lookup the type using the given name as a java.security.spec.AlgorithmParameterSpec type.
buffersize		`Integer`	The size of the buffer used in the signature process.
macAlgorithm	`HmacSHA1`	`String`	The JCE algorithm name indicating the Message Authentication algorithm.
shouldAppendHMAC	`false`	`Boolean`	Flag indicating that a Message Authentication Code should be calculated and appended to the encrypted data.
inline	`false`	`Boolean`	Flag indicating that the configured IV should be inlined into the encrypted data stream. Is by default false.
contentTypeHeader	`false`	`Boolean`	Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.

72.2. Basic Usage

At its most basic all that is required to encrypt/decrypt an exchange is a shared secret key. If one or more instances of the Crypto data format are configured with this key the format can be used to encrypt the payload in one route (or part of one) and decrypted in another. For example, using the Java DSL as follows:

KeyGenerator generator = KeyGenerator.getInstance("DES");

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES", generator.generateKey());

from("direct:basic-encryption")
    .marshal(cryptoFormat)
    .to("mock:encrypted")
    .unmarshal(cryptoFormat)
    .to("mock:unencrypted");

In Spring the dataformat is configured first and then used in routes

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
  <dataFormats>
    <crypto id="basic" algorithm="DES" keyRef="desKey" />
  </dataFormats>
    ...
  <route>
    <from uri="direct:basic-encryption" />
    <marshal ref="basic" />
    <to uri="mock:encrypted" />
    <unmarshal ref="basic" />
    <to uri="mock:unencrypted" />
  </route>
</camelContext>

72.3. Specifying the Encryption Algorithm

Changing the algorithm is a matter of supplying the JCE algorithm name. If you change the algorithm you will need to use a compatible key.

KeyGenerator generator = KeyGenerator.getInstance("DES");

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES", generator.generateKey());
cryptoFormat.setShouldAppendHMAC(true);
cryptoFormat.setMacAlgorithm("HmacMD5");

from("direct:hmac-algorithm")
    .marshal(cryptoFormat)
    .to("mock:encrypted")
    .unmarshal(cryptoFormat)
    .to("mock:unencrypted");

A list of the available algorithms in Java 7 is available via the Java Cryptography Architecture Standard Algorithm Name Documentation.

72.4. Specifying an Initialization Vector

Some crypto algorithms, particularly block algorithms, require configuration with an initial block of data known as an Initialization Vector. In the JCE this is passed as an AlgorithmParameterSpec when the Cipher is initialized. To use such a vector with the CryptoDataFormat you can configure it with a byte[] containing the required data e.g.

KeyGenerator generator = KeyGenerator.getInstance("DES");
byte[] initializationVector = new byte[] {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07};

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES/CBC/PKCS5Padding", generator.generateKey());
cryptoFormat.setInitializationVector(initializationVector);

from("direct:init-vector")
    .marshal(cryptoFormat)
    .to("mock:encrypted")
    .unmarshal(cryptoFormat)
    .to("mock:unencrypted");

or with spring, suppling a reference to a byte[]

<crypto id="initvector" algorithm="DES/CBC/PKCS5Padding" keyRef="desKey" initVectorRef="initializationVector" />

The same vector is required in both the encryption and decryption phases. As it is not necessary to keep the IV a secret, the DataFormat allows for it to be inlined into the encrypted data and subsequently read out in the decryption phase to initialize the Cipher. To inline the IV set the /oinline flag.

KeyGenerator generator = KeyGenerator.getInstance("DES");
byte[] initializationVector = new byte[] {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07};
SecretKey key = generator.generateKey();

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES/CBC/PKCS5Padding", key);
cryptoFormat.setInitializationVector(initializationVector);
cryptoFormat.setShouldInlineInitializationVector(true);
CryptoDataFormat decryptFormat = new CryptoDataFormat("DES/CBC/PKCS5Padding", key);
decryptFormat.setShouldInlineInitializationVector(true);

from("direct:inline")
    .marshal(cryptoFormat)
    .to("mock:encrypted")
    .unmarshal(decryptFormat)
    .to("mock:unencrypted");

or with spring.

<crypto id="inline" algorithm="DES/CBC/PKCS5Padding" keyRef="desKey" initVectorRef="initializationVector"
  inline="true" />
<crypto id="inline-decrypt" algorithm="DES/CBC/PKCS5Padding" keyRef="desKey" inline="true" />

For more information of the use of Initialization Vectors, consult

72.5. Hashed Message Authentication Codes (HMAC)

To avoid attacks against the encrypted data while it is in transit the CryptoDataFormat can also calculate a Message Authentication Code for the encrypted exchange contents based on a configurable MAC algorithm. The calculated HMAC is appended to the stream after encryption. It is separated from the stream in the decryption phase. The MAC is recalculated and verified against the transmitted version to insure nothing was tampered with in transit.For more information on Message Authentication Codes see http://en.wikipedia.org/wiki/HMAC

KeyGenerator generator = KeyGenerator.getInstance("DES");

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES", generator.generateKey());
cryptoFormat.setShouldAppendHMAC(true);

from("direct:hmac")
    .marshal(cryptoFormat)
    .to("mock:encrypted")
    .unmarshal(cryptoFormat)
    .to("mock:unencrypted");

or with spring.

<crypto id="hmac" algorithm="DES" keyRef="desKey" shouldAppendHMAC="true" />

By default the HMAC is calculated using the HmacSHA1 mac algorithm though this can be easily changed by supplying a different algorithm name. See here for how to check what algorithms are available through the configured security providers

KeyGenerator generator = KeyGenerator.getInstance("DES");

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES", generator.generateKey());
cryptoFormat.setShouldAppendHMAC(true);
cryptoFormat.setMacAlgorithm("HmacMD5");

from("direct:hmac-algorithm")
    .marshal(cryptoFormat)
    .to("mock:encrypted")
    .unmarshal(cryptoFormat)
    .to("mock:unencrypted");

or with spring.

<crypto id="hmac-algorithm" algorithm="DES" keyRef="desKey" macAlgorithm="HmacMD5" shouldAppendHMAC="true" />

72.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 neither be feasible or desirable. It would be useful to be able to specify keys dynamically on a per exchange basis. The exchange could then be dynamically enriched with the key of its target recipient before being processed by the data format. To facilitate this the DataFormat allow for keys to be supplied dynamically via the message headers below

CryptoDataFormat.KEY "CamelCryptoKey"

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES", null);
/**
 * Note: the header containing the key should be cleared after
 * marshalling to stop it from leaking by accident and
 * potentially being compromised. The processor version below is
 * arguably better as the key is left in the header when you use
 * the DSL leaks the fact that camel encryption was used.
 */
from("direct:key-in-header-encrypt")
    .marshal(cryptoFormat)
    .removeHeader(CryptoDataFormat.KEY)
    .to("mock:encrypted");

from("direct:key-in-header-decrypt").unmarshal(cryptoFormat).process(new Processor() {
    public void process(Exchange exchange) throws Exception {
        exchange.getIn().getHeaders().remove(CryptoDataFormat.KEY);
        exchange.getOut().copyFrom(exchange.getIn());
    }
}).to("mock:unencrypted");

or with spring.

<crypto id="nokey" algorithm="DES" />

72.7. Dependencies

To use the Crypto dataformat in your camel routes you need to add the following dependency to your pom.

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

72.8. See Also

Data Format
Crypto (Digital Signatures)
http://www.bouncycastle.org/java.html

Chapter 73. CSV DataFormat

Available as of Camel version 1.3

The CSV Data Format uses Apache Commons CSV to handle CSV payloads (Comma Separated Values) such as those exported/imported by Excel.

73.1. Options

The CSV dataformat supports 28 options which are listed below.

Name	Default	Java Type	Description
formatRef		`String`	The reference format to use, it will be updated with the other format options, the default value is CSVFormat.DEFAULT
formatName		`String`	The name of the format to use, the default value is CSVFormat.DEFAULT
commentMarkerDisabled	`false`	`Boolean`	Disables the comment marker of the reference format.
commentMarker		`String`	Sets the comment marker of the reference format.
delimiter		`String`	Sets the delimiter to use. The default value is , (comma)
escapeDisabled	`false`	`Boolean`	Use for disabling using escape character
escape		`String`	Sets the escape character to use
headerDisabled	`false`	`Boolean`	Use for disabling headers
header		`List`	To configure the CSV headers
allowMissingColumnNames	`false`	`Boolean`	Whether to allow missing column names.
ignoreEmptyLines	`false`	`Boolean`	Whether to ignore empty lines.
ignoreSurroundingSpaces	`false`	`Boolean`	Whether to ignore surrounding spaces
nullStringDisabled	`false`	`Boolean`	Used to disable null strings
nullString		`String`	Sets the null string
quoteDisabled	`false`	`Boolean`	Used to disable quotes
quote		`String`	Sets the quote which by default is
recordSeparatorDisabled		`String`	Used for disabling record separator
recordSeparator		`String`	Sets the record separator (aka new line) which by default is new line characters (CRLF)
skipHeaderRecord	`false`	`Boolean`	Whether to skip the header record in the output
quoteMode		`String`	Sets the quote mode
ignoreHeaderCase	`false`	`Boolean`	Sets whether or not to ignore case when accessing header names.
trim	`false`	`Boolean`	Sets whether or not to trim leading and trailing blanks.
trailingDelimiter	`false`	`Boolean`	Sets whether or not to add a trailing delimiter.
lazyLoad	`false`	`Boolean`	Whether the unmarshalling should produce an iterator that reads the lines on the fly or if all the lines must be read at one.
useMaps	`false`	`Boolean`	Whether the unmarshalling should produce maps (HashMap)for the lines values instead of lists. It requires to have header (either defined or collected).
useOrderedMaps	`false`	`Boolean`	Whether the unmarshalling should produce ordered maps (LinkedHashMap) for the lines values instead of lists. It requires to have header (either defined or collected).
recordConverterRef		`String`	Refers to a custom CsvRecordConverter to lookup from the registry to use.
contentTypeHeader	`false`	`Boolean`	Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.

73.2. Marshalling a Map to CSV

The component allows you to marshal a Java Map (or any other message type that can be converted in a Map) into a CSV payload.

Considering the following body

Map<String, Object> body = new LinkedHashMap<>();
body.put("foo", "abc");
body.put("bar", 123);

and this Java route definition

from("direct:start")
    .marshal().csv()
    .to("mock:result");

or this XML route definition

<route>
    <from uri="direct:start" />
    <marshal>
        <csv />
    </marshal>
    <to uri="mock:result" />
</route>

then it will produce

abc,123

73.3. Unmarshalling a CSV message into a Java List

Unmarshalling will transform a CSV messsage into a Java List with CSV file lines (containing another List with all the field values).

An example: we have a CSV file with names of persons, their IQ and their current activity.

Jack Dalton, 115, mad at Averell
Joe Dalton, 105, calming Joe
William Dalton, 105, keeping Joe from killing Averell
Averell Dalton, 80, playing with Rantanplan
Lucky Luke, 120, capturing the Daltons

We can now use the CSV component to unmarshal this file:

from("file:src/test/resources/?fileName=daltons.csv&noop=true")
    .unmarshal().csv()
    .to("mock:daltons");

The resulting message will contain a List<List<String>> like…

List<List<String>> data = (List<List<String>>) exchange.getIn().getBody();
for (List<String> line : data) {
    LOG.debug(String.format("%s has an IQ of %s and is currently %s", line.get(0), line.get(1), line.get(2)));
}

73.4. Marshalling a List<Map> to CSV

Available as of Camel 2.1

If you have multiple rows of data you want to be marshalled into CSV format you can now store the message payload as a List<Map<String, Object>> object where the list contains a Map for each row.

73.5. File Poller of CSV, then unmarshaling

Given a bean which can handle the incoming data…

MyCsvHandler.java

// Some comments here
public void doHandleCsvData(List<List<String>> csvData)
{
    // do magic here
}

your route then looks as follows

<route>
        <!-- poll every 10 seconds -->
        <from uri="file:///some/path/to/pickup/csvfiles?delete=true&amp;consumer.delay=10000" />
        <unmarshal><csv /></unmarshal>
        <to uri="bean:myCsvHandler?method=doHandleCsvData" />
</route>

73.6. Marshaling with a pipe as delimiter

Considering the following body

Map<String, Object> body = new LinkedHashMap<>();
body.put("foo", "abc");
body.put("bar", 123);

and this Java route definition

// Camel version < 2.15
CsvDataFormat oldCSV = new CsvDataFormat();
oldCSV.setDelimiter("|");
from("direct:start")
    .marshal(oldCSV)
    .to("mock:result")

// Camel version >= 2.15
from("direct:start")
    .marshal(new CsvDataFormat().setDelimiter(&#39;|&#39;))
    .to("mock:result")

or this XML route definition

<route>
  <from uri="direct:start" />
  <marshal>
    <csv delimiter="|" />
  </marshal>
  <to uri="mock:result" />
</route>

then it will produce

abc|123

Using autogenColumns, configRef and strategyRef attributes inside XML # DSL

Available as of Camel 2.9.2 / 2.10 and deleted for Camel 2.15

You can customize the CSV Data Format to make use of your own CSVConfig and/or CSVStrategy. Also note that the default value of the autogenColumns option is true. The following example should illustrate this customization.

<route>
  <from uri="direct:start" />
  <marshal>
    <!-- make use of a strategy other than the default one which is 'org.apache.commons.csv.CSVStrategy.DEFAULT_STRATEGY' -->
    <csv autogenColumns="false" delimiter="|" configRef="csvConfig" strategyRef="excelStrategy" />
  </marshal>
  <convertBodyTo type="java.lang.String" />
  <to uri="mock:result" />
</route>

<bean id="csvConfig" class="org.apache.commons.csv.writer.CSVConfig">
  <property name="fields">
    <list>
      <bean class="org.apache.commons.csv.writer.CSVField">
        <property name="name" value="orderId" />
      </bean>
      <bean class="org.apache.commons.csv.writer.CSVField">
        <property name="name" value="amount" />
      </bean>
    </list>
  </property>
</bean>

<bean id="excelStrategy" class="org.springframework.beans.factory.config.FieldRetrievingFactoryBean">
  <property name="staticField" value="org.apache.commons.csv.CSVStrategy.EXCEL_STRATEGY" />
</bean>

73.7. Using skipFirstLine option while unmarshaling

Available as of Camel 2.10 and deleted for Camel 2.15

You can instruct the CSV Data Format to skip the first line which contains the CSV headers. Using the Spring/XML DSL:

<route>
  <from uri="direct:start" />
  <unmarshal>
    <csv skipFirstLine="true" />
  </unmarshal>
  <to uri="bean:myCsvHandler?method=doHandleCsv" />
</route>

Or the Java DSL:

CsvDataFormat csv = new CsvDataFormat();
csv.setSkipFirstLine(true);

from("direct:start")
  .unmarshal(csv)
.to("bean:myCsvHandler?method=doHandleCsv");

73.8. Unmarshaling with a pipe as delimiter

Using the Spring/XML DSL:

<route>
  <from uri="direct:start" />
  <unmarshal>
    <csv delimiter="|" />
  </unmarshal>
  <to uri="bean:myCsvHandler?method=doHandleCsv" />
</route>

Or the Java DSL:

CsvDataFormat csv = new CsvDataFormat();
CSVStrategy strategy = CSVStrategy.DEFAULT_STRATEGY;
strategy.setDelimiter('|');
csv.setStrategy(strategy);

from("direct:start")
  .unmarshal(csv)
  .to("bean:myCsvHandler?method=doHandleCsv");

CsvDataFormat csv = new CsvDataFormat();
csv.setDelimiter("|");

from("direct:start")
  .unmarshal(csv)
  .to("bean:myCsvHandler?method=doHandleCsv");

CsvDataFormat csv = new CsvDataFormat();
CSVConfig csvConfig = new CSVConfig();
csvConfig.setDelimiter(";");
csv.setConfig(csvConfig);

from("direct:start")
  .unmarshal(csv)
  .to("bean:myCsvHandler?method=doHandleCsv");

Issue in CSVConfig

It looks like that

CSVConfig csvConfig = new CSVConfig();
csvConfig.setDelimiter(';');

doesn’t work. You have to set the delimiter as a String!

73.9. Dependencies

To use CSV in your Camel routes you need to add a dependency on camel-csv, which implements this data format.

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

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

Chapter 74. CXF

CXF Component

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

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

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

Note

If you want to learn about CXF dependencies, see the WHICH-JARS text file.

Note

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

Camel on EAP deployment

This component is supported by the Camel on EAP (Wildfly Camel) framework, which offers a simplified deployment model on the Red Hat JBoss Enterprise Application Platform (JBoss EAP) container.

The CXF component integrates with the JBoss EAP webservices susbsystem that also uses Apache CXF. For more information, see JAX-WS.

Note

At present, the Camel on EAP subsystem does not support CXF or Restlet consumers. However, it is possible to mimic CXF consumer behaviour, using the CamelProxy.

URI format

cxf:bean:cxfEndpoint[?options]

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.

cxf://someAddress[?options]

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:

cxf:bean:cxfEndpoint?wsdlURL=wsdl/hello_world.wsdl&dataFormat=PAYLOAD

Options

Name	Required	Description
`wsdlURL`	No	The location of the WSDL. WSDL is obtained from endpoint address by default. For 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. Since 2.0, 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. Since 2.0, it is possible to use `\#` notation to reference a `serviceClass` object instance from the registry.. 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. 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. For example: `org.apache.camel.Hello`
`serviceName`	Only if more than one `serviceName` present in WSDL	The service name this service is implementing, it maps to the `wsdl:service@name`. For example: `{http://org.apache.camel}ServiceName`
`endpointName`	Only if more than one `portName` under the `serviceName` is present, and it is required for camel-cxf consumer since camel 2.2	The port name this service is implementing, it maps to the `wsdl:port@name`. For example: `{http://org.apache.camel}PortName`
`dataFormat`	No	Which message data format the CXF endpoint supports. Possible values are: `POJO` (default), `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 the CXF endpoint producer will invoke. Possible values are: `true`, `false` (default).
`wrappedStyle`	No	Since 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
`setDefaultBus`	No	Deprecated: Specifies whether or not to use the default CXF bus for this endpoint. Possible values are: `true`, `false` (default). This option is deprecated and you should use `defaultBus` from Camel 2.16 onwards.
`defaultBus`	No	Deprecated: Specifies whether or not to use the default CXF bus for this endpoint. Possible values are: `true`, `false` (default). This option is deprecated and you should use `defaultBus` from Camel 2.16 onwards.
`bus`	No	Use `\#` notation to reference a bus object from the registry — for example, `bus=\#busName`. The referenced object must be an instance of `org.apache.cxf.Bus`. By default, uses the default bus created by CXF Bus Factory.
`cxfBinding`	No	Use `\#` notation to reference a CXF binding object from the registry — for example, `cxfBinding=\#bindingName`. The referenced object must be an instance of `org.apache.camel.component.cxf.CxfBinding`.
`headerFilterStrategy`	No	Use `\#` notation to reference a header filter strategy object from the registry — for example, `headerFilterStrategy=\#strategyName`. The referenced object must be an instance of `org.apache.camel.spi.HeaderFilterStrategy`.
`loggingFeatureEnabled`	No	New in 2.3, this option enables CXF Logging Feature which writes inbound and outbound SOAP messages to log. Possible values are: `true`, `false` (default).
`defaultOperationName`	No	New in 2.4, this option will set the default `operationName` that will be used by the `CxfProducer` that invokes the remote service. For 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. For 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.
`publishedEndpointUrl`	No	New in 2.5, this option overrides the endpoint URL that appears in the published WSDL that is accessed using the service address URL plus `?wsdl`. For example: `publshedEndpointUrl=http://example.com/service`
`properties.propName`	No	Camel 2.8: Allows you to set custom CXF properties in the endpoint URI. For example, setting `properties.mtom-enabled=true` to enable MTOM. To make sure that CXF does not switch the thread when starting the invocation, you can set `properties.org.apache.cxf.interceptor.OneWayProcessorInterceptor.USE_ORIGINAL_THREAD=true`.
`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.
`cxfEndpointConfigurer`	No	New in Camel 2.11. This option could apply the implementation of `org.apache.camel.component.cxf.CxfEndpointConfigurer which` supports to configure the CXF endpoint in programmatic way. Since Camel 2.15.0, user can configure the CXF server and client by implementing configure{Server
Client} method of `CxfEndpointConfigurer`.	`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

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.

Configuring the CXF Endpoints with Apache Aries Blueprint.

Since Camel 2.8, there is support for using Aries blueprint dependency injection for your CXF endpoints. The schema is very similar to the Spring schema, so the transition is fairly transparent.

For example:

 <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0"
            xmlns:camel-cxf="http://camel.apache.org/schema/blueprint/cxf"
 	   xmlns:cxfcore="http://cxf.apache.org/blueprint/core"
            xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 https://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd">

       <camel-cxf:cxfEndpoint id="routerEndpoint"
                      address="http://localhost:9001/router"
                      serviceClass="org.apache.servicemix.examples.cxf.HelloWorld">
         <camel-cxf:properties>
             <entry key="dataFormat" value="MESSAGE"/>
         </camel-cxf:properties>
      </camel-cxf:cxfEndpoint>

      <camel-cxf:cxfEndpoint id="serviceEndpoint"
			address="http://localhost:9000/SoapContext/SoapPort"
                     serviceClass="org.apache.servicemix.examples.cxf.HelloWorld">
    </camel-cxf:cxfEndpoint>

    <camelContext xmlns="http://camel.apache.org/schema/blueprint">
        <route>
            <from uri="routerEndpoint"/>
            <to uri="log:request"/>
        </route>
    </camelContext>

</blueprint>

Currently the endpoint element is the first supported CXF namespacehandler.

You can also use the bean references just as in spring

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0"
           xmlns:jaxws="http://cxf.apache.org/blueprint/jaxws"
           xmlns:cxf="http://cxf.apache.org/blueprint/core"
           xmlns:camel="http://camel.apache.org/schema/blueprint"
           xmlns:camelcxf="http://camel.apache.org/schema/blueprint/cxf"
           xsi:schemaLocation="
             http://www.osgi.org/xmlns/blueprint/v1.0.0 https://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
             http://cxf.apache.org/blueprint/jaxws http://cxf.apache.org/schemas/blueprint/jaxws.xsd
             http://cxf.apache.org/blueprint/core http://cxf.apache.org/schemas/blueprint/core.xsd
             ">

    <camelcxf:cxfEndpoint id="reportIncident"
                     address="/camel-example-cxf-blueprint/webservices/incident"
                     wsdlURL="META-INF/wsdl/report_incident.wsdl"
                     serviceClass="org.apache.camel.example.reportincident.ReportIncidentEndpoint">
    </camelcxf:cxfEndpoint>

    <bean id="reportIncidentRoutes" class="org.apache.camel.example.reportincident.ReportIncidentRoutes" />

    <camelContext xmlns="http://camel.apache.org/schema/blueprint">
        <routeBuilder ref="reportIncidentRoutes"/>
    </camelContext>

</blueprint>

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.

   <bean id="loggingOutInterceptor" class="org.apache.cxf.interceptor.LoggingOutInterceptor">
        <!--  it really should have been user-prestream but CXF does have such phase! -->
        <constructor-arg value="target/write"/>
   </bean>

<cxf:cxfEndpoint id="serviceEndpoint" address="http://localhost:9002/helloworld"
	serviceClass="org.apache.camel.component.cxf.HelloService">
	<cxf:outInterceptors>
	    <ref bean="loggingOutInterceptor"/>
	</cxf:outInterceptors>
	<cxf:properties>
		<entry key="dataFormat" value="MESSAGE"/>
	</cxf:properties>
</cxf:cxfEndpoint>

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

<cxf:cxfEndpoint ...>
   <cxf:properties>
     <entry key="org.apache.camel.cxf.message.headers.relays">
       <list>
         <ref bean="customHeadersRelay"/>
       </list>
     </entry>
   </cxf:properties>
 </cxf:cxfEndpoint>
 <bean id="customHeadersRelay" class="org.apache.camel.component.cxf.soap.headers.CustomHeadersRelay"/>

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

link: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[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 the 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.

<bean id="dropAllMessageHeadersStrategy" class="org.apache.camel.component.cxf.common.header.CxfHeaderFilterStrategy">

    <!--  Set relayHeaders to false to drop all SOAP headers -->
    <property name="relayHeaders" value="false"/>

</bean>

Then, your endpoint can reference the CxfHeaderFilterStrategy.

<route>
    <from uri="cxf:bean:routerNoRelayEndpoint?headerFilterStrategy=#dropAllMessageHeadersStrategy"/>
    <to uri="cxf:bean:serviceNoRelayEndpoint?headerFilterStrategy=#dropAllMessageHeadersStrategy"/>
</route>

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:

<bean id="customMessageFilterStrategy" class="org.apache.camel.component.cxf.common.header.CxfHeaderFilterStrategy">
    <property name="messageHeaderFilters">
        <list>
            <!--  SoapMessageHeaderFilter is the built in filter.  It can be removed by omitting it. -->
            <bean class="org.apache.camel.component.cxf.common.header.SoapMessageHeaderFilter"/>

            <!--  Add custom filter here -->
            <bean class="org.apache.camel.component.cxf.soap.headers.CustomHeaderFilter"/>
        </list>
    </property>
</bean>

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

Name	Description	type	Required?	Default value
`relayHeaders`	All message headers will be processed by Message Header Filters	`boolean`	No	`true` (1.6.1 behavior)
`relayAllMessageHeaders`	All message headers will be propagated (without processing by Message Header Filters)	`boolean`	No	`false` (1.6.1 behavior)
`allowFilterNamespaceClash`	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	`boolean`	No	`false` (1.6.1 behavior)

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.

NOTE In Camel 2.x we change to use http://camel.apache.org/schema/cxf as the CXF endpoint’s target namespace.

<beans xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:cxf="http://camel.apache.org/schema/cxf"
        xsi:schemaLocation="
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
        http://camel.apache.org/schema/cxf http://camel.apache.org/schema/cxf/camel-cxf.xsd
        http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd     ">
 ...

Note

In Apache Camel 2.x, the http://activemq.apache.org/camel/schema/cxfEndpoint namespace was changed to http://camel.apache.org/schema/cxf.

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 which show how to provide interceptors, properties and handlers here: http://cwiki.apache.org/CXF20DOC/jax-ws-configuration.html

Note

You can use CXF:properties to set the CXF endpoint’s dataFormat and setDefaultBus properties from a Spring configuration file, as follows:

<cxf:cxfEndpoint id="testEndpoint" address="http://localhost:9000/router"
     serviceClass="org.apache.camel.component.cxf.HelloService"
     endpointName="s:PortName"
     serviceName="s:ServiceName"
     xmlns:s="http://www.example.com/test">
     <cxf:properties>
       <entry key="dataFormat" value="MESSAGE"/>
       <entry key="setDefaultBus" value="true"/>
     </cxf:properties>
   </cxf:cxfEndpoint>

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

Error:sendSms: SoapFault exception: [Client] looks like we got no XML document in [...]

To resolved this issue, you just need to tell StaxOutInterceptor to write the XML start document for you.

public class WriteXmlDeclarationInterceptor extends AbstractPhaseInterceptor<SoapMessage> {
    public WriteXmlDeclarationInterceptor() {
        super(Phase.PRE_STREAM);
        addBefore(StaxOutInterceptor.class.getName());
    }

    public void handleMessage(SoapMessage message) throws Fault {
        message.put("org.apache.cxf.stax.force-start-document", Boolean.TRUE);
    }

}

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

<cxf:cxfEndpoint id="routerEndpoint" address="http://localhost:${CXFTestSupport.port2}/CXFGreeterRouterTest/CamelContext/RouterPort"
 		serviceClass="org.apache.hello_world_soap_http.GreeterImpl"
 		skipFaultLogging="true">
     <cxf:outInterceptors>
         <!-- This interceptor will force the CXF server send the XML start document to client -->
         <bean class="org.apache.camel.component.cxf.WriteXmlDeclarationInterceptor"/>
     </cxf:outInterceptors>
     <cxf:properties>
         <!-- Set the publishedEndpointUrl which could override the service address from generated WSDL as you want -->
         <entry key="publishedEndpointUrl" value="http://www.simple.com/services/test" />
     </cxf:properties>
 </cxf:cxfEndpoint>

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

 // set up the response context which force start document
 Map<String, Object> map = new HashMap<String, Object>();
 map.put("org.apache.cxf.stax.force-start-document", Boolean.TRUE);
 exchange.getOut().setHeader(Client.RESPONSE_CONTEXT, map);

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.

public class PersonProcessor implements Processor {

    private static final transient Logger LOG = LoggerFactory.getLogger(PersonProcessor.class);

    @SuppressWarnings("unchecked")
    public void process(Exchange exchange) throws Exception {
        LOG.info("processing exchange in camel");

        BindingOperationInfo boi = (BindingOperationInfo)exchange.getProperty(BindingOperationInfo.class.toString());
        if (boi != null) {
            LOG.info("boi.isUnwrapped" + boi.isUnwrapped());
        }
        // Get the parameters list which element is the holder.
        MessageContentsList msgList = (MessageContentsList)exchange.getIn().getBody();
        Holder<String> personId = (Holder<String>)msgList.get(0);
        Holder<String> ssn = (Holder<String>)msgList.get(1);
        Holder<String> name = (Holder<String>)msgList.get(2);

        if (personId.value == null || personId.value.length() == 0) {
            LOG.info("person id 123, so throwing exception");
            // Try to throw out the soap fault message
            org.apache.camel.wsdl_first.types.UnknownPersonFault personFault =
                new org.apache.camel.wsdl_first.types.UnknownPersonFault();
            personFault.setPersonId("");
            org.apache.camel.wsdl_first.UnknownPersonFault fault =
                new org.apache.camel.wsdl_first.UnknownPersonFault("Get the null value of person name", personFault);
            // Since camel has its own exception handler framework, we can't throw the exception to trigger it
            // We just set the fault message in the exchange for camel-cxf component handling and return
            exchange.getOut().setFault(true);
            exchange.getOut().setBody(fault);
            return;
        }

        name.value = "Bonjour";
        ssn.value = "123";
        LOG.info("setting Bonjour as the response");
        // Set the response message, first element is the return value of the operation,
        // the others are the holders of method parameters
        exchange.getOut().setBody(new Object[] {null, personId, ssn, name});
    }

}

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

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

If you don’t specify the operation name in the message header, CxfProducer will try to use the defaultOperationName from CxfEndpoint. If there is no defaultOperationName set on CxfEndpoint, it will pick up the first operation name from the operation list.

If you want to get the object array from the message body, you can get the body using message.getbody(Object[].class), as follows:

Exchange senderExchange = new DefaultExchange(context, ExchangePattern.InOut);
final List<String> params = new ArrayList<String>();
// Prepare the request message for the camel-cxf procedure
params.add(TEST_MESSAGE);
senderExchange.getIn().setBody(params);
senderExchange.getIn().setHeader(CxfConstants.OPERATION_NAME, ECHO_OPERATION);

Exchange exchange = template.send("direct:EndpointA", senderExchange);

org.apache.camel.Message out = exchange.getOut();
// The response message's body is an MessageContentsList which first element is the return value of the operation,
// If there are some holder parameters, the holder parameter will be filled in the reset of List.
// The result will be extract from the MessageContentsList with the String class type
MessageContentsList result = (MessageContentsList)out.getBody();
LOG.info("Received output text: " + result.get(0));
Map<String, Object> responseContext = CastUtils.cast((Map<?, ?>)out.getHeader(Client.RESPONSE_CONTEXT));
assertNotNull(responseContext);
assertEquals("We should get the response context here", "UTF-8", responseContext.get(org.apache.cxf.message.Message.ENCODING));
assertEquals("Reply body on Camel is wrong", "echo " + TEST_MESSAGE, result.get(0));

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

In Apache Camel 2.0: CxfMessage.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 Apache Camel message.

protected RouteBuilder createRouteBuilder() {
    return new RouteBuilder() {
        public void configure() {
            from(SIMPLE_ENDPOINT_URI + "&dataFormat=PAYLOAD").to("log:info").process(new Processor() {
                @SuppressWarnings("unchecked")
                public void process(final Exchange exchange) throws Exception {
                    CxfPayload<SoapHeader> requestPayload = exchange.getIn().getBody(CxfPayload.class);
                    List<Source> inElements = requestPayload.getBodySources();
                    List<Source> outElements = new ArrayList<Source>();
                    // You can use a customer toStringConverter to turn a CxfPayLoad message into String as you want
                    String request = exchange.getIn().getBody(String.class);
                    XmlConverter converter = new XmlConverter();
                    String documentString = ECHO_RESPONSE;

                    Element in = new XmlConverter().toDOMElement(inElements.get(0));
                    // Just check the element namespace
                    if (!in.getNamespaceURI().equals(ELEMENT_NAMESPACE)) {
                        throw new IllegalArgumentException("Wrong element namespace");
                    }
                    if (in.getLocalName().equals("echoBoolean")) {
                        documentString = ECHO_BOOLEAN_RESPONSE;
                        checkRequest("ECHO_BOOLEAN_REQUEST", request);
                    } else {
                        documentString = ECHO_RESPONSE;
                        checkRequest("ECHO_REQUEST", request);
                    }
                    Document outDocument = converter.toDOMDocument(documentString);
                    outElements.add(new DOMSource(outDocument.getDocumentElement()));
                    // set the payload header with null
                    CxfPayload<SoapHeader> responsePayload = new CxfPayload<SoapHeader>(null, outElements, null);
                    exchange.getOut().setBody(responsePayload);
                }
            });
        }
    };
}

How to get and set SOAP headers in POJO mode

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

The following example illustrates how to get/set SOAP headers. Suppose we have a route that forwards from one CXF endpoint to another. That is, SOAP Client → Apache 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:

<route>
    <from uri="cxf:bean:routerRelayEndpointWithInsertion"/>
    <process ref="InsertRequestOutHeaderProcessor" />
    <to uri="cxf:bean:serviceRelayEndpointWithInsertion"/>
    <process ref="InsertResponseOutHeaderProcessor" />
</route>

In 2.x SOAP headers are propagated to and from Apache Camel Message headers. The Apache 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 inserts 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.

public static class InsertResponseOutHeaderProcessor implements Processor {

    @SuppressWarnings("unchecked")
    public void process(Exchange exchange) throws Exception {
        // You should be able to get the header if exchange is routed from camel-cxf endpoint
        List<SoapHeader> soapHeaders = CastUtils.cast((List<?>)exchange.getIn().getHeader(Header.HEADER_LIST));
        if (soapHeaders == null) {
            // we just create a new soap headers in case the header is null
            soapHeaders = new ArrayList<SoapHeader>();
        }

        // Insert a new header
        String xml = "<?xml version=\"1.0\" encoding=\"utf-8\"?><outofbandHeader "
            + "xmlns=\"http://cxf.apache.org/outofband/Header\" hdrAttribute=\"testHdrAttribute\" "
            + "xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\" soap:mustUnderstand=\"1\">"
            + "<name>New_testOobHeader</name><value>New_testOobHeaderValue</value></outofbandHeader>";
        SoapHeader newHeader = new SoapHeader(soapHeaders.get(0).getName(),
                       DOMUtils.readXml(new StringReader(xml)).getDocumentElement());
        // make sure direction is OUT since it is a response message.
        newHeader.setDirection(Direction.DIRECTION_OUT);
        //newHeader.setMustUnderstand(false);
        soapHeaders.add(newHeader);

    }

}

How to get and set SOAP headers in PAYLOAD mode

We have already shown how to access SOAP message (CxfPayload object) in PAYLOAD mode (see the section called “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).

from(getRouterEndpointURI()).process(new Processor() {
    @SuppressWarnings("unchecked")
    public void process(Exchange exchange) throws Exception {
        CxfPayload<SoapHeader> payload = exchange.getIn().getBody(CxfPayload.class);
        List<Source> elements = payload.getBodySources();
        assertNotNull("We should get the elements here", elements);
        assertEquals("Get the wrong elements size", 1, elements.size());

        Element el = new XmlConverter().toDOMElement(elements.get(0));
        elements.set(0, new DOMSource(el));
        assertEquals("Get the wrong namespace URI", "http://camel.apache.org/pizza/types",
                el.getNamespaceURI());

        List<SoapHeader> headers = payload.getHeaders();
        assertNotNull("We should get the headers here", headers);
        assertEquals("Get the wrong headers size", headers.size(), 1);
        assertEquals("Get the wrong namespace URI",
                ((Element)(headers.get(0).getObject())).getNamespaceURI(),
                "http://camel.apache.org/pizza/types");
    }

})
.to(getServiceEndpointURI());

Since Camel 2.16.0, you can use the same approach as described in the section called “How to get and set SOAP headers in POJO mode” to set or get the SOAP headers. You can now use the org.apache.cxf.headers.Header.list header to get and set a list of SOAP headers. This means that if you have a route that forwards from one Camel CXF endpoint to another (SOAP Client → Camel → CXF service), the SOAP headers sent by the SOAP client are now also forwarded to the CXF service. If you do not want the headers to be forwarded, remove them from the org.apache.cxf.headers.Header.list Camel header.

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

If you are using a 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:

SOAP_FAULT = new SoapFault(EXCEPTION_MESSAGE, SoapFault.FAULT_CODE_CLIENT);
Element detail = SOAP_FAULT.getOrCreateDetail();
Document doc = detail.getOwnerDocument();
Text tn = doc.createTextNode(DETAIL_TEXT);
detail.appendChild(tn);

Then throw it as you like:

from(routerEndpointURI).setFaultBody(constant(SOAP_FAULT));

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.

from(routerEndpointURI).process(new Processor() {

    public void process(Exchange exchange) throws Exception {
        Message out = exchange.getOut();
        // Set the message body with the
        out.setBody(this.getClass().getResourceAsStream("SoapFaultMessage.xml"));
        // Set the response code here
        out.setHeader(org.apache.cxf.message.Message.RESPONSE_CODE, new Integer(500));
    }

});

The same is true for the POJO data format. You can set the SOAP Fault on the Out body and also indicate it’s a fault by calling Message.setFault(true), as follows:

from("direct:start").onException(SoapFault.class).maximumRedeliveries(0).handled(true)
    .process(new Processor() {
        public void process(Exchange exchange) throws Exception {
            SoapFault fault = exchange
                .getProperty(Exchange.EXCEPTION_CAUGHT, SoapFault.class);
            exchange.getOut().setFault(true);
            exchange.getOut().setBody(fault);
        }

    }).end().to(serviceURI);

How to propagate a 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 CXF endpoint producer to invoke the external Web service, you can set the request context and get the response context with the following code:

        CxfExchange exchange = (CxfExchange)template.send(getJaxwsEndpointUri(), new Processor() {
             public void process(final Exchange exchange) {
                 final List<String> params = new ArrayList<String>();
                 params.add(TEST_MESSAGE);
                 // Set the request context to the inMessage
                 Map<String, Object> requestContext = new HashMap<String, Object>();
                 requestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, JAXWS_SERVER_ADDRESS);
                 exchange.getIn().setBody(params);
                 exchange.getIn().setHeader(Client.REQUEST_CONTEXT , requestContext);
                 exchange.getIn().setHeader(CxfConstants.OPERATION_NAME, GREET_ME_OPERATION);
             }
         });
         org.apache.camel.Message out = exchange.getOut();
         // The output is an object array, the first element of the array is the return value
         Object\[\] output = out.getBody(Object\[\].class);
         LOG.info("Received output text: " + output\[0\]);
         // Get the response context form outMessage
         Map<String, Object> responseContext = CastUtils.cast((Map)out.getHeader(Client.RESPONSE_CONTEXT));
         assertNotNull(responseContext);
         assertEquals("Get the wrong wsdl opertion name", "{http://apache.org/hello_world_soap_http}greetMe",
                      responseContext.get("javax.xml.ws.wsdl.operation").toString());

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 since 2.1.So, it is possible to retreive attachments by Camel Message API

DataHandler Message.getAttachment(String id)

.

Payload Mode: MTOM is supported since 2.1. Attachments can be retrieved by Camel Message APIs mentioned above. SOAP with Attachment is not supported as there is no SOAP processing in this mode.

To enable MTOM, set the CXF endpoint property "mtom_enabled" to true. (I believe you can only do it with Spring.)

<cxf:cxfEndpoint id="routerEndpoint" address="http://localhost:${CXFTestSupport.port1}/CxfMtomRouterPayloadModeTest/jaxws-mtom/hello"
         wsdlURL="mtom.wsdl"
         serviceName="ns:HelloService"
         endpointName="ns:HelloPort"
         xmlns:ns="http://apache.org/camel/cxf/mtom_feature">

     <cxf:properties>
         <!--  enable mtom by setting this property to true -->
         <entry key="mtom-enabled" value="true"/>

         <!--  set the camel-cxf endpoint data fromat to PAYLOAD mode -->
         <entry key="dataFormat" value="PAYLOAD"/>
     </cxf:properties>

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

Exchange exchange = context.createProducerTemplate().send("direct:testEndpoint", new Processor() {

    public void process(Exchange exchange) throws Exception {
        exchange.setPattern(ExchangePattern.InOut);
        List&lt;Source> elements = new ArrayList&lt;Source>();
        elements.add(new DOMSource(DOMUtils.readXml(new StringReader(MtomTestHelper.REQ_MESSAGE)).getDocumentElement()));
        CxfPayload<SoapHeader> body = new CxfPayload<SoapHeader>(new ArrayList<SoapHeader>(),
            elements, null);
        exchange.getIn().setBody(body);
        exchange.getIn().addAttachment(MtomTestHelper.REQ_PHOTO_CID,
            new DataHandler(new ByteArrayDataSource(MtomTestHelper.REQ_PHOTO_DATA, "application/octet-stream")));

        exchange.getIn().addAttachment(MtomTestHelper.REQ_IMAGE_CID,
            new DataHandler(new ByteArrayDataSource(MtomTestHelper.requestJpeg, "image/jpeg")));

    }

});

// process response

CxfPayload<SoapHeader> out = exchange.getOut().getBody(CxfPayload.class);
Assert.assertEquals(1, out.getBody().size());

Map<String, String> ns = new HashMap<String, String>();
ns.put("ns", MtomTestHelper.SERVICE_TYPES_NS);
ns.put("xop", MtomTestHelper.XOP_NS);

XPathUtils xu = new XPathUtils(ns);
Element oute = new XmlConverter().toDOMElement(out.getBody().get(0));
Element ele = (Element)xu.getValue("//ns:DetailResponse/ns:photo/xop:Include", oute,
                                   XPathConstants.NODE);
String photoId = ele.getAttribute("href").substring(4); // skip "cid:"

ele = (Element)xu.getValue("//ns:DetailResponse/ns:image/xop:Include", oute,
                                   XPathConstants.NODE);
String imageId = ele.getAttribute("href").substring(4); // skip "cid:"

DataHandler dr = exchange.getOut().getAttachment(photoId);
Assert.assertEquals("application/octet-stream", dr.getContentType());
MtomTestHelper.assertEquals(MtomTestHelper.RESP_PHOTO_DATA, IOUtils.readBytesFromStream(dr.getInputStream()));

dr = exchange.getOut().getAttachment(imageId);
Assert.assertEquals("image/jpeg", dr.getContentType());

BufferedImage image = ImageIO.read(dr.getInputStream());
Assert.assertEquals(560, image.getWidth());
Assert.assertEquals(300, image.getHeight());

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

public static class MyProcessor implements Processor {

    @SuppressWarnings("unchecked")
    public void process(Exchange exchange) throws Exception {
        CxfPayload<SoapHeader> in = exchange.getIn().getBody(CxfPayload.class);

        // verify request
        assertEquals(1, in.getBody().size());

        Map<String, String> ns = new HashMap<String, String>();
        ns.put("ns", MtomTestHelper.SERVICE_TYPES_NS);
        ns.put("xop", MtomTestHelper.XOP_NS);

        XPathUtils xu = new XPathUtils(ns);
        Element body = new XmlConverter().toDOMElement(in.getBody().get(0));
        Element ele = (Element)xu.getValue("//ns:Detail/ns:photo/xop:Include", body,
                                           XPathConstants.NODE);
        String photoId = ele.getAttribute("href").substring(4); // skip "cid:"
        assertEquals(MtomTestHelper.REQ_PHOTO_CID, photoId);

        ele = (Element)xu.getValue("//ns:Detail/ns:image/xop:Include", body,
                                           XPathConstants.NODE);
        String imageId = ele.getAttribute("href").substring(4); // skip "cid:"
        assertEquals(MtomTestHelper.REQ_IMAGE_CID, imageId);

        DataHandler dr = exchange.getIn().getAttachment(photoId);
        assertEquals("application/octet-stream", dr.getContentType());
        MtomTestHelper.assertEquals(MtomTestHelper.REQ_PHOTO_DATA, IOUtils.readBytesFromStream(dr.getInputStream()));

        dr = exchange.getIn().getAttachment(imageId);
        assertEquals("image/jpeg", dr.getContentType());
        MtomTestHelper.assertEquals(MtomTestHelper.requestJpeg, IOUtils.readBytesFromStream(dr.getInputStream()));

        // create response
        List&lt;Source> elements = new ArrayList&lt;Source>();
        elements.add(new DOMSource(DOMUtils.readXml(new StringReader(MtomTestHelper.RESP_MESSAGE)).getDocumentElement()));
        CxfPayload&lt;SoapHeader> sbody = new CxfPayload&lt;SoapHeader>(new ArrayList&lt;SoapHeader>(),
            elements, null);
        exchange.getOut().setBody(sbody);
        exchange.getOut().addAttachment(MtomTestHelper.RESP_PHOTO_CID,
            new DataHandler(new ByteArrayDataSource(MtomTestHelper.RESP_PHOTO_DATA, "application/octet-stream")));

        exchange.getOut().addAttachment(MtomTestHelper.RESP_IMAGE_CID,
            new DataHandler(new ByteArrayDataSource(MtomTestHelper.responseJpeg, "image/jpeg")));

    }
}

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

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

How to propagate stack trace information

It is possible to configure a CXF endpoint so that, when a Java exception is thrown on the server side, the stack trace for the exception is marshalled into a fault message and returned to the client. To enable this feaure, set the dataFormat to PAYLOAD and set the faultStackTraceEnabled property to true in the cxfEndpoint element, as follows:

<cxf:cxfEndpoint id="router" address="http://localhost:9002/TestMessage"
    wsdlURL="ship.wsdl"
    endpointName="s:TestSoapEndpoint"
    serviceName="s:TestService"
    xmlns:s="http://test">
  <cxf:properties>
    <!-- enable sending the stack trace back to client; the default value is false-->
    <entry key="faultStackTraceEnabled" value="true" /> <entry key="dataFormat" value="PAYLOAD" />
  </cxf:properties>
</cxf:cxfEndpoint>

For security reasons, the stack trace does not include the causing exception (that is, the part of a stack trace that follows Caused by). If you want to include the causing exception in the stack trace, set the exceptionMessageCauseEnabled property to true in the cxfEndpoint element, as follows:

<cxf:cxfEndpoint id="router" address="http://localhost:9002/TestMessage"
    wsdlURL="ship.wsdl"
    endpointName="s:TestSoapEndpoint"
    serviceName="s:TestService"
    xmlns:s="http://test">
  <cxf:properties>
    <!-- enable to show the cause exception message and the default value is false -->
    <entry key="exceptionMessageCauseEnabled" value="true" />
    <!-- enable to send the stack trace back to client,  the default value is false-->
    <entry key="faultStackTraceEnabled" value="true" />
    <entry key="dataFormat" value="PAYLOAD" />
  </cxf:properties>
</cxf:cxfEndpoint>

Warning

You should only enable the exceptionMessageCauseEnabled flag for testing and diagnostic purposes. It is normal practice for servers to conceal the original cause of an exception to make it harder for hostile users to probe the server.

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.

<cxf:cxfEndpoint id="testEndpoint" address="http://localhost:9000/SoapContext/SoapAnyPort">
  <cxf:properties>
    <entry key="dataFormat" value="PAYLOAD"/>
  </cxf:properties>
</cxf:cxfEndpoint>

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

Chapter 75. CXF-RS Component

Available as of Camel version 2.0

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

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.

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

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

75.1. URI format

cxfrs://address?options

Where address represents the CXF endpoint’s address

cxfrs:bean:rsEndpoint

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:

cxfrs:bean:cxfEndpoint?resourceClasses=org.apache.camel.rs.Example

75.2. Options

The CXF-RS component supports 3 options which are listed below.

Name	Description	Default	Type
useGlobalSslContext Parameters (security)	Enable usage of global SSL context parameters.	false	boolean
headerFilterStrategy (filter)	To use a custom org.apache.camel.spi.HeaderFilterStrategy to filter header to and from Camel message.		HeaderFilterStrategy
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The CXF-RS endpoint is configured using URI syntax:

cxfrs:beanId:address

with the following path and query parameters:

75.2.1. Path Parameters (2 parameters):

Name	Description	Default	Type
beanId	To lookup an existing configured CxfRsEndpoint. Must used bean: as prefix.		String
address	The service publish address.		String

75.2.2. Query Parameters (29 parameters):

Name	Description	Default	Type
features (common)	Set the feature list to the CxfRs endpoint.		List
loggingFeatureEnabled (common)	This option enables CXF Logging Feature which writes inbound and outbound REST messages to log.	false	boolean
loggingSizeLimit (common)	To limit the total size of number of bytes the logger will output when logging feature has been enabled.		int
modelRef (common)	This option is used to specify the model file which is useful for the resource class without annotation. When using this option, then the service class can be omitted, to emulate document-only endpoints		String
providers (common)	Set custom JAX-RS provider(s) list to the CxfRs endpoint. You can specify a string with a list of providers to lookup in the registy separated by comma.		String
resourceClasses (common)	The resource classes which you want to export as REST service. Multiple classes can be separated by comma.		List
schemaLocations (common)	Sets the locations of the schema(s) which can be used to validate the incoming XML or JAXB-driven JSON.		List
skipFaultLogging (common)	This option controls whether the PhaseInterceptorChain skips logging the Fault that it catches.	false	boolean
bindingStyle (consumer)	Sets how requests and responses will be mapped to/from Camel. Two values are possible: SimpleConsumer: This binding style processes request parameters, multiparts, etc. and maps them to IN headers, IN attachments and to the message body. It aims to eliminate low-level processing of org.apache.cxf.message.MessageContentsList. It also also adds more flexibility and simplicity to the response mapping. Only available for consumers. Default: The default style. For consumers this passes on a MessageContentsList to the route, requiring low-level processing in the route. This is the traditional binding style, which simply dumps the org.apache.cxf.message.MessageContentsList coming in from the CXF stack onto the IN message body. The user is then responsible for processing it according to the contract defined by the JAX-RS method signature. Custom: allows you to specify a custom binding through the binding option.	Default	BindingStyle
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
publishedEndpointUrl (consumer)	This option can override the endpointUrl that published from the WADL which can be accessed with resource address url plus _wadl		String
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
cookieHandler (producer)	Configure a cookie handler to maintain a HTTP session		CookieHandler
hostnameVerifier (producer)	The hostname verifier to be used. Use the notation to reference a HostnameVerifier from the registry.		HostnameVerifier
sslContextParameters (producer)	The Camel SSL setting reference. Use the notation to reference the SSL Context.		SSLContextParameters
throwExceptionOnFailure (producer)	This option tells the CxfRsProducer to inspect return codes and will generate an Exception if the return code is larger than 207.	true	boolean
httpClientAPI (producer)	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	true	boolean
ignoreDeleteMethodMessage Body (producer)	This option is used to tell CxfRsProducer to ignore the message body of the DELETE method when using HTTP API.	false	boolean
maxClientCacheSize (producer)	This option allows you to configure the maximum size of the cache. The implementation caches CXF clients or ClientFactoryBean in CxfProvider and CxfRsProvider.	10	int
binding (advanced)	To use a custom CxfBinding to control the binding between Camel Message and CXF Message.		CxfRsBinding
bus (advanced)	To use a custom configured CXF Bus.		Bus
continuationTimeout (advanced)	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.	30000	long
cxfRsEndpointConfigurer (advanced)	This option could apply the implementation of org.apache.camel.component.cxf.jaxrs.CxfRsEndpointConfigurer which supports to configure the CXF endpoint in programmatic way. User can configure the CXF server and client by implementing configureServer/Client method of CxfEndpointConfigurer.		CxfRsEndpoint Configurer
defaultBus (advanced)	Will set the default bus when CXF endpoint create a bus by itself	false	boolean
headerFilterStrategy (advanced)	To use a custom HeaderFilterStrategy to filter header to and from Camel message.		HeaderFilterStrategy
performInvocation (advanced)	When the option is true, Camel will perform the invocation of the resource class instance and put the response object into the exchange for further processing.	false	boolean
propagateContexts (advanced)	When the option is true, JAXRS UriInfo, HttpHeaders, Request and SecurityContext contexts will be available to custom CXFRS processors as typed Camel exchange properties. These contexts can be used to analyze the current requests using JAX-RS API.	false	boolean
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

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.

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

75.4. How to override the CXF producer address from message header

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

 // set up the service address from the message header to override the setting of CXF endpoint
 exchange.getIn().setHeader(Exchange.DESTINATION_OVERRIDE_URL, constant(getServiceAddress()));

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

75.5.1. Enabling the Simple Binding Style

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

  from("cxfrs:bean:rsServer?bindingStyle=SimpleConsumer")
    .to("log:TEST?showAll=true");

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

75.5.3. More examples of the Simple Binding Style

Given a JAX-RS resource class with this method:

    @POST @Path("/customers/{type}")
    public Response newCustomer(Customer customer, @PathParam("type") String type, @QueryParam("active") @DefaultValue("true") boolean active) {
        return null;
    }

Serviced by the following route:

    from("cxfrs:bean:rsServer?bindingStyle=SimpleConsumer")
        .recipientList(simple("direct:${header.operationName}"));

    from("direct:newCustomer")
        .log("Request: type=${header.type}, active=${header.active}, customerData=${body}");

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

POST /customers/gold?active=true

Payload:
<Customer>
  <fullName>Raul Kripalani</fullName>
  <country>Spain</country>
  <project>Apache Camel</project>
</Customer>

Will print the message:

Request: type=gold, active=true, customerData=<Customer.toString() representation>

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

75.6. Consuming a REST Request - Default Binding Style

The http://cxf.apache.org/docs/jax-rs.html[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…

INFO:*Note about resource classes*

By default, JAX-RS 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.

Note that starting from Camel 2.15 it is also sufficient to provide an interface only as opposed to a no-op service implementation class for the default mode.

Starting from Camel 2.15, if a performInvocation option is enabled, the service implementation will be invoked first, the response will be set on the Camel exchange and the route execution will continue as usual. This can be useful for integrating the existing JAX-RS implementations into Camel routes and for post-processing JAX-RS Responses in custom processors.

75.7. How to invoke the REST service through camel-cxfrs producer

The http://cxf.apache.org/docs/jax-rs.html[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 http://cxf.apache.org/docs/jax-rs.html[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://camel.apache.org/maven/current/camel-core/apidocs/org/apache/camel/Exchange.html#HTTP_METHOD[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 http://camel.apache.org/maven/current/camel-cxf/apidocs/org/apache/camel/component/cxf/CxfConstants.html#CAMEL_CXF_RS_RESPONSE_CLASS[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.

Error formatting macro: snippet: java.lang.IndexOutOfBoundsException: Index: 20, Size: 20

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.

75.8. What’s the Camel Transport for CXF

In CXF you offer or consume a webservice by defining its address. The first part of the address specifies the protocol to use. For example address="http://localhost:9000" in an endpoint configuration means your service will be offered using the http protocol on port 9000 of localhost. When you integrate Camel Tranport into CXF you get a new transport "camel". So you can specify address="camel://direct:MyEndpointName" to bind the CXF service address to a camel direct endpoint.

Technically speaking Camel transport for CXF is a component which implements the CXF transport API with the Camel core library. This allows you to easily use Camel’s routing engine and integration patterns support together with your CXF services.

75.9. Integrate Camel into CXF transport layer

To include the Camel Tranport into your CXF bus you use the CamelTransportFactory. You can do this in Java as well as in Spring.

75.9.1. Setting up the Camel Transport in Spring

You can use the following snippet in your applicationcontext if you want to configure anything special. If you only want to activate the camel transport you do not have to do anything in your application context. As soon as you include the camel-cxf-transport jar (or camel-cxf.jar if your camel version is less than 2.7.x) in your app, cxf will scan the jar and load a CamelTransportFactory for you.

<!-- you don't need to specify the CamelTransportFactory configuration as it is auto load by CXF bus -->
<bean class="org.apache.camel.component.cxf.transport.CamelTransportFactory">
  <property name="bus" ref="cxf" />
  <property name="camelContext" ref="camelContext" />
  <!-- checkException new added in Camel 2.1 and Camel 1.6.2 -->
  <!-- If checkException is true , CamelDestination will check the outMessage's
     exception and set it into camel exchange. You can also override this value
     in CamelDestination's configuration. The default value is false.
     This option should be set true when you want to leverage the camel's error
     handler to deal with fault message -->
  <property name="checkException" value="true" />
  <property name="transportIds">
    <list>
      <value>http://cxf.apache.org/transports/camel</value>
    </list>
  </property>
</bean>

75.9.2. Integrating the Camel Transport in a programmatic way

Camel transport provides a setContext method that you could use to set the Camel context into the transport factory. If you want this factory take effect, you need to register the factory into the CXF bus. Here is a full example for you.

import org.apache.cxf.Bus;
import org.apache.cxf.BusFactory;
import org.apache.cxf.transport.ConduitInitiatorManager;
import org.apache.cxf.transport.DestinationFactoryManager;
...

BusFactory bf = BusFactory.newInstance();
Bus bus = bf.createBus();
CamelTransportFactory camelTransportFactory = new CamelTransportFactory();
// set up the CamelContext which will be use by the CamelTransportFactory
camelTransportFactory.setCamelContext(context)
// if you are using CXF higher then 2.4.x the
camelTransportFactory.setBus(bus);

// if you are lower CXF, you need to register the ConduitInitiatorManager and DestinationFactoryManager like below
// register the conduit initiator
ConduitInitiatorManager cim = bus.getExtension(ConduitInitiatorManager.class);
cim.registerConduitInitiator(CamelTransportFactory.TRANSPORT_ID, camelTransportFactory);
// register the destination factory
DestinationFactoryManager dfm = bus.getExtension(DestinationFactoryManager.class);
dfm.registerDestinationFactory(CamelTransportFactory.TRANSPORT_ID, camelTransportFactory);
// set or bus as the default bus for cxf
BusFactory.setDefaultBus(bus);

75.10. Configure the destination and conduit with Spring

75.10.1. Namespace

The elements used to configure an Camel transport endpoint are defined in the namespace http://cxf.apache.org/transports/camel. It is commonly referred to using the prefix camel. In order to use the Camel transport configuration elements, you will need to add the lines shown below to the beans element of your endpoint’s configuration file. In addition, you will need to add the configuration elements' namespace to the xsi:schemaLocation attribute.

Adding the Configuration Namespace

<beans ...
       xmlns:camel="http://cxf.apache.org/transports/camel
       ...
       xsi:schemaLocation="...
                           http://cxf.apache.org/transports/camel
                           http://cxf.apache.org/transports/camel.xsd
                          ...>

75.10.2. The `destination` element

You configure an Camel transport server endpoint using the camel:destination element and its children. The camel:destination element takes a single attribute, name, that specifies the WSDL port element that corresponds to the endpoint. The value for the name attribute takes the form portQName`.camel-destination`. The example below shows the camel:destination element that would be used to add configuration for an endpoint that was specified by the WSDL fragment <port binding="widgetSOAPBinding" name="widgetSOAPPort"> if the endpoint’s target namespace was http://widgets.widgetvendor.net.

camel:destination Element

...
  <camel:destination name="{http://widgets/widgetvendor.net}widgetSOAPPort.http-destination>
    <camelContext id="context" xmlns="http://activemq.apache.org/camel/schema/spring">
         <route>
           <from uri="direct:EndpointC" />
           <to uri="direct:EndpointD" />
         </route>
     </camelContext>
  </camel:destination>

  <!-- new added feature since Camel 2.11.x
  <camel:destination name="{http://widgets/widgetvendor.net}widgetSOAPPort.camel-destination" camelContextId="context" />

...

The camel:destination element for Spring has a number of child elements that specify configuration information. They are described below.

Element

Description

camel-spring:camelContext

You can specify the camel context in the camel destination

camel:camelContextRef

The camel context id which you want inject into the camel destination

75.10.3. The `conduit` element

You configure a Camel transport client using the camel:conduit element and its children. The camel:conduit element takes a single attribute, name, that specifies the WSDL port element that corresponds to the endpoint. The value for the name attribute takes the form portQName`.camel-conduit`. For example, the code below shows the camel:conduit element that would be used to add configuration for an endpoint that was specified by the WSDL fragment <port binding="widgetSOAPBinding" name="widgetSOAPPort"> if the endpoint’s target namespace was http://widgets.widgetvendor.net.

http-conf:conduit Element

...
  <camelContext id="conduit_context" xmlns="http://activemq.apache.org/camel/schema/spring">
       <route>
           <from uri="direct:EndpointA" />
           <to uri="direct:EndpointB" />
       </route>
   </camelContext>

  <camel:conduit name="{http://widgets/widgetvendor.net}widgetSOAPPort.camel-conduit">
     <camel:camelContextRef>conduit_context</camel:camelContextRef>
  </camel:conduit>

  <!-- new added feature since Camel 2.11.x
  <camel:conduit name="{http://widgets/widgetvendor.net}widgetSOAPPort.camel-conduit" camelContextId="conduit_context" />


  <camel:conduit name="*.camel-conduit">
  <!-- you can also using the wild card to specify the camel-conduit that you want to configure -->
    ...
  </camel:conduit>
...

The camel:conduit element has a number of child elements that specify configuration information. They are described below.

Element

Description

camel-spring:camelContext

You can specify the camel context in the camel conduit

camel:camelContextRef

The camel context id which you want inject into the camel conduit

75.11. Configure the destination and conduit with Blueprint

From Camel 2.11.x, Camel Transport supports to be configured with Blueprint.

If you are using blueprint, you should use the the namespace http://cxf.apache.org/transports/camel/blueprint and import the schema like the blow.

Adding the Configuration Namespace for blueprint

<beans ...
       xmlns:camel="http://cxf.apache.org/transports/camel/blueprint"
       ...
       xsi:schemaLocation="...
                           http://cxf.apache.org/transports/camel/blueprint
                           http://cxf.apache.org/schmemas/blueprint/camel.xsd
                          ...>

In blueprint camel:conduit camel:destination only has one camelContextId attribute, they doesn’t support to specify the camel context in the camel destination.

  <camel:conduit id="*.camel-conduit" camelContextId="camel1" />
  <camel:destination id="*.camel-destination" camelContextId="camel1" />

75.12. Example Using Camel as a load balancer for CXF

This example shows how to use the camel load balancing feature in CXF. You need to load the configuration file in CXF and publish the endpoints on the address "camel://direct:EndpointA" and "camel://direct:EndpointB"

75.13. Complete Howto and Example for attaching Camel to CXF

Better JMS Transport for CXF Webservice using Apache Camel

Chapter 76. Data Format Component

Available as of Camel version 2.12

The dataformat: component allows to use Data Format as a Camel Component.

76.1. URI format

dataformat:name:(marshal|unmarshal)[?options]

Where name is the name of the Data Format. And then followed by the operation which must either be marshal or unmarshal. The options is used for configuring the Data Format in use. See the Data Format documentation for which options it support.

76.2. DataFormat Options

The Data Format component has no options.

The Data Format endpoint is configured using URI syntax:

dataformat:name:operation

with the following path and query parameters:

76.2.1. Path Parameters (2 parameters):

Name	Description	Default	Type
name	Required Name of data format		String
operation	Required Operation to use either marshal or unmarshal		String

76.2.2. Query Parameters (1 parameters):

Name	Description	Default	Type
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

76.3. Samples

For example to use the JAXB Data Format we can do as follows:

from("activemq:My.Queue").
  to("dataformat:jaxb:unmarshal?contextPath=com.acme.model").
  to("mqseries:Another.Queue");

And in XML DSL you do:

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
  <route>
    <from uri="activemq:My.Queue"/>
    <to uri="dataformat:jaxb:unmarshal?contextPath=com.acme.model"/>
    <to uri="mqseries:Another.Queue"/>
  </route>
</camelContext>

Chapter 77. Dataset Component

Available as of Camel version 1.3

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.

77.1. URI format

dataset:name[?options]

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

Camel ships with a support implementation of org.apache.camel.component.dataset.DataSet, the org.apache.camel.component.dataset.DataSetSupport class, that can be used as a base for implementing your own DataSet. Camel also ships with some implementations that can be used for testing: org.apache.camel.component.dataset.SimpleDataSet, org.apache.camel.component.dataset.ListDataSet and org.apache.camel.component.dataset.FileDataSet, all of which extend DataSetSupport.

77.2. Options

The Dataset component has no options.

The Dataset endpoint is configured using URI syntax:

dataset:name

with the following path and query parameters:

77.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
name	Required Name of DataSet to lookup in the registry		DataSet

77.2.2. Query Parameters (19 parameters):

Name	Description	Default	Type
dataSetIndex (common)	Controls the behaviour of the CamelDataSetIndex header. For Consumers: - off = the header will not be set - strict/lenient = the header will be set For Producers: - off = the header value will not be verified, and will not be set if it is not present = strict = the header value must be present and will be verified = lenient = the header value will be verified if it is present, and will be set if it is not present	lenient	String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN/ERROR level and ignored.	false	boolean
initialDelay (consumer)	Time period in millis to wait before starting sending messages.	1000	long
minRate (consumer)	Wait until the DataSet contains at least this number of messages	0	int
preloadSize (consumer)	Sets how many messages should be preloaded (sent) before the route completes its initialization	0	long
produceDelay (consumer)	Allows a delay to be specified which causes a delay when a message is sent by the consumer (to simulate slow processing)	3	long
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN/ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the default exchange pattern when creating an exchange.		ExchangePattern
assertPeriod (producer)	Sets a grace period after which the mock endpoint will re-assert to ensure the preliminary assertion is still valid. This is used for example to assert that exactly a number of messages arrives. For example if link expectedMessageCount(int) was set to 5, then the assertion is satisfied when 5 or more message arrives. To ensure that exactly 5 messages arrives, then you would need to wait a little period to ensure no further message arrives. This is what you can use this link setAssertPeriod(long) method for. By default this period is disabled.	0	long
consumeDelay (producer)	Allows a delay to be specified which causes a delay when a message is consumed by the producer (to simulate slow processing)	0	long
expectedCount (producer)	Specifies the expected number of message exchanges that should be received by this endpoint. Beware: If you want to expect that 0 messages, then take extra care, as 0 matches when the tests starts, so you need to set a assert period time to let the test run for a while to make sure there are still no messages arrived; for that use link setAssertPeriod(long). An alternative is to use NotifyBuilder, and use the notifier to know when Camel is done routing some messages, before you call the link assertIsSatisfied() method on the mocks. This allows you to not use a fixed assert period, to speedup testing times. If you want to assert that exactly n’th message arrives to this mock endpoint, then see also the link setAssertPeriod(long) method for further details.	-1	int
reportGroup (producer)	A number that is used to turn on throughput logging based on groups of the size.		int
resultMinimumWaitTime (producer)	Sets the minimum expected amount of time (in millis) the link assertIsSatisfied() will wait on a latch until it is satisfied	0	long
resultWaitTime (producer)	Sets the maximum amount of time (in millis) the link assertIsSatisfied() will wait on a latch until it is satisfied	0	long
retainFirst (producer)	Specifies to only retain the first n’th number of received Exchanges. This is used when testing with big data, to reduce memory consumption by not storing copies of every Exchange this mock endpoint receives. Important: When using this limitation, then the link getReceivedCounter() will still return the actual number of received Exchanges. For example if we have received 5000 Exchanges, and have configured to only retain the first 10 Exchanges, then the link getReceivedCounter() will still return 5000 but there is only the first 10 Exchanges in the link getExchanges() and link getReceivedExchanges() methods. When using this method, then some of the other expectation methods is not supported, for example the link expectedBodiesReceived(Object…) sets a expectation on the first number of bodies received. You can configure both link setRetainFirst(int) and link setRetainLast(int) methods, to limit both the first and last received.	-1	int
retainLast (producer)	Specifies to only retain the last n’th number of received Exchanges. This is used when testing with big data, to reduce memory consumption by not storing copies of every Exchange this mock endpoint receives. Important: When using this limitation, then the link getReceivedCounter() will still return the actual number of received Exchanges. For example if we have received 5000 Exchanges, and have configured to only retain the last 20 Exchanges, then the link getReceivedCounter() will still return 5000 but there is only the last 20 Exchanges in the link getExchanges() and link getReceivedExchanges() methods. When using this method, then some of the other expectation methods is not supported, for example the link expectedBodiesReceived(Object…) sets a expectation on the first number of bodies received. You can configure both link setRetainFirst(int) and link setRetainLast(int) methods, to limit both the first and last received.	-1	int
sleepForEmptyTest (producer)	Allows a sleep to be specified to wait to check that this endpoint really is empty when link expectedMessageCount(int) is called with zero	0	long
copyOnExchange (producer)	Sets whether to make a deep copy of the incoming Exchange when received at this mock endpoint. Is by default true.	true	boolean
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

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

77.3. Configuring DataSet

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

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

77.4. Example

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

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

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

The above would look in the Registry to find the foo DataSet instance which is used to create the messages.

Then you create a DataSet implementation, such as using the SimpleDataSet as described below, configuring things like how big the data set is and what the messages look like etc.

77.5. DataSetSupport (abstract class)

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

77.5.1. Properties on DataSetSupport

Property	Type	Default	Description
`defaultHeaders`	`Map<String,Object>`	`null`	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`.
`outputTransformer`	`org.apache.camel.Processor`	null
`size`	`long`	`10`	Specifies how many messages to send/consume.
`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.

77.6. SimpleDataSet

The SimpleDataSet extends DataSetSupport, and adds a default body.

77.6.1. Additional Properties on SimpleDataSet

Property	Type	Default	Description
`defaultBody`	`Object`	`<hello>world!</hello>`	Specifies the default message body. By default, the `SimpleDataSet` produces the same constant payload for each exchange. If you want to customize the payload for each exchange, create a Camel `Processor` and configure the `SimpleDataSet` to use it by setting the `outputTransformer` property.

77.7. ListDataSet

Available since Camel 2.17

The List`DataSet` extends DataSetSupport, and adds a list of default bodies.

77.7.1. Additional Properties on ListDataSet

Property	Type	Default	Description
`defaultBodies`	`List<Object>`	`empty LinkedList<Object>`	Specifies the default message body. By default, the `ListDataSet` selects a constant payload from the list of `defaultBodies` using the `CamelDataSetIndex`. If you want to customize the payload, create a Camel `Processor` and configure the `ListDataSet` to use it by setting the `outputTransformer` property.
`size`	`long`	the size of the defaultBodies list	Specifies how many messages to send/consume. This value can be different from the size of the `defaultBodies` list. If the value is less than the size of the `defaultBodies` list, some of the list elements will not be used. If the value is greater than the size of the `defaultBodies` list, the payload for the exchange will be selected using the modulus of the `CamelDataSetIndex` and the size of the `defaultBodies` list (i.e. `CamelDataSetIndex % defaultBodies.size()` )

77.8. FileDataSet

Available since Camel 2.17

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

77.8.1. Additional Properties on FileDataSet

Property	Type	Default	Description
`sourceFile`	`File`	null	Specifies the source file for payloads
`delimiter`	`String`	\z	Specifies the delimiter pattern used by a `java.util.Scanner` to split the file into multiple payloads.

Chapter 78. DigitalOcean Component

Available as of Camel version 2.19

The DigitalOcean component allows you to manage Droplets and resources within the DigitalOcean cloud with Camel by encapsulating [digitalocean-api-java](https://www.digitalocean.com/community/projects/api-client-in-java). All of the functionality that you are familiar with in the DigitalOcean control panel is also available through this Camel component.

78.1. Prerequisites

You must have a valid DigitalOcean account and a valid OAuth token. You can generate an OAuth token by visiting the [Apps & API](https://cloud.digitalocean.com/settings/applications) section of the DigitalOcean control panel for your account.

78.2. URI format

The DigitalOcean Component uses the following URI format:

digitalocean://endpoint?[options]

where endpoint is a DigitalOcean resource type.

Example : to list your droplets:

digitalocean://droplets?operation=list&oAuthToken=XXXXXX&page=1&perPage=10

The DigitalOcean component only supports producer endpoints so you cannot use this component at the beginning of a route to listen to messages in a channel.

78.3. Options

The DigitalOcean component has no options.

The DigitalOcean endpoint is configured using URI syntax:

digitalocean:operation

with the following path and query parameters:

78.3.1. Path Parameters (1 parameters):

Name	Description	Default	Type
operation	The operation to perform to the given resource.		DigitalOceanOperations

78.3.2. Query Parameters (10 parameters):

Name	Description	Default	Type
page (producer)	Use for pagination. Force the page number.	1	Integer
perPage (producer)	Use for pagination. Set the number of item per request. The maximum number of results per page is 200.	25	Integer
resource (producer)	Required The DigitalOcean resource type on which perform the operation.		DigitalOceanResources
digitalOceanClient (advanced)	To use a existing configured DigitalOceanClient as client		DigitalOceanClient
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
httpProxyHost (proxy)	Set a proxy host if needed		String
httpProxyPassword (proxy)	Set a proxy password if needed		String
httpProxyPort (proxy)	Set a proxy port if needed		Integer
httpProxyUser (proxy)	Set a proxy host if needed		String
oAuthToken (security)	DigitalOcean OAuth Token		String

You have to provide an operation value for each endpoint, with the operation URI option or the CamelDigitalOceanOperation message header.

All operation values are defined in DigitalOceanOperations enumeration.

All header names used by the component are defined in DigitalOceanHeaders enumeration.

78.4. Message body result

All message bodies returned are using objects provided by the digitalocean-api-java library.

78.5. API Rate Limits

DigitalOcean REST API encapsulated by camel-digitalocean component is subjected to API Rate Limiting. You can find the per method limits in the [API Rate Limits documentation](https://developers.digitalocean.com/documentation/v2/#rate-limit).

78.6. Account endpoint

| operation | Description | Headers | Result | | ------ | ---- | ------- | ----------- | | get | get account info | | com.myjeeva.digitalocean.pojo.Account |

78.7. BlockStorages endpoint

| operation | Description | Headers | Result | | ------ | ---- | ------- | ----------- | | list | list all of the Block Storage volumes available on your account | | List<com.myjeeva.digitalocean.pojo.Volume> | | get | show information about a Block Storage volume| CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Volume | | get | show information about a Block Storage volume by name| CamelDigitalOceanName String `CamelDigitalOceanRegion` String| com.myjeeva.digitalocean.pojo.Volume | | listSnapshots | retrieve the snapshots that have been created from a volume | CamelDigitalOceanId Integer| List<com.myjeeva.digitalocean.pojo.Snapshot> | | create | create a new volume | CamelDigitalOceanVolumeSizeGigabytes Integer `CamelDigitalOceanName` String `CamelDigitalOceanDescription`* String `CamelDigitalOceanRegion`* String| com.myjeeva.digitalocean.pojo.Volume | | delete | delete a Block Storage volume, destroying all data and removing it from your account| CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Delete| | delete | delete a Block Storage volume by name| CamelDigitalOceanName String `CamelDigitalOceanRegion` String| com.myjeeva.digitalocean.pojo.Delete | attach | attach a Block Storage volume to a Droplet| CamelDigitalOceanId Integer `CamelDigitalOceanDropletId` Integer `CamelDigitalOceanDropletRegion` String| com.myjeeva.digitalocean.pojo.Action | attach | attach a Block Storage volume to a Droplet by name| CamelDigitalOceanName String `CamelDigitalOceanDropletId` Integer `CamelDigitalOceanDropletRegion` String| com.myjeeva.digitalocean.pojo.Action | detach | detach a Block Storage volume from a Droplet| CamelDigitalOceanId Integer `CamelDigitalOceanDropletId` Integer `CamelDigitalOceanDropletRegion` String| com.myjeeva.digitalocean.pojo.Action | attach | detach a Block Storage volume from a Droplet by name| CamelDigitalOceanName String `CamelDigitalOceanDropletId` Integer `CamelDigitalOceanDropletRegion` String| com.myjeeva.digitalocean.pojo.Action | resize | resize a Block Storage volume | CamelDigitalOceanVolumeSizeGigabytes Integer `CamelDigitalOceanRegion` String| com.myjeeva.digitalocean.pojo.Action | | listActions | retrieve all actions that have been executed on a volume | CamelDigitalOceanId Integer| List<com.myjeeva.digitalocean.pojo.Action> |

78.8. Droplets endpoint

| operation | Description | Headers | Result | | ------ | ---- | ------- | ----------- | | list | list all Droplets in your account | | List<com.myjeeva.digitalocean.pojo.Droplet> | | get | show an individual droplet | CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Droplet | | create | create a new Droplet | CamelDigitalOceanName String `CamelDigitalOceanDropletImage` String `CamelDigitalOceanRegion` String `CamelDigitalOceanDropletSize` String `CamelDigitalOceanDropletSSHKeys`* List\<String\> `CamelDigitalOceanDropletEnableBackups`* Boolean `CamelDigitalOceanDropletEnableIpv6`* Boolean `CamelDigitalOceanDropletEnablePrivateNetworking`* Boolean `CamelDigitalOceanDropletUserData`* String `CamelDigitalOceanDropletVolumes`* List\<String\> `CamelDigitalOceanDropletTags` List\<String\>| com.myjeeva.digitalocean.pojo.Droplet | | create | create multiple Droplets | CamelDigitalOceanNames List\<String\> `CamelDigitalOceanDropletImage` String `CamelDigitalOceanRegion` String `CamelDigitalOceanDropletSize` String `CamelDigitalOceanDropletSSHKeys`* List\<String\> `CamelDigitalOceanDropletEnableBackups`* Boolean `CamelDigitalOceanDropletEnableIpv6`* Boolean `CamelDigitalOceanDropletEnablePrivateNetworking`* Boolean `CamelDigitalOceanDropletUserData`* String `CamelDigitalOceanDropletVolumes`* List\<String\> `CamelDigitalOceanDropletTags` List\<String\>| com.myjeeva.digitalocean.pojo.Droplet | | delete | delete a Droplet, | CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Delete | | enableBackups | enable backups on an existing Droplet | CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Action | | disableBackups | disable backups on an existing Droplet | CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Action | | enableIpv6 | enable IPv6 networking on an existing Droplet | CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Action | | enablePrivateNetworking | enable private networking on an existing Droplet | CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Action | | reboot | reboot a Droplet | CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Action | | powerCycle | power cycle a Droplet | CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Action | | shutdown | shutdown a Droplet | CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Action | | powerOff | power off a Droplet | CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Action | | powerOn | power on a Droplet | CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Action | | restore | shutdown a Droplet | CamelDigitalOceanId Integer `CamelDigitalOceanImageId` Integer| com.myjeeva.digitalocean.pojo.Action | | passwordReset | reset the password for a Droplet | CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Action | | resize | resize a Droplet | CamelDigitalOceanId Integer `CamelDigitalOceanDropletSize` String| com.myjeeva.digitalocean.pojo.Action | | rebuild | rebuild a Droplet | CamelDigitalOceanId Integer `CamelDigitalOceanImageId` Integer| com.myjeeva.digitalocean.pojo.Action | | rename | rename a Droplet | CamelDigitalOceanId Integer `CamelDigitalOceanName` String| com.myjeeva.digitalocean.pojo.Action | | changeKernel | change the kernel of a Droplet | CamelDigitalOceanId Integer `CamelDigitalOceanKernelId` Integer| com.myjeeva.digitalocean.pojo.Action | | takeSnapshot | snapshot a Droplet | CamelDigitalOceanId Integer `CamelDigitalOceanName`* String| com.myjeeva.digitalocean.pojo.Action | | tag | tag a Droplet | CamelDigitalOceanId Integer `CamelDigitalOceanName` String| com.myjeeva.digitalocean.pojo.Response | | untag | untag a Droplet | CamelDigitalOceanId Integer `CamelDigitalOceanName` String| com.myjeeva.digitalocean.pojo.Response | | listKernels | retrieve a list of all kernels available to a Droplet | CamelDigitalOceanId Integer | List<com.myjeeva.digitalocean.pojo.Kernel> | | listSnapshots | retrieve the snapshots that have been created from a Droplet | CamelDigitalOceanId Integer | List<com.myjeeva.digitalocean.pojo.Snapshot> | | listBackups | retrieve any backups associated with a Droplet | CamelDigitalOceanId Integer | List<com.myjeeva.digitalocean.pojo.Backup> | | listActions | retrieve all actions that have been executed on a Droplet | CamelDigitalOceanId Integer | List<com.myjeeva.digitalocean.pojo.Action> | | listNeighbors | retrieve a list of droplets that are running on the same physical server | CamelDigitalOceanId Integer | List<com.myjeeva.digitalocean.pojo.Droplet> | | listAllNeighbors | retrieve a list of any droplets that are running on the same physical hardware | | List<com.myjeeva.digitalocean.pojo.Droplet> |

78.9. Images endpoint

| operation | Description | Headers | Result | | ------ | ---- | ------- | ----------- | | list | list images available on your account | CamelDigitalOceanType* DigitalOceanImageTypes | List<com.myjeeva.digitalocean.pojo.Image> | | ownList | retrieve only the private images of a user | | List<com.myjeeva.digitalocean.pojo.Image> | | listActions | retrieve all actions that have been executed on a Image | CamelDigitalOceanId Integer | List<com.myjeeva.digitalocean.pojo.Action> | | get | retrieve information about an image (public or private) by id| CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Image | | get | retrieve information about an public image by slug| CamelDigitalOceanDropletImage String| com.myjeeva.digitalocean.pojo.Image | | update | update an image| CamelDigitalOceanId Integer `CamelDigitalOceanName` String| com.myjeeva.digitalocean.pojo.Image | | delete | delete an image| CamelDigitalOceanId Integer | com.myjeeva.digitalocean.pojo.Delete | | transfer | transfer an image to another region| CamelDigitalOceanId Integer `CamelDigitalOceanRegion` String| com.myjeeva.digitalocean.pojo.Action | | convert | convert an image, for example, a backup to a snapshot| CamelDigitalOceanId Integer | com.myjeeva.digitalocean.pojo.Action |

78.10. Snapshots endpoint

| operation | Description | Headers | Result | | ------ | ---- | ------- | ----------- | | list | list all of the snapshots available on your account | CamelDigitalOceanType* DigitalOceanSnapshotTypes | List<com.myjeeva.digitalocean.pojo.Snapshot> | | get | retrieve information about a snapshot| CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Snapshot | | delete | delete an snapshot| CamelDigitalOceanId Integer | com.myjeeva.digitalocean.pojo.Delete |

78.11. Keys endpoint

| operation | Description | Headers | Result | | ------ | ---- | ------- | ----------- | | list | list all of the keys in your account | | List<com.myjeeva.digitalocean.pojo.Key> | | get | retrieve information about a key by id| CamelDigitalOceanId Integer| com.myjeeva.digitalocean.pojo.Key | | get | retrieve information about a key by fingerprint| CamelDigitalOceanKeyFingerprint String| com.myjeeva.digitalocean.pojo.Key | | update | update a key by id| CamelDigitalOceanId Integer `CamelDigitalOceanName` String| com.myjeeva.digitalocean.pojo.Key | | update | update a key by fingerprint| CamelDigitalOceanKeyFingerprint String `CamelDigitalOceanName` String| com.myjeeva.digitalocean.pojo.Key | | delete | delete a key by id| CamelDigitalOceanId Integer | com.myjeeva.digitalocean.pojo.Delete | | delete | delete a key by fingerprint| CamelDigitalOceanKeyFingerprint String | com.myjeeva.digitalocean.pojo.Delete |

78.12. Regions endpoint

| operation | Description | Headers | Result | | ------ | ---- | ------- | ----------- | | list | list all of the regions that are available | | List<com.myjeeva.digitalocean.pojo.Region> |

78.13. Sizes endpoint

| operation | Description | Headers | Result | | ------ | ---- | ------- | ----------- | | list | list all of the sizes that are available | | List<com.myjeeva.digitalocean.pojo.Size> |

78.14. Floating IPs endpoint

| operation | Description | Headers | Result | | ------ | ---- | ------- | ----------- | | list | list all of the Floating IPs available on your account | | List<com.myjeeva.digitalocean.pojo.FloatingIP> | | create | create a new Floating IP assigned to a Droplet | CamelDigitalOceanId Integer | List<com.myjeeva.digitalocean.pojo.FloatingIP> | | create | create a new Floating IP assigned to a Region | CamelDigitalOceanRegion String | List<com.myjeeva.digitalocean.pojo.FloatingIP> | | get | retrieve information about a Floating IP| CamelDigitalOceanFloatingIPAddress String| com.myjeeva.digitalocean.pojo.Key | | delete | delete a Floating IP and remove it from your account| CamelDigitalOceanFloatingIPAddress String| com.myjeeva.digitalocean.pojo.Delete | | assign | assign a Floating IP to a Droplet| CamelDigitalOceanFloatingIPAddress String `CamelDigitalOceanDropletId` Integer| com.myjeeva.digitalocean.pojo.Action | | unassign | unassign a Floating IP | CamelDigitalOceanFloatingIPAddress String | com.myjeeva.digitalocean.pojo.Action | | listActions | retrieve all actions that have been executed on a Floating IP | CamelDigitalOceanFloatingIPAddress String | List<com.myjeeva.digitalocean.pojo.Action> |

78.15. Tags endpoint

| operation | Description | Headers | Result | | ------ | ---- | ------- | ----------- | | list | list all of your tags | | List<com.myjeeva.digitalocean.pojo.Tag> | | create | create a Tag | CamelDigitalOceanName String | com.myjeeva.digitalocean.pojo.Tag | | get | retrieve an individual tag | CamelDigitalOceanName String | com.myjeeva.digitalocean.pojo.Tag | | delete | delete a tag | CamelDigitalOceanName String | com.myjeeva.digitalocean.pojo.Delete | | update | update a tag | CamelDigitalOceanName String `CamelDigitalOceanNewName` String| com.myjeeva.digitalocean.pojo.Tag |

78.16. Examples

Get your account info

from("direct:getAccountInfo")
    .setHeader(DigitalOceanConstants.OPERATION, constant(DigitalOceanOperations.get))
    .to("digitalocean:account?oAuthToken=XXXXXX")

Create a droplet

from("direct:createDroplet")
    .setHeader(DigitalOceanConstants.OPERATION, constant("create"))
    .setHeader(DigitalOceanHeaders.NAME, constant("myDroplet"))
    .setHeader(DigitalOceanHeaders.REGION, constant("fra1"))
    .setHeader(DigitalOceanHeaders.DROPLET_IMAGE, constant("ubuntu-14-04-x64"))
    .setHeader(DigitalOceanHeaders.DROPLET_SIZE, constant("512mb"))
    .to("digitalocean:droplet?oAuthToken=XXXXXX")

List all your droplets

from("direct:getDroplets")
    .setHeader(DigitalOceanConstants.OPERATION, constant("list"))
    .to("digitalocean:droplets?oAuthToken=XXXXXX")

Retrieve information for the Droplet (dropletId = 34772987)

from("direct:getDroplet")
    .setHeader(DigitalOceanConstants.OPERATION, constant("get"))
    .setHeader(DigitalOceanConstants.ID, 34772987)
    .to("digitalocean:droplet?oAuthToken=XXXXXX")

Shutdown information for the Droplet (dropletId = 34772987)

from("direct:shutdown")
    .setHeader(DigitalOceanConstants.ID, 34772987)
    .to("digitalocean:droplet?operation=shutdown&oAuthToken=XXXXXX")

Chapter 79. Direct Component

Available as of Camel version 1.0

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.

Tip

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

Tip

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

79.1. URI format

direct:someName[?options]

Where someName can be any string to uniquely identify the endpoint

79.2. Options

The Direct component supports 3 options which are listed below.

Name	Description	Default	Type
block (producer)	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.	true	boolean
timeout (producer)	The timeout value to use if block is enabled.	30000	long
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Direct endpoint is configured using URI syntax:

direct:name

with the following path and query parameters:

79.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
name	Required Name of direct endpoint		String

79.2.2. Query Parameters (7 parameters):

Name	Description	Default	Type
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN/ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN/ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the default exchange pattern when creating an exchange.		ExchangePattern
block (producer)	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.	true	boolean
failIfNoConsumers (producer)	Whether the producer should fail by throwing an exception, when sending to a DIRECT endpoint with no active consumers.	false	boolean
timeout (producer)	The timeout value to use if block is enabled.	30000	long
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

79.3. Samples

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

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

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

And the sample using spring DSL:

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

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

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

Chapter 80. Direct VM Component

Available as of Camel version 2.10

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

This component differs from the Direct component in that Direct-VM supports communication across CamelContext instances - so you can use this mechanism to communicate across web applications (provided that camel-core.jar is on the system/boot classpath).

At runtime you can swap in new consumers, by stopping the existing consumer(s) and start new consumers.
But at any given time there can be at most only one active consumer for a given endpoint.

This component allows also to connect routes deployed in different OSGI Bundles as you can see here after. Even if they are running in different bundles, the camel routes will use
the same thread. That autorises to develop applications using Transactions - Tx.

80.1. URI format

direct-vm:someName

Where someName can be any string to uniquely identify the endpoint

80.2. Options

The Direct VM component supports 5 options which are listed below.

Name	Description	Default	Type
block (producer)	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.	true	boolean
timeout (producer)	The timeout value to use if block is enabled.	30000	long
headerFilterStrategy (advanced)	Sets a HeaderFilterStrategy that will only be applied on producer endpoints (on both directions: request and response). Default value: none.		HeaderFilterStrategy
propagateProperties (advanced)	Whether to propagate or not properties from the producer side to the consumer side, and vice versa. Default value: true.	true	boolean
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Direct VM endpoint is configured using URI syntax:

direct-vm:name

with the following path and query parameters:

80.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
name	Required Name of direct-vm endpoint		String

80.2.2. Query Parameters (9 parameters):

Name	Description	Default	Type
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN/ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN/ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the default exchange pattern when creating an exchange.		ExchangePattern
block (producer)	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.	true	boolean
failIfNoConsumers (producer)	Whether the producer should fail by throwing an exception, when sending to a Direct-VM endpoint with no active consumers.	false	boolean
timeout (producer)	The timeout value to use if block is enabled.	30000	long
headerFilterStrategy (producer)	Sets a HeaderFilterStrategy that will only be applied on producer endpoints (on both directions: request and response). Default value: none.		HeaderFilterStrategy
propagateProperties (advanced)	Whether to propagate or not properties from the producer side to the consumer side, and vice versa. Default value: true.	true	boolean
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

80.3. Samples

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

from("activemq:queue:order.in")
    .to("bean:orderServer?method=validate")
    .to("direct-vm:processOrder");

And now in another CamelContext, such as another OSGi bundle

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

And the sample using spring DSL:

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

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

80.4. See Also

Direct
SEDA
VM

Chapter 81. Disruptor Component

Available as of Camel version 2.12

The disruptor: component provides asynchronous SEDA behavior much as the standard SEDA Component, but utilizes a Disruptor instead of a BlockingQueue utilized by the standard SEDA. Alternatively, a

disruptor-vm: endpoint is supported by this component, providing an alternative to the standard VM. As with the SEDA component, buffers of the disruptor: endpoints are only visible within a single CamelContext and no support is provided for persistence or recovery. The buffers of the disruptor-vm: endpoints also provides support for communication across CamelContexts instances so you can use this mechanism to communicate across web applications (provided that camel-disruptor.jar is on the system/boot classpath).

The main advantage of choosing to use the Disruptor Component over the SEDA or the VM Component is performance in use cases where there is high contention between producer(s) and/or multicasted or concurrent Consumers. In those cases, significant increases of throughput and reduction of latency has been observed. Performance in scenarios without contention is comparable to the SEDA and VM Components.

The Disruptor is implemented with the intention of mimicing the behaviour and options of the SEDA and VM Components as much as possible. The main differences with the them are the following:

The buffer used is always bounded in size (default 1024 exchanges).
As a the buffer is always bouded, the default behaviour for the Disruptor is to block while the buffer is full instead of throwing an exception. This default behaviour may be configured on the component (see options).
The Disruptor enpoints don’t implement the BrowsableEndpoint interface. As such, the exchanges currently in the Disruptor can’t be retrieved, only the amount of exchanges.
The Disruptor requires its consumers (multicasted or otherwise) to be statically configured. Adding or removing consumers on the fly requires complete flushing of all pending exchanges in the Disruptor.
As a result of the reconfiguration: Data sent over a Disruptor is directly processed and 'gone' if there is at least one consumer, late joiners only get new exchanges published after they’ve joined.
The pollTimeout option is not supported by the Disruptor Component.
When a producer blocks on a full Disruptor, it does not respond to thread interrupts.

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

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

81.1. URI format

 disruptor:someName[?options]

or

 disruptor-vm:someName[?options]

Where someName can be any string that uniquely identifies the endpoint within the current CamelContext (or across contexts in case of
disruptor-vm:).
You can append query options to the URI in the following format:

  ?option=value&option=value&…

81.2. Options

All the following options are valid for both the disruptor: and disruptor-vm: components.

The Disruptor component supports 8 options which are listed below.

Name	Description	Default	Type
defaultConcurrent Consumers (consumer)	To configure the default number of concurrent consumers	1	int
defaultMultiple Consumers (consumer)	To configure the default value for multiple consumers	false	boolean
defaultProducerType (producer)	To configure the default value for DisruptorProducerType The default value is Multi.	Multi	DisruptorProducerType
defaultWaitStrategy (consumer)	To configure the default value for DisruptorWaitStrategy The default value is Blocking.	Blocking	DisruptorWaitStrategy
defaultBlockWhenFull (producer)	To configure the default value for block when full The default value is true.	true	boolean
queueSize (common)	Deprecated To configure the ring buffer size		int
bufferSize (common)	To configure the ring buffer size	1024	int
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Disruptor endpoint is configured using URI syntax:

disruptor:name

with the following path and query parameters:

81.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
name	Required Name of queue		String

81.2.2. Query Parameters (12 parameters):

Name	Description	Default	Type
size (common)	The maximum capacity of the Disruptors ringbuffer Will be effectively increased to the nearest power of two. Notice: Mind if you use this option, then its the first endpoint being created with the queue name, that determines the size. To make sure all endpoints use same size, then configure the size option on all of them, or the first endpoint being created.	1024	int
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
concurrentConsumers (consumer)	Number of concurrent threads processing exchanges.	1	int
multipleConsumers (consumer)	Specifies whether multiple consumers are allowed. If enabled, you can use Disruptor for Publish-Subscribe messaging. That is, you can send a message to the queue and have each consumer receive a copy of the message. When enabled, this option should be specified on every consumer endpoint.	false	boolean
waitStrategy (consumer)	Defines the strategy used by consumer threads to wait on new exchanges to be published. The options allowed are:Blocking, Sleeping, BusySpin and Yielding.	Blocking	DisruptorWaitStrategy
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
blockWhenFull (producer)	Whether a thread that sends messages to a full Disruptor will block until the ringbuffer’s capacity is no longer exhausted. By default, the calling thread will block and wait until the message can be accepted. By disabling this option, an exception will be thrown stating that the queue is full.	false	boolean
producerType (producer)	Defines the producers allowed on the Disruptor. The options allowed are: Multi to allow multiple producers and Single to enable certain optimizations only allowed when one concurrent producer (on one thread or otherwise synchronized) is active.	Multi	DisruptorProducerType
timeout (producer)	Timeout (in milliseconds) before a producer will stop waiting for an asynchronous task to complete. You can disable timeout by using 0 or a negative value.	30000	long
waitForTaskToComplete (producer)	Option to specify whether the caller should wait for the async task to complete or not before continuing. The following three options are supported: Always, Never or IfReplyExpected. The first two values are self-explanatory. The last value, IfReplyExpected, will only wait if the message is Request Reply based.	IfReplyExpected	WaitForTaskToComplete
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

81.3. Wait strategies

The wait strategy effects the type of waiting performed by the consumer threads that are currently waiting for the next exchange to be published. The following strategies can be chosen:

Name	Description	Advice
Blocking	Blocking strategy that uses a lock and condition variable for Consumers waiting on a barrier.	This strategy can be used when throughput and low-latency are not as important as CPU resource.
Sleeping	Sleeping strategy that initially spins, then uses a Thread.yield(), and eventually for the minimum number of nanos the OS and JVM will allow while the Consumers are waiting on a barrier.	This strategy is a good compromise between performance and CPU resource. Latency spikes can occur after quiet periods.
BusySpin	Busy Spin strategy that uses a busy spin loop for Consumers waiting on a barrier.	This strategy will use CPU resource to avoid syscalls which can introduce latency jitter. It is best used when threads can be bound to specific CPU cores.
Yielding	Yielding strategy that uses a Thread.yield() for Consumers waiting on a barrier after an initially spinning.	This strategy is a good compromise between performance and CPU resource without incurring significant latency spikes.

81.4. Use of Request Reply

The Disruptor component supports using Request Reply, where the caller will wait for the Async route to complete. For instance:

from("mina:tcp://0.0.0.0:9876?textline=true&sync=true").to("disruptor:input");
from("disruptor:input").to("bean:processInput").to("bean:createResponse");

In the route above, we have a TCP listener on port 9876 that accepts incoming requests. The request is routed to the disruptor:input buffer. As it is a Request Reply message, we wait for the response. When the consumer on the disruptor:input buffer is complete, it copies the response to the original message response.

81.5. Concurrent consumers

By default, the Disruptor endpoint uses a single consumer thread, but you can configure it to use concurrent consumer threads. So instead of thread pools you can use:

from("disruptor:stageName?concurrentConsumers=5").process(...)

As for the difference between the two, note a thread pool can increase/shrink dynamically at runtime depending on load, whereas the number of concurrent consumers is always fixed and supported by the Disruptor internally so performance will be higher.

81.6. Thread pools

Be aware that adding a thread pool to a Disruptor endpoint by doing something like:

from("disruptor:stageName").thread(5).process(...)

Can wind up with adding a normal BlockingQueue to be used in conjunction with the Disruptor, effectively negating part of the performance gains achieved by using the Disruptor. Instead, it is advices to directly configure number of threads that process messages on a Disruptor endpoint using the concurrentConsumers option.

81.7. Sample

In the route below we use the Disruptor to send the request to this async queue to be able to send a fire-and-forget message for further processing in another thread, and return a constant reply in this thread to the original caller.

public void configure() throws Exception {
    from("direct:start")
        // send it to the disruptor that is async
        .to("disruptor:next")
        // return a constant response
        .transform(constant("OK"));

    from("disruptor:next").to("mock:result");
}

Here we send a Hello World message and expects the reply to be OK.

Object out = template.requestBody("direct:start", "Hello World");
assertEquals("OK", out);

The "Hello World" message will be consumed from the Disruptor from another thread for further processing. Since this is from a unit test, it will be sent to a mock endpoint where we can do assertions in the unit test.

81.8. Using multipleConsumers

In this example we have defined two consumers and registered them as spring beans.

<!-- define the consumers as spring beans -->
<bean id="consumer1" class="org.apache.camel.spring.example.FooEventConsumer"/>

<bean id="consumer2" class="org.apache.camel.spring.example.AnotherFooEventConsumer"/>

<camelContext xmlns="http://camel.apache.org/schema/spring">
    <!-- define a shared endpoint which the consumers can refer to instead of using url -->
    <endpoint id="foo" uri="disruptor:foo?multipleConsumers=true"/>
</camelContext>

Since we have specified multipleConsumers=true on the Disruptor foo endpoint we can have those two or more consumers receive their own copy of the message as a kind of pub-sub style messaging. As the beans are part of an unit test they simply send the message to a mock endpoint, but notice how we can use @Consume to consume from the Disruptor.

public class FooEventConsumer {

    @EndpointInject(uri = "mock:result")
    private ProducerTemplate destination;

    @Consume(ref = "foo")
    public void doSomething(String body) {
        destination.sendBody("foo" + body);
    }

}

81.9. Extracting disruptor information

If needed, information such as buffer size, etc. can be obtained without using JMX in this fashion:

DisruptorEndpoint disruptor = context.getEndpoint("disruptor:xxxx");
int size = disruptor.getBufferSize();

Chapter 82. DNS Component

Available as of Camel version 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

INFO:*Requires SUN JVM* 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:

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

82.1. URI format

The URI scheme for a DNS component is as follows

dns://operation[?options]

This component only supports producers.

82.2. Options

The DNS component has no options.

The DNS endpoint is configured using URI syntax:

dns:dnsType

with the following path and query parameters:

82.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
dnsType	Required The type of the lookup.		DnsType

82.2.2. Query Parameters (1 parameters):

Name	Description	Default	Type
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

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

82.4. Examples

82.4.1. IP lookup

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

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

82.4.2. DNS lookup

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

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

82.4.3. DNS Dig

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

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

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

82.5. Dns Activation Policy

DnsActivationPolicy can be used to dynamically start and stop routes based on dns state.

If you have instances of the same component running in different regions you can configure a route in each region to activate only if dns is pointing to its region.

i.e. You may have an instance in NYC and an instance in SFO. You would configure a service CNAME service.example.com to point to nyc-service.example.com to bring NYC instance up and SFO instance down. When you change the CNAME service.example.com to point to sfo-service.example.com — nyc instance would stop its routes and sfo will bring its routes up. This allows you to switch regions without restarting actual components.

	<bean id="dnsActivationPolicy" class="org.apache.camel.component.dns.policy.DnsActivationPolicy">
		<property name="hostname" value="service.example.com" />
		<property name="resolvesTo" value="nyc-service.example.com" />
		<property name="ttl" value="60000" />
	</bean>

	<route id="routeId" autoStartup="false" routePolicyRef="dnsActivationPolicy">
	</route>

Chapter 83. Docker Component

Available as of Camel version 2.15

Camel component for communicating with Docker.

The Docker Camel component leverages the docker-java via the Docker Remote API.

83.1. URI format

docker://[operation]?[options]

Where operation is the specific action to perform on Docker.

83.2. General Options

The Docker component supports 2 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	To use the shared docker configuration		DockerConfiguration
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Docker endpoint is configured using URI syntax:

docker:operation

with the following path and query parameters:

83.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
operation	Required Which operation to use		DockerOperation

83.2.2. Query Parameters (20 parameters):

Name	Description	Default	Type
email (common)	Email address associated with the user		String
host (common)	Required Docker host	localhost	String
port (common)	Required Docker port	2375	Integer
requestTimeout (common)	Request timeout for response (in seconds)		Integer
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
cmdExecFactory (advanced)	The fully qualified class name of the DockerCmdExecFactory implementation to use	com.github.dockerjava.netty.NettyDockerCmdExecFactory	String
followRedirectFilter (advanced)	Whether to follow redirect filter	false	boolean
loggingFilter (advanced)	Whether to use logging filter	false	boolean
maxPerRouteConnections (advanced)	Maximum route connections	100	Integer
maxTotalConnections (advanced)	Maximum total connections	100	Integer
serverAddress (advanced)	Server address for docker registry.	https://index.docker.io/v1/	String
socket (advanced)	Socket connection mode	true	boolean
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
certPath (security)	Location containing the SSL certificate chain		String
password (security)	Password to authenticate with		String
secure (security)	Use HTTPS communication	false	boolean
tlsVerify (security)	Check TLS	false	boolean
username (security)	User name to authenticate with		String

83.3. Header Strategy

All URI option can be passed as Header properties. Values found in a message header take precedence over URI parameters. A header property takes the form of a URI option prefixed with CamelDocker as shown below

URI Option	Header Property
containerId	CamelDockerContainerId

83.4. Examples

The following example consumes events from Docker:

from("docker://events?host=192.168.59.103&port=2375").to("log:event");

The following example queries Docker for system wide information

from("docker://info?host=192.168.59.103&port=2375").to("log:info");

83.5. Dependencies

To use Docker in your Camel routes you need to add a dependency on camel-docker, which implements the component.

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

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

Chapter 84. Dozer Component

Available as of Camel version 2.15

The dozer: component provides the ability to map between Java beans using the Dozer mapping framework since Camel 2.15.0. Camel also supports the ability to trigger Dozer mappings as a type converter. The primary differences between using a Dozer endpoint and a Dozer converter are:

The ability to manage Dozer mapping configuration on a per-endpoint basis vs. global configuration via the converter registry.
A Dozer endpoint can be configured to marshal/unmarshal input and output data using Camel data formats to support a single, any-to-any transformation endpoint
The Dozer component allows for fine-grained integration and extension of Dozer to support additional functionality (e.g. mapping literal values, using expressions for mappings, etc.).

In order to use the Dozer component, Maven users will need to add the following dependency to their pom.xml:

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

84.1. URI format

The Dozer component only supports producer endpoints.

dozer:endpointId[?options]

Where endpointId is a name used to uniquely identify the Dozer endpoint configuration.

An example Dozer endpoint URI:

from("direct:orderInput").
  to("dozer:transformOrder?mappingFile=orderMapping.xml&targetModel=example.XYZOrder").
  to("direct:orderOutput");

84.2. Options

The Dozer component has no options.

The Dozer endpoint is configured using URI syntax:

dozer:name

with the following path and query parameters:

84.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
name	Required A human readable name of the mapping.		String

84.2.2. Query Parameters (7 parameters):

Name	Description	Default	Type
mappingConfiguration (producer)	The name of a DozerBeanMapperConfiguration bean in the Camel registry which should be used for configuring the Dozer mapping. This is an alternative to the mappingFile option that can be used for fine-grained control over how Dozer is configured. Remember to use a prefix in the value to indicate that the bean is in the Camel registry (e.g. myDozerConfig).		DozerBeanMapper Configuration
mappingFile (producer)	The location of a Dozer configuration file. The file is loaded from the classpath by default, but you can use file:, classpath:, or http: to load the configuration from a specific location.	dozerBeanMapping.xml	String
marshalId (producer)	The id of a dataFormat defined within the Camel Context to use for marshalling the mapping output to a non-Java type.		String
sourceModel (producer)	Fully-qualified class name for the source type used in the mapping. If specified, the input to the mapping is converted to the specified type before being mapped with Dozer.		String
targetModel (producer)	Required Fully-qualified class name for the target type used in the mapping.		String
unmarshalId (producer)	The id of a dataFormat defined within the Camel Context to use for unmarshalling the mapping input from a non-Java type.		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

84.3. Using Data Formats with Dozer

Dozer does not support non-Java sources and targets for mappings, so it cannot, for example, map an XML document to a Java object on its own. Luckily, Camel has extensive support for marshalling between Java and a wide variety of formats using data formats. The Dozer component takes advantage of this support by allowing you to specify that input and output data should be passed through a data format prior to processing via Dozer. You can always do this on your own outside the call to Dozer, but supporting it directly in the Dozer component allows you to use a single endpoints to configure any-to-any transformation within Camel.

As an example, let’s say you wanted to map between an XML data structure and a JSON data structure using the Dozer component. If you had the following data formats defined in a Camel Context:

<dataFormats>
  <json library="Jackson" id="myjson"/>
  <jaxb contextPath="org.example" id="myjaxb"/>
</dataFormats>

You could then configure a Dozer endpoint to unmarshal the input XML using a JAXB data format and marshal the mapping output using Jackson.

<endpoint uri="dozer:xml2json?marshalId=myjson&amp;unmarshalId=myjaxb&amp;targetModel=org.example.Order"/>

84.4. Configuring Dozer

All Dozer endpoints require a Dozer mapping configuration file which defines mappings between source and target objects. The component will default to a location of META-INF/dozerBeanMapping.xml if the mappingFile or mappingConfiguration options are not specified on an endpoint. If you need to supply multiple mapping configuration files for a single endpoint or specify additional configuration options (e.g. event listeners, custom converters, etc.), then you can use an instance of org.apache.camel.converter.dozer.DozerBeanMapperConfiguration.

<bean id="mapper" class="org.apache.camel.converter.dozer.DozerBeanMapperConfiguration">  
  <property name="mappingFiles">
    <list>
      <value>mapping1.xml</value>
      <value>mapping2.xml</value>
    </list>
  </property>
</bean>

84.5. Mapping Extensions

The Dozer component implements a number of extensions to the Dozer mapping framework as custom converters. These converters implement mapping functions that are not supported directly by Dozer itself.

84.5.1. Variable Mappings

Variable mappings allow you to map the value of a variable definition within a Dozer configuration into a target field instead of using the value of a source field. This is equivalent to constant mapping in other mapping frameworks, where can you assign a literal value to a target field. To use a variable mapping, simply define a variable within your mapping configuration and then map from the VariableMapper class into your target field of choice:

<mappings xmlns="http://dozermapper.github.io/schema/bean-mapping"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://dozermapper.github.io/schema/bean-mapping http://dozermapper.github.io/schema/bean-mapping.xsd">
  <configuration>
    <variables>
      <variable name="CUST_ID">ACME-SALES</variable>
    </variables>
  </configuration>
  <mapping>
    <class-a>org.apache.camel.component.dozer.VariableMapper</class-a>
    <class-b>org.example.Order</class-b>
    <field custom-converter-id="_variableMapping" custom-converter-param="${CUST_ID}">
      <a>literal</a>
      <b>custId</b>
    </field>
  </mapping>
</mappings>

84.5.2. Custom Mappings

Custom mappings allow you to define your own logic for how a source field is mapped to a target field. They are similar in function to Dozer customer converters, with two notable differences:

You can have multiple converter methods in a single class with custom mappings.
There is no requirement to implement a Dozer-specific interface with custom mappings.

A custom mapping is declared by using the built-in '_customMapping' converter in your mapping configuration. The parameter to this converter has the following syntax:

[class-name][,method-name]

Method name is optional - the Dozer component will search for a method that matches the input and output types required for a mapping. An example custom mapping and configuration are provided below.

public class CustomMapper {
    // All customer ids must be wrapped in "[ ]"
    public Object mapCustomer(String customerId) {
        return "[" + customerId + "]";
    }
}

<mappings xmlns="http://dozermapper.github.io/schema/bean-mapping"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://dozermapper.github.io/schema/bean-mapping http://dozermapper.github.io/schema/bean-mapping.xsd">
  <mapping>
    <class-a>org.example.A</class-a>
    <class-b>org.example.B</class-b>
    <field custom-converter-id="_customMapping"
        custom-converter-param="org.example.CustomMapper,mapCustomer">
      <a>header.customerNum</a>
      <b>custId</b>
    </field>
  </mapping>
</mappings>

84.5.3. Expression Mappings

Expression mappings allow you to use the powerful language capabilities of Camel to evaluate an expression and assign the result to a target field in a mapping. Any language that Camel supports can be used in an expression mapping. Basic examples of expressions include the ability to map a Camel message header or exchange property to a target field or to concatenate multiple source fields into a target field. The syntax of a mapping expression is:

[language]:[expression]

An example of mapping a message header into a target field:

<mappings xmlns="http://dozermapper.github.io/schema/bean-mapping"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://dozermapper.github.io/schema/bean-mapping http://dozermapper.github.io/schema/bean-mapping.xsd">
  <mapping>
    <class-a>org.apache.camel.component.dozer.ExpressionMapper</class-a>
    <class-b>org.example.B</class-b>
    <field custom-converter-id="_expressionMapping" custom-converter-param="simple:\${header.customerNumber}">
      <a>expression</a>
      <b>custId</b>
    </field>
  </mapping>
</mappings>

Note that any properties within your expression must be escaped with "\" to prevent an error when Dozer attempts to resolve variable values defined using the EL.

Chapter 85. Drill Component

Available as of Camel version 2.19

The drill: component gives you the ability to querying to Apache Drill Cluster

Drill is an Apache open-source SQL query engine for Big Data exploration. Drill is designed from the ground up to support high-performance analysis on the semi-structured and rapidly evolving data coming from modern Big Data applications, while still providing the familiarity and ecosystem of ANSI SQL, the industry-standard query language

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

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

85.1. URI format

drill://host[?options]

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

85.2. Drill Producer

The producer execute query using CamelDrillQuery header and put results into body.

85.3. Options

The Drill component has no options.

The Drill endpoint is configured using URI syntax:

drill:host

with the following path and query parameters:

85.3.1. Path Parameters (1 parameters):

Name	Description	Default	Type
host	Required ZooKeeper host name or IP address. Use local instead of a host name or IP address to connect to the local Drillbit		String

85.3.2. Query Parameters (5 parameters):

Name	Description	Default	Type
clusterId (producer)	Cluster ID https://drill.apache.org/docs/using-the-jdbc-driver/determining-the-cluster-id		String
directory (producer)	Drill directory in ZooKeeper		String
mode (producer)	Connection mode: zk: Zookeeper drillbit: Drillbit direct connection https://drill.apache.org/docs/using-the-jdbc-driver/	ZK	DrillConnectionMode
port (producer)	ZooKeeper port number		Integer
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

85.4. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 86. Dropbox Component

Available as of Camel version 2.14

The dropbox: component allows you to treat Dropbox remote folders as a producer or consumer of messages. Using the Dropbox Java Core API (reference version for this component is 1.7.x), this camel component has the following features:

As a consumer, download files and search files by queries
As a producer, download files, move files between remote directories, delete files/dir, upload files and search files by queries

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

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

86.1. URI format

dropbox://[operation]?[options]

Where operation is the specific action (typically is a CRUD action) to perform on Dropbox remote folder.

86.2. Operations

Operation	Description
`del`	deletes files or directories on Dropbox
`get`	download files from Dropbox
`move`	move files from folders on Dropbox
`put`	upload files on Dropbox
`search`	search files on Dropbox based on string queries

Operations require additional options to work, some are mandatory for the specific operation.

86.3. Options

In order to work with Dropbox API you need to obtain an accessToken and a clientIdentifier.
You can refer to the Dropbox documentation that explains how to get them.

The Dropbox component has no options.

The Dropbox endpoint is configured using URI syntax:

dropbox:operation

with the following path and query parameters:

86.3.1. Path Parameters (1 parameters):

Name	Description	Default	Type
operation	Required The specific action (typically is a CRUD action) to perform on Dropbox remote folder.		DropboxOperation

86.3.2. Query Parameters (12 parameters):

Name	Description	Default	Type
accessToken (common)	Required The access token to make API requests for a specific Dropbox user		String
client (common)	To use an existing DbxClient instance as DropBox client.		DbxClientV2
clientIdentifier (common)	Name of the app registered to make API requests		String
localPath (common)	Optional folder or file to upload on Dropbox from the local filesystem. If this option has not been configured then the message body is used as the content to upload.		String
newRemotePath (common)	Destination file or folder		String
query (common)	A space-separated list of sub-strings to search for. A file matches only if it contains all the sub-strings. If this option is not set, all files will be matched.		String
remotePath (common)	Original file or folder to move		String
uploadMode (common)	Which mode to upload. in case of add the new file will be renamed if a file with the same name already exists on dropbox. in case of force if a file with the same name already exists on dropbox, this will be overwritten.		DropboxUploadMode
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

86.4. Del operation

Delete files on Dropbox.

Works only as Camel producer.

Below are listed the options for this operation:

Property	Mandatory	Description
`remotePath`	`true`	Folder or file to delete on Dropbox

86.4.1. Samples

from("direct:start")
  .to("dropbox://del?accessToken=XXX&clientIdentifier=XXX&remotePath=/root/folder1")
  .to("mock:result");

from("direct:start")
  .to("dropbox://del?accessToken=XXX&clientIdentifier=XXX&remotePath=/root/folder1/file1.tar.gz")
  .to("mock:result");

86.4.2. Result Message Headers

The following headers are set on message result:

Property	Value
`DELETED_PATH`	name of the path deleted on dropbox

86.4.3. Result Message Body

The following objects are set on message body result:

Object type	Description
`String`	name of the path deleted on dropbox

86.5. Get (download) operation

Download files from Dropbox.

Works as Camel producer or Camel consumer.

Below are listed the options for this operation:

Property	Mandatory	Description
`remotePath`	`true`	Folder or file to download from Dropbox

86.5.1. Samples

from("direct:start")
  .to("dropbox://get?accessToken=XXX&clientIdentifier=XXX&remotePath=/root/folder1/file1.tar.gz")
  .to("file:///home/kermit/?fileName=file1.tar.gz");

from("direct:start")
  .to("dropbox://get?accessToken=XXX&clientIdentifier=XXX&remotePath=/root/folder1")
  .to("mock:result");

from("dropbox://get?accessToken=XXX&clientIdentifier=XXX&remotePath=/root/folder1")
  .to("file:///home/kermit/");

86.5.2. Result Message Headers

The following headers are set on message result:

Property	Value
`DOWNLOADED_FILE`	in case of single file download, path of the remote file downloaded
`DOWNLOADED_FILES`	in case of multiple files download, path of the remote files downloaded

86.5.3. Result Message Body

The following objects are set on message body result:

Object type	Description
`ByteArrayOutputStream`	in case of single file download, stream representing the file downloaded
`Map<String, ByteArrayOutputStream>`	in case of multiple files download, a map with as key the path of the remote file downloaded and as value the stream representing the file downloaded

86.6. Move operation

Move files on Dropbox between one folder to another.

Works only as Camel producer.

Below are listed the options for this operation:

Property	Mandatory	Description
`remotePath`	`true`	Original file or folder to move
`newRemotePath`	`true`	Destination file or folder

86.6.1. Samples

from("direct:start")
  .to("dropbox://move?accessToken=XXX&clientIdentifier=XXX&remotePath=/root/folder1&newRemotePath=/root/folder2")
  .to("mock:result");

86.6.2. Result Message Headers

The following headers are set on message result:

Property	Value
`MOVED_PATH`	name of the path moved on dropbox

86.6.3. Result Message Body

The following objects are set on message body result:

Object type	Description
`String`	name of the path moved on dropbox

86.7. Put (upload) operation

Upload files on Dropbox.

Works as Camel producer.

Below are listed the options for this operation:

Property Mandatory Description

uploadMode

true

add or force this option specifies how a file should be saved on dropbox: in case of "add" the new file will be renamed if a file with the same name already exists on dropbox. In case of "force" if a file with the same name already exists on dropbox, this will be overwritten.

localPath

false

Folder or file to upload on Dropbox from the local filesystem. If this option has been configured then it takes precedence over uploading as a single file with content from the Camel message body (message body is converted into a byte array).

remotePath

false

Folder destination on Dropbox. If the property is not set, the component will upload the file on a remote path equal to the local path. With Windows or without an absolute localPath you may run into an exception like the following:

Caused by: java.lang.IllegalArgumentException: 'path': bad path: must start with "/": "C:/My/File"
OR
Caused by: java.lang.IllegalArgumentException: 'path': bad path: must start with "/": "MyFile"

86.7.1. Samples

from("direct:start").to("dropbox://put?accessToken=XXX&clientIdentifier=XXX&uploadMode=add&localPath=/root/folder1")
  .to("mock:result");

from("direct:start").to("dropbox://put?accessToken=XXX&clientIdentifier=XXX&uploadMode=add&localPath=/root/folder1&remotePath=/root/folder2")
  .to("mock:result");

And to upload a single file with content from the message body

from("direct:start")
   .setHeader(DropboxConstants.HEADER_PUT_FILE_NAME, constant("myfile.txt"))
   .to("dropbox://put?accessToken=XXX&clientIdentifier=XXX&uploadMode=add&remotePath=/root/folder2")
   .to("mock:result");

The name of the file can be provided in the header DropboxConstants.HEADER_PUT_FILE_NAME or Exchange.FILE_NAME in that order of precedence. If no header has been provided then the message id (uuid) is used as the file name.

86.7.2. Result Message Headers

The following headers are set on message result:

Property	Value
`UPLOADED_FILE`	in case of single file upload, path of the remote path uploaded
`UPLOADED_FILES`	in case of multiple files upload, string with the remote paths uploaded

86.7.3. Result Message Body

The following objects are set on message body result:

Object type	Description
`String`	in case of single file upload, result of the upload operation, OK or KO
`Map<String, DropboxResultCode>`	in case of multiple files upload, a map with as key the path of the remote file uploaded and as value the result of the upload operation, OK or KO

86.8. Search operation

Search inside a remote Dropbox folder including its sub directories.

Works as Camel producer and as Camel consumer.

Below are listed the options for this operation:

Property	Mandatory	Description
`remotePath`	`true`	Folder on Dropbox where to search in.
`query`	`true`	A space-separated list of sub-strings to search for. A file matches only if it contains all the sub-strings. If this option is not set, all files will be matched. The query is required to be provided in either the endpoint configuration or as a header `CamelDropboxQuery` on the Camel message.

86.8.1. Samples

from("dropbox://search?accessToken=XXX&clientIdentifier=XXX&remotePath=/XXX&query=XXX")
  .to("mock:result");

from("direct:start")
  .setHeader("CamelDropboxQuery", constant("XXX"))
  .to("dropbox://search?accessToken=XXX&clientIdentifier=XXX&remotePath=/XXX")
  .to("mock:result");

86.8.2. Result Message Headers

The following headers are set on message result:

Property	Value
`FOUNDED_FILES`	list of file path founded

86.8.3. Result Message Body

The following objects are set on message body result:

Object type	Description
`List<DbxEntry>`	list of file path founded. For more information on this object refer to Dropbox documentation,

Chapter 87. Ehcache Component

Available as of Camel version 2.18

The ehcache component enables you to perform caching operations using Ehcache 3 as the Cache Implementation.

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.

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

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

87.1. URI format

ehcache://cacheName[?options]

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

87.2. Options

The Ehcache component supports 7 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	Sets the global component configuration		EhcacheConfiguration
cacheManager (common)	The cache manager		CacheManager
cacheManager Configuration (common)	The cache manager configuration		Configuration
cacheConfiguration (common)	The default cache configuration to be used to create caches.		CacheConfiguration<?,?>
cachesConfigurations (common)	A map of caches configurations to be used to create caches.		Map
cacheConfigurationUri (common)	URI pointing to the Ehcache XML configuration file’s location		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Ehcache endpoint is configured using URI syntax:

ehcache:cacheName

with the following path and query parameters:

87.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cacheName	Required the cache name		String

87.2.2. Query Parameters (17 parameters):

Name	Description	Default	Type
cacheManager (common)	The cache manager		CacheManager
cacheManagerConfiguration (common)	The cache manager configuration		Configuration
configurationUri (common)	URI pointing to the Ehcache XML configuration file’s location		String
createCacheIfNotExist (common)	Configure if a cache need to be created if it does exist or can’t be pre-configured.	true	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
eventFiring (consumer)	Set the the delivery mode (synchronous, asynchronous)	ASYNCHRONOUS	EventFiring
eventOrdering (consumer)	Set the the delivery mode (ordered, unordered)	ORDERED	EventOrdering
eventTypes (consumer)	Set the type of events to listen for	EVICTED,EXPIRED,REMOVED,CREATED,UPDATED	Set
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
action (producer)	To configure the default cache action. If an action is set in the message header, then the operation from the header takes precedence.		String
key (producer)	To configure the default action key. If a key is set in the message header, then the key from the header takes precedence.		Object
configuration (advanced)	The default cache configuration to be used to create caches.		CacheConfiguration<?,?>
configurations (advanced)	A map of cache configuration to be used to create caches.		Map
keyType (advanced)	The cache key type, default java.lang.Object	java.lang.Object	String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
valueType (advanced)	The cache value type, default java.lang.Object	java.lang.Object	String

87.2.3. Message Headers Camel

Header	Type	Description
CamelEhcacheAction	`String`	The operation to be perfomed on the cache, valid options are: * CLEAR * PUT * PUT_ALL * PUT_IF_ABSENT * GET * GET_ALL * REMOVE * REMOVE_ALL * REPLACE
CamelEhcacheActionHasResult	Boolean	Set to true if the action has a result
CamelEhcacheActionSucceeded	`Boolean`	Set to true if the actionsuccedded
CamelEhcacheKey	Object	The cache key used for an action
CamelEhcacheKeys	Set<Object>	A list of keys, used in * PUT_ALL * GET_ALL * REMOVE_ALL
CamelEhcacheValue	Object	The value to put in the cache or the result of an operation
CamelEhcacheOldValue	Object	The old value associated to a key for actions like PUT_IF_ABSENT or the Object used for comparison for actions like REPLACE
CamelEhcacheEventType	EventType	The type of event received

87.3. Ehcache based idempotent repository example:

CacheManager manager = CacheManagerBuilder.newCacheManager(new XmlConfiguration("ehcache.xml"));
EhcacheIdempotentRepository repo = new EhcacheIdempotentRepository(manager, "idempotent-cache");

from("direct:in")
    .idempotentConsumer(header("messageId"), idempotentRepo)
    .to("mock:out");

87.4. Ehcache based aggregation repository example:

public class EhcacheAggregationRepositoryRoutesTest extends CamelTestSupport {
    private static final String ENDPOINT_MOCK = "mock:result";
    private static final String ENDPOINT_DIRECT = "direct:one";
    private static final int[] VALUES = generateRandomArrayOfInt(10, 0, 30);
    private static final int SUM = IntStream.of(VALUES).reduce(0, (a, b) -> a + b);
    private static final String CORRELATOR = "CORRELATOR";

    @EndpointInject(uri = ENDPOINT_MOCK)
    private MockEndpoint mock;

    @Produce(uri = ENDPOINT_DIRECT)
    private ProducerTemplate producer;

    @Test
    public void checkAggregationFromOneRoute() throws Exception {
        mock.expectedMessageCount(VALUES.length);
        mock.expectedBodiesReceived(SUM);

        IntStream.of(VALUES).forEach(
            i -> producer.sendBodyAndHeader(i, CORRELATOR, CORRELATOR)
        );

        mock.assertIsSatisfied();
    }

    private Exchange aggregate(Exchange oldExchange, Exchange newExchange) {
        if (oldExchange == null) {
            return newExchange;
        } else {
            Integer n = newExchange.getIn().getBody(Integer.class);
            Integer o = oldExchange.getIn().getBody(Integer.class);
            Integer v = (o == null ? 0 : o) + (n == null ? 0 : n);

            oldExchange.getIn().setBody(v, Integer.class);

            return oldExchange;
        }
    }

    @Override
    protected RoutesBuilder createRouteBuilder() throws Exception {
        return new RouteBuilder() {
            @Override
            public void configure() throws Exception {
                from(ENDPOINT_DIRECT)
                    .routeId("AggregatingRouteOne")
                    .aggregate(header(CORRELATOR))
                    .aggregationRepository(createAggregateRepository())
                    .aggregationStrategy(EhcacheAggregationRepositoryRoutesTest.this::aggregate)
                    .completionSize(VALUES.length)
                        .to("log:org.apache.camel.component.ehcache.processor.aggregate.level=INFO&showAll=true&mulltiline=true")
                        .to(ENDPOINT_MOCK);
            }
        };
    }

    protected EhcacheAggregationRepository createAggregateRepository() throws Exception {
        CacheManager cacheManager = CacheManagerBuilder.newCacheManager(new XmlConfiguration("ehcache.xml"));
        cacheManager.init();

        EhcacheAggregationRepository repository = new EhcacheAggregationRepository();
        repository.setCacheManager(cacheManager);
        repository.setCacheName("aggregate");

        return repository;
    }
}

Chapter 88. EJB Component

Available as of Camel version 2.4

The ejb: component binds EJBs to Camel message exchanges.

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

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

88.1. URI format

ejb:ejbName[?options]

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

88.2. Options

The EJB component supports 3 options which are listed below.

Name	Description	Default	Type
context (producer)	The Context to use for looking up the EJBs		Context
properties (producer)	Properties for creating javax.naming.Context if a context has not been configured.		Properties
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The EJB endpoint is configured using URI syntax:

ejb:beanName

with the following path and query parameters:

88.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
beanName	Required Sets the name of the bean to invoke		String

88.2.2. Query Parameters (5 parameters):

Name	Description	Default	Type
method (producer)	Sets the name of the method to invoke on the bean		String
cache (advanced)	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.	false	boolean
multiParameterArray (advanced)	Deprecated How to treat the parameters which are passed from the message body.true means the message body should be an array of parameters.. Deprecation note: This option is used internally by Camel, and is not intended for end users to use. Deprecation note: This option is used internally by Camel, and is not intended for end users to use.	false	boolean
parameters (advanced)	Used for configuring additional properties on the bean		Map
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

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

88.4. Examples

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

GreaterLocal.java

public interface GreaterLocal {

    String hello(String name);

    String bye(String name);

}

And the implementation

GreaterImpl.java

@Stateless
public class GreaterImpl implements GreaterLocal {

    public String hello(String name) {
        return "Hello " + name;
    }

    public String bye(String name) {
        return "Bye " + name;
    }

}

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

@Override
protected CamelContext createCamelContext() throws Exception {
    CamelContext answer = new DefaultCamelContext();

    // enlist EJB component using the JndiContext
    EjbComponent ejb = answer.getComponent("ejb", EjbComponent.class);
    ejb.setContext(createEjbContext());

    return answer;
}

private static Context createEjbContext() throws NamingException {
    // here we need to define our context factory to use OpenEJB for our testing
    Properties properties = new Properties();
    properties.setProperty(Context.INITIAL_CONTEXT_FACTORY, "org.apache.openejb.client.LocalInitialContextFactory");

    return new InitialContext(properties);
}

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

from("direct:start")
    // invoke the greeter EJB using the local interface and invoke the hello method
    .to("ejb:GreaterImplLocal?method=hello")
    .to("mock:result");

In a real application server

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.

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

<!-- setup Camel EJB component -->
<bean id="ejb" class="org.apache.camel.component.ejb.EjbComponent">
    <property name="properties" ref="jndiProperties"/>
</bean>

<!-- use OpenEJB context factory -->
<p:properties id="jndiProperties">
    <prop key="java.naming.factory.initial">org.apache.openejb.client.LocalInitialContextFactory</prop>
</p:properties>

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

<camelContext xmlns="http://camel.apache.org/schema/spring">
    <route>
        <from uri="direct:start"/>
        <to uri="ejb:GreaterImplLocal?method=hello"/>
        <to uri="mock:result"/>
    </route>
</camelContext>

88.5. See Also

Configuring Camel
Component
Endpoint
Getting Started
Bean
Bean Binding
Bean Integration

Chapter 89. Elasticsearch Component (deprecated)

Available as of Camel version 2.11

The ElasticSearch component allows you to interface with an ElasticSearch server.

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

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

89.1. URI format

elasticsearch://clusterName[?options]

89.2. Endpoint Options

The Elasticsearch component supports 2 options which are listed below.

Name	Description	Default	Type
client (advanced)	To use an existing configured Elasticsearch client, instead of creating a client per endpoint.		Client
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Elasticsearch endpoint is configured using URI syntax:

elasticsearch:clusterName

with the following path and query parameters:

89.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
clusterName	Required Name of cluster or use local for local mode		String

89.2.2. Query Parameters (11 parameters):

Name	Description	Default	Type
clientTransportSniff (producer)	Is the client allowed to sniff the rest of the cluster or not (default true). This setting map to the client.transport.sniff setting.	true	Boolean
consistencyLevel (producer)	The write consistency level to use with INDEX and BULK operations (can be any of ONE, QUORUM, ALL or DEFAULT)	DEFAULT	WriteConsistencyLevel
data (producer)	Is the node going to be allowed to allocate data (shards) to it or not. This setting map to the node.data setting.		Boolean
indexName (producer)	The name of the index to act against		String
indexType (producer)	The type of the index to act against		String
ip (producer)	The TransportClient remote host ip to use		String
operation (producer)	What operation to perform		String
pathHome (producer)	The path.home property of ElasticSearch configuration. You need to provide a valid path, otherwise the default, $user.home/.elasticsearch, will be used.	${user.home}/.elasticsearch	String
port (producer)	The TransportClient remote port to use (defaults to 9300)	9300	int
transportAddresses (producer)	Comma separated list with ip:port formatted remote transport addresses to use. The ip and port options must be left blank for transportAddresses to be considered instead.		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

89.3. Local testing

If you want to run against a local (in JVM/classloader) ElasticSearch server, just set the clusterName value in the URI to "local". See the client guide for more details.

89.4. Message Operations

The following ElasticSearch operations are currently supported. Simply set an endpoint URI option or exchange header with a key of "operation" and a value set to one of the following. Some operations also require other parameters or the message body to be set.

operation	message body	description
INDEX	Map, String, byte[] or XContentBuilder content to index	adds content to an index and returns the content’s indexId in the body. Camel 2.15, you can set the indexId by setting the message header with the key "indexId".
GET_BY_ID	index id of content to retrieve	retrieves the specified index and returns a GetResult object in the body
DELETE	index id of content to delete	deletes the specified indexId and returns a DeleteResult object in the body
BULK_INDEX	a List or Collection of any type that is already accepted (XContentBuilder, Map, byte[], String)	Camel 2.14,adds content to an index and return a List of the id of the successfully indexed documents in the body
BULK	a List or Collection of any type that is already accepted (XContentBuilder, Map, byte[], String)	Camel 2.15: Adds content to an index and returns the BulkResponse object in the body
SEARCH	Map or SearchRequest Object	Camel 2.15: search the content with the map of query string
MULTIGET	List of MultigetRequest.Item object	Camel 2.17: retrieves the specified indexes, types etc. in MultigetRequest and returns a MultigetResponse object in the body
MULTISEARCH	List of SearchRequest object	Camel 2.17: search for parameters specified in MultiSearchRequest and returns a MultiSearchResponse object in the body
EXISTS	Index name as header	Camel 2.17: Returns a Boolean object in the body
UPDATE	Map, String, byte[] or XContentBuilder content to update	Camel 2.17: Updates content to an index and returns the content’s indexId in the body.

89.5. Index Example

Below is a simple INDEX example

from("direct:index")
.to("elasticsearch://local?operation=INDEX&indexName=twitter&indexType=tweet");

<route>
    <from uri="direct:index" />
    <to uri="elasticsearch://local?operation=INDEX&indexName=twitter&indexType=tweet"/>
</route>

A client would simply need to pass a body message containing a Map to the route. The result body contains the indexId created.

Map<String, String> map = new HashMap<String, String>();
map.put("content", "test");
String indexId = template.requestBody("direct:index", map, String.class);

89.6. For more information, see these resources

ElasticSearch Main Site

ElasticSearch Java API

89.7. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 90. Elasticsearch5 Component (deprecated)

Available as of Camel version 2.19

The ElasticSearch component allows you to interface with an ElasticSearch 5.x API.

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

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

90.1. URI format

elasticsearch5://clusterName[?options]

90.2. Endpoint Options

The Elasticsearch5 component supports 2 options which are listed below.

Name	Description	Default	Type
client (advanced)	To use an existing configured Elasticsearch client, instead of creating a client per endpoint. This allow to customize the client with specific settings.		TransportClient
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Elasticsearch5 endpoint is configured using URI syntax:

elasticsearch5:clusterName

with the following path and query parameters:

90.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
clusterName	Required Name of the cluster		String

90.2.2. Query Parameters (16 parameters):

Name	Description	Default	Type
clientTransportSniff (producer)	Is the client allowed to sniff the rest of the cluster or not. This setting map to the client.transport.sniff setting.	false	boolean
indexName (producer)	The name of the index to act against		String
indexType (producer)	The type of the index to act against		String
ip (producer)	The TransportClient remote host ip to use		String
operation (producer)	What operation to perform		ElasticsearchOperation
pingSchedule (producer)	The time(in unit) the client ping the cluster.	5s	String
pingTimeout (producer)	The time(in unit) to wait for a ping response from a node too return.	5s	String
port (producer)	The TransportClient remote port to use (defaults to 9300)	9300	int
tcpCompress (producer)	true if compression (LZF) enable between all nodes.	false	boolean
tcpConnectTimeout (producer)	The time( in unit) to wait for connection timeout.	30s	String
transportAddresses (producer)	Comma separated list with ip:port formatted remote transport addresses to use. The ip and port options must be left blank for transportAddresses to be considered instead.		String
waitForActiveShards (producer)	Index creation waits for the write consistency number of shards to be available	1	int
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
enableSSL (security)	Enable SSL. Require XPack client jar on the classpath	false	boolean
password (authentication)	Password for authenticate against the cluster. Require XPack client jar on the classpath		String
user (authentication)	User for authenticate against the cluster. Requires transport_client role for accessing the cluster. Require XPack client jar on the classpath		String

90.3. Message Operations

The following ElasticSearch operations are currently supported. Simply set an endpoint URI option or exchange header with a key of "operation" and a value set to one of the following. Some operations also require other parameters or the message body to be set.

operation	message body	description
INDEX	Map, String, byte[] or XContentBuilder content to index	Adds content to an index and returns the content’s indexId in the body. You can set the indexId by setting the message header with the key "indexId".
GET_BY_ID	index id of content to retrieve	Retrieves the specified index and returns a GetResult object in the body
DELETE	index name and type of content to delete	Deletes the specified indexName and indexType and returns a DeleteResponse object in the body
DELETE_INDEX	index name of content to delete	Deletes the specified indexName and returns a DeleteIndexResponse object in the body
BULK_INDEX	a List or Collection of any type that is already accepted (XContentBuilder, Map, byte[], String)	Adds content to an index and return a List of the id of the successfully indexed documents in the body
BULK	a List or Collection of any type that is already accepted (XContentBuilder, Map, byte[], String)	Adds content to an index and returns the BulkResponse object in the body
SEARCH	Map, String or SearchRequest Object	Search the content with the map of query string
MULTIGET	List of MultigetRequest.Item object	Retrieves the specified indexes, types etc. in MultigetRequest and returns a MultigetResponse object in the body
MULTISEARCH	List of SearchRequest object	Search for parameters specified in MultiSearchRequest and returns a MultiSearchResponse object in the body
EXISTS	Index name as header	Checks the index exists or not and returns a Boolean flag in the body
UPDATE	Map, String, byte[] or XContentBuilder content to update	Updates content to an index and returns the content’s indexId in the body.

90.4. Index Example

Below is a simple INDEX example

from("direct:index")
.to("elasticsearch5://elasticsearch?operation=INDEX&indexName=twitter&indexType=tweet");

<route>
    <from uri="direct:index" />
    <to uri="elasticsearch5://elasticsearch?operation=INDEX&indexName=twitter&indexType=tweet"/>
</route>

A client would simply need to pass a body message containing a Map to the route. The result body contains the indexId created.

Map<String, String> map = new HashMap<String, String>();
map.put("content", "test");
String indexId = template.requestBody("direct:index", map, String.class);

90.5. For more information, see these resources

Elastic Main Site

ElasticSearch Java API

90.6. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 91. Elastichsearch Rest Component

Available as of Camel version 2.21

The ElasticSearch component allows you to interface with an ElasticSearch 6.x API using the REST Client library.

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

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

91.1. URI format

elasticsearch-rest://clusterName[?options]

91.2. Endpoint Options

The Elastichsearch Rest component supports 12 options which are listed below.

Name	Description	Default	Type
client (advanced)	To use an existing configured Elasticsearch client, instead of creating a client per endpoint. This allow to customize the client with specific settings.		RestClient
hostAddresses (advanced)	Comma separated list with ip:port formatted remote transport addresses to use. The ip and port options must be left blank for hostAddresses to be considered instead.		String
socketTimeout (advanced)	The timeout in ms to wait before the socket will timeout.	30000	int
connectionTimeout (advanced)	The time in ms to wait before connection will timeout.	30000	int
user (advance)	Basic authenticate user		String
password (producer)	Password for authenticate		String
enableSSL (advanced)	Enable SSL	false	Boolean
maxRetryTimeout (advanced)	The time in ms before retry	30000	int
enableSniffer (advanced)	Enable automatically discover nodes from a running Elasticsearch cluster	false	Boolean
snifferInterval (advanced)	The interval between consecutive ordinary sniff executions in milliseconds. Will be honoured when sniffOnFailure is disabled or when there are no failures between consecutive sniff executions	300000	int
sniffAfterFailureDelay (advanced)	The delay of a sniff execution scheduled after a failure (in milliseconds)	60000	int
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Elastichsearch Rest endpoint is configured using URI syntax:

elasticsearch-rest:clusterName

with the following path and query parameters:

91.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
clusterName	Required Name of the cluster		String

91.2.2. Query Parameters (11 parameters):

Name	Description	Default	Type
connectionTimeout (producer)	The time in ms to wait before connection will timeout.	30000	int
disconnect (producer)	Disconnect after it finish calling the producer	false	boolean
enableSSL (producer)	Enable SSL	false	boolean
hostAddresses (producer)	Required Comma separated list with ip:port formatted remote transport addresses to use. The ip and port options must be left blank for hostAddresses to be considered instead.		String
indexName (producer)	The name of the index to act against		String
indexType (producer)	The type of the index to act against		String
maxRetryTimeout (producer)	The time in ms before retry	30000	int
operation (producer)	What operation to perform		ElasticsearchOperation
socketTimeout (producer)	The timeout in ms to wait before the socket will timeout.	30000	int
waitForActiveShards (producer)	Index creation waits for the write consistency number of shards to be available	1	int
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

91.3. Message Operations

The following ElasticSearch operations are currently supported. Simply set an endpoint URI option or exchange header with a key of "operation" and a value set to one of the following. Some operations also require other parameters or the message body to be set.

operation	message body	description
Index	Map, String, byte[], XContentBuilder or IndexRequest content to index	Adds content to an index and returns the content’s indexId in the body. You can set the indexId by setting the message header with the key "indexId".
GetById	String or GetRequest index id of content to retrieve	Retrieves the specified index and returns a GetResult object in the body
Delete	String or DeleteRequest index name and type of content to delete	Deletes the specified indexName and indexType and returns a DeleteResponse object in the body
DeleteIndex	String or DeleteRequest index name of the index to delete	Deletes the specified indexName and returns a status code the body
BulkIndex	a List, BulkRequest, or Collection of any type that is already accepted (XContentBuilder, Map, byte[], String)	Adds content to an index and return a List of the id of the successfully indexed documents in the body
Bulk	a List, BulkRequest, or Collection of any type that is already accepted (XContentBuilder, Map, byte[], String)	Adds content to an index and returns the BulkItemResponse[] object in the body
Search	Map, String or SearchRequest	Search the content with the map of query string
Exists	Index name(indexName) as header	Checks the index exists or not and returns a Boolean flag in the body
Update	Map, UpdateRequest, String, byte[] or XContentBuilder content to update	Updates content to an index and returns the content’s indexId in the body.
Ping	None	Pings the remote Elasticsearch cluster and returns true if the ping succeeded, false otherwise

91.4. Configure the component and enable basic authentication

To use the Elasticsearch component is has to be configured with a minimum configuration.

ElasticsearchComponent elasticsearchComponent = new ElasticsearchComponent();
elasticsearchComponent.setHostAddresses("myelkhost:9200");
camelContext.addComponent("elasticsearch-rest", elasticsearchComponent);

For basic authentication with elasticsearch or using reverse http proxy in front of the elasticsearch cluster, simply setup basic authentication and SSL on the component like the example below

ElasticsearchComponent elasticsearchComponent = new ElasticsearchComponent();
elasticsearchComponent.setHostAddresses("myelkhost:9200");
elasticsearchComponent.setUser("elkuser");
elasticsearchComponent.setPassword("secure!!");
elasticsearchComponent.setEnableSSL(true);

camelContext.addComponent("elasticsearch-rest", elasticsearchComponent);

91.5. Index Example

Below is a simple INDEX example

from("direct:index")
  .to("elasticsearch-rest://elasticsearch?operation=Index&indexName=twitter&indexType=tweet");

<route>
    <from uri="direct:index" />
    <to uri="elasticsearch-rest://elasticsearch?operation=Index&indexName=twitter&indexType=tweet"/>
</route>

A client would simply need to pass a body message containing a Map to the route. The result body contains the indexId created.

Map<String, String> map = new HashMap<String, String>();
map.put("content", "test");
String indexId = template.requestBody("direct:index", map, String.class);

91.6. Search Example

Searching on specific field(s) and value use the Operation ´Search´. Pass in the query JSON String or the Map

from("direct:search")
  .to("elasticsearch-rest://elasticsearch?operation=Search&indexName=twitter&indexType=tweet");

<route>
    <from uri="direct:search" />
    <to uri="eelasticsearch-rest://elasticsearch?operation=Search&indexName=twitter&indexType=tweet"/>
</route>

String query = "{\"query\":{\"match\":{\"content\":\"new release of ApacheCamel\"}}}";
SearchHits response = template.requestBody("direct:search", query, SearchHits.class);

Search on specific field(s) using Map.

Map<String, Object> actualQuery = new HashMap<>();
actualQuery.put("content", "new release of ApacheCamel");

Map<String, Object> match = new HashMap<>();
match.put("match", actualQuery);

Map<String, Object> query = new HashMap<>();
query.put("query", match);
SearchHits response = template.requestBody("direct:search", query, SearchHits.class);

Chapter 92. ElSQL Component

Available as of Camel version 2.16

The elsql: component is an extension to the existing SQL Component that uses ElSql to define the SQL queries.

This component uses spring-jdbc behind the scenes for the actual SQL handling.

This component can be used as a Transactional Client.

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

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

The SQL component uses the following endpoint URI notation:

sql:elSqlName:resourceUri[?options]

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

The parameters to the SQL queries are named parameters in the elsql mapping files, and maps to corresponding keys from the Camel message, in the given precedence:

Camel 2.16.1: from message body if Simple expression.
from message body if its a `java.util.Map`3. from message headers

If a named parameter cannot be resolved, then an exception is thrown.

92.1. Options

The ElSQL component supports 5 options which are listed below.

Name	Description	Default	Type
databaseVendor (common)	To use a vendor specific com.opengamma.elsql.ElSqlConfig		ElSqlDatabaseVendor
dataSource (common)	Sets the DataSource to use to communicate with the database.		DataSource
elSqlConfig (advanced)	To use a specific configured ElSqlConfig. It may be better to use the databaseVendor option instead.		ElSqlConfig
resourceUri (common)	The resource file which contains the elsql SQL statements to use. You can specify multiple resources separated by comma. The resources are loaded on the classpath by default, you can prefix with file: to load from file system. Notice you can set this option on the component and then you do not have to configure this on the endpoint.		String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The ElSQL endpoint is configured using URI syntax:

elsql:elsqlName:resourceUri

with the following path and query parameters:

92.1.1. Path Parameters (2 parameters):

Name	Description	Default	Type
elsqlName	Required The name of the elsql to use (is NAMED in the elsql file)		String
resourceUri	The resource file which contains the elsql SQL statements to use. You can specify multiple resources separated by comma. The resources are loaded on the classpath by default, you can prefix with file: to load from file system. Notice you can set this option on the component and then you do not have to configure this on the endpoint.		String

92.1.2. Query Parameters (47 parameters):

Name	Description	Default	Type
allowNamedParameters (common)	Whether to allow using named parameters in the queries.	true	boolean
databaseVendor (common)	To use a vendor specific com.opengamma.elsql.ElSqlConfig		ElSqlDatabaseVendor
dataSource (common)	Sets the DataSource to use to communicate with the database.		DataSource
dataSourceRef (common)	Deprecated Sets the reference to a DataSource to lookup from the registry, to use for communicating with the database.		String
outputClass (common)	Specify the full package and class name to use as conversion when outputType=SelectOne.		String
outputHeader (common)	Store the query result in a header instead of the message body. By default, outputHeader == null and the query result is stored in the message body, any existing content in the message body is discarded. If outputHeader is set, the value is used as the name of the header to store the query result and the original message body is preserved.		String
outputType (common)	Make the output of consumer or producer to SelectList as List of Map, or SelectOne as single Java object in the following way:a) If the query has only single column, then that JDBC Column object is returned. (such as SELECT COUNT( ) FROM PROJECT will return a Long object.b) If the query has more than one column, then it will return a Map of that result.c) If the outputClass is set, then it will convert the query result into an Java bean object by calling all the setters that match the column names.It will assume your class has a default constructor to create instance with.d) If the query resulted in more than one rows, it throws an non-unique result exception.StreamList streams the result of the query using an Iterator. This can be used with the Splitter EIP in streaming mode to process the ResultSet in streaming fashion.	SelectList	SqlOutputType
separator (common)	The separator to use when parameter values is taken from message body (if the body is a String type), to be inserted at placeholders.Notice if you use named parameters, then a Map type is used instead. The default value is comma	,	char
breakBatchOnConsumeFail (consumer)	Sets whether to break batch if onConsume failed.	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
expectedUpdateCount (consumer)	Sets an expected update count to validate when using onConsume.	-1	int
maxMessagesPerPoll (consumer)	Sets the maximum number of messages to poll		int
onConsume (consumer)	After processing each row then this query can be executed, if the Exchange was processed successfully, for example to mark the row as processed. The query can have parameter.		String
onConsumeBatchComplete (consumer)	After processing the entire batch, this query can be executed to bulk update rows etc. The query cannot have parameters.		String
onConsumeFailed (consumer)	After processing each row then this query can be executed, if the Exchange failed, for example to mark the row as failed. The query can have parameter.		String
routeEmptyResultSet (consumer)	Sets whether empty resultset should be allowed to be sent to the next hop. Defaults to false. So the empty resultset will be filtered out.	false	boolean
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
transacted (consumer)	Enables or disables transaction. If enabled then if processing an exchange failed then the consumerbreak out processing any further exchanges to cause a rollback eager.	false	boolean
useIterator (consumer)	Sets how resultset should be delivered to route. Indicates delivery as either a list or individual object. defaults to true.	true	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
processingStrategy (consumer)	Allows to plugin to use a custom org.apache.camel.component.sql.SqlProcessingStrategy to execute queries when the consumer has processed the rows/batch.		SqlProcessingStrategy
batch (producer)	Enables or disables batch mode	false	boolean
noop (producer)	If set, will ignore the results of the SQL query and use the existing IN message as the OUT message for the continuation of processing	false	boolean
useMessageBodyForSql (producer)	Whether to use the message body as the SQL and then headers for parameters. If this option is enabled then the SQL in the uri is not used.	false	boolean
alwaysPopulateStatement (producer)	If enabled then the populateStatement method from org.apache.camel.component.sql.SqlPrepareStatementStrategy is always invoked, also if there is no expected parameters to be prepared. When this is false then the populateStatement is only invoked if there is 1 or more expected parameters to be set; for example this avoids reading the message body/headers for SQL queries with no parameters.	false	boolean
parametersCount (producer)	If set greater than zero, then Camel will use this count value of parameters to replace instead of querying via JDBC metadata API. This is useful if the JDBC vendor could not return correct parameters count, then user may override instead.		int
elSqlConfig (advanced)	To use a specific configured ElSqlConfig. It may be better to use the databaseVendor option instead.		ElSqlConfig
placeholder (advanced)	Specifies a character that will be replaced to in SQL query. Notice, that it is simple String.replaceAll() operation and no SQL parsing is involved (quoted strings will also change).	#	String
prepareStatementStrategy (advanced)	Allows to plugin to use a custom org.apache.camel.component.sql.SqlPrepareStatementStrategy to control preparation of the query and prepared statement.		SqlPrepareStatement Strategy
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
templateOptions (advanced)	Configures the Spring JdbcTemplate with the key/values from the Map		Map
usePlaceholder (advanced)	Sets whether to use placeholder and replace all placeholder characters with sign in the SQL queries.	true	boolean
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean

92.2. Result of the query

For select operations, the result is an instance of List<Map<String, Object>> type, as returned by the JdbcTemplate.queryForList() method. For update operations, the result is the number of updated rows, returned as an Integer.

By default, the result is placed in the message body. If the outputHeader parameter is set, the result is placed in the header. This is an alternative to using a full message enrichment pattern to add headers, it provides a concise syntax for querying a sequence or some other small value into a header. It is convenient to use outputHeader and outputType together:

92.3. Header values

When performing update operations, the SQL Component stores the update count in the following message headers:

Header	Description
`CamelSqlUpdateCount`	The number of rows updated for `update` operations, returned as an `Integer` object.
`CamelSqlRowCount`	The number of rows returned for `select` operations, returned as an `Integer` object.

92.3.1. Sample

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 for these parameters from the message body or message headers. Notice in the example above we set two headers with constant value
for the named parameters:

   from("direct:projects")
     .setHeader("lic", constant("ASF"))
     .setHeader("min", constant(123))
     .to("elsql:projects:com/foo/orders.elsql")

And the elsql mapping file

@NAME(projects)
  SELECT *
  FROM projects
  WHERE license = :lic AND id > :min
  ORDER BY id

Though if the message body is a java.util.Map then the named parameters will be taken from the body.

   from("direct:projects")
     .to("elsql:projects:com/foo/orders.elsql")

In from Camel 2.16.1 onwards you can use Simple expressions as well, which allows to use an OGNL like notation on the message body, where it assumes to have getLicense and getMinimum methods:

@NAME(projects)
  SELECT *
  FROM projects
  WHERE license = :${body.license} AND id > :${body.minimum}
  ORDER BY id

92.4. See Also

Configuring Camel
Component
Endpoint
Getting Started
SQL Component
MyBatis
JDBC

Chapter 93. etcd Component

Available as of Camel version 2.18

The camel etcd component allows you to work with Etcd, a distributed reliable key-value store.

93.1. URI Format

etcd:namespace/path[?options]

93.2. URI Options

The etcd component supports 7 options which are listed below.

Name	Description	Default	Type
uris (common)	To set the URIs the client connects.		String
sslContextParameters (common)	To configure security using SSLContextParameters.		SSLContextParameters
userName (common)	The user name to use for basic authentication.		String
password (common)	The password to use for basic authentication.		String
configuration (advanced)	Sets the common configuration shared among endpoints		EtcdConfiguration
useGlobalSslContext Parameters (security)	Enable usage of global SSL context parameters.	false	boolean
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The etcd endpoint is configured using URI syntax:

etcd:namespace/path

with the following path and query parameters:

93.2.1. Path Parameters (2 parameters):

Name	Description	Default	Type
namespace	Required The API namespace to use		EtcdNamespace
path	The path the endpoint refers to		String

93.2.2. Query Parameters (29 parameters):

Name	Description	Default	Type
recursive (common)	To apply an action recursively.	false	boolean
servicePath (common)	The path to look for for service discovery	/services/	String
timeout (common)	To set the maximum time an action could take to complete.		Long
uris (common)	To set the URIs the client connects.	http://localhost:2379,http://localhost:4001	String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
sendEmptyExchangeOnTimeout (consumer)	To send an empty message in case of timeout watching for a key.	false	boolean
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
fromIndex (consumer)	The index to watch from	0	Long
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
timeToLive (producer)	To set the lifespan of a key in milliseconds.		Integer
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean
password (security)	The password to use for basic authentication.		String
sslContextParameters (security)	To configure security using SSLContextParameters.		SSLContextParameters
userName (security)	The user name to use for basic authentication.		String

Chapter 94. OSGi EventAdmin Component

Available as of Camel version 2.6

The eventadmin component can be used in an OSGi environment to receive OSGi EventAdmin events and process them.

94.1. Dependencies

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

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

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

94.2. URI format

eventadmin:topic[?options]

where topic is the name of the topic to listen too.

94.3. URI options

The OSGi EventAdmin component supports 2 options which are listed below.

Name	Description	Default	Type
bundleContext (common)	The OSGi BundleContext is automatic injected by Camel		BundleContext
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The OSGi EventAdmin endpoint is configured using URI syntax:

eventadmin:topic

with the following path and query parameters:

94.3.1. Path Parameters (1 parameters):

Name	Description	Default	Type
topic	Name of topic to listen or send to		String

94.3.2. Query Parameters (5 parameters):

Name	Description	Default	Type
send (common)	Whether to use 'send' or 'synchronous' deliver. Default false (async delivery)	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

94.4. Message headers

Name	Type	Message
Description

94.5. Message body

The in message body will be set to the received Event.

94.6. Example usage

<route>
    <from uri="eventadmin:*"/>
    <to uri="stream:out"/>
</route>

Chapter 95. Exec Component

Available as of Camel version 2.3

The exec component can be used to execute system commands.

95.1. Dependencies

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

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

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

95.2. URI format

exec://executable[?options]

where executable is the name, or file path, of the system command that will be executed. If executable name is used (e.g. exec:java), the executable must in the system path.

95.3. URI options

The Exec component has no options.

The Exec endpoint is configured using URI syntax:

exec:executable

with the following path and query parameters:

95.3.1. Path Parameters (1 parameters):

Name	Description	Default	Type
executable	Required Sets the executable to be executed. The executable must not be empty or null.		String

95.3.2. Query Parameters (8 parameters):

Name	Description	Default	Type
args (producer)	The arguments may be one or many whitespace-separated tokens.		String
binding (producer)	A reference to a org.apache.commons.exec.ExecBinding in the Registry.		ExecBinding
commandExecutor (producer)	A reference to a org.apache.commons.exec.ExecCommandExecutor in the Registry that customizes the command execution. The default command executor utilizes the commons-exec library, which adds a shutdown hook for every executed command.		ExecCommandExecutor
outFile (producer)	The name of a file, created by the executable, that should be considered as its output. If no outFile is set, the standard output (stdout) of the executable will be used instead.		String
timeout (producer)	The timeout, in milliseconds, after which the executable should be terminated. If execution has not completed within the timeout, the component will send a termination request.		long
useStderrOnEmptyStdout (producer)	A boolean indicating that when stdout is empty, this component will populate the Camel Message Body with stderr. This behavior is disabled (false) by default.	false	boolean
workingDir (producer)	The directory in which the command should be executed. If null, the working directory of the current process will be used.		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

95.4. Message headers

The supported headers are defined in org.apache.camel.component.exec.ExecBinding.

Name	Type	Message	Description
`ExecBinding.EXEC_COMMAND_EXECUTABLE`	`String`	`in`	The name of the system command that will be executed. Overrides `executable` in the URI.
`ExecBinding.EXEC_COMMAND_ARGS`	`java.util.List<String>`	`in`	Command-line arguments to pass to the executed process. The arguments are used literally - no quoting is applied. Overrides any existing `args` in the URI.
`ExecBinding.EXEC_COMMAND_ARGS`	`String`	`in`	Camel 2.5: The arguments of the executable as a Single string where each argument is whitespace separated (see `args` in URI option). The arguments are used literally, no quoting is applied. Overrides any existing `args` in the URI.
`ExecBinding.EXEC_COMMAND_OUT_FILE`	`String`	`in`	The name of a file, created by the executable, that should be considered as its output. Overrides any existing `outFile` in the URI.
`ExecBinding.EXEC_COMMAND_TIMEOUT`	`long`	`in`	The timeout, in milliseconds, after which the executable should be terminated. Overrides any existing `timeout` in the URI.
`ExecBinding.EXEC_COMMAND_WORKING_DIR`	`String`	`in`	The directory in which the command should be executed. Overrides any existing `workingDir` in the URI.
`ExecBinding.EXEC_EXIT_VALUE`	`int`	`out`	The value of this header is the exit value of the executable. Non-zero exit values typically indicate abnormal termination. Note that the exit value is OS-dependent.
`ExecBinding.EXEC_STDERR`	`java.io.InputStream`	`out`	The value of this header points to the standard error stream (stderr) of the executable. If no stderr is written, the value is `null`.
`ExecBinding.EXEC_USE_STDERR_ON_EMPTY_STDOUT`	`boolean`	`in`	Indicates that when `stdout` is empty, this component will populate the Camel Message Body with `stderr`. This behavior is disabled (`false`) by default.

95.5. Message body

If the Exec component receives an in message body that is convertible to java.io.InputStream, it is used to feed input to the executable via its stdin. After execution, the message body is the result of the execution,- that is, an org.apache.camel.components.exec.ExecResult instance containing the stdout, stderr, exit value, and out file. This component supports the following ExecResult type converters for convenience:

From	To
`ExecResult`	`java.io.InputStream`
`ExecResult`	`String`
`ExecResult`	`byte []`
`ExecResult`	`org.w3c.dom.Document`

If an out file is specified (in the endpoint via outFile or the message headers via ExecBinding.EXEC_COMMAND_OUT_FILE), converters will return the content of the out file. If no out file is used, then this component will convert the stdout of the process to the target type. For more details, please refer to the usage examples below.

95.6. Usage examples

95.6.1. Executing word count (Linux)

The example below executes wc (word count, Linux) to count the words in file /usr/share/dict/words. The word count (output) is written to the standard output stream of wc.

from("direct:exec")
.to("exec:wc?args=--words /usr/share/dict/words")
.process(new Processor() {
     public void process(Exchange exchange) throws Exception {
       // By default, the body is ExecResult instance
       assertIsInstanceOf(ExecResult.class, exchange.getIn().getBody());
       // Use the Camel Exec String type converter to convert the ExecResult to String
       // In this case, the stdout is considered as output
       String wordCountOutput = exchange.getIn().getBody(String.class);
       // do something with the word count
     }
});

95.6.2. Executing `java`

The example below executes java with 2 arguments: -server and -version, provided that java is in the system path.

from("direct:exec")
.to("exec:java?args=-server -version")

The example below executes java in c:\temp with 3 arguments: -server, -version and the sytem property user.name.

from("direct:exec")
.to("exec:c:/program files/jdk/bin/java?args=-server -version -Duser.name=Camel&workingDir=c:/temp")

95.6.3. Executing Ant scripts

The following example executes Apache Ant (Windows only) with the build file CamelExecBuildFile.xml, provided that ant.bat is in the system path, and that CamelExecBuildFile.xml is in the current directory.

from("direct:exec")
.to("exec:ant.bat?args=-f CamelExecBuildFile.xml")

In the next example, the ant.bat command redirects its output to CamelExecOutFile.txt with -l. The file CamelExecOutFile.txt is used as the out file with outFile=CamelExecOutFile.txt. The example assumes that ant.bat is in the system path, and that CamelExecBuildFile.xml is in the current directory.

from("direct:exec")
.to("exec:ant.bat?args=-f CamelExecBuildFile.xml -l CamelExecOutFile.txt&outFile=CamelExecOutFile.txt")
.process(new Processor() {
     public void process(Exchange exchange) throws Exception {
        InputStream outFile = exchange.getIn().getBody(InputStream.class);
        assertIsInstanceOf(InputStream.class, outFile);
        // do something with the out file here
     }
  });

95.6.4. Executing `echo` (Windows)

Commands such as echo and dir can be executed only with the command interpreter of the operating system. This example shows how to execute such a command - echo - in Windows.

from("direct:exec").to("exec:cmd?args=/C echo echoString")

95.7. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 96. Facebook Component

Available as of Camel version 2.14

The Facebook component provides access to all of the Facebook APIs accessible using Facebook4J. It allows producing messages to retrieve, add, and delete posts, likes, comments, photos, albums, videos, photos, checkins, locations, links, etc. It also supports APIs that allow polling for posts, users, checkins, groups, locations, etc.

Facebook requires the use of OAuth for all client application authentication. In order to use camel-facebook with your account, you’ll need to create a new application within Facebook at https://developers.facebook.com/apps and grant the application access to your account. The Facebook application’s id and secret will allow access to Facebook APIs which do not require a current user. A user access token is required for APIs that require a logged in user. More information on obtaining a user access token can be found at https://developers.facebook.com/docs/facebook-login/access-tokens/.

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

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

96.1. URI format

  facebook://[endpoint]?[options]

96.2. FacebookComponent

The facebook component can be configured with the Facebook account settings below, which are mandatory. The values can be provided to the component using the bean property configuration of type org.apache.camel.component.facebook.config.FacebookConfiguration. The oAuthAccessToken option may be ommited but that will only allow access to application APIs.

The Facebook component supports 2 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	To use the shared configuration		FacebookConfiguration
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Facebook endpoint is configured using URI syntax:

facebook:methodName

with the following path and query parameters:

96.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
methodName	Required What operation to perform		String

96.2.2. Query Parameters (102 parameters):

Name	Description	Default	Type
achievementURL (common)	The unique URL of the achievement		URL
albumId (common)	The album ID		String
albumUpdate (common)	The facebook Album to be created or updated		AlbumUpdate
appId (common)	The ID of the Facebook Application		String
center (common)	Location latitude and longitude		GeoLocation
checkinId (common)	The checkin ID		String
checkinUpdate (common)	Deprecated The checkin to be created. Deprecated, instead create a Post with an attached location		CheckinUpdate
clientURL (common)	Facebook4J API client URL		String
clientVersion (common)	Facebook4J client API version		String
commentId (common)	The comment ID		String
commentUpdate (common)	The facebook Comment to be created or updated		CommentUpdate
debugEnabled (common)	Enables deubg output. Effective only with the embedded logger	false	Boolean
description (common)	The description text		String
distance (common)	Distance in meters		Integer
domainId (common)	The domain ID		String
domainName (common)	The domain name		String
domainNames (common)	The domain names		List
eventId (common)	The event ID		String
eventUpdate (common)	The event to be created or updated		EventUpdate
friendId (common)	The friend ID		String
friendlistId (common)	The friend list ID		String
friendlistName (common)	The friend list Name		String
friendUserId (common)	The friend user ID		String
groupId (common)	The group ID		String
gzipEnabled (common)	Use Facebook GZIP encoding	true	Boolean
httpConnectionTimeout (common)	Http connection timeout in milliseconds	20000	Integer
httpDefaultMaxPerRoute (common)	HTTP maximum connections per route	2	Integer
httpMaxTotalConnections (common)	HTTP maximum total connections	20	Integer
httpReadTimeout (common)	Http read timeout in milliseconds	120000	Integer
httpRetryCount (common)	Number of HTTP retries	0	Integer
httpRetryIntervalSeconds (common)	HTTP retry interval in seconds	5	Integer
httpStreamingReadTimeout (common)	HTTP streaming read timeout in milliseconds	40000	Integer
ids (common)	The ids of users		List
inBody (common)	Sets the name of a parameter to be passed in the exchange In Body		String
includeRead (common)	Enables notifications that the user has already read in addition to unread ones		Boolean
isHidden (common)	Whether hidden		Boolean
jsonStoreEnabled (common)	If set to true, raw JSON forms will be stored in DataObjectFactory	false	Boolean
link (common)	Link URL		URL
linkId (common)	Link ID		String
locale (common)	Desired FQL locale		Locale
mbeanEnabled (common)	If set to true, Facebook4J mbean will be registerd	false	Boolean
message (common)	The message text		String
messageId (common)	The message ID		String
metric (common)	The metric name		String
milestoneId (common)	The milestone id		String
name (common)	Test user name, must be of the form 'first last'		String
noteId (common)	The note ID		String
notificationId (common)	The notification ID		String
objectId (common)	The insight object ID		String
offerId (common)	The offer id		String
optionDescription (common)	The question’s answer option description		String
pageId (common)	The page id		String
permissionName (common)	The permission name		String
permissions (common)	Test user permissions in the format perm1,perm2,…		String
photoId (common)	The photo ID		String
pictureId (common)	The picture id		Integer
pictureId2 (common)	The picture2 id		Integer
pictureSize (common)	The picture size		PictureSize
placeId (common)	The place ID		String
postId (common)	The post ID		String
postUpdate (common)	The post to create or update		PostUpdate
prettyDebugEnabled (common)	Prettify JSON debug output if set to true	false	Boolean
queries (common)	FQL queries		Map
query (common)	FQL query or search terms for search endpoints		String
questionId (common)	The question id		String
reading (common)	Optional reading parameters. See Reading Options(reading)		Reading
readingOptions (common)	To configure Reading using key/value pairs from the Map.		Map
restBaseURL (common)	API base URL	https://graph.facebook.com/	String
scoreValue (common)	The numeric score with value		Integer
size (common)	The picture size, one of large, normal, small or square		PictureSize
source (common)	The media content from either a java.io.File or java.io.Inputstream		Media
subject (common)	The note of the subject		String
tabId (common)	The tab id		String
tagUpdate (common)	Photo tag information		TagUpdate
testUser1 (common)	Test user 1		TestUser
testUser2 (common)	Test user 2		TestUser
testUserId (common)	The ID of the test user		String
title (common)	The title text		String
toUserId (common)	The ID of the user to tag		String
toUserIds (common)	The IDs of the users to tag		List
userId (common)	The Facebook user ID		String
userId1 (common)	The ID of a user 1		String
userId2 (common)	The ID of a user 2		String
userIds (common)	The IDs of users to invite to event		List
userLocale (common)	The test user locale		String
useSSL (common)	Use SSL	true	Boolean
videoBaseURL (common)	Video API base URL	https://graph-video.facebook.com/	String
videoId (common)	The video ID		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
httpProxyHost (proxy)	HTTP proxy server host name		String
httpProxyPassword (proxy)	HTTP proxy server password		String
httpProxyPort (proxy)	HTTP proxy server port		Integer
httpProxyUser (proxy)	HTTP proxy server user name		String
oAuthAccessToken (security)	The user access token		String
oAuthAccessTokenURL (security)	OAuth access token URL	https://graph.facebook.com/oauth/access_token	String
oAuthAppId (security)	The application Id		String
oAuthAppSecret (security)	The application Secret		String
oAuthAuthorizationURL (security)	OAuth authorization URL	https://www.facebook.com/dialog/oauth	String
oAuthPermissions (security)	Default OAuth permissions. Comma separated permission names. See https://developers.facebook.com/docs/reference/login/permissions for the detail		String

96.3. Producer Endpoints:

Producer endpoints can use endpoint names and options from the table below. Endpoints can also use the short name without the get or search prefix, except checkin due to ambiguity between getCheckin and searchCheckin. Endpoint options that are not mandatory are denoted by [].

Producer endpoints can also use a special option inBody that in turn should contain the name of the endpoint option whose value will be contained in the Camel Exchange In message. For example, the facebook endpoint in the following route retrieves activities for the user id value in the incoming message body.

    from("direct:test").to("facebook://activities?inBody=userId")...

Any of the endpoint options can be provided in either the endpoint URI, or dynamically in a message header. The message header name must be of the format CamelFacebook.https://cwiki.apache.org/confluence/pages/createpage.action?spaceKey=CAMEL&title=option&linkCreation=true&fromPageId=34020899[option]. For example, the userId option value in the previous route could alternately be provided in the message header CamelFacebook.userId. Note that the inBody option overrides message header, e.g. the endpoint option inBody=user would override a CamelFacebook.userId header.

Endpoints that return a String return an Id for the created or modified entity, e.g. addAlbumPhoto returns the new album Id. Endpoints that return a boolean, return true for success and false otherwise. In case of Facebook API errors the endpoint will throw a RuntimeCamelException with a facebook4j.FacebookException cause.

96.4. Consumer Endpoints:

Any of the producer endpoints that take a reading#reading parameter can be used as a consumer endpoint. The polling consumer uses the since and until fields to get responses within the polling interval. In addition to other reading fields, an initial since value can be provided in the endpoint for the first poll.

Rather than the endpoints returning a List (or facebook4j.ResponseList) through a single route exchange, camel-facebook creates one route exchange per returned object. As an example, if "facebook://home" results in five posts, the route will be executed five times (once for each Post).

96.5. Reading Options

The reading option of type facebook4j.Reading adds support for reading parameters, which allow selecting specific fields, limits the number of results, etc. For more information see Graph API#reading - Facebook Developers.

It is also used by consumer endpoints to poll Facebook data to avoid sending duplicate messages across polls.

The reading option can be a reference or value of type facebook4j.Reading, or can be specified using the following reading options in either the endpoint URI or exchange header with CamelFacebook. prefix.

96.6. Message header

Any of the URI options#urioptions can be provided in a message header for producer endpoints with CamelFacebook. prefix.

96.7. Message body

All result message bodies utilize objects provided by the Facebook4J API. Producer endpoints can specify the option name for incoming message body in the inBody endpoint parameter.

For endpoints that return an array, or facebook4j.ResponseList, or java.util.List, a consumer endpoint will map every elements in the list to distinct messages.

96.8. Use cases

To create a post within your Facebook profile, send this producer a facebook4j.PostUpdate body.

    from("direct:foo")
        .to("facebook://postFeed/inBody=postUpdate);

To poll, every 5 sec (You can set the polling consumer options by adding a prefix of "consumer"), all statuses on your home feed:

    from("facebook://home?consumer.delay=5000")
        .to("bean:blah");

Searching using a producer with dynamic options from header.

In the bar header we have the Facebook search string we want to execute in public posts, so we need to assign this value to the CamelFacebook.query header.

    from("direct:foo")
        .setHeader("CamelFacebook.query", header("bar"))
        .to("facebook://posts");

Chapter 97. File Component

Available as of Camel version 1.0

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.

97.1. URI format

file:directoryName[?options]

or

file://directoryName[?options]

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

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.

Warning

Avoid reading files currently being written by another application 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.

97.2. URI Options

The File component has no options.

The File endpoint is configured using URI syntax:

file:directoryName

with the following path and query parameters:

97.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
directoryName	Required The starting directory		File

97.2.2. Query Parameters (81 parameters):

Name	Description	Default	Type
charset (common)	This option is used to specify the encoding of the file. 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. Do mind that when writing the file Camel may have to read the message content into memory to be able to convert the data into the configured charset, so do not use this if you have big messages.		String
doneFileName (common)	Producer: 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. Consumer: 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. Only $file.name and $file.name.noext is supported as dynamic placeholders.		String
fileName (common)	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. 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.		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN/ERROR level and ignored.	false	boolean
delete (consumer)	If true, the file will be deleted after it is processed successfully.	false	boolean
moveFailed (consumer)	Sets the move failure expression based on Simple language. 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.		String
noop (consumer)	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.	false	boolean
preMove (consumer)	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.		String
preSort (consumer)	When pre-sort is enabled then the consumer will sort the file and directory names during polling, that was retrieved from the file system. You may want to do this in case you need to operate on the files in a sorted order. The pre-sort is executed before the consumer starts to filter, and accept files to process by Camel. This option is default=false meaning disabled.	false	boolean
recursive (consumer)	If a directory, will look for files in all the sub-directories as well.	false	boolean
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
directoryMustExist (consumer)	Similar to startingDirectoryMustExist but this applies during polling recursive sub directories.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN/ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the default exchange pattern when creating an exchange.		ExchangePattern
extendedAttributes (consumer)	To define which file attributes of interest. Like posix:permissions,posix:owner,basic:lastAccessTime, it supports basic wildcard like posix:, basic:lastAccessTime		String
inProgressRepository (consumer)	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.		String>
localWorkDirectory (consumer)	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.		String
onCompletionException Handler (consumer)	To use a custom org.apache.camel.spi.ExceptionHandler to handle any thrown exceptions that happens during the file on completion process where the consumer does either a commit or rollback. The default implementation will log any exception at WARN level and ignore.		ExceptionHandler
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
probeContentType (consumer)	Whether to enable probing of the content type. If enable then the consumer uses link FilesprobeContentType(java.nio.file.Path) to determine the content-type of the file, and store that as a header with key link ExchangeFILE_CONTENT_TYPE on the Message.	false	boolean
processStrategy (consumer)	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.		GenericFileProcess Strategy<T>
startingDirectoryMustExist (consumer)	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.	false	boolean
fileExist (producer)	What to do if a file already exists with the same name. 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. Move - option requires to use the 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 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.	Override	GenericFileExist
flatten (producer)	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 in CamelFileName header will be stripped for any leading paths.	false	boolean
moveExisting (producer)	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.		String
tempFileName (producer)	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.		String
tempPrefix (producer)	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.		String
allowNullBody (producer)	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.	false	boolean
chmod (producer)	Specify the file permissions which is sent by the producer, the chmod value must be between 000 and 777; If there is a leading digit like in 0755 we will ignore it.		String
chmodDirectory (producer)	Specify the directory permissions used when the producer creates missing directories, the chmod value must be between 000 and 777; If there is a leading digit like in 0755 we will ignore it.		String
eagerDeleteTargetFile (producer)	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. 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 copyAndDeleteOnRenameFails 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.	true	boolean
forceWrites (producer)	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.	true	boolean
keepLastModified (producer)	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.	false	boolean
autoCreate (advanced)	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.	true	boolean
bufferSize (advanced)	Write buffer sized in bytes.	131072	int
copyAndDeleteOnRenameFail (advanced)	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.	true	boolean
renameUsingCopy (advanced)	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.	false	boolean
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
antExclude (filter)	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.		String
antFilterCaseSensitive (filter)	Sets case sensitive flag on ant filter	true	boolean
antInclude (filter)	Ant style filter inclusion. Multiple inclusions may be specified in comma-delimited format.		String
eagerMaxMessagesPerPoll (filter)	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.	true	boolean
exclude (filter)	Is used to exclude files, if filename matches the regex pattern (matching is case in-senstive). Notice if you use symbols such as plus sign and others you would need to configure this using the RAW() syntax if configuring this as an endpoint uri. See more details at configuring endpoint uris		String
filter (filter)	Pluggable filter as a org.apache.camel.component.file.GenericFileFilter class. Will skip files if filter returns false in its accept() method.		GenericFileFilter<T>
filterDirectory (filter)	Filters the directory based on Simple language. For example to filter on current date, you can use a simple date pattern such as $date:now:yyyMMdd		String
filterFile (filter)	Filters the file based on Simple language. For example to filter on file size, you can use $file:size 5000		String
idempotent (filter)	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.	false	Boolean
idempotentKey (filter)	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: idempotentKey=$file:name-$file:size		String
idempotentRepository (filter)	A pluggable repository org.apache.camel.spi.IdempotentRepository which by default use MemoryMessageIdRepository if none is specified and idempotent is true.		String>
include (filter)	Is used to include files, if filename matches the regex pattern (matching is case in-sensitive). Notice if you use symbols such as plus sign and others you would need to configure this using the RAW() syntax if configuring this as an endpoint uri. See more details at configuring endpoint uris		String
maxDepth (filter)	The maximum depth to traverse when recursively processing a directory.	2147483647	int
maxMessagesPerPoll (filter)	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. 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.		int
minDepth (filter)	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.		int
move (filter)	Expression (such as Simple Language) used to dynamically set the filename when moving it after processing. To move files into a .done subdirectory just enter .done.		String
exclusiveReadLockStrategy (lock)	Pluggable read-lock as a org.apache.camel.component.file.GenericFileExclusiveReadLockStrategy implementation.		GenericFileExclusive ReadLockStrategy<T>
readLock (lock)	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: none - No read lock is in use 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 - 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. 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 - rename is for using a try to rename the file as a test if we can get exclusive read-lock. idempotent - (only for file component) idempotent is for using a idempotentRepository as the read-lock. This allows to use read locks that supports clustering if the idempotent repository implementation supports that. idempotent-changed - (only for file component) idempotent-changed is for using a idempotentRepository and changed as the combined read-lock. This allows to use read locks that supports clustering if the idempotent repository implementation supports that. idempotent-rename - (only for file component) idempotent-rename is for using a idempotentRepository and rename as the combined read-lock. This allows to use read locks that supports clustering if the idempotent repository implementation supports that. Notice: The various read locks is not all suited to work in clustered mode, where concurrent consumers on different nodes is competing for the same files on a shared file system. The markerFile using a close to atomic operation to create the empty marker file, but its not guaranteed to work in a cluster. The fileLock may work better but then the file system need to support distributed file locks, and so on. Using the idempotent read lock can support clustering if the idempotent repository supports clustering, such as Hazelcast Component or Infinispan.	none	String
readLockCheckInterval (lock)	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. Notice: For FTP the default readLockCheckInterval is 5000. The readLockTimeout value must be higher than readLockCheckInterval, but a rule of thumb is to have a timeout that is at least 2 or more times higher than the readLockCheckInterval. This is needed to ensure that amble time is allowed for the read lock process to try to grab the lock before the timeout was hit.	1000	long
readLockDeleteOrphanLock Files (lock)	Whether or not read lock with marker files should upon startup delete any orphan read lock files, which may have been left on the file system, if Camel was not properly shutdown (such as a JVM crash). If turning this option to false then any orphaned lock file will cause Camel to not attempt to pickup that file, this could also be due another node is concurrently reading files from the same shared directory.	true	boolean
readLockLoggingLevel (lock)	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, idempotent, idempotent-changed, idempotent-rename, rename.	DEBUG	LoggingLevel
readLockMarkerFile (lock)	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.	true	boolean
readLockMinAge (lock)	This option applied only for readLock=change. This option allows to specify a minimum age the file must be before attempting to acquire the read lock. For example use readLockMinAge=300s to require the file is at last 5 minutes old. This can speedup the changed read lock as it will only attempt to acquire files which are at least that given age.	0	long
readLockMinLength (lock)	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.	1	long
readLockRemoveOnCommit (lock)	This option applied only for readLock=idempotent. This option allows to specify whether to remove the file name entry from the idempotent repository when processing the file is succeeded and a commit happens. By default the file is not removed which ensures that any race-condition do not occur so another active node may attempt to grab the file. Instead the idempotent repository may support eviction strategies that you can configure to evict the file name entry after X minutes - this ensures no problems with race conditions.	false	boolean
readLockRemoveOnRollback (lock)	This option applied only for readLock=idempotent. This option allows to specify whether to remove the file name entry from the idempotent repository when processing the file failed and a rollback happens. If this option is false, then the file name entry is confirmed (as if the file did a commit).	true	boolean
readLockTimeout (lock)	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. Currently fileLock, changed and rename support the timeout. Notice: For FTP the default readLockTimeout value is 20000 instead of 10000. The readLockTimeout value must be higher than readLockCheckInterval, but a rule of thumb is to have a timeout that is at least 2 or more times higher than the readLockCheckInterval. This is needed to ensure that amble time is allowed for the read lock process to try to grab the lock before the timeout was hit.	10000	long
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. The default value is 500. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. The default value is 1000. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	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 consumers.		ScheduledExecutor Service
scheduler (scheduler)	Allow to plugin a custom org.apache.camel.spi.ScheduledPollConsumerScheduler to use as the scheduler for firing when the polling consumer runs. The default implementation uses the ScheduledExecutorService and there is a Quartz2, and Spring based which supports CRON expressions. Notice: If using a custom scheduler then the options for initialDelay, useFixedDelay, timeUnit, and scheduledExecutorService may not be in use. Use the text quartz2 to refer to use the Quartz2 scheduler; and use the text spring to use the Spring based; and use the text myScheduler to refer to a custom scheduler by its id in the Registry. See Quartz2 page for an example.	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean
shuffle (sort)	To shuffle the list of files (sort in random order)	false	boolean
sortBy (sort)	Built-in sort by 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.		String
sorter (sort)	Pluggable sorter as a java.util.Comparator class.		GenericFile<T>>

Tip

Default behavior for file producer By default it will override any existing file, if one exist with the same name.

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

from("file://inbox?move=.done").to("bean:handleOrder");

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

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

move=../backup/copy-of-${file:name}

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:

from("file://inobox?delete=true").to("bean:handleOrder");

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.

from("file://inbox?preMove=inprogress").to("bean:handleOrder");

You can combine the pre move and the regular move:

from("file://inbox?preMove=inprogress&move=.done").to("bean:handleOrder");

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.

97.4. Fine grained control over Move and PreMove option

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

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

move=backup/${date:now:yyyyMMdd}/${file:name}

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

97.6. Message Headers

The following headers are supported by this component:

97.6.1. File producer only

Header	Description
`CamelFileName`	Specifies the name of the file to write (relative to the endpoint directory). This 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.

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

97.7. Batch Consumer

This component implements the Batch Consumer.

97.8. Exchange Properties, file consumer only

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

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 exist in this batch and for instance let the Aggregator2 aggregate this number of files.

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

from("file:inbox?charset=utf-8")
  .to("file:outbox?charset=iso-8859-1")

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.

from("file:inbox?charset=utf-8")
  .convertBodyTo(byte[].class, "iso-8859-1")
  .to("bean:myBean")
  .to("file:outbox");

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

from("file:inbox")
  .convertBodyTo(byte[].class, "iso-8859-1")
  .to("bean:myBean")
  .to("file:outbox");

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.

from("file:inbox")
  .convertBodyTo(byte[].class, "iso-8859-1")
  .to("bean:myBean")
  .setProperty(Exchange.CHARSET_NAME, header("someCharsetHeader"))
  .to("file:outbox");

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:

from("file:inbox?charset=utf-8")
  .to("file:outbox?charset=iso-8859-1")

And the logs:

DEBUG GenericFileConverter           - Read file /Users/davsclaus/workspace/camel/camel-core/target/charset/input/input.txt with charset utf-8
DEBUG FileOperations                 - Using Reader to write file: target/charset/output.txt with charset: iso-8859-1

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

from("direct:report").to("file:target/reports");

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

from("direct:report").setHeader(Exchange.FILE_NAME, constant("report.txt")).to( "file:target/reports");

the same as above, but with CamelFileName:

from("direct:report").setHeader("CamelFileName", constant("report.txt")).to( "file:target/reports");

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

from("direct:report").to("file:target/reports/?fileName=report.txt");

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

97.12. Consuming files from folders where others drop files directly

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

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

from("file:bar?doneFileName=done");

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

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

from("file:bar?doneFileName=${file:name}.done");

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:

from("file:bar?doneFileName=ready-${file:name}");

hello.txt - is the file to be consumed
ready-hello.txt - is the associated done file

97.14. Writing done files

Available as of Camel 2.6

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

.to("file:bar?doneFileName=done");

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

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

.to("file:bar?doneFileName=done-${file:name}");

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.

.to("file:bar?doneFileName=${file:name}.done");

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.

.to("file:bar?doneFileName=${file:name.noext}.done");

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

97.15. Samples

97.15.1. Read from a directory and write to another directory

from("file://inputdir/?delete=true").to("file://outputdir")

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

from("file://inputdir/?delete=true").to("file://outputdir?overruleFile=copy-of-${file: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.

97.15.3. Reading recursively from a directory and writing to another

from("file://inputdir/?recursive=true&delete=true").to("file://outputdir")

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.

inputdir/foo.txt
inputdir/sub/bar.txt

Will result in the following output layout:

outputdir/foo.txt
outputdir/sub/bar.txt

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

from("file://inputdir/?recursive=true&delete=true").to("file://outputdir?flatten=true")

Will result in the following output layout:

outputdir/foo.txt
outputdir/bar.txt

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

from("file://inputdir/?recursive=true&delete=true").to("file://outputdir")

Affects the layout as follows:
before

inputdir/foo.txt
inputdir/sub/bar.txt

after

inputdir/.camel/foo.txt
inputdir/sub/.camel/bar.txt
outputdir/foo.txt
outputdir/sub/bar.txt

97.18. Read from a directory and process the message in java

from("file://inputdir/").process(new Processor() {
  public void process(Exchange exchange) throws Exception {
    Object body = exchange.getIn().getBody();
    // do some business logic with the input body
  }
});

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

97.19. Writing to files

Camel is of course also able to write files, i.e. produce files. In the sample below we receive some reports on the SEDA queue that we process before they are being written to a directory.

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

<route>
  <from uri="bean:myBean"/>
  <to uri="file:/rootDirectory"/>
</route>

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

Exchange.FILE_NAME = hello.txt => /rootDirectory/hello.txt
Exchange.FILE_NAME = foo/bye.txt => /rootDirectory/foo/bye.txt

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

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

from("direct:start").
  to("file:///var/myapp/finalDirectory?tempPrefix=/../filesInProgress/");

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

from("file://inbox?move=backup/${date:now:yyyyMMdd}/${file:name}").to("...");

See File Language for more samples.

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

from("file://inbox?idempotent=true").to("...");

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

<route>
  <from uri="file://inbox?idempotent=true&amp;idempotentKey=${file:name}-${file:size}"/>
  <to uri="bean:processInbox"/>
</route>

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.

 <!-- define our store as a plain spring bean -->
 <bean id="myStore" class="com.mycompany.MyIdempotentStore"/>

<route>
  <from uri="file://inbox?idempotent=true&amp;idempotentRepository=#myStore"/>
  <to uri="bean:processInbox"/>
</route>

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

DEBUG FileConsumer is idempotent and the file has been consumed before. Will skip this file: target\idempotent\report.txt

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

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

<persistence-unit name="idempotentDb" transaction-type="RESOURCE_LOCAL">
  <class>org.apache.camel.processor.idempotent.jpa.MessageProcessed</class>

  <properties>
    <property name="openjpa.ConnectionURL" value="jdbc:derby:target/idempotentTest;create=true"/>
    <property name="openjpa.ConnectionDriverName" value="org.apache.derby.jdbc.EmbeddedDriver"/>
    <property name="openjpa.jdbc.SynchronizeMappings" value="buildSchema"/>
    <property name="openjpa.Log" value="DefaultLevel=WARN, Tool=INFO"/>
    <property name="openjpa.Multithreaded" value="true"/>
  </properties>
</persistence-unit>

Next, we can create our JPA idempotent repository in the spring XML file as well:

<!-- we define our jpa based idempotent repository we want to use in the file consumer -->
<bean id="jpaStore" class="org.apache.camel.processor.idempotent.jpa.JpaMessageIdRepository">
    <!-- Here we refer to the entityManagerFactory -->
    <constructor-arg index="0" ref="entityManagerFactory"/>
    <!-- This 2nd parameter is the name  (= a category name).
         You can have different repositories with different names -->
    <constructor-arg index="1" value="FileConsumer"/>
</bean>

And yes then we just need to refer to the jpaStore bean in the file consumer endpoint using the idempotentRepository using the # syntax option:

<route>
  <from uri="file://inbox?idempotent=true&amp;idempotentRepository=#jpaStore"/>
  <to uri="bean:processInbox"/>
</route>

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

<!-- define our filter as a plain spring bean -->
<bean id="myFilter" class="com.mycompany.MyFileFilter"/>

<route>
  <from uri="file://inbox?filter=#myFilter"/>
  <to uri="bean:processInbox"/>
</route>

97.25. Filtering using ANT path matcher

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

The file paths is matched with the following rules:

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

Tip

New options from Camel 2.10 onwards 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 sample below demonstrates how to use it:

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

 <!-- define our sorter as a plain spring bean -->
 <bean id="mySorter" class="com.mycompany.MyFileSorter"/>

<route>
  <from uri="file://inbox?sorter=#mySorter"/>
  <to uri="bean:processInbox"/>
</route>

Tip

URI options can reference beans using the # syntax In the Spring DSL route above 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.

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

sortBy=group 1;group 2;group 3;...

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

sortBy=file:name

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

sortBy=reverse:file:name

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:

sortBy=file:length

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:

sortBy=ignoreCase:file:name

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

sortBy=reverse:ignoreCase:file:name

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

sortBy=file:modified

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

sortBy=file:modified;file:name

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

sortBy=date:file:yyyyMMdd;file:name

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

sortBy=date:file:yyyyMMdd;reverse:file:name

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

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

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

// to handle any IOException being thrown
onException(IOException.class)
    .handled(true)
    .log("IOException occurred due: ${exception.message}")
    .transform().simple("Error ${exception.message}")
    .to("mock:error");

// this is the file route that pickup files, notice how we bridge the consumer to use the Camel routing error handler
// the exclusiveReadLockStrategy is only configured because this is from an unit test, so we use that to simulate exceptions
from("file:target/nospace?consumer.bridgeErrorHandler=true")
    .convertBodyTo(String.class)
    .to("mock:result");

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

Important

Important when using consumer.bridgeErrorHandler 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.

97.29. Debug logging

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

97.30. See Also

File Language
FTP
Polling Consumer

Chapter 98. File Language

Available as of Camel version 1.1

INFO:*File language is now merged with Simple language* From Camel 2.2 onwards, the file language is now merged with Simple language which means you can use all the file syntax directly within the simple language.

The File Expression Language is an extension to the Simple language, adding file related capabilities. These capabilities are related to common use cases working with file path and names. The goal is to allow expressions to be used with the File and FTP components for setting dynamic file patterns for both consumer and producer.

98.1. File Language options

The File language supports 2 options which are listed below.

Name	Default	Java Type	Description
resultType		`String`	Sets the class name of the result type (type from output)
trim	`true`	`Boolean`	Whether to trim the value to remove leading and trailing whitespaces and line breaks

98.2. Syntax

This language is an extension to the Simple language so the Simple syntax applies also. So the table below only lists the additional.
As opposed to Simple language File Language also supports Constant expressions so you can enter a fixed filename.

All the file tokens use the same expression name as the method on the java.io.File object, for instance file:absolute refers to the java.io.File.getAbsolute() method. Notice that not all expressions are supported by the current Exchange. For instance the FTP component supports some of the options, where as the File component supports all of them.

Expression	Type	File Consumer	File Producer	FTP Consumer	FTP Producer	Description
file:name	String	yes	no	yes	no	refers to the file name (is relative to the starting directory, see note below)
file:name.ext	String	yes	no	yes	no	Camel 2.3: refers to the file extension only
file:name.ext.single	String	yes	no	yes	no	Camel 2.14.4/2.15.3: refers to the file extension. If the file extension has mutiple dots, then this expression strips and only returns the last part.
file:name.noext	String	yes	no	yes	no	refers to the file name with no extension (is relative to the starting directory, see note below)
file:name.noext.single	String	yes	no	yes	no	Camel 2.14.4/2.15.3: refers to the file name with no extension (is relative to the starting directory, see note below). If the file extension has multiple dots, then this expression strips only the last part, and keep the others.
file:onlyname	String	yes	no	yes	no	refers to the file name only with no leading paths.
file:onlyname.noext	String	yes	no	yes	no	refers to the file name only with no extension and with no leading paths.
file:onlyname.noext.single	String	yes	no	yes	no	Camel 2.14.4/2.15.3:refers to the file name only with no extension and with no leading paths. If the file extension has multiple dots, then this expression strips only the last part, and keep the others.
file:ext	String	yes	no	yes	no	refers to the file extension only
file:parent	String	yes	no	yes	no	refers to the file parent
file:path	String	yes	no	yes	no	refers to the file path
file:absolute	Boolean	yes	no	no	no	refers to whether the file is regarded as absolute or relative
file:absolute.path	String	yes	no	no	no	refers to the absolute file path
file:length	Long	yes	no	yes	no	refers to the file length returned as a Long type
file:size	Long	yes	no	yes	no	Camel 2.5: refers to the file length returned as a Long type
file:modified	Date	yes	no	yes	no	Refers to the file last modified returned as a Date type
date:_command:pattern_	String	yes	yes	yes	yes	for date formatting using the `java.text.SimpleDateFormat` patterns. Is an extension to the Simple language. Additional command is: file (consumers only) for the last modified timestamp of the file. Notice: all the commands from the Simple language can also be used.

98.3. File token example

98.3.1. Relative paths

We have a java.io.File handle for the file hello.txt in the following relative directory: .\filelanguage\test. And we configure our endpoint to use this starting directory .\filelanguage. The file tokens will return as:

Expression	Returns
file:name	test\hello.txt
file:name.ext	txt
file:name.noext	test\hello
file:onlyname	hello.txt
file:onlyname.noext	hello
file:ext	txt
file:parent	filelanguage\test
file:path	filelanguage\test\hello.txt
file:absolute	false
file:absolute.path	\workspace\camel\camel-core\target\filelanguage\test\hello.txt

98.3.2. Absolute paths

We have a java.io.File handle for the file hello.txt in the following absolute directory: \workspace\camel\camel-core\target\filelanguage\test. And we configure out endpoint to use the absolute starting directory \workspace\camel\camel-core\target\filelanguage. The file tokens will return as:

Expression	Returns
file:name	test\hello.txt
file:name.ext	txt
file:name.noext	test\hello
file:onlyname	hello.txt
file:onlyname.noext	hello
file:ext	txt
file:parent	\workspace\camel\camel-core\target\filelanguage\test
file:path	\workspace\camel\camel-core\target\filelanguage\test\hello.txt
file:absolute	true
file:absolute.path	\workspace\camel\camel-core\target\filelanguage\test\hello.txt

98.4. Samples

You can enter a fixed Constant expression such as myfile.txt:

fileName="myfile.txt"

Lets assume we use the file consumer to read files and want to move the read files to backup folder with the current date as a sub folder. This can be archieved using an expression like:

fileName="backup/${date:now:yyyyMMdd}/${file:name.noext}.bak"

relative folder names are also supported so suppose the backup folder should be a sibling folder then you can append .. as:

fileName="../backup/${date:now:yyyyMMdd}/${file:name.noext}.bak"

As this is an extension to the Simple language we have access to all the goodies from this language also, so in this use case we want to use the in.header.type as a parameter in the dynamic expression:

fileName="../backup/${date:now:yyyyMMdd}/type-${in.header.type}/backup-of-${file:name.noext}.bak"

If you have a custom Date you want to use in the expression then Camel supports retrieving dates from the message header.

fileName="orders/order-${in.header.customerId}-${date:in.header.orderDate:yyyyMMdd}.xml"

And finally we can also use a bean expression to invoke a POJO class that generates some String output (or convertible to String) to be used:

fileName="uniquefile-${bean:myguidgenerator.generateid}.txt"

And of course all this can be combined in one expression where you can use the File Language, Simple and the Bean language in one combined expression. This is pretty powerful for those common file path patterns.

98.5. Using Spring PropertyPlaceholderConfigurer together with the File component

In Camel you can use the File Language directly from the Simple language which makes a Content Based Router easier to do in Spring XML, where we can route based on file extensions as shown below:

<from uri="file://input/orders"/>
   <choice>
     <when>
         <simple>${file:ext} == 'txt'</simple>
         <to uri="bean:orderService?method=handleTextFiles"/>
     </when>
     <when>
         <simple>${file:ext} == 'xml'</simple>
         <to uri="bean:orderService?method=handleXmlFiles"/>
     </when>
     <otherwise>
         <to uri="bean:orderService?method=handleOtherFiles"/>
     </otherwise>
  </choice>

If you use the fileName option on the File endpoint to set a dynamic filename using the File Language then make sure you
use the alternative syntax (available from Camel 2.5 onwards) to avoid clashing with Springs PropertyPlaceholderConfigurer.

bundle-context.xml

<bean id="propertyPlaceholder" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
    <property name="location" value="classpath:bundle-context.cfg" />
</bean>

<bean id="sampleRoute" class="SampleRoute">
    <property name="fromEndpoint" value="${fromEndpoint}" />
    <property name="toEndpoint" value="${toEndpoint}" />
</bean>

bundle-context.cfg

fromEndpoint=activemq:queue:test
toEndpoint=file://fileRoute/out?fileName=test-$simple{date:now:yyyyMMdd}.txt

Notice how we use the $simple\{ } syntax in the toEndpoint above.
If you don’t do this, there is a clash and Spring will throw an exception like

org.springframework.beans.factory.BeanDefinitionStoreException:
Invalid bean definition with name 'sampleRoute' defined in class path resource [bundle-context.xml]:
Could not resolve placeholder 'date:now:yyyyMMdd'

98.6. Dependencies

The File language is part of camel-core.

Chapter 99. Flatpack Component

Available as of Camel version 1.4

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

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

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

99.1. URI format

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

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

flatpack:someName[?options]

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

99.2. URI Options

The Flatpack component has no options.

The Flatpack endpoint is configured using URI syntax:

flatpack:type:resourceUri

with the following path and query parameters:

99.2.1. Path Parameters (2 parameters):

Name	Description	Default	Type
type	Whether to use fixed or delimiter	delim	FlatpackType
resourceUri	Required URL for loading the flatpack mapping file from classpath or file system		String

99.2.2. Query Parameters (25 parameters):

Name	Description	Default	Type
allowShortLines (common)	Allows for lines to be shorter than expected and ignores the extra characters	false	boolean
delimiter (common)	The default character delimiter for delimited files.	,	char
ignoreExtraColumns (common)	Allows for lines to be longer than expected and ignores the extra characters	false	boolean
ignoreFirstRecord (common)	Whether the first line is ignored for delimited files (for the column headers).	true	boolean
splitRows (common)	Sets the Component to send each row as a separate exchange once parsed	true	boolean
textQualifier (common)	The text qualifier for delimited files.		char
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean

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

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

99.5. Message Body

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

For example to get the firstname from the sample below:

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

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

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

99.6. Header and Trailer records

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

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

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

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

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

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

99.7. Using the endpoint

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

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

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

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

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

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

99.10. Usage

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

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

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.

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

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

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.

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

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

99.12. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 100. Flatpack DataFormat

Available as of Camel version 2.1

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.

100.1. Options

The Flatpack dataformat supports 9 options which are listed below.

Name	Default	Java Type	Description
definition		`String`	The flatpack pzmap configuration file. Can be omitted in simpler situations, but its preferred to use the pzmap.
fixed	`false`	`Boolean`	Delimited or fixed. Is by default false = delimited
ignoreFirstRecord	`true`	`Boolean`	Whether the first line is ignored for delimited files (for the column headers). Is by default true.
textQualifier		`String`	If the text is qualified with a character. Uses quote character by default.
delimiter	`,`	`String`	The delimiter char (could be ; , or similar)
allowShortLines	`false`	`Boolean`	Allows for lines to be shorter than expected and ignores the extra characters
ignoreExtraColumns	`false`	`Boolean`	Allows for lines to be longer than expected and ignores the extra characters.
parserFactoryRef		`String`	References to a custom parser factory to lookup in the registry
contentTypeHeader	`false`	`Boolean`	Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.

100.2. Usage

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

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

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.

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

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

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.

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

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

Chapter 101. Apache Flink Component

Available as of Camel version 2.18

This documentation page covers the Apache Flink component for the Apache Camel. The camel-flink component provides a bridge between Camel connectors and Flink tasks.
This Camel Flink connector provides a way to route message from various transports, dynamically choosing a flink task to execute, use incoming message as input data for the task and finally deliver the results back to the Camel pipeline.

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

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

101.1. URI Format

Currently, the Flink Component supports only Producers. One can create DataSet, DataStream jobs.

flink:dataset?dataset=#myDataSet&dataSetCallback=#dataSetCallback
flink:datastream?datastream=#myDataStream&dataStreamCallback=#dataStreamCallback

FlinkEndpoint Options

The Apache Flink endpoint is configured using URI syntax:

flink:endpointType

with the following path and query parameters:

101.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
endpointType	Required Type of the endpoint (dataset, datastream).		EndpointType

101.1.2. Query Parameters (6 parameters):

Name	Description	Default	Type
collect (producer)	Indicates if results should be collected or counted.	true	boolean
dataSet (producer)	DataSet to compute against.		DataSet
dataSetCallback (producer)	Function performing action against a DataSet.		DataSetCallback
dataStream (producer)	DataStream to compute against.		DataStream
dataStreamCallback (producer)	Function performing action against a DataStream.		DataStreamCallback
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

101.2. FlinkComponent Options

The Apache Flink component supports 5 options which are listed below.

Name	Description	Default	Type
dataSet (producer)	DataSet to compute against.		DataSet
dataStream (producer)	DataStream to compute against.		DataStream
dataSetCallback (producer)	Function performing action against a DataSet.		DataSetCallback
dataStreamCallback (producer)	Function performing action against a DataStream.		DataStreamCallback
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

101.3. Flink DataSet Callback

@Bean
public DataSetCallback<Long> dataSetCallback() {
    return new DataSetCallback<Long>() {
        public Long onDataSet(DataSet dataSet, Object... objects) {
            try {
                 dataSet.print();
                 return new Long(0);
            } catch (Exception e) {
                 return new Long(-1);
            }
        }
    };
}

101.4. Flink DataStream Callback

@Bean
public VoidDataStreamCallback dataStreamCallback() {
    return new VoidDataStreamCallback() {
        @Override
        public void doOnDataStream(DataStream dataStream, Object... objects) throws Exception {
            dataStream.flatMap(new Splitter()).print();

            environment.execute("data stream test");
        }
    };
}

101.5. Camel-Flink Producer call

CamelContext camelContext = new SpringCamelContext(context);

String pattern = "foo";

try {
    ProducerTemplate template = camelContext.createProducerTemplate();
    camelContext.start();
    Long count = template.requestBody("flink:dataSet?dataSet=#myDataSet&dataSetCallback=#countLinesContaining", pattern, Long.class);
    } finally {
        camelContext.stop();
    }

101.6. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 102. FOP Component

Available as of Camel version 2.10

The FOP component allows you to render a message into different output formats using Apache FOP.

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

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

102.1. URI format

fop://outputFormat?[options]

102.2. Output Formats

The primary output format is PDF but other output formats are also supported:

name	outputFormat	description
PDF	application/pdf	Portable Document Format
PS	application/postscript	Adobe Postscript
PCL	application/x-pcl	Printer Control Language
PNG	image/png	PNG images
JPEG	image/jpeg	JPEG images
SVG	image/svg+xml	Scalable Vector Graphics
XML	application/X-fop-areatree	Area tree representation
MIF	application/mif	FrameMaker’s MIF
RTF	application/rtf	Rich Text Format
TXT	text/plain	Text

The complete list of valid output formats can be found here

102.3. Endpoint Options

The FOP component has no options.

The FOP endpoint is configured using URI syntax:

fop:outputType

with the following path and query parameters:

102.3.1. Path Parameters (1 parameters):

Name	Description	Default	Type
outputType	Required The primary output format is PDF but other output formats are also supported.		FopOutputType

102.3.2. Query Parameters (3 parameters):

Name	Description	Default	Type
fopFactory (producer)	Allows to use a custom configured or implementation of org.apache.fop.apps.FopFactory.		FopFactory
userConfigURL (producer)	The location of a configuration file which can be loaded from classpath or file system.		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

The location of a configuration file with the following structure. From Camel 2.12 onwards the file is loaded from the classpath by default. You can use file:, or classpath: as prefix to load the resource from file or classpath. In previous releases the file is always loaded from file system.

fopFactory

Allows to use a custom configured or implementation of org.apache.fop.apps.FopFactory.

102.4. Message Operations

name	default value	description
CamelFop.Output.Format		Overrides the output format for that message
CamelFop.Encrypt.userPassword		PDF user password
CamelFop.Encrypt.ownerPassword		PDF owner passoword
CamelFop.Encrypt.allowPrint	true	Allows printing the PDF
CamelFop.Encrypt.allowCopyContent	true	Allows copying content of the PDF
CamelFop.Encrypt.allowEditContent	true	Allows editing content of the PDF
CamelFop.Encrypt.allowEditAnnotations	true	Allows editing annotation of the PDF
CamelFop.Render.producer	Apache FOP	Metadata element for the system/software that produces the document
CamelFop.Render.creator		Metadata element for the user that created the document
CamelFop.Render.creationDate		Creation Date
CamelFop.Render.author		Author of the content of the document
CamelFop.Render.title		Title of the document
CamelFop.Render.subject		Subject of the document
CamelFop.Render.keywords		Set of keywords applicable to this document

102.5. Example

Below is an example route that renders PDFs from xml data and xslt template and saves the PDF files in target folder:

from("file:source/data/xml")
    .to("xslt:xslt/template.xsl")
    .to("fop:application/pdf")
    .to("file:target/data");

For more information, see these resources…

102.6. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 103. Freemarker Component

Available as of Camel version 2.10

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:

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

103.1. URI format

freemarker:templateName[?options]

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

103.2. Options

The Freemarker component supports 2 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	To use an existing freemarker.template.Configuration instance as the configuration.		Configuration
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Freemarker endpoint is configured using URI syntax:

freemarker:resourceUri

with the following path and query parameters:

103.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
resourceUri	Required Path to the resource. You can prefix with: classpath, file, http, ref, or bean. classpath, file and http loads the resource using these protocols (classpath is default). ref will lookup the resource in the registry. bean will call a method on a bean to be used as the resource. For bean you can specify the method name after dot, eg bean:myBean.myMethod.		String

103.2.2. Query Parameters (5 parameters):

Name	Description	Default	Type
configuration (producer)	Sets the Freemarker configuration to use		Configuration
contentCache (producer)	Sets whether to use resource content cache or not	false	boolean
encoding (producer)	Sets the encoding to be used for loading the template file.		String
templateUpdateDelay (producer)	Number of seconds the loaded template resource will remain in the cache.		int
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

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

${request.setHeader('fruit', 'Apple')}

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

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

Map<String, Object> variableMap = new HashMap<String, Object>();
variableMap.put("headers", headersMap);
variableMap.put("body", "Monday");
variableMap.put("exchange", exchange);
exchange.getIn().setHeader("CamelFreemarkerDataModel", variableMap);

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

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

103.7. Samples

For example you could use something like:

from("activemq:My.Queue").
  to("freemarker:com/acme/MyResponse.ftl");

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:

from("activemq:My.Queue").
  to("freemarker:com/acme/MyResponse.ftl").
  to("activemq:Another.Queue");

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

from("activemq:My.Queue").
  to("freemarker:com/acme/MyResponse.ftl?contentCache=false").
  to("activemq:Another.Queue");

And a file-based resource:

from("activemq:My.Queue").
  to("freemarker:file://myfolder/MyResponse.ftl?contentCache=false").
  to("activemq:Another.Queue");

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

from("direct:in").
  setHeader(FreemarkerConstants.FREEMARKER_RESOURCE_URI).constant("path/to/my/template.ftl").
  to("freemarker:dummy");

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

Dear ${headers.lastName}, ${headers.firstName}

Thanks for the order of ${headers.item}.

Regards Camel Riders Bookstore
${body}

And the java code:

103.9. See Also

Configuring Camel
Component
Endpoint
Getting Started

Chapter 104. FTP Component

Available as of Camel version 1.1

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

When consuming from remote FTP server make sure you read the section titled Default when consuming files further below for details related to consuming files.

Absolute path is not supported. Camel 2.16 will translate absolute path to relative by trimming all leading slashes from directoryname. There’ll be WARN message printed in the logs.

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

<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-ftp</artifactId>
    <version>x.x.x</version>See the documentation of the Apache Commons
    <!-- use the same version as your Camel core version -->
</dependency>

104.1. URI format

ftp://[username@]hostname[:port]/directoryname[?options]
sftp://[username@]hostname[:port]/directoryname[?options]
ftps://[username@]hostname[:port]/directoryname[?options]

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

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

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

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

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

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

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

104.2. URI Options

The options below are exclusive for the FTP component.

The FTP component has no options.

The FTP endpoint is configured using URI syntax:

ftp:host:port/directoryName

with the following path and query parameters:

104.2.1. Path Parameters (3 parameters):

Name	Description	Type
host	Required Hostname of the FTP server	String
port	Port of the FTP server	int
directoryName	The starting directory	String

104.2.2. Query Parameters (108 parameters):

Name	Description	Default	Type
binary (common)	Specifies the file transfer mode, BINARY or ASCII. Default is ASCII (false).	false	boolean
charset (common)	This option is used to specify the encoding of the file. 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. Do mind that when writing the file Camel may have to read the message content into memory to be able to convert the data into the configured charset, so do not use this if you have big messages.		String
disconnect (common)	Whether or not to disconnect from remote FTP server right after use. 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.	false	boolean
doneFileName (common)	Producer: 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. Consumer: 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. Only $file.name and $file.name.noext is supported as dynamic placeholders.		String
fileName (common)	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. 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.		String
passiveMode (common)	Sets passive mode connections. Default is active mode connections.	false	boolean
separator (common)	Sets the path separator to be used. UNIX = Uses unix style path separator Windows = Uses windows style path separator Auto = (is default) Use existing path separator in file name	UNIX	PathSeparator
transferLoggingInterval Seconds (common)	Configures the interval in seconds to use when logging the progress of upload and download operations that are in-flight. This is used for logging progress when operations takes longer time.	5	int
transferLoggingLevel (common)	Configure the logging level to use when logging the progress of upload and download operations.	DEBUG	LoggingLevel
transferLoggingVerbose (common)	Configures whether the perform verbose (fine grained) logging of the progress of upload and download operations.	false	boolean
fastExistsCheck (common)	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. 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.	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
delete (consumer)	If true, the file will be deleted after it is processed successfully.	false	boolean
moveFailed (consumer)	Sets the move failure expression based on Simple language. 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.		String
noop (consumer)	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.	false	boolean
preMove (consumer)	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.		String
preSort (consumer)	When pre-sort is enabled then the consumer will sort the file and directory names during polling, that was retrieved from the file system. You may want to do this in case you need to operate on the files in a sorted order. The pre-sort is executed before the consumer starts to filter, and accept files to process by Camel. This option is default=false meaning disabled.	false	boolean
recursive (consumer)	If a directory, will look for files in all the sub-directories as well.	false	boolean
resumeDownload (consumer)	Configures whether resume download is enabled. This must be supported by the FTP server (almost all FTP servers support it). In addition the options localWorkDirectory must be configured so downloaded files are stored in a local directory, and the option binary must be enabled, which is required to support resuming of downloads.	false	boolean
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
streamDownload (consumer)	Sets the download method to use when not using a local working directory. If set to true, the remote files are streamed to the route as they are read. When set to false, the remote files are loaded into memory before being sent into the route.	false	boolean
directoryMustExist (consumer)	Similar to startingDirectoryMustExist but this applies during polling recursive sub directories.	false	boolean
download (consumer)	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.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
handleDirectoryParser AbsoluteResult (consumer)	Allows you to set how the consumer will handle subfolders and files in the path if the directory parser results in with absolute paths The reason for this is that some FTP servers may return file names with absolute paths, and if so then the FTP component needs to handle this by converting the returned path into a relative path.	false	boolean
ignoreFileNotFoundOr PermissionError (consumer)	Whether to ignore when (trying to list files in directories or when downloading a file), which does not exist or due to permission error. By default when a directory or file does not exists or insufficient permission, then an exception is thrown. Setting this option to true allows to ignore that instead.	false	boolean
inProgressRepository (consumer)	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.		String>
localWorkDirectory (consumer)	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.		String
onCompletionException Handler (consumer)	To use a custom org.apache.camel.spi.ExceptionHandler to handle any thrown exceptions that happens during the file on completion process where the consumer does either a commit or rollback. The default implementation will log any exception at WARN level and ignore.		ExceptionHandler
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
processStrategy (consumer)	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.		GenericFileProcess Strategy<T>
receiveBufferSize (consumer)	The receive (download) buffer size Used only by FTPClient	32768	int
startingDirectoryMustExist (consumer)	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.	false	boolean
useList (consumer)	Whether to allow using LIST command when downloading a file. Default is true. In some use cases you may want to download a specific file and are not allowed to use the LIST command, and therefore you can set this option to false. Notice when using this option, then the specific file to download does not include meta-data information such as file size, timestamp, permissions etc, because those information is only possible to retrieve when LIST command is in use.	true	boolean
fileExist (producer)	What to do if a file already exists with the same name. 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. Move - option requires to use the 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 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.	Override	GenericFileExist
flatten (producer)	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 in CamelFileName header will be stripped for any leading paths.	false	boolean
moveExisting (producer)	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.		String
tempFileName (producer)	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.		String
tempPrefix (producer)	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.		String
allowNullBody (producer)	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.	false	boolean
chmod (producer)	Allows you to set chmod on the stored file. For example chmod=640.		String
disconnectOnBatchComplete (producer)	Whether or not to disconnect from remote FTP server right after a Batch upload is complete. disconnectOnBatchComplete will only disconnect the current connection to the FTP server.	false	boolean
eagerDeleteTargetFile (producer)	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. 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 copyAndDeleteOnRenameFails 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.	true	boolean
keepLastModified (producer)	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.	false	boolean
sendNoop (producer)	Whether to send a noop command as a pre-write check before uploading files to the FTP server. This is enabled by default as a validation of the connection is still valid, which allows to silently re-connect to be able to upload the file. However if this causes problems, you can turn this option off.	true	boolean
activePortRange (advanced)	Set the client side port range in active mode. The syntax is: minPort-maxPort Both port numbers are inclusive, eg 10000-19999 to include all 1xxxx ports.		String
autoCreate (advanced)	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.	true	boolean
bufferSize (advanced)	Write buffer sized in bytes.	131072	int
connectTimeout (advanced)	Sets the connect timeout for waiting for a connection to be established Used by both FTPClient and JSCH	10000	int
ftpClient (advanced)	To use a custom instance of FTPClient		FTPClient
ftpClientConfig (advanced)	To use a custom instance of FTPClientConfig to configure the FTP client the endpoint should use.		FTPClientConfig
ftpClientConfigParameters (advanced)	Used by FtpComponent to provide additional parameters for the FTPClientConfig		Map
ftpClientParameters (advanced)	Used by FtpComponent to provide additional parameters for the FTPClient		Map
maximumReconnectAttempts (advanced)	Specifies the maximum reconnect attempts Camel performs when it tries to connect to the remote FTP server. Use 0 to disable this behavior.		int
reconnectDelay (advanced)	Delay in millis Camel will wait before performing a reconnect attempt.		long
siteCommand (advanced)	Sets optional site command(s) to be executed after successful login. Multiple site commands can be separated using a new line character.		String
soTimeout (advanced)	Sets the so timeout Used only by FTPClient	300000	int
stepwise (advanced)	Sets whether we should stepwise change directories while traversing file structures when downloading files, or as well when uploading a file to a directory. You can disable this if you for example are in a situation where you cannot change directory on the FTP server due security reasons.	true	boolean
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
throwExceptionOnConnect Failed (advanced)	Should an exception be thrown if connection failed (exhausted) By default exception is not thrown and a WARN is logged. You can use this to enable exception being thrown and handle the thrown exception from the org.apache.camel.spi.PollingConsumerPollStrategy rollback method.	false	boolean
timeout (advanced)	Sets the data timeout for waiting for reply Used only by FTPClient	30000	int
antExclude (filter)	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.		String
antFilterCaseSensitive (filter)	Sets case sensitive flag on ant filter	true	boolean
antInclude (filter)	Ant style filter inclusion. Multiple inclusions may be specified in comma-delimited format.		String
eagerMaxMessagesPerPoll (filter)	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.	true	boolean
exclude (filter)	Is used to exclude files, if filename matches the regex pattern (matching is case in-senstive). Notice if you use symbols such as plus sign and others you would need to configure this using the RAW() syntax if configuring this as an endpoint uri. See more details at configuring endpoint uris		String
filter (filter)	Pluggable filter as a org.apache.camel.component.file.GenericFileFilter class. Will skip files if filter returns false in its accept() method.		GenericFileFilter<T>
filterDirectory (filter)	Filters the directory based on Simple language. For example to filter on current date, you can use a simple date pattern such as $date:now:yyyMMdd		String
filterFile (filter)	Filters the file based on Simple language. For example to filter on file size, you can use $file:size 5000		String
idempotent (filter)	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.	false	Boolean
idempotentKey (filter)	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: idempotentKey=$file:name-$file:size		String
idempotentRepository (filter)	A pluggable repository org.apache.camel.spi.IdempotentRepository which by default use MemoryMessageIdRepository if none is specified and idempotent is true.		String>
include (filter)	Is used to include files, if filename matches the regex pattern (matching is case in-sensitive). Notice if you use symbols such as plus sign and others you would need to configure this using the RAW() syntax if configuring this as an endpoint uri. See more details at configuring endpoint uris		String
maxDepth (filter)	The maximum depth to traverse when recursively processing a directory.	2147483647	int
maxMessagesPerPoll (filter)	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. 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.		int
minDepth (filter)	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.		int
move (filter)	Expression (such as Simple Language) used to dynamically set the filename when moving it after processing. To move files into a .done subdirectory just enter .done.		String
exclusiveReadLockStrategy (lock)	Pluggable read-lock as a org.apache.camel.component.file.GenericFileExclusiveReadLockStrategy implementation.		GenericFileExclusive ReadLockStrategy<T>
readLock (lock)	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: none - No read lock is in use 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 - 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. 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 - rename is for using a try to rename the file as a test if we can get exclusive read-lock. idempotent - (only for file component) idempotent is for using a idempotentRepository as the read-lock. This allows to use read locks that supports clustering if the idempotent repository implementation supports that. idempotent-changed - (only for file component) idempotent-changed is for using a idempotentRepository and changed as the combined read-lock. This allows to use read locks that supports clustering if the idempotent repository implementation supports that. idempotent-rename - (only for file component) idempotent-rename is for using a idempotentRepository and rename as the combined read-lock. This allows to use read locks that supports clustering if the idempotent repository implementation supports that. Notice: The various read locks is not all suited to work in clustered mode, where concurrent consumers on different nodes is competing for the same files on a shared file system. The markerFile using a close to atomic operation to create the empty marker file, but its not guaranteed to work in a cluster. The fileLock may work better but then the file system need to support distributed file locks, and so on. Using the idempotent read lock can support clustering if the idempotent repository supports clustering, such as Hazelcast Component or Infinispan.	none	String
readLockCheckInterval (lock)	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. Notice: For FTP the default readLockCheckInterval is 5000. The readLockTimeout value must be higher than readLockCheckInterval, but a rule of thumb is to have a timeout that is at least 2 or more times higher than the readLockCheckInterval. This is needed to ensure that amble time is allowed for the read lock process to try to grab the lock before the timeout was hit.	1000	long
readLockDeleteOrphanLock Files (lock)	Whether or not read lock with marker files should upon startup delete any orphan read lock files, which may have been left on the file system, if Camel was not properly shutdown (such as a JVM crash). If turning this option to false then any orphaned lock file will cause Camel to not attempt to pickup that file, this could also be due another node is concurrently reading files from the same shared directory.	true	boolean
readLockLoggingLevel (lock)	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, idempotent, idempotent-changed, idempotent-rename, rename.	DEBUG	LoggingLevel
readLockMarkerFile (lock)	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.	true	boolean
readLockMinAge (lock)	This option applied only for readLock=change. This option allows to specify a minimum age the file must be before attempting to acquire the read lock. For example use readLockMinAge=300s to require the file is at last 5 minutes old. This can speedup the changed read lock as it will only attempt to acquire files which are at least that given age.	0	long
readLockMinLength (lock)	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.	1	long
readLockRemoveOnCommit (lock)	This option applied only for readLock=idempotent. This option allows to specify whether to remove the file name entry from the idempotent repository when processing the file is succeeded and a commit happens. By default the file is not removed which ensures that any race-condition do not occur so another active node may attempt to grab the file. Instead the idempotent repository may support eviction strategies that you can configure to evict the file name entry after X minutes - this ensures no problems with race conditions.	false	boolean
readLockRemoveOnRollback (lock)	This option applied only for readLock=idempotent. This option allows to specify whether to remove the file name entry from the idempotent repository when processing the file failed and a rollback happens. If this option is false, then the file name entry is confirmed (as if the file did a commit).	true	boolean
readLockTimeout (lock)	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. Currently fileLock, changed and rename support the timeout. Notice: For FTP the default readLockTimeout value is 20000 instead of 10000. The readLockTimeout value must be higher than readLockCheckInterval, but a rule of thumb is to have a timeout that is at least 2 or more times higher than the readLockCheckInterval. This is needed to ensure that amble time is allowed for the read lock process to try to grab the lock before the timeout was hit.	10000	long
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean
shuffle (sort)	To shuffle the list of files (sort in random order)	false	boolean
sortBy (sort)	Built-in sort by 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.		String
sorter (sort)	Pluggable sorter as a java.util.Comparator class.		GenericFile<T>>
account (security)	Account to use for login		String
password (security)	Password to use for login		String
username (security)	Username to use for login		String

104.3. FTPS component default trust store

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:

from("ftp://foo@myserver?password=secret&ftpClient.dataTimeout=30000").to("bean:foo");

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

from("ftp://foo@myserver?password=secret&ftpClient.dataTimeout=30000&ftpClientConfig.serverLanguageCode=fr").to("bean:foo");

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:

   <bean id="myConfig" class="org.apache.commons.net.ftp.FTPClientConfig">
       <property name="lenientFutureDates" value="true"/>
       <property name="serverLanguageCode" value="fr"/>
   </bean>

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

from("ftp://foo@myserver?password=secret&ftpClientConfig=#myConfig").to("bean:foo");

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

104.5. Concurrency

FTP Consumer does not support concurrency

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.

104.6. More information

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

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

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

104.8. 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 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.
`CamelFileIndex`	Current index out of total number of files being consumed in this batch.
`CamelFileSize`	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

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

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

from("ftp://someone@someserver.com?password=secret&localWorkDirectory=/tmp").to("file://inbox");

Tip

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.

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

/
/one
/one/two
/one/two/sub-a
/one/two/sub-b

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

104.11.1. Using stepwise=true (default mode)

TYPE A
200 Type set to A
PWD
257 "/" is current directory.
CWD one
250 CWD successful. "/one" is current directory.
CWD two
250 CWD successful. "/one/two" is current directory.
SYST
215 UNIX emulated by FileZilla
PORT 127,0,0,1,17,94
200 Port command successful
LIST
150 Opening data channel for directory list.
226 Transfer OK
CWD sub-a
250 CWD successful. "/one/two/sub-a" is current directory.
PORT 127,0,0,1,17,95
200 Port command successful
LIST
150 Opening data channel for directory list.
226 Transfer OK
CDUP
200 CDUP successful. "/one/two" is current directory.
CWD sub-b
250 CWD successful. "/one/two/sub-b" is current directory.
PORT 127,0,0,1,17,96
200 Port command successful
LIST
150 Opening data channel for directory list.
226 Transfer OK
CDUP
200 CDUP successful. "/one/two" is current directory.
CWD /
250 CWD successful. "/" is current directory.
PWD
257 "/" is current directory.
CWD one
250 CWD successful. "/one" is current directory.
CWD two
250 CWD successful. "/one/two" is current directory.
PORT 127,0,0,1,17,97
200 Port command successful
RETR foo.txt
150 Opening data channel for file transfer.
226 Transfer OK
CWD /
250 CWD successful. "/" is current directory.
PWD
257 "/" is current directory.
CWD one
250 CWD successful. "/one" is current directory.
CWD two
250 CWD successful. "/one/two" is current directory.
CWD sub-a
250 CWD successful. "/one/two/sub-a" is current directory.
PORT 127,0,0,1,17,98
200 Port command successful
RETR a.txt
150 Opening data channel for file transfer.
226 Transfer OK
CWD /
250 CWD successful. "/" is current directory.
PWD
257 "/" is current directory.
CWD one
250 CWD successful. "/one" is current directory.
CWD two
250 CWD successful. "/one/two" is current directory.
CWD sub-b
250 CWD successful. "/one/two/sub-b" is current directory.
PORT 127,0,0,1,17,99
200 Port command successful
RETR b.txt
150 Opening data channel for file transfer.
226 Transfer OK
CWD /
250 CWD successful. "/" is current directory.
QUIT
221 Goodbye
disconnected.

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

104.11.2. Using stepwise=false

230 Logged on
TYPE A
200 Type set to A
SYST
215 UNIX emulated by FileZilla
PORT 127,0,0,1,4,122
200 Port command successful
LIST one/two
150 Opening data channel for directory list
226 Transfer OK
PORT 127,0,0,1,4,123
200 Port command successful
LIST one/two/sub-a
150 Opening data channel for directory list
226 Transfer OK
PORT 127,0,0,1,4,124
200 Port command successful
LIST one/two/sub-b
150 Opening data channel for directory list
226 Transfer OK
PORT 127,0,0,1,4,125
200 Port command successful
RETR one/two/foo.txt
150 Opening data channel for file transfer.
226 Transfer OK
PORT 127,0,0,1,4,126
200 Port command successful
RETR one/two/sub-a/a.txt
150 Opening data channel for file transfer.
226 Transfer OK
PORT 127,0,0,1,4,127
200 Port command successful
RETR one/two/sub-b/b.txt
150 Opening data channel for file transfer.
226 Transfer OK
QUIT
221 Goodbye
disconnected.

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

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

  <route>
     <from uri="ftp://scott@localhost/public/reports?password=tiger&amp;binary=true&amp;delay=60000"/>
     <to uri="file://target/test-reports"/>
  </route>

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

from("ftps://admin@localhost:2222/public/camel?password=admin&securityProtocol=SSL&isImplicit=true
      &ftpClient.keyStore.file=./src/test/resources/server.jks
      &ftpClient.keyStore.password=password&ftpClient.keyStore.keyPassword=password")
  .to("bean:foo");

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

from("ftps://admin@localhost:2222/public/camel?password=admin&ftpClient.trustStore.file=./src/test/resources/server.jks&ftpClient.trustStore.password=password")
  .to("bean:foo");

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

   <!-- define our sorter as a plain spring bean -->
   <bean id="myFilter" class="com.mycompany.MyFileFilter"/>

  <route>
    <from uri="ftp://someuser@someftpserver.com?password=secret&amp;filter=#myFilter"/>
    <to uri="bean:processInbox"/>
  </route>

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

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

<!-- define our sorter as a plain spring bean -->
<bean id="proxy" class="com.jcraft.jsch.ProxyHTTP">
  <constructor-arg value="localhost"/>
  <constructor-arg value="7777"/>
</bean>

<route>
  <from uri="sftp://localhost:9999/root?username=admin&password=admin&proxy=#proxy"/>
  <to uri="bean:processFile"/>
</route>

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.

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

from("sftp://localhost:9999/root?username=admin&password=admin&preferredAuthentications=publickey,password").
  to("bean:processFile");

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

from("ftp://admin@localhost:21/nolist/?password=admin&stepwise=false&useList=false&ignoreFileNotFoundOrPermissionError=true&fileName=report.txt&delete=true")
  .to("activemq:queue:report");

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:

String data = template.retrieveBodyNoWait("ftp://admin@localhost:21/nolist/?password=admin&stepwise=false&useList=false&ignoreFileNotFoundOrPermissionError=true&fileName=report.txt&delete=true", String.class);

104.18. Debug logging

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

104.19. See Also

Configuring Camel
Component
Endpoint
Getting Started
File2

Chapter 105. FTPS Component

Available as of Camel version 2.2

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:

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

For more information you can look at FTP component

105.1. URI Options

The options below are exclusive for the FTPS component.

The FTPS component supports 2 options which are listed below.

Name	Description	Default	Type
useGlobalSslContext Parameters (security)	Enable usage of global SSL context parameters.	false	boolean
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The FTPS endpoint is configured using URI syntax:

ftps:host:port/directoryName

with the following path and query parameters:

105.1.1. Path Parameters (3 parameters):

Name	Description	Type
host	Required Hostname of the FTP server	String
port	Port of the FTP server	int
directoryName	The starting directory	String

105.1.2. Query Parameters (116 parameters):

Name	Description	Default	Type
binary (common)	Specifies the file transfer mode, BINARY or ASCII. Default is ASCII (false).	false	boolean
charset (common)	This option is used to specify the encoding of the file. 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. Do mind that when writing the file Camel may have to read the message content into memory to be able to convert the data into the configured charset, so do not use this if you have big messages.		String
disconnect (common)	Whether or not to disconnect from remote FTP server right after use. 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.	false	boolean
doneFileName (common)	Producer: 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. Consumer: 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. Only $file.name and $file.name.noext is supported as dynamic placeholders.		String
fileName (common)	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. 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.		String
passiveMode (common)	Sets passive mode connections. Default is active mode connections.	false	boolean
separator (common)	Sets the path separator to be used. UNIX = Uses unix style path separator Windows = Uses windows style path separator Auto = (is default) Use existing path separator in file name	UNIX	PathSeparator
transferLoggingInterval Seconds (common)	Configures the interval in seconds to use when logging the progress of upload and download operations that are in-flight. This is used for logging progress when operations takes longer time.	5	int
transferLoggingLevel (common)	Configure the logging level to use when logging the progress of upload and download operations.	DEBUG	LoggingLevel
transferLoggingVerbose (common)	Configures whether the perform verbose (fine grained) logging of the progress of upload and download operations.	false	boolean
fastExistsCheck (common)	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. 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.	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
delete (consumer)	If true, the file will be deleted after it is processed successfully.	false	boolean
moveFailed (consumer)	Sets the move failure expression based on Simple language. 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.		String
noop (consumer)	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.	false	boolean
preMove (consumer)	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.		String
preSort (consumer)	When pre-sort is enabled then the consumer will sort the file and directory names during polling, that was retrieved from the file system. You may want to do this in case you need to operate on the files in a sorted order. The pre-sort is executed before the consumer starts to filter, and accept files to process by Camel. This option is default=false meaning disabled.	false	boolean
recursive (consumer)	If a directory, will look for files in all the sub-directories as well.	false	boolean
resumeDownload (consumer)	Configures whether resume download is enabled. This must be supported by the FTP server (almost all FTP servers support it). In addition the options localWorkDirectory must be configured so downloaded files are stored in a local directory, and the option binary must be enabled, which is required to support resuming of downloads.	false	boolean
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
streamDownload (consumer)	Sets the download method to use when not using a local working directory. If set to true, the remote files are streamed to the route as they are read. When set to false, the remote files are loaded into memory before being sent into the route.	false	boolean
directoryMustExist (consumer)	Similar to startingDirectoryMustExist but this applies during polling recursive sub directories.	false	boolean
download (consumer)	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.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
handleDirectoryParser AbsoluteResult (consumer)	Allows you to set how the consumer will handle subfolders and files in the path if the directory parser results in with absolute paths The reason for this is that some FTP servers may return file names with absolute paths, and if so then the FTP component needs to handle this by converting the returned path into a relative path.	false	boolean
ignoreFileNotFoundOr PermissionError (consumer)	Whether to ignore when (trying to list files in directories or when downloading a file), which does not exist or due to permission error. By default when a directory or file does not exists or insufficient permission, then an exception is thrown. Setting this option to true allows to ignore that instead.	false	boolean
inProgressRepository (consumer)	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.		String>
localWorkDirectory (consumer)	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.		String
onCompletionException Handler (consumer)	To use a custom org.apache.camel.spi.ExceptionHandler to handle any thrown exceptions that happens during the file on completion process where the consumer does either a commit or rollback. The default implementation will log any exception at WARN level and ignore.		ExceptionHandler
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
processStrategy (consumer)	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.		GenericFileProcess Strategy<T>
receiveBufferSize (consumer)	The receive (download) buffer size Used only by FTPClient	32768	int
startingDirectoryMustExist (consumer)	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.	false	boolean
useList (consumer)	Whether to allow using LIST command when downloading a file. Default is true. In some use cases you may want to download a specific file and are not allowed to use the LIST command, and therefore you can set this option to false. Notice when using this option, then the specific file to download does not include meta-data information such as file size, timestamp, permissions etc, because those information is only possible to retrieve when LIST command is in use.	true	boolean
fileExist (producer)	What to do if a file already exists with the same name. 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. Move - option requires to use the 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 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.	Override	GenericFileExist
flatten (producer)	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 in CamelFileName header will be stripped for any leading paths.	false	boolean
moveExisting (producer)	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.		String
tempFileName (producer)	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.		String
tempPrefix (producer)	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.		String
allowNullBody (producer)	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.	false	boolean
chmod (producer)	Allows you to set chmod on the stored file. For example chmod=640.		String
disconnectOnBatchComplete (producer)	Whether or not to disconnect from remote FTP server right after a Batch upload is complete. disconnectOnBatchComplete will only disconnect the current connection to the FTP server.	false	boolean
eagerDeleteTargetFile (producer)	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. 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 copyAndDeleteOnRenameFails 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.	true	boolean
keepLastModified (producer)	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.	false	boolean
sendNoop (producer)	Whether to send a noop command as a pre-write check before uploading files to the FTP server. This is enabled by default as a validation of the connection is still valid, which allows to silently re-connect to be able to upload the file. However if this causes problems, you can turn this option off.	true	boolean
activePortRange (advanced)	Set the client side port range in active mode. The syntax is: minPort-maxPort Both port numbers are inclusive, eg 10000-19999 to include all 1xxxx ports.		String
autoCreate (advanced)	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.	true	boolean
bufferSize (advanced)	Write buffer sized in bytes.	131072	int
connectTimeout (advanced)	Sets the connect timeout for waiting for a connection to be established Used by both FTPClient and JSCH	10000	int
ftpClient (advanced)	To use a custom instance of FTPClient		FTPClient
ftpClientConfig (advanced)	To use a custom instance of FTPClientConfig to configure the FTP client the endpoint should use.		FTPClientConfig
ftpClientConfigParameters (advanced)	Used by FtpComponent to provide additional parameters for the FTPClientConfig		Map
ftpClientParameters (advanced)	Used by FtpComponent to provide additional parameters for the FTPClient		Map
maximumReconnectAttempts (advanced)	Specifies the maximum reconnect attempts Camel performs when it tries to connect to the remote FTP server. Use 0 to disable this behavior.		int
reconnectDelay (advanced)	Delay in millis Camel will wait before performing a reconnect attempt.		long
siteCommand (advanced)	Sets optional site command(s) to be executed after successful login. Multiple site commands can be separated using a new line character.		String
soTimeout (advanced)	Sets the so timeout Used only by FTPClient	300000	int
stepwise (advanced)	Sets whether we should stepwise change directories while traversing file structures when downloading files, or as well when uploading a file to a directory. You can disable this if you for example are in a situation where you cannot change directory on the FTP server due security reasons.	true	boolean
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
throwExceptionOnConnect Failed (advanced)	Should an exception be thrown if connection failed (exhausted) By default exception is not thrown and a WARN is logged. You can use this to enable exception being thrown and handle the thrown exception from the org.apache.camel.spi.PollingConsumerPollStrategy rollback method.	false	boolean
timeout (advanced)	Sets the data timeout for waiting for reply Used only by FTPClient	30000	int
antExclude (filter)	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.		String
antFilterCaseSensitive (filter)	Sets case sensitive flag on ant filter	true	boolean
antInclude (filter)	Ant style filter inclusion. Multiple inclusions may be specified in comma-delimited format.		String
eagerMaxMessagesPerPoll (filter)	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.	true	boolean
exclude (filter)	Is used to exclude files, if filename matches the regex pattern (matching is case in-senstive). Notice if you use symbols such as plus sign and others you would need to configure this using the RAW() syntax if configuring this as an endpoint uri. See more details at configuring endpoint uris		String
filter (filter)	Pluggable filter as a org.apache.camel.component.file.GenericFileFilter class. Will skip files if filter returns false in its accept() method.		GenericFileFilter<T>
filterDirectory (filter)	Filters the directory based on Simple language. For example to filter on current date, you can use a simple date pattern such as $date:now:yyyMMdd		String
filterFile (filter)	Filters the file based on Simple language. For example to filter on file size, you can use $file:size 5000		String
idempotent (filter)	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.	false	Boolean
idempotentKey (filter)	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: idempotentKey=$file:name-$file:size		String
idempotentRepository (filter)	A pluggable repository org.apache.camel.spi.IdempotentRepository which by default use MemoryMessageIdRepository if none is specified and idempotent is true.		String>
include (filter)	Is used to include files, if filename matches the regex pattern (matching is case in-sensitive). Notice if you use symbols such as plus sign and others you would need to configure this using the RAW() syntax if configuring this as an endpoint uri. See more details at configuring endpoint uris		String
maxDepth (filter)	The maximum depth to traverse when recursively processing a directory.	2147483647	int
maxMessagesPerPoll (filter)	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. 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.		int
minDepth (filter)	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.		int
move (filter)	Expression (such as Simple Language) used to dynamically set the filename when moving it after processing. To move files into a .done subdirectory just enter .done.		String
exclusiveReadLockStrategy (lock)	Pluggable read-lock as a org.apache.camel.component.file.GenericFileExclusiveReadLockStrategy implementation.		GenericFileExclusive ReadLockStrategy<T>
readLock (lock)	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: none - No read lock is in use 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 - 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. 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 - rename is for using a try to rename the file as a test if we can get exclusive read-lock. idempotent - (only for file component) idempotent is for using a idempotentRepository as the read-lock. This allows to use read locks that supports clustering if the idempotent repository implementation supports that. idempotent-changed - (only for file component) idempotent-changed is for using a idempotentRepository and changed as the combined read-lock. This allows to use read locks that supports clustering if the idempotent repository implementation supports that. idempotent-rename - (only for file component) idempotent-rename is for using a idempotentRepository and rename as the combined read-lock. This allows to use read locks that supports clustering if the idempotent repository implementation supports that. Notice: The various read locks is not all suited to work in clustered mode, where concurrent consumers on different nodes is competing for the same files on a shared file system. The markerFile using a close to atomic operation to create the empty marker file, but its not guaranteed to work in a cluster. The fileLock may work better but then the file system need to support distributed file locks, and so on. Using the idempotent read lock can support clustering if the idempotent repository supports clustering, such as Hazelcast Component or Infinispan.	none	String
readLockCheckInterval (lock)	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. Notice: For FTP the default readLockCheckInterval is 5000. The readLockTimeout value must be higher than readLockCheckInterval, but a rule of thumb is to have a timeout that is at least 2 or more times higher than the readLockCheckInterval. This is needed to ensure that amble time is allowed for the read lock process to try to grab the lock before the timeout was hit.	1000	long
readLockDeleteOrphanLock Files (lock)	Whether or not read lock with marker files should upon startup delete any orphan read lock files, which may have been left on the file system, if Camel was not properly shutdown (such as a JVM crash). If turning this option to false then any orphaned lock file will cause Camel to not attempt to pickup that file, this could also be due another node is concurrently reading files from the same shared directory.	true	boolean
readLockLoggingLevel (lock)	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, idempotent, idempotent-changed, idempotent-rename, rename.	DEBUG	LoggingLevel
readLockMarkerFile (lock)	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.	true	boolean
readLockMinAge (lock)	This option applied only for readLock=change. This option allows to specify a minimum age the file must be before attempting to acquire the read lock. For example use readLockMinAge=300s to require the file is at last 5 minutes old. This can speedup the changed read lock as it will only attempt to acquire files which are at least that given age.	0	long
readLockMinLength (lock)	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.	1	long
readLockRemoveOnCommit (lock)	This option applied only for readLock=idempotent. This option allows to specify whether to remove the file name entry from the idempotent repository when processing the file is succeeded and a commit happens. By default the file is not removed which ensures that any race-condition do not occur so another active node may attempt to grab the file. Instead the idempotent repository may support eviction strategies that you can configure to evict the file name entry after X minutes - this ensures no problems with race conditions.	false	boolean
readLockRemoveOnRollback (lock)	This option applied only for readLock=idempotent. This option allows to specify whether to remove the file name entry from the idempotent repository when processing the file failed and a rollback happens. If this option is false, then the file name entry is confirmed (as if the file did a commit).	true	boolean
readLockTimeout (lock)	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. Currently fileLock, changed and rename support the timeout. Notice: For FTP the default readLockTimeout value is 20000 instead of 10000. The readLockTimeout value must be higher than readLockCheckInterval, but a rule of thumb is to have a timeout that is at least 2 or more times higher than the readLockCheckInterval. This is needed to ensure that amble time is allowed for the read lock process to try to grab the lock before the timeout was hit.	10000	long
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean
shuffle (sort)	To shuffle the list of files (sort in random order)	false	boolean
sortBy (sort)	Built-in sort by 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.		String
sorter (sort)	Pluggable sorter as a java.util.Comparator class.		GenericFile<T>>
account (security)	Account to use for login		String
disableSecureDataChannel Defaults (security)	Use this option to disable default options when using secure data channel. This allows you to be in full control what the execPbsz and execProt setting should be used. Default is false	false	boolean
execPbsz (security)	When using secure data channel you can set the exec protection buffer size		Long
execProt (security)	The exec protection level PROT command. C - Clear S - Safe(SSL protocol only) E - Confidential(SSL protocol only) P - Private		String
ftpClientKeyStore Parameters (security)	Set the key store parameters		Map
ftpClientTrustStore Parameters (security)	Set the trust store parameters		Map
isImplicit (security)	Set the security mode(Implicit/Explicit). true - Implicit Mode / False - Explicit Mode	false	boolean
password (security)	Password to use for login		String
securityProtocol (security)	Set the underlying security protocol.	TLS	String
sslContextParameters (security)	Gets the JSSE configuration that overrides any settings in link FtpsEndpointftpClientKeyStoreParameters, link ftpClientTrustStoreParameters, and link FtpsConfigurationgetSecurityProtocol().		SSLContextParameters
username (security)	Username to use for login		String

Chapter 106. Ganglia Component

Available as of Camel version 2.15

Provides a mechanism to send a value (the message body) as a metric to the Ganglia monitoring system. Uses the gmetric4j library. Can be used in conjunction with standard Ganglia and JMXetric for monitoring metrics from the OS, JVM and business processes through a single platform.

You should have a Ganglia gmond agent running on the machine where your JVM runs. The gmond sends a heartbeat to the Ganglia infrastructure, camel-ganglia can’t send the heartbeat itself currently.

On most Linux systems (Debian, Ubuntu, Fedora and RHEL/CentOS with EPEL) you can just install the Ganglia agent package and it runs automatically using multicast configuration. You can configure it to use regular UDP unicast if you prefer.

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

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

106.1. URI format

ganglia:address:port[?options]

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

106.2. Ganglia component and endpoint URI options

The Ganglia component supports 2 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	To use the shared configuration		GangliaConfiguration
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Ganglia endpoint is configured using URI syntax:

ganglia:host:port

with the following path and query parameters:

106.2.1. Path Parameters (2 parameters):

Name	Description	Default	Type
host	Host name for Ganglia server	239.2.11.71	String
port	Port for Ganglia server	8649	int

106.2.2. Query Parameters (13 parameters):

Name	Description	Default	Type
dmax (producer)	Minumum time in seconds before Ganglia will purge the metric value if it expires. Set to 0 and the value will remain in Ganglia indefinitely until a gmond agent restart.	0	int
groupName (producer)	The group that the metric belongs to.	java	String
metricName (producer)	The name to use for the metric.	metric	String
mode (producer)	Send the UDP metric packets using MULTICAST or UNICAST	MULTICAST	UDPAddressingMode
prefix (producer)	Prefix the metric name with this string and an underscore.		String
slope (producer)	The slope	BOTH	GMetricSlope
spoofHostname (producer)	Spoofing information IP:hostname		String
tmax (producer)	Maximum time in seconds that the value can be considered current. After this, Ganglia considers the value to have expired.	60	int
ttl (producer)	If using multicast, set the TTL of the packets	5	int
type (producer)	The type of value	STRING	GMetricType
units (producer)	Any unit of measurement that qualifies the metric, e.g. widgets, litres, bytes. Do not include a prefix such as k (kilo) or m (milli), other tools may scale the units later. The value should be unscaled.		String
wireFormat31x (producer)	Use the wire format of Ganglia 3.1.0 and later versions. Set this to false to use Ganglia 3.0.x or earlier.	true	boolean
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

106.3. Message body

Any value (such as a string or numeric type) in the body is sent to the Ganglia system.

106.4. Return value / response

Ganglia sends metrics using unidirectional UDP or multicast. There is no response or change to the message body.

106.5. Examples

106.5.1. Sending a String metric

The message body will be converted to a String and sent as a metric value. Unlike numeric metrics, String values can’t be charted but Ganglia makes them available for reporting. The os_version string at the top of every Ganglia host page is an example of a String metric.

from("direct:string.for.ganglia")
    .setHeader(GangliaConstants.METRIC_NAME, simple("my_string_metric"))
    .setHeader(GangliaConstants.METRIC_TYPE, GMetricType.STRING)
    .to("direct:ganglia.tx");

from("direct:ganglia.tx")
    .to("ganglia:239.2.11.71:8649?mode=MULTICAST&prefix=test");

106.5.2. Sending a numeric metric

from("direct:value.for.ganglia")
    .setHeader(GangliaConstants.METRIC_NAME, simple("widgets_in_stock"))
    .setHeader(GangliaConstants.METRIC_TYPE, GMetricType.UINT32)
    .setHeader(GangliaConstants.METRIC_UNITS, simple("widgets"))
    .to("direct:ganglia.tx");

from("direct:ganglia.tx")
    .to("ganglia:239.2.11.71:8649?mode=MULTICAST&prefix=test");

Chapter 107. Geocoder Component

Available as of Camel version 2.12

The geocoder: component is used for looking up geocodes (latitude and longitude) for a given address, or reverse lookup. The component uses the Java API for Google Geocoder library.

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

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

107.1. URI format

geocoder:address:name[?options]
geocoder:latlng:latitude,longitude[?options]

107.2. Options

The Geocoder component has no options.

The Geocoder endpoint is configured using URI syntax:

geocoder:address:latlng

with the following path and query parameters:

107.2.1. Path Parameters (2 parameters):

Name	Description	Default	Type
address	The geo address which should be prefixed with address:		String
latlng	The geo latitude and longitude which should be prefixed with latlng:		String

107.2.2. Query Parameters (14 parameters):

Name	Description	Default	Type
clientId (producer)	To use google premium with this client id		String
clientKey (producer)	To use google premium with this client key		String
headersOnly (producer)	Whether to only enrich the Exchange with headers, and leave the body as-is.	false	boolean
language (producer)	The language to use.	en	String
httpClientConfigurer (advanced)	Register a custom configuration strategy for new HttpClient instances created by producers or consumers such as to configure authentication mechanisms etc		HttpClientConfigurer
httpConnectionManager (advanced)	To use a custom HttpConnectionManager to manage connections		HttpConnectionManager
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
proxyAuthDomain (proxy)	Domain for proxy NTML authentication		String
proxyAuthHost (proxy)	Optional host for proxy NTML authentication		String
proxyAuthMethod (proxy)	Authentication method for proxy, either as Basic, Digest or NTLM.		String
proxyAuthPassword (proxy)	Password for proxy authentication		String
proxyAuthUsername (proxy)	Username for proxy authentication		String
proxyHost (proxy)	The proxy host name		String
proxyPort (proxy)	The proxy port number		Integer

107.3. Exchange data format

Camel will deliver the body as a com.google.code.geocoder.model.GeocodeResponse type.
And if the address is "current" then the response is a String type with a JSON representation of the current location.

If the option headersOnly is set to true then the message body is left as-is, and only headers will be added to the Exchange.

107.4. Message Headers

Header	Description
`CamelGeoCoderStatus`	Mandatory. Status code from the geocoder library. If status is `GeocoderStatus.OK` then additional headers is enriched
`CamelGeoCoderAddress`	The formatted address
`CamelGeoCoderLat`	The latitude of the location.
`CamelGeoCoderLng`	The longitude of the location.
`CamelGeoCoderLatlng`	The latitude and longitude of the location. Separated by comma.
`CamelGeoCoderCity`	The city long name.
`CamelGeoCoderRegionCode`	The region code.
`CamelGeoCoderRegionName`	The region name.
`CamelGeoCoderCountryLong`	The country long name.
`CamelGeoCoderCountryShort`	The country short name.

Notice not all headers may be provided depending on available data and mode in use (address vs latlng).

107.5. Samples

In the example below we get the latitude and longitude for Paris, France

  from("direct:start")
    .to("geocoder:address:Paris, France")

If you provide a header with the CamelGeoCoderAddress then that overrides the endpoint configuration, so to get the location of Copenhagen, Denmark we can send a message with a headers as shown:

template.sendBodyAndHeader("direct:start", "Hello", GeoCoderConstants.ADDRESS, "Copenhagen, Denmark");

To get the address for a latitude and longitude we can do:

  from("direct:start")
    .to("geocoder:latlng:40.714224,-73.961452")
    .log("Location ${header.CamelGeocoderAddress} is at lat/lng: ${header.CamelGeocoderLatlng} and in country ${header.CamelGeoCoderCountryShort}")

Which will log

Location 285 Bedford Avenue, Brooklyn, NY 11211, USA is at lat/lng: 40.71412890,-73.96140740 and in country US

To get the current location you can use "current" as the address as shown:

  from("direct:start")
    .to("geocoder:address:current")

Chapter 108. Git Component

Available as of Camel version 2.16

The git: component allows you to work with a generic Git repository.

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

URI Format

git://localRepositoryPath[?options]

108.1. URI Options

The producer allows to do operations on a specific repository.
The consumer allows consuming commits, tags and branches on a specific repository.

The Git component has no options.

The Git endpoint is configured using URI syntax:

git:localPath

with the following path and query parameters:

108.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
localPath	Required Local repository path		String

108.1.2. Query Parameters (13 parameters):

Name	Description	Default	Type
branchName (common)	The branch name to work on		String
password (common)	Remote repository password		String
remoteName (common)	The remote repository name to use in particular operation like pull		String
remotePath (common)	The remote repository path		String
tagName (common)	The tag name to work on		String
username (common)	Remote repository username		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
type (consumer)	The consumer type		GitType
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
allowEmpty (producer)	The flag to manage empty git commits	true	boolean
operation (producer)	The operation to do on the repository		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

108.2. Message Headers

Name	Default Value	Type	Context	Description
CamelGitOperation	`null`	String	Producer	The operation to do on a repository, if not specified as endpoint option
CamelGitFilename	`null`	String	Producer	The file name in an add operation
CamelGitCommitMessage	`null`	String	Producer	The commit message related in a commit operation
CamelGitCommitUsername	`null`	String	Producer	The commit username in a commit operation
CamelGitCommitEmail	`null`	String	Producer	The commit email in a commit operation
CamelGitCommitId	`null`	String	Producer	The commit id
CamelGitAllowEmpty	`null`	Boolean	Producer	The flag to manage empty git commits

108.3. Producer Example

Below is an example route of a producer that add a file test.java to a local repository, commit it with a specific message on master branch and then push it to remote repository.

from("direct:start")
        .setHeader(GitConstants.GIT_FILE_NAME, constant("test.java"))
        .to("git:///tmp/testRepo?operation=add")
        .setHeader(GitConstants.GIT_COMMIT_MESSAGE, constant("first commit"))
        .to("git:///tmp/testRepo?operation=commit")
        .to("git:///tmp/testRepo?operation=push&remotePath=https://foo.com/test/test.git&username=xxx&password=xxx")

108.4. Consumer Example

Below is an example route of a consumer that consumes commit:

from("git:///tmp/testRepo?type=commit")
                        .to(....)

Chapter 109. GitHub Component

Available as of Camel version 2.15

The GitHub component interacts with the GitHub API by encapsulating http://org.eclipse.egit.github.core[egit-github]. It currently provides polling for new pull requests, pull request comments, tags, and commits. It is also able to produce comments on pull requests, as well as close the pull request entirely.

Rather than webhooks, this endpoint relies on simple polling. Reasons include:

Concern for reliability/stability
The types of payloads we’re polling aren’t typically large (plus, paging is available in the API)
The need to support apps running somewhere not publicly accessible where a webhook would fail

Note that the GitHub API is fairly expansive. Therefore, this component could be easily expanded to provide additional interactions.

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

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

109.1. URI format

github://endpoint[?options]

109.2. Mandatory Options:

Note that these can be configured directly through the endpoint.

The GitHub component has no options.

The GitHub endpoint is configured using URI syntax:

github:type/branchName

with the following path and query parameters:

109.2.1. Path Parameters (2 parameters):

Name	Description	Default	Type
type	Required What git operation to execute		GitHubType
branchName	Name of branch		String

109.2.2. Query Parameters (12 parameters):

Name	Description	Default	Type
oauthToken (common)	GitHub OAuth token, required unless username & password are provided		String
password (common)	GitHub password, required unless oauthToken is provided		String
repoName (common)	Required GitHub repository name		String
repoOwner (common)	Required GitHub repository owner (organization)		String
username (common)	GitHub username, required unless oauthToken is provided		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
encoding (producer)	To use the given encoding when getting a git commit file		String
state (producer)	To set git commit status state		String
targetUrl (producer)	To set git commit status target url		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

109.3. Consumer Endpoints:

Endpoint	Context	Body Type
pullRequest	polling	org.eclipse.egit.github.core.PullRequest
pullRequestComment	polling	org.eclipse.egit.github.core.Comment (comment on the general pull request discussion) or org.eclipse.egit.github.core.CommitComment (inline comment on a pull request diff)
tag	polling	org.eclipse.egit.github.core.RepositoryTag
commit	polling	org.eclipse.egit.github.core.RepositoryCommit

109.4. Producer Endpoints:

Endpoint

Body

Message Headers

pullRequestComment

String (comment text)

- GitHubPullRequest (integer) (REQUIRED): Pull request number.

- GitHubInResponseTo (integer): Required if responding to another inline comment on the pull request diff. If left off, a general comment on the pull request discussion is assumed.

closePullRequest

none

- GitHubPullRequest (integer) (REQUIRED): Pull request number.

createIssue (From Camel 2.18)

String (issue body text)

- GitHubIssueTitle (String) (REQUIRED): Issue Title.

Chapter 110. Google BigQuery Component

Available as of Camel version 2.20

110.1. Component Description

The Google Bigquery component provides access to Cloud BigQuery Infrastructure via the Google Client Services API.

The current implementation does not use gRPC.

The current implementation does not support querying BigQuery i.e. is a producer only.

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

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

110.2. Authentication Configuration

Google BigQuery component authentication is targeted for use with the GCP Service Accounts. For more information please refer to Google Cloud Platform Auth Guide

Google security credentials can be set explicitly via one of the two options:

Service Account Email and Service Account Key (PEM format)
GCP credentials file location

If both are set, the Service Account Email/Key will take precedence.

Or implicitly, where the connection factory falls back on Application Default Credentials.

OBS! The location of the default credentials file is configurable - via GOOGLE_APPLICATION_CREDENTIALS environment variable.

Service Account Email and Service Account Key can be found in the GCP JSON credentials file as client_email and private_key respectively.

110.3. URI Format

        google-bigquery://project-id:datasetId[:tableId]?[options]

110.4. Options

The Google BigQuery component supports 4 options which are listed below.

Name	Description	Default	Type
projectId (producer)	Google Cloud Project Id		String
datasetId (producer)	BigQuery Dataset Id		String
connectionFactory (producer)	ConnectionFactory to obtain connection to Bigquery Service. If non provided the default one will be used		GoogleBigQuery ConnectionFactory
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Google BigQuery endpoint is configured using URI syntax:

google-bigquery:projectId:datasetId:tableName

with the following path and query parameters:

110.4.1. Path Parameters (3 parameters):

Name	Description	Type
projectId	Required Google Cloud Project Id	String
datasetId	Required BigQuery Dataset Id	String
tableId	BigQuery table id	String

110.4.2. Query Parameters (3 parameters):

Name	Description	Default	Type
connectionFactory (producer)	ConnectionFactory to obtain connection to Bigquery Service. If non provided the default will be used.		GoogleBigQuery ConnectionFactory
useAsInsertId (producer)	Field name to use as insert id		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

110.5. Message Headers

Name	Type	Description
`CamelGoogleBigQuery.TableSuffix`	`String`	Table suffix to use when inserting data
`CamelGoogleBigQuery.InsertId`	`String`	InsertId to use when inserting data
`CamelGoogleBigQuery.PartitionDecorator`	`String`	Partition decorator to indicate partition to use when inserting data
`CamelGoogleBigQuery.TableId`	`String`	Table id where data will be submitted. If specified will override endpoint configuration

110.6. Producer Endpoints

Producer endpoints can accept and deliver to BigQuery individual and grouped exchanges alike. Grouped exchanges have Exchange.GROUPED_EXCHANGE property set.

Goole BigQuery producer will send a grouped exchange in a single api call unless different table suffix or partition decorators are specified in which case it will break it down to ensure data is written with the correct suffix or partition decorator.

Google BigQuery endpoint expects the payload to be either a map or list of maps. A payload containing a map will insert a single row and a payload containing a list of map’s will insert a row for each entry in the list.

110.7. Template tables

Reference: https://cloud.google.com/bigquery/streaming-data-into-bigquery#template-tables

Templated tables can be specified using the GoogleBigQueryConstants.TABLE_SUFFIX header.

I.e. the following route will create tables and insert records sharded on a per day basis:

from("direct:start")
.header(GoogleBigQueryConstants.TABLE_SUFFIX, "_${date:now:yyyyMMdd}")
.to("google-bigquery:sampleDataset:sampleTable")

Note it is recommended to use partitioning for this use case.

110.8. Partitioning

Reference: https://cloud.google.com/bigquery/docs/creating-partitioned-tables

Partitioning is specified when creating a table and if set data will be automatically partitioned into separate tables. When inserting data a specific partition can be specified by setting the GoogleBigQueryConstants.PARTITION_DECORATOR header on the exchange.

110.9. Ensuring data consistency

Reference: https://cloud.google.com/bigquery/streaming-data-into-bigquery#dataconsistency

A insert id can be set on the exchange with the header GoogleBigQueryConstants.INSERT_ID or by specifying query parameter useAsInsertId. As an insert id need to be specified per row inserted the exchange header can’t be used when the payload is a list - if the payload is a list the GoogleBigQueryConstants.INSERT_ID will be ignored. In that case use the query parameter useAsInsertId.

Chapter 111. Google Calendar Component

Available as of Camel version 2.15

The Google Calendar component provides access to http://google.com/calendar[Google Calendar] via the https://developers.google.com/google-apps/calendar/v3/reference/[Google Calendar Web APIs].

Google Calendar uses the https://developers.google.com/accounts/docs/OAuth2[OAuth 2.0 protocol] for authenticating a Google account and authorizing access to user data. Before you can use this component, you will need to https://developers.google.com/google-apps/calendar/auth[create an account and generate OAuth credentials]. Credentials comprise of a clientId, clientSecret, and a refreshToken. A handy resource for generating a long-lived refreshToken is the https://developers.google.com/oauthplayground[OAuth playground].

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

    <dependency>
            <groupId>org.apache.camel</groupId>
            <artifactId>camel-google-calendar</artifactId>
            <version>2.15.0</version>
    </dependency>

111.1. 1. Google Calendar Options

The Google Calendar component supports 3 options which are listed below.

Name	Description	Default	Type
configuration (common)	To use the shared configuration		GoogleCalendar Configuration
clientFactory (advanced)	To use the GoogleCalendarClientFactory as factory for creating the client. Will by default use BatchGoogleCalendarClientFactory		GoogleCalendarClient Factory
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Google Calendar endpoint is configured using URI syntax:

google-calendar:apiName/methodName

with the following path and query parameters:

111.1.1. Path Parameters (2 parameters):

Name	Description	Default	Type
apiName	Required What kind of operation to perform		GoogleCalendarApiName
methodName	Required What sub operation to use for the selected operation		String

111.1.2. Query Parameters (14 parameters):

Name	Description	Default	Type
accessToken (common)	OAuth 2 access token. This typically expires after an hour so refreshToken is recommended for long term usage.		String
applicationName (common)	Google calendar application name. Example would be camel-google-calendar/1.0		String
clientId (common)	Client ID of the calendar application		String
clientSecret (common)	Client secret of the calendar application		String
emailAddress (common)	The emailAddress of the Google Service Account.		String
inBody (common)	Sets the name of a parameter to be passed in the exchange In Body		String
p12FileName (common)	The name of the p12 file which has the private key to use with the Google Service Account.		String
refreshToken (common)	OAuth 2 refresh token. Using this, the Google Calendar component can obtain a new accessToken whenever the current one expires - a necessity if the application is long-lived.		String
scopes (common)	Specifies the level of permissions you want a calendar application to have to a user account. You can separate multiple scopes by comma. See https://developers.google.com/google-apps/calendar/auth for more info.	https://www.googleapis.com/auth/calendar	String
user (common)	The email address of the user the application is trying to impersonate in the service account flow		String
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

111.2. URI Format

The GoogleCalendar Component uses the following URI format:

        google-calendar://endpoint-prefix/endpoint?[options]

Endpoint prefix can be one of:

acl
calendars
channels
colors
events
freebusy
list
settings

111.3. Producer Endpoints

Producer endpoints can use endpoint prefixes followed by endpoint names and associated options described next. A shorthand alias can be used for some endpoints. The endpoint URI MUST contain a prefix.

Endpoint options that are not mandatory are denoted by []. When there are no mandatory options for an endpoint, one of the set of [] options MUST be provided. Producer endpoints can also use a special option inBody that in turn should contain the name of the endpoint option whose value will be contained in the Camel Exchange In message.

Any of the endpoint options can be provided in either the endpoint URI, or dynamically in a message header. The message header name must be of the format CamelGoogleCalendar.<option>. Note that the inBody option overrides message header, i.e. the endpoint option inBody=option would override a CamelGoogleCalendar.option header.

111.4. Consumer Endpoints

Any of the producer endpoints can be used as a consumer endpoint. Consumer endpoints can use Scheduled Poll Consumer Options with a consumer. prefix to schedule endpoint invocation. Consumer endpoints that return an array or collection will generate one exchange per element, and their routes will be executed once for each exchange.

111.5. Message Headers

Any URI option can be provided in a message header for producer endpoints with a CamelGoogleCalendar. prefix.

111.6. Message Body

All result message bodies utilize objects provided by the underlying APIs used by the GoogleCalendarComponent. Producer endpoints can specify the option name for incoming message body in the inBody endpoint URI parameter. For endpoints that return an array or collection, a consumer endpoint will map every element to distinct messages.

Chapter 112. Google Drive Component

Available as of Camel version 2.14

The Google Drive component provides access to the Google Drive file storage service via the Google Drive Web APIs.

Google Drive uses the https://developers.google.com/accounts/docs/OAuth2[OAuth 2.0 protocol] for authenticating a Google account and authorizing access to user data. Before you can use this component, you will need to create an account and generate OAuth credentials. Credentials comprise of a clientId, clientSecret, and a refreshToken. A handy resource for generating a long-lived refreshToken is the OAuth playground.

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

    <dependency>
            <groupId>org.apache.camel</groupId>
            <artifactId>camel-google-drive</artifactId>
            <version>2.14-SNAPSHOT</version>
    </dependency>

112.1. URI Format

The GoogleDrive Component uses the following URI format:

        google-drive://endpoint-prefix/endpoint?[options]

Endpoint prefix can be one of:

drive-about
drive-apps
drive-changes
drive-channels
drive-children
drive-comments
drive-files
drive-parents
drive-permissions
drive-properties
drive-realtime
drive-replies
drive-revisions

112.2. GoogleDriveComponent

The Google Drive component supports 3 options which are listed below.

Name	Description	Default	Type
configuration (common)	To use the shared configuration		GoogleDrive Configuration
clientFactory (advanced)	To use the GoogleCalendarClientFactory as factory for creating the client. Will by default use BatchGoogleDriveClientFactory		GoogleDriveClient Factory
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Google Drive endpoint is configured using URI syntax:

google-drive:apiName/methodName

with the following path and query parameters:

112.2.1. Path Parameters (2 parameters):

Name	Description	Default	Type
apiName	Required What kind of operation to perform		GoogleDriveApiName
methodName	Required What sub operation to use for the selected operation		String

112.2.2. Query Parameters (12 parameters):

Name	Description	Default	Type
accessToken (common)	OAuth 2 access token. This typically expires after an hour so refreshToken is recommended for long term usage.		String
applicationName (common)	Google drive application name. Example would be camel-google-drive/1.0		String
clientFactory (common)	To use the GoogleCalendarClientFactory as factory for creating the client. Will by default use BatchGoogleDriveClientFactory		GoogleDriveClient Factory
clientId (common)	Client ID of the drive application		String
clientSecret (common)	Client secret of the drive application		String
inBody (common)	Sets the name of a parameter to be passed in the exchange In Body		String
refreshToken (common)	OAuth 2 refresh token. Using this, the Google Calendar component can obtain a new accessToken whenever the current one expires - a necessity if the application is long-lived.		String
scopes (common)	Specifies the level of permissions you want a drive application to have to a user account. See https://developers.google.com/drive/web/scopes for more info.		List
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

112.3. Producer Endpoints

Producer endpoints can use endpoint prefixes followed by endpoint names and associated options described next. A shorthand alias can be used for some endpoints. The endpoint URI MUST contain a prefix.

Endpoint options that are not mandatory are denoted by []. When there are no mandatory options for an endpoint, one of the set of [] options MUST be provided. Producer endpoints can also use a special option inBody that in turn should contain the name of the endpoint option whose value will be contained in the Camel Exchange In message.

Any of the endpoint options can be provided in either the endpoint URI, or dynamically in a message header. The message header name must be of the format CamelGoogleDrive.<option>. Note that the inBody option overrides message header, i.e. the endpoint option inBody=option would override a CamelGoogleDrive.option header.

For more information on the endpoints and options see API documentation at: https://developers.google.com/drive/v2/reference/[https://developers.google.com/drive/v2/reference/]

112.4. Consumer Endpoints

Any of the producer endpoints can be used as a consumer endpoint. Consumer endpoints can use Scheduled Poll Consumer Options with a consumer. prefix to schedule endpoint invocation. Consumer endpoints that return an array or collection will generate one exchange per element, and their routes will be executed once for each exchange.

112.5. Message Headers

Any URI option can be provided in a message header for producer endpoints with a CamelGoogleDrive. prefix.

112.6. Message Body

All result message bodies utilize objects provided by the underlying APIs used by the GoogleDriveComponent. Producer endpoints can specify the option name for incoming message body in the inBody endpoint URI parameter. For endpoints that return an array or collection, a consumer endpoint will map every element to distinct messages.

Chapter 113. Google Mail Component

Available as of Camel version 2.15

The Google Mail component provides access to http://gmail.com/[Gmail] via the https://developers.google.com/gmail/api/v1/reference/[Google Mail Web APIs].

Google Mail uses the https://developers.google.com/accounts/docs/OAuth2[OAuth 2.0 protocol] for authenticating a Google account and authorizing access to user data. Before you can use this component, you will need to https://developers.google.com/gmail/api/auth/web-server[create an account and generate OAuth credentials]. Credentials comprise of a clientId, clientSecret, and a refreshToken. A handy resource for generating a long-lived refreshToken is the https://developers.google.com/oauthplayground[OAuth playground].

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

    <dependency>
            <groupId>org.apache.camel</groupId>
            <artifactId>camel-google-mail</artifactId>
            <version>2.15-SNAPSHOT</version>
    </dependency>

113.1. URI Format

The GoogleMail Component uses the following URI format:

        google-mail://endpoint-prefix/endpoint?[options]

Endpoint prefix can be one of:

attachments
drafts
history
labels
messages
threads
users

113.2. GoogleMailComponent

The Google Mail component supports 3 options which are listed below.

Name	Description	Default	Type
configuration (common)	To use the shared configuration		GoogleMailConfiguration
clientFactory (advanced)	To use the GoogleCalendarClientFactory as factory for creating the client. Will by default use BatchGoogleMailClientFactory		GoogleMailClient Factory
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Google Mail endpoint is configured using URI syntax:

google-mail:apiName/methodName

with the following path and query parameters:

113.2.1. Path Parameters (2 parameters):

Name	Description	Default	Type
apiName	Required What kind of operation to perform		GoogleMailApiName
methodName	Required What sub operation to use for the selected operation		String

113.2.2. Query Parameters (11 parameters):

Name	Description	Default	Type
accessToken (common)	OAuth 2 access token. This typically expires after an hour so refreshToken is recommended for long term usage.		String
applicationName (common)	Google mail application name. Example would be camel-google-mail/1.0		String
clientId (common)	Client ID of the mail application		String
clientSecret (common)	Client secret of the mail application		String
inBody (common)	Sets the name of a parameter to be passed in the exchange In Body		String
refreshToken (common)	OAuth 2 refresh token. Using this, the Google Calendar component can obtain a new accessToken whenever the current one expires - a necessity if the application is long-lived.		String
scopes (common)	Specifies the level of permissions you want a mail application to have to a user account. See https://developers.google.com/gmail/api/auth/scopes for more info.		List
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

113.3. Producer Endpoints

Producer endpoints can use endpoint prefixes followed by endpoint names and associated options described next. A shorthand alias can be used for some endpoints. The endpoint URI MUST contain a prefix.

Endpoint options that are not mandatory are denoted by []. When there are no mandatory options for an endpoint, one of the set of [] options MUST be provided. Producer endpoints can also use a special option inBody that in turn should contain the name of the endpoint option whose value will be contained in the Camel Exchange In message.

Any of the endpoint options can be provided in either the endpoint URI, or dynamically in a message header. The message header name must be of the format CamelGoogleMail.<option>. Note that the inBody option overrides message header, i.e. the endpoint option inBody=option would override a CamelGoogleMail.option header.

For more information on the endpoints and options see API documentation at: https://developers.google.com/gmail/api/v1/reference/[https://developers.google.com/gmail/api/v1/reference/]

113.4. Consumer Endpoints

Any of the producer endpoints can be used as a consumer endpoint. Consumer endpoints can use Scheduled Poll Consumer Options with a consumer. prefix to schedule endpoint invocation. Consumer endpoints that return an array or collection will generate one exchange per element, and their routes will be executed once for each exchange.

113.5. Message Headers

Any URI option can be provided in a message header for producer endpoints with a CamelGoogleMail. prefix.

113.6. Message Body

All result message bodies utilize objects provided by the underlying APIs used by the GoogleMailComponent. Producer endpoints can specify the option name for incoming message body in the inBody endpoint URI parameter. For endpoints that return an array or collection, a consumer endpoint will map every element to distinct messages.

Chapter 114. Google Pubsub Component

Available as of Camel version 2.19

The Google Pubsub component provides access to Cloud Pub/Sub Infrastructure via the Google Client Services API.

The current implementation does not use gRPC.

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

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

114.1. URI Format

The GoogleMail Component uses the following URI format:

google-pubsub://project-id:destinationName?[options]

Destination Name can be either a topic or a subscription name.

114.2. Options

The Google Pubsub component supports 2 options which are listed below.

Name	Description	Default	Type
connectionFactory (common)	Sets the connection factory to use: provides the ability to explicitly manage connection credentials: - the path to the key file - the Service Account Key / Email pair		GooglePubsubConnection Factory
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Google Pubsub endpoint is configured using URI syntax:

google-pubsub:projectId:destinationName

with the following path and query parameters:

114.2.1. Path Parameters (2 parameters):

Name	Description	Default	Type
projectId	Required Project Id		String
destinationName	Required Destination Name		String

114.2.2. Query Parameters (9 parameters):

Name	Description	Default	Type
ackMode (common)	AUTO = exchange gets ack’ed/nack’ed on completion. NONE = downstream process has to ack/nack explicitly	AUTO	AckMode
concurrentConsumers (common)	The number of parallel streams consuming from the subscription	1	Integer
connectionFactory (common)	ConnectionFactory to obtain connection to PubSub Service. If non provided the default will be used.		GooglePubsubConnection Factory
loggerId (common)	Logger ID to use when a match to the parent route required		String
maxMessagesPerPoll (common)	The max number of messages to receive from the server in a single API call	1	Integer
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

114.3. Producer Endpoints

Producer endpoints can accept and deliver to PubSub individual and grouped exchanges alike. Grouped exchanges have Exchange.GROUPED_EXCHANGE property set.

Google PubSub expects the payload to be byte[] array, Producer endpoints will send:

String body as byte[] encoded as UTF-8
byte[] body as is
Everything else will be serialised into byte[] array

A Map set as message header GooglePubsubConstants.ATTRIBUTES will be sent as PubSub attributes. Once exchange has been delivered to PubSub the PubSub Message ID will be assigned to the header GooglePubsubConstants.MESSAGE_ID.

114.4. Consumer Endpoints

Google PubSub will redeliver the message if it has not been acknowledged within the time period set as a configuration option on the subscription.

The component will acknowledge the message once exchange processing has been completed.

If the route throws an exception, the exchange is marked as failed and the component will NACK the message - it will be redelivered immediately.

To ack/nack the message the component uses Acknowledgement ID stored as header GooglePubsubConstants.ACK_ID. If the header is removed or tampered with, the ack will fail and the message will be redelivered again after the ack deadline.

114.5. Message Headers

Headers set by the consumer endpoints:

GooglePubsubConstants.MESSAGE_ID
GooglePubsubConstants.ATTRIBUTES
GooglePubsubConstants.PUBLISH_TIME
GooglePubsubConstants.ACK_ID

114.6. Message Body

The consumer endpoint returns the content of the message as byte[] - exactly as the underlying system sends it. It is up for the route to convert/unmarshall the contents.

114.7. Authentication Configuration

Google Pubsub component authentication is targeted for use with the GCP Service Accounts. For more information please refer to Google Cloud Platform Auth Guide

Google security credentials can be set explicitly via one of the two options:

Service Account Email and Service Account Key (PEM format)
GCP credentials file location

If both are set, the Service Account Email/Key will take precedence.

Or implicitly, where the connection factory falls back on Application Default Credentials.

OBS! The location of the default credentials file is configurable - via GOOGLE_APPLICATION_CREDENTIALS environment variable.

Service Account Email and Service Account Key can be found in the GCP JSON credentials file as client_email and private_key respectively.

114.8. Rollback and Redelivery

The rollback for Google PubSub relies on the idea of the Acknowledgement Deadline - the time period where Google PubSub expects to receive the acknowledgement. If the acknowledgement has not been received, the message is redelivered.

Google provides an API to extend the deadline for a message.

More information in Google PubSub Documentation

So, rollback is effectively a deadline extension API call with zero value - i.e. deadline is reached now and message can be redelivered to the next consumer.

It is possible to delay the message redelivery by setting the acknowledgement deadline explicitly for the rollback by setting the message header GooglePubsubConstants.ACK_DEADLINE to the value in seconds.

Chapter 115. Groovy Language

Available as of Camel version 1.3

Camel supports Groovy among other Scripting Languages to allow an Expression or Predicate to be used in the DSL or Xml Configuration.

To use a Groovy expression use the following Java code

... groovy("someGroovyExpression") ...

For example you could use the groovy function to create an Predicate in a Message Filter or as an Expression for a Recipient List

115.1. Groovy Options

The Groovy language supports 1 options which are listed below.

Name	Default	Java Type	Description
trim	`true`	`Boolean`	Whether to trim the value to remove leading and trailing whitespaces and line breaks

115.2. Customizing Groovy Shell

Sometimes you may need to use custom GroovyShell instance in your Groovy expressions. To provide custom GroovyShell, add implementation of the org.apache.camel.language.groovy.GroovyShellFactory SPI interface to your Camel registry. For example after adding the following bean to your Spring context…

public class CustomGroovyShellFactory implements GroovyShellFactory {
 
  public GroovyShell createGroovyShell(Exchange exchange) {
    ImportCustomizer importCustomizer = new ImportCustomizer();
    importCustomizer.addStaticStars("com.example.Utils");
    CompilerConfiguration configuration = new CompilerConfiguration();
    configuration.addCompilationCustomizers(importCustomizer);
    return new GroovyShell(configuration);
  }

}

…Camel will use your custom GroovyShell instance (containing your custom static imports), instead of the default one.

115.3. Example

// lets route if a line item is over $100
from("queue:foo").filter(groovy("request.lineItems.any { i -> i.value > 100 }")).to("queue:bar")

And the Spring DSL:

        <route>
            <from uri="queue:foo"/>
            <filter>
                <groovy>request.lineItems.any { i -> i.value > 100 }</groovy>
                <to uri="queue:bar"/>
            </filter>
        </route>

115.4. ScriptContext

The JSR-223 scripting languages ScriptContext is pre configured with the following attributes all set at ENGINE_SCOPE:

Attribute	Type	Value
context	`org.apache.camel.CamelContext`	The Camel Context ( It cannot be used in groovy)
camelContext	`org.apache.camel.CamelContext`	The Camel Context
exchange	`org.apache.camel.Exchange`	The current Exchange
request	`org.apache.camel.Message`	The message (IN message)
response	`org.apache.camel.Message`	Deprecated: The OUT message. The OUT message if null by default. Use IN message instead.
properties	`org.apache.camel.builder.script.PropertiesFunction`	Camel 2.9: Function with a `resolve` method to make it easier to use Camels Properties component from scripts. See further below for example.

See Scripting Languages for the list of languages with explicit DSL support.

115.5. Additional arguments to ScriptingEngine

Available as of Camel 2.8

You can provide additional arguments to the ScriptingEngine using a header on the Camel message with the key CamelScriptArguments.
See this example:

115.6. Using properties function

Available as of Camel 2.9

If you need to use the Properties component from a script to lookup property placeholders, then its a bit cumbersome to do so. For example to set a header name myHeader with a value from a property placeholder, which key is provided in a header named "foo".

.setHeader("myHeader").groovy(""context.resolvePropertyPlaceholders( + '{{' + request.headers.get(&#39;foo&#39;) + '}}' + ")")

From Camel 2.9 onwards you can now use the properties function and the same example is simpler:

.setHeader("myHeader").groovy("properties.resolve(request.headers.get(&#39;foo&#39;))")

115.7. Loading script from external resource

Available as of Camel 2.11

You can externalize the script and have Camel load it from a resource such as "classpath:", "file:", or "http:".
This is done using the following syntax: "resource:scheme:location", eg to refer to a file on the classpath you can do:

.setHeader("myHeader").groovy("resource:classpath:mygroovy.groovy")

115.8. How to get the result from multiple statements script

Available as of Camel 2.14

As the scripteengine evale method just return a Null if it runs a multiple statments script. Camel now look up the value of script result by using the key of "result" from the value set. If you have multiple statements script, you need to make sure you set the value of result variable as the script return value.

bar = "baz";
# some other statements ...
# camel take the result value as the script evaluation result
result = body * 2 + 1

115.9. Dependencies

To use scripting languages in your camel routes you need to add the a dependency on camel-script which integrates the JSR-223 scripting engine.

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

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

Chapter 116. gRPC Component

Available as of Camel version 2.19

The gRPC component allows you to call or expose Remote Procedure Call (RPC) services using Protocol Buffers (protobuf) exchange format over HTTP/2 transport.

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

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

116.1. URI format

grpc://service[?options]

116.2. Endpoint Options

The gRPC component has no options.

The gRPC endpoint is configured using URI syntax:

grpc:host:port/service

with the following path and query parameters:

116.2.1. Path Parameters (3 parameters):

Name	Description	Type
host	Required The gRPC server host name. This is localhost or 0.0.0.0 when being a consumer or remote server host name when using producer.	String
port	Required The gRPC local or remote server port	int
service	Required Fully qualified service name from the protocol buffer descriptor file (package dot service definition name)	String

116.2.2. Query Parameters (25 parameters):

Name	Description	Default	Type
flowControlWindow (common)	The HTTP/2 flow control window size (MiB)	1048576	int
maxMessageSize (common)	The maximum message size allowed to be received/sent (MiB)	4194304	int
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
consumerStrategy (consumer)	This option specifies the top-level strategy for processing service requests and responses in streaming mode. If an aggregation strategy is selected, all requests will be accumulated in the list, then transferred to the flow, and the accumulated responses will be sent to the sender. If a propagation strategy is selected, request is sent to the stream, and the response will be immediately sent back to the sender.	PROPAGATION	GrpcConsumerStrategy
forwardOnCompleted (consumer)	Determines if onCompleted events should be pushed to the Camel route.	false	boolean
forwardOnError (consumer)	Determines if onError events should be pushed to the Camel route. Exceptions will be set as message body.	false	boolean
maxConcurrentCallsPer Connection (consumer)	The maximum number of concurrent calls permitted for each incoming server connection	2147483647	int
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
method (producer)	gRPC method name		String
producerStrategy (producer)	The mode used to communicate with a remote gRPC server. In SIMPLE mode a single exchange is translated into a remote procedure call. In STREAMING mode all exchanges will be sent within the same request (input and output of the recipient gRPC service must be of type 'stream').	SIMPLE	GrpcProducerStrategy
streamRepliesTo (producer)	When using STREAMING client mode, it indicates the endpoint where responses should be forwarded.		String
userAgent (producer)	The user agent header passed to the server		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
authenticationType (security)	Authentication method type in advance to the SSL/TLS negotiation	NONE	GrpcAuthType
jwtAlgorithm (security)	JSON Web Token sign algorithm	HMAC256	JwtAlgorithm
jwtIssuer (security)	JSON Web Token issuer		String
jwtSecret (security)	JSON Web Token secret		String
jwtSubject (security)	JSON Web Token subject		String
keyCertChainResource (security)	The X.509 certificate chain file resource in PEM format link		String
keyPassword (security)	The PKCS8 private key file password		String
keyResource (security)	The PKCS8 private key file resource in PEM format link		String
negotiationType (security)	Identifies the security negotiation type used for HTTP/2 communication	PLAINTEXT	NegotiationType
serviceAccountResource (security)	Service Account key file in JSON format resource link supported by the Google Cloud SDK		String
trustCertCollectionResource (security)	The trusted certificates collection file resource in PEM format for verifying the remote endpoint’s certificate		String

116.3. Transport security and authentication support (available from Camel 2.20)

The following authentication mechanisms are built-in to gRPC and available in this component:

SSL/TLS: gRPC has SSL/TLS integration and promotes the use of SSL/TLS to authenticate the server, and to encrypt all the data exchanged between the client and the server. Optional mechanisms are available for clients to provide certificates for mutual authentication.
Token-based authentication with Google: gRPC provides a generic mechanism to attach metadata based credentials to requests and responses. Additional support for acquiring access tokens while accessing Google APIs through gRPC is provided. In general this mechanism must be used as well as SSL/TLS on the channel.

To enable these features the following component properties combinations must be configured:

Num.	Option	Parameter	Value	Required/Optional
1	SSL/TLS	negotiationType	TLS	Required
		keyCertChainResource		Required
		keyResource		Required
		keyPassword		Optional
		trustCertCollectionResource		Optional
2	Token-based authentication with Google API	authenticationType	GOOGLE	Required
		negotiationType	TLS	Required
		serviceAccountResource		Required
3	Custom JSON Web Token implementation authentication	authenticationType	JWT	Required
		negotiationType	NONE or TLS	Optional. The TLS/SSL not checking for this type, but strongly recommended.
		jwtAlgorithm	HMAC256(default) or (HMAC384,HMAC512)	Optional
		jwtSecret		Required
		jwtIssuer		Optional
		jwtSubject		Optional

TLS with OpenSSL is currently the recommended approach for using gRPC over TLS component. Using the JDK for ALPN is generally much slower and may not support the necessary ciphers for HTTP2. This function is not implemented in the component.

116.4. gRPC producer resource type mapping

The table below shows the types of objects in the message body, depending on the types (simple or stream) of incoming and outgoing parameters, as well as the invocation style (synchronous or asynchronous). Please note, that invocation of the procedures with incoming stream parameter in asynchronous style are not allowed.

Invocation style	Request type	Response type	Request Body Type	Result Body Type
synchronous	simple	simple	Object	Object
synchronous	simple	stream	Object	List<Object>
synchronous	stream	simple	not allowed	not allowed
synchronous	stream	stream	not allowed	not allowed
asynchronous	simple	simple	Object	List<Object>
asynchronous	simple	stream	Object	List<Object>
asynchronous	stream	simple	Object or List<Object>	List<Object>
asynchronous	stream	stream	Object or List<Object>	List<Object>

116.5. gRPC consumer headers (will be installed after the consumer invocation)

Header name	Description	Possible values
CamelGrpcMethodName	Method name handled by the consumer service
CamelGrpcEventType	Received event type from the sent request	onNext, onCompleted or onError
CamelGrpcUserAgent	If provided, the given agent will prepend the gRPC library’s user agent information

116.6. Examples

Below is a simple synchronous method invoke with host and port parameters

from("direct:grpc-sync")
.to("grpc://remotehost:1101/org.apache.camel.component.grpc.PingPong?method=sendPing&synchronous=true");

<route>
    <from uri="direct:grpc-sync" />
    <to uri="grpc://remotehost:1101/org.apache.camel.component.grpc.PingPong?method=sendPing&synchronous=true"/>
</route>

An asynchronous method invoke

from("direct:grpc-async")
.to("grpc://remotehost:1101/org.apache.camel.component.grpc.PingPong?method=pingAsyncResponse");

gRPC service consumer with propagation consumer strategy

from("grpc://localhost:1101/org.apache.camel.component.grpc.PingPong?consumerStrategy=PROPAGATION")
.to("direct:grpc-service");

gRPC service producer with streaming producer strategy (requires a service that uses "stream" mode as input and output)

from("direct:grpc-request-stream")
.to("grpc://remotehost:1101/org.apache.camel.component.grpc.PingPong?method=PingAsyncAsync&producerStrategy=STREAMING&streamRepliesTo=direct:grpc-response-stream");

from("direct:grpc-response-stream")
.log("Response received: ${body}");

gRPC service consumer TLS/SLL security negotiation enable

from("grpc://localhost:1101/org.apache.camel.component.grpc.PingPong?consumerStrategy=PROPAGATION&negotiationType=TLS&keyCertChainResource=file:src/test/resources/certs/server.pem&keyResource=file:src/test/resources/certs/server.key&trustCertCollectionResource=file:src/test/resources/certs/ca.pem")
.to("direct:tls-enable")

gRPC service producer with custom JSON Web Token implementation authentication

from("direct:grpc-jwt")
.to("grpc://localhost:1101/org.apache.camel.component.grpc.PingPong?method=pingSyncSync&synchronous=true&authenticationType=JWT&jwtSecret=supersecuredsecret");

116.7. Configuration

It’s it is recommended to use Maven Protocol Buffers Plugin which calls Protocol Buffer Compiler (protoc) tool to generate Java source files from .proto (protocol buffer definition) files for the custom project. This plugin will generate procedures request and response classes, their builders and gRPC procedures stubs classes as well.

Following steps are required:

Insert operating system and CPU architecture detection extension inside <build> tag of the project pom.xml or set ${os.detected.classifier} parameter manually

<extensions>
  <extension>
    <groupId>kr.motd.maven</groupId>
    <artifactId>os-maven-plugin</artifactId>
    <version>1.4.1.Final</version>
  </extension>
</extensions>

Insert gRPC and protobuf Java code generator plugin <plugins> tag of the project pom.xml

<plugin>
  <groupId>org.xolstice.maven.plugins</groupId>
  <artifactId>protobuf-maven-plugin</artifactId>
  <version>0.5.0</version>
  <configuration>
    <protocArtifact>com.google.protobuf:protoc:${protobuf-version}:exe:${os.detected.classifier}</protocArtifact>
    <pluginId>grpc-java</pluginId>
    <pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc-version}:exe:${os.detected.classifier}</pluginArtifact>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>compile</goal>
        <goal>compile-custom</goal>
        <goal>test-compile</goal>
        <goal>test-compile-custom</goal>
      </goals>
    </execution>
  </executions>
</plugin>

116.8. For more information, see these resources

gRPC project site

Maven Protocol Buffers Plugin

116.9. See Also

Getting Started
Configuring Camel
Component
Endpoint
Protocol Buffers Data Format

Chapter 117. Guava EventBus Component

Available as of Camel version 2.10

The Google Guava EventBus allows publish-subscribe-style communication between components without requiring the components to explicitly register with one another (and thus be aware of each other). The guava-eventbus: component provides integration bridge between Camel and Google Guava EventBus infrastructure. With the latter component, messages exchanged with the Guava EventBus can be transparently forwarded to the Camel routes. EventBus component allows also to route body of Camel exchanges to the Guava EventBus.

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

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

117.1. URI format

guava-eventbus:busName[?options]

Where busName represents the name of the com.google.common.eventbus.EventBus instance located in the Camel registry.

117.2. Options

The Guava EventBus component supports 3 options which are listed below.

Name	Description	Default	Type
eventBus (common)	To use the given Guava EventBus instance		EventBus
listenerInterface (common)	The interface with method(s) marked with the Subscribe annotation. Dynamic proxy will be created over the interface so it could be registered as the EventBus listener. Particularly useful when creating multi-event listeners and for handling DeadEvent properly. This option cannot be used together with eventClass option.		Class<?>
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Guava EventBus endpoint is configured using URI syntax:

guava-eventbus:eventBusRef

with the following path and query parameters:

117.2.1. Path Parameters (1 parameters):

Name	Description	Default	Type
eventBusRef	To lookup the Guava EventBus from the registry with the given name		String

117.2.2. Query Parameters (6 parameters):

Name	Description	Default	Type
eventClass (common)	If used on the consumer side of the route, will filter events received from the EventBus to the instances of the class and superclasses of eventClass. Null value of this option is equal to setting it to the java.lang.Object i.e. the consumer will capture all messages incoming to the event bus. This option cannot be used together with listenerInterface option.		Class<?>
listenerInterface (common)	The interface with method(s) marked with the Subscribe annotation. Dynamic proxy will be created over the interface so it could be registered as the EventBus listener. Particularly useful when creating multi-event listeners and for handling DeadEvent properly. This option cannot be used together with eventClass option.		Class<?>
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

117.3. Usage

Using guava-eventbus component on the consumer side of the route will capture messages sent to the Guava EventBus and forward them to the Camel route. Guava EventBus consumer processes incoming messages asynchronously.

SimpleRegistry registry = new SimpleRegistry();
EventBus eventBus = new EventBus();
registry.put("busName", eventBus);
CamelContext camel = new DefaultCamelContext(registry);

from("guava-eventbus:busName").to("seda:queue");

eventBus.post("Send me to the SEDA queue.");

Using guava-eventbus component on the producer side of the route will forward body of the Camel exchanges to the Guava EventBus instance.

SimpleRegistry registry = new SimpleRegistry();
EventBus eventBus = new EventBus();
registry.put("busName", eventBus);
CamelContext camel = new DefaultCamelContext(registry);

from("direct:start").to("guava-eventbus:busName");

ProducerTemplate producerTemplate = camel.createProducerTemplate();
producer.sendBody("direct:start", "Send me to the Guava EventBus.");

eventBus.register(new Object(){
  @Subscribe
  public void messageHander(String message) {
    System.out.println("Message received from the Camel: " + message);
  }
});

117.4. DeadEvent considerations

Keep in mind that due to the limitations caused by the design of the Guava EventBus, you cannot specify event class to be received by the listener without creating class annotated with @Subscribe method. This limitation implies that endpoint with eventClass option specified actually listens to all possible events (java.lang.Object) and filter appropriate messages programmatically at runtime. The snipped below demonstrates an appropriate excerpt from the Camel code base.

@Subscribe
public void eventReceived(Object event) {
  if (eventClass == null || eventClass.isAssignableFrom(event.getClass())) {
    doEventReceived(event);
...

This drawback of this approach is that EventBus instance used by Camel will never generate com.google.common.eventbus.DeadEvent notifications. If you want Camel to listen only to the precisely specified event (and therefore enable DeadEvent support), use listenerInterface endpoint option. Camel will create dynamic proxy over the interface you specify with the latter option and listen only to messages specified by the interface handler methods. The example of the listener interface with single method handling only SpecificEvent instances is demonstrated below.

package com.example;

public interface CustomListener {

  @Subscribe
  void eventReceived(SpecificEvent event);

}

The listener presented above could be used in the endpoint definition as follows.

from("guava-eventbus:busName?listenerInterface=com.example.CustomListener").to("seda:queue");

117.5. Consuming multiple type of events

In order to define multiple type of events to be consumed by Guava EventBus consumer use listenerInterface endpoint option, as listener interface could provide multiple methods marked with the @Subscribe annotation.

package com.example;

public interface MultipleEventsListener {

  @Subscribe
  void someEventReceived(SomeEvent event);

  @Subscribe
  void anotherEventReceived(AnotherEvent event);

}

The listener presented above could be used in the endpoint definition as follows.

from("guava-eventbus:busName?listenerInterface=com.example.MultipleEventsListener").to("seda:queue");

117.6. HawtDB

Available as of Camel 2.3

HawtDB is a very lightweight and embedable key value database. It allows together with Camel to provide persistent support for various Camel features such as Aggregator.

Deprecated

The HawtDB project is being deprecated and replaced by leveldb as the lightweight and embedable key value database. To make using leveldb easy there is a leveldbjni project for that. The Apache ActiveMQ project is planning on using leveldb as their primary file based message store in the future, to replace kahadb.

There os a camel-leveldb component we recommend to use instead of this.

Issue with HawtDB 1.4 or older

There is a bug in HawtDB 1.4 or older which means the filestore will not free unused space. That means the file keeps growing. This has been fixed in HawtDB 1.5 which is shipped with Camel 2.5 onwards.

Current features it provides:

HawtDBAggregationRepository

117.6.1. Using HawtDBAggregationRepository

HawtDBAggregationRepository is an AggregationRepository which on the fly persists the aggregated messages. This ensures that you will not loose messages, as the default aggregator will use an in memory only AggregationRepository.

It has the following options:

Option	Type	Description
`repositoryName`	String	A mandatory repository name. Allows you to use a shared `HawtDBFile` for multiple repositories.
`persistentFileName`	String	Filename for the persistent storage. If no file exists on startup a new file is created.
`bufferSize`	int	The size of the memory segment buffer which is mapped to the file store. By default its 8mb. The value is in bytes.
`sync`	boolean	Whether or not the `HawtDBFile` should sync on write or not. Default is `true`. By sync on write ensures that its always waiting for all writes to be spooled to disk and thus will not loose updates. If you disable this option, then HawtDB will auto sync when it has batched up a number of writes.
`pageSize`	short	The size of memory pages. By default its 512 bytes. The value is in bytes.
`hawtDBFile`	HawtDBFile	Use an existing configured `org.apache.camel.component.hawtdb.HawtDBFile` instance.
`returnOldExchange`	boolean	Whether the get operation should return the old existing Exchange if any existed. By default this option is `false` to optimize as we do not need the old exchange when aggregating.
`useRecovery`	boolean	Whether or not recovery is enabled. This option is by default `true`. When enabled the Camel Aggregator automatic recover failed aggregated exchange and have them resubmitted.
`recoveryInterval`	long	If recovery is enabled then a background task is run every x’th time to scan for failed exchanges to recover and resubmit. By default this interval is 5000 millis.
`maximumRedeliveries`	int	Allows you to limit the maximum number of redelivery attempts for a recovered exchange. If enabled then the Exchange will be moved to the dead letter channel if all redelivery attempts failed. By default this option is disabled. If this option is used then the `deadLetterUri` option must also be provided.
`deadLetterUri`	String	An endpoint uri for a Dead Letter Channel where exhausted recovered Exchanges will be moved. If this option is used then the `maximumRedeliveries` option must also be provided.
`optimisticLocking`	`false`	Camel 2.12: To turn on optimistic locking, which often would be needed in clustered environments where multiple Camel applications shared the same HawtDB based aggregation repository.

The repositoryName option must be provided. Then either the persistentFileName or the hawtDBFile must be provided.

117.6.2. What is preserved when persisting

HawtDBAggregationRepository will only preserve any Serializable compatible data types. If a data type is not such a type its dropped and a WARN is logged. And it only persists the Message body and the Message headers. The Exchange properties are not persisted.

117.6.3. Recovery

The HawtDBAggregationRepository will by default recover any failed Exchange. It does this by having a background tasks that scans for failed Exchanges in the persistent store. You can use the checkInterval option to set how often this task runs. The recovery works as transactional which ensures that Camel will try to recover and redeliver the failed Exchange. Any Exchange which was found to be recovered will be restored from the persistent store and resubmitted and send out again.

The following headers is set when an Exchange is being recovered/redelivered:

Header	Type	Description
`Exchange.REDELIVERED`	Boolean	Is set to true to indicate the Exchange is being redelivered.
`Exchange.REDELIVERY_COUNTER`	Integer	The redelivery attempt, starting from 1.

Only when an Exchange has been successfully processed it will be marked as complete which happens when the confirm method is invoked on the AggregationRepository. This means if the same Exchange fails again it will be kept retried until it success.

You can use option maximumRedeliveries to limit the maximum number of redelivery attempts for a given recovered Exchange. You must also set the deadLetterUri option so Camel knows where to send the Exchange when the maximumRedeliveries was hit.

You can see some examples in the unit tests of camel-hawtdb, for example this test.

117.6.3.1. Using HawtDBAggregationRepository in Java DSL

In this example we want to persist aggregated messages in the target/data/hawtdb.dat file.

117.6.3.2. Using HawtDBAggregationRepository in Spring XML

The same example but using Spring XML instead:

117.6.4. Dependencies

To use HawtDB in your camel routes you need to add the a dependency on camel-hawtdb.

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

<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-hawtdb</artifactId>
  <version>2.3.0</version>
</dependency>

117.6.5. See Also

Configuring Camel
Component
Endpoint
Getting Started
Aggregator
Components

Chapter 118. Hazelcast Component

Available as of Camel version 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:

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

118.1. Hazelcast components

See followings for each component usage: * map * multimap * queue * topic * list * seda * set * atomic number * cluster support (instance) * replicatedmap * ringbuffer

118.2. Using hazelcast reference

118.2.1. By its name

<bean id="hazelcastLifecycle" class="com.hazelcast.core.LifecycleService"
      factory-bean="hazelcastInstance" factory-method="getLifecycleService"
      destroy-method="shutdown" />

<bean id="config" class="com.hazelcast.config.Config">
    <constructor-arg type="java.lang.String" value="HZ.INSTANCE" />
</bean>

<bean id="hazelcastInstance" class="com.hazelcast.core.Hazelcast" factory-method="newHazelcastInstance">
    <constructor-arg type="com.hazelcast.config.Config" ref="config"/>
</bean>
<camelContext xmlns="http://camel.apache.org/schema/spring">
    <route id="testHazelcastInstanceBeanRefPut">
        <from uri="direct:testHazelcastInstanceBeanRefPut"/>
        <setHeader headerName="CamelHazelcastOperationType">
            <constant>put</constant>
        </setHeader>
        <to uri="hazelcast-map:testmap?hazelcastInstanceName=HZ.INSTANCE"/>
    </route>

    <route id="testHazelcastInstanceBeanRefGet">
        <from uri="direct:testHazelcastInstanceBeanRefGet" />
        <setHeader headerName="CamelHazelcastOperationType">
            <constant>get</constant>
        </setHeader>
        <to uri="hazelcast-map:testmap?hazelcastInstanceName=HZ.INSTANCE"/>
        <to uri="seda:out" />
    </route>
</camelContext>

118.2.2. By instance

<bean id="hazelcastInstance" class="com.hazelcast.core.Hazelcast"
      factory-method="newHazelcastInstance" />
<bean id="hazelcastLifecycle" class="com.hazelcast.core.LifecycleService"
      factory-bean="hazelcastInstance" factory-method="getLifecycleService"
      destroy-method="shutdown" />

<camelContext xmlns="http://camel.apache.org/schema/spring">
    <route id="testHazelcastInstanceBeanRefPut">
        <from uri="direct:testHazelcastInstanceBeanRefPut"/>
        <setHeader headerName="CamelHazelcastOperationType">
            <constant>put</constant>
        </setHeader>
        <to uri="hazelcast-map:testmap?hazelcastInstance=#hazelcastInstance"/>
    </route>

    <route id="testHazelcastInstanceBeanRefGet">
        <from uri="direct:testHazelcastInstanceBeanRefGet" />
        <setHeader headerName="CamelHazelcastOperationType">
            <constant>get</constant>
        </setHeader>
        <to uri="hazelcast-map:testmap?hazelcastInstance=#hazelcastInstance"/>
        <to uri="seda:out" />
    </route>
</camelContext>

118.3. Publishing hazelcast instance as an OSGI service

If operating in an OSGI container and you would want to use one instance of hazelcast across all bundles in the same container. You can publish the instance as an OSGI service and bundles using the cache al need is to reference the service in the hazelcast endpoint.

118.3.1. Bundle A create an instance and publishes it as an OSGI service

<bean id="config" class="com.hazelcast.config.FileSystemXmlConfig">
    <argument type="java.lang.String" value="${hazelcast.config}"/>
</bean>

<bean id="hazelcastInstance" class="com.hazelcast.core.Hazelcast" factory-method="newHazelcastInstance">
    <argument type="com.hazelcast.config.Config" ref="config"/>
</bean>

<!-- publishing the hazelcastInstance as a service -->
<service ref="hazelcastInstance" interface="com.hazelcast.core.HazelcastInstance" />

118.3.2. Bundle B uses the instance

<!-- referencing the hazelcastInstance as a service -->
<reference ref="hazelcastInstance" interface="com.hazelcast.core.HazelcastInstance" />

<camelContext xmlns="http://camel.apache.org/schema/blueprint">
    <route id="testHazelcastInstanceBeanRefPut">
        <from uri="direct:testHazelcastInstanceBeanRefPut"/>
        <setHeader headerName="CamelHazelcastOperationType">
            <constant>put</constant>
        </setHeader>
        <to uri="hazelcast-map:testmap?hazelcastInstance=#hazelcastInstance"/>
    </route>

    <route id="testHazelcastInstanceBeanRefGet">
        <from uri="direct:testHazelcastInstanceBeanRefGet" />
        <setHeader headerName="CamelHazelcastOperationType">
            <constant>get</constant>
        </setHeader>
        <to uri="hazelcast-map:testmap?hazelcastInstance=#hazelcastInstance"/>
        <to uri="seda:out" />
    </route>
</camelContext>

Chapter 119. Hazelcast Atomic Number Component

Available as of Camel version 2.7

The Hazelcast atomic number component is one of Camel Hazelcast Components which allows you to access Hazelcast atomic number. An atomic number is an object that simply provides a grid wide number (long).

There is no consumer for this endpoint!

119.1. Options

The Hazelcast Atomic Number component supports 3 options which are listed below.

Name	Description	Default	Type
hazelcastInstance (advanced)	The hazelcast instance reference 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.		HazelcastInstance
hazelcastMode (advanced)	The hazelcast mode reference which kind of instance should be used. If you don’t specify the mode, then the node mode will be the default.	node	String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Hazelcast Atomic Number endpoint is configured using URI syntax:

hazelcast-atomicvalue:cacheName

with the following path and query parameters:

119.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cacheName	Required The name of the cache		String

119.1.2. Query Parameters (10 parameters):

Name	Description	Default	Type
reliable (common)	Define if the endpoint will use a reliable Topic struct or not.	false	boolean
defaultOperation (producer)	To specify a default operation to use, if no operation header has been provided.		HazelcastOperation
hazelcastInstance (producer)	The hazelcast instance reference which can be used for hazelcast endpoint.		HazelcastInstance
hazelcastInstanceName (producer)	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.		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
concurrentConsumers (seda)	To use concurrent consumers polling from the SEDA queue.	1	int
onErrorDelay (seda)	Milliseconds before consumer continues polling after an error has occurred.	1000	int
pollTimeout (seda)	The timeout used when consuming from the SEDA queue. When a timeout occurs, the consumer can check whether it is allowed to continue running. Setting a lower value allows the consumer to react more quickly upon shutdown.	1000	int
transacted (seda)	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.	false	boolean
transferExchange (seda)	If set to true the whole Exchange will be transfered. If header or body contains not serializable objects, they will be skipped.	false	boolean

119.2. atomic number producer - to("hazelcast-atomicvalue:foo")

The operations for this producer are: * setvalue (set the number with a given value) * get * increase (+1) * decrease (-1) * destroy

Header Variables for the request message:

Name	Type	Description
`CamelHazelcastOperationType`	`String`	valid values are: setvalue, get, increase, decrease, destroy

119.2.1. Sample for set:

Java DSL:

from("direct:set")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.SET_VALUE))
.toF("hazelcast-%sfoo", HazelcastConstants.ATOMICNUMBER_PREFIX);

Spring DSL:

<route>
    <from uri="direct:set" />
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>setvalue</constant>
    </setHeader>
    <to uri="hazelcast-atomicvalue:foo" />
</route>

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

119.2.2. Sample for get:

Java DSL:

from("direct:get")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.GET))
.toF("hazelcast-%sfoo", HazelcastConstants.ATOMICNUMBER_PREFIX);

Spring DSL:

<route>
    <from uri="direct:get" />
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>get</constant>
    </setHeader>
    <to uri="hazelcast-atomicvalue:foo" />
</route>

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

119.2.3. Sample for increment:

Java DSL:

from("direct:increment")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.INCREMENT))
.toF("hazelcast-%sfoo", HazelcastConstants.ATOMICNUMBER_PREFIX);

Spring DSL:

<route>
    <from uri="direct:increment" />
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>increment</constant>
    </setHeader>
    <to uri="hazelcast-atomicvalue:foo" />
</route>

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

119.2.4. Sample for decrement:

Java DSL:

from("direct:decrement")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.DECREMENT))
.toF("hazelcast-%sfoo", HazelcastConstants.ATOMICNUMBER_PREFIX);

Spring DSL:

<route>
    <from uri="direct:decrement" />
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>decrement</constant>
    </setHeader>
    <to uri="hazelcast-atomicvalue:foo" />
</route>

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

119.2.5. Sample for destroy

Java DSL:

from("direct:destroy")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.DESTROY))
.toF("hazelcast-%sfoo", HazelcastConstants.ATOMICNUMBER_PREFIX);

Spring DSL:

<route>
    <from uri="direct:destroy" />
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>destroy</constant>
    </setHeader>
    <to uri="hazelcast-atomicvalue:foo" />
</route>

Chapter 120. Hazelcast Instance Component

Available as of Camel version 2.7

The Hazelcast instance component is one of Camel Hazelcast Components which allows you to consume join/leave events of the cache instance in the cluster. Hazelcast makes sense in one single "server node", but it’s extremly powerful in a clustered environment.

This endpoint provides no producer!

120.1. Options

The Hazelcast Instance component supports 3 options which are listed below.

Name	Description	Default	Type
hazelcastInstance (advanced)	The hazelcast instance reference 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.		HazelcastInstance
hazelcastMode (advanced)	The hazelcast mode reference which kind of instance should be used. If you don’t specify the mode, then the node mode will be the default.	node	String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Hazelcast Instance endpoint is configured using URI syntax:

hazelcast-instance:cacheName

with the following path and query parameters:

120.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cacheName	Required The name of the cache		String

120.1.2. Query Parameters (16 parameters):

Name	Description	Default	Type
reliable (common)	Define if the endpoint will use a reliable Topic struct or not.	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
defaultOperation (consumer)	To specify a default operation to use, if no operation header has been provided.		HazelcastOperation
hazelcastInstance (consumer)	The hazelcast instance reference which can be used for hazelcast endpoint.		HazelcastInstance
hazelcastInstanceName (consumer)	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.		String
pollingTimeout (consumer)	Define the polling timeout of the Queue consumer in Poll mode	10000	long
poolSize (consumer)	Define the Pool size for Queue Consumer Executor	1	int
queueConsumerMode (consumer)	Define the Queue Consumer mode: Listen or Poll	Listen	HazelcastQueueConsumer Mode
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
concurrentConsumers (seda)	To use concurrent consumers polling from the SEDA queue.	1	int
onErrorDelay (seda)	Milliseconds before consumer continues polling after an error has occurred.	1000	int
pollTimeout (seda)	The timeout used when consuming from the SEDA queue. When a timeout occurs, the consumer can check whether it is allowed to continue running. Setting a lower value allows the consumer to react more quickly upon shutdown.	1000	int
transacted (seda)	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.	false	boolean
transferExchange (seda)	If set to true the whole Exchange will be transfered. If header or body contains not serializable objects, they will be skipped.	false	boolean

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

The instance consumer fires if a new cache instance will join or leave the cluster.

Here’s a sample:

fromF("hazelcast-%sfoo", HazelcastConstants.INSTANCE_PREFIX)
.log("instance...")
.choice()
    .when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ADDED))
        .log("...added")
        .to("mock:added")
    .otherwise()
        .log("...removed")
        .to("mock:removed");

Each event provides the following information inside the message header:

Header Variables inside the response message:

Name	Type	Description
`CamelHazelcastListenerTime`	`Long`	time of the event in millis
`CamelHazelcastListenerType`	`String`	the map consumer sets here "instancelistener"
`CamelHazelcastListenerAction`	`String`	type of event - here added or removed.
`CamelHazelcastInstanceHost`	`String`	host name of the instance
`CamelHazelcastInstancePort`	`Integer`	port number of the instance

Chapter 121. Hazelcast List Component

Available as of Camel version 2.7

The Hazelcast List component is one of Camel Hazelcast Components which allows you to access Hazelcast distributed list.

121.1. Options

The Hazelcast List component supports 3 options which are listed below.

Name	Description	Default	Type
hazelcastInstance (advanced)	The hazelcast instance reference 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.		HazelcastInstance
hazelcastMode (advanced)	The hazelcast mode reference which kind of instance should be used. If you don’t specify the mode, then the node mode will be the default.	node	String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Hazelcast List endpoint is configured using URI syntax:

hazelcast-list:cacheName

with the following path and query parameters:

121.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cacheName	Required The name of the cache		String

121.1.2. Query Parameters (16 parameters):

Name	Description	Default	Type
defaultOperation (common)	To specify a default operation to use, if no operation header has been provided.		HazelcastOperation
hazelcastInstance (common)	The hazelcast instance reference which can be used for hazelcast endpoint.		HazelcastInstance
hazelcastInstanceName (common)	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.		String
reliable (common)	Define if the endpoint will use a reliable Topic struct or not.	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
pollingTimeout (consumer)	Define the polling timeout of the Queue consumer in Poll mode	10000	long
poolSize (consumer)	Define the Pool size for Queue Consumer Executor	1	int
queueConsumerMode (consumer)	Define the Queue Consumer mode: Listen or Poll	Listen	HazelcastQueueConsumer Mode
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
concurrentConsumers (seda)	To use concurrent consumers polling from the SEDA queue.	1	int
onErrorDelay (seda)	Milliseconds before consumer continues polling after an error has occurred.	1000	int
pollTimeout (seda)	The timeout used when consuming from the SEDA queue. When a timeout occurs, the consumer can check whether it is allowed to continue running. Setting a lower value allows the consumer to react more quickly upon shutdown.	1000	int
transacted (seda)	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.	false	boolean
transferExchange (seda)	If set to true the whole Exchange will be transfered. If header or body contains not serializable objects, they will be skipped.	false	boolean

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

The list producer provides 7 operations: * add * addAll * set * get * removevalue * removeAll * clear

121.2.1. Sample for add:

from("direct:add")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.ADD))
.toF("hazelcast-%sbar", HazelcastConstants.LIST_PREFIX);

121.2.2. Sample for get:

from("direct:get")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.GET))
.toF("hazelcast-%sbar", HazelcastConstants.LIST_PREFIX)
.to("seda:out");

121.2.3. Sample for setvalue:

from("direct:set")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.SET_VALUE))
.toF("hazelcast-%sbar", HazelcastConstants.LIST_PREFIX);

121.2.4. Sample for removevalue:

from("direct:removevalue")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.REMOVE_VALUE))
.toF("hazelcast-%sbar", HazelcastConstants.LIST_PREFIX);

Note that CamelHazelcastObjectIndex header is used for indexing purpose.

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

The list consumer provides 2 operations: * add * remove

fromF("hazelcast-%smm", HazelcastConstants.LIST_PREFIX)
    .log("object...")
    .choice()
        .when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ADDED))
            .log("...added")
                        .to("mock:added")
        .when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.REMOVED))
            .log("...removed")
                        .to("mock:removed")
                .otherwise()
                        .log("fail!");

Chapter 122. Hazelcast Map Component

Available as of Camel version 2.7

The Hazelcast Map component is one of Camel Hazelcast Components which allows you to access Hazelcast distributed map.

122.1. Options

The Hazelcast Map component supports 3 options which are listed below.

Name	Description	Default	Type
hazelcastInstance (advanced)	The hazelcast instance reference 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.		HazelcastInstance
hazelcastMode (advanced)	The hazelcast mode reference which kind of instance should be used. If you don’t specify the mode, then the node mode will be the default.	node	String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Hazelcast Map endpoint is configured using URI syntax:

hazelcast-map:cacheName

with the following path and query parameters:

122.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cacheName	Required The name of the cache		String

122.1.2. Query Parameters (16 parameters):

Name	Description	Default	Type
defaultOperation (common)	To specify a default operation to use, if no operation header has been provided.		HazelcastOperation
hazelcastInstance (common)	The hazelcast instance reference which can be used for hazelcast endpoint.		HazelcastInstance
hazelcastInstanceName (common)	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.		String
reliable (common)	Define if the endpoint will use a reliable Topic struct or not.	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
pollingTimeout (consumer)	Define the polling timeout of the Queue consumer in Poll mode	10000	long
poolSize (consumer)	Define the Pool size for Queue Consumer Executor	1	int
queueConsumerMode (consumer)	Define the Queue Consumer mode: Listen or Poll	Listen	HazelcastQueueConsumer Mode
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
concurrentConsumers (seda)	To use concurrent consumers polling from the SEDA queue.	1	int
onErrorDelay (seda)	Milliseconds before consumer continues polling after an error has occurred.	1000	int
pollTimeout (seda)	The timeout used when consuming from the SEDA queue. When a timeout occurs, the consumer can check whether it is allowed to continue running. Setting a lower value allows the consumer to react more quickly upon shutdown.	1000	int
transacted (seda)	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.	false	boolean
transferExchange (seda)	If set to true the whole Exchange will be transfered. If header or body contains not serializable objects, they will be skipped.	false	boolean

122.2. 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 follow operations specified by CamelHazelcastOperationType header:

put
putIfAbsent
get
getAll
keySet
containsKey
containsValue
delete
update
query
clear
evict
evictAll

All operations are provide the inside the "hazelcast.operation.type" header variable. In Java DSL you can use the constants from org.apache.camel.component.hazelcast.HazelcastOperation.

Header Variables for the request message:

Name	Type	Description
`CamelHazelcastOperationType`	`String`	as already described.
`CamelHazelcastObjectId`	`String`	the object id to store / find your object inside the cache (not needed for the query operation)

put and putIfAbsent operations provide an eviction mechanism:

Name	Type	Description
`CamelHazelcastObjectTtlValue`	`Integer`	value of TTL.
`CamelHazelcastObjectTtlUnit`	`java.util.concurrent.TimeUnit`	value of time unit ( DAYS / HOURS / MINUTES / ….

You can call the samples with:

template.sendBodyAndHeader("direct:[put|get|update|delete|query|evict]", "my-foo", HazelcastConstants.OBJECT_ID, "4711");

122.2.1. Sample for put:

Java DSL:

from("direct:put")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.PUT))
.toF("hazelcast-%sfoo", HazelcastConstants.MAP_PREFIX);

Spring DSL:

<route>
    <from uri="direct:put" />
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>put</constant>
    </setHeader>
    <to uri="hazelcast-map:foo" />
</route>

Sample for put with eviction:

Java DSL:

from("direct:put")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.PUT))
.setHeader(HazelcastConstants.TTL_VALUE, constant(Long.valueOf(1)))
.setHeader(HazelcastConstants.TTL_UNIT, constant(TimeUnit.MINUTES))
.toF("hazelcast-%sfoo", HazelcastConstants.MAP_PREFIX);

Spring DSL:

<route>
    <from uri="direct:put" />
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>put</constant>
    </setHeader>
    <setHeader headerName="HazelcastConstants.TTL_VALUE">
        <simple resultType="java.lang.Long">1</simple>
    </setHeader>
    <setHeader headerName="HazelcastConstants.TTL_UNIT">
        <simple resultType="java.util.concurrent.TimeUnit">TimeUnit.MINUTES</simple>
    </setHeader>
    <to uri="hazelcast-map:foo" />
</route>

122.2.2. Sample for get:

Java DSL:

from("direct:get")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.GET))
.toF("hazelcast-%sfoo", HazelcastConstants.MAP_PREFIX)
.to("seda:out");

Spring DSL:

<route>
    <from uri="direct:get" />
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>get</constant>
    </setHeader>
    <to uri="hazelcast-map:foo" />
    <to uri="seda:out" />
</route>

122.2.3. Sample for update:

Java DSL:

from("direct:update")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.UPDATE))
.toF("hazelcast-%sfoo", HazelcastConstants.MAP_PREFIX);

Spring DSL:

<route>
    <from uri="direct:update" />
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>update</constant>
    </setHeader>
    <to uri="hazelcast-map:foo" />
</route>

122.2.4. Sample for delete:

Java DSL:

from("direct:delete")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.DELETE))
.toF("hazelcast-%sfoo", HazelcastConstants.MAP_PREFIX);

Spring DSL:

<route>
    <from uri="direct:delete" />
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>delete</constant>
    </setHeader>
    <to uri="hazelcast-map:foo" />
</route>

122.2.5. Sample for query

Java DSL:

from("direct:query")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.QUERY))
.toF("hazelcast-%sfoo", HazelcastConstants.MAP_PREFIX)
.to("seda:out");

Spring DSL:

<route>
    <from uri="direct:query" />
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>query</constant>
    </setHeader>
    <to uri="hazelcast-map:foo" />
    <to uri="seda:out" />
</route>

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

String q1 = "bar > 1000";
template.sendBodyAndHeader("direct:query", null, HazelcastConstants.QUERY, q1);

122.3. 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
`CamelHazelcastListenerTime`	`Long`	time of the event in millis
`CamelHazelcastListenerType`	`String`	the map consumer sets here "cachelistener"
`CamelHazelcastListenerAction`	`String`	type of event - here added, updated, envicted and removed.
`CamelHazelcastObjectId`	`String`	the oid of the object
`CamelHazelcastCacheName`	`String`	the name of the cache - e.g. "foo"
`CamelHazelcastCacheType`	`String`	the type of the cache - here map

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

Here’s a sample:

fromF("hazelcast-%sfoo", HazelcastConstants.MAP_PREFIX)
.log("object...")
.choice()
    .when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ADDED))
         .log("...added")
         .to("mock:added")
    .when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ENVICTED))
         .log("...envicted")
         .to("mock:envicted")
    .when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.UPDATED))
         .log("...updated")
         .to("mock:updated")
    .when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.REMOVED))
         .log("...removed")
         .to("mock:removed")
    .otherwise()
         .log("fail!");

Chapter 123. Hazelcast Multimap Component

Available as of Camel version 2.7

The Hazelcast Multimap component is one of Camel Hazelcast Components which allows you to access Hazelcast distributed multimap.

123.1. Options

The Hazelcast Multimap component supports 3 options which are listed below.

Name	Description	Default	Type
hazelcastInstance (advanced)	The hazelcast instance reference 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.		HazelcastInstance
hazelcastMode (advanced)	The hazelcast mode reference which kind of instance should be used. If you don’t specify the mode, then the node mode will be the default.	node	String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Hazelcast Multimap endpoint is configured using URI syntax:

hazelcast-multimap:cacheName

with the following path and query parameters:

123.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cacheName	Required The name of the cache		String

123.1.2. Query Parameters (16 parameters):

Name	Description	Default	Type
defaultOperation (common)	To specify a default operation to use, if no operation header has been provided.		HazelcastOperation
hazelcastInstance (common)	The hazelcast instance reference which can be used for hazelcast endpoint.		HazelcastInstance
hazelcastInstanceName (common)	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.		String
reliable (common)	Define if the endpoint will use a reliable Topic struct or not.	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
pollingTimeout (consumer)	Define the polling timeout of the Queue consumer in Poll mode	10000	long
poolSize (consumer)	Define the Pool size for Queue Consumer Executor	1	int
queueConsumerMode (consumer)	Define the Queue Consumer mode: Listen or Poll	Listen	HazelcastQueueConsumer Mode
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
concurrentConsumers (seda)	To use concurrent consumers polling from the SEDA queue.	1	int
onErrorDelay (seda)	Milliseconds before consumer continues polling after an error has occurred.	1000	int
pollTimeout (seda)	The timeout used when consuming from the SEDA queue. When a timeout occurs, the consumer can check whether it is allowed to continue running. Setting a lower value allows the consumer to react more quickly upon shutdown.	1000	int
transacted (seda)	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.	false	boolean
transferExchange (seda)	If set to true the whole Exchange will be transfered. If header or body contains not serializable objects, they will be skipped.	false	boolean

123.2. 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
`CamelHazelcastOperationType`	`String`	valid values are: put, get, removevalue, delete From Camel 2.16: clear.
`CamelHazelcastObjectId`	`String`	the object id to store / find your object inside the cache

123.2.1. Sample for put:

Java DSL:

from("direct:put")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.PUT))
.to(String.format("hazelcast-%sbar", HazelcastConstants.MULTIMAP_PREFIX));

Spring DSL:

<route>
    <from uri="direct:put" />
    <log message="put.."/>
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>put</constant>
    </setHeader>
    <to uri="hazelcast-multimap:foo" />
</route>

123.2.2. Sample for removevalue:

Java DSL:

from("direct:removevalue")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.REMOVE_VALUE))
.toF("hazelcast-%sbar", HazelcastConstants.MULTIMAP_PREFIX);

Spring DSL:

<route>
    <from uri="direct:removevalue" />
    <log message="removevalue..."/>
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>removevalue</constant>
    </setHeader>
    <to uri="hazelcast-multimap:foo" />
</route>

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.

123.2.3. Sample for get:

Java DSL:

from("direct:get")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.GET))
.toF("hazelcast-%sbar", HazelcastConstants.MULTIMAP_PREFIX)
.to("seda:out");

Spring DSL:

<route>
    <from uri="direct:get" />
    <log message="get.."/>
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>get</constant>
    </setHeader>
    <to uri="hazelcast-multimap:foo" />
    <to uri="seda:out" />
</route>

123.2.4. Sample for delete:

Java DSL:

from("direct:delete")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.DELETE))
.toF("hazelcast-%sbar", HazelcastConstants.MULTIMAP_PREFIX);

Spring DSL:

<route>
    <from uri="direct:delete" />
    <log message="delete.."/>
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>delete</constant>
    </setHeader>
    <to uri="hazelcast-multimap:foo" />
</route>

you can call them in your test class with:

template.sendBodyAndHeader("direct:[put|get|removevalue|delete]", "my-foo", HazelcastConstants.OBJECT_ID, "4711");

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

fromF("hazelcast-%sbar", HazelcastConstants.MULTIMAP_PREFIX)
.log("object...")
.choice()
    .when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ADDED))
        .log("...added")
                .to("mock:added")
        //.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ENVICTED))
        //        .log("...envicted")
        //        .to("mock:envicted")
        .when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.REMOVED))
                .log("...removed")
                .to("mock:removed")
        .otherwise()
                .log("fail!");

Header Variables inside the response message:

Name	Type	Description
`CamelHazelcastListenerTime`	`Long`	time of the event in millis
`CamelHazelcastListenerType`	`String`	the map consumer sets here "cachelistener"
`CamelHazelcastListenerAction`	`String`	type of event - here added and removed (and soon envicted)
`CamelHazelcastObjectId`	`String`	the oid of the object
`CamelHazelcastCacheName`	`String`	the name of the cache - e.g. "foo"
`CamelHazelcastCacheType`	`String`	the type of the cache - here multimap

Chapter 124. Hazelcast Queue Component

Available as of Camel version 2.7

The Hazelcast Queue component is one of Camel Hazelcast Components which allows you to access Hazelcast distributed queue.

124.1. Options

The Hazelcast Queue component supports 3 options which are listed below.

Name	Description	Default	Type
hazelcastInstance (advanced)	The hazelcast instance reference 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.		HazelcastInstance
hazelcastMode (advanced)	The hazelcast mode reference which kind of instance should be used. If you don’t specify the mode, then the node mode will be the default.	node	String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Hazelcast Queue endpoint is configured using URI syntax:

hazelcast-queue:cacheName

with the following path and query parameters:

124.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cacheName	Required The name of the cache		String

124.1.2. Query Parameters (16 parameters):

Name	Description	Default	Type
defaultOperation (common)	To specify a default operation to use, if no operation header has been provided.		HazelcastOperation
hazelcastInstance (common)	The hazelcast instance reference which can be used for hazelcast endpoint.		HazelcastInstance
hazelcastInstanceName (common)	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.		String
reliable (common)	Define if the endpoint will use a reliable Topic struct or not.	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
pollingTimeout (consumer)	Define the polling timeout of the Queue consumer in Poll mode	10000	long
poolSize (consumer)	Define the Pool size for Queue Consumer Executor	1	int
queueConsumerMode (consumer)	Define the Queue Consumer mode: Listen or Poll	Listen	HazelcastQueueConsumer Mode
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
concurrentConsumers (seda)	To use concurrent consumers polling from the SEDA queue.	1	int
onErrorDelay (seda)	Milliseconds before consumer continues polling after an error has occurred.	1000	int
pollTimeout (seda)	The timeout used when consuming from the SEDA queue. When a timeout occurs, the consumer can check whether it is allowed to continue running. Setting a lower value allows the consumer to react more quickly upon shutdown.	1000	int
transacted (seda)	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.	false	boolean
transferExchange (seda)	If set to true the whole Exchange will be transfered. If header or body contains not serializable objects, they will be skipped.	false	boolean

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

The queue producer provides 10 operations: * add * put * poll * peek * offer * remove value * remaining capacity * remove all * remove if * drain to * take * retain all

124.2.1. Sample for add:

from("direct:add")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.ADD))
.toF("hazelcast-%sbar", HazelcastConstants.QUEUE_PREFIX);

124.2.2. Sample for put:

from("direct:put")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.PUT))
.toF("hazelcast-%sbar", HazelcastConstants.QUEUE_PREFIX);

124.2.3. Sample for poll:

from("direct:poll")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.POLL))
.toF("hazelcast:%sbar", HazelcastConstants.QUEUE_PREFIX);

124.2.4. Sample for peek:

from("direct:peek")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.PEEK))
.toF("hazelcast:%sbar", HazelcastConstants.QUEUE_PREFIX);

124.2.5. Sample for offer:

from("direct:offer")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.OFFER))
.toF("hazelcast:%sbar", HazelcastConstants.QUEUE_PREFIX);

124.2.6. Sample for removevalue:

from("direct:removevalue")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.REMOVE_VALUE))
.toF("hazelcast-%sbar", HazelcastConstants.QUEUE_PREFIX);

124.2.7. Sample for remaining capacity:

from("direct:remaining-capacity").setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.REMAINING_CAPACITY)).to(
String.format("hazelcast-%sbar", HazelcastConstants.QUEUE_PREFIX));

124.2.8. Sample for remove all:

from("direct:removeAll").setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.REMOVE_ALL)).to(
String.format("hazelcast-%sbar", HazelcastConstants.QUEUE_PREFIX));

124.2.9. Sample for remove if:

from("direct:removeIf").setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.REMOVE_IF)).to(
String.format("hazelcast-%sbar", HazelcastConstants.QUEUE_PREFIX));

124.2.10. Sample for drain to:

from("direct:drainTo").setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.DRAIN_TO)).to(
String.format("hazelcast-%sbar", HazelcastConstants.QUEUE_PREFIX));

124.2.11. Sample for take:

from("direct:take").setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.TAKE)).to(
String.format("hazelcast-%sbar", HazelcastConstants.QUEUE_PREFIX));

124.2.12. Sample for retain all:

from("direct:retainAll").setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.RETAIN_ALL)).to(
String.format("hazelcast-%sbar", HazelcastConstants.QUEUE_PREFIX));

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

The queue consumer provides two different modes:

Poll
Listen

Sample for Poll mode

fromF("hazelcast-%sfoo?queueConsumerMode=Poll", HazelcastConstants.QUEUE_PREFIX)).to("mock:result");

In this way the consumer will poll the queue and return the head of the queue or null after a timeout.

In Listen mode instead the consumer will listen for events on queue.

The queue consumer in Listen mode provides 2 operations: * add * remove

Sample for Listen mode

fromF("hazelcast-%smm", HazelcastConstants.QUEUE_PREFIX)
   .log("object...")
   .choice()
    .when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ADDED))
            .log("...added")
        .to("mock:added")
    .when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.REMOVED))
        .log("...removed")
        .to("mock:removed")
    .otherwise()
        .log("fail!");

Chapter 125. Hazelcast Replicated Map Component

Available as of Camel version 2.16

The Hazelcast instance component is one of Camel Hazelcast Components which allows you to consume join/leave events of the cache instance in the cluster. A replicated map is a weakly consistent, distributed key-value data structure with no data partition.

125.1. Options

The Hazelcast Replicated Map component supports 3 options which are listed below.

Name	Description	Default	Type
hazelcastInstance (advanced)	The hazelcast instance reference 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.		HazelcastInstance
hazelcastMode (advanced)	The hazelcast mode reference which kind of instance should be used. If you don’t specify the mode, then the node mode will be the default.	node	String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Hazelcast Replicated Map endpoint is configured using URI syntax:

hazelcast-replicatedmap:cacheName

with the following path and query parameters:

125.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cacheName	Required The name of the cache		String

125.1.2. Query Parameters (16 parameters):

Name	Description	Default	Type
defaultOperation (common)	To specify a default operation to use, if no operation header has been provided.		HazelcastOperation
hazelcastInstance (common)	The hazelcast instance reference which can be used for hazelcast endpoint.		HazelcastInstance
hazelcastInstanceName (common)	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.		String
reliable (common)	Define if the endpoint will use a reliable Topic struct or not.	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
pollingTimeout (consumer)	Define the polling timeout of the Queue consumer in Poll mode	10000	long
poolSize (consumer)	Define the Pool size for Queue Consumer Executor	1	int
queueConsumerMode (consumer)	Define the Queue Consumer mode: Listen or Poll	Listen	HazelcastQueueConsumer Mode
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
concurrentConsumers (seda)	To use concurrent consumers polling from the SEDA queue.	1	int
onErrorDelay (seda)	Milliseconds before consumer continues polling after an error has occurred.	1000	int
pollTimeout (seda)	The timeout used when consuming from the SEDA queue. When a timeout occurs, the consumer can check whether it is allowed to continue running. Setting a lower value allows the consumer to react more quickly upon shutdown.	1000	int
transacted (seda)	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.	false	boolean
transferExchange (seda)	If set to true the whole Exchange will be transfered. If header or body contains not serializable objects, they will be skipped.	false	boolean

125.2. replicatedmap cache producer

The replicatedmap producer provides 4 operations: * put * get * delete * clear

Header Variables for the request message:

Name	Type	Description
`CamelHazelcastOperationType`	`String`	valid values are: put, get, removevalue, delete
`CamelHazelcastObjectId`	`String`	the object id to store / find your object inside the cache

125.2.1. Sample for put:

Java DSL:

from("direct:put")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.PUT))
.to(String.format("hazelcast-%sbar", HazelcastConstants.REPLICATEDMAP_PREFIX));

Spring DSL:

<route>
    <from uri="direct:put" />
    <log message="put.."/>
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>put</constant>
    </setHeader>
    <to uri="hazelcast-replicatedmap:foo" />
</route>

125.2.2. Sample for get:

Java DSL:

from("direct:get")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.GET))
.toF("hazelcast-%sbar", HazelcastConstants.REPLICATEDMAP_PREFIX)
.to("seda:out");

Spring DSL:

<route>
    <from uri="direct:get" />
    <log message="get.."/>
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>get</constant>
    </setHeader>
    <to uri="hazelcast-replicatedmap:foo" />
    <to uri="seda:out" />
</route>

125.2.3. Sample for delete:

Java DSL:

from("direct:delete")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.DELETE))
.toF("hazelcast-%sbar", HazelcastConstants.REPLICATEDMAP_PREFIX);

Spring DSL:

<route>
    <from uri="direct:delete" />
    <log message="delete.."/>
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>delete</constant>
    </setHeader>
    <to uri="hazelcast-replicatedmap:foo" />
</route>

you can call them in your test class with:

template.sendBodyAndHeader("direct:[put|get|delete|clear]", "my-foo", HazelcastConstants.OBJECT_ID, "4711");

125.3. replicatedmap cache consumer

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:

fromF("hazelcast-%sbar", HazelcastConstants.MULTIMAP_PREFIX)
.log("object...")
.choice()
    .when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ADDED))
        .log("...added")
                .to("mock:added")
        //.when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.ENVICTED))
        //        .log("...envicted")
        //        .to("mock:envicted")
        .when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.REMOVED))
                .log("...removed")
                .to("mock:removed")
        .otherwise()
                .log("fail!");

Header Variables inside the response message:

Name	Type	Description
`CamelHazelcastListenerTime`	`Long`	time of the event in millis
`CamelHazelcastListenerType`	`String`	the map consumer sets here "cachelistener"
`CamelHazelcastListenerAction`	`String`	type of event - here added and removed (and soon envicted)
`CamelHazelcastObjectId`	`String`	the oid of the object
`CamelHazelcastCacheName`	`String`	the name of the cache - e.g. "foo"
`CamelHazelcastCacheType`	`String`	the type of the cache - here replicatedmap

Chapter 126. Hazelcast Ringbuffer Component

Available as of Camel version 2.16

Avalaible from Camel 2.16

The Hazelcast ringbuffer component is one of Camel Hazelcast Components which allows you to access Hazelcast ringbuffer. Ringbuffer is a distributed data structure where the data is stored in a ring-like structure. You can think of it as a circular array with a certain capacity.

126.1. Options

The Hazelcast Ringbuffer component supports 3 options which are listed below.

Name	Description	Default	Type
hazelcastInstance (advanced)	The hazelcast instance reference 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.		HazelcastInstance
hazelcastMode (advanced)	The hazelcast mode reference which kind of instance should be used. If you don’t specify the mode, then the node mode will be the default.	node	String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Hazelcast Ringbuffer endpoint is configured using URI syntax:

hazelcast-ringbuffer:cacheName

with the following path and query parameters:

126.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cacheName	Required The name of the cache		String

126.1.2. Query Parameters (10 parameters):

Name	Description	Default	Type
reliable (common)	Define if the endpoint will use a reliable Topic struct or not.	false	boolean
defaultOperation (producer)	To specify a default operation to use, if no operation header has been provided.		HazelcastOperation
hazelcastInstance (producer)	The hazelcast instance reference which can be used for hazelcast endpoint.		HazelcastInstance
hazelcastInstanceName (producer)	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.		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
concurrentConsumers (seda)	To use concurrent consumers polling from the SEDA queue.	1	int
onErrorDelay (seda)	Milliseconds before consumer continues polling after an error has occurred.	1000	int
pollTimeout (seda)	The timeout used when consuming from the SEDA queue. When a timeout occurs, the consumer can check whether it is allowed to continue running. Setting a lower value allows the consumer to react more quickly upon shutdown.	1000	int
transacted (seda)	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.	false	boolean
transferExchange (seda)	If set to true the whole Exchange will be transfered. If header or body contains not serializable objects, they will be skipped.	false	boolean

126.2. ringbuffer cache producer

The ringbuffer producer provides 5 operations: * add * readonceHead * readonceTail * remainingCapacity * capacity

Header Variables for the request message:

Name	Type	Description
`CamelHazelcastOperationType`	`String`	valid values are: put, get, removevalue, delete
`CamelHazelcastObjectId`	`String`	the object id to store / find your object inside the cache

126.2.1. Sample for put:

Java DSL:

from("direct:put")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.ADD))
.to(String.format("hazelcast-%sbar", HazelcastConstants.RINGBUFFER_PREFIX));

Spring DSL:

<route>
    <from uri="direct:put" />
    <log message="put.."/>
        <!-- If using version 2.8 and above set headerName to "CamelHazelcastOperationType" -->
    <setHeader headerName="hazelcast.operation.type">
        <constant>add</constant>
    </setHeader>
    <to uri="hazelcast-ringbuffer:foo" />
</route>

126.2.2. Sample for readonce from head:

Java DSL:

from("direct:get")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.READ_ONCE_HEAD))
.toF("hazelcast-%sbar", HazelcastConstants.RINGBUFFER_PREFIX)
.to("seda:out");

Chapter 127. Hazelcast SEDA Component

Available as of Camel version 2.7

The Hazelcast SEDA component is one of Camel Hazelcast Components which allows you to access Hazelcast BlockingQueue. 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.

127.1. Options

The Hazelcast SEDA component supports 3 options which are listed below.

Name	Description	Default	Type
hazelcastInstance (advanced)	The hazelcast instance reference 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.		HazelcastInstance
hazelcastMode (advanced)	The hazelcast mode reference which kind of instance should be used. If you don’t specify the mode, then the node mode will be the default.	node	String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Hazelcast SEDA endpoint is configured using URI syntax:

hazelcast-seda:cacheName

with the following path and query parameters:

127.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cacheName	Required The name of the cache		String

127.1.2. Query Parameters (16 parameters):

Name	Description	Default	Type
defaultOperation (common)	To specify a default operation to use, if no operation header has been provided.		HazelcastOperation
hazelcastInstance (common)	The hazelcast instance reference which can be used for hazelcast endpoint.		HazelcastInstance
hazelcastInstanceName (common)	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.		String
reliable (common)	Define if the endpoint will use a reliable Topic struct or not.	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
pollingTimeout (consumer)	Define the polling timeout of the Queue consumer in Poll mode	10000	long
poolSize (consumer)	Define the Pool size for Queue Consumer Executor	1	int
queueConsumerMode (consumer)	Define the Queue Consumer mode: Listen or Poll	Listen	HazelcastQueueConsumer Mode
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
concurrentConsumers (seda)	To use concurrent consumers polling from the SEDA queue.	1	int
onErrorDelay (seda)	Milliseconds before consumer continues polling after an error has occurred.	1000	int
pollTimeout (seda)	The timeout used when consuming from the SEDA queue. When a timeout occurs, the consumer can check whether it is allowed to continue running. Setting a lower value allows the consumer to react more quickly upon shutdown.	1000	int
transacted (seda)	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.	false	boolean
transferExchange (seda)	If set to true the whole Exchange will be transfered. If header or body contains not serializable objects, they will be skipped.	false	boolean

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

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

Java DSL :

from("direct:foo")
.to("hazelcast-seda:foo");

Spring DSL :

<route>
   <from uri="direct:start" />
   <to uri="hazelcast-seda:foo" />
</route>

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

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

Java DSL :

from("hazelcast-seda:foo")
.to("mock:result");

Spring DSL:

<route>
  <from uri="hazelcast-seda:foo" />
  <to uri="mock:result" />
</route>

Chapter 128. Hazelcast Set Component

Available as of Camel version 2.7

The Hazelcast Set component is one of Camel Hazelcast Components which allows you to access Hazelcast distributed set.

128.1. Options

The Hazelcast Set component supports 3 options which are listed below.

Name	Description	Default	Type
hazelcastInstance (advanced)	The hazelcast instance reference 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.		HazelcastInstance
hazelcastMode (advanced)	The hazelcast mode reference which kind of instance should be used. If you don’t specify the mode, then the node mode will be the default.	node	String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Hazelcast Set endpoint is configured using URI syntax:

hazelcast-set:cacheName

with the following path and query parameters:

128.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cacheName	Required The name of the cache		String

128.1.2. Query Parameters (16 parameters):

Name	Description	Default	Type
defaultOperation (common)	To specify a default operation to use, if no operation header has been provided.		HazelcastOperation
hazelcastInstance (common)	The hazelcast instance reference which can be used for hazelcast endpoint.		HazelcastInstance
hazelcastInstanceName (common)	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.		String
reliable (common)	Define if the endpoint will use a reliable Topic struct or not.	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
pollingTimeout (consumer)	Define the polling timeout of the Queue consumer in Poll mode	10000	long
poolSize (consumer)	Define the Pool size for Queue Consumer Executor	1	int
queueConsumerMode (consumer)	Define the Queue Consumer mode: Listen or Poll	Listen	HazelcastQueueConsumer Mode
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
concurrentConsumers (seda)	To use concurrent consumers polling from the SEDA queue.	1	int
onErrorDelay (seda)	Milliseconds before consumer continues polling after an error has occurred.	1000	int
pollTimeout (seda)	The timeout used when consuming from the SEDA queue. When a timeout occurs, the consumer can check whether it is allowed to continue running. Setting a lower value allows the consumer to react more quickly upon shutdown.	1000	int
transacted (seda)	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.	false	boolean
transferExchange (seda)	If set to true the whole Exchange will be transfered. If header or body contains not serializable objects, they will be skipped.	false	boolean

Chapter 129. Hazelcast Topic Component

Available as of Camel version 2.15

The Hazelcast Topic component is one of Camel Hazelcast Components which allows you to access Hazelcast distributed topic.

129.1. Options

The Hazelcast Topic component supports 3 options which are listed below.

Name	Description	Default	Type
hazelcastInstance (advanced)	The hazelcast instance reference 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.		HazelcastInstance
hazelcastMode (advanced)	The hazelcast mode reference which kind of instance should be used. If you don’t specify the mode, then the node mode will be the default.	node	String
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The Hazelcast Topic endpoint is configured using URI syntax:

hazelcast-topic:cacheName

with the following path and query parameters:

129.1.1. Path Parameters (1 parameters):

Name	Description	Default	Type
cacheName	Required The name of the cache		String

129.1.2. Query Parameters (16 parameters):

Name	Description	Default	Type
defaultOperation (common)	To specify a default operation to use, if no operation header has been provided.		HazelcastOperation
hazelcastInstance (common)	The hazelcast instance reference which can be used for hazelcast endpoint.		HazelcastInstance
hazelcastInstanceName (common)	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.		String
reliable (common)	Define if the endpoint will use a reliable Topic struct or not.	false	boolean
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
pollingTimeout (consumer)	Define the polling timeout of the Queue consumer in Poll mode	10000	long
poolSize (consumer)	Define the Pool size for Queue Consumer Executor	1	int
queueConsumerMode (consumer)	Define the Queue Consumer mode: Listen or Poll	Listen	HazelcastQueueConsumer Mode
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
concurrentConsumers (seda)	To use concurrent consumers polling from the SEDA queue.	1	int
onErrorDelay (seda)	Milliseconds before consumer continues polling after an error has occurred.	1000	int
pollTimeout (seda)	The timeout used when consuming from the SEDA queue. When a timeout occurs, the consumer can check whether it is allowed to continue running. Setting a lower value allows the consumer to react more quickly upon shutdown.	1000	int
transacted (seda)	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.	false	boolean
transferExchange (seda)	If set to true the whole Exchange will be transfered. If header or body contains not serializable objects, they will be skipped.	false	boolean

129.2. Topic producer – to(“hazelcast-topic:foo”)

The topic producer provides only one operation (publish).

129.2.1. Sample for publish:

from("direct:add")
.setHeader(HazelcastConstants.OPERATION, constant(HazelcastOperation.PUBLISH))
.toF("hazelcast-%sbar", HazelcastConstants.PUBLISH_OPERATION);

129.3. Topic consumer – from(“hazelcast-topic:foo”)

The topic consumer provides only one operation (received). This component is supposed to support multiple consumption as it’s expected when it comes to topics so you are free to have as much consumers as you need on the same hazelcast topic.

fromF("hazelcast-%sfoo", HazelcastConstants.TOPIC_PREFIX)
  .choice()
    .when(header(HazelcastConstants.LISTENER_ACTION).isEqualTo(HazelcastConstants.RECEIVED))
      .log("...message received")
    .otherwise()
      .log("...this should never have happened")

Chapter 130. HBase Component

Available as of Camel version 2.10

This component provides an idemptotent repository, producers and consumers for Apache HBase.

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

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

130.1. Apache HBase Overview

HBase is an open-source, distributed, versioned, column-oriented store modeled after Google’s Bigtable: A Distributed Storage System for Structured Data. You can use HBase when you need random, realtime read/write access to your Big Data. More information at Apache HBase.

130.2. Camel and HBase

When using a datasotre inside a camel route, there is always the chalenge of specifying how the camel message will stored to the datastore. In document based stores things are more easy as the message body can be directly mapped to a document. In relational databases an ORM solution can be used to map properties to columns etc. In column based stores things are more challenging as there is no standard way to perform that kind of mapping.

HBase adds two additional challenges:

HBase groups columns into families, so just mapping a property to a column using a name convention is just not enough.
HBase doesn’t have the notion of type, which means that it stores everything as byte[] and doesn’t know if the byte[] represents a String, a Number, a serialized Java object or just binary data.

To overcome these challenges, camel-hbase makes use of the message headers to specify the mapping of the message to HBase columns. It also provides the ability to use some camel-hbase provided classes that model HBase data and can be easily convert to and from xml/json etc.
Finally it provides the ability to the user to implement and use his own mapping strategy.

Regardless of the mapping strategy camel-hbase will convert a message into an org.apache.camel.component.hbase.model.HBaseData object and use that object for its internal operations.

130.3. Configuring the component

The HBase component can be provided a custom HBaseConfiguration object as a property or it can create an HBase configuration object on its own based on the HBase related resources that are found on classpath.

    <bean id="hbase" class="org.apache.camel.component.hbase.HBaseComponent">
        <property name="configuration" ref="config"/>
    </bean>

If no configuration object is provided to the component, the component will create one. The created configuration will search the class path for an hbase-site.xml file, from which it will draw the configuration. You can find more information about how to configure HBase clients at: HBase client configuration and dependencies

130.4. HBase Producer

As mentioned above camel provides produers endpoints for HBase. This allows you to store, delete, retrieve or query data from HBase using your camel routes.

hbase://table[?options]

where table is the table name.

The supported operations are:

Put
Get
Delete
Scan

130.4.1. Supported URI options

The HBase component supports 3 options which are listed below.

Name	Description	Default	Type
configuration (advanced)	To use the shared configuration		Configuration
poolMaxSize (common)	Maximum number of references to keep for each table in the HTable pool. The default value is 10.	10	int
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The HBase endpoint is configured using URI syntax:

hbase:tableName

with the following path and query parameters:

130.4.2. Path Parameters (1 parameters):

Name	Description	Default	Type
tableName	Required The name of the table		String

130.4.3. Query Parameters (16 parameters):

Name	Description	Default	Type
cellMappingStrategyFactory (common)	To use a custom CellMappingStrategyFactory that is responsible for mapping cells.		CellMappingStrategy Factory
filters (common)	A list of filters to use.		List
mappingStrategyClassName (common)	The class name of a custom mapping strategy implementation.		String
mappingStrategyName (common)	The strategy to use for mapping Camel messages to HBase columns. Supported values: header, or body.		String
rowMapping (common)	To map the key/values from the Map to a HBaseRow. The following keys is supported: rowId - The id of the row. This has limited use as the row usually changes per Exchange. rowType - The type to covert row id to. Supported operations: CamelHBaseScan. family - The column family. Supports a number suffix for referring to more than one columns. qualifier - The column qualifier. Supports a number suffix for referring to more than one columns. value - The value. Supports a number suffix for referring to more than one columns valueType - The value type. Supports a number suffix for referring to more than one columns. Supported operations: CamelHBaseGet, and CamelHBaseScan.		Map
rowModel (common)	An instance of org.apache.camel.component.hbase.model.HBaseRow which describes how each row should be modeled		HBaseRow
userGroupInformation (common)	Defines privileges to communicate with HBase such as using kerberos.		UserGroupInformation
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
maxMessagesPerPoll (consumer)	Gets the maximum number of messages as a limit to poll at each polling. Is default unlimited, but use 0 or negative number to disable it as unlimited.		int
operation (consumer)	The HBase operation to perform		String
remove (consumer)	If the option is true, Camel HBase Consumer will remove the rows which it processes.	true	boolean
removeHandler (consumer)	To use a custom HBaseRemoveHandler that is executed when a row is to be removed.		HBaseRemoveHandler
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
maxResults (producer)	The maximum number of rows to scan.	100	int
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean

130.4.4. Put Operations.

HBase is a column based store, which allows you to store data into a specific column of a specific row. Columns are grouped into families, so in order to specify a column you need to specify the column family and the qualifier of that column. To store data into a specific column you need to specify both the column and the row.

The simplest scenario for storing data into HBase from a camel route, would be to store part of the message body to specified HBase column.

        <route>
            <from uri="direct:in"/>
            <!-- Set the HBase Row -->
            <setHeader headerName="CamelHBaseRowId">
                <el>${in.body.id}</el>
            </setHeader>
            <!-- Set the HBase Value -->
            <setHeader headerName="CamelHBaseValue">
                <el>${in.body.value}</el>
            </setHeader>
            <to uri="hbase:mytable?operation=CamelHBasePut&amp;family=myfamily&amp;qualifier=myqualifier"/>
        </route>

The route above assumes that the message body contains an object that has an id and value property and will store the content of value in the HBase column myfamily:myqualifier in the row specified by id. If we needed to specify more than one column/value pairs we could just specify additional column mappings. Notice that you must use numbers from the 2nd header onwards, eg RowId2, RowId3, RowId4, etc. Only the 1st header does not have the number 1.

        <route>
            <from uri="direct:in"/>
            <!-- Set the HBase Row 1st column -->
            <setHeader headerName="CamelHBaseRowId">
                <el>${in.body.id}</el>
            </setHeader>
            <!-- Set the HBase Row 2nd column -->
            <setHeader headerName="CamelHBaseRowId2">
                <el>${in.body.id}</el>
            </setHeader>
            <!-- Set the HBase Value for 1st column -->
            <setHeader headerName="CamelHBaseValue">
                <el>${in.body.value}</el>
            </setHeader>
            <!-- Set the HBase Value for 2nd column -->
            <setHeader headerName="CamelHBaseValue2">
                <el>${in.body.othervalue}</el>
            </setHeader>
            <to uri="hbase:mytable?operation=CamelHBasePut&amp;family=myfamily&amp;qualifier=myqualifier&amp;family2=myfamily&amp;qualifier2=myqualifier2"/>
        </route>

It is important to remember that you can use uri options, message headers or a combination of both. It is recommended to specify constants as part of the uri and dynamic values as headers. If something is defined both as header and as part of the uri, the header will be used.

130.4.5. Get Operations.

A Get Operation is an operation that is used to retrieve one or more values from a specified HBase row. To specify what are the values that you want to retrieve you can just specify them as part of the uri or as message headers.

        <route>
            <from uri="direct:in"/>
            <!-- Set the HBase Row of the Get -->
            <setHeader headerName="CamelHBaseRowId">
                <el>${in.body.id}</el>
            </setHeader>
            <to uri="hbase:mytable?operation=CamelHBaseGet&amp;family=myfamily&amp;qualifier=myqualifier&amp;valueType=java.lang.Long"/>
            <to uri="log:out"/>
        </route>

In the example above the result of the get operation will be stored as a header with name CamelHBaseValue.

130.4.6. Delete Operations.

You can also you camel-hbase to perform HBase delete operation. The delete operation will remove an entire row. All that needs to be specified is one or more rows as part of the message headers.

        <route>
            <from uri="direct:in"/>
            <!-- Set the HBase Row of the Get -->
            <setHeader headerName="CamelHBaseRowId">
                <el>${in.body.id}</el>
            </setHeader>
            <to uri="hbase:mytable?operation=CamelHBaseDelete"/>
        </route>

130.4.7. Scan Operations.

A scan operation is the equivalent of a query in HBase. You can use the scan operation to retrieve multiple rows. To specify what columns should be part of the result and also specify how the values will be converted to objects you can use either uri options or headers.

        <route>
            <from uri="direct:in"/>
            <to uri="hbase:mytable?operation=CamelHBaseScan&amp;family=myfamily&amp;qualifier=myqualifier&amp;valueType=java.lang.Long&amp;rowType=java.lang.String"/>
            <to uri="log:out"/>
        </route>

In this case its probable that you also also need to specify a list of filters for limiting the results. You can specify a list of filters as part of the uri and camel will return only the rows that satisfy ALL the filters.
To have a filter that will be aware of the information that is part of the message, camel defines the ModelAwareFilter. This will allow your filter to take into consideration the model that is defined by the message and the mapping strategy.
When using a ModelAwareFilter camel-hbase will apply the selected mapping strategy to the in message, will create an object that models the mapping and will pass that object to the Filter.

For example to perform scan using as criteria the message headers, you can make use of the ModelAwareColumnMatchingFilter as shown below.

        <route>
            <from uri="direct:scan"/>
            <!-- Set the Criteria -->
            <setHeader headerName="CamelHBaseFamily">
                <constant>name</constant>
            </setHeader>
            <setHeader headerName="CamelHBaseQualifier">
                <constant>first</constant>
            </setHeader>
            <setHeader headerName="CamelHBaseValue">
                <el>in.body.firstName</el>
            </setHeader>
            <setHeader headerName="CamelHBaseFamily2">
                <constant>name</constant>
            </setHeader>
            <setHeader headerName="CamelHBaseQualifier2">
                <constant>last</constant>
            </setHeader>
            <setHeader headerName="CamelHBaseValue2">
                <el>in.body.lastName</el>
            </setHeader>
            <!-- Set additional fields that you want to be return by skipping value -->
            <setHeader headerName="CamelHBaseFamily3">
                <constant>address</constant>
            </setHeader>
            <setHeader headerName="CamelHBaseQualifier3">
                <constant>country</constant>
            </setHeader>
            <to uri="hbase:mytable?operation=CamelHBaseScan&amp;filters=#myFilterList"/>
        </route>

        <bean id="myFilters" class="java.util.ArrayList">
            <constructor-arg>
                <list>
                    <bean class="org.apache.camel.component.hbase.filters.ModelAwareColumnMatchingFilter"/>
                </list>
            </constructor-arg>
        </bean>

The route above assumes that a pojo is with properties firstName and lastName is passed as the message body, it takes those properties and adds them as part of the message headers. The default mapping strategy will create a model object that will map the headers to HBase columns and will pass that model the the ModelAwareColumnMatchingFilter. The filter will filter out any rows, that do not contain columns that match the model. It is like query by example.

130.5. HBase Consumer

The Camel HBase Consumer, will perform repeated scan on the specified HBase table and will return the scan results as part of the message. You can either specify header mapping (default) or body mapping. The later will just add the org.apache.camel.component.hbase.model.HBaseData as part of the message body.

hbase://table[?options]

You can specify the columns that you want to be return and their types as part of the uri options:

hbase:mutable?family=name&qualifer=first&valueType=java.lang.String&family=address&qualifer=number&valueType2=java.lang.Integer&rowType=java.lang.Long

The example above will create a model object that is consisted of the specified fields and the scan results will populate the model object with values. Finally the mapping strategy will be used to map this model to the camel message.

130.6. HBase Idempotent repository

The camel-hbase component also provides an idempotent repository which can be used when you want to make sure that each message is processed only once. The HBase idempotent repository is configured with a table, a column family and a column qualifier and will create to that table a row per message.

HBaseConfiguration configuration = HBaseConfiguration.create();
HBaseIdempotentRepository repository = new HBaseIdempotentRepository(configuration, tableName, family, qualifier);

from("direct:in")
  .idempotentConsumer(header("messageId"), repository)
  .to("log:out);

130.7. HBase Mapping

It was mentioned above that you the default mapping strategies are header and body mapping.
Below you can find some detailed examples of how each mapping strategy works.

130.7.1. HBase Header mapping Examples

The header mapping is the default mapping. To put the value "myvalue" into HBase row "myrow" and column "myfamily:mycolum" the message should contain the following headers:

Header	Value
CamelHBaseRowId	myrow
CamelHBaseFamily	myfamily
CamelHBaseQualifier	myqualifier
CamelHBaseValue	myvalue

To put more values for different columns and / or different rows you can specify additional headers suffixed with the index of the headers, e.g:

Header	Value
CamelHBaseRowId	myrow
CamelHBaseFamily	myfamily
CamelHBaseQualifier	myqualifier
CamelHBaseValue	myvalue
CamelHBaseRowId2	myrow2
CamelHBaseFamily2	myfamily
CamelHBaseQualifier2	myqualifier
CamelHBaseValue2	myvalue2

In the case of retrieval operations such as get or scan you can also specify for each column the type that you want the data to be converted to. For exampe:

Header	Value
CamelHBaseFamily	myfamily
CamelHBaseQualifier	myqualifier
CamelHBaseValueType	Long

Please note that in order to avoid boilerplate headers that are considered constant for all messages, you can also specify them as part of the endpoint uri, as you will see below.

130.7.2. Body mapping Examples

In order to use the body mapping strategy you will have to specify the option mappingStrategy as part of the uri, for example:

hbase:mytable?mappingStrategyName=body

To use the body mapping strategy the body needs to contain an instance of org.apache.camel.component.hbase.model.HBaseData. You can construct t

HBaseData data = new HBaseData();
HBaseRow row = new HBaseRow();
row.setId("myRowId");
HBaseCell cell = new HBaseCell();
cell.setFamily("myfamily");
cell.setQualifier("myqualifier");
cell.setValue("myValue");
row.getCells().add(cell);
data.addRows().add(row);

The object above can be used for example in a put operation and will result in creating or updating the row with id myRowId and add the value myvalue to the column myfamily:myqualifier.
The body mapping strategy might not seem very appealing at first. The advantage it has over the header mapping strategy is that the HBaseData object can be easily converted to or from xml/json.

130.8. See also

Polling Consumer
Apache HBase

Chapter 131. HDFS Component (deprecated)

Available as of Camel version 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:

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

131.1. URI format

hdfs://hostname[:port][/path][?options]

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

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

Note

When consuming from hdfs then in normal mode, a file is split into chunks, producing a message per chunk. You can configure the size of the chunk using the chunkSize option. If you want to read from hdfs and write to a regular file using the file component, then you can use the fileMode=Append to append each of the chunks together.

131.2. Options

The HDFS component supports 2 options which are listed below.

Name	Description	Default	Type
jAASConfiguration (common)	To use the given configuration for security with JAAS.		Configuration
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The HDFS endpoint is configured using URI syntax:

hdfs:hostName:port/path

with the following path and query parameters:

131.2.1. Path Parameters (3 parameters):

Name	Description	Default	Type
hostName	Required HDFS host to use		String
port	HDFS port to use	8020	int
path	Required The directory path to use		String

131.2.2. Query Parameters (38 parameters):

Name	Description	Default	Type
connectOnStartup (common)	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.	true	boolean
fileSystemType (common)	Set to LOCAL to not use HDFS but local java.io.File instead.	HDFS	HdfsFileSystemType
fileType (common)	The file type to use. For more details see Hadoop HDFS documentation about the various files types.	NORMAL_FILE	HdfsFileType
keyType (common)	The type for the key in case of sequence or map files.	NULL	WritableType
owner (common)	The file owner must match this owner for the consumer to pickup the file. Otherwise the file is skipped.		String
valueType (common)	The type for the key in case of sequence or map files	BYTES	WritableType
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
delay (consumer)	The interval (milliseconds) between the directory scans.	1000	long
initialDelay (consumer)	For the consumer, how much to wait (milliseconds) before to start scanning the directory.		long
pattern (consumer)	The pattern used for scanning the directory	*	String
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
append (producer)	Append to existing file. Notice that not all HDFS file systems support the append option.	false	boolean
overwrite (producer)	Whether to overwrite existing files with the same name	true	boolean
blockSize (advanced)	The size of the HDFS blocks	67108864	long
bufferSize (advanced)	The buffer size used by HDFS	4096	int
checkIdleInterval (advanced)	How often (time in millis) in to run the idle checker background task. This option is only in use if the splitter strategy is IDLE.	500	int
chunkSize (advanced)	When reading a normal file, this is split into chunks producing a message per chunk.	4096	int
compressionCodec (advanced)	The compression codec to use	DEFAULT	HdfsCompressionCodec
compressionType (advanced)	The compression type to use (is default not in use)	NONE	CompressionType
openedSuffix (advanced)	When a file is opened for reading/writing the file is renamed with this suffix to avoid to read it during the writing phase.	opened	String
readSuffix (advanced)	Once the file has been read is renamed with this suffix to avoid to read it again.	read	String
replication (advanced)	The HDFS replication factor	3	short
splitStrategy (advanced)	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		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean

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

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

Note

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:

hdfs://localhost/tmp/simple-file?splitStrategy=IDLE:1000,BYTES:5

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.

131.4. Message Headers

The following headers are supported by this component:

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

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

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

Chapter 132. HDFS2 Component

Available as of Camel version 2.14

The hdfs2 component enables you to read and write messages from/to an HDFS file system using Hadoop 2.x. 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:

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

132.1. URI format

hdfs2://hostname[:port][/path][?options]

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

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

When consuming from hdfs2 then in normal mode, a file is split into chunks, producing a message per chunk. You can configure the size of the chunk using the chunkSize option. If you want to read from hdfs and write to a regular file using the file component, then you can use the fileMode=Append to append each of the chunks together.

132.2. Options

The HDFS2 component supports 2 options which are listed below.

Name	Description	Default	Type
jAASConfiguration (common)	To use the given configuration for security with JAAS.		Configuration
resolveProperty Placeholders (advanced)	Whether the component should resolve property placeholders on itself when starting. Only properties which are of String type can use property placeholders.	true	boolean

The HDFS2 endpoint is configured using URI syntax:

hdfs2:hostName:port/path

with the following path and query parameters:

132.2.1. Path Parameters (3 parameters):

Name	Description	Default	Type
hostName	Required HDFS host to use		String
port	HDFS port to use	8020	int
path	Required The directory path to use		String

132.2.2. Query Parameters (38 parameters):

Name	Description	Default	Type
connectOnStartup (common)	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.	true	boolean
fileSystemType (common)	Set to LOCAL to not use HDFS but local java.io.File instead.	HDFS	HdfsFileSystemType
fileType (common)	The file type to use. For more details see Hadoop HDFS documentation about the various files types.	NORMAL_FILE	HdfsFileType
keyType (common)	The type for the key in case of sequence or map files.	NULL	WritableType
owner (common)	The file owner must match this owner for the consumer to pickup the file. Otherwise the file is skipped.		String
valueType (common)	The type for the key in case of sequence or map files	BYTES	WritableType
bridgeErrorHandler (consumer)	Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, 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 will be logged at WARN or ERROR level and ignored.	false	boolean
pattern (consumer)	The pattern used for scanning the directory	*	String
sendEmptyMessageWhenIdle (consumer)	If the polling consumer did not poll any files, you can enable this option to send an empty message (no body) instead.	false	boolean
exceptionHandler (consumer)	To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this options is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored.		ExceptionHandler
exchangePattern (consumer)	Sets the exchange pattern when the consumer creates an exchange.		ExchangePattern
pollStrategy (consumer)	A pluggable org.apache.camel.PollingConsumerPollingStrategy 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.		PollingConsumerPoll Strategy
append (producer)	Append to existing file. Notice that not all HDFS file systems support the append option.	false	boolean
overwrite (producer)	Whether to overwrite existing files with the same name	true	boolean
blockSize (advanced)	The size of the HDFS blocks	67108864	long
bufferSize (advanced)	The buffer size used by HDFS	4096	int
checkIdleInterval (advanced)	How often (time in millis) in to run the idle checker background task. This option is only in use if the splitter strategy is IDLE.	500	int
chunkSize (advanced)	When reading a normal file, this is split into chunks producing a message per chunk.	4096	int
compressionCodec (advanced)	The compression codec to use	DEFAULT	HdfsCompressionCodec
compressionType (advanced)	The compression type to use (is default not in use)	NONE	CompressionType
openedSuffix (advanced)	When a file is opened for reading/writing the file is renamed with this suffix to avoid to read it during the writing phase.	opened	String
readSuffix (advanced)	Once the file has been read is renamed with this suffix to avoid to read it again.	read	String
replication (advanced)	The HDFS replication factor	3	short
splitStrategy (advanced)	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		String
synchronous (advanced)	Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported).	false	boolean
backoffErrorThreshold (scheduler)	The number of subsequent error polls (failed due some error) that should happen before the backoffMultipler should kick-in.		int
backoffIdleThreshold (scheduler)	The number of subsequent idle polls that should happen before the backoffMultipler should kick-in.		int
backoffMultiplier (scheduler)	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.		int
delay (scheduler)	Milliseconds before the next poll. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	500	long
greedy (scheduler)	If greedy is enabled, then the ScheduledPollConsumer will run immediately again, if the previous run polled 1 or more messages.	false	boolean
initialDelay (scheduler)	Milliseconds before the first poll starts. You can also specify time values using units, such as 60s (60 seconds), 5m30s (5 minutes and 30 seconds), and 1h (1 hour).	1000	long
runLoggingLevel (scheduler)	The consumer logs a start/complete log line when it polls. This option allows you to configure the logging level for that.	TRACE	LoggingLevel
scheduledExecutorService (scheduler)	Allows for configuring a custom/shared thread pool to use for the consumer. By default each consumer has its own single threaded thread pool.		ScheduledExecutor Service
scheduler (scheduler)	To use a cron scheduler from either camel-spring or camel-quartz2 component	none	ScheduledPollConsumer Scheduler
schedulerProperties (scheduler)	To configure additional properties when using a custom scheduler or any of the Quartz2, Spring based scheduler.		Map
startScheduler (scheduler)	Whether the scheduler should be auto started.	true	boolean
timeUnit (scheduler)	Time unit for initialDelay and delay options.	MILLISECONDS	TimeUnit
useFixedDelay (scheduler)	Controls if fixed delay or fixed rate is used. See ScheduledExecutorService in JDK for details.	true	boolean

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

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

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:

hdfs2://localhost/tmp/simple-file?splitStrategy=IDLE:1000,BYTES:5

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.

132.4. Message Headers

The following headers are supported by this component:

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

132.5. Controlling to close file stream

When using the HDFS2 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.

132.6. Using this component in OSGi

There are some quirks when running this component in an OSGi environment related to the mechanism Hadoop 2.x uses to discover different org.apache.hadoop.fs.FileSystem implementations. Hadoop 2.x uses java.util.ServiceLoader which looks for /META-INF/services/org.apache.hadoop.fs.FileSystem files defining available filesystem types and implementations. These resources are not available when running inside OSGi.

As with camel-hdfs component, 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 (and e.g., hdfs-default.xml) in your bundle root.

132.6.1. Using this component with manually defined routes

There are two options:

Package /META-INF/services/org.apache.hadoop.fs.FileSystem resource with bundle that defines the routes. This resource should list all the required Hadoop 2.x filesystem implementations.
Provide boilerplate initialization code which populates internal, static cache inside org.apache.hadoop.fs.FileSystem class:

org.apache.hadoop.conf.Configuration conf = new org.apache.hadoop.conf.Configuration();
conf.setClass("fs.file.impl", org.apache.hadoop.fs.LocalFileSystem.class, FileSystem.class);
conf.setClass("fs.hdfs.impl", org.apache.hadoop.hdfs.DistributedFileSystem.class, FileSystem.class);
...
FileSystem.get("file:///", conf);
FileSystem.get("hdfs://localhost:9000/", conf);
...

132.6.2. Using this component with Blueprint container

Two options:

Package /META-INF/services/org.apache.hadoop.fs.FileSystem resource with bundle that contains blueprint definition.
Add the following to the blueprint definition file:

<bean id="hdfsOsgiHelper" class="org.apache.camel.component.hdfs2.HdfsOsgiHelper">
   <argument>
      <map>
         <entry key="file:///" value="org.apache.hadoop.fs.LocalFileSystem"  />
         <entry key="hdfs://localhost:9000/" value="org.apache.hadoop.hdfs.DistributedFileSystem" />
         ...
      </map>
   </argument>
</bean>

<bean id="hdfs2" class="org.apache.camel.component.hdfs2.HdfsComponent" depends-on="hdfsOsgiHelper" />

This way Hadoop 2.x will have correct mapping of URI schemes to filesystem implementations.

Chapter 133. HeadersMap

Available as of Camel 2.20

The camel-headersmap is a faster implementation of a case-insenstive map which can be plugged in and used by Camel at runtime to have slight faster performance in the Camel Message headers.

133.1. Auto detection from classpath

To use this implementation all you need to do is to add the camel-headersmap dependency to the classpath, and Camel should auto-detect this on startup and log as follows:

Detected and using custom HeadersMapFactory: org.apache.camel.component.headersmap.FastHeadersMapFactory@71e9ebae

For spring-boot there is a camel-headersmap-starter dependency you should use.

133.2. Manual enabling

If you use OSGi or the implementation is not added to the classpath, you need to enable this explict such .Title

CamelContext camel = ...

camel.setHeadersMapFactory(new FastHeadersMapFactory());

Or in XML DSL (spring or blueprint XML file) you can declare the factory as a <bean>

<bean id="fastMapFactory" class="org.apache.camel.component.headersmap.FastHeadersMapFactory"/>

and then Camel should detect the bean and use the factory, which is logged:

Chapter 134. Hessian DataFormat (deprecated)

Available as of Camel version 2.17

Hessian is Data Format for marshalling and unmarshalling messages using Caucho’s Hessian format.

If you want to use Hessian Data Format from Maven, add the following dependency to your pom.xml:

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

134.1. Options

The Hessian dataformat supports 4 options which are listed below.

Name	Default	Java Type	Description
whitelistEnabled	`true`	`Boolean`	Define if Whitelist feature is enabled or not
allowedUnmarshallObjects		`String`	Define the allowed objects to be unmarshalled
deniedUnmarshallObjects		`String`	Define the denied objects to be unmarshalled
contentTypeHeader	`false`	`Boolean`	Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSon etc.

134.2. Using the Hessian data format in Java DSL

    from("direct:in")
        .marshal().hessian();

134.3. Using the Hessian data format in Spring DSL

    <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
        <route>
            <from uri="direct:in"/>
            <marshal ref="hessian"/>
        </route>
    </camelContext>

Chapter 135. Hipchat Component

Available as of Camel version 2.15

The Hipchat component supports producing and consuming messages from/to Hipchat service.

Prerequisites

You must have a valid Hipchat user account and get a personal access token that you can use to produce/consume messages.

135.1. URI Format

hipchat://[host][:port]?options

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

135.2. URI Options

The Hipchat component has no options.

The Hipchat endpoint is configured using URI syntax:

hipchat:protocol:host:port

with the following path and query parameters:

135.2.1. Path Parameters (3 parameters):

Name	Description	Default	Type
protocol	Required The protocol for the hipchat server, such as http.		String
host	Required The host for the hipchat server, such as api.hipchat.com		String
port	The port for the hipchat server. Is by default 80.	80	Integer

135.2.2. Query Parameters (22 parameters):

Name	Description	Default	Type
authToken (common)	OAuth 2 auth token		String
consumeUsers (common)	Username(s) when consuming messages from the hiptchat server. Multiple user names can be separated by comma.		String
httpClient (common)	The CloseableHttpClient reference from registry to be used during API HTTP requests.	CloseableHttpClient default from HttpClient library	CloseableHttpClient
bridgeErrorHandler (consumer)

Configuration reference for Camel components

Chapter 1. Components Overview

1.1. Container types

1.2. Supported components

Chapter 2. ActiveMQ

ActiveMQ Component

URI format

Options

Camel on EAP deployment

Configuring the Connection Factory

Configuring the Connection Factory using Spring XML

Using connection pooling

Invoking MessageListener POJOs in a route

Using ActiveMQ Destination Options

Consuming Advisory Messages

Getting Component JAR

Chapter 3. AHC Component

3.1. URI format

3.2. AhcEndpoint Options

3.2.1. Path Parameters (1 parameters):

3.2.2. Query Parameters (13 parameters):

3.3. AhcComponent Options

3.4. Message Headers

3.5. Message Body

3.6. Response code

3.7. AhcOperationFailedException

3.8. Calling using GET or POST

3.9. Configuring URI to call

3.10. Configuring URI Parameters

3.11. How to set the http method to the HTTP producer

3.12. Configuring charset

3.12.1. URI Parameters from the endpoint URI

3.12.2. URI Parameters from the Message

3.12.3. Getting the Response Code

3.13. Configuring AsyncHttpClient

3.14. SSL Support (HTTPS)

3.15. See Also

Chapter 4. AHC Websocket Component

4.1. URI Format

4.2. AHC-WS Options

4.2.1. Path Parameters (1 parameters):

4.2.2. Query Parameters (18 parameters):

4.3. Writing and Reading Data over Websocket

4.4. Configuring URI to Write or Read Data

4.5. See Also

Chapter 5. AMQP Component

5.1. URI format

5.2. AMQP Options

5.2.1. Path Parameters (2 parameters):

5.2.2. Query Parameters (91 parameters):

5.3. Usage

5.4. Configuring AMQP component

5.5. Using topics

5.6. See Also

Chapter 6. APNS Component

6.1. URI format

6.2. Options

6.2.1. Path Parameters (1 parameters):

6.2.2. Query Parameters (20 parameters):

6.2.3. Component

6.2.3.1. SSL Setting

6.3. Exchange data format

6.4. Message Headers

6.5. ApnsServiceFactory builder callback

6.6. Samples

6.6.1. Camel Xml route

6.6.2. Camel Java route

6.7. See Also

Chapter 7. ASN.1 File DataFormat

7.1. ASN.1 Data Format Options

7.2. Unmarshal

7.3. Dependencies

Chapter 8. Asterisk Component

8.1. URI format

8.2. Options

8.2.1. Path Parameters (1 parameters):

8.2.2. Query Parameters (8 parameters):

8.3. Action

Chapter 9. Atmos Component