How to use Camel utilities in routes

This page lists Camel utility expressions that can help you perform basic common tasks. For instance, these expressions can format dates or generate random numbers.

Expressions

The expression are used whenever a value is needed. For instance it can be used in <setBody> or <setHeader> tags.

<u:date-add>

Description Add a number of periods to a date
Usage Examples
date-add
<!-- Remove one day from now -->
<u:date-add type="days" scalar="-1" date="NOW" />
 
<!-- Remove one day from the given date -->
<u:date-add type="days" scalar="-1">
	<u:date>
		<!-- Expression to use in order to retrieve the date -->
		<simple>${body[date]}</simple>
	</u:date>
</u:date-add>
 
<!-- Remove any number of days from the given date -->
<u:date-add type="days">
	<u:date>
		<!-- Expression to use in order to retrieve the date -->
		<simple>${body[date]}</simple>
	</u:date>
	<u:scalar>
		<!-- Expression to use in order to retrieve the number of days -->
		<simple>${body[dateShift]}</simple>
	</u:scalar>
</u:date-add>
Attributes type (required): The duration type, see reference values .
scalar (can use nested element instead): The number of period to add, must be an integer. If the value is null or an empty string, then the given date remains unchanged.
date (can use nested element instead): The reference date. This value must be one of the reference values . If the value is null or an empty string, then it returns null.
Nested elements <u:scalar> (can use attribute instead): The number of period to add, must be an integer. This nested element must contains a single expression in order to retrieve the value. If the value is null or an empty string, then the given date remains unchanged.
<u:date> (can used attribute instead): The reference date. This nested element must contains a single expression in order to retrieve the date. If the value is null or an empty string, then it returns null.
Return type org.joda.time.ReadableInstant (can be converted to java.util.Date or Long)

<u:date-format>

Description Format a date into a string according the given format
Usage Examples
date-format
<!-- Format the given date -->
<u:date-format pattern="yyyy-MM-dd 'at' HH:mm:ss.SSS Z">
	<!-- Expression to use in order to retrieve the date -->
	<simple>${body[date]}</simple>
</u:date-format>

<!-- Format the given date having the month as plain text with timezone and locale -->
<u:date-format pattern="dd MMMM yyyy" tz="UTC" locale="FR_FR">
	<!-- Expression to use in order to retrieve the date -->
	<simple>${body[date]}</simple>
</u:date-format>
Attributes pattern (required): The format pattern of the date, see reference values .
tz (optional): The timezone to use, see reference values .
locale (optional): The locale to use, see reference values . For instance, it allows to use the names of monthes instead of their number, or the names of days.
useOldFormatter (optional): set to true to use java date format  . Default is joda date format.
Nested elements A single expression in order to retrieve the date to format. The date to use, see Date parsing values.
Return type String

<u:date-parse> 

Description Parse a string date using the given format
Usage Examples
date-parse
<!-- Parse the given date -->
<u:date-parse pattern="yyyy-MM-dd 'at' HH:mm:ss.SSS">
	<!-- Expression to use in order to retrieve the date -->
	<simple>${body[date]}</simple>
</u:date-parse>

<!-- Parse the given date having the month as plain text with timezone and locale -->
<u:date-parse pattern="dd MMMM yyyy" tz="UTC" locale="FR_FR">
	<!-- Expression to use in order to retrieve the date -->
	<simple>${body[date]}</simple>
</u:date-parse>

<!-- Parse the given date having the month as plain text with dynamic timezone and locale -->
<u:date-parse pattern="dd MMMM yyyy" locale="FR_FR">
	<!-- Expression to use in order to retrieve the date -->
	<simple>${body[date]}</simple>
	<u:tz>
		<simple>${body[tz]}</simple>
	</u:tz>
</u:date-parse>
Attributes

pattern (required): The format pattern of the date, see reference values .

(warning) Zone names: Time zone names ('z') cannot be parsed - use tz attribute instead.

tz (optional, can use nested element instead): The timezone to use, see reference values .
locale (optional): The locale to use, see reference values . For instance, it allows to use the names of monthes instead of their number, or the names of days.
useOldParser (optional): set to true to use java date format. Default is joda date format.
Nested elements An expression in order to retrieve the date to parse. If the value is null or an empty string, then it returns null.
<u:tz> (optional, can use attribute instead): The timezone to use.
Return type java.util.Date (can be converted to org.joda.time.ReadableInstant)

<u:date-slide>

Description Slide a date starting at now. This is for simulation pupose; if you have a data source with dates in it, it will slide the first date to now and apply the same shift to the other dates.
Usage Examples
date-slide
<!-- Slide the given date -->
<u:date-slide>
	<!-- Expression to use in order to retrieve the date -->	
	<simple>${body[date]}</simple>
</u:date-slide>
Nested elements A single expression in order to retrieve the date to slide. If the value is null or an empty string, then it returns null.
Return type org.joda.time.ReadableInstant (can be converted to java.util.Date or Long)

<u:duration-create>

Description Create a duration given its number of hours, minutes, seconds and milliseconds
Usage Examples
date-add
<!-- Create duration with attributes -->
<u:duration-create hour="6" minute="30" />


<!-- Create duration with nested elements -->
<u:duration-create>
    <u:second>
	    <!-- Expression to use in order to retrieve the number of seconds-->	
	    <simple>${body[second]}</simple>
    </u:second>
</u:duration-create>
Attributes hour   (optional, can use nested element instead) : The number of hours.
minute   (optional, can use nested element instead) : The number of minutes.
second   (optional, can use nested element instead) : The number of seconds.
millis   (optional, can use nested element instead) : The number of milliseconds.
Nested elements <u:hour> (optional, can use attribute instead): The number of hours.
<u:minute>   (optional, can use attribute instead) : The number of minutes.
<u:second>   (optional, can use attribute instead) : The number of seconds.
<u:millis>   (optional, can use attribute instead) : The number of milliseconds.
Return type org.joda.time.ReadableDuration

<u:interval-create>

Description Create an interval based on 2 dates
Usage Examples
date-add
<!-- Create interval -->
<u:interval-create end="NOW">
    <u:begin>
        <simple>${body[begin]}</simple>
    </u:begin>
</u:interval-create>
Attributes begin (can use nested element instead): The begin date of the interval.
end (can use nested element instead): The end date of the interval.
Nested elements <u:begin> (can use attribute instead): The begin date of the interval.
<u:end> (can use attribute instead): The end date of the interval.
Return type org.joda.time.ReadableInterval (can be converted to org.joda.time.ReadableDuration)

<u:number-format>

Description Format the given number into a string.
Usage Examples
number-format
<!-- Format the given number -->
<u:number-format pattern="#,###.00">
	<!-- Expression to use in order to retrieve the number -->
	<simple>${body[amount]}</simple>
</u:number-format>
Attributes pattern (required): The format pattern of the number, reference values .
locale (optional): The locale to use, see reference values . This allows to use the proper decimal separator, thousand separator, money symbol or percent sign.
Nested elements A single expression in order to retrieve the number to format. If the value is null or an empty string, then it returns null .

<u:number-parse>

Description Parse the given string into any number.
Usage Examples
number-parse
<!-- We're parsing PI written in French, thus with comma as decimal separator -->
<u:number-parse locale="FR">
	<constant>3,14</constant>
</u:number-parse>

 
<!-- We're parsing the population of the Falkland Islands written in English, thus with comma as thousand separator -->
<u:number-parse locale="EN">
	<constant>2,563</constant>
</u:number-parse>
 
<!-- Trying to parse the time from a string, it will return 5 -->
<u:number-parse locale="EN" pattern="# o''clock">
	<constant>5 o'clock</constant>
</u:number-parse>
 
<!-- Trying to parse a French percentage, it will return 1.2345 (thus between 1 and 2) -->
<u:number-parse locale="FR" pattern="#%">
	<constant>123,45%</constant>
</u:number-parse>
Attributes locale   (required) : The locale to use, see reference values . It defines the proper decimal separator, thousand separator, money symbol or percent sign that will be used.

pattern (optional): The format pattern of the number, reference values .

Most of the times defining the pattern not necessary. It becomes useful when you tries to parse number in a very complicated format.

It is also important to note that the pattern depends on the locale in order to find the proper symbols.

Nested elements A single expression in order to retrieve the number to parse. If the value is null or an empty string, then it returns null .

<u:number-round>

Description Round a number with a given number of decimals
Usage Examples
number-parse
<!-- Round the number contained into the body with 2 digits  -->
<setBody>
    <u:number-round digits="2">
        <simple>${body}</simple>
    </u:number-round>
</setBody>
Attributes digits (required): the number of digits to keep. Can be zero to round to an integer number.
Nested elements A single expression in order to retrieve the number to round. If the value is null or a not a number, then it returns null.

<u:random-choice>

Description Randomly select one of the expression within. This is used in simulation purpose in order to inject known random values.
Usage Examples
random-choice
<!-- Select the first one 10 times more often than the second one -->
<u:random-choice distributionRatio="10,1">
	<constant>1.4142</constant>
	<constant>3.1416</constant>
</u:random-choice>
Attributes distributionRatio (required): The ratio of each choice separated by commas.
Nested elements The same number of expression that you have distribution ratios. One of this expression will be randomly selected.

<u:random-poisson> 

Description Generate a random number according to the Poisson distribution.
Usage Examples
random-poisson
<!-- Generate a random number -->
<u:random-poisson lambda="5" />
Attributes lambda (required): The lambda value of the Poisson distribution (integer).

<u:random-stddev> 

Description Generate a random number according to the standard deviation.
Usage Examples
random-stddev
<!-- Generate a random number -->
<u:random-stddev mean="17.64" stdDev="12.5" />
Attributes mean (required): The mean value of the standard deviation (decimal)
stdDev (required): The stdDev value of the standard deviation (decimal)

<u:random-uniform> 

Description Generate a random number according to a uniform rule.
Usage Examples
random-uniform
<!-- Generate a random number -->
<u:random-uniform min="5" max="10" />
 
<!-- Generate a random number -->
<u:random-uniform range="10">
	<u:max>
		<simple>${body[max]}</simple>
	</u:max>
</u:random-uniform>
Attributes range (optional, can use nested element instead): The range value of the uniform rule. (integer or decimal) (has to be positive)
integer (optional): Whether or not it should generates an integer, values are: true or false (default value).
min (optional, can use nested element instead): The minimum generated value (inclusive). (integer or decimal)
max (optional, can use nested element instead): The maximum generated value (exclusive). (integer or decimal)
Nested elements <u:range> (optional, can use attribute instead):The range value of the uniform rule. This nested element must contains a single expression in order to retrieve the value. (integer or decimal)
<u:max> (optional, can use attribute instead): The maximum generated value (exclusive). This nested element must contains a single expression in order to retrieve the value. (integer or decimal)
<u:min>   (optional, can use attribute instead) : The minimum generated value (inclusive). This nested element must contains a single expression in order to retrieve the value. (integer or decimal)
Rules Only 2 parameters between range, min and max must be defined.

<u:random-weibull> 

Description Generate a random number according to the Weibull distribution.
Usage Examples
random-weibull
<!-- Generate a random number -->
<u:random-weibull lambda="5" k="0.5" />
Attributes lambda (required): The lamda value of the Weibull distribution (integer)
k (required): The k value of the Weibull distribution (decimal)

<u:string-concat>

Description Concat several string expressions
Usage Examples
string-concat
<!-- Concatenate several string separated by spaces, it will produce "Bond, James Bond" -->
<u:string-concat separator=", ">
	<!-- Expressions to concat -->
	<constant>Bond</constant>
	<constant>James Bond</constant>
</u:string-concat>
Attributes separator (optional): The separator to use between strings
Nested elements Several expression that needs to be concatenated. A null value is equivalent to an empty string.

<u:string-regexp>

Description Extract data from a string using a Regular expression
Usage Examples
string-regexp
<!-- Find the name from a string -->
<u:string-regexp pattern="My name is ([a-zA-Z]*)">
	<constant>My name is Bond</constant>
</u:string-regexp>

Ouput is a List = ["My name is Bond", "Bond"]

string-regexp
<!-- Extract two information to a Map -->
<u:string-regexp useNamedGroups="true" pattern="Entry key=(?&lt;key&gt;.+) value=(?&lt;value&gt;.+)">
    <constant>Entry key=abc value=123</constant>
</u:string-regexp>

Ouput is a Map = {"value"="123", "key"="abc"}

Attributes pattern (required): The pattern of the regular expression

useNamedGroups (optional) :

  • if set to false (default), the result is a List that contains the elements matched by the regular expression. The matched expression is available at index 0 and then the first matched group is available at index 1, the second at 2, etc...
  • if set to true, the result is a Map that uses the group name as key and the corresponding matched element as value. Unnamed groups won't appears in the result.
Nested elements A single expression that defines the string to analyze. If the value is null or an empty string, then it returns null .
Return type If the nested expression match the pattern it returns a Map or a List depending the value of the attribute useNamedGroup. Else it returns null.

<u:extract-vtAxisTransitions>

Description Return a list of transitions from one value to the next along the vt time axis
Usage Examples
extract-vtAxisTransitions
<u:extract-vtAxisTransitions ignoreSuccessiveIdentical="false">
    <simple>body</simple>
</u:extract-vtAxisTransitions>
 
<!-- OR -->
 
<u:extract-vtAxisTransitions ignoreSuccessiveIdentical="false"/>

 
<!-- where in both cases body is an IndicatorUpdateEvent -->
Attributes ignoreSuccessiveIdentical (optional, defaults to false) : discard transitions with previous values same as current
Nested elements

 

Output A Transition object containing the vt, oldValue and newValue properties.

<u:list-create>

Description

Create a list of elements.

The resulting list will be a list of Object items.

Usage Examples
list-create
<!-- Add two elements to a list -->
<u:list-create>
   	<simple resultType="java.lang.Double">10000.00</simple>
	<simple resultType="java.lang.Double">5000.00</simple>
</u:list-create>
Attributes

None

Nested elements  

<u:map-create>

Description Instantiate a map of elements, each of them being available through its key.
Usage Examples
map-create
<u:map-create> <!-- Create a map -->
	<u:map-entry key="ReferenceTime"> <!-- Add an entry "ReferenceTime" -->
			<simple resultType="org.joda.time.ReadableInstant">NOW</simple>   
	</u:map-entry>
</u:map-create>
Attributes None
Nested elements

<u:map-entry> the Key-Value pair that will be inserted in the map.

<u:map-entry>

Description A Key-Value pair to be inserted in a map
Usage Examples
map-entry
<u:map-create> <!-- Create parameters map -->
	<u:map-entry key="ReferenceTime"> <!-- Add an entry "ReferenceTime" -->
			<simple resultType="org.joda.time.ReadableInstant">NOW</simple>   
	</u:map-entry>
</u:map-create>
Attributes key (required, can use nested element instead) The index by which the value will be retrieved.
value (required, can use nested element instead) The object being stored in the map.
Nested elements <u:map-key> (required, can use attributes instead) The index by which the value will be retrieved.

(info) All expressions that are not map-key are assumed to be values.

<u:map-key>

Description Create a key for a map entry
Usage Examples
map-key
<u:map-create> <!-- Create parameters map -->
	<u:map-entry> <!-- Add an entry "ReferenceTime" -->
		<u:map-key>
			<constant>ReferenceTime</constant>
		</u:map-key>
			<simple resultType="org.joda.time.ReadableInstant">NOW</simple>   
	</u:map-entry>
</u:map-create>
Attributes None
Nested elements A single expression to be used as a key for a map entry

<u:random-select>

Description Weight random selection of an element from a list.
Usage Examples
map-key
<u:random-select>
	<u:list>
        <simple>${header[items]}</simple>
    </u:list>
	<u:weight>
        <simple>${body[weight]}</simple>
	</u:weight>
</u:random-select>
Attributes None
Nested elements <u:list> ( required ) single expression to be used as the list of elements
<u:weight> ( optional ) single expression to be used to extract weight from an element. For this expression, body is bind to an element of the list. If this nested element is not set, then every element will have the same weight.

<u:tnd-resource>

Description Load the content of a resource
Usage Examples
tnd-resource
<u:tnd-resource>myResource</u:tnd-resource>
Attributes binary (optional, default is false) Whether or not the resource should be treated as a binary resource and kept as an InputStream

resultType (optional, default is empty) The result type to use for casting the resource content.

Text content The name of the Resource to retrieve

<u:extract-threshold-rule>

Description

Given a map body containing a threshold definition and a value, extract:

  • the classifier corresponding to the value
  • the rule for the higher rank (if any)
  • the rule for the lower rank (if any)
Usage Examples

for the given body map:

extract-threshold-rule input example
{
    "threshold": [
        {
            "classifier": "CRITICAL",
            "classifierRank": 2,
            "threshold": 400,
            "included": false
        },
        {
            "classifier": "WARNING",
            "classifierRank": 1,
            "threshold": 300,
            "included": false
        },
        {
            "classifier": "NORMAL",
            "classifierRank": 0
        }
    ],
    "value": 350
}

invoking the following expression:

extract-threshold-rule command example
<u:extract-threshold-rule valueKey="value" thresholdKey="threshold" />

will output:

extract-threshold-rule output example
{
    "higherRank": {
        "threshold": 400,
        "included": false,
        "classifier": "CRITICAL"
    },
    "lowerRank": {
        "threshold": 300,
        "included": true,
        "classifier": "NORMAL"
    },
    "classifier": "WARNING"
}
Attributes

valueKey (required) The map key containing the value

thresholdKey (required) The map key containing the threshold

Processors

The processors are used within the route process. It's similar to <to> or <split> tags.

<u:setMapValue>

Description

Adds a value into a map. It replaces the existing value if already defined. It throws an exception if it's not a map.

Usage Examples
map-key
<!-- Add a value in the body Map -->
<u:setMapValue key="stepName">
    <simple>myNewStep</simple>
</u:setMapValue>
 
<!-- Add a value in a specified Map -->
<u:setMapValue key="stepName">
    <u:map>
        <simple>${headers.myMap}</simple>
    </u:map>
    <simple>myNewStep</simple>
</u:setMapValue>
Attributes key (required) The key of the value
Nested elements <u:map> (optional) The target Map, it uses the exchange body if not defined.
A required expression for the value

<u:addListItem>

Description

Add one element to an existing list.

Usage Examples
list-create
<!-- Add a number to the body list -->
<u:addListItem>
    <simple resultType="java.lang.Double">555.00</simple>
</u:addListItem>
 
<!-- Add a number to the specified list -->
<u:addListItem>
    <u:list>
        <simple>${header.list}</simple>
    </u:list>
    <simple resultType="java.lang.Double">555.00</simple>
</u:addListItem>
Attributes

None

Nested elements

<u:list> (optional) to specify the target list, addListItem uses the body if not defined

A required expression to specify the value to append to the list


Reference documentation

Duration type values

The possible values for a duration type are:

  • weekyears
  • years
  • months
  • weeks
  • days
  • hours
  • minutes
  • seconds
  • millis

Date parsing values

The possible values for a date are:

  • NOW
  • FROM_START
  • UNTIL_END
  • UNTIL_CHANGED
  • Any string with the given format: yyyy-MM-dd'T'HH:mm:ss.SSSZZ

Date pattern format

See below the list of the pattern characters:

Letter Date or Time Component Presentation Examples
G Era designator Text AD
c century of era Number 20
y Year of era Year 199696
M Month in year Month JulyJul07
w Week in year Number 27
W Week in month Number 2
D Day in year Number 189
d Day in month Number 10
F Day of week in month Number 2
E Day in week Text TuesdayTue
a Am/pm marker Text PM
H Hour in day (0-23) Number 0
k Hour in day (1-24) Number 24
K Hour in am/pm (0-11) Number 0
h Hour in am/pm (1-12) Number 12
m Minute in hour Number 30
s Second in minute Number 55
S Fraction of second Number 978
z Time zone
(warning) Not available for parsing
General time zone Pacific Standard TimePSTGMT-08:00
Z Time zone RFC 822 time zone -0800

Complete reference (when parsing dates using the old parser, use this reference instead)

 

Zone names: Time zone names ('z') cannot be parsed.

Date time zones

The time zone can either be defined with:

  • its abbreviation such as PST
  • its full name such as America/Los_Angeles
  • a custom value like GMT-8:00

The most common values are:

  • GMT for global reference
  • Europe/Paris for Paris

Locales

A Locale defines a language, it can be for a particular country. It's a 2-letter language code and it can be followed by an underscore and a 2-letter country code.

Local examples:

  • en for global english
  • en_US for the american english
  • fr for the french
  • fr_BE for the french in Belgium.

See LocalePlanet for the list of locales with their:

  • Date formats: months, days, ...
  • Number formats: decimal separator, thousand separator, ...

Number pattern format

See below the list of the pattern characters:

Symbol Location Localized? Meaning
0 Number Yes Digit
# Number Yes Digit, zero shows as absent
. Number Yes Decimal separator or monetary decimal separator
- Number Yes Minus sign
, Number Yes Grouping separator
E Number Yes Separates mantissa and exponent in scientific notation. Need not be quoted in prefix or suffix.
; Subpattern boundary Yes Separates positive and negative subpatterns
% Prefix or suffix Yes Multiply by 100 and show as percentage
\u2030 Prefix or suffix Yes Multiply by 1000 and show as per mille value
¤ (\u00A4) Prefix or suffix No Currency sign, replaced by currency symbol. If doubled, replaced by international currency symbol. If present in a pattern, the monetary decimal separator is used instead of the decimal separator.
' Prefix or suffix No Used to quote special characters in a prefix or suffix, for example, "'#'#" formats 123 to "#123". To create a single quote itself, use two in a row: "# o''clock".

Complete reference

Related Links