org.jaxen.dom

Class DocumentNavigator

public class DocumentNavigator extends DefaultNavigator

Interface for navigating around the W3C DOM Level 2 object model.

This class is not intended for direct usage, but is used by the Jaxen engine during evaluation.

This class implements the {@link org.jaxen.DefaultNavigator} interface for the Jaxen XPath library. This adapter allows the Jaxen library to be used to execute XPath queries against any object tree that implements the DOM level 2 interfaces.

Note: DOM level 2 does not include a node representing an XPath namespace node. This navigator will return namespace nodes as instances of the custom {@link NamespaceNode} class, and users will have to check result sets to locate and isolate these.

Author: David Megginson James Strachan

See Also: XPath NamespaceNode

Nested Class Summary
static classDocumentNavigator.AttributeIterator
An iterator over an attribute list.
abstract classDocumentNavigator.NodeIterator
A generic iterator over DOM nodes.
Field Summary
static longserialVersionUID
static DocumentNavigatorSINGLETON
Constructor Summary
DocumentNavigator()
Default constructor.
Method Summary
IteratorgetAttributeAxisIterator(Object contextNode)
Get an iterator over all attributes.
StringgetAttributeName(Object attribute)
Get the local name of an attribute.
StringgetAttributeNamespaceUri(Object attribute)
Get the namespace URI of an attribute.
StringgetAttributeQName(Object attribute)
Get the qualified name of an attribute.
StringgetAttributeStringValue(Object object)
Get the string value of an attribute node.
IteratorgetChildAxisIterator(Object contextNode)
Get an iterator over all of this node's children.
StringgetCommentStringValue(Object object)
Get the string value of a comment node.
ObjectgetDocument(String uri)
Use JAXP to load a namespace aware document from a given URI.
ObjectgetDocumentNode(Object contextNode)
Get the top-level document node.
ObjectgetElementById(Object object, String elementId)
Returns the element whose ID is given by elementId.
StringgetElementName(Object element)
Get the local name of an element.
StringgetElementNamespaceUri(Object element)
Get the namespace URI of an element.
StringgetElementQName(Object element)
Get the qualified name of an element.
StringgetElementStringValue(Object object)
Get the string value of an element node.
IteratorgetFollowingAxisIterator(Object contextNode)
Get an iterator over all following nodes, depth-first.
IteratorgetFollowingSiblingAxisIterator(Object contextNode)
Get an iterator over all following siblings.
static NavigatorgetInstance()
Get a constant DocumentNavigator for efficiency.
IteratorgetNamespaceAxisIterator(Object contextNode)
Get an iterator over all declared namespaces.
StringgetNamespacePrefix(Object object)
Get the prefix value of a namespace node.
StringgetNamespaceStringValue(Object object)
Get the string value of a namespace node.
IteratorgetParentAxisIterator(Object contextNode)
Get a (single-member) iterator over this node's parent.
ObjectgetParentNode(Object o)
Return the XPath parent of this DOM node.
IteratorgetPrecedingSiblingAxisIterator(Object contextNode)
Get an iterator over all preceding siblings.
StringgetProcessingInstructionData(Object obj)
Get the data of a processing instruction node.
StringgetProcessingInstructionTarget(Object obj)
Get the target of a processing instruction node.
StringBuffergetStringValue(Node node, StringBuffer buffer)
Construct a node's string value recursively.
StringgetTextStringValue(Object object)
Get the string value of text.
booleanisAttribute(Object object)
Test if a node is an attribute.
booleanisComment(Object object)
Test if a node is a comment.
booleanisDocument(Object object)
Test if a node is a top-level document.
booleanisElement(Object object)
Test if a node is an element.
booleanisNamespace(Object object)
Test if a node is a namespace.
booleanisProcessingInstruction(Object object)
Test if a node is a processing instruction.
booleanisText(Object object)
Test if a node is plain text.
XPathparseXPath(String xpath)
Returns a parsed form of the given XPath string, which will be suitable for queries on DOM documents.
StringtranslateNamespacePrefixToUri(String prefix, Object element)
Translate a namespace prefix to a URI.

Field Detail

serialVersionUID

private static final long serialVersionUID

SINGLETON

private static final DocumentNavigator SINGLETON

Constructor Detail

DocumentNavigator

public DocumentNavigator()
Default constructor.

Method Detail

getAttributeAxisIterator

public Iterator getAttributeAxisIterator(Object contextNode)
Get an iterator over all attributes.

Parameters: contextNode the context node for the attribute axis

Returns: a possibly-empty iterator (not null)

getAttributeName

public String getAttributeName(Object attribute)
Get the local name of an attribute.

Parameters: attribute the target node

Returns: a string representing the unqualified local name if the node is an attribute, or null otherwise

getAttributeNamespaceUri

public String getAttributeNamespaceUri(Object attribute)
Get the namespace URI of an attribute.

Parameters: attribute the target node

Returns: the namespace name of the specified node

getAttributeQName

public String getAttributeQName(Object attribute)
Get the qualified name of an attribute.

Parameters: attribute the target node

Returns: a string representing the qualified (i.e. possibly prefixed) name if the argument is an attribute, or null otherwise

getAttributeStringValue

public String getAttributeStringValue(Object object)
Get the string value of an attribute node.

Parameters: object the target node

Returns: the text of the attribute value if the node is an attribute, null otherwise

getChildAxisIterator

public Iterator getChildAxisIterator(Object contextNode)
Get an iterator over all of this node's children.

Parameters: contextNode the context node for the child axis.

Returns: a possibly-empty iterator (not null)

getCommentStringValue

public String getCommentStringValue(Object object)
Get the string value of a comment node.

Parameters: object the target node

Returns: the text of the comment if the node is a comment, null otherwise

getDocument

public Object getDocument(String uri)
Use JAXP to load a namespace aware document from a given URI.

Parameters: uri the URI of the document to load

Returns: the new W3C DOM Level 2 Document instance

Throws: FunctionCallException containing a nested exception if a problem occurs trying to parse the given document

getDocumentNode

public Object getDocumentNode(Object contextNode)
Get the top-level document node.

Parameters: contextNode any node in the document

Returns: the root node

getElementById

public Object getElementById(Object object, 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. Attribute types are only known if when the parser understands DTD's or schemas that declare attributes of type ID. When JAXP is used, you must call setValidating(true) on the DocumentBuilderFactory.

Parameters: object 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

Throws: ClassCastException if object is not an org.w3c.dom.Node object

See Also: javax.xml.parsers.DocumentBuilderFactory

getElementName

public String getElementName(Object element)
Get the local name of an element.

Parameters: element the target node

Returns: a string representing the unqualified local name if the node is an element, or null otherwise

getElementNamespaceUri

public String getElementNamespaceUri(Object element)
Get the namespace URI of an element.

Parameters: element the target node

Returns: a string (possibly empty) if the node is an element, and null otherwise

getElementQName

public String getElementQName(Object element)
Get the qualified name of an element.

Parameters: element the target node

Returns: a string representing the qualified (i.e. possibly prefixed) name if the argument is an element, or null otherwise

getElementStringValue

public String getElementStringValue(Object object)
Get the string value of an element node.

Parameters: object the target node

Returns: the text inside the node and its descendants if the node is an element, null otherwise

getFollowingAxisIterator

public Iterator getFollowingAxisIterator(Object contextNode)
Get an iterator over all following nodes, depth-first.

Parameters: contextNode the context node for the following axis

Returns: a possibly-empty iterator (not null)

getFollowingSiblingAxisIterator

public Iterator getFollowingSiblingAxisIterator(Object contextNode)
Get an iterator over all following siblings.

Parameters: contextNode the context node for the sibling iterator

Returns: a possibly-empty iterator (not null)

getInstance

public static Navigator getInstance()
Get a constant DocumentNavigator for efficiency.

Returns: a constant instance of a DocumentNavigator.

getNamespaceAxisIterator

public Iterator getNamespaceAxisIterator(Object contextNode)
Get an iterator over all declared namespaces.

Note: this iterator is not live: it takes a snapshot and that snapshot remains static during the life of the iterator (i.e. it won't reflect subsequent changes to the DOM).

In the event that the DOM is inconsistent; for instance a pre:foo element is declared by DOM to be in the http://www.a.com/ namespace but also has an xmlns:pre="http://www.b.com" attribute; then only one of the namespaces will be counted. This will be the intrinsic namespace of the Element or Attr object rather than the one provide by the contradictory namespace declaration attribute. In the event of a contradiction between two attributes on the same element--e.g. pre:foo in the http://www.a.com/ namespace and pre:bar in the http://www.b.com/ namespace--it is undefined which namespace will be returned.

Parameters: contextNode the context node for the namespace axis

Returns: a possibly-empty iterator (not null)

getNamespacePrefix

public String getNamespacePrefix(Object object)
Get the prefix value of a namespace node.

Parameters: object the target node

Returns: the namespace prefix a (possibly empty) string if the node is a namespace node, null otherwise

getNamespaceStringValue

public String getNamespaceStringValue(Object object)
Get the string value of a namespace node.

Parameters: object the target node

Returns: the namespace URI as a (possibly empty) string if the node is a namespace node, null otherwise

getParentAxisIterator

public Iterator getParentAxisIterator(Object contextNode)
Get a (single-member) iterator over this node's parent.

Parameters: contextNode the context node for the parent axis

Returns: a possibly-empty iterator (not null)

getParentNode

public Object getParentNode(Object o)
Return the XPath parent of this DOM node. XPath has slightly different definition of parent than DOM does. In particular, the parent of an attribute is not null.

Parameters: o

Returns: the parent of the specified node; or null if the node does not have a parent

getPrecedingSiblingAxisIterator

public Iterator getPrecedingSiblingAxisIterator(Object contextNode)
Get an iterator over all preceding siblings.

Parameters: contextNode the context node for the preceding sibling axis

Returns: a possibly-empty iterator (not null)

getProcessingInstructionData

public String getProcessingInstructionData(Object obj)
Get the data of a processing instruction node.

Parameters: obj the processing instruction

Returns: the target of the processing instruction

Throws: ClassCastException if obj is not a processing instruxtion

getProcessingInstructionTarget

public String getProcessingInstructionTarget(Object obj)
Get the target of a processing instruction node.

Parameters: obj the processing instruction

Returns: the target of the processing instruction

Throws: ClassCastException if obj is not a processing instruxtion

getStringValue

private StringBuffer getStringValue(Node node, StringBuffer buffer)
Construct a node's string value recursively.

Parameters: node the current node buffer the buffer for building the text

Returns: the buffer passed as a parameter (for convenience)

getTextStringValue

public String getTextStringValue(Object object)
Get the string value of text.

Parameters: object the target node

Returns: the string of text if the node is text, null otherwise

isAttribute

public boolean isAttribute(Object object)
Test if a node is an attribute. xmlns and xmlns:pre attributes do not count as attributes for the purposes of XPath.

Parameters: object the target node

Returns: true if the node is an attribute, false otherwise

isComment

public boolean isComment(Object object)
Test if a node is a comment.

Parameters: object the target node

Returns: true if the node is a comment, false otherwise

isDocument

public boolean isDocument(Object object)
Test if a node is a top-level document.

Parameters: object the target node

Returns: true if the node is the document root, false otherwise

isElement

public boolean isElement(Object object)
Test if a node is an element.

Parameters: object the target node

Returns: true if the node is an element, false otherwise

isNamespace

public boolean isNamespace(Object object)
Test if a node is a namespace.

Parameters: object the target node

Returns: true if the node is a namespace, false otherwise

isProcessingInstruction

public boolean isProcessingInstruction(Object object)
Test if a node is a processing instruction.

Parameters: object the target node

Returns: true if the node is a processing instruction, false otherwise

isText

public boolean isText(Object object)
Test if a node is plain text.

Parameters: object the target node

Returns: true if the node is a text node, false otherwise

parseXPath

public XPath parseXPath(String xpath)
Returns a parsed form of the given XPath string, which will be suitable for queries on DOM documents.

Parameters: xpath the XPath expression

Returns: a parsed form of the given XPath string

Throws: org.jaxen.saxpath.SAXPathException if the string is syntactically incorrect

translateNamespacePrefixToUri

public String translateNamespacePrefixToUri(String prefix, Object element)
Translate a namespace prefix to a URI.

Parameters: prefix the namespace prefix element the namespace context

Returns: the namespace URI bound to the prefix in the scope of element; null if the prefix is not bound