JDOM2 Feature Extended Filter

'Filter' is a concept that has been around for a long time in JDOM. JDOM2 takes the Filter concept and uses it as the foundation for much of the generification process. It does this by extending the Filter interface to have a filter(Object) method in addition to the 'old' match(Object) method. The filter(Object) method is carefully specified: The method returns 'null' if the input value does not match the Filter criteria. The filter returns the input value cast to the Generic type of the Filter if the input value matches the filter critera.

In other words, a Filter<String> instance will return the following types of value from the filter(Object) method:

1. return null for a null input value.
2. return null for any non-String input value
3. return null for any String input value that does not match the filter critera.
4. return the input value cast to String if the input value is a string, and it also matches the filter critera.

The match(Object) method now returns true if filter(Object) != null;

Further, the Filter interface has been expanded with the negate(), and(Filter), or(Filter) and refine(Filter) methods which now formalize much of what the AbstractFilter class did (the AbstractFilter used to define these methods, but now the Filter interface defines them, and the AbstractFilter class overrides them).

These changes will impact anyone who has custom implementations of the Filter interface, but this should be mitigated if they extended the AbstractFilter class rather than a full Filter interface implementation.

This extension initially grew out of the complex requirements for XPath result management. XPath expressions can return all sorts of non-JDOM data, including String, Boolean, and Double. Handling such diverse data in a Generics friendly way is a challenge, but this Filter extension will allow the XPath results to be almost seamlessly integrated.

The usefulness of the Filter concept has been extended in to the entire Generification process of JDOM2, and it is crucial to its success.

In addition to the Filter interface changes, there is also now a factory class called Filters (note the plural) which provides convenient ways to access common Filter instances. All Filter instances returned from the Filters factory are re-entrant and thread-safe, and the Filters factory will re-use these Filter instances where appropriate.