Mule Expression Language Reference
Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can migrate to the latest Mule version. |
This reference page for the Mule Expression Language (MEL) provides lists and brief explanations of MEL features such as operators, literals, and functions, but it is not intended as an introduction or thorough explanation of MEL. For explanatory information, see Mule Expression Language, Mule Expression Language Basic Syntax, and the MEL examples.
Assumptions
This document assumes you are familiar with Mule Expression Language (MEL).
Context Objects, Variables, and Fields
The term Context Object forms the first part of the simplest form of a MEL expression; the second part is the Field.
Context Objects
Context objects provide logical groupings for the fields of the Mule message and its environment. More than just another expression language, the context objects make MEL Mule-centric. MEL has four context objects:
-
server: This object provides access to the fields for the hardware, operating system, user, and network interface.
-
mule: This object provides access to the fields for your Mule instance.
-
app: This object provides access to the fields of your Mule application.
-
message: This object provides access to the fields of the Mule message.
In MEL, you combine a context object with a field to form an expression. The simplest expressions take the form contextobject.field
. For example, this simple expression:
#[message.inboundProperties]
The following table describes the context objects and the fields to which they have access.
Context Object | Field | Read-Only Access | Read-Write Access | Field Description |
---|---|---|---|---|
|
|
x |
Date or time |
|
|
x |
environment |
||
|
x |
Character that separates components of a file path ( "/" on UNIX and "\" on Windows) |
||
|
x |
Fully-qualified domain name of the server |
||
|
x |
IP address of the server |
||
|
x |
Default locale (of type java.util.Locale) of the JRE (can access server.locale.language and server.locale.country) |
||
|
x |
JRE version |
||
|
x |
JRE vendor name |
||
|
x |
Measure of nanoseconds |
||
|
x |
Operating system name |
||
|
x |
Operating system architecture |
||
|
x |
Operating system version |
||
|
x |
Map of Java system properties |
||
|
x |
Default TimeZone (java.util.TimeZone) of the JRE |
||
|
x |
Temporary directory for use by the JRE |
||
|
x |
User name |
||
|
x |
User home directory |
||
|
x |
User working directory |
||
|
|
x |
Cluster ID |
|
|
x |
File system path to the home directory of the mule server installation |
||
|
x |
Cluster node ID |
||
|
x |
Mule version |
||
|
|
x |
Application default encoding |
|
|
x |
Application name |
||
|
x |
Evaluates to true if Mule is running standalone |
||
|
x |
Application work directory |
||
|
x |
Map representing the Mule registry |
||
|
|
x |
Unique identifier of Mule message |
|
|
x |
Root ID of Mule message |
||
|
x |
Correlation ID |
||
|
x |
Correlation sequence |
||
|
x |
Correlation group size |
||
|
x |
Reply to |
||
|
x |
Data type of payload |
||
|
x |
Mule message’s payload |
||
|
x |
Map representing the message’s immutable inbound properties |
||
|
x |
Map representing the message’s inbound attachments |
||
|
x |
Map representing the message’s mutable outbound properties |
||
|
x |
Map representing the message’s outbound attachments |
Variables
Use a Variable in a MEL expression to access information contained within a Flow Variable or Session Variable on your Mule message.
Itself a top-level identifier in MEL, a variable does not require that you define a context object in an expression. MEL evaluates against two types of variables:
-
flowVars
- Retain their values as control passes from one message processor to another within a single flow. Thus, you can set them in one message processor, then access them in another message processor using a MEL expression. -
sessionVars
- Retain their values as control passes from one flow to another within an application. Thus, you can set them in one flow, then access them in another using a MEL expression.
This example uses an expression to access the value of the session variable bar
and uses it to set the value of the flow variable foo
:
#[flowVars.foo = sessionVars.bar]
Shortcut As a shortcut, you can eliminate the #[foo = bar] Mule assumes that it is a If you wish to disable this auto-resolution of variables by name, include the following configuration XML configuration file:
Note that variables in MEL are scoped following rules similar to those of Java, so if you declare a variable within a given scope (for example within an IF statement) this variable won’t be recognized if you try to access it from outside this scope. |
Accessing Properties
This section summarizes the primary ways for accessing properties in MEL using dot syntax, bracket syntax, and null safe operators.
Dot Syntax
In general, property access in MEL is performed using dot syntax. Dot syntax works with maps (when keys are strings), beans, or POJOs.
#[message.payload.item]
Null Safety
To access properties in a null safe manner, add the .? operator before one or more objects in a chain. In the following expression, if fieldA is null, the expression evaluates to null instead of a NullPointerException.
#[contextObject.?fieldA.objectB]
Xpath and Regex
A MEL expression in Mule always resolves to a single value. You can use xpath3 and regex functions to extract information which doesn’t already exist as a single value.
Xpath
Xpath is a language for addressing parts of an XML document. The MEL xpath3 function allows you to evaluate XPath expressions.
Structure | Description |
---|---|
|
Applies the XPath expression to the message payload (an XML document) and returns the specified content. The example returns the first order from the message payload. Example: |
|
Applies the XPath expression to the XML element specified by the MEL expression appearing as the second argument, and returns the specified content. The example returns the first order from the order element in the current message’s inbound attachment map. Example: |
Regex
Regular expressions provide a means of specifying patterns to look for in a stream of text, and actions to take upon the patterns when found. The regex function enables you to use regular expressions from within MEL. Regular expressions in MEL use the syntax recognized by the java.util.regex
package.
Expression | Description |
---|---|
|
Applies the regular expression to the message payload. MEL processes this as follows:
Examples: With a payload of: regex('(aa)(.*)(cc)') With a payload of: regex('(aa)(bb)(cc)') |
|
Applies the regular expression to the value of the MEL expression, rather than the payload. Any string-valued MEL expression can appear as the second argument, using the same process as described above. |
|
Applies the regular expression to the value of the MEL expression, but uses the |
Operators
MEL operators follow standard Java syntax, but operands are evaluated by value, not by reference. For example, 'A' == 'A'
evaluates to true in MEL, whereas the same expression evaluates to false in Java.
Arithmetic Operators
Symbol | Definition | Example | Return Value |
---|---|---|---|
+ |
Plus. For numbers, the value is the sum of the values of the operands. For strings, the value is the string formed by concatenating the values of the operands. |
`#[2 + 4] `
|
The string` "fubar"` |
- |
Minus. The value is the value of the first operand minus the value of the second. |
`#[`2 - 4] |
` -2` |
/ |
Over. The value is the value of the first operand divided by the value of the second. |
|
|
* |
Times. The value is the product of the values of the operands. |
`#[`2 * 4] |
` 8` |
% |
Modulo. The value is the remainder after dividing the value of the first operand by the value of the second. |
`#[`9 % 4] |
` 1` |
Comparison Operators
Symbol | Definition | Example | Return Value |
---|---|---|---|
== |
Equal. True if and only if the values of the operands are equal. |
`#[’A' == 'A'] |
|
!= |
Not equal. True if the values of the operands are unequal. |
`#[’A' != 'B'] |
|
> |
Greater than. True if the value on the left is greater than the value on the right. |
`#[`7 > 5] |
|
< |
Less than. True if the value on the left is less than the value on the right |
`#[`5 < 5] |
|
>= |
Greater than or equal. True if the value on the left is greater than or equal to the value on the right. |
`#[`5 >= 7] |
|
<= |
Less than or equal. True if the value on the left is less than or equal to the value on the right. |
`#[`5 <= 5] |
|
contains |
Contains. True if the string on the right is a substring of the string on the left. |
`#[’fubar' contains 'bar'] |
|
is, instance of |
Is an instance of. True if the object on the left is an instance of the class on the right. |
`#[’fubar' is String] |
|
strsim |
Degree of similarity. The value of the expression is a number between 0 and 1 representing the degree of similarity between the two string arguments. |
|
|
soundslike |
Sounds like. True if the two string arguments sound alike according to a Soundex comparison. |
|
|
Wildcard |
Matches a value (the message palyoad, by default) against a wildcard pattern, these use the metacharacters |
|
|
Logical Operators
Symbol | Definition |
---|---|
&& |
Logical AND. True if both operands are true. (Do not use and.) Example: |
|| |
Logical OR. True if at least one operand is true. Example: |
or |
Chained OR. Scans left to right and returns the value of the first non-empty item Example: |
Ternary Condition Operators
Structure | Definition | Example | Value |
---|---|---|---|
condition ? true value : false value |
Conditional operand (ternary statement) |
#[lastname = (name == 'Smith') ? 'Smith' : 'Unknown'] |
Sets the value of variable |
Literals
Literals in MEL can be strings, numbers, Boolean values, types, and nulls. The Lists, and Arrays section shows how you can provide data structures as literals as well.
Numeric Literals
Numeric literals are integers and floating point numbers, with the same ranges of values as the underlying Java system.
Integers are assumed to be decimal unless they begin with 0. An integer consisting of 0 followed by digits ranging from 0 to 7 is interpreted as octal. An integer starting with 0x followed by digits ranging from 0 to 9 or letters ranging from a to f is interpreted as hexadecimal. An integer ending in an uppercase I is interpreted as a BigInteger. Literals that include alphabetic characters are case sensitive.
MEL recognizes floating point numbers by the presence of a decimal point. Floating point numbers can optionally have the following suffixes:
-
d
To represent double -
f
To represent float -
B
To represent BigDecimal
Examples:
-
255
-
0377
-
0xff
-
3.14159
-
3.14159f
-
3.14159265358979d
String Literals
String literals are sequences of characters enclosed in single quotes. Within String literals you can use the following escape sequences to represent non-printable characters, Unicode characters, and the escape character.
Escape Sequence | Represents |
---|---|
|
\ |
|
Newline character |
|
Return character |
|
ASCII character represented by the octal number xxx |
|
Unicode character represented by the hexadecimal number yyyy |
When writing in Studio’s XML editor, you cannot use double quotes to express String literals, because MEL expressions already appear enclosed in double quotes in configuration files. Instead, you can either:
If you’re writing on Studio’s visual editor, double quotes transform into escaped quotes` ("`) in the XML view. |
Type Literals
You can refer to any Java class by its fully qualified name or if it is one of the classes in the automatically-imported Java classes, by its unqualified name. References use the same dot notation as in Java, except that you must use $
rather than a dot to refer to a nested class.
MEL automatically imports the Java classes listed below. You can use these imported classes without using full-qualifier names. For example, because BigInteger is imported, you can write:
#[BigInteger.valueOf(payload.dueAmount)]
Instead of:
#[java.math.BigInteger.valueOf(payload.dueAmount)]
-
java.lang.*
-
java.io.*
-
java.net.*
-
java.util.*
-
java.math.BigDecimal
-
java.math.BigInteger
-
javax.activation.DataHandler
-
javax.activation.MimeType
-
java.util.regex.Pattern
-
org.mule.api.transformer.DataType
-
org.mule.transformer.types.DataTypeFactory
Maps, Lists, and Arrays
Mule Expression Language uses a convenient syntax for maps and other data structures. Rather than constructing a map, list or array with a new statement, and then using its put method to populate it, you can simply them inline within an expression (see examples below). Use this literal form wherever you would otherwise use a map by name, including as a method argument.
map |
|
list |
|
array |
|
Arrays in Java must specify the type of their contents, but in MEL they are untyped. MEL supplies the correct type when you use them – either by determining it at compile time or coercing the array to the correct type at run time.
Accessing Map Data
Similar to java.util.Map, MEL provides a a method for accessing data within a map.
For example, the inboundProperties
on a Mule message exist as a map. You can access this map in a MEL expression using message.inboundProperties
. To retrieve on of the items in the map – the one with the key name foo
– use:
#[message.inboundProperties['foo']]
Syntax Tip If the map keys are strings, MEL also allows the same Accessing Properties that you use to access object fields to access map values, i.e. #[message.inboundProperties.foo] In Anypoint Studio, autocomplete supports this dot syntax for all object fields. However, you must use the bracket syntax for map access in cases where the keys are not strings or you need to evaluate an expression to obtain the actual key to use. |
To set an outbound property on a message, use:
#[message.outboundProperties['key'] ='value']
To remove a key, you must explicitly use the map’s remove method:
#[message.outboundProperties.remove('key')]
Wildcard Function
The Wildcard Function matches a value against a wildcard expression pattern. Wildcard expression patterns are a String that can use the metacharacters '?' to represent any single character and '*' for a repetition of any character.
The wildcard function has the signature wildcard( wildcardExpression, target, isCaseSensitive)
.
Parameter | Type | Description | Default | Required |
---|---|---|---|---|
wildcardExpression |
String |
The wildcard expression to be used to match against the target String. |
Yes |
|
target |
String |
This is usually a MEL expression which evaluates to the target String. The matchExpression String is matched with this target String. |
|
No |
isCaseSensitive |
Boolean |
If true, case sensitivity is included in the match. For example, if this parameter is true, "Hello*" will not match "hello world". If this parameter is false, "Hello*" will match "hello world". |
true |
No |
If you only supply the first wildcardExpression String, then the match is done against the default target MEL expression #[message.payload]
, and the match is case sensitive.
Consider the examples below applied to a message with a String payload of : Hello World
.
wildcard("Hello*") // returns true
wildcard("hello*") // returns false
wildcard("*World") // returns true
wildcard("??????World") // returns true
wildcard("GoodBye*") // returns false
wildcard("*llo*d") // returns true
For more advanced use cases, the examples below are applied to a message with an inbound property named 'foo'
containing the value Hello World
:
wildcard("Hello*", message.inboundProperties['foo']) // returns true
wildcard("hELLO*", message.inboundProperties['foo'], false) // returns true
wildcard("*world",message.inboundProperties['foo'], true) // returns false
See Also
-
For reference on extracting and manipulating date and time in MEL, see MEL Date and Time Functions.
-
For full example applications which use MEL, access Mule Expression Language Examples.