Bean Language

The purpose of the Bean Language is to be able to implement an Expression or Predicate using a simple method on a bean. The bean name is resolved using a Registry, such as the SpringApplicationContext, then a method is invoked to evaluate the Expression or Predicate. If no method name is provided then one is chosen using the rules for Bean Binding; using the type of the message body and using any annotations on the bean methods.

The Bean Binding rules are used to bind the Message Exchange to the method parameters; so you can annotate the bean to extract headers or other expressions such as XPath or XQuery from the message.

Using Bean Expressions in Java

Using Bean Expressions in Spring XML

Bean Attribute Now Deprecated

The bean attribute of the method expression element is now deprecated. Use the ref attribute instead.

Writing the Expression Bean

The bean in the above examples is just any old Java Bean with a method called isGoldCustomer() that returns some object that is easily converted to a boolean value in this case, as its used as a predicate.

So you can bind parameters of the method to the Exchange, the Message or individual headers, properties, the body or other expressions.

Non-Registry Beans

The Bean Language also supports invoking beans that isn't registered in the Registry. This is usable for quickly to invoke a bean from Java DSL where you don't need to register the bean in the Registry such as the SpringApplicationContext. Camel can instantiate the bean and invoke the method if given a class or invoke an already existing instance.

Example:

The 2nd parameter isGoldCustomer is an optional parameter to explicit set the method name to invoke. If not provided Camel will try to invoke the most suitable method. If case of ambiguity Camel will thrown an Exception. In these situations the 2nd parameter can solve this problem. Also the code is more readable if the method name is provided. The 1st parameter can also be an existing instance of a Bean such as:

In Camel 2.2: you can avoid the BeanLanguage and have it just as:

Which also can be done in a bit shorter and nice way:

Other Examples

We have some test cases you can look at if it'll help

MethodFilterTest is a JUnit test case showing the Java DSL use of the bean expression being used in a filter

aggregator.xml is a Spring XML test case for the Aggregator which uses a bean method call to test for the completion of the aggregation.

Dependencies

The Bean language is part of camel-core.

Constant Expression Language

The Constant Expression Language is really just a way to specify constant strings as a type of expression.

Example usage

The setHeader element of the Spring DSL can utilize a constant expression like:

In this case, the Message coming from the seda:aEndpoint will have theHeader header set to the constant value the value.

Header Expression Language

The Header Expression Language allows you to extract values of named headers.

Example usage

The recipientList element of the Spring DSL can utilize a header expression like:

In this case, the list of recipients are contained in the header 'myHeader'.

And the same example in Java DSL:

And with a slightly different syntax where you use the builder to the fullest (i.e. avoid using parameters but using stacked operations, notice that header is not a parameter but a stacked method call)

You can use XPath expressions directly using smart completion in your IDE as follows

Variables

Variable

Type

Description

this

Exchange

the Exchange object

in

Message

the exchange.in message

out

Message

the exchange.out message

Options

Option

Type

Description

lenient

boolean

Camel 2.11/2.10.5: Allows to turn lenient on the JXPathContext. When turned on this allows the JXPath expression to evaluate against expressions and message bodies which may be invalid / missing data. See more details at the JXPath Documentation This option is by default false.

Using XML configuration

If you prefer to configure your routes in your Spring XML file then you can use JXPath expressions as follows

Examples

JXPath injection

You can use Bean Integration to invoke a method on a bean and use various languages such as JXPath to extract a value from the message and bind it to a method parameter.

For example

Loading script from external resource

Available as of Camel 2.11

You can externalize the script and have Camel load it from a resource such as "classpath:", "file:", or "http:".
This is done using the following syntax: "resource:scheme:location", eg to refer to a file on the classpath you can do:

Dependencies

To use JXpath in your camel routes you need to add the a dependency on camel-jxpath which implements the JXpath language.

Samples

Loading script from external resource

Available as of Camel 2.11

You can externalize the script and have Camel load it from a resource such as "classpath:", "file:", or "http:". This is done using the following syntax: "resource:scheme:location", eg to refer to a file on the classpath you can do:

Dependencies

To use Mvel in your camel routes you need to add the a dependency on camel-mvel which implements the Mvel language.

Samples

Loading script from external resource

Available as of Camel 2.11

You can externalize the script and have Camel load it from a resource such as "classpath:", "file:", or "http:". This is done using the following syntax: "resource:scheme:location", eg to refer to a file on the classpath you can do:

Dependencies

To use OGNL in your camel routes you need to add the a dependency on camel-ognl which implements the OGNL language.

Property Expression Language

The Property Expression Language allows you to extract values of named exchange properties.

From Camel 2.15 onwards the property language has been renamed to exchangeProperty to avoid ambiguity, confusion and clash with properties as a general term. So use exchangeProperty instead of property when using Camel 2.15 onwards.

Example usage

The recipientList element of the Spring DSL can utilize a property expression like:

In this case, the list of recipients are contained in the property 'myProperty'.

And the same example in Java DSL:

And with a slightly different syntax where you use the builder to the fullest (i.e. avoid using parameters but using stacked operations, notice that property is not a parameter but a stacked method call)

Dependencies

The Property language is part of camel-core.

Scripting Languages

Camel supports a number of scripting languages which can be used to create an Expression or Predicate via the standard JSR 223 which is a standard part of Java 6.

The following scripting languages are integrated into the DSL:

Language

DSL keyword

EL

el

Groovy

groovy

JavaScript

javaScript

JoSQL

sql

JXPath

jxpath

MVEL

mvel

OGNL

ognl

PHP

php

Python

python

Ruby

ruby

XPath

xpath

XQuery

xquery

However any JSR 223 scripting language can be used using the generic DSL methods.

ScriptContext Options

The JSR-223 scripting language's ScriptContext is pre-configured with the following attributes all set at ENGINE_SCOPE.

Attribute

Type

Value

camelContext

org.apache.camel.CamelContext

The Camel Context.

context

org.apache.camel.CamelContext

The Camel Context (cannot be used in groovy).

exchange

org.apache.camel.Exchange

The current Exchange.

properties

org.apache.camel.builder.script.PropertiesFunction

Camel 2.9: Function with a resolve method to make it easier to use Camels Properties component from scripts. See further below for example.

request

org.apache.camel.Message

The IN message.

response

org.apache.camel.Message

Deprecated: The OUT message. The OUT message is null by default. Use the IN message instead.

Passing Additional Arguments to the ScriptingEngine

You can provide additional arguments to the ScriptingEngine using a header on the Camel message with the key CamelScriptArguments.

Example:

Using Properties Function

Available from Camel 2.9

If you need to use the Properties component from a script to lookup property placeholders, then its a bit cumbersome to do so. For example, to set a header name myHeader with a value from a property placeholder, whose key is taken from a header named foo.

From Camel 2.9: you can now use the properties function and the same example is simpler:

Loading Script From External Resource

Available from Camel 2.11

You can externalize the script and have Camel load it from a resource such as classpath:, file:, or http:. This is done using the following syntax: resource:scheme:location e.g. to refer to a file on the classpath you can do:

How to Get the Result from Multiple Statements Script

Available from Camel 2.14

The script engine's eval method returns a null when it runs a multi-statement script. However, Camel can look up the value of a script's result by using the key result from the value set. When writing a multi-statement script set the value of the result variable as the script return value.

Dependencies

To use scripting languages in your camel routes you need to add the a dependency on camel-script which integrates the JSR-223 scripting engine.

Passing Additional Arguments to the ScriptingEngine

You can provide additional arguments to the ScriptingEngine using a header on the Camel message with the key CamelScriptArguments.

Example:

Using Properties Function

Available from Camel 2.9

If you need to use the Properties component from a script to lookup property placeholders, then its a bit cumbersome to do so. For example, to set a header name myHeader with a value from a property placeholder, whose key is taken from a header named foo.

From Camel 2.9: you can now use the properties function and the same example is simpler:

Loading Script From External Resource

Available from Camel 2.11

You can externalize the script and have Camel load it from a resource such as classpath:, file:, or http:. This is done using the following syntax: resource:scheme:location e.g. to refer to a file on the classpath you can do:

How to Get the Result from Multiple Statements Script

Available from Camel 2.14

The script engine's eval method returns a null when it runs a multi-statement script. However, Camel can look up the value of a script's result by using the key result from the value set. When writing a multi-statement script set the value of the result variable as the script return value.

Dependencies

To use scripting languages in your camel routes you need to add the a dependency on camel-script which integrates the JSR-223 scripting engine.

Passing Additional Arguments to the ScriptingEngine

You can provide additional arguments to the ScriptingEngine using a header on the Camel message with the key CamelScriptArguments.

Example:

Using Properties Function

Available from Camel 2.9

If you need to use the Properties component from a script to lookup property placeholders, then its a bit cumbersome to do so. For example, to set a header name myHeader with a value from a property placeholder, whose key is taken from a header named foo.

From Camel 2.9: you can now use the properties function and the same example is simpler:

Loading Script From External Resource

Available from Camel 2.11

You can externalize the script and have Camel load it from a resource such as classpath:, file:, or http:. This is done using the following syntax: resource:scheme:location e.g. to refer to a file on the classpath you can do:

How to Get the Result from Multiple Statements Script

Available from Camel 2.14

The script engine's eval method returns a null when it runs a multi-statement script. However, Camel can look up the value of a script's result by using the key result from the value set. When writing a multi-statement script set the value of the result variable as the script return value.

Dependencies

To use scripting languages in your camel routes you need to add the a dependency on camel-script which integrates the JSR-223 scripting engine.

Dependency

You should add the camel-groovy dependeny when using Groovy language with Camel. The generic camel-script is not optimized for best Groovy experience, and hence you should add camel-groovy as dependency.

Customizing Groovy Shell

Sometimes you may need to use custom GroovyShell instance in your Groovy expressions. To provide custom GroovyShell, add implementation of the org.apache.camel.language.groovy.GroovyShellFactory SPI interface to your Camel registry. For example after adding the following bean to your Spring context...

Passing Additional Arguments to the ScriptingEngine

You can provide additional arguments to the ScriptingEngine using a header on the Camel message with the key CamelScriptArguments.

Example:

Using Properties Function

Available from Camel 2.9

If you need to use the Properties component from a script to lookup property placeholders, then its a bit cumbersome to do so. For example, to set a header name myHeader with a value from a property placeholder, whose key is taken from a header named foo.

From Camel 2.9: you can now use the properties function and the same example is simpler:

Loading Script From External Resource

Available from Camel 2.11

You can externalize the script and have Camel load it from a resource such as classpath:, file:, or http:. This is done using the following syntax: resource:scheme:location e.g. to refer to a file on the classpath you can do:

How to Get the Result from Multiple Statements Script

Available from Camel 2.14

The script engine's eval method returns a null when it runs a multi-statement script. However, Camel can look up the value of a script's result by using the key result from the value set. When writing a multi-statement script set the value of the result variable as the script return value.

Dependencies

To use scripting languages in your camel routes you need to add the a dependency on camel-script which integrates the JSR-223 scripting engine.

Passing Additional Arguments to the ScriptingEngine

You can provide additional arguments to the ScriptingEngine using a header on the Camel message with the key CamelScriptArguments.

Example:

Using Properties Function

Available from Camel 2.9

If you need to use the Properties component from a script to lookup property placeholders, then its a bit cumbersome to do so. For example, to set a header name myHeader with a value from a property placeholder, whose key is taken from a header named foo.

From Camel 2.9: you can now use the properties function and the same example is simpler:

Loading Script From External Resource

Available from Camel 2.11

You can externalize the script and have Camel load it from a resource such as classpath:, file:, or http:. This is done using the following syntax: resource:scheme:location e.g. to refer to a file on the classpath you can do:

How to Get the Result from Multiple Statements Script

Available from Camel 2.14

The script engine's eval method returns a null when it runs a multi-statement script. However, Camel can look up the value of a script's result by using the key result from the value set. When writing a multi-statement script set the value of the result variable as the script return value.

Dependencies

To use scripting languages in your camel routes you need to add the a dependency on camel-script which integrates the JSR-223 scripting engine.

Passing Additional Arguments to the ScriptingEngine

You can provide additional arguments to the ScriptingEngine using a header on the Camel message with the key CamelScriptArguments.

Example:

Using Properties Function

Available from Camel 2.9

If you need to use the Properties component from a script to lookup property placeholders, then its a bit cumbersome to do so. For example, to set a header name myHeader with a value from a property placeholder, whose key is taken from a header named foo.

From Camel 2.9: you can now use the properties function and the same example is simpler:

Loading Script From External Resource

Available from Camel 2.11

You can externalize the script and have Camel load it from a resource such as classpath:, file:, or http:. This is done using the following syntax: resource:scheme:location e.g. to refer to a file on the classpath you can do:

How to Get the Result from Multiple Statements Script

Available from Camel 2.14

The script engine's eval method returns a null when it runs a multi-statement script. However, Camel can look up the value of a script's result by using the key result from the value set. When writing a multi-statement script set the value of the result variable as the script return value.

Dependencies

To use scripting languages in your camel routes you need to add the a dependency on camel-script which integrates the JSR-223 scripting engine.

Passing Additional Arguments to the ScriptingEngine

You can provide additional arguments to the ScriptingEngine using a header on the Camel message with the key CamelScriptArguments.

Example:

Using Properties Function

Available from Camel 2.9

If you need to use the Properties component from a script to lookup property placeholders, then its a bit cumbersome to do so. For example, to set a header name myHeader with a value from a property placeholder, whose key is taken from a header named foo.

From Camel 2.9: you can now use the properties function and the same example is simpler:

Loading Script From External Resource

Available from Camel 2.11

You can externalize the script and have Camel load it from a resource such as classpath:, file:, or http:. This is done using the following syntax: resource:scheme:location e.g. to refer to a file on the classpath you can do:

How to Get the Result from Multiple Statements Script

Available from Camel 2.14

The script engine's eval method returns a null when it runs a multi-statement script. However, Camel can look up the value of a script's result by using the key result from the value set. When writing a multi-statement script set the value of the result variable as the script return value.

Dependencies

To use scripting languages in your camel routes you need to add the a dependency on camel-script which integrates the JSR-223 scripting engine.

Simple Expression Language

The Simple Expression Language was a really simple language when it was created, but has since grown more powerful. It is primarily intended for being a really small and simple language for evaluating Expressions and Predicates without requiring any new dependencies or knowledge of XPath; so it is ideal for testing in camel-core. The idea was to cover 95% of the common use cases when you need a little bit of expression based script in your Camel routes.

However for much more complex use cases you are generally recommended to choose a more expressive and powerful language such as:

Deprecated: The ${ } placeholders can be omitted if the expression starts with the token, or if the token is only itself.

Alternative syntax

From Camel 2.5 you can also use the alternative syntax which uses $simple{ } as placeholders. This can be used in situations to avoid clashes when using for example Spring property placeholder together with Camel.

Configuring result type

From Camel 2.8 you can configure the result type of the Simple expression. For example to set the type as a java.lang.Boolean or a java.lang.Integer etc.

File language is now merged with Simple language

From Camel 2.2, the File Language is now merged with Simple language which means you can use all the file syntax directly within the simple language.

Simple Language Changes in Camel 2.9 onwards

The Simple language have been improved from Camel 2.9 to use a better syntax parser, which can do index precise error messages, so you know exactly what is wrong and where the problem is. For example if you have made a typo in one of the operators, then previously the parser would not be able to detect this, and cause the evaluation to be true. There are a few changes in the syntax which are no longer backwards compatible. When using Simple language as a Predicate then the literal text must be enclosed in either single or double quotes. For example: "${body} == 'Camel'". Notice how we have single quotes around the literal. The old style of using "body" and "header.foo" to refer to the message body and header is @deprecated, and it is encouraged to always use ${ } tokens for the built-in functions. The range operator now requires the range to be in single quote as well as shown: "${header.zip} between '30000..39999'".

To get the body of the in message: body, or in.body or ${body}.

A complex expression must use ${ } placeholders, such as: Hello ${in.header.name} how are you?.

You can have multiple functions in the same expression: "Hello ${in.header.name} this is ${in.header.me} speaking". However you can not nest functions in Camel 2.8.x or older e.g., having another ${ } placeholder in an existing, is not allowed. From Camel 2.9 you can nest functions.

Refer to the exception.message on the exchange, is null if no exception set on exchange. Will fallback and grab caught exceptions (Exchange.EXCEPTION_CAUGHT) if the Exchange has any.

exception.stacktrace

String

Camel 2.6. Refer to the exception.stracktrace on the exchange. Result is null if no exception set on exchange. Will fallback and grab caught exceptions (Exchange.EXCEPTION_CAUGHT) if the Exchange has any.

Camel 2.11: To refer to a type or field by its FQN name. To refer to a field you can append .FIELD_NAME. For example you can refer to the constant field from Exchange as: org.apache.camel.Exchange.FILE_NAME

Camel 2.17: The collate function iterates the message body and groups the data into sub lists of specified size. This can be used with the Splitter EIP to split a message body and group/batch the split sub messages into a group of N sub lists. This method works similar to the collate method in Groovy.

messageHistory

String

Camel 2.17: The message history of the current exchange how it has been routed. This is similar to the route stack-trace message history the error handler logs in case of an un-handled exception.

messageHistory(false)

String

Camel 2.17:As messageHistory but without the exchange details (only includes the route strack-trace). This can be used if you do not want to log sensitive data from the message itself.

OGNL expression support

Available as of Camel 2.3

Camel's OGNL support is for invoking methods only. You cannot access fields. From Camel 2.11.1 onwards we added special support for accessing the length field of Java arrays.

The Simple and Bean language now supports a Camel OGNL notation for invoking beans in a chain like fashion. Suppose the Message IN body contains a POJO which has a getAddress() method.

Then you can use Camel OGNL notation to access the address object:

Camel understands the shorthand names for accessors, but you can invoke any method or use the real name such as:

You can also use the null safe operator (?.) to avoid NPE if for example the body does not have an address

It is also possible to index in Map or List types, so you can do:

To assume the body is Map based and lookup the value with foo as key, and invoke the getName method on that value.

If the key has space, then you must enclose the key with quotes, for example:

You can access the Map or List objects directly using their key name (with or without dots) :

Suppose there was no value with the key foo then you can use the null safe operator to avoid the NPE as shown:

You can also access List types, for example to get lines from the address you can do:

There is a special last keyword which can be used to get the last value from a list.

And to get the 2nd last you can subtract a number, so we can use last-1 to indicate this:

And the 3rd last is of course:

And you can call the size method on the list with

From Camel 2.11.1 we added support for the length field for Java arrays as well, eg:

And yes you can combine this with the operator support as shown below:

Operator Support

The parser is limited to only support a single operator. To enable it the left value must be enclosed in ${ }.

The syntax is:

Where the rightValue can be a String literal enclosed in ' ', null, a constant value or another expression enclosed in ${}.

Important

There must be spaces around the operator.

Camel will automatically type convert the rightValue type to the leftValue type, so it is possible to for example, convert a string into a numeric so you can use > comparison for numeric values.

Note: from Camel 2.11, the escape character is no longer supported. It has been replaced with the following three escape sequences.

\n

Camel 2.11: To use newline character.

\t

Camel 2.11: To use tab character.

\r

Camel 2.11: To use carriage return character.

\}

Camel 2.18: To use the } character as text.

And the following logical operators can be used to group expressions:

Operator

Description

and

Deprecated use && instead. The logical and operator is used to group two expressions.

or

Deprecated use || instead. The logical or operator is used to group two expressions.

&&

Camel 2.9: The logical and operator is used to group two expressions.

||

Camel 2.9: The logical or operator is used to group two expressions.

Using and,or operators

In Camel 2.4 and older the and or or can only be used once in a simple language expression. From Camel 2.5: you can use these operators multiple times.

The syntax for AND is:

And the syntax for OR is:

Some examples:

Comparing with different types

When you compare with different types such as String and int, then you have to take a bit care. Camel will use the type from the left hand side as first priority. And fallback to the right hand side type if both values couldn't be compared based on that type. This means you can flip the values to enforce a specific type. Suppose the bar value above is a String. Then you can flip the equation:

which then ensures the int type is used as first priority.

This may change in the future if the Camel team improves the binary comparison operations to prefer numeric types over String based. It's most often the String type which causes problem when comparing with numbers.

And a bit more advanced example where the right value is another expression,

And an example with contains, testing if the title contains the word Camel

And an example with regex, testing if the number header is a four digit value:

And finally an example if the header equals any of the values in the list. Each element must be separated by comma, and no space around. This also works for numbers etc, as Camel will convert each element into the type of the left hand side.

And for all the last three we also support the negate test using not:

And you can test if the type is a certain instance, e.g., for instance a String:

We have added a shorthand for all java.lang types so you can write it as:

Ranges are also supported. The range interval requires numbers and both from and end are inclusive. For instance to test whether a value is between 100 and 199:

Notice we use .. in the range without spaces. It is based on the same syntax as Groovy.

From Camel 2.9 onwards the range value must be in single quotes:

Can be used in Spring XML

As the Spring XML does not have all the power as the Java DSL with all its various builder methods, you have to resort to use some other languages for testing with simple operators. Now you can do this with the simple language. In the sample below we want to test if the header is a widget order:

Using and / or

If you have two expressions you can combine them with the and or or operator.

Camel 2.9 onwards

Use && or ||

For instance:

And of course the or is also supported. The sample would be:

Note: currently and or or can only be used once in a simple language expression. This might change in the future. So you cannot do:

Samples

In the Spring XML sample below we filter based on a header value:

The Simple language can be used for the predicate test above in the Message Filter pattern, where we test if the in message has a foo header (a header with the key foo exists). If the expression evaluates to true then the message is routed to the mock:fooOrders endpoint, otherwise it is lost in the deep blue sea .

The same example in Java DSL:

You can also use the simple language for simple text concatenations such as:

Notice that we must use ${ } placeholders in the expression now to allow Camel to parse it correctly.

And this sample uses the date command to output current date.

And in the sample below we invoke the bean language to invoke a method on a bean to be included in the returned string:

Where orderIdGenerator is the id of the bean registered in the Registry. If using Spring then it is the Spring bean id.

If we want to declare which method to invoke on the order id generator bean we must prepend .method name such as below where we invoke the generateId method.

We can use the ?method=methodname option that we are familiar with the Bean component itself:

And from Camel 2.3 you can also convert the body to a given type, for example to ensure that it is a String you can do:

There are a few types which have a shorthand notation, so we can use String instead of java.lang.String. These are: byte[], String, Integer, Long. All other types must use their FQN name, e.g. org.w3c.dom.Document.

It is also possible to lookup a value from a header Map in Camel 2.3:

In the code above we lookup the header with name type and regard it as a java.util.Map and we then lookup with the key gold and return the value. If the header is not convertible to Map an exception is thrown. If the header with name type does not exist null is returned.

Referring to Constants or Enums

Using New Lines or Tabs in XML DSLs

Available as of Camel 2.9.3

From Camel 2.9.3 it is easier to specify new lines or tabs in XML DSLs as you can escape the value now

Leading and Trailing Whitespace Handling

Available as of Camel 2.10.0

From Camel 2.10.0, the trim attribute of the expression can be used to control whether the leading and trailing whitespace characters are removed or preserved. The default value is true, which removes the whitespace characters.

Setting the Result Type

Available as of Camel 2.8

You can now provide a result type to the Simple expression, which means the result of the evaluation will be converted to the desired type. This is most usable to define types such as boolean's, integer's, etc.

For example to set a header as a boolean type you can do:

And in XML DSL

Changing Function Start and End Tokens

Available as of Camel 2.9.1

You can configure the function start and end tokens - ${ } using the setters changeFunctionStartToken and changeFunctionEndToken on SimpleLanguage, using Java code. From Spring XML you can define a <bean> tag with the new changed tokens in the properties as shown below:

In the example above we use [] as the changed tokens. Notice by changing the start/end token you change those in all the Camel applications which share the same camel-core on their classpath. For example in an OSGi server this may affect many applications, where as a Web Application as a WAR file it only affects the Web Application.

Loading Script from External Resource

Available as of Camel 2.11

You can externalize the script and have Camel load it from a resource such as: classpath:, file:, or http:. This is done using the following syntax: resource:scheme:location, e.g., to refer to a file on the classpath you can do:

Setting Spring beans to Exchange properties

Dependencies

File Expression Language

File language is now merged with Simple language

From Camel 2.2: the file language is now merged with Simple language which means you can use all the file syntax directly within the simple language.

The File Expression Language is an extension to the Simple language, adding file related capabilities. These capabilities are related to common use cases working with file path and names. The goal is to allow expressions to be used with the File and FTP components for setting dynamic file patterns for both consumer and producer.

Syntax

This language is an extension to the Simple language so the Simple syntax applies also. So the table below only lists the additional. By contrast to the Simple language, the File Language also supports the use of Constant expressions to enter a fixed filename, for example.

All the file tokens use the same expression name as the method on the java.io.File object. For example: file:absolute refers to the java.io.File.getAbsolute() method.

Note: not all expressions are supported by the current Exchange. For example, the FTP component supports some of the options, whereas the File component supports all of them.

Expression

Type

File Consumer

File Producer

FTP Consumer

FTP Producer

Description

date:command:pattern

String

yes

yes

yes

yes

For date formatting using the java.text.SimpleDateFormat patterns which is an extension to the Simple language.

Additional command is: file (consumers only) for the last modified timestamp of the file.

Refers to the file name (is relative to the starting directory, see note below).

file:name.ext

String

yes

no

yes

no

Camel 2.3: refers to the file extension only.

file:name.ext.single

String

yes

no

yes

no

Camel 2.14.4/2.15.3: refers to the file extension. If the file extension has multiple dots, then this expression strips and only returns the last part.

file:name.noext

String

yes

no

yes

no

Refers to the file name with no extension (is relative to the starting directory, see note below).

file:name.noext.single

String

yes

no

yes

no

Camel 2.14.4/2.15.3:refers to the file name with no extension (is relative to the starting directory, see note below). If the file extension has multiple dots, then this expression strips only the last part, and keep the others.

file:onlyname

String

yes

no

yes

no

Refers to the file name only with no leading paths.

file:onlyname.noext

String

yes

no

yes

no

Refers to the file name only with no extension and with no leading paths.

file:onlyname.noext.single

String

yes

no

yes

no

Camel 2.14.4/2.15.3: refers to the file name only with no extension and with no leading paths. If the file extension has multiple dots, then this expression strips only the last part, and keep the others.

file:parent

String

yes

no

yes

no

Refers to the file parent.

file:path

String

yes

no

yes

no

Refers to the file path.

file:size

Long

yes

no

yes

no

Camel 2.5: refers to the file length returned as a Long type.

File Token Example

Relative Paths

We have a java.io.File handle for the file hello.txt in the following relative directory: .\filelanguage\test. And we configure our endpoint to use this starting directory .\filelanguage.

The file tokens returned are:

Expression

Returns

file:absolute

false

file:absolute.path

\workspace\camel\camel-core\target\filelanguage\test\hello.txt

file:ext

txt

file:name

test\hello.txt

file:name.ext

txt

file:name.noext

test\hello

file:onlyname

hello.txt

file:onlyname.noext

hello

file:parent

filelanguage\test

file:path

filelanguage\test\hello.txt

Absolute Paths

We have a java.io.File handle for the file hello.txt in the following absolute directory: \workspace\camel\camel-core\target\filelanguage\test. And we configure out endpoint to use the absolute starting directory: \workspace\camel\camel-core\target\filelanguage.

Examples

Lets assume we use the file consumer to read files and want to move the read files to backup folder with the current date as a sub folder. This can be achieved using an expression like:

relative folder names are also supported so suppose the backup folder should be a sibling folder then you can append .. as:

As this is an extension to the Simple language we have access to all the goodies from this language also, so in this use case we want to use the in.header.type as a parameter in the dynamic expression:

If you have a custom Date you want to use in the expression then Camel supports retrieving dates from the message header.

And finally we can also use a bean expression to invoke a POJO class that generates some String output (or convertible to String) to be used:

And of course all this can be combined in one expression where you can use the File Language, Simple and the Bean language in one combined expression. This is pretty powerful for those common file path patterns.

In Camel you can use the File Language directly from the Simple language which makes a Content Based Router easier to do in Spring XML, where we can route based on file extensions as shown below:

If you use the fileName option on the File endpoint to set a dynamic filename using the File Language then make sure you use the alternative syntax (available from Camel 2.5) to avoid clashing with Spring's PropertyPlaceholderConfigurer.

bundle-context.xml

bundle-context.cfg

Notice how we use the $simple{} syntax in the toEndpoint above. If you don't do this, they will clash and Spring will throw an exception:

Dependencies

The File language is part of camel-core.

SQL Language

The SQL support is added by JoSQL and is primarily used for performing SQL queries on in-memory objects. If you prefer to perform actual database queries then check out the JPA component.

Looking for the SQL component

Camel has both a SQL language and a SQL Component. This page is about the SQL language. Click on SQL Component if you are looking for the component instead.

To use SQL in your camel routes you need to add the a dependency on camel-josql which implements the SQL language.

Loading script from external resource

Available as of Camel 2.11

You can externalize the script and have Camel load it from a resource such as "classpath:", "file:", or "http:". This is done using the following syntax: "resource:scheme:location", eg to refer to a file on the classpath you can do:

If the message body is stream based, which means the input is received by Camel as a stream, then you will only be able to read the content of the stream once. Oftentimes when using XPath as Message Filter or Content Based Router the data will be accessed multiple times. Therefore use Stream caching or convert the message body to a String beforehand. This makes it safe to be re-read multiple times.

Namespaces

You can easily use namespaces with XPath expressions using the Namespaces helper class.

Namespace Given

If the namespace is given then Camel is instructed exactly what to return. However when resolving either IN or OUT Camel will try to resolve a header with the given local part first, and return it. If the local part has the value body then the body is returned instead.

No Namespace Given

If there is no namespace given then Camel resolves only based on the local part. Camel will try to resolve a variable in the following steps:

From variables that has been set using the variable(name, value) fluent builder.

From message.in.header if there is a header with the given key.

From exchange.properties if there is a property with the given key.

Functions

Camel adds the following XPath functions that can be used to access the exchange:

Function

Argument

Type

Description

in:body

none

Object

Will return the IN message body.

in:header

the header name

Object

Will return the IN message header.

out:body

none

Object

Will return the OUT message body.

out:header

the header name

Object

Will return the OUT message header.

function:properties

key for property

String

Camel 2.5: To lookup a property using the Properties component (property placeholders).

Note: function:properties and function:simple is not supported when the return type is a NodeSet, such as when using with a Splitter EIP.

Here's an example showing some of these functions in use.

And the new functions introduced in Camel 2.5:

Using XML Configuration

If you prefer to configure your routes in your Spring XML file then you can use XPath expressions as follows

Notice how we can reuse the namespace prefixes, foo in this case, in the XPath expression for easier namespace based XPath expressions! See also this discussion on the mailinglist about using your own namespaces with XPath.

Setting the Result Type

The XPath expression will return a result type using native XML objects such as org.w3c.dom.NodeList. But many times you want a result type to be a String. To do this you have to instruct the XPath which result type to use.

In Java DSL:

In Spring DSL you use the resultType attribute to provide a fully qualified classname:

In @XPath:Available as of Camel 2.1

Where we use the XPath function concat to prefix the order name with foo-. In this case we have to specify that we want a String as result type so the concat function works.

Using XPath on Headers

Available as of Camel 2.11

Some users may have XML stored in a header. To apply an XPath statement to a header's value you can do this by defining the headerName attribute.

In XML DSL:

And in Java DSL you specify the headerName as the 2nd parameter as shown:

Examples

If you have a standard set of namespaces you wish to work with and wish to share them across many different XPath expressions you can use the NamespaceBuilder as shown in this example

In this sample we have a choice construct. The first choice evaulates if the message has a header key type that has the value Camel. The 2nd choice evaluates if the message body has a name tag <name> which values is Kong. If neither is true the message is routed in the otherwise block:

And the spring XML equivalent of the route:

XPath Injection

You can use Bean Integration to invoke a method on a bean and use various languages such as XPath to extract a value from the message and bind it to a method parameter.

The default XPath annotation has SOAP and XML namespaces available. If you want to use your own namespace URIs in an XPath expression you can use your own copy of the XPath annotation to create whatever namespace prefixes you want to use.

e.g., cut and paste upper code to your own project in a different package and/or annotation name then add whatever namespace prefix/URIs you want in scope when you use your annotation on a method parameter. Then when you use your annotation on a method parameter all the namespaces you want will be available for use in your XPath expression.

Example:

Using XPathBuilder Without an Exchange

Available as of Camel 2.3

You can now use the org.apache.camel.builder.XPathBuilder without the need for an Exchange. This comes handy if you want to use it as a helper to do custom XPath evaluations. It requires that you pass in a CamelContext since a lot of the moving parts inside the XPathBuilder requires access to the Camel Type Converter and hence why CamelContext is needed.

For example you can do something like this:

This will match the given predicate.

You can also evaluate for example as shown in the following three examples:

Evaluating with a String result is a common requirement and thus you can do it a bit simpler:

Using Saxon with XPathBuilder

Available as of Camel 2.3

You need to add camel-saxon as dependency to your project. It's now easier to use Saxon with the XPathBuilder which can be done in several ways as shown below. Where as the latter ones are the easiest ones.

Camel will log at INFO level if it uses a non default XPathFactory such as:

To use Apache Xerces you can configure the system property:

Enabling Saxon from Spring DSL

Available as of Camel 2.10

Similarly to Java DSL, to enable Saxon from Spring DSL you have three options:

Specifying the factory

Specifying the object model

Shortcut

Namespace Auditing to Aid Debugging

Available as of Camel 2.10

A large number of XPath-related issues that users frequently face are linked to the usage of namespaces. You may have some misalignment between the namespaces present in your message and those that your XPath expression is aware of or referencing. XPath predicates or expressions that are unable to locate the XML elements and attributes due to namespaces issues may simply look like "they are not working", when in reality all there is to it is a lack of namespace definition.

Namespaces in XML are completely necessary, and while we would love to simplify their usage by implementing some magic or voodoo to wire namespaces automatically, truth is that any action down this path would disagree with the standards and would greatly hinder interoperability.

Therefore, the utmost we can do is assist you in debugging such issues by adding two new features to the XPath Expression Language and are thus accessible from both predicates and expressions.

Logging the Namespace Context of Your XPath Expression/Predicate

Every time a new XPath expression is created in the internal pool, Camel will log the namespace context of the expression under the org.apache.camel.builder.xml.XPathBuilder logger. Since Camel represents Namespace Contexts in a hierarchical fashion (parent-child relationships), the entire tree is output in a recursive manner with the following format:

Any of these options can be used to activate this logging:

Enable TRACE logging on the org.apache.camel.builder.xml.XPathBuilder logger, or some parent logger such as org.apache.camel or the root logger.

Enable the logNamespaces option as indicated in Auditing Namespaces, in which case the logging will occur on the INFO level.

Auditing namespaces

Camel is able to discover and dump all namespaces present on every incoming message before evaluating an XPath expression, providing all the richness of information you need to help you analyse and pinpoint possible namespace issues. To achieve this, it in turn internally uses another specially tailored XPath expression to extract all namespace mappings that appear in the message, displaying the prefix and the full namespace URI(s) for each individual mapping.

Some points to take into account:

The implicit XML namespace (xmlns:xml="http://www.w3.org/XML/1998/namespace") is suppressed from the output because it adds no value.

Default namespaces are listed under the DEFAULT keyword in the output.

Keep in mind that namespaces can be remapped under different scopes. Think of a top-level 'a' prefix which in inner elements can be assigned a different namespace, or the default namespace changing in inner scopes. For each discovered prefix, all associated URIs are listed.

You can enable this option in Java DSL and Spring DSL.

Java DSL:

Spring DSL:

The result of the auditing will be appear at the INFO level under the org.apache.camel.builder.xml.XPathBuilder logger and will look like the following:

Loading Script from External Resource

Available as of Camel 2.11

You can externalize the script and have Camel load it from a resource such as: classpath:, file: or http:. This is done using the following syntax: resource:scheme:location, e.g., to refer to a file on the classpath you can do:

Options

Name

Default Value

Description

allowStAX

false

Camel 2.8.3/2.9: Whether to allow using StAX as the javax.xml.transform.Source.

Examples

You can also use functions inside your query, in which case you need an explicit type conversion (or you will get a org.w3c.dom.DOMException: HIERARCHY_REQUEST_ERR) by passing the Class as a second argument to the xquery() method.

Variables

The IN message body will be set as the contextItem. Besides this these Variables is also added as parameters:

Variable

Type

Description

exchange

Exchange

The current Exchange

in.body

Object

The In message's body

out.body

Object

The OUT message's body (if any)

in.headers.*

Object

You can access the value of exchange.in.headers with key foo by using the variable which name is in.headers.foo

out.headers.*

Object

You can access the value of exchange.out.headers with key foo by using the variable which name is out.headers.foo variable

key name

Object

Any exchange.properties and exchange.in.headers and any additional parameters set using setParameters(Map). These parameters is added with they own key name, for instance if there is an IN header with the key name foo then its added as foo.

Using XML configuration

If you prefer to configure your routes in your Spring XML file then you can use XPath expressions as follows

Notice how we can reuse the namespace prefixes, foo in this case, in the XPath expression for easier namespace based XQuery expressions!

When you use functions in your XQuery expression you need an explicit type conversion which is done in the xml configuration via the @type attribute:

Using XQuery as transformation

We can do a message translation using transform or setBody in the route, as shown below:

Notice that xquery will use DOMResult by default, so if we want to grab the value of the person node, using text() we need to tell xquery to use String as result type, as shown:

Using XQuery as an endpoint

Sometimes an XQuery expression can be quite large; it can essentally be used for Templating. So you may want to use an XQuery Endpoint so you can route using XQuery templates.

The following example shows how to take a message of an ActiveMQ queue (MyQueue) and transform it using XQuery and send it to MQSeries.

Loading script from external resource

Available as of Camel 2.11

You can externalize the script and have Camel load it from a resource such as "classpath:", "file:", or "http:". This is done using the following syntax: "resource:scheme:location", eg to refer to a file on the classpath you can do:

Dependencies

To use XQuery in your camel routes you need to add the a dependency on camel-saxon which implements the XQuery language.