Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.7)
  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.

Prerequisites

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.

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 objects make MEL Mule-centric. MEL has four context objects:

Context Object Provides access to the fields for

Server

Hardware, operating system, user, and network interface.

Mule

Your Mule instance.

App

Your Mule application.

Message

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, #[message.inboundProperties] is a simple expression. The sections below describe each context object and the fields to which they have access.

Server Context Object

Field Read-only Access Read-write Access Field Description

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 a server

ip

x

IP address of a 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 Context Object

Field Read-only Access Read-write Access Field Description

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 Context Object

Field Read-only Access Read-write Access Field Description

encoding

x

Application default encoding

name

x

Application name

registry

x

Map representing the Mule registry

standalone

x

Evaluates to true if Mule is running standalone

workdir

x

Application work directory

Message Context Object

Field Read-only Access Read-write Access Field Description

id

x

Unique identifier of Mule message

rootId

x

Root ID of Mule message

correlationId

x

Correlation ID

correlationSequence

x

Correlation sequence

correlationGroupSize

x

Correlation group size

replyTo

x

Reply to

dataType

x

Data type of payload

payload

x

Mule message 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 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, and access them in another using a 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 rewritten as follows:

#[foo = bar]

Mule assumes that it is a flowVars and, when MEL evaluates the expression, looks 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.

XPath

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

  • #[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.
    Example: 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.
    Example: xpath3('/orders/order[0]', message.inboundAttachments.order)

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

#[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.

Arithmetic Operators

Symbol Definition Example Return Value

+

Plus. For numbers, the value is the sum of the values of the operands.

#[2 + 4]

6

For strings, the value is the string formed by concatenating the values of the operands.

#['fu' + 'bar']

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]

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']

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 of 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 a Soundex comparison.

#['Robert' soundslike 'Rupert']

true

Wildcard

Matches a value (the message payload, by default) against a wildcard pattern, these use the metacharacters '?' to represent any single character and '*' for a repetition of any character. It is case sensitive by default. See more

#[wildcard('Hello*')]

true

Logical Operators

  • && - Logical AND. True if both operands are true. (Do not use and.)
    Example: #[(a == b) && (c != d)]
    Result: True if a = b and c ≠ d

  • || - Logical OR. True if at least one operand is true.
    Example: #[true || anything ]
    Result: Always true

  • or - Chained OR. Scans left to right and returns the value of the first non-empty item.
    Example: #[payload.address or 'No address']
    Result: Either the address stored as an object on the payload, or the string 'No address'.

Ternary Condition Operator

Conditional operand (ternary statement):
condition ? true value : false value

Example:
#[lastname = (name == 'Smith') ? 'Smith' : 'Unknown']

Sets the value of variable lastname to the string Smith if the value of name is Smith. Sets the value of the variable to the string Unknown if the value of name is not Smith.

Line Delimiter

Symbol: Semicolon (;)

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

Example:

#[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, 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

\ \

\

\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 expressions 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 writing on Studio’s visual editor, double quotes transform 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 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

{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.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, 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 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.

#[message.payload]

No

isCaseSensitive

Boolean

If true, case sensitivity is included in the match.

For example, if this parameter is true, "Hello*" does not match "hello world". If this parameter is false, "Hello*" matches "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