docs/user-manual/modules/ROOT/pages/routes.adoc

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

For instance, you could write a _route_ to consume files from an FTP server and send them to an http://activemq.apache.org[ActiveMQ] messaging system. A _route_ to do so, using xref:java-dsl.adoc[Java DSL], would look like this:

[source,java]
----
from("ftp:myserver/folder")
  .to("activemq:queue:cheese");
----

Camel _routes_ can be defined using a variety of xref:dsl.adoc[domain-specific languages (DSLs)], such as Java, Spring XML, or YAML. For example, you could write the _route_ described above using XML:

[source,xml]
----
<route>
  <from uri="ftp:myserver/folder"/>
  <to uri="activemq:queue:cheese"/>
</route>
----

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

[tabs]
====
Java::
+
[source,java]
----
from("ftp:myserver/folder").routeDescription("Routes files from the FTP server to internal messaging system")
  .to("activemq:queue:cheese");
----

XML::
+
[source,xml]
----
<route description="Routes files from the FTP server to internal messaging system">
  <from uri="ftp:myserver/folder"/>
  <to uri="activemq:queue:cheese"/>
</route>
----

YAML::
+
[source,yaml]
----
- 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.

[tabs]
====
Java::
+
[source,java]
----
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");
----

XML::
+
[source,xml]
----
<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>
----

YAML::
+
[source,yaml]
----
- 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
----
====

TIP: 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 xref:manual::route-builder.adoc[`RouteBuilder` class], and implementing the `configure` method.

Here's an example:

[source,java]
------------------------------------------------------
RouteBuilder builder = new RouteBuilder() {
    public void configure() {
        from("direct:a").to("direct:b");
    }
};
------------------------------------------------------

As you can see from the code snippet above, Camel uses xref:manual::uris.adoc[URIs] to wire endpoints together.

We refer to this way of writing route as using the xref:manual::java-dsl.adoc[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.

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

[source,java]
----
from("direct:in").precondition("'{{format}}' == 'xml'")
   .unmarshal().jaxb()
   .to("direct:out");
----

You can write the same route described above using the xref:components:others:java-xml-io-dsl.adoc[XML DSL]:

[source,xml]
----
<route precondition="'{{format}}' == 'xml'">
  <from uri="direct:in"/>
  <unmarshal><jaxb/></unmarshal>
  <to uri="direct:out"/>
</route>
----

You can also write the same route described above using the xref:components:others:yaml-dsl.adoc[YAML DSL]:

[source,yaml]
----
- route:
    precondition: "'{{format}}' == 'xml'"
    from:
      uri: "direct:in"
      steps:
        - unmarshal:
            jaxb: {}
        - to: "direct:out"
----

== More Information

Check the xref:dsl.adoc[list of supported languages] that you can use for writing Camel routes.