OGNL (and MVEL) Guide

Introduction

iScreen utilizes the OGNL library for Java object references. It also uses the MVFLEX Expression Language (MVEL). Though this guide describes the use of OGNL, it is basically the same for the MVEL library. The primary difference is that where OGNL uses ${} for embedding expressions, MVEL uses @{}. Both are powerful libraries for accessing objects and object graphs.

For a more detailed explanation and guide to the OGNL library, see the OGNL website.

For a more detailed explanation of MVEL, see the MVEL website.

The Basics

OGNL utilizes an "expression" that defines the object graph that needs to be followed in order to either get or set data. This "expression" assumes a Java instance, called the "root." In iScreen, the actual OGNL root being used by a particular OGNL expression is dependent upon the context. In general, it's either the Java instance that's being validated, or it's a special OGNL root object called ContextBean (the full name is org.iscreen.impl.ContextBean).

A simple example of an OGNL expression would be the JavaBean property, such as "myProperty". A more complex expression might reference properties that are "deeper," such as "myProperty.deeperProperty". Referencing data in collections, arrays, maps, static methods, etc. are all possible. See the OGNL website for greater detail on what can be done.

Fundamentally, the OGNL expression acts upon the OGNL root to either get a property or set a property on that root. In one example within iScreen (more details later), one OGNL expression acts as a "getter" on one OGNL root, and another expression acts as a "setter" on a different OGNL root.

The org.iscreen.impl.ContextBean Object

The ContextBean object has a number of properties, some of which are "valid" at different times within the validation process. For exact detail, see the JavaDoc on the ContextBean class.

The primary properties of the ContextBean object are:

• label -- The Label property represents the configured label in the XML configuration file. It's available throughout the validation process (it's set during configuration of the service).
• bean -- The Bean property is the Java object being validated. It can be referenced throughout the validation process, though it's not set until right before validation.
• validator -- The Validator property is a reference to the configured validator that's about to be called for validation. It is available during the validation process where the specific validator is being called.
• failure -- The Failure property refers to the failure object supplied by the Validator during validation. When a Validator reports a validation failure, it calls the ValidatorContext's reportFailure() method. One possible parameter to this method is a "failure object," which is an instance of an object that the Validator needs to communicate to the failure message that needs to be generated. For example, the StringValidator, when reporting a failure when a String is not long enough (a minimum length failure), would supply the required minimum length as an Integer object as the failure object. This object can be referenced within a failure message like this: "The minimum length must be ${failure} characters long." The failure object is available only for failure messages.
• fields -- The Fields property refers to the OGNL getters on the mappings of a configured validator. They're useful for mapping the UI to an individual field that was validated. However, their usefullness is limited since they are OGNL expressions. The label should perform this capability better.
• index -- The Index property is only set and valid if a validation set is forwarding a validation to another validation set and is iterating over a collection or array. In that case, the index refers to the particular loop (for example, the first iteration through the collection/array will have an index of zero, etc.).

Where It's Used

There are two basic places where OGNL can be found: the XML configuration, and within individual messages in resources.

OGNL In Messages

OGNL can be used within resources (property files) by embedding OGNL expressions using the ${expression} approach. In all cases, the OGNL root used for messages, whether they are embedded within a properties file or directly within the XML configuration file (but as part of a resource), is the ContextBean object.

To embed OGNL expressions in messages, the OGNL expression is embedded within braces, like this: ${OGNL expression}. For example, to embed the label and the failure object within a message, the failure message might look like this: "The ${label} field failed because of ${failure}." Note that the OGNL expression root is the ContextBean object, described above.

OGNL In Configuration

OGNL is used through the XML configuration file for referencing properties of the Java instance being validated, or the properties of the ContextBean object. In addition, it's also used when mapping properties from a Java instance to the beanToValidate prior to validation.

Mapping -- The mapping element of the XML configuration is used to map properties on the Java instance (typically a JavaBean) to properties on the "bean to validate" that is created by a Validator prior to validation. The mapping element has two attributes: a 'to' and a 'from' attribute. The 'to' attribute refers to the "bean to validate" object and is a 'setter' OGNL expression with that object as the OGNL root. The 'from' attribute refers to the Java instance being validated, and is a 'getter' OGNL expression on it. The default value for the 'from' attribute is #root, which means the Java instance being validated (itself, not any of its properties). The default value for the 'to' attribute is 'value,' which implies the use of the default org.iscreen.SimpleBean object (it only has one property, which is 'value').

Validation Set Forwarding -- When forwarding to another validation set from within another validation set, there are a couple of attributes on the 'use-validation-set' element that use OGNL expressions. The first is the 'map' attribute, which maps a property (using an OGNL expression) on the Java instance being validated to the Java instance that the forwarded validation set actually acts upon (so, the "parent" validation set acts upon the "parent" Java instance, and the "child" validation set acts upon the "child" Java instance). By default, the 'map' attribute is #root, which means the Java instance, itself, is forwarded. The other attribute is 'if,' which is used as a conditional as to whether the forwarded validation set is actually used or not. The 'if' attribute is an OGNL expression that must be convertable to a boolean value. If true, then the forwarding occurs. If false, it does not. If it's not specified, it defaults to true. The OGNL root for the 'if' attribute is the Java instance being validated (or, more specifically, the Java instance that the validation set is validating).

Constraints -- The constraint element has an attribute called 'property' which is an OGNL expression for setting purposes on the Validator. It's used to set a contraint (really, it's just a property) on the Validator as part of its configuration. The ContextBean used in this expression is the Validator instance, itself.

Failures -- The failure element is exactly like the contraint element, so it has an attribute called 'property' that acts in the same way that a constraint does. The only real difference between these is to differentiate between what's being done and used. The failure object type is somewhat fixed, where the constraint can be of different types.