How do I configure endpoints?

There are a few different approaches to configuring components and endpoints.

Using Java Code

You can explicitly configure a Component using Java code as shown in this example

Or you can explicitly get hold of an Endpoint and configure it using Java code as shown in the Mock endpoint examples.

SomeEndpoint endpoint = camelContext.getEndpoint("someURI", SomeEndpoint.class);
endpoint.setSomething("aValue");

Using Spring XML

You can configure your Component or Endpoint instances in your Spring XML as <bean> as follows:

<bean id="activemq" class="org.apache.activemq.camel.component.ActiveMQComponent">
  <property name="connectionFactory">
    <bean class="org.apache.activemq.ActiveMQConnectionFactory">
      <property name="brokerURL" value="vm://localhost?broker.persistent=false&amp;broker.useJmx=false"/>
    </bean>
  </property>
</bean>

Which allows you to configure a component using some name (activemq in the above example), then you can refer to the component using activemq:[queue:|topic:]destinationName. This works by the SpringCamelContext lazily fetching components from the spring context for the scheme name you use for Endpoint URIs

Using Endpoint URIs

Another approach is to use the URI syntax. The URI syntax supports the query notation. So for example with the Mail component you can configure the password property via the URI

pop3://host:port?password=foo

Referring beans from Endpoint URIs

When configuring endpoints using the URI syntax you can refer to beans in the Registry using the #bean:id notation.

The older syntax with just #id has been deprecated due to ambiguity as Camel supports a number of additional functions that start with the # notation.

If the URI parameter value starts with #bean: then Camel will lookup in the Registry for a bean of the given type by id. For instance:

file://inbox?sorter=#bean:mySpecialFileSorter

Will lookup a bean with the id mySpecialFileSorter in the Registry.

Camel also supports to refer to beans by their class type.

Referring beans by class from Endpoint URIs

When configuring endpoints using URI syntax you can now refer to bean by its class name using the #class:fullyQualifiedName notation.

If the parameter value starts with a #class: sign then Camel will load the class with the given name, and create an instance of the bean using its no-arg constructor:

file://inbox?sorter=#class:com.foo.MySpecialSorter

If you need to provide parameters to the constructor, then this is also possible (limited to numbers, boolean, literal, and null values)

file://inbox?sorter=#class:com.foo.MySpecialSorter(10, 'Hello world', true)

Referring beans by type from Endpoint URIs

When configuring endpoints using URI syntax you can now refer to bean by its type which are used to lookup the bean by the given type from the Registry. If there is one bean found in the registry of the given type, then that bean instance will be used; otherwise an exception is thrown.

file://inbox?idempontentRepository=#type:org.apache.camel.spi.IdempotentRepository

Configuring parameter values using raw values, eg such as passwords

Since Camel 2.11

When configuring endpoint options using URI syntax, then the values is by default URI encoded. This can be a problem if you want to configure passwords and just use the value as is without any encoding. For example you may have a plus sign in the password, which would be decimal encoded by default.

So from Camel 2.11 onwards we made this easier as you can denote a parameter value to be raw using the following syntax RAW(value), e.g. the value starts with RAW( and then ends with the parenthesis ). Here is a little example:

.to("ftp:joe@myftpserver.com?password=RAW(se+re?t&23)&binary=true")

In the above example, we have declare the password value as raw, and the actual password would be as typed, eg se+re?t&23.

you may find a corner case when you use both ) and & character as part of your password (ie, se+re)t&23). The parser will interpret the ) as closing the RAW function and having a parameter started by &. In such case, you can instead use the RAW{} notation to let you include the ) character and have it decoded as part of the password (ie, RAW{se+re)t&23}). As a safe alternative you can also use password=#property:myPass and then have myPass a property placeholder value.

Using property placeholders

Camel has extensive support for using property placeholders, which you can read more about here. For example in the ftp example above we can externalize the password to a .properties file.

For example configuring the property placeholder when using a XML DSL, where we declare the location of the .properties file. Though we can also define this in Java code. See the documentation for more details.

<camelContext>
   <propertyPlaceholder id="properties" location="myftp.properties"/>
   ...
</camelContext>

And the Camel route now refers to the placeholder using the {{key}} notation:

.to("ftp:joe@myftpserver.com?password={{myFtpPassword}}&binary=true"

And have a myftp.properties file with password. Notice we still define the RAW(value) style to ensure the password is used as is:

myFtpPassword=RAW(se+re?t&23)

We could still have used the RAW(value) in the Camel route instead:

.to("ftp:joe@myftpserver.com?password=RAW({{myFtpPassword}})&binary=true")

And then we would need to remove the RAW from the properties file:

myFtpPassword=se+re?t&23

To understand more about property placeholders, read the documentation.

In Camel 3.4 you can use an alternative than RAW to refer to a property placeholder by its key, as discussed in the following section.

Referring to a property placeholder

When using {{key}} in configuring endpoint URIs then Camel will replace the {{key}} while parsing the endpoint URI. This has its pros but also a few cons, such as when using sensitive information such as passwords. As we have seen in the previous section you can use RAW() syntax. Instead of using RAW() you can use #property:key notation, as shown in the example below:

.to("ftp:joe@myftpserver.com?password=#property:myFtpPassword&binary=true")
  1. and in XML:

<to uri="ftp:joe@myftpserver.com?password=#property:myFtpPassword&amp;binary=true"/>

Configuring URIs using endpoint with bean property style

Sometimes configuring endpoint URIs may have many options, and therefore the URI can become long. In Java DSL you can break the URIs into new lines as its just Java code, e.g. just concat the String. When using XML DSL then the URI is an attribute, e.g. <from uri="bla bla"/>. From Camel 2.15 onwards you can configure the endpoint separately, and from the routes refer to the endpoints using their shorthand ids.

<camelContext>

  <endpoint id="foo" uri="ftp://foo@myserver">
    <property key="password" value="secret"/>
    <property key="recursive" value="true"/>
    <property key="ftpClient.dataTimeout" value="30000"/>
    <property key="ftpClient.serverLanguageCode" value="fr"/>
  </endpoint>

  <route>
    <from uri="ref:foo"/>
    ...
  </route>
</camelContext>

In the example above, the endpoint with id foo, is defined using <endpoint> which under the covers assembles this as an URI, with all the options, as if you have defined all the options directly in the URI. You can still configure some options in the URI, and then use <property> style for additional options, or to override options from the URI, such as:

<endpoint id="foo" uri="ftp://foo@myserver?recursive=true">
  <property key="password" value="secret"/>
  <property key="ftpClient.dataTimeout" value="30000"/>
  <property key="ftpClient.serverLanguageCode" value="fr"/>
</endpoint>

Configuring long URIs using new lines

Sometimes configuring endpoint URIs may have many options, and therefore the URI can become long. In Java DSL you can break the URIs into new lines as its just Java code, e.g. just concat the String. When using XML DSL then the URI is an attribute, e.g. <from uri="bla bla"/>. From Camel 2.15 onwards you can break the URI attribute using new line, such as shown below:

<route>
  <from uri="ftp://foo@myserver?password=secret&amp;
           recursive=true&amp;
           ftpClient.dataTimeout=30000&amp;
           ftpClientConfig.serverLanguageCode=fr"/>
  <to uri="bean:doSomething"/>
</route>

Notice that it still requires escaping & as &amp; in XML. Also you can have multiple options in one line, eg this is the same:

<route>
  <from uri="ftp://foo@myserver?password=secret&amp;
           recursive=true&amp;ftpClient.dataTimeout=30000&amp;
           ftpClientConfig.serverLanguageCode=fr"/>
  <to uri="bean:doSomething"/>
</route>