Expressions Many configuration parameters support dynamic expressions. Expressions — expression configuration parameter values Description 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}". 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. 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. Operations Universal Expression Language supports arbitrarily complex arithmetic, logical, relational and conditional operations. They are, in order of precedence: Index property value: [], . Change precedence of operation: () Unary negative: - Logical operations: not, !, empty Arithmetic operations: *, /, div, %, mod Binary arithmetic operations: +, - Relational operations: <, >, ⇐, >=, lt, gt, le, ge, ==, !=, eq, ne Logical operations: &&, and, ||, or Conditional operations: ?, : 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 OpenIG. 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 OpenIG. Functions A number of built-in functions described in Functions(5) can be called within an expression. Syntax is ${function(parameter, …)}, where zero or more parameters are supplied to the function. For example, "${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 Use the backslash \ character as the escape character. For example, ${true} as an expression normally evaluates to true. To include the string ${true} in an expression, write ${true}. You can also escape literal expressions by single-quoting the initial characters. For example, ${'${'}true} evaluates to ${true}. To include a single backslash \ character, write ${'\\'}. To include a double backslash, write ${'\\\\'}. Embedding Expressions Although an expression cannot be embedded as ${expression} inside another expression, embedding system property, environment variable, and function expressions within each other is fine. Do not enclose the embedded elements in ${}. The following single line example embeds an env environment variable expression and the Java String.concat() method in the argument to a read() function: "entity" : "${read(env['OPENIG_BASE'].concat('/html/defaultResponse.html'))}" In the example the entity property value is set to the contents of the file $OPENIG_BASE/html/defaultResponse.html. Extensions OpenIG offers a plugin interface for extending expressions. See Key Extension Points in the Gateway Guide. 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['OPENIG_BASE'] ? system['OPENIG_BASE'] : '/path/to'}/logs/gateway.log" See Also Contexts(5), Functions(5), Request(5), Response(5) Functions — built-in functions to call within expressions Description A set of built-in functions that can be called from within expressions, which are described in Expressions(5). array array(strings...) Returns an array of the strings given as argument. .Parameters strings the strings to put in the array. Returns array the resulting array of containing the given strings. contains contains(object, value) Returns true if the object contains the specified value. If the object is a string, a substring is searched for the value. If the object is a collection or array, its elements are searched for the value. .Parameters object the object to be searched for the presence of. value the value to be searched for. Returns true if the object contains the specified value. decodeBase64 decodeBase64(string) Returns the base64-decoded string, or null if the string is not valid Base64. .Parameters string The base64-encoded string to decode. Returns string The base64-decoded string. encodeBase64 encodeBase64(string) Returns the base64-encoded string, or null if the string is null. .Parameters string The string to encode into Base64. Returns string The base64-encoded string. formDecodeParameterNameOrValue formDecodeParameterNameOrValue(string) Returns the string that results from decoding the provided form encoded parameter name or value as per application/x-www-form-urlencoded, which can be null if the input is null. .Parameters string the parameter name or value Returns string The string resulting from decoding the provided form encoded parameter name or value as per application/x-www-form-urlencoded. formEncodeParameterNameOrValue formEncodeParameterNameOrValue(string) Returns the string that results from form encoding the provided parameter name or value as per application/x-www-form-urlencoded, which can be null if the input is null. .Parameters string the parameter name or value Returns string The string resulting from form encoding the provided parameter name or value as per application/x-www-form-urlencoded. indexOf indexOf(string, substring) Returns the index within a string of the first occurrence of a specified substring. .Parameters string the string in which to search for the specified substring. substring the value to search for within the string. Returns number the index of the first instance of substring, or -1 if not found. The index count starts from 1, not 0. join join(strings, separator) Joins an array of strings into a single string value, with a specified separator. .Parameters separator the separator to place between joined elements. strings the array of strings to be joined. Returns string the string containing the joined strings. keyMatch keyMatch(map, pattern) Returns the first key found in a map that matches the specified regular expression pattern, or null if no such match is found. .Parameters map the map whose keys are to be searched. pattern a string containing the regular expression pattern to match. Returns string the first matching key, or null if no match found. length length(object) Returns the number of items in a collection, or the number of characters in a string. .Parameters object the object whose length is to be determined. Returns number the length of the object, or 0 if length could not be determined. matchingGroups matchingGroups(string, pattern) Returns an array of matching groups for the specified regular expression pattern applied to the specified string, or null if no such match is found. The first element of the array is the entire match, and each subsequent element correlates to any capture group specified within the regular expression. .Parameters string the string to be searched. pattern a string containing the regular expression pattern to match. Returns array an array of matching groups, or null if no such match is found. matches matches(string, pattern) Returns true if the string contains a match for the specified regular expression pattern. .Parameters string the string to be searched. pattern a string containing the regular expression pattern to find. Returns true if the string contains the specified regular expression pattern. read read(string) Takes a file name as a string, and returns the content of the file as a plain string, or null on error (due to the file not being found, for example). Either provide the absolute path to the file, or a path relative to the location of the Java system property user.dir. .Parameters string The name of the file to read. Returns string The content of the file or null on error. readProperties readProperties(string) Takes a Java Properties file name as a string, and returns the content of the file as a key/value map of properties, or null on error (due to the file not being found, for example). Either provide the absolute path to the file, or a path relative to the location of the Java system property user.dir. For example, to get the value of the key property in the properties file /path/to/my.properties, use ${readProperties('/path/to/my.properties')['key']}. .Parameters string The name of the Java Properties file to read. Returns object The key/value map of properties or null on error. split split(string, pattern) Splits the specified string into an array of substrings around matches for the specified regular expression pattern. .Parameters string the string to be split. pattern the regular expression to split substrings around. Returns array the resulting array of split substrings. toLowerCase toLowerCase(string) Converts all of the characters in a string to lower case. .Parameters string the string whose characters are to be converted. Returns string the string with characters converted to lower case. toString toString(object) Returns the string value of an arbitrary object. .Parameters object the object whose string value is to be returned. Returns string the string value of the object. toUpperCase toUpperCase(string) Converts all of the characters in a string to upper case. .Parameters string the string whose characters are to be converted. Returns string the string with characters converted to upper case. trim trim(string) Returns a copy of a string with leading and trailing whitespace omitted. .Parameters string the string whose white space is to be omitted. Returns string the string with leading and trailing white space omitted. urlDecode urlDecode(string) Returns the URL decoding of the provided string. This is equivalent to "formDecodeParameterNameOrValue". .Parameters string The string to be URL decoded, which may be null. Returns string The URL decoding of the provided string, or null if string was null. urlEncode urlEncode(string) Returns the URL encoding of the provided string. This is equivalent to "formEncodeParameterNameOrValue". .Parameters string The string to be URL encoded, which may be null. Returns string The URL encoding of the provided string, or null if string was null. urlDecodeFragment urlDecodeFragment(string) Returns the string that results from decoding the provided URL encoded fragment as per RFC 3986, which can be null if the input is null. .Parameters string the fragment Returns string The string resulting from decoding the provided URL encoded fragment as per RFC 3986. urlDecodePathElement urlDecodePathElement(string) Returns the string that results from decoding the provided URL encoded path element as per RFC 3986, which can be null if the input is null. .Parameters string the path element Returns string The string resulting from decoding the provided URL encoded path element as per RFC 3986. urlDecodeQueryParameterNameOrValue urlDecodeQueryParameterNameOrValue(string) Returns the string that results from decoding the provided URL encoded query parameter name or value as per RFC 3986, which can be null if the input is null. .Parameters string the parameter name or value Returns string The string resulting from decoding the provided URL encoded query parameter name or value as per RFC 3986. urlDecodeUserInfo urlDecodeUserInfo(string) Returns the string that results from decoding the provided URL encoded userInfo as per RFC 3986, which can be null if the input is null. .Parameters string the userInfo Returns string The string resulting from decoding the provided URL encoded userInfo as per RFC 3986. urlEncodeFragment urlEncodeFragment(string) Returns the string that results from URL encoding the provided fragment as per RFC 3986, which can be null if the input is null. .Parameters string the fragment Returns string The string resulting from URL encoding the provided fragment as per RFC 3986. urlEncodePathElement urlEncodePathElement(string) Returns the string that results from URL encoding the provided path element as per RFC 3986, which can be null if the input is null. .Parameters string the path element Returns string The string resulting from URL encoding the provided path element as per RFC 3986. urlEncodeQueryParameterNameOrValue urlEncodeQueryParameterNameOrValue(string) Returns the string that results from URL encoding the provided query parameter name or value as per RFC 3986, which can be null if the input is null. .Parameters string the parameter name or value Returns string The string resulting from URL encoding the provided query parameter name or value as per RFC 3986. urlEncodeUserInfo urlEncodeUserInfo(string) Returns the string that results from URL encoding the provided userInfo as per RFC 3986, which can be null if the input is null. .Parameters string the userInfo Returns string The string resulting from URL encoding the provided userInfo as per RFC 3986. Javadoc Some functions are provided by org.forgerock.openig.el.Functions. Other functions are provided by org.forgerock.http.util.Uris. Patterns — regular expression patterns Description Patterns in configuration parameters and expressions use the standard Java regular expression Pattern class. For more information on regular expressions, see Oracle’s tutorial on Regular Expressions. Pattern Templates A regular expression pattern template expresses a transformation to be applied for a matching regular expression pattern. It may contain references to capturing groups within the match result. Each occurrence of $g (where g is an integer value) is substituted by the indexed capturing group in a match result. Capturing group zero "$0" denotes the entire pattern match. A dollar sign or numeral literal immediately following a capture group reference can be included as a literal in the template by preceding it with a backslash ( \ ). Backslash itself must be also escaped in this manner. See Also Java Pattern class Regular Expressions tutorial Miscellaneous Heap Objects Requests, Responses, and Contexts