Expressions

Expressions are specified as configuration parameter values for a number of built-in objects. Such expressions conform to the Universal Expression Language as specified in JSR-245.

General Syntax

All expressions follow standard Universal Expression Language syntax: ${expression}. The expression can be a simple reference to a value, a function call, or arbitrarily complex arithmetic, logical, relational and conditional operations. When supplied within a configuration parameter, an expression is always a string enclosed in quotation marks, for example: "${request.method}".

Configuration and Runtime Expressions

Expressions are evaluated at configuration time (when routes are loaded), or at runtime (when IG is running).

When expressions are evaluated, they access the current environment through the implicit object openig. The object has the following properties:

  • baseDirectory, the path to the base location for IG files. The default location is $HOME/.openig (%appdata%\OpenIG).

  • configDirectory, the path to the IG configuration files. The default location is $HOME/.openig/config (%appdata%\OpenIG\config).

  • temporaryDirectory, the path to the IG temporary files. The default location is $HOME/.openig/tmp (%appdata%\OpenIG\tmp).

For information about how to change the default values, see "Changing the Default Location of the Configuration Folders".

configuration expression

Expression evaluated at configuration time, when routes are loaded.

Configuration expressions can refer to the system heap properties, the built-in functions listed in "Functions", the ${env['variable']}, and ${system['property']}. Because configuration expressions are evaluated before any requests are made, they cannot refer to the runtime properties, request, response, or context. For more information, see "Expressions".

runtime expression

Expression evaluated at runtime, for each request and response.

Runtime expressions can refer to the same information as configuration expressions, plus the following objects:

Value Expressions

A value expression references a value relative to the scope supplied to the expression. For example, "${request.method}" references the method of an incoming HTTP request.

An lvalue-expression is a specific type of value expression that references a value to be written. For example, "${session.gotoURL}" specifies a session attribute named gotoURL to write a value to. Attempts to write values to read-only values are ignored.

Indexed Properties

Properties of values are accessed using the . and [] operators, and can be nested arbitrarily.

The value expressions "${request.method}" and "${request['method']}" are equivalent.

To prevent errors, in property names containing characters that are also expression operators, use the [] operator instead of the . operator. For example, use contexts.amSession.properties['a-b-c'] instead of contexts.amSession.properties.a-b-c.

In the case of arrays, the index of an element in the array is expressed as a number in brackets. For example, "${request.headers['Content-Type'][0]}" references the first Content-Type header value in a request. If a property does not exist, then the index reference yields a null (empty) value.

Operators

Universal Expression Language provides the following operators:

  • Index property value: [], .

  • Change precedence: ()

  • Arithmetic: + (binary), - (binary), *, /, div, %, mod, - (unary)

  • Logical: and, &&, or, ||, not, !

  • Relational: ==, eq, !=, ne, <, lt, >, gt, <=, le, >=, ge

  • Empty: empty

    Prefix operation that can be used to determine whether a value is null or empty.

  • Conditional: ?, :

Operators have the following precedence, from highest to lowest, and from left to right:

  • [] .

  • ()

  • - (unary) not ! empty

  • * / div % mod

  • + (binary) - (binary)

  • < > <= >= lt gt le ge

  • == != eq ne

  • && and

  • || or

  • ? :

System Properties and Environment Variables

You can use expressions to retrieve Java system properties, and to retrieve environment variables.

For system properties, ${system['property']} yields the value of property, or null if there is no value for property. For example, ${system['user.home']} yields the home directory of the user running the application server for IG.

For environment variables, ${env['variable']} yields the value of variable, or null if there is no value for variable. For example, ${env['HOME']} yields the home directory of the user running the application server for IG.

Token Resolution

Runtime expressions have access to evaluated configuration tokens described in "JSON Evaluation". For example, the following boolean expression returns true if the configuration token my.status.code resolves to 200:

${integer(_token.resolve('my.status.code', '404')) == 200}

Functions

A number of built-in functions described in "Functions" can be called within an expression.

The syntax is ${function(parameter, ...)}, where zero or more parameters are supplied to the function. For example:

  • "${bool(env['ENABLE_TIMER'])}" recovers the environment variable "ENABLE_TIMER" and transforms it into a boolean

  • "${toLowerCase(request.method)}" yields the method of the request, converted to lower case.

Functions can be operands for operations, and can yield parameters for other function calls.

Escaping Literal Expressions

The character \ is treated as an escape character when it is followed by ${ or #{. For example, the expression ${true} normally evaluates to true. To include the string ${true} in an expression, write ${true}

When the character \ is followed by any other character sequence, it is not treated as an escape character. For example, ${ evaluates to ${, but \$ evaluates to \$.

Embedding Expressions

Consider the following points when embedding expressions:

  • System properties, environment variables, or function expressions can be embedded within expressions.

    The following example embeds an environment variable in the argument for a read() function. The value of entity is set to the contents of the file $HOME/.openig/html/defaultResponse.html, where $HOME/.openig is the instance directory:

    "entity": "${read('&{ig.instance.dir}/html/defaultResponse.html')}"
  • Expressions cannot be embedded inside other expressions, as ${expression}.

  • Embedded elements cannot be enclosed in ${}.

Extensions

IG offers a plugin interface for extending expressions. See "Key Extension Points".

If your deployment uses expression plugins, read the plugin documentation about the additional expressions you can use.

Examples

"${request.uri.path == '/wordpress/wp-login.php'
   and request.form['action'][0] != 'logout'}"

"${request.uri.host == 'wiki.example.com'}"

"${request.cookies[keyMatch(request.cookies,'^SESS.*')][0].value}"

"${toString(request.uri)}"

"${request.method == 'POST' and request.uri.path == '/wordpress/wp-login.php'}"

"${request.method != 'GET'}"

"${request.headers['cookie'][0]}"

"${request.uri.scheme == 'http'}"

"${not (response.status.code == 302 and not empty session.gotoURL)}"

"${response.headers['Set-Cookie'][0]}"

"${request.headers['host'][0]}"

"${not empty system['my-variable'] ? system['my-variable'] : '/path/to'}/logs/gateway.log"

More Information

For more information, see "Contexts", "Functions", "Request", and "Response".

Read a different version of :