net.sf.practicalxml.xpath

Class AbstractFunction<T>

java.lang.Object

net.sf.practicalxml.xpath.FunctionResolver.AbstractSelfDescribingFunction

net.sf.practicalxml.xpath.AbstractFunction<T>

All Implemented Interfaces:

Comparable<FunctionResolver.SelfDescribingFunction>, XPathFunction, FunctionResolver.SelfDescribingFunction

public class AbstractFunction<T>
extends FunctionResolver.AbstractSelfDescribingFunction

A base class for writing XPath functions, using a "template method" approach. Execution goes through the following three stages:

1. Initialization: the subclass method init() is invoked.
2. Input: for each argument, the type-appropriate processArg(int, java.lang.String, T) method is called.
3. Completion: the subclass method getResult(T) is invoked, and its return value is returned from evaluate(java.util.List).

Subclasses define their name, namespace, and the number of arguments they accept (which may be undefined).

To support thread safety, subclasses are expected to make use of a helper object that holds intermediate results. The helper object is created by init(), is an argument to and return from processArg() , and is an argument to getResult(). Subclasses are parameterized with the helper object type, and the default behavior of getResult() is to return the helper (this makes life easier for a function that takes zero or one arguments).

Note: in JDK 1.5, DOM objects implement both Node and NodeList. While this means that processArg(Node) would never be called as part of the normal dispatch loop (unless the implementation changes), it is called as part of the default behavior of processArg(NodeList), and is given the first element in the list.

Implementation note: The design of this class is arguably over-complex. If all you want is a simple function to process string content, use AbstractStringFunction.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractFunction(QName qname, int minArgs, int maxArgs) Base constructor.
protected	AbstractFunction(String nsUri, String localName) Constructor for a function that can take any number of arguments.
protected	AbstractFunction(String nsUri, String localName, int numArgs) Constructor for a function that has a fixed number of arguments.
protected	AbstractFunction(String nsUri, String localName, int minArgs, int maxArgs) Constructor for a function that has a variable number of arguments.

Method Summary

Methods

Modifier and Type	Method and Description
Object	evaluate(List args) Invokes methods defined by the subclasses to evaluate the function.
protected Object	getResult(T helper) Returns the result of this invocation.
protected T	init() Creates a helper object to preserve intermediate results.
protected T	processArg(int index, Boolean value, T helper) Processes a Boolean argument.
protected T	processArg(int index, NodeList value, T helper) Processes a NodeList argument.
protected T	processArg(int index, Node value, T helper) Processes a Node argument.
protected T	processArg(int index, Number value, T helper) Processes a Number argument.
protected T	processArg(int index, String value, T helper) Processes a String argument.
protected T	processNullArg(int index, T helper) Processes a null argument — it's unclear whether this can ever happen.
protected T	processUnexpectedArg(int index, Object value, T helper) Processes an argument that is not one of the defined types for XPath evaluation — it is unclear whether this can actually happen.

Methods inherited from class net.sf.practicalxml.xpath.FunctionResolver.AbstractSelfDescribingFunction

compareTo, equals, getMaxArgCount, getMinArgCount, getName, getNamespaceUri, getQName, hashCode, isArityMatch, isMatch

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractFunction

protected AbstractFunction(String nsUri,
                String localName)

Constructor for a function that can take any number of arguments.

AbstractFunction

protected AbstractFunction(String nsUri,
                String localName,
                int numArgs)

Constructor for a function that has a fixed number of arguments.

AbstractFunction

protected AbstractFunction(String nsUri,
                String localName,
                int minArgs,
                int maxArgs)

Constructor for a function that has a variable number of arguments.

AbstractFunction

protected AbstractFunction(QName qname,
                int minArgs,
                int maxArgs)

Base constructor.

Method Detail

evaluate

public Object evaluate(List args)
                throws XPathFunctionException

Invokes methods defined by the subclasses to evaluate the function. Will invoke the appropriate processArg() method in turn for each argument, then invokes getResult() to retrieve the function's result.

Throws:

XPathFunctionException - if the supplied argument list does not match the min/max for this function, or if any called method throws an exception.

init

protected T init()
          throws Exception

Creates a helper object to preserve intermediate results. This object is passed to processArg() and getResult().

The default implementation returns null.

Subclasses are permitted to throw any exception; it will be wrapped in an XPathFunctionException.

Throws:

Exception

processArg

protected T processArg(int index,
           String value,
           T helper)
                throws Exception

Processes a String argument.

Parameters:

index - Index of the argument, numbered from 0.

value - Value of the argument.

helper - Helper object to preserve intermediate results.

Returns:

The helper object (subclasses may return a replacement).

Throws:

Subclasses - are permitted to throw any exception. It will be wrapped in XPathFunctionException and cause function processing to abort.

Exception

processArg

protected T processArg(int index,
           Number value,
           T helper)
                throws Exception

Processes a Number argument. Per the XPath spec, this should be a Double

Parameters:

index - Index of the argument, numbered from 0.

value - Value of the argument.

helper - Helper object to preserve intermediate results.

Returns:

The helper object (subclasses may return a replacement).

Throws:

Subclasses - are permitted to throw any exception. It will be wrapped in XPathFunctionException and cause function processing to abort.

Exception

processArg

protected T processArg(int index,
           Boolean value,
           T helper)
                throws Exception

Processes a Boolean argument.

Parameters:

index - Index of the argument, numbered from 0.

value - Value of the argument.

helper - Helper object to preserve intermediate results.

Returns:

The helper object (subclasses may return a replacement).

Throws:

Subclasses - are permitted to throw any exception. It will be wrapped in XPathFunctionException and cause function processing to abort.

Exception

processArg

protected T processArg(int index,
           Node value,
           T helper)
                throws Exception

Processes a Node argument. This function will be invoked by the default implementation of processArg(NodeList).

Parameters:

index - Index of the argument, numbered from 0.

value - Value of the argument. May be null.

helper - Helper object to preserve intermediate results.

Returns:

The helper object (subclasses may return a replacement).

Throws:

Subclasses - are permitted to throw any exception. It will be wrapped in XPathFunctionException and cause function processing to abort.

Exception

processArg

protected T processArg(int index,
           NodeList value,
           T helper)
                throws Exception

Processes a NodeList argument.

The default implementation calls processArg(Node) with the first element in the list (null if the list is empty).

Parameters:

index - Index of the argument, numbered from 0.

value - Value of the argument.

helper - Helper object to preserve intermediate results.

Returns:

The helper object (subclasses may return a replacement).

Throws:

Subclasses - are permitted to throw any exception. It will be wrapped in XPathFunctionException and cause function processing to abort.

Exception

processNullArg

protected T processNullArg(int index,
               T helper)
                    throws Exception

Processes a null argument — it's unclear whether this can ever happen. The default implementation throws IllegalArgumentException.

Parameters:

index - Index of the argument, numbered from 0.

helper - Helper object to preserve intermediate results.

Returns:

The helper object (subclasses may return a replacement).

Throws:

Subclasses - are permitted to throw any exception. It will be wrapped in XPathFunctionException and cause function processing to abort.

Exception

processUnexpectedArg

protected T processUnexpectedArg(int index,
                     Object value,
                     T helper)
                          throws Exception

Processes an argument that is not one of the defined types for XPath evaluation — it is unclear whether this can actually happen. The default implementation throws IllegalArgumentException.

Parameters:

index - Index of the argument, numbered from 0.

value - The argument value

helper - Helper object to preserve intermediate results.

Returns:

The helper object (subclasses may return a replacement).

Throws:

Subclasses - are permitted to throw any exception. It will be wrapped in XPathFunctionException and cause function processing to abort.

Exception

getResult

protected Object getResult(T helper)
                    throws Exception

Returns the result of this invocation.

Parameters:

helper - Helper object to preserve intermediate results.

Returns:

The helper object (subclasses may return whatever they want).

Throws:

Subclasses - are permitted to throw any exception. It will be wrapped in XPathFunctionException and cause function processing to abort.

Exception