Route Template

A Route template is as its name implies a template for a route, which are used to create routes from a set of input parameters. Another way of think is that route templates are parameterized routes.

Route template + input parameters => route

From a route template you can create one or more routes.

Defining route templates in the DSL

Route templates are to be defined in the DSL (just like routes) as shown in the following:

public class MyRouteTemplates extends RouteBuilder {

    @Override
    public void configure() throws Exception {
        // create a route template with the given name
        routeTemplate("myTemplate")
            // here we define the required input parameters (can have default values)
            .templateParameter("name")
            .templateParameter("greeting")
            .templateParameter("myPeriod", "3s")
            // here comes the route in the template
            // notice how we use {{name}} to refer to the template parameters
            // we can also use {{propertyName}} to refer to property placeholders
            .from("timer:{{name}}?period={{myPeriod}}")
                .setBody(simple("{{greeting}} ${body}"))
                .log("${body}");
    }
}

And in XML DSL

<camelContext>
  <routeTemplate id="myTemplate">
    <templateParameter name="name"/>
    <templateParameter name="greeting"/>
    <templateParameter name="myPeriod" defaultValue="3s"/>
    <route>
      <from uri="timer:{{name}}?period={{myPeriod}}"/>
      <setBody><simple>{{greeting}} ${body}</simple></setBody>
      <log message="${body}"/>
    </route>
  </routeTemplate>
</camelContext>

In the examples above there was one route template, but you can define as many as you want. Each template must have an unique id. The template parameters are used for defining the parameters the template accepts. As you can see there are 3 parameters: name, greeting, and myPeriod. The first two parameters are mandatory, where as myPeriod is optional as it has a default value of 3s.

The template parameters are then used in the route as regular property placeholders with the {{ }} syntax. Notice how we use {{name}} and {{greeting}} in the timer endpoint and the simple language.

The route can of course also use regular property placeholders as well. Now imagine there was a property placeholder with the name greeting:

greeting = Davs

Then Camel would normally have used this value Davs when creating the route. However as the route template has defined a template parameter with the same name greeting then a value must be provided when creating routes from the template.

Template parameters take precedence over regular property placeholders.

Creating a route from a route template

To create routes from route templates, then you must use the Java API from CamelContext.

In the following you can see how this is done with the addRouteFromTemplate method

    Map<String, Object> parameters = new HashMap<>();
    parameters.put("name", "one");
    parameters.put("greeting", "hello");
    context.addRouteFromTemplate(null, "myTemplate", parameters);

There is a fluent builder variation as shown below:

    // create two routes from the template
    context.addRouteFromTemplate("myTemplate")
        .parameter("name", "one")
        .parameter("greeting", "Hello")
        .build();

    context.addRouteFromTemplate("myTemplate")
        .parameter("name", "two")
        .parameter("greeting", "Bonjour")
        .parameter("myPeriod", "5s")
        .build();

The returned value from addRouteFromTemplate is the route id of the new route that was added. However null is returned if the route is not yet created and added, which can happen if CamelContext is not started yet.

If no route id is provided, then Camel will auto assign a route id. In the example above then Camel would assign route ids such as route1, route2 to these routes.

If you want to specify a route id, then do as follows, where the name is myCoolRoute:

    Map<String, Object> parameters = new HashMap<>();
    parameters.put("name", "one");
    parameters.put("greeting", "hello");
    context.addRouteFromTemplate("myCoolRoute", "myTemplate", parameters);

Or with the fluent builder:

    context.addRouteFromTemplate("myTemplate")
        .routeId("myCoolRoute")
        .parameter("name", "one")
        .parameter("greeting", "Hello")
        .build();

JMX management

The route templates can be dumped as XML from the ManagedCamelContextMBean MBean via the dumpRouteTemplatesAsXml operation.

Creating routes from properties file

When using camel-main you can specify the parameters for route templates in application.properties file.

For example given the route template below (from a RouteBuilder class):

routeTemplate("mytemplate")
    .templateParameter("input")
    .templateParameter("result")
    .from("direct:{{input}}")
        .to("mock:{{result}}");

Then we can create two routes from this template by configuring the values in the application.properties file:

camel.route-template[0].template-id=mytemplate
camel.route-template[0].input=foo
camel.route-template[1].result=cheese

camel.route-template[1].template-id=mytemplate
camel.route-template[1].input=bar
camel.route-template[1].result=cheese

Creating routes from custom sources of template parameters

The SPI interface org.apache.camel.spi.RouteTemplateParameterSource can be used to implement custom sources that are used during startup of Camel to create routes via the templates with parameters from the custom source(s).

For example a custom source can be implemented that reads parameters from a shared database that Camel uses during staring by creating routes. This allows to externalize these parameters and as well to easily add more routes with varying parameters.

To let Camel discover custom sources then register the source into the Camel registry.