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.
This specification was created to map between the Document Object Model's representation of the W3C Information Set and XPath's model to permit XPath functions to be supplied and results returned within the framework of DOM APIs in a standard, interoperable way, allowing also for liveness of data, which is not addressed by the XPath specification but is present in results coming from the DOM hierarchy.
This section presents a mapping between the Document Object Model [DOM Level 2 Core] and the XPath 1.0 [XPath 1.0] model for the purposes of implementing the APIs.
The DOM model uses Element nodes to represent Element Information Items.
These nodes of a document are directly used to represent the elements of
an XPath result.
The DOM model uses Attr nodes to represent Attribute Information
Items of attribute and namespace attribute
properties of Element
Information Item. These nodes have no parent, but
have an ownerElement which can be used as XPath
defines an attribute's parent.
XPath 1.0 does not make available the namespace attributes of an
element. The DOM implementation of XPath 1.0 using these defined
interfaces never directly returns Attr nodes of namespace
attributes, but returned Element nodes still contain them.
The XPath model expects namespace nodes for each in-scope namespace to
be attached to each element. DOM only
maintains the namespace attributes instead of replicating in-scope
namespaces on each Element where they are in-scope. The DOM
implementation of XPath produces a new node of type
XPATH_NAMESPACE_NODE, defined in the
XPathNamespace interface, to properly preserve identity and
ordering in a way that is compatible with XPath. This node type is only
visible using the XPath evaluation methods.
The set of in-scope namespaces of an element is the default xml namespace combined with the contributions of namespace attributes of the current and all ancestor elements. In addition to explicit namespace attributes, any element has an implicit declaration of its own prefix, if any, or if no prefix then of the default namespace, which is enforced during namespace serialization, fixup, and lookup, which must be added to the set of in-scope namespaces when generating namespace nodes for an element. This causes the set of namespace nodes to be consistent with serialization, fixup, and lookup of namespaces in DOM Level 3.
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 DOM model may represent Unexpanded Entity Reference
Information Items or may provide the position and URI of
expanded entity hierarchies by using EntityReference nodes.
XPath 1.0 does not preserve corresponding information.
Where the node represents an unexpanded entity reference, it is skipped as dictated by the XPath specifications for all infoset items besides those specifically processed.
Where there is a hierarchy underneath the node, these nodes are processed as though they were siblings of the entity reference, as is consistent with the rest of the DOM specification.
EntityReference nodes found within a DOM hierarchy are
never returned as a node of the result, but returned nodes may contain
or be contained within an EntityReference node. Text may be
split partially inside and partially outside of an
EntityReference node, but this is solved by handling
Text nodes as described in the previous section.
The DOM model uses Comment nodes to represent Comment Information Items.
These nodes of a document are directly used to represent the comments of
an XPath result.
The DOM model uses ProcessingInstruction nodes to
represent Processing Instruction
Information Items. These nodes of a document are directly used
to represent the processing instructions of an XPath result.
The document order of nodes
in the DOM Core has been defined to be compatible with the XPath document order.
The XPath DOM extends 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 extended document order if
the XPath DOM module is supported.
Note: It is possible that in future versions of XPath, the order of namespace nodes or other aspects of document order may change incompatibly.
This section explains conformance to DOM Level 3 XPath Module.
A DOM implementation must not return true to
hasFeature("xpath", "3.0") unless the implementation
conforms to that module. As documented in [DOM Level 3 Core], if a null or empty string is
passed in for the second parameter, then conformance is still
required to some version of the DOM XPath Module or
false must be returned.
A conformant
implementation is DOM Level 3 XPath must support all the interfaces
as specified in that specification. In addition to implementing the
interfaces in the DOM XPath Module, a conforming implementation must
correctly implement each part of the XPath 1.0 specification when
evaluating expressions including Location Paths, Expressions, the
Core Function Library, and the mapping between DOM and the XPath 1.0
data model described in the DOM Level 3 XPath Module. The XPath
id()function must return the corresponding element, if
any, returned by the DOM method
Document.getElementById.
After meeting the requirements for conformance, a conforming implementation may implement additional functions and variables. Applications which evaluate expressions using these extensions will not necessarily be portable to other implementations of the DOM Level 3 XPath Module.
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 = 51; const unsigned short TYPE_ERR = 52;
INVALID_EXPRESSION_ERRXPathEvaluator or contains specialized extension functions
or variables not supported by this implementation.TYPE_ERR
The evaluation of XPath expressions is provided by
XPathEvaluator. In a DOM
implementation which supports the XPath 3.0 feature, as described
above, the XPathEvaluator interface will be implemented
on the same object which implements the Document
interface permitting it to be obtained by the usual binding-specific
method such as casting or by using the DOM Level 3 getInterface method.
In this case the implementation obtained from the Document supports the
XPath DOM module and is compatible with the XPath 1.0 specification.
Evaluation of expressions with specialized extension functions or
variables may not work in all implementations and is, therefore, not
portable. XPathEvaluator implementations may be available
from other sources that could provide specific support for specialized
extension functions or variables as would be defined by other
specifications.
interface XPathEvaluator { XPathExpression createExpression(in DOMString expression, in XPathNSResolver resolver) raises(XPathException, DOMException); XPathNSResolver createNSResolver(in Node nodeResolver); DOMObject evaluate(in DOMString expression, in Node contextNode, in XPathNSResolver resolver, in unsigned short type, in DOMObject result) raises(XPathException, DOMException); };
createExpressionexpression of type
DOMStringresolver of type
XPathNSResolverresolver permits translation of all
prefixes, including the xml namespace prefix,
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
|
createNSResolverlookupNamespaceURI
on nodes in resolving the namespaceURI from a given prefix
using the current information available in the node's
hierarchy at the time lookupNamespaceURI is called. also
correctly resolving the implicit xml prefix.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 all
prefixes, including the xml namespace prefix,
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 returned as the corresponding type.XPathResult interface.result of type
DOMObjectresult specifies a specific result object
which may be reused and returned by this method. If this is specified
as nullor the implementation does not reuse the specified
result, a new result object will be constructed and returned.XPathResult.
|
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 NOT_SUPPORTED_ERR: The Node is not a type permitted as an
XPath context node or the request type is not permitted by this
|
The XPathExpression interface represents a parsed
and resolved XPath expression.
interface XPathExpression { DOMObject evaluate(in Node contextNode, in unsigned short type, in DOMObject 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
DOMObjectresult specifies a specific result object
which may be reused and returned by this method. If this is specified
as nullor the implementation does not reuse the specified
result, a new result object will be constructed and returned.XPathResult.
|
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 XPathEvaluator that created this
NOT_SUPPORTED_ERR: The Node is not a type permitted as an
XPath context node or the request type is not permitted by this
|
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.prefix of type
DOMString
|
Returns the associated namespace URI or
|
The XPathResult interface represents the result
of the evaluation of an XPath 1.0 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.
interface 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.
If a specific type is specified, then the
result will be returned as the corresponding type, using
XPath type
conversions where required and possible.
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 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 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.
nodeName is always the string "#namespace".
prefix is the prefix of the namespace
represented by the node.
localName is the same as prefix.
nodeType is equal to XPATH_NAMESPACE_NODE.
namespaceURI is the namespace URI of the namespace
represented by the node.
nodeValue is the same as namespaceURI.
adoptNode, cloneNode, and
importNode fail on this node type by raising a
DOMException with the code NOT_SUPPORTED_ERR.
Note: In future versions of the XPath specification, the definition of a namespace node may be changed incomatibly, in which case incompatible changes to field values may be required to implement versions beyond XPath 1.0.
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.