Thursday 15 September 2011

Cross field validation with JSF and ExtVal

JSF has support for validation built in, but it is limited to a single field. Is it required, is it in the correct range, has it the correct format and so on.

With the MyFaces Extensions Validator framework (ExtVal in short), there is support for cross field validation. You can verify if two fields have the same or different content. Check the relative order of two dates and so on. For the feature we need 2 fields we can compare and this is done by specifying a reference in the annotation on one field to the other field.

And although the current possibilities to specify the other field are sufficient in 99% of your cases, I was already thinking about a mechanism for two years that allows greater flexibility and easier custom implementations.

And since I now have almost completed the Reference Resolver add-on for ExtVal, the time has come to start blogging about the possibilities.

The add-on introduces an interface, the ReferenceResolver, when it comes to resolving the references to the other field in ExtVal. This allows the developer to implement any kind of reference he like. But since the default ExtVal functionality is enough in 99% of the cases, the requirement of the add-on was that it should recognize and correctly evaluates the current system. Backwards compatibility was in this case a requirement.

The Apache Commons JEXL project proved to be the ideal candidate. With some extensions, it correctly handles the default references of ExtVal and allowed some advanced references out of the box.

Cross field validation overview
But the details of the add-on will be explained in the next blog entry/entries I'll make. First I need to explain some concepts of the cross field validation of ExtVal before I can continue with the explanation of the add-on.

So the rest of this blog entry will only explain the default functionality and concepts of ExtVal. You don't need the add-on for this.

An example makes it more clear.

-- Managed Bean
public class ClassicGrammarBean {

     @Equals(value = "target")
     private String source;

     private String target;

     // setters and getters omitted

-- screen

<h:inputText id="source" value="#{bean.source}" label="source"/>
<h:inputText id="target" value="#{}" label="target"/>

If you use the above code, posting the screen will result in an error except when the contents in the 2 fields are the same.

How does it work? ExtVal installs a proxy for each renderer defined in the JSF system. That way, it can perform some action anytime there is a decode or encode request. One of the actions is that after the standard decode method is called, the value is 'verified' against the annotations that are present on the property in the managed bean to which the field is linked.

How is cross field validation then implemented? Another action which is performed after the decode, is that the value is stored by the ProcessedInformationRecorder for later usage. After the JSF validation lifecycle phase, there is a check for any cross field annotations on the properties used in the screen. If so, the required checks are performed based on the values stored by the ProcessedInformationRecorder. Later on I'll make some comments on this principle.

Reference methods
There are 2 options to refer to the other field that is needed in the cross field validation. One is based on EL expression, but first I'll explain the other one.

local reference (javaBean reference)
The example which is presented earlier in this text, is an example of the local reference type. In the value attribute of the annotation, we specify the property name of the other property we like to use in our comparison. Besides the referring to other simple properties (like target in the example) we can reference properties in another class as long as the object is a local property in the bean.

As always, the example makes it very clear what I mean.

public class SubBean {
     private String targetInSub;

     // setter and getter omitted

public class ClassicGrammarBean {

     @Equals(value = "subBean.targetInSub")
     private String source;

     private SubBean subBean;

     // setters and getters ommitted

But not all kind of java references are supported. Besides the above 2 example, the map notation is also supported. But only with a fixed key value, a literal and not a reference to another property. The contents in the value attribute of the annotation then looks like mapProperty.key where key is the string literal of the map key.

EL reference
The El references are more common because we all use them in the JSF pages. But the disadvantage is that the bean name is placed in a string attribute of the annotation. Changing the bean name will break your validation rules, which isn't the case if you can use the local reference method. But there you have the problems when you rename the properties of the bean.

Validation mode
Knowing the possible reference methods isn't enough to understand how the cross field validation works. You basically point to 2 properties of objects but the values aren't yet pushed into them. This is done in the update model phase of the JSF lifecycle which comes after the validation phase.

A very important piece of the cross field functionality is the matching of the EL references used in the JSF pages to link a component to a managed bean property and the reference specified in the attribute of the annotations.

In the case the reference of the annotation couldn't be matched to a value found in the current request, the reference is evaluated and the value stored in the model, the managed bean property in this case, is taken. This is called the model validation mode.

The new Reference Resolver add-on for ExtVal makes it possible to reference any kind of other value for the cross field validation functionality of ExtVal. If you have exotic requirement regarding the other party in the validation rule, you can implement them yourself using the ReferenceResolver interface.

And by default, by using the fine JEXL engine, the backward compatibility is guaranteed and opens the gate for very complex references.

In the next blog entry I'll explain how you can use the value of an MBean in the cross field validation with the new add-on.