Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.5)
  3. Developing
  4. Mule Expression Language MEL

  5. Mule Expression Language Reference

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 Control Object forms the first part of the simplest form of a MEL expression; the second part is the Field.

contextob_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 object makes 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 context object with a field to form an expression. The simplest expression take the form contextobject.field. For example, #[message.inboundProperties] is a simple expression. The table below describes the context objects and fields to which they have access.

Context Object Field Access Field Description

read-only

read-write

server

dateTime

x

date or time

env

x

environment

fileSeparator

x

character that separates components of a file path ( "/" on UNIX and "\" on Windows)

host

x

fully-qualified domain name of the server

ip

x

IP address of the server

locale

x

default locale (of type java.util.Locale) of the JRE (can access server.locale.language and server.locale.country)

javaVersion

x

JRE version

javaVendor

x

JRE vendor name

nanoSeconds

x

measure of nanoseconds

osName

x

operating system name

osArch

x

operating system architecture

osVersion

x

operating system version

systemProperties

x

map of Java system properties

timeZone

x

default TimeZone (java.util.TimeZone) of the JRE

tmpDir

x

temporary directory for use by the JRE

userName

x

user name

userHome

x

user home directory

userDir

x

user working directory

mule

clusterID

x

cluster id

home

x

file system path to the home directory of the mule server installation

nodeId

x

cluster node ID

version

x

Mule version

app

encoding

x

application default encoding

name

x

application name

standalone

x

evaluates to true if Mule is running standalone

workdir

x

application work directory

registry

x

map representing the Mule registry

message

id

x

unique identifier of Mule message

ootId

x

root ID of Mule message

correlationId

x

correlationSequence

x

correlationGroupSize

x

replyTo

x

dataType

x

data type payload

payload

x

Mule message’s payload

inboundProperties

x

map representing the message’s immutable inbound properties

inboundAttachments

x

map representing the message’s inbound attachments

outboundProperties

x

map representing the message’s mutable outbound properties

outboundAttachments

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.

flowVars-syntax

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 MEL expression.

  • sessionVars that 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 MEL expression.

The example code below 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 flowVars in your expression and simply use the variable name in a MEL expression. The example above could be written as follows:

#[foo = bar]

Mule assumes that it is a flowVars and when MEL evaluates the expression, look for a variable by that name. If Mule cannot find a flowVars by that name, it looks for a sessionVars by that name before failing.

If you wish to disable this auto-resolution of variables by name, include the following configuration XML configuration file:

<configuration>
        <expression-language autoResolveVariables="false">
</configuration>

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]

Escaping Complex Names

Complex object names can be escaped using single quotes, like this:

#[message.inboundProperties.'http.query.params']

#[sessionVars.'complex name with spaces']

Bracket Syntax

Bracket syntax is also supported for accessing properties and objects. Bracket syntax is required when dealing with map keys that are not strings, or when you need to evaluate expressions to resolve to a map key.

#[payload[5]]

#[flowVars['keys.' + keyName]]

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.

XPath3

XPath is a language for addressing parts of an XML document. The MEL XPath3 function allows you to evaluate XPath expressions.

Structure Description Example

#[xpath3(xPathExpression)]

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.

xpath3(\'/orders/order[0]')

#[xpath3(xPathExpression, xmlElement)]

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.

xpath3(\'/orders/order[0]', message.inboundAttachments.order)

#[xpath3(xPathExpression, xmlElement, returnType)]

Applies the XPath expression to the XML element specified by the MEL expression appearing as the second argument, and returns something of the required type. Accepted types are boolean, string, number, node and nodeset. The example returns true if a fourth element exists in the current message’s inbound attachment map, or false otherwise.

xpath3(\'/orders/order[3]', message.inboundAttachments.order, boolean)

Regex

Regular expressions provide a means of specifying patterns to look for in a stream of text, and actions to take upon the pattern 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

#[regex(regularExpression)]

Applies the regular expression to the message payload.

MEL processes this as follows:

  • Creates a java.util.regex.Matcher using a compiled version of the regular expression and a string representing the payload.

  • Uses the Matcher.matches() method to match the payload against the given pattern.

  • Uses the Matcher.group() method to get the match of each group defined in the regular expression (each group is delimited by parentheses).

  • If there are no matches, return null.

  • Else if there is only a group and It matches return the match,

  • Else if there are many groups and every group matches returns matches in an array.

Examples:

With a payload of: aaabbbbbbbbbbccc returns an array with three elements: aaa, bbbbbbbbbb, and ccc:

regex('(aa)(.*)(cc)')

With a payload of: aaabbbbccc returns null because the second group doesn’t match:

regex('(aa)(bb)(cc)')

#[regex(regularExpression, melExpression)]

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.

#[regex(regularExpression, melExpression, matchFlags)]

Applies the regular expression to the value of the MEL expression, but uses the matchFlags bit mask as described in the Java documentation for java.util.regex.Pattern

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.

Table 1. 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]

#['fu' + 'bar']

6

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.

#[2 / 4]

0.5

*

Times The value is the product of the values of the operands

#[2 * 4]

%
Table 2. Comparison Operators
Symbol Definition Eample Return Value

==

Equal. Not true if and only if the values of the operands are equal.

#['A' == 'A']

true

!=

Not equal. True if the values of the operands are unequal.

#['A' != 'B']

true

>

Greater than. True if the value on the left is greater than the value on the right.

#[7 > 5]

true

<

Less than. True if the value on the left is less than the value on the right.

#[5 < 5]

false

>=

Greater than or equal. True if the value on the left is greater than or equal to the value on the right.

#[5 >= 7]

false

⇐

Less than or equal. True if the value on the left is less than or equal to the value on the right.

#[5 ⇐ 5]

true

contains

Contains. True if the string on the right is a substring off the string on the left

#['fubar' contains 'bar']

true

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]

true

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.

#['foo' strsim 'foo']

1.0

#[‘foobar’ strsim ‘foo’]

0.5

soundslike

Sounds like. True if the two string arguments sound alike according to Soundex comparison.

#['Robert' soundslike 'Rupert']

true
Table 3. Logical Operators
Symbol Definition Example Value

&&

Logical AND. True if both operands are true. (Do not use and)

#[(a == b) && (c != d)]

true if a=b and c≠d

||

Logical OR. True if at least one operand is true.

#[true ||anything ]

always true

or

Chained OR. Scans left to right and returns the value of the first non-empty item.

#[payload.address or 'No address']

either stored as an object on the payload, or the string 'No address'
Table 4. 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 lastname to the string "Smith" if the value of name is "Smith". It sets the value of the variable to the string "Unknown" if the value of the name is not "Smith"
Table 5. Line Delimiters
Symbol Definition Example

;

You can write multi-line expressions, each line must be delimited by a ;

#[calendar = Calendar.getInstance(); message.payload = new org.mule.el.datetime.DateTime(calendar);]

Literals

Literals in MEL can be strings, numbers, Boolean values, types, and nulls. The Maps, List, and Arrays section shows how you can provide data structure 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 BigInterger. Literals that include alphabetic characters are case sensitive.

MEL reconginzes 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

\ \

\

\n

Newline character

\r

Return character

\xxx

ASCII character represented by the octal number xxx

\uyyyy

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 expression already appear enclosed in double quotes in configuration files. Instead, you can either:

  • use single quotes

('expression')

  • escape quotes with "

("expression")

  • escape quotes with \u0027

(\u0027expression\u0027)

If you’re using Studio’s visual editor, double quotes are transformed into escaped quotes (") in the XML view.

Boolean Literals

Boolean literals are the values true and false. These are case sensitive.

Null Literals

A null literal takes the form null or nil. These are case sensitive.

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 BigInterger is imported, you can write #[BigInteger.valueOf(payload.dueAmount)] instead of #[java.math.BigInteger.valueOf(payload.dueAmount)].

  • java.lang.*

  • java.io.*

  • java.net.*

  • java.until*

  • java.math.BigDecimal

  • java.math.BigInterger

  • 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 inline them with an expression (see examples below). Use this literal form whenever you would otherwise use a map by name, including as a method argument.

map

{key1 : value1, key2 : value2, . . .}

list

`[item1, item2, . . .] `

array

{item1, item2, . . .}

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.untl.Map, MEL provides 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 MEL expression using message.inboundProperties. To retrieve one 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 allwos the same dot syntax that you use to access object fields to access map values, that is, #[map.key]. Thus, you can write the expression above like this:

#[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 of 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')]

See Also