Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.6)
  3. Developing
  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 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 provides lists and brief explanations of the date and time functions in MEL. For explanatory information, see Mule Expression Language, MEL Basic Syntax, and the MEL examples.

Assumptions

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

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

compare

  • 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 Example

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

 
#[server.dateTime]

server.nanoTime()

Current system time in nanoseconds. Equivalent to System.nanoTime() and has the same limitations, that is, should be used only to measure elapsed time, etc.

int

 
#[server.nanoTime()]

Access Partial DateTime Information

Qualifier Description Return Type Example

milliSeconds

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

long

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

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

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

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

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

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

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

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

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

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

year

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

int

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

Create New DateTime Instance

Function Description Example

DateTime()

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

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

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

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

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

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

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

DateTime(String dateString, String format)

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

Argument Type

dateString

java.lang.String

string

java.lang.String

Throws exception: ParseException

 
#[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);

DateTime

Example

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

Compare

Function Description Return Type Example

isBefore(ortherInstant)

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

boolean

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

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

Access Timezones

Function Description Return Type Example

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)

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

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

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

timeZone

Returns the current TimeZone of the dateTime instance.

string
A TimeZone.getTimeZone() compatible string.

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

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

Format Strings

Function Description Return Type Example

format()

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

string

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

 
#[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 will be transformed into escaped quotes` ("`) in the XML view.

Transform

Function Description Return Type Example

toCalendar()

Returns a Java Calendar representation of the dateTime instance.

Calendar

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

toDate()

Returns a Java Date representation of the datetime instance.

java.util.Date

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

toXMLCalendar()

Returns a XMLCalendar representation of the datetime instance.

Throws: DatatypeConfigurationException

XMLGregorianCalendar

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

See Also