XPath 1.0 [XPath 1.0] is becoming an important part of a variety of many specifications including XForms, XPointer, XSL, XML Query, and so on. It is also a clear advantage for user applications which use DOM to be able to use XPath expressions to locate nodes automatically and declaratively. But liveness issues have plagued each attempt to get a list of DOM nodes matching specific criteria, as would be expected for an XPath API. There have also traditionally been model mismatches between DOM and XPath. This proposal specifies new interfaces and approaches to resolving these issues.
This section considers the differences between the Document Object Model [DOM Level 2 Core] and the XPath 1.0 model [XPath 1.0].
The XPath model relies on the XML Information Set [XML Information
set] ands represents
Character Information Items in a single logical text
node where DOM may have multiple fragmented Text nodes
due to cdata sections, entity references, etc. Instead of returning
multiple nodes where XPath sees a single logical text node, only
the first non-empty DOM Text or
CDATASection node of any logical XPath text will be
returned in the node set. Applications using XPath in an
environment with fragmented text nodes must manually gather the
text of a single logical text node possibly from multiple nodes
beginning with the first Text node or
CDATASection node returned by the implementation.
Note: In an attempt to better implement the XML
Information Set, DOM Level 3 Core [DOM Level 3 Core] adds the
attribute wholeText on the Text interface
for retrieving the whole text for logically-adjacent
Text nodes and the method replaceWholeText
for replacing those nodes.
The XPath model expects namespace nodes for each in-scope
namespace to be attached to each element. DOM and certain
other W3C Information Set conformant implementations only maintain
the declaration of namespaces instead of replicating them on each
Element where they are in-scope. The DOM
implementation of XPath returns a new node of type
XPATH_NAMESPACE_NODE, defined in the XPathNamespace
interface, to properly preserve identity and ordering. This node
type is only visible using the XPath evaluation methods.
The document
order of nodes in the DOM Core has been defined to be
compatible with the
XPath document order. The XPath DOM is extending the
document order of the DOM Core to include the XPathNamespace nodes.
Element nodes occur before their children. The attribute nodes and
namespace nodes of an element occur before the children of the
element. The namespace nodes are defined to occur before the
attribute nodes. The relative order of namespace nodes is
implementation-dependent. The relative order of attribute nodes is
implementation-dependent. The compareTreePosition
method on the Node interface defined in the DOM Core
must compare the XPathNamespace nodes
using this extending document order if the XPath DOM module is
supported.
An implementation is DOM Level 3 XPath conformant if it supports the Core module defined in [DOM Level 2 Core] and the module defined in this specification. An implementation conforms to a DOM module if it supports all the interfaces for that module and the associated semantics.
A DOM application may use the hasFeature(feature,
version) method of the DOMImplementation
interface with parameter values "XPath" and "3.0" (respectively) to
determine whether or not the XPath module is supported by the
implementation. In order to fully support this module, an
implementation must also support the "Core" feature defined in the
DOM Level 2 Core specification [DOM Level 2 Core].
A DOM implementation must not return true to the
hasFeature(feature, version) method of the
DOMImplementation interface for that feature unless the
implementation conforms to that module. The version number for the
feature used in this document is "3.0".
A new exception has been created for exceptions specific to these XPath interfaces.
exception XPathException { unsigned short code; }; // XPathExceptionCode const unsigned short INVALID_EXPRESSION_ERR = 1; const unsigned short TYPE_ERR = 2;
INVALID_EXPRESSION_ERRXPathEvaluator. If the
XPathEvaluator was
obtained by casting the document, the expression must be XPath 1.0
with no special extension functions.
TYPE_ERRThe evaluation of XPath expressions is provided by
XPathEvaluator, which will provide evaluation of XPath
1.0 expressions with no specialized extension functions or
variables. It is expected that the XPathEvaluator
interface will be implemented on the same object which implements
the Document interface in an implementation which
supports the XPath DOM module. XPathEvaluator
implementations may be available from other sources that may
provide support for special extension functions or variables which
are not defined in this specification.
interface XPathEvaluator { XPathExpression createExpression(in DOMString expression, in XPathNSResolver resolver) raises(XPathException, DOMException); XPathNSResolver createNSResolver(in Node nodeResolver); XPathResult evaluate(in DOMString expression, in Node contextNode, in XPathNSResolver resolver, in unsigned short type, in XPathResult result) raises(XPathException, DOMException); };
createExpressionexpression of type
DOMStringresolver of type XPathNSResolverresolver permits translation of prefixes
within the XPath expression into appropriate namespace URIs. If
this is specified as null, any namespace prefix
within the expression will result in DOMException
being thrown with the code NAMESPACE_ERR.|
The compiled form of the XPath expression. |
|
INVALID_EXPRESSION_ERR: Raised if the expression is not legal
according to the rules of the |
|
|
|
NAMESPACE_ERR: Raised if the expression contains namespace prefixes
which cannot be resolved by the specified |
createNSResolverlookupNamespacePrefix on Node.
nodeResolver of type
Node|
|
evaluateexpression of type
DOMStringcontextNode of type
Nodecontext is context node for the evaluation of
this XPath expression. If the XPathEvaluator was obtained by
casting the Document then this must be owned by the
same document and must be a Document,
Element, Attribute, Text,
CDATASection, Comment,
ProcessingInstruction, or XPathNamespace node.
If the context node is a Text or a
CDATASection, then the context is interpreted as the
whole logical text node as seen by XPath, unless the node is empty
in which case it may not serve as the XPath context.resolver of type XPathNSResolverresolver permits translation of prefixes
within the XPath expression into appropriate namespace URIs. If
this is specified as null, any namespace prefix
within the expression will result in DOMException
being thrown with the code NAMESPACE_ERR.type of type unsigned
shorttype is specified, then the result
will be coerced to return the specified type relying on
XPath type conversions and fail if the desired coercion is
not possible. This must be one of the type codes of XPathResult.result of type XPathResultresult specifies a specific XPathResult which
may be reused and returned by this method. If this is specified as
nullor the implementation cannot reuse the specified
result, a new XPathResult will be
constructed and returned.|
The result of the evaluation of the XPath expression. |
|
INVALID_EXPRESSION_ERR: Raised if the expression is not legal
according to the rules of the TYPE_ERR: Raised if the result cannot be converted to return the specified type. |
|
|
|
NAMESPACE_ERR: Raised if the expression contains namespace prefixes
which cannot be resolved by the specified WRONG_DOCUMENT_ERR: The Node is from a document that is not supported by this XPathEvaluator. NOT_SUPPORTED_ERR: The Node is not a type permitted as an XPath context node. |
The XPathExpression interface represents a parsed
and resolved XPath expression.
interface XPathExpression { XPathResult evaluate(in Node contextNode, in unsigned short type, in XPathResult result) raises(XPathException, DOMException); };
evaluatecontextNode of type
Nodecontext is context node for the evaluation of
this XPath expression.Document then this must be owned by the same document
and must be a Document, Element,
Attribute, Text,
CDATASection, Comment,
ProcessingInstruction, or XPathNamespace
node.Text or a
CDATASection, then the context is interpreted as the
whole logical text node as seen by XPath, unless the node is empty
in which case it may not serve as the XPath context.type of type unsigned
shorttype is specified, then the result
will be coerced to return the specified type relying on XPath
conversions and fail if the desired coercion is not possible. This
must be one of the type codes of XPathResult.result of type XPathResultresult specifies a specific XPathResult which
may be reused and returned by this method. If this is specified as
nullor the implementation cannot reuse the specified
result, a new XPathResult will be
constructed and returned.|
The result of the evaluation of the XPath expression. |
|
TYPE_ERR: Raised if the result cannot be converted to return the specified type. |
|
|
|
WRONG_DOCUMENT_ERR: The Node is from a document that is not
supported by the XPathExpression that created this
NOT_SUPPORTED_ERR: The Node is not a type permitted as an XPath context node. |
The XPathNSResolver interface permit
prefix strings in the expression to be properly bound
to namespaceURI strings. XPathEvaluator can
construct an implementation of XPathNSResolver from a
node, or the interface may be implemented by any application.
interface XPathNSResolver { DOMString lookupNamespaceURI(in DOMString prefix); };
lookupNamespaceURInull
or empty argument, because the result of doing this is undefined.
nullto be passed in
invocation, allowing the implementation, if shared, to do anything
it wants with a passed null.nullwhere required.prefix of type
DOMString|
|
Returns the associated namespace URI or
|
The XPathResult interface represents the result of
the evaluation of an XPath expression within the context of a
particular node. Since evaluation of an XPath expression can result
in various result types, this object makes it possible to discover
and manipulate the type and value of the result.
invalidIteratorStateinterface XPathResult { // XPathResultType const unsigned short ANY_TYPE = 0; const unsigned short NUMBER_TYPE = 1; const unsigned short STRING_TYPE = 2; const unsigned short BOOLEAN_TYPE = 3; const unsigned short UNORDERED_NODE_ITERATOR_TYPE = 4; const unsigned short ORDERED_NODE_ITERATOR_TYPE = 5; const unsigned short UNORDERED_NODE_SNAPSHOT_TYPE = 6; const unsigned short ORDERED_NODE_SNAPSHOT_TYPE = 7; const unsigned short ANY_UNORDERED_NODE_TYPE = 8; const unsigned short FIRST_ORDERED_NODE_TYPE = 9; readonly attribute unsigned short resultType; readonly attribute double numberValue; // raises(XPathException) on retrieval readonly attribute DOMString stringValue; // raises(XPathException) on retrieval readonly attribute boolean booleanValue; // raises(XPathException) on retrieval readonly attribute Node singleNodeValue; // raises(XPathException) on retrieval readonly attribute boolean invalidIteratorState; readonly attribute unsigned long snapshotLength; // raises(XPathException) on retrieval Node iterateNext() raises(XPathException, DOMException); Node snapshotItem(in unsigned long index) raises(XPathException); };
An integer indicating what type of result this is.
ANY_TYPEANY_TYPE was
requested, then UNORDERED_NODE_ITERATOR_TYPE is always
the resulting type. Any other representation of a node set must be
explicitly requested.ANY_UNORDERED_NODE_TYPEnullif the node set is
empty. Document modification does not invalidate the node, but may
mean that the result node no longer corresponds to the current
document. This is a convenience that permits optimization since the
implementation can stop once any node in the in the resulting set
has been found.BOOLEAN_TYPEFIRST_ORDERED_NODE_TYPEnull if the node set is
empty. Document modification does not invalidate the node, but may
mean that the result node no longer corresponds to the current
document. This is a convenience that permits optimization since the
implementation can stop once the first node in document order of
the resulting set has been found.NUMBER_TYPEORDERED_NODE_ITERATOR_TYPEORDERED_NODE_SNAPSHOT_TYPESTRING_TYPEUNORDERED_NODE_ITERATOR_TYPEANY_TYPE is requested.UNORDERED_NODE_SNAPSHOT_TYPEbooleanValue of type
boolean, readonly|
TYPE_ERR: raised if |
invalidIteratorState
of type boolean, readonlyresultType is
UNORDERED_NODE_ITERATOR_TYPE or
ORDERED_NODE_ITERATOR_TYPE and the document has been
modified since this result was returned.numberValue of type
double, readonly|
TYPE_ERR: raised if |
resultType of type
unsigned short, readonlysingleNodeValue of type
Node, readonlynull.|
TYPE_ERR: raised if |
snapshotLength of type
unsigned long, readonly0 to
snapshotLength-1 inclusive.|
TYPE_ERR: raised if |
stringValue of type
DOMString, readonly|
TYPE_ERR: raised if |
iterateNextnullif there are no more nodes.
|
|
Returns the next node. |
|
TYPE_ERR: raised if |
|
|
|
INVALID_STATE_ERR: The document has been mutated since the result was returned. |
snapshotItemindexth item in the
snapshot collection. If index is greater than or equal
to the number of nodes in the list, this method returns
null. Unlike the iterator result, the snapshot does
not become invalid, but may not correspond to the current document
if it is mutated.
index of type
unsigned long|
|
The node at the |
|
TYPE_ERR: raised if |
The XPathNamespace interface is returned by XPathResult
interfaces to represent the XPath namespace node type that DOM
lacks. There is no public constructor for this node type. Attempts
to place it into a hierarchy or a NamedNodeMap result in a
DOMException with the code
HIERARCHY_REQUEST_ERR. This node is read only, so methods
or setting of attributes that would mutate the node result in a
DOMException with the code
NO_MODIFICATION_ALLOWED_ERR.
The core specification describes attributes of the
Node interface that are different for different node
node types but does not describe XPATH_NAMESPACE_NODE,
so here is a description of those attributes for this node type.
All attributes of Node not described in this section
have a null or false value.
ownerDocument matches the
ownerDocument of the ownerElement even if
the element is later adopted.
prefix is the prefix of the namespace represented
by the node.
nodeName is the same as prefix.
nodeType is equal to
XPATH_NAMESPACE_NODE.
namespaceURI is the namespace URI of the namespace
represented by the node.
adoptNode, cloneNode, and
importNode fail on this node type by raising a
DOMException with the code
NOT_SUPPORTED_ERR.
Node.namespaceValue should be identical to
Node.namespaceURI and not null.interface XPathNamespace : Node { // XPathNodeType const unsigned short XPATH_NAMESPACE_NODE = 13; readonly attribute Element ownerElement; };
An integer indicating which type of node this is.
Note: There is currently only one type of node which is specific to XPath. The numbers in this list must not collide with the values assigned to core node types.
XPATH_NAMESPACE_NODENamespace.ownerElement of type
Element, readonlyElement on which the namespace was in scope
when it was requested. This does not change on a returned namespace
node even if the document changes such that the namespace goes out
of scope on that element and this node is no
longer found there by XPath.