Reading Devin Olson's recent series on EL processing put me in the mood to refresh and fill out my knowledge of how that stuff actually happens.
A while back, I made a small foray of my own into explaining how property resolution in XPages EL works, one which I followed up with a mea culpa explaining that I had left out a few additional supported types. As happens frequently, that still didn't cover the full story. Before getting to what I mean by that, I'll step back to an overview of XPages EL in general.
Components of EL Processing
To my knowledge, there are three main conceptual pieces to the EL-resolution process. I'll use the EL #{foo.bar.baz[1]} as a common example.
- The EL parser itself. This is what reads the EL above and determines that you want the
1-indexed property of the baz property of the bar property of the foo object. I don't know if there's a realistic way to override or extend this stock-EL behavior.
- This does, though contain an extensible side path: BindingFactory. This lets you create your own processors for value and method bindings based on the EL prefix, in the same vein as
#{javascript: ... }.
- The
VariableResolver. This is a relatively-common bit of XPages extensibility and for good reason: they're quite useful. The variable resolver is what is used by EL (and SSJS, and others) to determine what object is referenced by foo in the example.
- The
PropertyResolver. This is the companion to the VariableResolver and is what handles the rest of the dereferencing in the example. EL asks the app's property resolver to find the bar property of foo, then the baz property of that, and then the 1 indexed property of that. This is the main topic of conversation today.
Setting An Application's PropertyResolver
There are two main ways I know of to make use of property resolvers, and the first is analogous to the VariableResolver: you write a single object and specify it in your faces-config file, like so:
<application>
<property-resolver>config.PropResolver</property-resolver>
</application>
Then the skeletal implementation of such an object looks like this:
package config;
import javax.faces.el.EvaluationException;
import javax.faces.el.PropertyNotFoundException;
import javax.faces.el.PropertyResolver;
public class PropResolver extends PropertyResolver {
private final PropertyResolver delegate_;
public PropResolver(PropertyResolver delegate) {
delegate_ = delegate;
}
@Override
public Class<?> getType(Object obj, Object property) throws EvaluationException, PropertyNotFoundException {
return delegate_.getType(obj, property);
}
@Override
public Class<?> getType(Object obj, int index) throws EvaluationException, PropertyNotFoundException {
return delegate_.getType(obj, index);
}
@Override
public Object getValue(Object obj, Object property) throws EvaluationException, PropertyNotFoundException {
return delegate_.getValue(obj, property);
}
@Override
public Object getValue(Object obj, int index) throws EvaluationException, PropertyNotFoundException {
return delegate_.getValue(obj, index);
}
@Override
public boolean isReadOnly(Object obj, Object property) throws EvaluationException, PropertyNotFoundException {
return delegate_.isReadOnly(obj, property);
}
@Override
public boolean isReadOnly(Object obj, int index) throws EvaluationException, PropertyNotFoundException {
return delegate_.isReadOnly(obj, index);
}
@Override
public void setValue(Object obj, Object property, Object value) throws EvaluationException, PropertyNotFoundException {
delegate_.setValue(obj, property, value);
}
@Override
public void setValue(Object obj, int index, Object value) throws EvaluationException, PropertyNotFoundException {
delegate_.setValue(obj, index, value);
}
}
If you've done much with DataObjects, you'll likely immediately recognize those methods: I imagine that DataObject was created as a simplest-possible implementation of a PropertyResolver-friendly interface.
So how might you use this? Well, most of the time, you probably shouldn't - in my experience, the standard property resolver is sufficient and using DataObject in custom objects is easy enough that it's the best path. Still, you could use this to patch the behavior that is driving Devin to madness or to paint over other persistent annoyances. For example, DominoViewEntry contains hard-coded properties for accessing the entry's Note ID, but not its cluster-friendly Universal ID. To fix this, you could override the non-indexed getValue method like so:
public Object getValue(Object obj, Object property) throws EvaluationException, PropertyNotFoundException {
if (obj instanceof DominoViewEntry && "documentId".equals(property)) {
return ((DominoViewEntry) obj).getUniversalID();
}
return delegate_.getValue(obj, property);
}
Now, anywhere where you have a DominoViewEntry, you can use #{viewEntry.documentId} to get the UNID. You could do the same for DominoDocument as well, if you were so inclined. You'll just have to plan to never have a column or field named "documentId" (much like you currently have to avoid "openPageURL", "columnIndentLevel", "childCount", "noteID", "selected", "responseLevel", "responseCount", and "id").
Property Resolver Factories
The other way to use PropertyResolvers is to register and use a PropertyResolverFactory. Unlike the faces-config approach, these do not override (all of) the default behavior, but are instead looked up by IBM's PropertyResolver implementation at a point during its attempts at property resolution. Specifically, that point is after support for ResourceBundle, ViewRowData, and DataObject and before delegation to Sun's stock resolver (which handles Maps, Lists, arrays, and generic POJOs).
If you get a type hierarchy, you can see that IBM uses this route for lotus.domino.Document, com.ibm.commons.util.io.json.JsonObject, and com.ibm.jscript.types.FBSObject (SSJS object) support. So the idea of this route is that you'd have your own custom object type which doesn't implement any of the aforementioned interfaces and for which you want to provide EL support beyond the normal getter/setter support. Normally, this is not something worth doing, but I could see it being useful if you have a third-party class you want to work in, such as a non-Domino/JDBC data source.
The method for actually using one of these is... counterintuitive, but is something you may have run into in plugin development. The first step is simple enough: implement the factory:
package config;
import javax.faces.el.PropertyResolver;
import com.ibm.xsp.el.PropertyResolverFactory;
public class PropResolverFactory implements PropertyResolverFactory {
public PropertyResolver getPropertyResolver(Object obj) {
return null;
}
}
That getPropertyResolver method's job is to check to see if the object is one of the types it supports and, if it is, return a PropertyResolver object (the same kind as above) that will allow the primary resolver to get the property.
Actually registering the factory is weirder. It must be done via a plugin (or by code that manually registers it in the application when needed), and the best way to see what I mean is to take a look at an example: the OpenntfDominoXspContributor class used by the OpenNTF Domino API. The contributor is registered in the plugin.xml and returns an array of arrays (because Java doesn't have tuples or map literals) representing a unique name for your factory plus the implementing class.
This concept of factories actually probably warrants its own blog post down the line. For the time being, the upshot is that this approach is appropriate if you're adding your own data type via a plugin (and which wouldn't be better-suited to implement DataObject), so it's a rare use case indeed.