Appendix A. Mule Expression Language

The Mule Expression Language (MEL) is based on the MVFLEX Expression Language (MVEL; see http://mvel.codehaus.org/), a hybrid dynamic/statically typed language. We strongly recommend you get acquainted with MVEL by reading its online documentation (http://mvel.codehaus.org/Language+Guide+for+2.0). MEL itself is also extensively documented online (http://mng.bz/g8sM). This appendix is a quick reference guide to Mule-specific features of MEL. It also provides a quick overview on how to customize MEL to implement custom needs.

A.1. MEL quick reference

Mule binds custom objects, variables, and functions within the MEL context to facilitate accessing Mule resources, processing messages, and so on.

Top-level variables quick reference

The four main context objects exposed by MEL are server, mule, app, and message. Additionally, payload is available as a shortcut to message.payload, flowVars and sessionVars are maps that give access to flow and session variables, and exception is bound if the current event carries an exception.

Before looking in detail at these context helpers, let’s take a quick peek at MVEL. Take a look at this sample script from MVEL’s documentation (http://mvel.codehaus.org/Sample+Scripts):

colors = {'red', 'green', 'blue'};
foreach (c : colors) {
    System.out.println(c + "!");
}

What should strike you is the following:

• MVEL has nice syntactic sugar for data structures. Lists and maps can be created as easily as arrays, for example, with ['key':'value'] for a map.
• Any Java class can be reached. Classes not in the auto-imported list (see section A.1.4) must be referred to via their fully qualified names.

Of all the goodness MVEL provides, its unified support for property navigation (including null-safe navigation) is one of the most convenient features. For example, in the following snippet,

user.name

name can refer to either a getName accessor on a user JavaBean or the name key in a user hashmap.

Without further ado, let’s go through the context objects Mule gives you access to.

A.1.1. Context objects

There are four context objects available: server, mule, app, and message. We’ll review them in detail.

server

The server context gives access to the properties of the hardware, operating system, virtual machine, user and network interface, and time-related functions. See table A.1.

Table A.1. Properties of the server context object

mule

The mule context allows you to retrieve the properties of the Mule instance, which is either the standalone broker instance or the instance that’s embedded in an application (for example, in a web application). See table A.2.

Table A.2. Properties of the mule context object

app

The app context exposes the properties of the Mule application that the current expression is evaluated into. See table A.3.

Table A.3. Properties of the app context object

message

The message context gives access to the payload, attachments, and properties of the Mule message that’s under processing. This context isn’t available if the expression is evaluated outside the context of a Mule event. See table A.4.

Table A.4. Properties of the message context object

A.1.2. Context variables

Mule binds extra context entries that are similar to the objects we’ve just described but specific to the in-flight message flow and session variables (that is, respectively, invocation- and session-scoped message properties; refer to section 2.3.2 for more on this).

These entries are as follows:

• flowVars— A read/write Map of flow variables.
• sessionVars— A read/write Map of session variables.
• Any flow variable whose name doesn’t conflict with other context entries and is a valid MVEL variable name. For example, the currentUser flow variable would be available both in the flowVars map, with either flowVars['currentUser'] or flowVars.currentUser, and as a top-level context variable named current-User. Conversely, a flow variable named current-user would only be available as flowVars['current-user'] because it can’t be used directly as a valid MVEL variable name.
• exception— A java.lang.Exception optionally bound if the current message carries an exception payload.

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

A.1.3. Context functions

Mule binds helper functions in the MEL context. These functions simplify using XPath and regular expressions.

XPath

• xpath(xPathExpression)— Applies the XPath expression to the in-flight message payload (which must be an XML document or a DOM instance).
• xpath(xPathExpression, xmlElement)— Applies the XPath expression to the XML element specified by the MEL expression appearing as the second argument. xmlElement can be an MVEL variable or another expression (for example, to retrieve XML out of a message property or attachment).

Be aware that the xpath function returns DOM nodes (elements and attributes, but also node lists). If you want to get the node string content instead, you’ll need to specifically get it; for example, like this for an attribute:

xpath('/book/@id').value

Or like this for a text element:

path('/book/name').text

regex

• regex(regularExpression)— Applies the regular expression to the in-flight message payload
• regex(regularExpression, melExpression)— Applies the regular expression to the specified MEL expression
• regex(regularExpression, melExpression, matchFlags)— Applies the regular expression to the specified MEL expression using the flags defined in Java’s Pattern documentation (http://mng.bz/gyte)

The regex function returns null if no match has been found and an array of results if more than one match was found. Otherwise, it returns the single matching value.

A.1.4. Imported classes

MEL automatically imports the following Java classes, so you can use them without using their fully qualified names:

• java.lang.Boolean
• java.lang.Byte
• java.lang.Character
• java.lang.Enum
• java.lang.Float
• java.lang.Integer
• java.lang.Long
• java.lang.Math
• java.lang.Number
• java.lang.Object
• java.lang.Short
• java.lang.String
• java.lang.System
• java.util.Calendar
• java.util.Collection
• java.util.Date
• java.util.Map
• java.util.List
• java.util.Set
• java.util.regex.Pattern
• javax.activation.DataHandler
• javax.activation.MimeType
• org.mule.api.transformer.DataType
• org.mule.transformer.types.DataTypeFactory

A.2. Customizing MEL

MEL supports multiple configuration-based customizations. For example, it is possible to do the following:

• Import additional classes in the context
• Alias these imported classes
• Alias complete MEL expressions under new names
• Define new globally bound functions

Take a look at the following Mule configuration fragment:

<configuration>
  <expression-language autoResolveVariables="false">
    <import class="org.mule.util.StringUtils" />
    <import name="rsu"
            class="org.apache.commons.lang.RandomStringUtils" />
    <alias name="appName" expression="app.name" />
    <global-functions>
      def reversePayload() { StringUtils.reverse(payload) }
      def randomString(size) { rsu.randomAlphanumeric(size) }
    </global-functions>
  </expression-language>
</configuration>

The noticeable aspects of this configuration are

• org.mule.util.StringUtils gets globally imported and used in a global custom function named reversePayload (of arity 0).
• org.apache.commons.lang.RandomStringUtils gets globally imported and aliased as rsu, and then used in a global custom function named randomString (of arity 1).
• The expression app.name gets globally aliased to appName.

Optionally, you can also specify a file attribute on the global-functions configuration element should you want to store your custom MEL functions in an external file. With this configuration in place, it’s possible to use the declared global functions and variables, as shown in the following example:

<set-property propertyName="random-app-property"
              value="#[appName + ':' + randomString(20)]" />
<set-payload  value="#[reversePayload()]" />

Or code it...

It’s also possible to programmatically extend MEL by coding custom language extensions. This is beyond the scope of this appendix, but if you want to get started with that approach, take a look at org.mule.module.xml.el.XMLExpressionLanguageExtension from the mule-module-xml to have an idea of how to achieve this. Also take a look at META-INF/services/org/mule/config/registry-bootstrap.properties to see how the XMLExpression-LanguageExtension is globally registered so that it can be used throughout Mule.