Component Appendix

There now follows the documentation on each Camel component.

AMQP

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

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

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

URI format

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

AMQP Options

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

Usage

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

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

Configuring AMQP component

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

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

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

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

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

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

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

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

Configuring Connection Factory

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

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

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

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

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

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

Using amqp inside Karaf

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

Example:

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

and the environment would be set.

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

Bean Component

The bean: component binds beans to Camel message exchanges.

URI format

bean:beanID[?options]

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

Options

confluenceTableSmall

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

Using

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

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

CamelContext camelContext = new DefaultCamelContext(context);

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

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

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

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

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

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

And the same route using Spring DSL:

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

Bean as endpoint

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

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

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

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

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

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

Java DSL bean syntax

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

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

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

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

Bean Binding

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

Endpoint See Also

• Class component
• Bean Binding
• Bean Integration

Direct Component

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

URI format

direct:someName[?options]

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

Options

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

Samples

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

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

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

And the sample using spring DSL:

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

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

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

• SEDA
• VM

Esper

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

URI format

esper:name[?options]

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

Pattern example:

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

EQL example:

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

Options

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

EsperMessage

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

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

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

Demo

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

• Esper Camel Demo

HTTP Component

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

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

URI Format

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

Examples

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

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

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

Set the HTTP request method to POST:

HttpEndpoint Options

Authentication and Proxy

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

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

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

HttpComponent Options

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

Message Headers

Message Body

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

Response Code

Camel will handle according to the HTTP response code:

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

• Response code is 400+, Camel regards it as an external server failure and will throw a HttpOperationFailedException with the information.

  throwExceptionOnFailure

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

HttpOperationFailedException

This exception contains the following information:

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

Calling Using GET or POST

The following algorithm is used to determine if either GET or POST HTTP method should be used:

1. Use method provided in header.
2. GET if query string is provided in header.
3. GET if endpoint is configured with a query string.
4. POST if there is data to send (body is not null).
5. GET otherwise.

How To Access The HttpServletRequest and HttpServletResponse

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

Using Client Timeout - SO_TIMEOUT

See the unit test in this link

More Examples

Configuring a Proxy

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

Using Proxy Settings Outside of the URI

Options on Endpoint will override options on the context.

Configuring charset

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

Sample with Scheduled Poll

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

Getting the Response Code

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

Using throwExceptionOnFailure=false To Obtain All Server Responses

In the route below we want to route a message that we enrich with data returned from a remote HTTP call. As we want all responses from the remote server, we set the throwExceptionOnFailure=false so we get any response in the AggregationStrategy. As the code is based on a unit test that simulates a HTTP status code 404, there is some assertion code etc.{snippet:id=e1|lang=java|url=camel/tags/camel-2.2.0/components/camel-jetty/src/test/java/org/apache/camel/component/jetty/JettySimplifiedHandle404Test.java}

Disabling Cookies

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

Advanced Usage

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

Setting MaxConnectionsPerHost

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

First, we define the http component in Spring XML. Yes, we use the same scheme name, http, because otherwise Camel will auto-discover and create the component with default settings. What we need is to overrule this so we can set our options. In the sample below we set the max connection to 5 instead of the default of 2.{snippet:id=e1|lang=xml|url=camel/tags/camel-2.2.0/tests/camel-itest/src/test/resources/org/apache/camel/itest/http/HttpMaxConnectionPerHostTest-context.xml}And then we can just use it as we normally do in our routes:{snippet:id=e2|lang=xml|url=camel/tags/camel-2.2.0/tests/camel-itest/src/test/resources/org/apache/camel/itest/http/HttpMaxConnectionPerHostTest-context.xml}

Using Pre-Emptive Authentication

If an HTTP server should fail to respond correctly with an expected 401 Authorization Required response for a failed authentication attempt a client can instead use preemptive authentication by specifying the URI option: httpClient.authenticationPreemptive=true.

Accepting Self-Signed Certificates From Remote Server

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

Setting up SSL for HTTP Client

Using the JSSE Configuration Utility

From Camel 2.8: the HTTP4 component supports SSL/TLS configuration through the Camel JSSE Configuration Utility.  This utility greatly decreases the amount of component specific code you need to write and is configurable at the endpoint and component levels.  The following examples demonstrate how to use the utility with the HTTP4 component.

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

Configuring Apache HTTP Client Directly

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

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

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

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

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

Endpoint See Also

• Jetty

iBATIS

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

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

URI format

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

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

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

Options

Message Headers

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

Message Body

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

Samples

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

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

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

Using StatementType for better control of IBatis

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

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

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

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

Scheduled polling example

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

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

And the iBatis SQL map file used:

Using onConsume

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

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

And the statements in the sqlmap file:

Endpoint See Also

• MyBatis

IRC Component

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

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

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

URI format

irc:nick@host[:port]/#room[?options]
irc:nick@host[:port]?channels=#channel1,#channel2,#channel3[?options]

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

Options

SSL Support

Using the JSSE Configuration Utility

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

Programmatic configuration of the endpoint

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

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

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

Registry registry = ...
registry.bind("sslContextParameters", scp);

...

from(...)
    .to("ircs://camel-prd-user@server:6669/#camel-test?nickname=camel-prd&password=password&sslContextParameters=#sslContextParameters");

Spring DSL based configuration of endpoint

...
  <camel:sslContextParameters
      id="sslContextParameters">
    <camel:trustManagers>
      <camel:keyStore
          resource="/users/home/server/truststore.jks"
          password="keystorePassword"/>
    </camel:keyManagers>
  </camel:sslContextParameters>...
...
  <to uri="ircs://camel-prd-user@server:6669/#camel-test?nickname=camel-prd&password=password&sslContextParameters=#sslContextParameters"/>...

Using the legacy basic configuration options

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

ircs:host[:port]/#room?username=user&password=pass

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

ircs:host[:port]/#room?username=user&password=pass&trustManager=#referenceToMyTrustManagerBean

Using keys

Available as of Camel 2.2

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

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

irc:nick@irc.server.org?channels=#chan1,#chan2,#chan3&keys=chan1Key,,chan3key

JBI Component

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

The following code:

from("jbi:endpoint:http://foo.bar.org/MyService/MyEndpoint")

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

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

to("jbi:endpoint:http://foo.bar.org/MyService/MyEndpoint")

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

URI format

jbi:service:serviceNamespace[sep]serviceName[?options]
jbi:endpoint:serviceNamespace[sep]serviceName[sep]endpointName[?options]
jbi:name:endpointName[?options]

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

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

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

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

{http://activemq.apache.org/camel/schema/jbi}endpoint

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

Examples

jbi:service:http://foo.bar.org/MyService
jbi:endpoint:urn:foo:bar:MyService:MyEndpoint
jbi:endpoint:http://foo.bar.org/MyService/MyEndpoint
jbi:name:cheese

URI options

Examples

jbi:service:http://foo.bar.org/MyService?mep=in-out       (override the MEP, use InOut JBI MessageExchanges)
jbi:endpoint:urn:foo:bar:MyService:MyEndpoint?mep=in      (override the MEP, use InOnly JBI MessageExchanges)  
jbi:endpoint:urn:foo:bar:MyService:MyEndpoint?operation={http://www.mycompany.org}AddNumbers 
 (overide the operation for the JBI Exchange to {http://www.mycompany.org}AddNumbers)

Using Stream bodies

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

from("jbi:endpoint:http://foo.bar.org/MyService/MyEndpoint").streamCaching().to("xslt:transform.xsl", "bean:doSomething");

The stream caching is default enabled, so it is not necessary to set the streamCaching() option.
We store big input streams (by default, over 64K) in a temp file using CachedOutputStream. When you close the input stream, the temp file will be deleted.

Creating a JBI Service Unit

If you have some Camel routes that you want to deploy inside JBI as a Service Unit, you can use the JBI Service Unit Archetype to create a new Maven project for the Service Unit.

If you have an existing Maven project that you need to convert into a JBI Service Unit, you may want to consult ServiceMix Maven JBI Plugins for further help. The key steps are as follows:

• Create a Spring XML file at src/main/resources/camel-context.xml to bootstrap your routes inside the JBI Service Unit.
• Change the POM file's packaging to jbi-service-unit.

Your pom.xml should look something like this to enable the jbi-service-unit packaging:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <groupId>myGroupId</groupId>
  <artifactId>myArtifactId</artifactId>
  <packaging>jbi-service-unit</packaging>
  <version>1.0-SNAPSHOT</version>

  <name>A Camel based JBI Service Unit</name>

  <url>http://www.myorganization.org</url>

  <properties>
    <camel-version>x.x.x</camel-version>
    <servicemix-version>3.3</servicemix-version>
  </properties>

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

    <dependency>
      <groupId>org.apache.servicemix</groupId>
      <artifactId>servicemix-core</artifactId>
      <version>${servicemix-version}</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>

  <build>
    <defaultGoal>install</defaultGoal>

    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.5</source>
          <target>1.5</target>
        </configuration>
      </plugin>

      <!-- creates the JBI deployment unit -->
      <plugin>
        <groupId>org.apache.servicemix.tooling</groupId>
        <artifactId>jbi-maven-plugin</artifactId>
        <version>${servicemix-version}</version>
        <extensions>true</extensions>
      </plugin>
    </plugins>
  </build>
</project>

• ServiceMix Camel module
• Using Camel with ServiceMix
• Cookbook on using Camel with ServiceMix

JCR Component

The jcr component allows you to add/read nodes to/from a JCR compliant content repository (for example, Apache Jackrabbit) with its producer, or register an EventListener with the consumer.

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

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

URI format

jcr://user:password@repository/path/to/node

Usage

The repository element of the URI is used to look up the JCR Repository object in the Camel context registry.

Producer

When a message is sent to a JCR producer endpoint:

• If the operation is CamelJcrInsert: A new node is created in the content repository, all the message headers of the IN message are transformed to javax.jcr.Value instances and added to the new node and the node's UUID is returned in the OUT message.
• If the operation is CamelJcrGetById: A new node is retrieved from the repository using the message body as node identifier.

Consumer

The consumer will connect to JCR periodically and return a List<javax.jcr.observation.Event> in the message body.

Example

The snippet below creates a node named node under the /home/test node in the content repository. One additional property is added to the node as well: my.contents.property which will contain the body of the message being sent.

from("direct:a").setHeader(JcrConstants.JCR_NODE_NAME, constant("node"))
    .setHeader("my.contents.property", body())
    .to("jcr://user:pass@repository/home/test");

The following code will register an EventListener under the path import-application/inbox for Event.NODE_ADDED and Event.NODE_REMOVED events (event types 1 and 2, both masked as 3) and listening deep for all the children.

<route>
    <from uri="jcr://user:pass@repository/import-application/inbox?eventTypes=3&deep=true" />
    <to uri="direct:execute-import-application" />
</route>

JDBC Component

The jdbc component enables you to access databases through JDBC, where SQL queries (SELECT) and operations (INSERT, UPDATE, etc) are sent in the message body. This component uses the standard JDBC API, unlike the SQL Component component, which uses spring-jdbc.

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

URI format

This component only supports producer endpoints.

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

Options

Result

By default the result is returned in the OUT body as an ArrayList<HashMap<String, Object>>. The List object contains the list of rows and the Map objects contain each row with the String key as the column name. You can use the option outputType to control the result.

Note: This component fetches ResultSetMetaData to be able to return the column name as the key in the Map.

Message Headers

Generated keys

Available as of Camel 2.10

If you insert data using SQL INSERT, then the RDBMS may support auto generated keys. You can instruct the JDBC producer to return the generated keys in headers.
To do that set the header CamelRetrieveGeneratedKeys=true. Then the generated keys will be provided as headers with the keys listed in the table above.

You can see more details in this unit test.

Using named parameters

Available as of Camel 2.12

In the given route below, we want to get all the projects from the projects table. Notice the SQL query has 2 named parameters, :?lic and :?min.
Camel will then lookup these parameters from the message headers. Notice in the example above we set two headers with constant value
for the named parameters:

You can also store the header values in a java.util.Map and store the map on the headers with the key CamelJdbcParameters.

Samples

In the following example, we fetch the rows from the customer table.

First we register our datasource in the Camel registry as testdb:{snippet:id=register|lang=java|url=camel/trunk/components/camel-jdbc/src/test/java/org/apache/camel/component/jdbc/AbstractJdbcTestSupport.java}Then we configure a route that routes to the JDBC component, so the SQL will be executed. Note how we refer to the testdb datasource that was bound in the previous step:{snippet:id=route|lang=java|url=camel/trunk/components/camel-jdbc/src/test/java/org/apache/camel/component/jdbc/JdbcRouteTest.java}Or you can create a DataSource in Spring like this:{snippet:id=example|lang=java|url=camel/trunk/components/camel-jdbc/src/test/resources/org/apache/camel/component/jdbc/camelContext.xml}We create an endpoint, add the SQL query to the body of the IN message, and then send the exchange. The result of the query is returned in the OUT body:{snippet:id=invoke|lang=java|url=camel/trunk/components/camel-jdbc/src/test/java/org/apache/camel/component/jdbc/JdbcRouteTest.java}If you want to work on the rows one by one instead of the entire ResultSet at once you need to use the Splitter EIP such as:

In Camel 2.13.x or older{snippet:id=e1|lang=java|url=camel/trunk/components/camel-jdbc/src/test/java/org/apache/camel/component/jdbc/JdbcRouteSplitTest.java}In Camel 2.14.x or newer

Sample - Polling the database every minute

If we want to poll a database using the JDBC component, we need to combine it with a polling scheduler such as the Timer or Quartz etc. In the following example, we retrieve data from the database every 60 seconds:

Sample - Move Data Between Data Sources

A common use case is to query for data, process it and move it to another data source (ETL operations). In the following example, we retrieve new customer records from the source table every hour, filter/transform them and move them to a destination table:

Endpoint See Also

• SQL

Jetty Component

The jetty component provides HTTP-based endpoints for consuming and producing HTTP requests. That is, the Jetty component behaves as a simple Web server. Jetty can also be used as an HTTP client which mean you can also use it with Camel as a producer.

Maven users should add the following dependency to their pom.xml to use this component:

URI Format

Query options should be appended to the URI using the following format: ?option=value&option=value&...

Options

Message Headers

Camel uses the same message headers as the HTTP component. From Camel 2.2, it also uses (Exchange.HTTP_CHUNKED, CamelHttpChunked) header to toggle chunked encoding on the camel-jetty consumer. Camel also populates all request.parameter and request.headers. For example, given a client request with the URL, http://myserver/myserver?orderid=123, the exchange will contain a header named orderid with the value 123.

From Camel 2.2.0: you can get the request.parameter from the message header not only from GET HTTP Method, but also other HTTP method.

Usage

The Jetty component supports both consumer and producer endpoints. Another option for producing to other HTTP endpoints, is to use the HTTP Component

Component Options

The JettyHttpComponent provides the following options:

Producer Example

The following is a basic example of how to send an HTTP request to an existing HTTP endpoint.

Java DSL:

XML DSL:

Consumer Example

In this sample we define a route that exposes a HTTP service at http://localhost:8080/myapp/myservice:{snippet:id=e1|lang=java|url=camel/trunk/components/camel-jetty9/src/test/java/org/apache/camel/component/jetty/JettyRouteTest.java}

Our business logic is implemented in the MyBookService class, which accesses the HTTP request contents and then returns a response.
Note: The assert call appears in this example, because the code is part of an unit test.{snippet:id=e2|lang=java|url=camel/trunk/components/camel-jetty9/src/test/java/org/apache/camel/component/jetty/JettyRouteTest.java}The following sample shows a content-based route that routes all requests containing the URI parameter, one, to the endpoint, mock:one, and all others to mock:other.{snippet:id=e1|lang=java|url=camel/trunk/components/camel-jetty9/src/test/java/org/apache/camel/component/jetty/JettyContentBasedRouteTest.java}If a client sends an HTTP request, http://serverUri?one=hello, the Jetty component will copy the HTTP request parameter, one to the exchange's in.header. We can then use the simple language to route exchanges that contain this header to a specific endpoint and all others to another. If we used a language more powerful than Simple, e.g., EL or OGNL, then we can also test for the parameter value and route based on the header value as well.

Session Support

The session support option, sessionSupport, can be used to enable a HttpSession object and access the session object while processing the exchange.

For example, the following route enables sessions:

The myCode Processor can be instantiated by a Spring bean element:

Where the processor implementation can access the HttpSession as follows:

SSL Support (HTTPS)

Using the JSSE Configuration Utility

From Camel 2.8: the camel-jetty component supports SSL/TLS configuration through the Camel JSSE Configuration Utility.  This utility greatly decreases the amount of component specific code you need to write and is configurable at the endpoint and component levels.  The following examples demonstrate how to use the utility with the Jetty component.

Programmatic configuration of the component

Spring DSL based configuration of endpoint

Configuring Jetty Directly

Jetty provides SSL support out of the box. To enable Jetty to run in SSL mode, simply format the URI using the https:// prefix.

Example:

Jetty also needs to know where to load your keystore from and what passwords to use in order to load the correct SSL certificate. Set the following JVM System Properties:

Before Camel 2.3:

From Camel 2.3:

For details of how to configure SSL on a Jetty endpoint, read the following Jetty documentation. Some SSL properties aren't exposed directly by Camel. However, Camel does expose the underlying SslSocketConnector, which will allow you to set properties like needClientAuth for mutual authentication requiring a client certificate or wantClientAuth for mutual authentication where a client doesn't need a certificate but can have one.

There's a slight difference between the various Camel versions:

Up to Camel 2.2

Camel 2.3, 2.4

From Camel 2.5: we switch to use SslSelectChannelConnector *

The value you use as keys in the above map is the port you configure Jetty to listen on.

Configuring General SSL Properties

From Camel 2.5: instead of a per port number specific SSL socket connector (as shown above) you can now configure general properties which applies for all SSL socket connectors (which is not explicit configured as above with the port number as entry).

How to Obtain A Reference to the X509Certificate

Jetty stores a reference to the certificate in the HttpServletRequest which you can access from code as follows:

Configuring General HTTP Properties

From Camel 2.5: instead of a per port number specific HTTP socket connector (as shown above) you can now configure general properties which applies for all HTTP socket connectors (which is not explicit configured as above with the port number as entry).

How to Get the Value of The X-Forwarded-For HTTP Header Using HttpServletRequest.getRemoteAddr()

If the HTTP requests are handled by an Apache server and forwarded to Jetty with mod_proxy, the original client IP address is in the X-Forwarded-For header and the HttpServletRequest.getRemoteAddr() will return the address of the Apache proxy.

Jetty has a forwarded property which takes the value from X-Forwarded-For and places it in the HttpServletRequest remoteAddr property.  This property is not available directly through the endpoint configuration but it can be easily added using the socketConnectors property:

This is particularly useful when an existing Apache server handles TLS connections for a domain and proxies them to application servers internally.

Default Behavior for Returning HTTP Status Codes

The default behavior of HTTP status codes is defined by the org.apache.camel.component.http.DefaultHttpBinding class, which handles how a response is written and also sets the HTTP status code. If the exchange was processed successfully, the 200 HTTP status code is returned. If the exchange failed with an exception, the 500 HTTP status code is returned, and the stacktrace is returned in the body. If you want to specify which HTTP status code to return, set the code in the Exchange.HTTP_RESPONSE_CODE header of the OUT message.

Customizing HttpBinding

By default, Camel uses the org.apache.camel.component.http.DefaultHttpBinding to handle how a response is written. If you like, you can customize this behavior either by implementing your own HttpBinding class or by extending DefaultHttpBinding and overriding the appropriate methods.

The following example shows how to customize the DefaultHttpBinding in order to change how exceptions are returned:{snippet:id=e1|lang=java|url=camel/trunk/components/camel-jetty9/src/test/java/org/apache/camel/component/jetty/HttpBindingRefTest.java}We can then create an instance of our binding and register it in the Spring registry as follows:

And then we can reference this binding when we define the route:

Jetty Handlers and Security Configuration

You can configure a list of Jetty handlers on the endpoint, which can be useful for enabling advanced Jetty security features. These handlers are configured in Spring XML as follows:

From Camel 2.3: you can configure a list of Jetty handlers as follows:

You can then define the endpoint as:

If you need more handlers, set the handlers option equal to a comma-separated list of bean IDs.

How to Customize the Response on an HTTP 500 Server Error

You may want to return a custom reply message when something goes wrong, instead of the default reply message Camel Jetty replies with. You could use a custom HttpBinding to be in control of the message mapping, but often it may be easier to use Camel's Exception Clause to construct the custom reply message.

Example: return the message: Dude something went wrong for the HTTP error code 500:{snippet:id=e1|lang=java|url=camel/trunk/components/camel-jetty9/src/test/java/org/apache/camel/component/jetty/JettyOnExceptionHandledTest.java}

Multi-Part Form Support

From Camel 2.3.0: camel-jetty support to multi-part form post out of box. The submitted form-data are mapped into the message header. camel-jetty creates an attachment for each uploaded file. The file name is mapped to the name of the attachment. The content type is set as the content type of the attachment file name. You can find the example here.{snippet:id=e1|lang=java|url=camel/components/camel-jetty9/src/test/java/org/apache/camel/component/jetty/MultiPartFormTest.java|title=Note: getName() functions as shown below in versions 2.5 and higher. In earlier versions you receive the temporary file name for the attachment instead}

Jetty JMX Support

From Camel 2.3.0: camel-jetty supports the enabling of Jetty's JMX capabilities at the component and endpoint level with the endpoint configuration taking priority.

Note: JMX must be enabled within the Camel context in order to enable JMX support in this component as the component provides Jetty with a reference to the MBeanServer registered with the Camel context.

As the camel-jetty component caches and reuses Jetty resources for a given protocol/host/port pairing, this configuration option will only be evaluated during the creation of the first endpoint to use a protocol/host/port pairing.

Example: given two routes created from the following XML fragments, JMX support would remain enabled for all endpoints listening on: https://0.0.0.0.

The camel-jetty component also provides for direct configuration of the Jetty MBeanContainer. Jetty creates MBean names dynamically. If you are running another instance of Jetty outside of the Camel context and sharing the same MBeanContainer between the instances, you can provide both instances with a reference to the same MBeanContainer in order to avoid name collisions when registering Jetty MBeans.

Endpoint See Also

• HTTP

JPA Component

The jpa component enables you to store and retrieve Java objects from persistent storage using EJB 3's Java Persistence Architecture (JPA), which is a standard interface layer that wraps Object/Relational Mapping (ORM) products such as OpenJPA, Hibernate, TopLink, and so on.

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

Sending to the endpoint

You can store a Java entity bean in a database by sending it to a JPA producer endpoint. The body of the In message is assumed to be an entity bean (that is, a POJO with an @Entity annotation on it) or a collection or array of entity beans.

If the body is a List of entities, make sure to use entityType=java.util.ArrayList as a configuration passed to the producer endpoint.

If the body does not contain one of the previous listed types, put a Message Translator in front of the endpoint to perform the necessary conversion first.

From Camel 2.19 onwards you can use query, namedQuery and nativeQuery option for the producer as well to retrieve a set of entities or execute bulk update/delete.

Consuming from the endpoint

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

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

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

From Camel 2.13 onwards you can use @PreConsumed which will be invoked on your entity bean before it has been processed (before routing).

If you are consuming a lot (100K+) of rows and experience OutOfMemory problems you should set the maximumResults to sensible value.

Note: Since Camel 2.18, JPA now includes a JpaPollingConsumer implementation that better supports Content Enricher using pollEnrich() to do an on-demand poll that returns either none, one or a list of entities as the result.

URI format

For sending to the endpoint, the entityClassName is optional. If specified, it helps the Type Converter to ensure the body is of the correct type.

For consuming, the entityClassName is mandatory.

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

Options

Message Headers

Camel adds the following message headers to the exchange:

Configuring EntityManagerFactory

Its strongly advised to configure the JPA component to use a specific EntityManagerFactory instance. If failed to do so each JpaEndpoint will auto create their own instance of EntityManagerFactory which most often is not what you want.

For example, you can instantiate a JPA component that references the myEMFactory entity manager factory, as follows:

In Camel 2.3 the JpaComponent will auto lookup the EntityManagerFactory from the Registry which means you do not need to configure this on the JpaComponent as shown above. You only need to do so if there is ambiguity, in which case Camel will log a WARN.

Configuring TransactionManager

Since Camel 2.3 the JpaComponent will auto lookup the TransactionManager from the Registry. If Camel won't find any TransactionManager instance registered, it will also look up for the TransactionTemplate and try to extract TransactionManager from it.

If none TransactionTemplate is available in the registry, JpaEndpoint will auto create their own instance of TransactionManager which most often is not what you want.

If more than single instance of the TransactionManager is found, Camel will log a WARN. In such cases you might want to instantiate and explicitly configure a JPA component that references the myTransactionManager transaction manager, as follows:

Using a consumer with a named query

For consuming only selected entities, you can use the consumer.namedQuery URI query option. First, you have to define the named query in the JPA Entity class:

After that you can define a consumer uri like this one:

Using a consumer with a query

For consuming only selected entities, you can use the consumer.query URI query option. You only have to define the query option:

Using a consumer with a native query

For consuming only selected entities, you can use the consumer.nativeQuery URI query option. You only have to define the native query option:

If you use the native query option, you will receive an object array in the message body.

Using a producer with a named query

For retrieving selected entities or execute bulk update/delete, you can use the namedQuery URI query option. First, you have to define the named query in the JPA Entity class:

After that you can define a producer uri like this one:

Using a producer with a query

For retrieving selected entities or execute bulk update/delete, you can use the query URI query option. You only have to define the query option:

Using a producer with a native query

For retrieving selected entities or execute bulk update/delete, you can use the nativeQuery URI query option. You only have to define the native query option:

If you use the native query option without specifying resultClass, you will receive an object array in the message body.

Example

See Tracer Example for an example using JPA to store traced messages into a database.

Using the JPA based idempotent repository

In this section we will use the JPA based idempotent repository.

First we need to setup a persistence-unit in the persistence.xml file:{snippet:id=e1|lang=xml|url=camel/trunk/components/camel-jpa/src/test/resources/META-INF/persistence.xml}Second we have to setup a org.springframework.orm.jpa.JpaTemplate which is used by the org.apache.camel.processor.idempotent.jpa.JpaMessageIdRepository:{snippet:id=e1|lang=xml|url=camel/trunk/components/camel-jpa/src/test/resources/org/apache/camel/processor/jpa/spring.xml}Afterwards we can configure our org.apache.camel.processor.idempotent.jpa.JpaMessageIdRepository:{snippet:id=jpaStore|lang=xml|url=camel/trunk/components/camel-jpa/src/test/resources/org/apache/camel/processor/jpa/fileConsumerJpaIdempotentTest-config.xml}And finally we can create our JPA idempotent repository in the spring XML file as well:

Endpoint See Also

• Tracer Example

List Component

deprecated: is renamed to the Browse component in Camel 2.0

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

URI format

list:someName

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

Sample

In the route below we have the list component to be able to browse the Exchanges that is passed through:

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

Then we will be able to inspect the received exchanges from java code:

    private CamelContext context;

    public void inspectRecievedOrders() {
        BrowsableEndpoint browse = context.getEndpoint("list: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();
            ...
        }
   }

• Browse

Log Component

The log: component logs message exchanges to the underlying logging mechanism.

URI format

log:loggingCategory[?options]

Where loggingCategory is the name of the logging category to use. You can append query options to the URI in the following format, ?option=value&option=value&...

For example, a log endpoint typically specifies the logging level using the level option, as follows:

log:org.apache.camel.example?level=DEBUG

The default logger logs every exchange (regular logging). But Camel also ships with the Throughput logger, which is used whenever the groupSize option is specified.

Options

Formatting

The log formats the execution of exchanges to log lines. 

By default, the log uses LogFormatter to format the log output, where LogFormatter has the following options:

camelContext.getProperties().put(Exchange.LOG_DEBUG_BODY_STREAMS, true);

Regular Logger Example

In the route below we log the incoming orders at DEBUG level before the order is processed:

from("activemq:orders")
  .to("log:com.mycompany.order?level=DEBUG")
  .to("bean:processOrder");

Or using Spring XML:

  <route>
    <from uri="activemq:orders"/>
    <to uri="log:com.mycompany.order?level=DEBUG"/>
    <to uri="bean:processOrder"/>
  </route> 

Regular Logger with Formatter

In the route below we log the incoming orders at INFO level before the order is processed.

from("activemq:orders")
  .to("log:com.mycompany.order?showAll=true&multiline=true")
  .to("bean:processOrder");

Throughput Logger With groupSize

In the route below we log the throughput of the incoming orders at DEBUG level grouped by 10 messages.

from("activemq:orders")
  .to("log:com.mycompany.order?level=DEBUG&groupSize=10")
  .to("bean:processOrder");

Throughput Logger With groupInterval

This route will result in message stats logged every 10s, with an initial 60s delay and stats should be displayed even if there isn't any message traffic.

from("activemq:orders")
  .to("log:com.mycompany.order?level=DEBUG&groupInterval=10000&groupDelay=60000&groupActiveOnly=false")
  .to("bean:processOrder");

The following will be logged:

"Received: 1000 new messages, with total 2000 so far. Last group took: 10000 millis which is: 100 messages per second. average: 100"

Full Customization of the Logged Output

Available as of Camel 2.11

With the options outlined in the #Formatting section, you can control much of the output of the logger. However, log lines will always follow this structure:

Exchange[Id:ID-machine-local-50656-1234567901234-1-2, ExchangePattern:InOut, 
Properties:{CamelToEndpoint=log://org.apache.camel.component.log.TEST?showAll=true, 
CamelCreatedTimestamp=Thu Mar 28 00:00:00 WET 2013}, 
Headers:{breadcrumbId=ID-machine-local-50656-1234567901234-1-1}, BodyType:String, Body:Hello World, Out: null]

This format is unsuitable in some cases, perhaps because you need to:

• Filter the headers and properties that are printed, to strike a balance between insight and verbosity.
• Adjust the log message to whatever you deem most readable.
• Tailor log messages for digestion by log mining systems, e.g. Splunk.
• Print specific body types differently.
• Etc.

Whenever you require absolute customization, you can create a class that implements the ExchangeFormatter interface. Within the format(Exchange) method you have access to the full Exchange, so you can select and extract the precise information you need, format it in a custom manner and return it. The return value will become the final log message.

You can have the Log component pick up your custom ExchangeFormatter in one of two ways:

Explicitly instantiating the LogComponent in your Registry

<bean name="log" class="org.apache.camel.component.log.LogComponent">
   <property name="exchangeFormatter" ref="myCustomFormatter"/>
</bean>

Convention Over Configuration

Simply by registering a bean with the name logFormatter; the Log Component is intelligent enough to pick it up automatically.

<bean name="logFormatter" class="com.xyz.MyCustomExchangeFormatter"/>

From Camel 2.11.2/2.12: when using a custom log formatter, you can specify parameters in the log URI, which gets configured on the custom log formatter. Though when you do that you should define the logFormatter as prototype scoped so its not shared if you have different parameters.

Example:

<bean name="logFormatter" class="com.xyz.MyCustomExchangeFormatter" scope="prototype"/>

And then we can have Camel routes using the log URI with different options:

<to uri="log:foo?param1=foo&amp;param2=100"/>
<!-- ... -->
<to uri="log:bar?param1=bar&amp;param2=200"/>

Using Log Component in OSGi

Improvements from Camel 2.12.4/2.13.1

When using Log component inside OSGi (e.g., in Karaf), the underlying logging mechanisms are provided by PAX logging. It searches for a bundle which invokes org.slf4j.LoggerFactory.getLogger() method and associates the bundle with the logger instance. Without specifying custom org.sfl4j.Logger instance, the logger created by Log component is associated with camel-core bundle.

In some scenarios it is required that the bundle associated with logger should be the bundle which contains route definition. To do this, either register a single instance of org.slf4j.Logger in the Registry or reference it using logger URI parameter.

• Tracer
• How do I use log4j
• How do I use Java 1.4 logging
• LogEIP for using log directly in the DSL for human logs.

Mail Component

The mail component provides access to Email via Spring's Mail support and the underlying JavaMail system.

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

URI format

Mail endpoints can have one of the following URI formats (for the protocols, SMTP, POP3, or IMAP, respectively):

The mail component also supports secure variants of these protocols (layered over SSL). You can enable the secure protocols by adding s to the scheme:

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

Sample endpoints

Typically, you specify a URI with login credentials as follows (taking SMTP as an example):

Alternatively, it is possible to specify both the user name and the password as query options:

For example:

DefaultPortsDefault ports

Default port numbers are supported. If the port number is omitted, Camel determines the port number to use based on the protocol.

Options

dummyTrustManager

SSL support

The underlying mail framework is responsible for providing SSL support.  You may either configure SSL/TLS support by completely specifying the necessary Java Mail API configuration options, or you may provide a configured SSLContextParameters through the component or endpoint configuration.

Using the JSSE Configuration Utility

As of Camel 2.10, the mail 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 mail component.

Programmatic configuration of the endpoint

Spring DSL based configuration of endpoint

Configuring JavaMail Directly

Camel uses SUN JavaMail, which only trusts certificates issued by well known Certificate Authorities (the default JVM trust configuration). If you issue your own certificates, you have to import the CA certificates into the JVM's Java trust/key store files, override the default JVM trust/key store files (see SSLNOTES.txt in JavaMail for details).

Mail Message Content

Camel uses the message exchange's IN body as the MimeMessage text content. The body is converted to String.class.

Camel copies all of the exchange's IN headers to the MimeMessage headers. You may wish to read How to avoid sending some or all message headers to prevent inadvertent data "leaks" from your application.

The subject of the MimeMessage can be configured using a header property on the IN message. The code below demonstrates this:{snippet:id=e1|lang=java|url=camel/trunk/components/camel-mail/src/test/java/org/apache/camel/component/mail/MailSubjectTest.java}The same applies for other MimeMessage headers such as recipients, so you can use a header property as To:{snippet:id=e1|lang=java|url=camel/trunk/components/camel-mail/src/test/java/org/apache/camel/component/mail/MailUsingHeadersTest.java}Since Camel 2.11 When using the MailProducer the send the mail to server, you should be able to get the message id of the MimeMessage with the key CamelMailMessageId from the Camel message header.

Headers take precedence over pre-configured recipients

The recipients specified in the message headers always take precedence over recipients pre-configured in the endpoint URI. The idea is that if you provide any recipients in the message headers, that is what you get. The recipients pre-configured in the endpoint URI are treated as a fallback.

In the sample code below, the email message is sent to davsclaus@apache.org, because it takes precedence over the pre-configured recipient, info@mycompany.com. Any cc and bcc settings in the endpoint URI are also ignored and those recipients will not receive any mail. The choice between headers and pre-configured settings is all or nothing: the mail component either takes the recipients exclusively from the headers or exclusively from the pre-configured settings. It is not possible to mix and match headers and pre-configured settings.

Multiple recipients for easier configuration

It is possible to set multiple recipients using a comma-separated or a semicolon-separated list. This applies both to header settings and to settings in an endpoint URI. For example:

The preceding example uses a semicolon, ;, as the separator character.

Setting sender name and email

You can specify recipients in the format, name <email>, to include both the name and the email address of the recipient.

For example, you define the following headers on the a Message:

JavaMail API (ex SUN JavaMail)

JavaMail API is used under the hood for consuming and producing mails.
We encourage end-users to consult these references when using either POP3 or IMAP protocol. Note particularly that POP3 has a much more limited set of features than IMAP.

• JavaMail POP3 API
• JavaMail IMAP API
• And generally about the MAIL Flags

Samples

We start with a simple route that sends the messages received from a JMS queue as emails. The email account is the admin account on mymailserver.com.

In the next sample, we poll a mailbox for new emails once every minute. Notice that we use the special consumer option for setting the poll interval, consumer.delay, as 60000 milliseconds = 60 seconds.

In this sample we want to send a mail to multiple recipients:{snippet:id=e1|lang=java|url=camel/trunk/components/camel-mail/src/test/java/org/apache/camel/component/mail/MailRecipientsTest.java}

Sending mail with attachment sample

The mail component supports attachments. In the sample below, we send a mail message containing a plain text message with a logo file attachment.{snippet:id=e1|lang=java|url=camel/trunk/components/camel-mail/src/test/java/org/apache/camel/component/mail/MailAttachmentTest.java}

SSL sample

In this sample, we want to poll our Google mail inbox for mails. To download mail onto a local mail client, Google mail requires you to enable and configure SSL. This is done by logging into your Google mail account and changing your settings to allow IMAP access. Google have extensive documentation on how to do this.

The preceding route polls the Google mail inbox for new mails once every minute and logs the received messages to the newmail logger category.
Running the sample with DEBUG logging enabled, we can monitor the progress in the logs:

Consuming mails with attachment sample

In this sample we poll a mailbox and store all attachments from the mails as files. First, we define a route to poll the mailbox. As this sample is based on google mail, it uses the same route as shown in the SSL sample:

Instead of logging the mail we use a processor where we can process the mail from java code:

As you can see the API to handle attachments is a bit clunky but it's there so you can get the javax.activation.DataHandler so you can handle the attachments using standard API.

How to split a mail message with attachments

In this example we consume mail messages which may have a number of attachments. What we want to do is to use the Splitter EIP per individual attachment, to process the attachments separately. For example if the mail message has 5 attachments, we want the Splitter to process five messages, each having a single attachment. To do this we need to provide a custom Expression to the Splitter where we provide a List<Message> that contains the five messages with the single attachment.

The code is provided out of the box in Camel 2.10 onwards in the camel-mail component. The code is in the class: org.apache.camel.component.mail.SplitAttachmentsExpression, which you can find the source code here

In the Camel route you then need to use this Expression in the route as shown below:{snippet:id=e1|lang=java|url=camel/trunk/components/camel-mail/src/test/java/org/apache/camel/component/mail/MailSplitAttachmentsTest.java}If you use XML DSL then you need to declare a method call expression in the Splitter as shown below

From Camel 2.16 onwards you can also split the attachments as byte[] to be stored as the message body. This is done by creating the expression with boolean true

And then use the expression with the splitter eip.

Using custom SearchTerm

Available as of Camel 2.11

You can configure a searchTerm on the MailEndpoint which allows you to filter out unwanted mails.

For example to filter mails to contain Camel in either Subject or Text you can do as follows:

Notice we use the "searchTerm.subjectOrBody" as parameter key to indicate that we want to search on mail subject or body, to contain the word "Camel".
The class org.apache.camel.component.mail.SimpleSearchTerm has a number of options you can configure:

Or to get the new unseen emails going 24 hours back in time you can do. Notice the "now-24h" syntax. See the table below for more details.

You can have multiple searchTerm in the endpoint uri configuration. They would then be combined together using AND operator, eg so both conditions must match. For example to get the last unseen emails going back 24 hours which has Camel in the mail subject you can do:

The SimpleSearchTerm is designed to be easily configurable from a POJO, so you can also configure it using a <bean> style in XML

You can then refer to this bean, using #beanId in your Camel route as shown:

In Java there is a builder class to build compound SearchTerm}}s using the {{org.apache.camel.component.mail.SearchTermBuilder class.
This allows you to build complex terms such as:

Endpoint See Also

MINA Component

Deprecated

The mina: component is a transport for working with Apache MINA

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

URI format

You can specify a codec in the Registry using the codec option. If you are using TCP and no codec is specified then the textline flag is used to determine if text line based codec or object serialization should be used instead. By default the object serialization is used.

For UDP if no codec is specified the default uses a basic ByteBuffer based codec.

The VM protocol is used as a direct forwarding mechanism in the same JVM. See the MINA VM-Pipe API documentation for details.

A Mina producer has a default timeout value of 30 seconds, while it waits for a response from the remote server.

In normal use, camel-mina only supports marshalling the body content—message headers and exchange properties are not sent.
However, the option, transferExchange, does allow you to transfer the exchange itself over the wire. See options below.

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

Options

Using a custom codec

See the Mina documentation how to write your own codec. To use your custom codec with camel-mina, you should register your codec in the Registry; for example, by creating a bean in the Spring XML file. Then use the codec option to specify the bean ID of your codec. See HL7 that has a custom codec.

Sample with sync=false

In this sample, Camel exposes a service that listens for TCP connections on port 6200. We use the textline codec. In our route, we create a Mina consumer endpoint that listens on port 6200:

As the sample is part of a unit test, we test it by sending some data to it on port 6200.

Sample with sync=true

In the next sample, we have a more common use case where we expose a TCP service on port 6201 also use the textline codec. However, this time we want to return a response, so we set the sync option to true on the consumer.

Then we test the sample by sending some data and retrieving the response using the template.requestBody() method. As we know the response is a String, we cast it to String and can assert that the response is, in fact, something we have dynamically set in our processor code logic.

Sample with Spring DSL

Spring DSL can, of course, also be used for MINA. In the sample below we expose a TCP server on port 5555:

In the route above, we expose a TCP server on port 5555 using the textline codec. We let the Spring bean with ID, myTCPOrderHandler, handle the request and return a reply. For instance, the handler bean could be implemented as follows:

Configuring Mina endpoints using Spring bean style

Configuration of Mina endpoints is possible using regular Spring bean style configuration in the Spring DSL.

However, in the underlying Apache Mina toolkit, it is relatively difficult to set up the acceptor and the connector, because you can not use simple setters. To resolve this difficulty, we leverage the MinaComponent as a Spring factory bean to configure this for us. If you really need to configure this yourself, there are setters on the MinaEndpoint to set these when needed.

The sample below shows the factory approach:

And then we can refer to our endpoint directly in the route, as follows:

Closing Session When Complete

When acting as a server you sometimes want to close the session when, for example, a client conversion is finished. To instruct Camel to close the session, you should add a header with the key CamelMinaCloseSessionWhenComplete set to a boolean true value.

For instance, the example below will close the session after it has written the bye message back to the client:

Get the IoSession for message

Available since Camel 2.1
You can get the IoSession from the message header with this key MinaEndpoint.HEADER_MINA_IOSESSION, and also get the local host address with the key MinaEndpoint.HEADER_LOCAL_ADDRESS and remote host address with the key MinaEndpoint.HEADER_REMOTE_ADDRESS.

Configuring Mina filters

Filters permit you to use some Mina Filters, such as SslFilter. You can also implement some customized filters. Please note that codec and logger are also implemented as Mina filters of type, IoFilter. Any filters you may define are appended to the end of the filter chain; that is, after codec and logger.

For instance, the example below will send a keep-alive message after 10 seconds of inactivity:

As Camel Mina may use a request-reply scheme, the endpoint as a client would like to drop some message, such as greeting when the connection is established. For example, when you connect to an FTP server, you will get a 220 message with a greeting (220 Welcome to Pure-FTPd). If you don't drop the message, your request-reply scheme will be broken.

Then, you can configure your endpoint using Spring DSL:

Endpoint See Also

• MINA2
• Netty

Mock Component

Testing Summary Include

The Mock component provides a powerful declarative testing mechanism, which is similar to jMock in that it allows declarative expectations to be created on any Mock endpoint before a test begins. Then the test is run, which typically fires messages to one or more endpoints, and finally the expectations can be asserted in a test case to ensure the system worked as expected.

This allows you to test various things like:

• The correct number of messages are received on each endpoint,
• The correct payloads are received, in the right order,
• Messages arrive on an endpoint in order, using some Expression to create an order testing function,
• Messages arrive match some kind of Predicate such as that specific headers have certain values, or that parts of the messages match some predicate, such as by evaluating an XPath or XQuery Expression.

Note that there is also the Test endpoint which is a Mock endpoint, but which uses a second endpoint to provide the list of expected message bodies and automatically sets up the Mock endpoint assertions. In other words, it's a Mock endpoint that automatically sets up its assertions from some sample messages in a File or database, for example.

URI format

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

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

Options

Simple Example

Here's a simple example of Mock endpoint in use. First, the endpoint is resolved on the context. Then we set an expectation, and then, after the test has run, we assert that our expectations have been met.

You typically always call the assertIsSatisfied() method to test that the expectations were met after running a test.

Camel will by default wait 10 seconds when the assertIsSatisfied() is invoked. This can be configured by setting the setResultWaitTime(millis) method.

Using assertPeriod

Available as of Camel 2.7
When the assertion is satisfied then Camel will stop waiting and continue from the assertIsSatisfied method. That means if a new message arrives on the mock endpoint, just a bit later, that arrival will not affect the outcome of the assertion. Suppose you do want to test that no new messages arrives after a period thereafter, then you can do that by setting the setAssertPeriod method, for example:

Setting expectations

You can see from the javadoc of MockEndpoint the various helper methods you can use to set expectations. The main methods are as follows:

Here's another example:

Adding expectations to specific messages

In addition, you can use the message(int messageIndex) method to add assertions about a specific message that is received.

For example, to add expectations of the headers or body of the first message (using zero-based indexing like java.util.List), you can use the following code:

There are some examples of the Mock endpoint in use in the camel-core processor tests.

Mocking existing endpoints

Available as of Camel 2.7

Camel now allows you to automatically mock existing endpoints in your Camel routes.

Suppose you have the given route below:

You can then use the adviceWith feature in Camel to mock all the endpoints in a given route from your unit test, as shown below:

Notice that the mock endpoints is given the uri mock:<endpoint>, for example mock:direct:foo. Camel logs at INFO level the endpoints being mocked:

Its also possible to only mock certain endpoints using a pattern. For example to mock all log endpoints you do as shown:

The pattern supported can be a wildcard or a regular expression. See more details about this at Intercept as its the same matching function used by Camel.

Mocking existing endpoints using the camel-test component

Instead of using the adviceWith to instruct Camel to mock endpoints, you can easily enable this behavior when using the camel-test Test Kit.
The same route can be tested as follows. Notice that we return "*" from the isMockEndpoints method, which tells Camel to mock all endpoints.
If you only want to mock all log endpoints you can return "log*" instead.

Mocking existing endpoints with XML DSL

If you do not use the camel-test component for unit testing (as shown above) you can use a different approach when using XML files for routes.
The solution is to create a new XML file used by the unit test and then include the intended XML file which has the route you want to test.

Suppose we have the route in the camel-route.xml file:

Then we create a new XML file as follows, where we include the camel-route.xml file and define a spring bean with the class org.apache.camel.impl.InterceptSendToMockEndpointStrategy which tells Camel to mock all endpoints:

Then in your unit test you load the new XML file (test-camel-route.xml) instead of camel-route.xml.

To only mock all Log endpoints you can define the pattern in the constructor for the bean:

Mocking endpoints and skip sending to original endpoint

Available as of Camel 2.10

Sometimes you want to easily mock and skip sending to a certain endpoints. So the message is detoured and send to the mock endpoint only. From Camel 2.10 onwards you can now use the mockEndpointsAndSkip method using AdviceWith or the Test Kit. The example below will skip sending to the two endpoints "direct:foo", and "direct:bar".

The same example using the Test Kit

Limiting the number of messages to keep

Available as of Camel 2.10

The Mock endpoints will by default keep a copy of every Exchange that it received. So if you test with a lot of messages, then it will consume memory.
From Camel 2.10 onwards we have introduced two options retainFirst and retainLast that can be used to specify to only keep N'th of the first and/or last Exchanges.

For example in the code below, we only want to retain a copy of the first 5 and last 5 Exchanges the mock receives.

Using this has some limitations. The getExchanges() and getReceivedExchanges() methods on the MockEndpoint will return only the retained copies of the Exchanges. So in the example above, the list will contain 10 Exchanges; the first five, and the last five.
The retainFirst and retainLast options also have limitations on which expectation methods you can use. For example the expectedXXX methods that work on message bodies, headers, etc. will only operate on the retained messages. In the example above they can test only the expectations on the 10 retained messages.

Testing with arrival times

Available as of Camel 2.7

The Mock endpoint stores the arrival time of the message as a property on the Exchange.

You can use this information to know when the message arrived on the mock. But it also provides foundation to know the time interval between the previous and next message arrived on the mock. You can use this to set expectations using the arrives DSL on the Mock endpoint.

For example to say that the first message should arrive between 0-2 seconds before the next you can do:

You can also define this as that 2nd message (0 index based) should arrive no later than 0-2 seconds after the previous:

You can also use between to set a lower bound. For example suppose that it should be between 1-4 seconds:

You can also set the expectation on all messages, for example to say that the gap between them should be at most 1 second:

Endpoint See Also

• Spring Testing
• Testing

MSV Component

The MSV component performs XML validation of the message body using the MSV Library and any of the supported XML schema languages, such as XML Schema or RelaxNG XML Syntax.

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

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

Note that the Jing component also supports RelaxNG Compact Syntax

URI format

msv:someLocalOrRemoteResource[?options]

Where someLocalOrRemoteResource is some URL to a local resource on the classpath or a full URL to a remote resource or resource on the file system. For example

msv:org/foo/bar.rng
msv:file:../foo/bar.rng
msv:http://acme.com/cheese.rng

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

Options

Example

The following example shows how to configure a route from endpoint direct:start which then goes to one of two endpoints, either mock:valid or mock:invalid based on whether or not the XML matches the given RelaxNG XML Schema (which is supplied on the classpath).

Pojo Component

The pojo: component is now just an alias for the Bean component.

Has been removed in Camel 2.0.

Quartz Component

The quartz: component provides a scheduled delivery of messages using the Quartz Scheduler 1.x .
Each endpoint represents a different timer (in Quartz terms, a Trigger and JobDetail).

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

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

URI format

quartz://timerName?options
quartz://groupName/timerName?options
quartz://groupName/timerName?cron=expression
quartz://timerName?cron=expression

The component uses either a CronTrigger or a SimpleTrigger. If no cron expression is provided, the component uses a simple trigger. If no groupName is provided, the quartz component uses the Camel group name.

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

Options

For example, the following routing rule will fire two timer events to the mock:results endpoint:

When using a StatefulJob, the JobDataMap is re-persisted after every execution of the job, thus preserving state for the next execution.

Configuring quartz.properties file

By default Quartz will look for a quartz.properties file in the org/quartz directory of the classpath. If you are using WAR deployments this means just drop the quartz.properties in WEB-INF/classes/org/quartz.

However the Camel Quartz component also allows you to configure properties:

To do this you can configure this in Spring XML as follows

<bean id="quartz" class="org.apache.camel.component.quartz.QuartzComponent">
    <property name="propertiesFile" value="com/mycompany/myquartz.properties"/>
</bean>

Enabling Quartz scheduler in JMX

You need to configure the quartz scheduler properties to enable JMX.
That is typically setting the option "org.quartz.scheduler.jmx.export" to a true value in the configuration file.

From Camel 2.13 onwards Camel will automatic set this option to true, unless explicit disabled.

Starting the Quartz scheduler

Available as of Camel 2.4

The Quartz component offers an option to let the Quartz scheduler be started delayed, or not auto started at all.

To do this you can configure this in Spring XML as follows

<bean id="quartz" class="org.apache.camel.component.quartz.QuartzComponent">
    <property name="startDelayedSeconds" value="5"/>
</bean>

Clustering

Available as of Camel 2.4

If you use Quartz in clustered mode, e.g. the JobStore is clustered. Then from Camel 2.4 onwards the Quartz component will not pause/remove triggers when a node is being stopped/shutdown. This allows the trigger to keep running on the other nodes in the cluster.

Note: When running in clustered node no checking is done to ensure unique job name/group for endpoints.

Message Headers

Camel adds the getters from the Quartz Execution Context as header values. The following headers are added:
calendar, fireTime, jobDetail, jobInstance, jobRuntTime, mergedJobDataMap, nextFireTime, previousFireTime, refireCount, result, scheduledFireTime, scheduler, trigger, triggerName, triggerGroup.