Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.8)
  3. Reference
  4. Mule Expression Language (MEL)
  5. Mule Expression Language Reference

  6. Mule Expression Language Date and Time Functions

Mule Expression Language Date and Time Functions

Mule runtime engine version 3.8 reached its End of Life on November 16, 2021. For more information, contact your Customer Success Manager to determine how to migrate to the latest Mule version.

This reference page provides lists and brief explanations of the date and time functions in MEL.

For more information, see:

Prerequisites

This document assumes you are familiar with Mule Expression Language (MEL). Further, this document assumes you are using Mule 3.4.0 or newer.

Obtaining the Server Time

You can obtain the current date and time of the server using the context object server and one of the following fields:

  • dateTime

  • nanoTime

For example, the following expression returns the date and time of the server:

  `#[server.dateTime]`

You can further specify the data you wish to extract using the following quantifiers:

  • server.dateTime.getMilliSeconds()

  • seconds

  • minutes

  • hours

  • dayOfWeek

  • dayOfMonth

  • dayOfYear

  • weekOfMonth

  • weekOfYear

  • month

  • year

The following table describes operations you can perform with dateTime. The sections below offer details on how to use the operations in MEL expressions.

Action Operations

Obtain DateTime

  • dateTime

  • nanoTime

create a new DateTime instance

  • Default constructor

    • calendar

    • date

    • XMLGregorianCalendar

    • iso860

    • formatted string

Compute Relative Dates

  • plusMilliSeconds

  • plusSeconds

  • plusMinutes

  • plusHours

  • plusDays

  • plusWeeks

  • plusMonths

  • plusYears

Comparison

  • compared for equality using the == operator

  • isBefore

  • isAfter

Access timezones

  • withTimeZone

  • changeTimeZone(timezone)

  • timeZone

  • withLocale(localeAsString);

Format Strings

  • format()

  • format(String pattern)

Transform

  • toCalendar

  • toDate

  • toXMLCalendar

Obtain DateTime

ContextObject.Field Description Return Type

server.dateTime

Current system date and time in a DateTime object that simplifies the parsing/formatting and very basic manipulation of dates via the Mule expression language.

org.mule.el.datetime.DateTime

Example:

#[server.dateTime]

server.nanoTime()

Current system time in nanoseconds. Equivalent to System.nanoTime() and has the same limitations. Only use this to measure elapsed time, etc.

int

Example:

#[server.nanoTime()]

Access Partial DateTime Information

Qualifier Description Return Type

milliSeconds

Returns the number of milliseconds in the current second.
Equivalent to calendar.get(Calendar.MILLISECOND)

long

Example:

#[payload = (1000 - server.dateTime.milliSeconds) + ' to the next second.';]

seconds

Returns the number of seconds passed in the current minute (0 to 59).
Equivalent to calendar.get(Calendar.SECOND)

int

Example:

#[payload = (60 - server.dateTime.seconds) + ' to the next minute.';]

minutes

Returns the number of minutes passed in the current hour (0 to 59).
Equivalent to calendar.get(Calendar.MINUTE)

int

Example:

#[payload = (60 - server.dateTime.minutes) + ' to the next hour.';]

hours

Returns the number of hours passed in the current day (0 - 24).
Equivalent to calendar.get(Calendar.HOUR_OF_DAY)

int

Example:

#[payload = (24 - server.dateTime.hours) + ' to the next day.';]

dayOfWeek

Returns one of the following integer values:

  • Calendar.SUNDAY = 1

  • Calendar.MONDAY = 2

  • Calendar.TUESDAY = 3

  • Calendar.WEDNESDAY = 4

  • Calendar.THURSDAY = 5

  • Calendar.FRIDAY = 6

  • Calendar.SATURDAY = 7;

Equivalent to calendar.get(Calendar.DAY_OF_WEEK)

int

Example:

#[if (server.dateTime.dayOfWeek == Calendar.FRIDAY) { message.payload = 'TGIF'; }]

dayOfMonth

Returns the day of the month (1 to 31).
Equivalent to calendar.get(Calendar.DAY_OF_MONTH)

int

Example:

#[if (server.dateTime.dayOfMonth == 1) { payload = 'Paycheck!!!'; }]

dayOfYear

Returns the day of the year (1 to 366).
Equivalent to calendar.get(Calendar.DAY_OF_YEAR)

int

Example:

#[if (server.dateTime.dayOfYear == 1) { payload = "Happy New Year!!!"; }]

weekOfMonth

Returns the week of the month (1 to 5).
Equivalent to calendar.get(Calendar.DAY_OF_MONTH)

int

Example:

#[if (server.dateTime.weekOfMonth == 1) { payload = "Happy New Year!!!"; }]

weekOfYear

Returns the week of the year (1 - 53)
Equivalent to calendar.get(Calendar.WEEK_OF_YEAR)

int

Example:

#[if (server.dateTime.weekOfYear == 2) { payload = 'Stop saying happy new year!!!'; }]

month

Returns the month of the year (1 - 12)
Equivalent to calendar.get(Calendar.MONTH) + 1

int

Example:

#[if (server.dateTime.month == 12) { payload = 'Christmas!!!'; }]

year

Returns the the year (for example, 2013).
Equivalent to calendar.get(Calendar.YEAR)

int

Example:

#[if (server.dateTime.year == 1979) { payload = 'Year of good wine and programmers.'; }]

Create New DateTime Instance

Function Description

DateTime()

Constructs a DateTime with the current time and the time zone and locale of the server.

Example:

#[payload = new org.mule.el.datetime.DateTime();]

DateTime(calendar, locale)

Constructs a DateTime with the calendar and locale specified.

Argument Type

calender

java.util.Calendar

locale

java.util.Calendar

Example:

#[calendar = Calendar.getInstance(); locale = org.apache.commons.lang.LocaleUtils.toLocale('en_GB'); payload = new org.mule.el.datetime.DateTime(calendar, locale);]

DateTime(calendar)

Constructs a DateTime with the calendar specified and the locale of the server.

Argument Type

calender

java.util.Calendar

Example:

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

DateTime(calendar)

Constructs a DateTime with the calendar specified and the locale of the server.

Argument Type

calender

javax.xml.datatype.XMLGregorianCalendar

Example:

`#[calendar = javax.xml.datatype.DatatypeFactory .newInstance().newXMLGregorianCalendar();

payload = new org.mule.el.datetime.DateTime(calendar);]`

DateTime(date)

Constructs a DateTime with the specified date and the locale and time zone of the server.

Argument Type

date

java.util.Date

Example:

#[payload = new org.mule.el.datetime.DateTime(new Date());]

DateTime(iso8601String)

Construct a DateTime using the specified iso8601 date.

Argument Type

iso8601String

java.lang.String

Example:

#[payload = new org.mule.el.datetime.DateTime('1994-11-05T08:15:30-05:00');]

DateTime(String dateString, String format)

Constructs a DateTime using a string containing a date time in the specified format. The format should be SimpleDateFormat compatible.

Argument Type

dateString

java.lang.String

format

java.lang.String

Throws exception: ParseException

Example:

#[dateString = new Date().toString(); payload = new org.mule.el.datetime.DateTime(dateString, 'EEE MMM dd HH:mm:ss zzz yyyy');]

Compute Relative Dates

Functions Description Return Type

plusMilliSeconds(int add)

Returns the DateTime with the given amount of milliseconds added (or subtracted if it is a negative value).
Equivalent to: calendar.add(Calendar.MILLISECOND, add);

DateTime
This allows chaining: server.dateTime.plusWeeks(1).plusDays(1)

plusSeconds(int add)

Returns the DateTime with the given amount of seconds added (or subtracted if it is a negative value).
Equivalent to: calendar.add(Calendar.SECOND, add);

DateTime

plusMinutes(int add)

Returns the DateTime with the given amount of minutes added (or subtracted if it is a negative value).
Equivalent to: calendar.add(Calendar.MINUTE, add);

DateTime

plusHours(int add)

Returns the DateTime with the given amount of hours added (or subtracted if it is a negative value).
Equivalent to: calendar.add(Calendar.HOUR_OF_DAY, add);

DateTime

plusDays(int add)

Returns the DateTime with the given amount of days added (or subtracted if it is a negative value).
Equivalent to: calendar.add(Calendar.DAY_OF_YEAR, add);

DateTime

plusWeeks(int add)

Returns the DateTime with the given amount of weeks added (or subtracted if it is a negative value).

DateTime

plusMonths(int add)

Returns the DateTime with the given amount of months added (or subtracted if it is a negative value).
Equivalent to: calendar.add(Calendar.MONTH, add);

DateTime

plusYears(int add)

Returns the DateTime with the given amount of years added (or subtracted if it is a negative value).
Equivalent to: calendar.add(Calendar.YEAR, add); // public abstract void add(int field,int amount)

DateTime

Example

#[payload = 'Two days ago it was the ' + server.dateTime.plusDays(-2).dayOfWeek + 'st day of the week';]

Compare

Function Description Return Type

isBefore(ortherInstant)

Returns whether this Calendar represents a time before the instant represented by the specified argument.
Equivalent to calendar.before(otherInstant);

boolean

Example:

#[if (server.dateTime.isBefore(expiryOfSomething)) { payload = 'Not Yet Expired'; }]

isAfter(otherInstant)

Returns whether this Calendar represents a time after the instant represented by the specified argument.
Equivalent to calendar.after(otherInstant);

boolean

Example:

#[if (server.dateTime.isAfter(expiryOfSomething)) { payload = 'Expired'; }]

Access Timezones

Function Description Return Type

withTimeZone(timezone);

Changes the current DateTime to match a defined timezone. Effectively changing the dateTime and the timezone of the instance.

Argument Type

timezone

String compatible with TimeZone.getTimeZone()

DateTime
This allows chaining: server.dateTime.plusWeeks(1).plusDays(1)

Example:

`#[pstTimeZoneInstant = server.dateTime.withTimeZone('PST');]

#[phoenixInstant = server.dateTime.withTimeZone('America/Phoenix');]`

changeTimeZone(timezone)

Changes the timezone of the instance. Effectively changing only the timezone of the instance.

Argument Type

timezone

String compatible with TimeZone.getTimeZone()

DateTime
This allows chaining: server.dateTime.plusWeeks(1).plusDays(1)

Example:

`#[pstTimeZoneInstant = server.dateTime.withTimeZone('PST');]

#[phoenixInstant = server.dateTime.changeTimeZone('America/Phoenix');]`

timeZone

Returns the current TimeZone of the dateTime instance.

string
String compatible with TimeZone.getTimeZone()

Example:

#[payload = server.dateTime.timeZone]

withLocale(localeAsString);

This method takes the string format of a locale and creates the locale object from it.

Argument Type

localAsString

String. The language code must be lowercase. The country code must be uppercase. The separator must be an underscore. The length must be correct.

DateTime
This allows chaining: server.dateTime.plusWeeks(1).plusDays(1)

Example:

#[payload = server.dateTime.withLocale('en_GB');]

Format Strings

Function Description Return Type

format()

Formats the instance in a string with the ISO8601 date time format.

string

Example:

#[payload = server.dateTime.format()]

format(String pattern)

Formats the instance in a specific format.

Argument Type

pattern

String compatible with SimpleDateFormat

string
A representation of the instance using the specified format.

Example:

#[payload = server.dateTime.format("yyyy.MM.dd G 'at' HH:mm:ss z")]

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.

Transform

Function Description Return Type

toCalendar()

Returns a Java Calendar representation of the dateTime instance.

Calendar

Example:

#[payload = server.dateTime.toCalendar()]

toDate()

Returns a Java Date representation of the datetime instance.

java.util.Date

Example:

#[payload = server.dateTime.toDate()]

toXMLCalendar()

Returns a XMLCalendar representation of the datetime instance.

Throws: DatatypeConfigurationException

XMLGregorianCalendar

Example:

#[payload = server.dateTime.toXMLCalendar()]

See Also