User manual

Routes

In Apache Camel, a route is a set of processing steps that are applied to a message as it travels from a source to a destination. A route typically consists of a series of processing steps that are connected in a linear sequence.

A Camel route is where the integration flow is defined. For example, you can write a Camel route to specify how two systems can be integrated. You can also specify how the data can be manipulated, routed, or mediated between the systems.

The routes are typically defined using a simple, declarative syntax that is easy to read and understand. Camel supports coding routes in different DSLs of your choice.

For instance, you could write a route to consume files from an FTP server and send them to an ActiveMQ messaging system. A route to do so, would look like this:

  • Java

  • XML

  • YAML

from("ftp:myserver/folder")
  .to("activemq:queue:cheese");
<route>
  <from uri="ftp:myserver/folder"/>
  <to uri="activemq:queue:cheese"/>
</route>
- route:
    from:
      uri: ftp:myserver/folder
      steps:
        - to:
            uri: activemq:queue:cheese

Naming routes

You can assign names to your routes in Java DSL using routeId:

  • Java

  • XML

  • YAML

In Java DSL you use routeId to declare the name/id of the route.

from("ftp:myserver/folder").routeId("myRoute")
  .to("activemq:queue:cheese");

In XML DSL you use id in the <route> element to declare the name/id of the route.

<route id="myRoute">
  <from uri="ftp:myserver/folder"/>
  <to uri="activemq:queue:cheese"/>
</route>

In YAML DSL you use id in the - route node to declare the name/id of the route.

- route:
    id: myRoute
    from:
      uri: ftp:myserver/folder
      steps:
        - to:
            uri: activemq:queue:cheese

Route Description and Notes

You can add a description to your routes, for example to provide a short human summary of what the route does.

  • Java

  • XML

  • YAML

from("ftp:myserver/folder").routeDescription("Routes files from the FTP server to internal messaging system")
  .to("activemq:queue:cheese");
<route description="Routes files from the FTP server to internal messaging system">
  <from uri="ftp:myserver/folder"/>
  <to uri="activemq:queue:cheese"/>
</route>
- route:
    description: "Routes files from the FTP server to internal messaging system"
    from:
      uri: ftp:myserver/folder
      steps:
        - to:
            uri: activemq:cheese

A note (requires Camel 4.16 onwards) on the other hand is like a code comments for developers or some other kind of information you want to keep. Both the notes and descriptions has no impact at runtime but are read-only information.

  • Java

  • XML

  • YAML

from("ftp:myserver/folder").routeDescription("Routes files from the FTP server to internal messaging system")
    .routeNote("The FTP server can be offline from time to time, and if so then just restart Camel")
  .to("activemq:queue:cheese");
<route description="Routes files from the FTP server to internal messaging system"
       note="The FTP server can be offline from time to time, and if so then just restart Camel">
  <from uri="ftp:myserver/folder"/>
  <to uri="activemq:queue:cheese"/>
</route>
- route:
    description: "Routes files from the FTP server to internal messaging system"
    note: "The FTP server can be offline from time to time, and if so then just restart Camel"
    from:
      uri: ftp:myserver/folder
      steps:
        - to:
            uri: activemq:cheese
You can also add description and notes to EIP patterns

Writing Routes in Java using the Java DSL

You can create a route using the Java language by extending the RouteBuilder class, and implementing the configure method.

Here’s an example:

Java-only: anonymous RouteBuilder class
RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        from("direct:a").to("direct:b");
    }
};

The code above is an anonymous class, and its more common to create your own class when using Java DSL for example we can create a class called MyRoute which then implements the route as follows:

Java-only: named RouteBuilder class
import org.apache.camel.builder.RouteBuilder;

public class MyRoute extends RouteBuilder {

    @Override
    public void configure() {
        from("direct:a").to("direct:b");
    }

}

As you can see from the code snippet above, Camel uses URIs to wire endpoints together.

We refer to this way of writing route as using the Java DSL.

Route Precondition

The routes can be included or not according to the result of a test. You can express the condition for the tests using the simple language. Camel evaluates this condition only once during the initialization phase.

When a route is not included due to precondition, then the route is skipped by Camel, and its not possible to include the router later during runtime. If you want to include the route, but not start the route, then you can set autoStartup=false on the route. Which allows to start the route later during runtime.

Here’s an example that includes the route only if the parameter format has been set to xml:

  • Java

  • XML

  • YAML

from("direct:in").precondition("'{{format}}' == 'xml'")
   .unmarshal().jaxb()
   .to("direct:out");
<route precondition="'{{format}}' == 'xml'">
  <from uri="direct:in"/>
  <unmarshal><jaxb contextPath="com.foo.model"/></unmarshal>
  <to uri="direct:out"/>
</route>
- route:
    precondition: "'{{format}}' == 'xml'"
    from:
      uri: "direct:in"
      steps:
        - unmarshal:
            jaxb:
              contextPath: com.foo.model
        - to:
            uri: direct:out

Route Checksum and Revision

Each route has a checksum of the route as written, which tools such as the Camel CLI, an IDE or an AI agent use to tell which routes changed between two runs of an application, or after a reload. The same route gives the same checksum in every run.

The checksum is a short hash (12 hex characters) of the whole route: its steps, their options and expressions, with property placeholders as written. It leaves out what does not change the route:

  • the ids Camel generates (a route or step with an id of its own keeps it in the checksum), also the node prefix that a route template or a Kamelet gives the routes it creates, and the id of a Kamelet route without one of its own: the same templated route has the same checksum each time it is created;

  • where the route is in its source: moving the route in its file, or adding a route above it, keeps its checksum;

  • the parts that route configurations add to every route (their onException, intercept and onCompletion): a change in a shared route configuration does not change every route. The onException of a route itself is part of it;

  • the secrets in endpoint URIs, such as a password written in the URI, which are masked as in the logs.

Each route also has a revision in the running application: it is 1 when the route is added, and one more each time the route is added again with another checksum, such as when route reloading changed it. A reload that brings the route back as it was keeps its revision. The revision follows the route id, and starts over when the application restarts: to compare two runs, compare the checksums. Camel keeps the revisions of the 10000 route ids used last.

The checksum and revision are on the Route (getChecksum() and getRevision()), on the route in JMX (the Checksum and Revision attributes), in the route developer console, and in the Camel CLI (camel get route --checksum). The route-structure and route-dump developer consoles have the checksum of each route, so the facts a tool keeps per line of a route know which version of the route they belong to. The Camel CLI gives the checksum of the routes of a source file without running it (camel cmd route-structure orders.camel.yaml): it is the one the route has when it runs.

The checksum needs camel-xml-io on the classpath, which comes with camel-core, camel-management and the Camel CLI connector. Without it the routes have no checksum, and no revision.

The checksum covers the route, not the code it calls: changing a Java lambda in .process(…​), or a bean the route calls, does not change it. Neither does a property value the route uses, which is configuration, not another route, nor an object given to an endpoint DSL option, such as a DataSource, which is a bean. A route without an id of its own gets an id such as route3, which can move to another route when routes are added to or removed from its file: match such routes by their checksum.

More Information

Check the list of supported languages that you can use for writing Camel routes.