Camel User Guide

1. Introduction

Apache Camel is a powerful open source integration framework based on known Enterprise Integration Patterns with powerful Bean Integration.

1.1. Camel in ServiceMix

In ServiceMix, Apache Camel is like our swiss army knife for creating integration solutions. It allows using XML or a Java/Scala-based DSL to express your routes, comes with almost 200 optional components, has powerful and versatile Java bean integration, error handling, and tons of other features.

Apache Camel is installed by default if you first start the container. We also have out-of-the-box hot-deployment support for both Spring and Blueprint to make it easy to deploy your own Camel routes, as well as optionally installable features for all the available Camel components.

1.2. Goal of this guide

The goal of this guide is to look into the details for using Camel inside ServiceMix:

deployment options
installing additional components

1.3. Examples

The Apache ServiceMix distribution also contain a set of Camel examples. You can find these examples in the examples/camel directory.

1.4. More information about Camel

More information about Camel itself can be found on http://camel.apache.org.

There’s also a great book available about Camel. Its second edition is planned to be published in July 2017:

Ibsen, Claus, and Anstey, Jonathan. (July 2017). Camel in Action, Second Edition. Manning Publications. ISBN: 9781617292934.

2. Deployment Options

There are a few different ways to deploy Camel routes on ServiceMix:

deploy routes in a plain Blueprint XML file
deploy routes in a plain Spring XML file
deploy a bundle containing a Blueprint XML file
deploy a bundle containing a Spring XML file

2.1. Benefits and drawbacks

2.1.1. Plain XML or OSGi bundles

Choose a plain XML file:

if you want to get routes deployed as quickly as possible.
All you need for developing routes is a simple text editor, no compilation and building is required.
if you prefer the XML syntax over the Java of Scala DSL.

Choose an OSGi bundle:

if you want to package helper classes together with your route definitions.
if you prefer developing routes in the Java or Scala DSL.
The RouteBuilder implementations can be packaged inside the bundle.

2.1.2. Blueprint or Spring

Choose Blueprint if you want the best possible integration with the OSGi Framework and Service Registy. The Blueprint specification has been developed specifically for the OSGi Framework by the OSGi Alliance.

Choose Spring if you already invested in Spring for creating and running Camel routes.

2.2. Deploy as a plain Spring XML file

ServiceMix supports the deployment of plain Spring XML files, automatically creating and starting the Spring ApplicationContext from the XML file.

In order to leverage this feature to create and start Camel routes, drop a file with this syntax in the $SERVICEMIX_HOME/deploy folder:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:ctx="http://www.springframework.org/schema/context"
       xmlns:camel="http://camel.apache.org/schema/spring"
       xmlns:osgix="http://www.springframework.org/schema/osgi-compendium"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
       http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
       http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd
       http://www.springframework.org/schema/osgi-compendium http://www.springframework.org/schema/osgi-compendium/spring-osgi-compendium.xsd">

  <camel:camelContext xmlns="http://camel.apache.org/schema/spring">
        <!-- add Camel route definitions etc here -->
  </camel:camelContext>

</beans>

2.2.1. Example

Create a new XML file, plain-spring.xml, in the deployment folder with the code below to start a route to copy files from one directory to another.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:ctx="http://www.springframework.org/schema/context"
       xmlns:camel="http://camel.apache.org/schema/spring"
       xmlns:osgix="http://www.springframework.org/schema/osgi-compendium"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
       http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
       http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd
       http://www.springframework.org/schema/osgi-compendium http://www.springframework.org/schema/osgi-compendium/spring-osgi-compendium.xsd">

  <camel:camelContext xmlns="http://camel.apache.org/schema/spring">
    <route>
      <from uri="file:input"/>
      <log message="Copying ${file:name} to the output directory"/>
      <to uri="file:output"/>
    </route>
  </camel:camelContext>

</beans>

Verify in the Karaf console that it has been started:

karaf@root> bundle:list | grep plain-spring
223 | Active   |  80 | 0.0.0                              | plain-spring.xml
karaf@root>

Copy a file into the folder $SERVICEMIX_HOME/input, and verify that it is copied to the folder $SERVICEMIX_HOME/output. Note that the original file has been moved to the folder $SERVICEMIX_HOME/input/.camel.

2.3. Deploy as a plain Blueprint XML file

ServiceMix supports the deployment of plain Blueprint XML files, automatically creating and starting the Blueprint container from the XML file.

In order to leverage this feature to create and start Camel routes, drop a file with this syntax in the $SERVICEMIX_HOME/deploy folder:

<?xml version="1.0" encoding="UTF-8"?>
<blueprint
    xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
    xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd">

    <camelContext xmlns="http://camel.apache.org/schema/blueprint">
        <!-- add Camel route definitions etc here -->
    </camelContext>

</blueprint>

2.3.1. Example

Create a new XML file, plain-blueprint.xml, in the deployment folder with the code below to start a route to copy files from one directory to another.

<?xml version="1.0" encoding="UTF-8"?>
<blueprint
    xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
    xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd">

    <camelContext xmlns="http://camel.apache.org/schema/blueprint">
      <route>
        <from uri="file:input"/>
        <log message="Copying ${file:name} to the output directory"/>
        <to uri="file:output"/>
      </route>
    </camelContext>

</blueprint>

Verify in the Karaf console that it has been started:

karaf@root> bundle:list | grep plain-blueprint
223 | Active   |  80 | 0.0.0                              | plain-blueprint.xml
karaf@root>

2.4. Deploy as an OSGi bundle with Spring

Using an OSGi bundle to deploy your Camel routes allows you to use the Java or Scala DSL for defining your routes.

In this case, you’re using Spring to start your Camel routes, so you include your Spring XML file (e.g. camel-context.xml) in the META-INF/spring folder inside your bundle.

+ <bundle classes, incl. your RouteBuilder>
\- META-INF
   |- MANIFEST.MF
   \- spring
      \- camel-context.xml

After the bundle has been activated, the Spring DM extender will find, create and start your Spring ApplicationContexts.

2.4.1. Example: Referring to Java or Scala RouteBuilder classes

If your RouteBuilder classes have been defined in the org.apache.servicemix.manual.camel package, the file would look like this:

<?xml version="1.0" encoding="UTF-8"?>
<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-${camel-version}.xsd">

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

</beans>

2.4.2. Example in the distribution

Another example for using this deployment option can be found in the camel-osgi example that is shipped with Apache ServiceMix.

2.5. Deploy as an OSGi bundle with Blueprint

Using an OSGi bundle to deploy your Camel routes allows you to use the Java or Scala DSL for defining your routes.

In this case, we will use a Blueprint XML file to start your Camel routs. To do so, the Blueprint XML files have to be included in the bundle inside the OSGI-INF/blueprint directory.

+ <bundle classes, incl. your RouteBuilder>
|- META-INF
|  |- MANIFEST.MF
\- OSGI-INF
   \- blueprint
      \- camel-context.xml

As soon as the bundle becomes Active, the Blueprint extender will create the Blueprint container starting your Routes.

2.5.1. Example: Referring to Java or Scala RouteBuilder classes

If your RouteBuilder classes have been defined in the org.apache.servicemix.examples.camel package, the file would look like this:

<blueprint
    xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
    xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd">

    <camelContext xmlns="http://camel.apache.org/schema/blueprint">
        <package>org.apache.servicemix.examples.camel</package>
    </camelContext>
</blueprint>

2.5.2. Example in the distribution

Another example for using this deployment option can be found in the camel-blueprint example that is shipped with Apache ServiceMix.

In order to add a Java DSL route to that example, the following changes have to be implemented.

First, add the camel-core library as a dependency to the pom-file:

<dependencies>
    <dependency>
        <groupId>org.apache.camel</groupId>
        <artifactId>camel-core</artifactId>
        <version>2.16.5</version>
    </dependency>
</dependencies>

Then, add the following class to the org.apache.servicemix.examples.camel-package, alongside the existing MyTransform-class:

package org.apache.servicemix.examples.camel;

import org.apache.camel.builder.RouteBuilder;

public class MyRouteBuilder extends RouteBuilder {

    public void configure() {
        // set up the transform bean
        MyTransform transform = new MyTransform();
        transform.setPrefix("JavaDSL");

        from("timer://javaTimer?fixedRate=true&period=2000")
            .bean(transform, "transform")
            .to("log:ExampleRouter");
    }
}

Finally, add the package-element to the Blueprint-file. The complete Blueprint file looks like this:

<blueprint
    xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
    xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd">

    <camelContext
        xmlns="http://camel.apache.org/schema/blueprint">
        <!-- install the Java DSL route builder -->
        <package>org.apache.servicemix.examples.camel</package> (1)

        <!-- install the route which is defined with XML tags --> (2)
        <route>
            <from uri="timer://myTimer?fixedRate=true&amp;period=2000" />
            <bean ref="myTransform" method="transform"/>
            <to uri="log:ExampleRouterBlueprint" />
        </route>
    </camelContext>

    <cm:property-placeholder persistent-id="org.apache.servicemix.examples" update-strategy="reload">
        <cm:default-properties>
            <cm:property name="prefix" value="Blueprint-Example"/> (3)
        </cm:default-properties>
    </cm:property-placeholder>

    <bean id="myTransform" class="org.apache.servicemix.examples.camel.MyTransform">
        <property name="prefix" value="${prefix}" />
    </bean>
</blueprint>

1	The package-element causes the route defined by the Java DSL to be installed and started.
2	The route defined by XML tags and the one defined by the Java DSL are functionally equivalent, and run independently.
3	The default value of the prefix-parameter is displayed in the output in the Karaf console, unless it is changed in the example configuration file.

Once you have built the example, with mvn clean install, and installed it in Karaf using feature:install examples-camel-blueprint output from both routes will be displayed in the Karaf console:

>>>> Blueprint-Example set body:  Sun May 07 13:38:47 CEST 2017
>>>> JavaDSL set body:  Sun May 07 13:38:47 CEST 2017

3. Installing Components

Camel comes with almost 200 components, so you can imagine that we don’t install all of them by default. This section shows you how to find available components and how to install them at runtime.

3.1. List available components

Camel components are available as installable features. You can look at the full list of available features using the feature:list command, using grep to limit things down to features related to Camel:

karaf@root> feature:list | grep camel
camel-xmlsecurity     | 2.16.5      |          | Uninstalled | camel-2.16.5  |
camel-xmpp            | 2.16.5      |          | Uninstalled | camel-2.16.5  |
camel-xstream         | 2.16.5      | x        | Started     | camel-2.16.5  |
camel-yammer          | 2.16.5      |          | Uninstalled | camel-2.16.5  |
camel-zipfile         | 2.16.5      |          | Uninstalled | camel-2.16.5  |

3.2. Install and uninstalling components

You can use feature:install to install any component on the list.

An example: to install the camel-cache component

karaf@root> feature:install camel-cache

Similarly, you can also uninstall components that you’re no longer using with feature:uninstall

karaf@root> feature:uninstall camel-cache

4. Troubleshooting

In this section, you’ll find solutions for some frequently asked questions when using Camel on ServicMix.

4.1. No component with id 'xyz' could be found

This usually means that your route is trying to use a component that hasn’t been installed yet.

Solution:

install the additional component
restart the bundle using the bundle:restart <bundle id> command - you can find the bundle id for your route in the output of the bundle:list command

Refer to Installing additional components

Apache ServiceMix Version 7.0.1-SNAPSHOT. © 2008-2017 The Apache Software Foundation.
Apache ServiceMix, ServiceMix, Apache, the Apache feather logo, and the Apache ServiceMix project logo are trademarks of The Apache Software Foundation.