org.geotools.xml
Class XPath

java.lang.Object
  org.geotools.xml.XPath

Direct Known Subclasses:

DOMXPath, MetadataXPath

public abstract class XPath

extends java.lang.Object

This class is a General Superclass for implementing XPath Expressions. A Subclass is required to implement getChildren, getNodeName and solve for XPath to be able to locate elements based on xpath expressions. XPath expressions are W3C specification related to XML. This implementation supports a subset of W3C's XPATH specification. A description of the support is as follows:

• Java's Regular expression's are used for matching nodes. See java.regex.Pattern
• Each object in an object tree is a Node
• A path in a object tree is syntactically similar to a unix directory path

  doc/child1/child2

• Each node is matched by comparing a java regular expression to the name of the node returned by the abstract method getNodeName
• Does not support the statement such as ancestor
• Does not support the written for of XPaths: child::name

Some examples of legal and illegal XPath statements: NOTE: For those reading the source code *=*

• doc/*/child2 -> matches node called child2 with a grandparent named doc
• */*/* -> matches any node that is a great-grandchild
• **/child2 -> matches a grandchild whith the name child2

  NOTE: does not have the same semantic meaning as the first example

• d*/c* -> matchs the grandchild starting with a c which has a parent that starts with a d

NOTE: No multiple descendant XPaths are possible. For example: you cannot make an XPath expression that means: "Any descendant that has the name 'child'"

Version:

$Revision: 1.9 $

Author:

Jesse Eichar

See Also:

DOMXPath

Nested Class Summary

class

XPath.NullIterator A convenience class.

Field Summary

protected static int	OP_FIND
protected static int	OP_NODEPATH
protected static int	OP_VALUE

Constructor Summary

protected

XPath(java.lang.String xpath) Splits the xpath string into terms, one for each node to match, and transforms the strings into Regex Patterns.

Method Summary

java.util.List	find(java.lang.Object root) Returns a list of the nodes that are identified by this XPath expression.
protected abstract java.util.Iterator	getChildren(java.lang.Object o) This method is used to get all the child nodes of Object o.
protected abstract java.lang.String	getNodeName(java.lang.Object o) Returns the string which identifies the name.
java.util.regex.Pattern[]	getTerms() Returns all the java.regex.Pattern objects that are used for matching.
protected abstract boolean	isLegalNode(java.lang.Object o, int operation, boolean isList) Tests whether the object passed is a legal node element Legal nodes may differ depending on the type of operation being performed.
protected boolean	nodeMatch(java.util.regex.Pattern term, java.lang.Object o) Checks if the pattern term matches object o's name as returned by the getNodeName() method.
java.util.List	nodePaths(java.lang.Object root) Returns a list of the node paths for all the solutions to the XPath expression In other words all the nodes from the root to the identified node are included in the nodepath If root is a valid object (accepts() returns true) then the object is used as the root and its children are matched against the first term.
protected abstract java.lang.Object	solve(java.util.List path) Given a list of node objects, a value is computed that is the semantic "value" of the path.
java.lang.String	toString() Translates the XPath into string form
java.util.List	value(java.lang.Object root) Returns a list of the values of the nodes that are identified by this XPath expression.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

OP_FIND

protected static final int OP_FIND

See Also:

Constant Field Values

OP_VALUE

protected static final int OP_VALUE

See Also:

Constant Field Values

OP_NODEPATH

protected static final int OP_NODEPATH

See Also:

Constant Field Values

Constructor Detail

XPath

protected XPath(java.lang.String xpath)

Splits the xpath string into terms, one for each node to match, and transforms the strings into Regex Patterns. The patterns are used to match the node names

Parameters:

xpath - the String form of the XPath expression

Method Detail

isLegalNode

protected abstract boolean isLegalNode(java.lang.Object o,
                                       int operation,
                                       boolean isList)

Tests whether the object passed is a legal node element Legal nodes may differ depending on the type of operation being performed.

Parameters:

o - Object to test

operation - one of the OP_XXX constants

Returns:

true if object o is a valid node object

getChildren

protected abstract java.util.Iterator getChildren(java.lang.Object o)

This method is used to get all the child nodes of Object o. It is up to the implementor to decide what a child relationship is. Normally a child is an object referred to by the parent, but this is not a requirement.

Parameters:

o - The object that is considered to be the "Parent." In the case of hierarchical datastructures o will often be a child of another object previously passed to the getChildren method.

Returns:

An immutable iterator that cycles through the list of all the children of object o.

getNodeName

protected abstract java.lang.String getNodeName(java.lang.Object o)

Returns the string which identifies the name. Names do not need to have unique names

Parameters:

o - The object being matched to the current term.

Returns:

The name of the object o in string form.

solve

protected abstract java.lang.Object solve(java.util.List path)

Given a list of node objects, a value is computed that is the semantic "value" of the path. It is up to the implementor to make solve return a meaningful value. The list is the path of nodes, in order, that matches the XPath expression. The first element of the list is the "root" object passed to the value method

Parameters:

path - The list is the path of nodes, in order, that matches the XPath expression. The first element of the list is the "root" object passed to the value method

Returns:

The "value" represented by the input path. For example the "value" of a DOM tree implementation would be the string value of the text node child of the last node in the list. Some cases require that the path be followed and a value computed at each node. Then the final value would be returned. It is up to the implementor to make solve return a meaningful value.

nodeMatch

protected boolean nodeMatch(java.util.regex.Pattern term,
                            java.lang.Object o)

Checks if the pattern term matches object o's name as returned by the getNodeName() method.

Parameters:

term - The pattern to be used to determine a match.

o - The current node being inspected

Returns:

true if the pattern matches object o's name as returned by getNodeName() false otherwise

find

public java.util.List find(java.lang.Object root)

Returns a list of the nodes that are identified by this XPath expression. If root is a valid object (accepts() returns true) then the object is used as the root and its children are matched against the first term. If root is a List then the elements of root are matched against the first term.

Parameters:

root - A Node or a List of Nodes. If root is a Node the children of root are matched against the first term of the XPath expression If root is a list then the elements of root are matched against the first term of the XPath expression

Returns:

null is returned if root is not a list or a node ( accepts() returns false ) A list of Nodes that are identified by the XPath expression

value

public java.util.List value(java.lang.Object root)

Returns a list of the values of the nodes that are identified by this XPath expression. For each identified node the solve method is called on the list of nodes in the node path from root to the Node. Each value returned by solve is added to the list. value() is the same as: List values; List paths=nodePaths(); foreach |path| in paths values.add(solve(path)) If root is a valid object (accepts() returns true) then the object is used as the root and its children are matched against the first term. If root is a List then the elements of root are matched against the first term.

Parameters:

root - A Node or a List of Nodes. If root is a Node the children of root are matched against the first term of the XPath expression If root is a list then the elements of root are matched against the first term of the XPath expression

Returns:

null is returned if root is not a list or a node ( accepts() returns false ) A list of the values of the identified nodes

nodePaths

public java.util.List nodePaths(java.lang.Object root)

Returns a list of the node paths for all the solutions to the XPath expression In other words all the nodes from the root to the identified node are included in the nodepath If root is a valid object (accepts() returns true) then the object is used as the root and its children are matched against the first term. If root is a List then the elements of root are matched against the first term.

Parameters:

root - A Node or a List of Nodes. If root is a Node the children of root are matched against the first term of the XPath expression If root is a list then the elements of root are matched against the first term of the XPath expression

Returns:

null is returned if root is not a list or a node ( accepts() returns false ) A list of the node paths for all the solutions to the XPath expression In other words all the nodes from the root to the identified node are included in the nodepath

getTerms

public java.util.regex.Pattern[] getTerms()

Returns all the java.regex.Pattern objects that are used for matching.

Returns:

all the java.regex.Pattern objects that are used for matching.

toString

public java.lang.String toString()

Translates the XPath into string form

Returns:

XPath is string form