net.sf.practicalxml.xpath

Class FunctionResolver

java.lang.Object

net.sf.practicalxml.xpath.FunctionResolver

All Implemented Interfaces:

Cloneable, XPathFunctionResolver

public class FunctionResolver
extends Object
implements XPathFunctionResolver, Cloneable

An XPathFunctionResolver that is intended to be easily configured (using the Builder pattern), can support multiple functions with the same name but different arity, and provides a simplified interface for functions that know their own name (ie, subclasses of AbstractFunction.

When holding functions that have the same name but different arity ranges, the resolver first looks for the smallest enclosing range, followed by the range with the smallest initial value. For example, given registrations of function "foo:bar", with arity ranges 1:1, 2:6, 2:7, and 5:10, resolveFunction() will act as follows:

• given 1, returns the function registered with 1:1, because it's the only match.
• given 2, returns the function registered with 2:6 because it coveres the smallest range. Ditto with calls for 3 to 6.
• given 7, returns the function registered with 2:7 because it has the lowest starting value.
• given 8, returns the function registered with 5:10 because it's the only match.

Note: no sane person should register functions like that.

Instances of this object are not thread-safe during construction, but are read-only (and therefore thread-safe) during usage.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	FunctionResolver.AbstractSelfDescribingFunction A base implementation of a self-describing function.
static interface	FunctionResolver.SelfDescribingFunction A self-describing function: one that can describe its own name and arity, and compare itself to other self-describing functions.

Constructor Summary

Constructors

Constructor and Description
FunctionResolver()

Method Summary

Methods

Modifier and Type	Method and Description
FunctionResolver	addFunction(FunctionResolver.SelfDescribingFunction func) Adds an instance of of #SelfDescribingFunction to this resolver.
FunctionResolver	addFunction(XPathFunction func, QName name) Adds a normal XPathFunction to this resolver, without specifying argument count.
FunctionResolver	addFunction(XPathFunction func, QName name, int argCount) Adds a normal XPathFunction to this resolver.
FunctionResolver	addFunction(XPathFunction func, QName name, int minArgCount, int maxArgCount) Adds a normal XPathFunction to this resolver.
FunctionResolver	clone() Returns a shallow clone of this object, containing all existing functions in a new lookup table.
boolean	equals(Object obj) Two instances are equal if they have the same number of functions, and each has a counterpart with the same QName and arity range (but not the same implementation).
int	hashCode()
XPathFunction	resolveFunction(QName functionName, int arity) Picks the "most eligble" function of those bound to this resolver.
String	toString() Returns a string that lists this resolver's functions, intended for debugging.

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

FunctionResolver

public FunctionResolver()

Method Detail

addFunction

public FunctionResolver addFunction(FunctionResolver.SelfDescribingFunction func)

Adds an instance of of #SelfDescribingFunction to this resolver. This function provides its own information about name, namespace, and supported number of arguments.

If the same function has already been added, will silently replace it.

Returns:

The resolver, so that calls may be chained.

addFunction

public FunctionResolver addFunction(XPathFunction func,
                           QName name)

Adds a normal XPathFunction to this resolver, without specifying argument count. This function will be chosen for any number of arguments, provided that there is not a more-specific binding).

If a function has already been added with the same name and argument range, this call will silently replace it.

Note: the resolver wraps the passed function with a decorator that allows it to be managed. The resolver will return this decorator object rather than the original function.

Returns:

The resolver, so that calls may be chained.

addFunction

public FunctionResolver addFunction(XPathFunction func,
                           QName name,
                           int argCount)

Adds a normal XPathFunction to this resolver. Specifies the exact number of arguments for which this function will be chosen.

If a function has already been added with the same name and argument range, this call will silently replace it.

Note: the resolver wraps the passed function with a decorator that allows it to be managed. The resolver will return this decorator object rather than the original function.

Returns:

The resolver, so that calls may be chained.

addFunction

public FunctionResolver addFunction(XPathFunction func,
                           QName name,
                           int minArgCount,
                           int maxArgCount)

Adds a normal XPathFunction to this resolver. Specifies the minimum and maximum number of arguments for which this function will be chosen.

If a function has already been added with the same name and argument range, this call will silently replace it.

Note: the resolver wraps the passed function with a decorator that allows it to be managed. The resolver will return this decorator object rather than the original function.

Returns:

The resolver, so that calls may be chained.

resolveFunction

public XPathFunction resolveFunction(QName functionName,
                            int arity)

Picks the "most eligble" function of those bound to this resolver. If unable to find any function that matches, returns null.

Specified by:

resolveFunction in interface XPathFunctionResolver

equals

public final boolean equals(Object obj)

Two instances are equal if they have the same number of functions, and each has a counterpart with the same QName and arity range (but not the same implementation).

Overrides:

equals in class Object

hashCode

public final int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Returns a string that lists this resolver's functions, intended for debugging. The output is similar to that of List.toString(), with each item having the form {NS}NAME(MIN:MAX), where:

• NS is the function's namespace URI
• NAME is the function's localname
• MIN is the minimum arity of the function
• MAX is the maximum arity of the function

Overrides:

toString in class Object

Since:

1.1.12

clone

public FunctionResolver clone()

Returns a shallow clone of this object, containing all existing functions in a new lookup table. Does not attempt to clone the functions themselves; if you create functions that have mutable state, you need to explicitly copy them.

Overrides:

clone in class Object

Since:

1.1.12