uk.ac.sheffield.jast.xpath

Class XPathRule

java.lang.Object

uk.ac.sheffield.jast.xpath.XPathRule

Direct Known Subclasses:

AbsolutePathRule, AttributeAxisRule, ContentAxisRule, ParentAxisRule, SelfAxisRule, SubtreeAxisRule

public abstract class XPathRule
extends java.lang.Object

XPathRule is the abstract ancestor of all XPath pattern-matching rules. An XPathRule represents a compiled segment of an XPath pattern, denoting a single step taken along one of the supported XPath axes. Each kind of rule has an apply(Content) method, which applies the rule to a given context node, and returns a list of nodes, possibly empty, that satisfy the rule. A compiled XPath consists of a list of XPathRules.

A rule may simply navigate to the target node set, by completing a step along one of the supported XPath axes. More commonly, a rule will apply one or more Filter constraints to the target node set. The various kinds of Filter implement the node test (for the desired node-type), or a more general predicate on the name or value of the node, or even a sophisticated restriction on the dependent attributes or children of the desired node.

Whereas each rule typically returns a set of matching nodes, XPathRule supports the ability to select a single node from the matching set, at a given position. The position is indexed either from the front, using a positive integer 1..n, or indexed from the back, using a negative integer -1..-n. The position zero indicates the last position in the matching list of nodes. A position restriction is always applied last, after the rule's other filters have determined the matching list. A consequence of this is that complex XPath patterns that add further predicates in the same step, after a position restriction, must be split over two XPathRules. This is handled automatically by XPath, when it compiles the pattern.

Version:

2.5

Author:

Anthony J H Simons

Field Summary

Fields

Modifier and Type	Field and Description
private IndexFilter	counter The IndexFilter used to select one from a list of results.
protected Filter	filter The filter used to restrict the current context node.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	XPathRule() Creates a default XPathRule that accepts any legal XPath context node.
protected	XPathRule(Filter restriction) Creates an XPathRule that accepts only nodes restricted by a filter.

Method Summary

Modifier and Type	Method and Description
java.util.List<Content>	apply(Content context) Applies this rule to the context node, returning any matching nodes.
void	broaden(Filter broadening) Broadens the current applicable contexts by adding a Filter.
Filter	getFilter() Returns the filter being used by this XPathRule.
void	restrict(Filter restriction) Restricts the current applicable contexts by adding a Filter.
java.lang.String	toString() Returns a pretty representation of this XPathRule.

Methods inherited from class java.lang.Object

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

Field Detail

filter

protected Filter filter

The filter used to restrict the current context node.

counter

private IndexFilter counter

The IndexFilter used to select one from a list of results. If the index of the IndexFilter is positive, will count forwards from the start; and if the index is zero or negative, will count backwards from the end of the list of results.

Constructor Detail

XPathRule

protected XPathRule()

Creates a default XPathRule that accepts any legal XPath context node. The W3C XPath specification defines this as any Content-node apart from the XML Declaration or Doctype nodes, which cannot be addressed by XPath.

XPathRule

protected XPathRule(Filter restriction)

Creates an XPathRule that accepts only nodes restricted by a filter.

Parameters:

restriction - a restriction on the context node.

Method Detail

getFilter

public Filter getFilter()

Returns the filter being used by this XPathRule.

Returns:

a filter.

apply

public java.util.List<Content> apply(Content context)

Applies this rule to the context node, returning any matching nodes. By default, returns an empty list. This method is redefined in every subclass of XPathRule to return a result list matching the rule's search pattern.

Parameters:

context - the current node, known as the context.

Returns:

a list of XML nodes satisfying the rule.

restrict

public void restrict(Filter restriction)

Restricts the current applicable contexts by adding a Filter. Installs a new restriction which is the conjunction of the existing restriction and the new Filter.

Parameters:

restriction - the extra restriction to apply.

broaden

public void broaden(Filter broadening)

Broadens the current applicable contexts by adding a Filter. Installs a new restriction which is the disjunction of the existing restriction and the new Filter.

Parameters:

broadening - the alternative restriction to apply.

toString

public java.lang.String toString()

Returns a pretty representation of this XPathRule. By default, this is the class-name of the rule, followed by any Filters in braces.

Overrides:

toString in class java.lang.Object