com.qizx.api
Interface Node

All Superinterfaces:

Item

public interface Node

extends Item

Nodes of the Document Data Model, as defined by XQuery1/XPath2, plus extensions.

Caution: a node of a Data Model can be represented by several different instances of Node. Therefore Node instances should never be compared with ==, but with the equals method, or possibly with the documentOrderCompareTo method.

Common exception causes: the node belongs to an unreachable Document (deleted or belonging to a closed Library).

Field Summary

static int	ATOM_ANY Node nature (returned by getNodeNature) for typed leaf node holding a value of any serializable class.
static int	ATOM_BOOLEAN Node nature (returned by getNodeNature) for a typed leaf node holding a boolean value.
static int	ATOM_DATE Node nature (returned by getNodeNature) for typed leaf node holding a date/time value.
static int	ATOM_DOUBLE Node nature (returned by getNodeNature) for a typed leaf node holding a double value.
static int	ATOM_LONG Node nature (returned by getNodeNature) for a typed integer node, holding a long integer value.
static int	ATTRIBUTE Node nature (returned by getNodeNature) for an Attribute node.
static int	COMMENT Node nature (returned by getNodeNature) for a Comment node.
static int	DOCUMENT Node nature (returned by getNodeNature) for a document node.
static int	ELEMENT Node nature (returned by getNodeNature) for an Element node.
static int	NAMESPACE Node nature (returned by getNodeNature) for a naemespacenode.
static int	PROCESSING_INSTRUCTION Node nature (returned by getNodeNature) for a processing instruction node.
static int	TEXT Node nature (returned by getNodeNature) for a leaf text node.

Method Summary

boolean	contains(Node node) Returns true if this node is an ancestor of the parameter node or the node itself.
boolean	deepEquals(Node node, Collator collator) Deep equality of two subtrees.
int	documentOrderCompareTo(Node that) Compares the document order of two nodes.
Object	getAtomValue() Returns the value of an atomic node.
Node	getAttribute(QName name) Gets an attribute of an element by name.
int	getAttributeCount() Returns the number of attributes of an Element.
Node[]	getAttributes() Gets the attributes of an element.
String	getBaseURI() Return the base-URI of this Node.
Node	getDocumentNode() Returns the document node if any, else the top-level node.
String	getDocumentURI() Returns the URI of the document.
Node	getFirstChild() Returns the first child node of an element or a document node.
Document	getLibraryDocument() Returns the XML Library Document the Node belongs to, if applicable.
long	getLongAtomValue() Returns the node contents as an integer value.
String	getNamespacePrefix(String nsURI) Returns a matching prefix for the Namespace URI by looking up the in-scope namespace definitions.
String	getNamespaceUri(String prefix) Returns a matching Namespace for the prefix by looking up the in-scope namespace definitions.
Node	getNextNode() Returns the next Node in document order.
Node	getNextSibling() Returns the next sibling Node.
String	getNodeKind() Returns the node kind as a string: "document", "element", "attribute", "text", "comment", or "processing-instruction".
QName	getNodeName() Returns the Qualified Name of the node.
int	getNodeNature() Returns a node kind in numeric form: DOCUMENT, ELEMENT etc.
Node	getParent() Returns the parent node.
String	getStringValue() Returns the String Value of this Node.
boolean	isElement() Returns true if the Node is an Element.
int	stringValueCompareTo(Node node, Collator collator) Compares the string values of two nodes, optionally using a collation.

Methods inherited from interface com.qizx.api.Item

export, exportNode, getBoolean, getDecimal, getDouble, getFloat, getInteger, getNode, getObject, getQName, getString, getType, isNode

Field Detail

DOCUMENT

public static final int DOCUMENT

Node nature (returned by getNodeNature) for a document node.

See Also:

Constant Field Values

ELEMENT

public static final int ELEMENT

Node nature (returned by getNodeNature) for an Element node.

See Also:

Constant Field Values

ATTRIBUTE

public static final int ATTRIBUTE

Node nature (returned by getNodeNature) for an Attribute node.

See Also:

Constant Field Values

NAMESPACE

public static final int NAMESPACE

Node nature (returned by getNodeNature) for a naemespacenode.

See Also:

Constant Field Values

PROCESSING_INSTRUCTION

public static final int PROCESSING_INSTRUCTION

Node nature (returned by getNodeNature) for a processing instruction node.

See Also:

Constant Field Values

COMMENT

public static final int COMMENT

Node nature (returned by getNodeNature) for a Comment node.

See Also:

Constant Field Values

TEXT

public static final int TEXT

Node nature (returned by getNodeNature) for a leaf text node.

See Also:

Constant Field Values

ATOM_BOOLEAN

public static final int ATOM_BOOLEAN

Node nature (returned by getNodeNature) for a typed leaf node holding a boolean value.

See Also:

Constant Field Values

ATOM_LONG

public static final int ATOM_LONG

Node nature (returned by getNodeNature) for a typed integer node, holding a long integer value.

See Also:

Constant Field Values

ATOM_DOUBLE

public static final int ATOM_DOUBLE

Node nature (returned by getNodeNature) for a typed leaf node holding a double value.

See Also:

Constant Field Values

ATOM_ANY

public static final int ATOM_ANY

Node nature (returned by getNodeNature) for typed leaf node holding a value of any serializable class.

See Also:

Constant Field Values

ATOM_DATE

public static final int ATOM_DATE

Node nature (returned by getNodeNature) for typed leaf node holding a date/time value.

See Also:

Constant Field Values

Method Detail

getNodeKind

public String getNodeKind()
                   throws DataModelException

Returns the node kind as a string: "document", "element", "attribute", "text", "comment", or "processing-instruction".

Corresponds to Data Model accessor dm:node-kind().

Returns:

a String representing the node kind.

Throws:

DataModelException - common causes

getNodeName

public QName getNodeName()
                  throws DataModelException

Returns the Qualified Name of the node.

Corresponds to Data Model accessor dm:node-name().

Returns:

the name of the node (for element and attribute), the target for a processing-instruction, null if the node has no name (document, text, comment).

Throws:

DataModelException - common causes

getParent

public Node getParent()
               throws DataModelException

Returns the parent node.

Corresponds to the XQuery Data Model accessor dm:parent().

Returns:

the parent node or null if the node has no parent.

Throws:

DataModelException - common causes

getFirstChild

public Node getFirstChild()
                   throws DataModelException

Returns the first child node of an element or a document node.

Returns:

null if the node has no first child.

Throws:

DataModelException - common causes

getNextSibling

public Node getNextSibling()
                    throws DataModelException

Returns the next sibling Node.

Returns:

null if the node has no next sibling.

Throws:

DataModelException - common causes

getNextNode

public Node getNextNode()
                 throws DataModelException

Returns the next Node in document order. If this node has children, the next node is the first child; otherwise this is the first of the following nodes (in the sense of the XPath axis 'following').

Returns:

the next node, or null if the node has no successor.

Throws:

DataModelException - common causes

getStringValue

public String getStringValue()
                      throws DataModelException

Returns the String Value of this Node.

Corresponds to the XQuery Data Model accessor dm:string-value().

Returns:

the string value of the node. For an element, it is the concatenation of text nodes contained in the element.

Throws:

DataModelException - common causes

getBaseURI

public String getBaseURI()
                  throws DataModelException

Return the base-URI of this Node.

Corresponds to the XQuery Data Model accessor dm:base-uri().

Returns:

the base-URI as a String

Throws:

DataModelException - common causes

getDocumentURI

public String getDocumentURI()
                      throws DataModelException

Returns the URI of the document.

Returns:

the document URI as a String

Throws:

DataModelException - common causes

getDocumentNode

public Node getDocumentNode()
                     throws DataModelException

Returns the document node if any, else the top-level node.

Returns:

the topmost ancestor node.

Throws:

DataModelException - common causes

getLibraryDocument

public Document getLibraryDocument()
                            throws DataModelException

Returns the XML Library Document the Node belongs to, if applicable.

Returns:

a Document descriptor if the node belongs to a document stored in an XML Library, otherwise null.

Throws:

DataModelException - common causes

getNodeNature

public int getNodeNature()
                  throws DataModelException

Returns a node kind in numeric form: DOCUMENT, ELEMENT etc.

Returns:

an integer representing the node nature

Throws:

DataModelException - common causes

isElement

public boolean isElement()
                  throws DataModelException

Returns true if the Node is an Element. Convenience method equivalent to: getNodeNature() == Node.ELEMENT.

Returns:

true if this node is an XML element

Throws:

DataModelException - common causes

getAttribute

public Node getAttribute(QName name)
                  throws DataModelException

Gets an attribute of an element by name.

Parameters:

name - qualified name of the sought attribute

Returns:

An attribute node; null if not found or not applied to an element.

Throws:

DataModelException - common causes

getAttributes

public Node[] getAttributes()
                     throws DataModelException

Gets the attributes of an element.

Returns:

an array of attribute nodes, or null if the node has no attributes.

Throws:

DataModelException - common causes

getAttributeCount

public int getAttributeCount()
                      throws DataModelException

Returns the number of attributes of an Element. Returns 0 if the node is not an Element.

Returns:

an integer which is the number of attributes

Throws:

DataModelException - common causes

getAtomValue

public Object getAtomValue()
                    throws DataModelException

Returns the value of an atomic node.

Returns:

Generally a String, but for typed atoms it is an object of class Boolean (ATOM_BOOLEAN), Long (ATOM_LONG), Double (ATOM_DOUBLE) or any serializable class (ATOM_ANY).

Throws:

DataModelException - common causes

getLongAtomValue

public long getLongAtomValue()
                      throws DataModelException

Returns the node contents as an integer value. Attempts to convert the string-value if the node has not the ATOM_LONG nature.

Returns:

a long value

Throws:

DataModelException - if not convertible to integer; common causes

getNamespacePrefix

public String getNamespacePrefix(String nsURI)
                          throws DataModelException

Returns a matching prefix for the Namespace URI by looking up the in-scope namespace definitions.

Parameters:

nsURI - a namespace URI as a String

Returns:

the first suitable prefix, otherwise null if none is found.

Throws:

DataModelException - common causes

getNamespaceUri

public String getNamespaceUri(String prefix)
                       throws DataModelException

Returns a matching Namespace for the prefix by looking up the in-scope namespace definitions.

Parameters:

prefix - a prefix as a String (canbe the empty string)

Returns:

the first suitable namespace URI, otherwise null if none is found.

Throws:

DataModelException - common causes

documentOrderCompareTo

public int documentOrderCompareTo(Node that)
                           throws DataModelException

Compares the document order of two nodes.

Parameters:

that - other node to compare

Returns:

-1 if this node is strictly before that node in document order, 0 if nodes are identical, 1 if after that node. If the two nodes belong to different documents, returns an arbitrary but stable "order of documents".

Throws:

DataModelException - common causes

stringValueCompareTo

public int stringValueCompareTo(Node node,
                                Collator collator)
                         throws DataModelException

Compares the string values of two nodes, optionally using a collation.

Parameters:

node - other node to compare

collator - an optional collator to compare string values; can be null

Returns:

0 if string values are equal, a negative integer if this string value is before the string value of the other node, a positive value otherwise.

Throws:

DataModelException - common causes

deepEquals

public boolean deepEquals(Node node,
                          Collator collator)
                   throws DataModelException

Deep equality of two subtrees. Implements fn:deep-equal on Node.

Parameters:

node - other node to compare

collator - an optional collator to compare string values; can be null

Returns:

true if the two nodes are deeply equal

Throws:

DataModelException - common causes

contains

public boolean contains(Node node)
                 throws DataModelException

Returns true if this node is an ancestor of the parameter node or the node itself.

Parameters:

node - other node to check for containment

Returns:

true if the node argument is a descendant

Throws:

DataModelException - common causes