org.jaxen

Interface Navigator

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 {@link UnsupportedAxisException} is to be thrown. If there are no nodes on that axis, an empty iterator should be returned.

Version: $Id: Navigator.java,v 1.30 2006/06/03 20:07:19 elharo Exp $

Author: bob mcwhirter James Strachan

Method Summary
IteratorgetAncestorAxisIterator(Object contextNode)
Retrieve an Iterator matching the ancestor XPath axis.
IteratorgetAncestorOrSelfAxisIterator(Object contextNode)
Retrieve an Iterator matching the ancestor-or-self XPath axis.
IteratorgetAttributeAxisIterator(Object contextNode)
Retrieve an Iterator matching the attribute XPath axis.
StringgetAttributeName(Object attr)
Retrieve the local name of the given attribute node.
StringgetAttributeNamespaceUri(Object attr)
Retrieve the namespace URI of the given attribute node.
StringgetAttributeQName(Object attr)
Retrieve the qualified name of the given attribute node.
StringgetAttributeStringValue(Object attr)
Retrieve the string-value of an attribute node.
IteratorgetChildAxisIterator(Object contextNode)
Retrieve an Iterator matching the child XPath axis.
StringgetCommentStringValue(Object comment)
Retrieve the string-value of a comment node.
IteratorgetDescendantAxisIterator(Object contextNode)
Retrieve an Iterator matching the descendant XPath axis.
IteratorgetDescendantOrSelfAxisIterator(Object contextNode)
Retrieve an Iterator matching the descendant-or-self XPath axis.
ObjectgetDocument(String uri)
Loads a document from the given URI
ObjectgetDocumentNode(Object contextNode)
Returns the document node that contains the given context node.
ObjectgetElementById(Object contextNode, String elementId)
Returns the element whose ID is given by elementId.
StringgetElementName(Object element)
Retrieve the local name of the given element node.
StringgetElementNamespaceUri(Object element)
Retrieve the namespace URI of the given element node.
StringgetElementQName(Object element)
Retrieve the qualified name of the given element node.
StringgetElementStringValue(Object element)
Retrieve the string-value of an element node.
IteratorgetFollowingAxisIterator(Object contextNode)
Retrieve an Iterator matching the following XPath axis.
IteratorgetFollowingSiblingAxisIterator(Object contextNode)
Retrieve an Iterator matching the following-sibling XPath axis.
IteratorgetNamespaceAxisIterator(Object contextNode)
Retrieve an Iterator matching the namespace XPath axis.
StringgetNamespacePrefix(Object ns)
Retrieve the namespace prefix of a namespace node.
StringgetNamespaceStringValue(Object ns)
Retrieve the string-value of a namespace node.
shortgetNodeType(Object node)
Returns a number that identifies the type of node that the given object represents in this navigator.
IteratorgetParentAxisIterator(Object contextNode)
Retrieve an Iterator matching the parent XPath axis.
ObjectgetParentNode(Object contextNode)
Returns the parent of the given context node.
IteratorgetPrecedingAxisIterator(Object contextNode)
Retrieve an Iterator matching the preceding XPath axis.
IteratorgetPrecedingSiblingAxisIterator(Object contextNode)
Retrieve an Iterator matching the preceding-sibling XPath axis.
StringgetProcessingInstructionData(Object pi)
Retrieve the data of a processing-instruction.
StringgetProcessingInstructionTarget(Object pi)
Retrieve the target of a processing-instruction.
IteratorgetSelfAxisIterator(Object contextNode)
Retrieve an Iterator matching the self XPath axis.
StringgetTextStringValue(Object text)
Retrieve the string-value of a text node.
booleanisAttribute(Object object)
Returns whether the given object is an attribute node.
booleanisComment(Object object)
Returns whether the given object is a comment node.
booleanisDocument(Object object)
Returns whether the given object is a document node.
booleanisElement(Object object)
Returns whether the given object is an element node.
booleanisNamespace(Object object)
Returns whether the given object is a namespace node.
booleanisProcessingInstruction(Object object)
Returns whether the given object is a processing-instruction node.
booleanisText(Object object)
Returns whether the given object is a text node.
XPathparseXPath(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.
StringtranslateNamespacePrefixToUri(String prefix, Object element)
Translate a namespace prefix to a namespace URI, possibly considering a particular element node.

Method Detail

getAncestorAxisIterator

public Iterator getAncestorAxisIterator(Object contextNode)
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

getAncestorOrSelfAxisIterator

public Iterator getAncestorOrSelfAxisIterator(Object contextNode)
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

getAttributeAxisIterator

public Iterator getAttributeAxisIterator(Object contextNode)
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

getAttributeName

public 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

getAttributeNamespaceUri

public 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

getAttributeQName

public 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

getAttributeStringValue

public 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

getChildAxisIterator

public Iterator getChildAxisIterator(Object contextNode)
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

getCommentStringValue

public 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

getDescendantAxisIterator

public Iterator getDescendantAxisIterator(Object contextNode)
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

getDescendantOrSelfAxisIterator

public Iterator getDescendantOrSelfAxisIterator(Object contextNode)
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

getDocument

public Object getDocument(String uri)
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

public 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:

getElementById

public 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

getElementName

public 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

getElementNamespaceUri

public 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

getElementQName

public 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

getElementStringValue

public 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.

getFollowingAxisIterator

public Iterator getFollowingAxisIterator(Object contextNode)
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

getFollowingSiblingAxisIterator

public Iterator getFollowingSiblingAxisIterator(Object contextNode)
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

getNamespaceAxisIterator

public Iterator getNamespaceAxisIterator(Object contextNode)
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

getNamespacePrefix

public String getNamespacePrefix(Object ns)
Retrieve the namespace prefix of a namespace node.

Parameters: ns the namespace node

Returns: the prefix associated with the node

getNamespaceStringValue

public 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

getNodeType

public 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

getParentAxisIterator

public Iterator getParentAxisIterator(Object contextNode)
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

getParentNode

public Object getParentNode(Object contextNode)
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: Navigator Navigator

getPrecedingAxisIterator

public Iterator getPrecedingAxisIterator(Object contextNode)
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

getPrecedingSiblingAxisIterator

public Iterator getPrecedingSiblingAxisIterator(Object contextNode)
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

getProcessingInstructionData

public 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

getProcessingInstructionTarget

public 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

getSelfAxisIterator

public Iterator getSelfAxisIterator(Object contextNode)
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

getTextStringValue

public 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

isAttribute

public 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

isComment

public 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

isDocument

public 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

public 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

isNamespace

public 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

isProcessingInstruction

public 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

isText

public 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

parseXPath

public 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.

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:

translateNamespacePrefixToUri

public 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: