Thursday, 20 October 2011

Custom reference resolver tutorial

Introduction


In the previous blog text, I described the cross field validation feature of ExtVal. In the meantime, the reference resolver add-on is released and this text shows how you can write your custom reference resolver.
And since the usage of the add-on API is easy, we are aiming a little bit higher with our example as a simple hello world. I'll explain you how you can write a resolver that checks a value stored in an MBean object.

Coding it

The reference resolver api is described here in the project documentation. There is just one method that you need to implement, resolveReference. The first parameter contains the string defined in the value attribute of the annotation (or method is repeatedly called for each string defined in the case of multiple values)


ReferencedValue resolveReference(final String targetValue, final MetaDataEntry metadataEntry);
So, first we have to 'invent' our indication how we will describe the property of the MBean where the value is stored. A possibility is using mbean@property where mbean is just the name in a certain node of our MBean server.

Our implementation of the method needs to do 3 things

  1. Get a reference to the MBean server of our environment
  2. Split the parameter in 2 parts (around the @ sign)
  3. Lookup the MBean and retrieve the value of the specified property.
If you aren't familiar with accessing JMX beans, you can find various documents on internet which explain it in detail. For this example, you can have a look at the source code placed in an apache extra repository (link). The implementation of our resolver is in the class org.os890.extval.addon.demo.resolver.MBeanReferenceResolver.

Before we can use this new resolver, we have to define a validationParameter so that we are able to use it in the cross field annotations of ExtVal. It is described in the add-on documentation on the referenceResolver page.

In our case, it results in:

public class MBeanReferenceResolver implements ReferenceResolver
{
    public interface MBeanReferenceResolverParameter extends ValidationParameter
    {
       @ParameterKey
       public Class KEY = ReferenceResolver.class;

       @ParameterValue
        public Class referenceResolverClass = MBeanReferenceResolver.class;
    }

     @Override
      public ReferencedValue resolveReference(String targetValue, MetaDataEntry metadataEntry)
      {
         // Implementation details omitted
       }
}
Now we can use this resolver in all cross field annotations like @Equals. In the example you can find a usage in the class org.os890.extval.addon.demo.view.BackingBean.

@Equals(value = "demo@TargetValue", parameters = MBeanReferenceResolver.MBeanReferenceResolverParameter.class)
private String source;
This property is linked to an inputField on a screen in the example.

Testing it

Now we are ready to run the example. If we press the 'Submit' button, a comparison will be made between the entered value and the value which is by default set in the MBean, which is 'ExtVal'. If they don't match, you see the message that the input is different.

This default value is set by the class org.os890.extval.addon.demo.startup.MBeanResolverStartupListener which is defined as JSF PhaseListener in the faces config file.

The following steps makes this example interesting. You can start up the default JMX console of your environment (look for the JConsole program) or any other JMX console that is able to connect to your (application) server. You will find between all the other MBeans, the one created by the demo application in the org.os890.extval.reference.addon node. It is called demo. The property TargetValue can be changed to another value, let's say 'Test'. If you now go back to your browser you will see that the comparison now only succeed with the new value 'Test' that you have entered in the JMX bean.

Conclusion
 This example shows how easy it is to create a new reference resolver and integrate it in ExtVal.  With the add-on you can create any reference you like that needs to be used by the cross field validation feature of ExtVal.