Copyright ©2001 W3C® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use and software licensing rules apply.
This specification defines the Document Object Model Level 3 XPath. It provides simple functionalities to access a DOM tree using [XPath 1.0]. This module builds on top of the Document Object Model Level 3 Core.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.
This document contains the Document Object Model Level 3 XPath specification.
This is a first public Working Draft for review by W3C members and other interested parties.
It is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". This is work in progress and does not imply endorsement by, or the consensus of, either W3C or members of the DOM Working Group or members of the XSL Working Group.
Comments on this document are invited and are to be sent to the public mailing list www-dom@w3.org. An archive is available at http://lists.w3.org/Archives/Public/www-dom/.
This document has been produced as part of the W3C DOM Activity. The authors of this document are the DOM Working Group members.
A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR.
Copyright © 2001 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.
This document is published under the W3C Document Copyright Notice and License. The bindings within this document are published under the W3C Software Copyright Notice and License. The software license requires "Notice of any changes or modifications to the W3C files, including the date changes were made." Consequently, modified versions of the DOM bindings must document that they do not conform to the W3C standard; in the case of the IDL definitions, the pragma prefix can no longer be 'w3c.org'; in the case of the Java language binding, the package names can no longer be in the 'org.w3c' package.
Note: This section is a copy of the W3C Document Notice and License and could be found at http://www.w3.org/Consortium/Legal/copyright-documents-19990405.
Copyright © 1994-2001 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.
http://www.w3.org/Consortium/Legal/
Public documents on the W3C site are provided by the copyright holders under the following license. The software or Document Type Definitions (DTDs) associated with W3C specifications are governed by the Software Notice. By using and/or copying this document, or the W3C document from which this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:
Permission to use, copy, and distribute the contents of this document, or the W3C document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that you use:
When space permits, inclusion of the full text of this NOTICE should be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.
No right to create modifications or derivatives of W3C documents is granted pursuant to this license. However, if additional requirements (documented in the Copyright FAQ) are satisfied, the right to create modifications or derivatives is sometimes granted by the W3C to individuals complying with those requirements.
THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.
The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.
Note: This section is a copy of the W3C Software Copyright Notice and License and could be found at http://www.w3.org/Consortium/Legal/copyright-software-19980720
Copyright © 1994-2001 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.
http://www.w3.org/Consortium/Legal/
This W3C work (including software, documents, or other related items) is being provided by the copyright holders under the following license. By obtaining, using and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:
Permission to use, copy, and modify this software and its documentation, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the software and documentation or portions thereof, including modifications, that you make:
THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders.
XPath is becoming an important part of a variety of many specifications including XForms, XPointer, XSL, CSS, 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 object 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 and the XPath Model as defined by [XPath 1.0] as well as Ranges.
The XPath model sees 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 node of any logical XPath text will
be returned or entered into Node set. Applications
will have to manually gather the text of a single logical text node
from multiple nodes beginning with the first Text node
identified by the implementation.
Note: DOM Level 3 Core adds the attribute
wholeText on the Text interface for
retrieving the whole text for logically-adjacent Text
nodes.
The XPath model expects namespace nodes for each in-scope
namespace attached to each Element. DOM and certain
other W3C infoset 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 will only return Attr nodes of
in-scope namespace declarations, which may be attached to the
current element or its ancestors.
xml" prefix declaration.ownerElement of the namespace declaration is
different from the parent of in-scope namespace nodes of
XPath.Note: The DOM WG should try to ensure compatibility between this approach and XPath 2.0. Removing the parent from XPath 2.0 namespace nodes does not help, because the relationship between the Namespace and Element was maintained, since XPath 2.0 maintains that the namespace nodes of an element still occur before its attribute nodes producing a many-to-one relationship between XPath 2.0 Namespace Nodes and DOM Attr nodes which declare namespaces, making it impossible to sort the results without a separate Namespace node for each occurrence to represent the order correctly. Also, the XQuery 1.0 and XPath 2.0 Data Model specification [XQuery 1.0 and XPath 2.0 Data Model] still maintains that each constructed Namespace node has a unique identity, implying that duplicates would be improperly eliminated in the resultant set. (See XQuery 1.0 and XPath 2.0 Data Model 3.1, 3.2, etc.).
Since XPath returns nodes and strings, but never ranges, there
is no use for ranges in this API as had been previously suggested.
It is conceivable that in the future data types could be added
supporting the notion of DOM ranges, especially if the DOM Working
Group decided to do the work, at which time a range could become
another return type of an XPath expression supported by the
evaluator. This would be supportable by adding appropriate
additional methods to XPathEvaluator to
evaluate XPath expressions returning ranges.
If sets of ranges were introduced, an appropriate interface for sets of ranges would need to be added to DOM (needed anyway for implementation of multiple selection), and this would be another new return type supported by the XPath evaluator.
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 event 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 3 Core specification [DOM Level 3 Core]. Please, refer to
additional information about conformance in the DOM Level 3 Core
specification [DOM
Level 3 Core].
Note: There is a fair amount of complexity in custom extension functions and variables because variables may be of various types and functions have arguments and return types. There are additional issues such as keeping functions from modifying the DOM, what exceptions to allow, and all the fun of callbacks. If the first draft of the specification ignores custom functions and variables, this should not make it more difficult to later add such a factory to the specification or for implementors to provide alternate evaluators that access extension functions and variables.
TYPE_ERR
exception XPathException {
unsigned short code;
};
The evaluation of XPath expressions is available in
XPathEvaluator. A Document which
implements the XPath module will be castable using
language-specific mechanisms to XPathEvaluator, which
will provide evaluation of XPath expressions with no special
extension functions or variables. XPathEvaluator
implementations may be available from other sources that provide
extension functions or variables.
evaluateAs method?
interface XPathEvaluator {
boolean evaluateAsBoolean(in DOMString expression,
in Node contextNode,
in NamespaceResolver resolver)
raises(XPathException);
double evaluateAsNumber(in DOMString expression,
in Node contextNode,
in NamespaceResolver resolver)
raises(XPathException);
DOMString evaluateAsString(in DOMString expression,
in Node contextNode,
in NamespaceResolver resolver)
raises(XPathException);
Node evaluateAsNode(in DOMString expression,
in Node contextNode,
in NamespaceResolver resolver)
raises(XPathException);
ActiveNodeSet evaluateAsNodeSet(in DOMString expression,
in Node contextNode,
in NamespaceResolver resolver)
raises(XPathException);
};
evaluateAsBooleanexpression of type
DOMStringcontextNode of type
Noderesolver of type NamespaceResolverresolver permits translation of prefixes
within the XPath expression into appropriate namespaceURIs.|
|
The result of the evaluation of the XPath expression. |
|
TYPE_ERR: Raised if the result cannot be converted to a boolean |
evaluateAsNodenull if the resulting
set is empty.
expression of type
DOMStringcontextNode of type
Noderesolver of type NamespaceResolverresolver permits translation of prefixes
within the XPath expression into appropriate namespaceURIs.|
|
The result of the evaluation of the XPath expression. |
|
TYPE_ERR: Raised if the result cannot be converted to a node set. |
evaluateAsNodeSetexpression of type
DOMStringcontextNode of type
Noderesolver of type NamespaceResolverresolver permits translation of prefixes
within the XPath expression into appropriate namespaceURIs.|
The result of the evaluation of the XPath expression. |
|
TYPE_ERR: Raised if the result cannot be converted to a node set. |
evaluateAsNumberexpression of type
DOMStringcontextNode of type
Noderesolver of type NamespaceResolverresolver permits translation of prefixes
within the XPath expression into appropriate namespaceURIs.|
|
The result of the evaluation of the XPath expression. |
|
TYPE_ERR: Raised if the result cannot be converted to a number (IEEE double precision floating point value) |
evaluateAsStringexpression of type
DOMStringcontextNode of type
Noderesolver of type NamespaceResolverresolver permits translation of prefixes
within the XPath expression into appropriate namespaceURIs.|
|
The result of the evaluation of the XPath expression. |
|
TYPE_ERR: Raised if the result cannot be converted to a
|
An XPath node set is represented by a NodeSet
interface which maintains a set of references to nodes. No node is
ever duplicated in NodeSet. When ActiveNodeSet is
returned from an XPath evaluation, it corresponds to the hierarchy
that it was requested on until the hierarchy is mutated in any way
(anything that could produce a mutation event) at which time the
set becomes invalid and any future call raises an exception. This
permits the XPath sets to be computed either all at once or
incrementally, however the implementation decides to do it. This
also guarantees that any valid ActiveNodeSet
corresponds to the current hierarchy.
NodeSet is not generally ordered in any way because
implementations may be parallelized and compound statements may
return nodes out of document order even in the simplest serial
implementation. XSL and other processing requires XPath sets to be
sorted in document order.
A StaticNodeSet is a collection of
Nodes evaluated from an XPath expression. It never
becomes invalid and never changes the array of node references even
if the nodes are no longer are in the hierarchy or no longer match
the expression that created the set. The individual nodes of a
StaticNodeSet may be manipulated in the hierarchy and
these changes are seen immediately by users referencing the nodes
through the set.
interface StaticNodeSet {
Node item(in unsigned long index);
readonly attribute unsigned long length;
};
length of type unsigned
long, readonlylength-1 inclusive.itemindexth item in the
collection. If index is greater than or equal to the
number of nodes in the list, this returns null.
index of type
unsigned long|
|
The node at the |
This represents a live node set obtained with the evaluation of an XPath expression.
interface ActiveNodeSet {
Node nextNode()
raises(DOMException);
void reset()
raises(DOMException);
ActiveNodeSet cloneSet()
raises(DOMException);
ActiveNodeSet getDocumentOrderedSet()
raises(DOMException);
StaticNodeSet getStaticNodeSet()
raises(DOMException);
};
cloneSetActiveNodeSet.
|
The new |
|
|
INVALID_STATE_ERR: The |
getDocumentOrderedSetAttr nodes attached to an Element) will
not be ordered in any particular order with respect to each other
by this method.
getDocumentOrderedSet. Some of the differences, we
could just adopt. Others are unclear.<foo bar1="abc"/><foo
bar2="def" bar3="ghi">, DOM currently says that attribute
nodes bar1 and bar2 are unordered with respect to each other, since
they each have no parent. XPath and DOM both agree that bar2 and
bar3 have no order with respect to each other, but XPath gives them
an order with respect to their parent, giving them a definate
position in the resulting sorted node set, whereas DOM does not
acknowledge the ownerElement as part of the ordering relationship
and makes it impossible to meaningfully sort attributes nodes of an
element with elements or the attributes of other elements. I think
we should adjust DOM's proposed comparison APIs and the result will
help, rather than hurting, the DOM specification.|
|
INVALID_STATE_ERR: The |
getStaticNodeSetStaticNodeSet, which
never becomes invalid and never changes the array of node
references even if the nodes are no longer are in the hierarchy or
no longer match the expression that created the set.
|
The complete evaluation of the XPath expression. |
|
|
INVALID_STATE_ERR: The |
nextNode|
|
Returns the next node. |
|
|
INVALID_STATE_ERR: The |
reset|
|
INVALID_STATE_ERR: The |
The NamespaceResolver interface permit
prefix strings in the expression to be properly bound
to namespaceURI strings. The expectation is that an
instance of the NamespaceResolver interface can be
obtained by using binding-specific casting methods on an instance
of the Element interface. This interface may also be
user implemented instead of obtaining the implementation from an
Element.
interface NamespaceResolver {
DOMString lookupNamespaceURI(in DOMString prefix);
};
lookupNamespaceURIprefix of type
DOMString|
|
Returns the associated namespace URI or |
This appendix contains the complete OMG IDL [OMGIDL] for the Level 3 Document Object Model XPath definitions.
The IDL files are also available as: http://www.w3.org/TR/2001/WD-DOM-Level-3-XPath-20010618/idl.zip
// File: xpath.idl
#ifndef _XPATH_IDL_
#define _XPATH_IDL_
#include "dom.idl"
#pragma prefix "dom.w3c.org"
module xpath
{
typedef dom::DOMString DOMString;
typedef dom::Node Node;
interface NamespaceResolver;
interface ActiveNodeSet;
exception XPathException {
unsigned short code;
};
interface XPathEvaluator {
boolean evaluateAsBoolean(in DOMString expression,
in Node contextNode,
in NamespaceResolver resolver)
raises(XPathException);
double evaluateAsNumber(in DOMString expression,
in Node contextNode,
in NamespaceResolver resolver)
raises(XPathException);
DOMString evaluateAsString(in DOMString expression,
in Node contextNode,
in NamespaceResolver resolver)
raises(XPathException);
Node evaluateAsNode(in DOMString expression,
in Node contextNode,
in NamespaceResolver resolver)
raises(XPathException);
ActiveNodeSet evaluateAsNodeSet(in DOMString expression,
in Node contextNode,
in NamespaceResolver resolver)
raises(XPathException);
};
interface StaticNodeSet {
Node item(in unsigned long index);
readonly attribute unsigned long length;
};
interface ActiveNodeSet {
Node nextNode()
raises(dom::DOMException);
void reset()
raises(dom::DOMException);
ActiveNodeSet cloneSet()
raises(dom::DOMException);
ActiveNodeSet getDocumentOrderedSet()
raises(dom::DOMException);
StaticNodeSet getStaticNodeSet()
raises(dom::DOMException);
};
interface NamespaceResolver {
DOMString lookupNamespaceURI(in DOMString prefix);
};
};
#endif // _XPATH_IDL_
This appendix contains the complete Java [Java] bindings for the Level 3 Document Object Model XPath.
The Java files are also available as http://www.w3.org/TR/2001/WD-DOM-Level-3-XPath-20010618/java-binding.zip
package org.w3c.dom.xpath;
public class XPathException extends RuntimeException {
public XPathException(short code, String message) {
super(message);
this.code = code;
}
public short code;
};
package org.w3c.dom.xpath;
import org.w3c.dom.Node;
public interface XPathEvaluator {
public boolean evaluateAsBoolean(String expression,
Node contextNode,
NamespaceResolver resolver)
throws XPathException;
public double evaluateAsNumber(String expression,
Node contextNode,
NamespaceResolver resolver)
throws XPathException;
public String evaluateAsString(String expression,
Node contextNode,
NamespaceResolver resolver)
throws XPathException;
public Node evaluateAsNode(String expression,
Node contextNode,
NamespaceResolver resolver)
throws XPathException;
public ActiveNodeSet evaluateAsNodeSet(String expression,
Node contextNode,
NamespaceResolver resolver)
throws XPathException;
}
package org.w3c.dom.xpath;
import org.w3c.dom.Node;
public interface StaticNodeSet {
public Node item(int index);
public int getLength();
}
package org.w3c.dom.xpath;
import org.w3c.dom.Node;
import org.w3c.dom.DOMException;
public interface ActiveNodeSet {
public Node nextNode()
throws DOMException;
public void reset()
throws DOMException;
public ActiveNodeSet cloneSet()
throws DOMException;
public ActiveNodeSet getDocumentOrderedSet()
throws DOMException;
public StaticNodeSet getStaticNodeSet()
throws DOMException;
}
package org.w3c.dom.xpath;
public interface NamespaceResolver {
public String lookupNamespaceURI(String prefix);
}
This appendix contains the complete ECMA Script [ECMAScript] binding for the Level 3 Document Object Model XPath definitions.
Many people contributed to this specification, including members of the DOM Working Group and the DOM Interest Group. We especially thank the following:
Andrew Watson (Object Management Group), Andy Heninger (IBM), Arnaud Le Hors (W3C and IBM), Ben Chang (Oracle), Bill Smith (Sun), Bill Shea (Merrill Lynch), Bob Sutor (IBM), Chris Lovett (Microsoft), Chris Wilson (Microsoft), David Brownell (Sun), David Singer (IBM), Don Park (invited), Eric Vasilik (Microsoft), Gavin Nicol (INSO), Ian Jacobs (W3C), James Clark (invited), James Davidson (Sun), Jared Sorensen (Novell), Joe Kesselman (IBM), Joe Lapp (webMethods), Joe Marini (Macromedia), Johnny Stenback (Netscape), Jonathan Marsh (Microsoft), Jonathan Robie (Texcel Research and Software AG), Kim Adamson-Sharpe (SoftQuad Software Inc.), Lauren Wood (SoftQuad Software Inc., former chair), Laurence Cable (Sun), Mark Davis (IBM), Mark Scardina (Oracle), Martin Dürst (W3C), Mick Goulish (Software AG), Mike Champion (Arbortext and Software AG), Miles Sabin (Cromwell Media), Patti Lutsky (Arbortext), Paul Grosso (Arbortext), Peter Sharpe (SoftQuad Software Inc.), Phil Karlton (Netscape), Philippe Le Hégaret (W3C, W3C team contact and Chair), Ramesh Lekshmynarayanan (Merrill Lynch), Ray Whitmer (iMall, Excite@Home and Netscape/AOL), Rich Rollman (Microsoft), Rick Gessner (Netscape), Scott Isaacs (Microsoft), Sharon Adler (INSO), Steve Byrne (JavaSoft), Tim Bray (invited), Tom Pixley (Netscape), Vidur Apparao (Netscape), Vinod Anupam (Lucent), Johnny Stenback (Netscape/AOL), Jeroen van Rotterdam (X-Hive Corporation), Rezaur Rahman (Intel), Rob Relyea (Microsoft), Tim Yu (Oracle), Angel Diaz (Oracle), Jon Ferraiolo (Adobe), David Ezell (Hewlett Packard Company), Ashok Malhotra, (IBM and Microsoft), Rick Jelliffe (invited), Elena Litani (IBM), Mary Brady (NIST), Dimitris Dimitriadis (Improve AB).
Thanks to all those who have helped to improve this specification by sending suggestions and corrections (Please, keep bugging us with your issues!).
This specification was written in XML. The HTML, OMG IDL, Java and ECMA Script bindings were all produced automatically.
Thanks to Joe English, author of cost, which was used as the basis for producing DOM Level 1. Thanks also to Gavin Nicol, who wrote the scripts which run on top of cost. Arnaud Le Hors and Philippe Le Hégaret maintained the scripts.
After DOM Level 1, we used Xerces as the basis DOM implementation and wish to thank the authors. Philippe Le Hégaret and Arnaud Le Hors wrote the Java programs which are the DOM application.
Thanks also to Jan Kärrman, author of html2ps, which we use in creating the PostScript version of the specification.
Several of the following term definitions have been borrowed or modified from similar definitions in other W3C or standards documents. See the links within the definitions for more information.
For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.