org.jaxen

Interface Navigator

All Superinterfaces:

Serializable

All Known Subinterfaces:

NamedAccessNavigator

All Known Implementing Classes:

DefaultNavigator, DocumentNavigator, DocumentNavigator

public interface Navigator
extends Serializable

Interface for navigating around an arbitrary object model, using XPath semantics.

There is a method to obtain a java.util.Iterator, for each axis specified by XPath. If the target object model does not support the semantics of a particular axis, an UnsupportedAxisException is to be thrown. If there are no nodes on that axis, an empty iterator should be returned.

Version:

$Id$

Author:

bob mcwhirter, James Strachan

Method Summary

Modifier and Type	Method and Description
Iterator	getAncestorAxisIterator(Object contextNode) Retrieve an Iterator matching the ancestor XPath axis.
Iterator	getAncestorOrSelfAxisIterator(Object contextNode) Retrieve an Iterator matching the ancestor-or-self XPath axis.
Iterator	getAttributeAxisIterator(Object contextNode) Retrieve an Iterator matching the attribute XPath axis.
String	getAttributeName(Object attr) Retrieve the local name of the given attribute node.
String	getAttributeNamespaceUri(Object attr) Retrieve the namespace URI of the given attribute node.
String	getAttributeQName(Object attr) Retrieve the qualified name of the given attribute node.
String	getAttributeStringValue(Object attr) Retrieve the string-value of an attribute node.
Iterator	getChildAxisIterator(Object contextNode) Retrieve an Iterator matching the child XPath axis.
String	getCommentStringValue(Object comment) Retrieve the string-value of a comment node.
Iterator	getDescendantAxisIterator(Object contextNode) Retrieve an Iterator matching the descendant XPath axis.
Iterator	getDescendantOrSelfAxisIterator(Object contextNode) Retrieve an Iterator matching the descendant-or-self XPath axis.
Object	getDocument(String uri) Loads a document from the given URI
Object	getDocumentNode(Object contextNode) Returns the document node that contains the given context node.
Object	getElementById(Object contextNode, String elementId) Returns the element whose ID is given by elementId.
String	getElementName(Object element) Retrieve the local name of the given element node.
String	getElementNamespaceUri(Object element) Retrieve the namespace URI of the given element node.
String	getElementQName(Object element) Retrieve the qualified name of the given element node.
String	getElementStringValue(Object element) Retrieve the string-value of an element node.
Iterator	getFollowingAxisIterator(Object contextNode) Retrieve an Iterator matching the following XPath axis.
Iterator	getFollowingSiblingAxisIterator(Object contextNode) Retrieve an Iterator matching the following-sibling XPath axis.
Iterator	getNamespaceAxisIterator(Object contextNode) Retrieve an Iterator matching the namespace XPath axis.
String	getNamespacePrefix(Object ns) Retrieve the namespace prefix of a namespace node.
String	getNamespaceStringValue(Object ns) Retrieve the string-value of a namespace node.
short	getNodeType(Object node) Returns a number that identifies the type of node that the given object represents in this navigator.
Iterator	getParentAxisIterator(Object contextNode) Retrieve an Iterator matching the parent XPath axis.
Object	getParentNode(Object contextNode) Returns the parent of the given context node.
Iterator	getPrecedingAxisIterator(Object contextNode) Retrieve an Iterator matching the preceding XPath axis.
Iterator	getPrecedingSiblingAxisIterator(Object contextNode) Retrieve an Iterator matching the preceding-sibling XPath axis.
String	getProcessingInstructionData(Object pi) Retrieve the data of a processing-instruction.
String	getProcessingInstructionTarget(Object pi) Retrieve the target of a processing-instruction.
Iterator	getSelfAxisIterator(Object contextNode) Retrieve an Iterator matching the self XPath axis.
String	getTextStringValue(Object text) Retrieve the string-value of a text node.
boolean	isAttribute(Object object) Returns whether the given object is an attribute node.
boolean	isComment(Object object) Returns whether the given object is a comment node.
boolean	isDocument(Object object) Returns whether the given object is a document node.
boolean	isElement(Object object) Returns whether the given object is an element node.
boolean	isNamespace(Object object) Returns whether the given object is a namespace node.
boolean	isProcessingInstruction(Object object) Returns whether the given object is a processing-instruction node.
boolean	isText(Object object) Returns whether the given object is a text node.
XPath	parseXPath(String xpath) Returns a parsed form of the given XPath string, which will be suitable for queries on documents that use the same navigator as this one.
String	translateNamespacePrefixToUri(String prefix, Object element) Translate a namespace prefix to a namespace URI, possibly considering a particular element node.

Method Detail

getChildAxisIterator

Iterator getChildAxisIterator(Object contextNode)
                       throws UnsupportedAxisException

Retrieve an Iterator matching the child XPath axis.

Parameters:

contextNode - the original context node

Returns:

an Iterator capable of traversing the axis, not null

Throws:

UnsupportedAxisException - if the semantics of the child axis are not supported by this object model

getDescendantAxisIterator

Iterator getDescendantAxisIterator(Object contextNode)
                            throws UnsupportedAxisException

Retrieve an Iterator matching the descendant XPath axis.

Parameters:

contextNode - the original context node

Returns:

an Iterator capable of traversing the axis, not null

Throws:

UnsupportedAxisException - if the semantics of the desscendant axis are not supported by this object model

getParentAxisIterator

Iterator getParentAxisIterator(Object contextNode)
                        throws UnsupportedAxisException

Retrieve an Iterator matching the parent XPath axis.

Parameters:

contextNode - the original context node

Returns:

an Iterator capable of traversing the axis, not null

Throws:

UnsupportedAxisException - if the semantics of the parent axis are not supported by this object model

getAncestorAxisIterator

Iterator getAncestorAxisIterator(Object contextNode)
                          throws UnsupportedAxisException

Retrieve an Iterator matching the ancestor XPath axis.

Parameters:

contextNode - the original context node

Returns:

an Iterator capable of traversing the axis, not null

Throws:

UnsupportedAxisException - if the semantics of the ancestor axis are not supported by this object model

getFollowingSiblingAxisIterator

Iterator getFollowingSiblingAxisIterator(Object contextNode)
                                  throws UnsupportedAxisException

Retrieve an Iterator matching the following-sibling XPath axis.

Parameters:

contextNode - the original context node

Returns:

an Iterator capable of traversing the axis, not null

Throws:

UnsupportedAxisException - if the semantics of the following-sibling axis are not supported by this object model

getPrecedingSiblingAxisIterator

Iterator getPrecedingSiblingAxisIterator(Object contextNode)
                                  throws UnsupportedAxisException

Retrieve an Iterator matching the preceding-sibling XPath axis.

Parameters:

contextNode - the original context node

Returns:

an Iterator capable of traversing the axis, not null

Throws:

UnsupportedAxisException - if the semantics of the preceding-sibling axis are not supported by this object model

getFollowingAxisIterator

Iterator getFollowingAxisIterator(Object contextNode)
                           throws UnsupportedAxisException

Retrieve an Iterator matching the following XPath axis.

Parameters:

contextNode - the original context node

Returns:

an Iterator capable of traversing the axis, not null

Throws:

UnsupportedAxisException - if the semantics of the following axis are not supported by this object model

getPrecedingAxisIterator

Iterator getPrecedingAxisIterator(Object contextNode)
                           throws UnsupportedAxisException

Retrieve an Iterator matching the preceding XPath axis.

Parameters:

contextNode - the original context node

Returns:

an Iterator capable of traversing the axis, not null

Throws:

UnsupportedAxisException - if the semantics of the preceding axis are not supported by this object model

getAttributeAxisIterator

Iterator getAttributeAxisIterator(Object contextNode)
                           throws UnsupportedAxisException

Retrieve an Iterator matching the attribute XPath axis.

Parameters:

contextNode - the original context node

Returns:

an Iterator capable of traversing the axis, not null

Throws:

UnsupportedAxisException - if the semantics of the attribute axis are not supported by this object model

getNamespaceAxisIterator

Iterator getNamespaceAxisIterator(Object contextNode)
                           throws UnsupportedAxisException

Retrieve an Iterator matching the namespace XPath axis.

Parameters:

contextNode - the original context node

Returns:

an Iterator capable of traversing the axis, not null

Throws:

UnsupportedAxisException - if the semantics of the namespace axis are not supported by this object model

getSelfAxisIterator

Iterator getSelfAxisIterator(Object contextNode)
                      throws UnsupportedAxisException

Retrieve an Iterator matching the self XPath axis.

Parameters:

contextNode - the original context node

Returns:

an Iterator capable of traversing the axis, not null

Throws:

UnsupportedAxisException - if the semantics of the self axis are not supported by this object model

getDescendantOrSelfAxisIterator

Iterator getDescendantOrSelfAxisIterator(Object contextNode)
                                  throws UnsupportedAxisException

Retrieve an Iterator matching the descendant-or-self XPath axis.

Parameters:

contextNode - the original context node

Returns:

an Iterator capable of traversing the axis, not null

Throws:

UnsupportedAxisException - if the semantics of the descendant-or-self axis are not supported by this object model

getAncestorOrSelfAxisIterator

Iterator getAncestorOrSelfAxisIterator(Object contextNode)
                                throws UnsupportedAxisException

Retrieve an Iterator matching the ancestor-or-self XPath axis.

Parameters:

contextNode - the original context node

Returns:

an Iterator capable of traversing the axis, not null

Throws:

UnsupportedAxisException - if the semantics of the ancestor-or-self axis are not supported by this object model

getDocument

Object getDocument(String uri)
            throws FunctionCallException

Loads a document from the given URI

Parameters:

uri - the URI of the document to load

Returns:

the document

Throws:

FunctionCallException - if the document could not be loaded

getDocumentNode

Object getDocumentNode(Object contextNode)

Returns the document node that contains the given context node.

Parameters:

contextNode - the context node

Returns:

the document of the context node

See Also:

isDocument(Object)

getParentNode

Object getParentNode(Object contextNode)
              throws UnsupportedAxisException

Returns the parent of the given context node.

The parent of any node must either be a document node or an element node.

Parameters:

contextNode - the context node

Returns:

the parent of the context node, or null if this is a document node.

Throws:

UnsupportedAxisException - if the parent axis is not supported by the model

See Also:

isDocument(java.lang.Object), isElement(java.lang.Object)

getElementNamespaceUri

String getElementNamespaceUri(Object element)

Retrieve the namespace URI of the given element node.

Parameters:

element - the context element node

Returns:

the namespace URI of the element node

getElementName

String getElementName(Object element)

Retrieve the local name of the given element node.

Parameters:

element - the context element node

Returns:

the local name of the element node

getElementQName

String getElementQName(Object element)

Retrieve the qualified name of the given element node.

Parameters:

element - the context element node

Returns:

the qualified name of the element node

getAttributeNamespaceUri

String getAttributeNamespaceUri(Object attr)

Retrieve the namespace URI of the given attribute node.

Parameters:

attr - the context attribute node

Returns:

the namespace URI of the attribute node

getAttributeName

String getAttributeName(Object attr)

Retrieve the local name of the given attribute node.

Parameters:

attr - the context attribute node

Returns:

the local name of the attribute node

getAttributeQName

String getAttributeQName(Object attr)

Retrieve the qualified name of the given attribute node.

Parameters:

attr - the context attribute node

Returns:

the qualified name of the attribute node

getProcessingInstructionTarget

String getProcessingInstructionTarget(Object pi)

Retrieve the target of a processing-instruction.

Parameters:

pi - the context processing-instruction node

Returns:

the target of the processing-instruction node

getProcessingInstructionData

String getProcessingInstructionData(Object pi)

Retrieve the data of a processing-instruction.

Parameters:

pi - the context processing-instruction node

Returns:

the data of the processing-instruction node

isDocument

boolean isDocument(Object object)

Returns whether the given object is a document node. A document node is the node that is selected by the XPath expression /.

Parameters:

object - the object to test

Returns:

true if the object is a document node, else false

isElement

boolean isElement(Object object)

Returns whether the given object is an element node.

Parameters:

object - the object to test

Returns:

true if the object is an element node, else false

isAttribute

boolean isAttribute(Object object)

Returns whether the given object is an attribute node.

Parameters:

object - the object to test

Returns:

true if the object is an attribute node, else false

isNamespace

boolean isNamespace(Object object)

Returns whether the given object is a namespace node.

Parameters:

object - the object to test

Returns:

true if the object is a namespace node, else false

isComment

boolean isComment(Object object)

Returns whether the given object is a comment node.

Parameters:

object - the object to test

Returns:

true if the object is a comment node, else false

isText

boolean isText(Object object)

Returns whether the given object is a text node.

Parameters:

object - the object to test

Returns:

true if the object is a text node, else false

isProcessingInstruction

boolean isProcessingInstruction(Object object)

Returns whether the given object is a processing-instruction node.

Parameters:

object - the object to test

Returns:

true if the object is a processing-instruction node, else false

getCommentStringValue

String getCommentStringValue(Object comment)

Retrieve the string-value of a comment node. This may be the empty string if the comment is empty, but must not be null.

Parameters:

comment - the comment node

Returns:

the string-value of the node

getElementStringValue

String getElementStringValue(Object element)

Retrieve the string-value of an element node. This may be the empty string if the element is empty, but must not be null.

Parameters:

element - the comment node.

Returns:

the string-value of the node.

getAttributeStringValue

String getAttributeStringValue(Object attr)

Retrieve the string-value of an attribute node. This should be the XML 1.0 normalized attribute value. This may be the empty string but must not be null.

Parameters:

attr - the attribute node

Returns:

the string-value of the node

getNamespaceStringValue

String getNamespaceStringValue(Object ns)

Retrieve the string-value of a namespace node. This is generally the namespace URI. This may be the empty string but must not be null.

Parameters:

ns - the namespace node

Returns:

the string-value of the node

getTextStringValue

String getTextStringValue(Object text)

Retrieve the string-value of a text node. This must not be null and should not be the empty string. The XPath data model does not allow empty text nodes.

Parameters:

text - the text node

Returns:

the string-value of the node

getNamespacePrefix

String getNamespacePrefix(Object ns)

Retrieve the namespace prefix of a namespace node.

Parameters:

ns - the namespace node

Returns:

the prefix associated with the node

translateNamespacePrefixToUri

String translateNamespacePrefixToUri(String prefix,
                                     Object element)

Translate a namespace prefix to a namespace URI, possibly considering a particular element node.

Strictly speaking, prefix-to-URI translation should occur irrespective of any element in the document. This method is provided to allow a non-conforming ease-of-use enhancement.

Parameters:

prefix - the prefix to translate

element - the element to consider during translation

Returns:

the namespace URI associated with the prefix

See Also:

NamespaceContext

parseXPath

XPath parseXPath(String xpath)
          throws SAXPathException

Returns a parsed form of the given XPath string, which will be suitable for queries on documents that use the same navigator as this one.

Parameters:

xpath - the XPath expression

Returns:

a new XPath expression object

Throws:

SAXPathException - if the string is not a syntactically correct XPath expression

See Also:

XPath

getElementById

Object getElementById(Object contextNode,
                      String elementId)

Returns the element whose ID is given by elementId. If no such element exists, returns null. Attributes with the name "ID" are not of type ID unless so defined. Implementations that do not know whether attributes are of type ID or not are expected to return null.

Parameters:

contextNode - a node from the document in which to look for the id

elementId - id to look for

Returns:

element whose ID is given by elementId, or null if no such element exists in the document or if the implementation does not know about attribute types

getNodeType

short getNodeType(Object node)

Returns a number that identifies the type of node that the given object represents in this navigator.

Parameters:

node - ????

Returns:

????

See Also:

Pattern