W3C

Document Object Model (DOM) Level 3 XPath Specification

Version 1.0

W3C Working Draft 30 August 2001

This version:
http://www.w3.org/TR/2001/WD-DOM-Level-3-XPath-20010830
( PostScript file , PDF file , plain text , ZIP file , single HTML file)
Latest version:
http://www.w3.org/TR/DOM-Level-3-XPath
Previous version:
http://www.w3.org/TR/2001/WD-DOM-Level-3-XPath-20010618
Editor:
Ray Whitmer, Netscape/AOL

Abstract

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 [DOM Level 3 Core].

Status of this document

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 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.

Table of contents

30 August 2001

Expanded Table of Contents

30 August 2001

Copyright Notice

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:

  1. A link or URL to the original W3C document.
  2. The pre-existing copyright notice of the original author, or if it doesn't exist, a notice of the form: "Copyright © [$date-of-document] 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/" (Hypertext is preferred, but a textual representation is permitted.)
  3. If it exists, the STATUS of the W3C document.

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:

  1. The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
  2. Any pre-existing intellectual property disclaimers. If none exist, then a notice of the following form: "Copyright © [$date-of-software] 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/."
  3. Notice of any changes or modifications to the W3C files, including the date changes were made. (We recommend you provide URIs to the location from which the code is derived.)

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.

30 August 2001

1. Document Object Model XPath

Editor:
Ray Whitmer, Netscape/AOL

Table of contents

1.1. Introduction

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 model mismatches between DOM and XPath. This proposal specifies new interfaces and approaches to resolving these issues.

1.2. Mapping DOM to XPath

This section considers the differences between the Document Object Model and the XPath model as defined by [XPath 1.0].

1.2.1. Text Nodes

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 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 from multiple nodes beginning with the first Text node identified 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.

1.2.2. Namespace 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 to properly preserve identity and ordering. This node type is only visible using the XPath evaluation methods.

1.2.3. Document Order

The document order of nodes in the DOM Core has been defined to be compatible with the XPath document order. According to XPath, namespace nodes are unordered with respect to other namespace nodes of the same element and precede attribute and child nodes of the same element. The DOM core must order the non-core XPathNamespace nodes in this way if the XPath DOM module is supported.

1.3. Interfaces

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].

Exception XPathException

A new exception has been created for exceptions specific to these XPath interfaces.


IDL Definition
exception XPathException {
  unsigned short   code;
};
// XPathExceptionCode
const unsigned short      INVALID_EXPRESSION_ERR         = 1;
const unsigned short      TYPE_ERR                       = 2;

Definition group XPathExceptionCode
Defined Constants
INVALID_EXPRESSION_ERR
If the expression is not a legal expression according to the rules of the specific XPathEvaluator or contains namespace prefixes which are not in scope according to the specified XPathNSResolver. If the XPathEvaluator was obtained by casting the document, the expression must be XPath 1.0 with no special extension functions.
TYPE_ERR
If the expression cannot be converted to return the specified type.
Interface XPathEvaluator

The evaluation of XPath expressions is performed 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 new versions of XPath or special extension functions or variables which are not defined in this specification.


IDL Definition
interface XPathEvaluator {
  XPathExpression    createExpression(in DOMString expression, 
                                      in XPathNSResolver resolver)
                                        raises(XPathException);
  XPathResult        createResult();
  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);
  XPathResult        evaluateExpression(in XPathExpression expression, 
                                        in Node contextNode, 
                                        in unsigned short type, 
                                        in XPathResult result)
                                        raises(XPathException);
};

Methods
createExpression
Creates a parsed XPath expression with resolved namespaces. This is useful when an expression will be reused in an application since it makes it possible to compile the expression string into a more efficient internal form and preresolve all namespace prefixes which occur within the expression.
Parameters
expression of type DOMString
The XPath expression string to be parsed.
resolver of type XPathNSResolver
The resolver 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 XPathException being thrown with the code INVALID_EXPRESSION_ERR.
Return Value

XPathExpression

The compiled form of the XPath expression.

Exceptions

XPathException

INVALID_EXPRESSION_ERR: Raised if the expression is not legal according to the rules of the XPathEvaluator and the in-scope namespace prefixes.

createNSResolver
Adapts any DOM node to resolve namespaces so that an XPath expression can be easily evaluated relative to the context of the node where it appeared within the document.
Parameters
nodeResolver of type Node
The node to be used as a context for namespace resolution.
Return Value

XPathNSResolver

XPathNSResolver which resolves namespaces with respect to the definitions in scope for a specified node.

No Exceptions
createResult
Creates an XPath result object which may be passed as a parameter to the evaluation methods of this XPathEvaluator so that a new one is not created on each call to an evaluation method.
Return Value

XPathResult

An empty XPathEvaluator with type ANY_TYPE.

No Parameters
No Exceptions
evaluate
Evaluates an XPath expression string and returns a result of the specified type if possible.
Parameters
expression of type DOMString
The XPath expression string to be parsed and evaluated.
contextNode of type Node
The context is context node for the evaluation of this XPath expression.
resolver of type XPathNSResolver
The resolver 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 XPathException being thrown with the code INVALID_EXPRESSION_ERR.
type of type unsigned short
If a specific type 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 XPathResult
The result specifies a specific XPathResult to be reused and returned by this method. If this is specified as null, a new XPathResult will be constructed and returned. Any XPathResult which was not created by this XPathEvaluator may be ignored as though a null were passed as the parameter.
Return Value

XPathResult

The result of the evaluation of the XPath expression.

Exceptions

XPathException

INVALID_EXPRESSION_ERR: Raised if the expression is not legal according to the rules of the XPathEvaluator and the in-scope namespace prefixes.

TYPE_ERR: Raised if the result cannot be converted to return the specified type.

evaluateExpression
Evaluates an XPath expression and returns a result.
Parameters
expression of type XPathExpression
The XPath expression to be evaluated.
contextNode of type Node
The context is context node for the evaluation of this XPath expression.
type of type unsigned short
If a specific type 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 XPathResult
The result specifies a specific XPathResult to be reused and returned by this method. If this is specified as null, a new XPathResult will be constructed and returned. Any XPathResult which was not created by this XPathEvaluator may be ignored as though a null were passed as the parameter.
Return Value

XPathResult

The result of the evaluation of the XPath expression.

Exceptions

XPathException

TYPE_ERR: Raised if the result cannot be converted to return the specified type.

Interface XPathExpression

The XPathExpression interface represents a parsed and resolved XPath expression.


IDL Definition
interface XPathExpression {
};

Interface XPathNSResolver

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.


IDL Definition
interface XPathNSResolver {
  DOMString          lookupNamespaceURI(in DOMString prefix);
};

Methods
lookupNamespaceURI
Look up the namespace URI associated to the given namespace prefix.
Parameters
prefix of type DOMString
The prefix to look for.
Return Value

DOMString

Returns the associated namespace URI or null if none is found.

No Exceptions
Interface XPathResult

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.


IDL Definition
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      NODE_SET_TYPE                  = 4;
  const unsigned short      SINGLE_NODE_TYPE               = 5;

  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

  XPathSetIterator   getSetIterator(in boolean ordered)
                                        raises(XPathException, 
                                               DOMException);
  XPathSetSnapshot   getSetSnapshot(in boolean ordered)
                                        raises(XPathException, 
                                               DOMException);
};

Definition group XPathResultType

An integer indicating what type of result this is.

Defined Constants
ANY_TYPE
This code does not represent a specific type. An evaluation of an XPath expression will never produce this type. If this type is requested, then the evaluation must return whatever type naturally results from evaluation of the expression.
BOOLEAN_TYPE
The result is a boolean as defined by XPath 1.0.
NODE_SET_TYPE
The result is a node set as defined by XPath 1.0.
NUMBER_TYPE
The result is a number as defined by XPath 1.0.
SINGLE_NODE_TYPE
The result is a single node, which may be any node of the node set defined by XPath 1.0, or null if the node set is empty. This is a convenience that permits optimization where the caller knows that no more than one such node exists because evaluation can stop after finding the one node of an expression that would otherwise return a node set (of type NODE_SET_TYPE).
Where it is possible that multiple nodes may exist and the first node in document order is required, a NODE_SET_TYPE should be processed using an ordered iterator, because there is no order guarantee for a single node.
STRING_TYPE
The result is a string as defined by XPath 1.0.
Attributes
booleanValue of type boolean, readonly
The value of this boolean result.
Exceptions on retrieval

XPathException

TYPE_ERR: raised if resultType is not BOOLEAN_TYPE.

numberValue of type double, readonly
The value of this number result.
Exceptions on retrieval

XPathException

TYPE_ERR: raised if resultType is not NUMBER_TYPE.

resultType of type unsigned short, readonly
A code representing the type of this result, as defined by the type constants.
singleNodeValue of type Node, readonly
The value of this single node result, which may be null. This result is not guaranteed to be the first node in document order where the expression evaluates to multiple nodes.
Exceptions on retrieval

XPathException

TYPE_ERR: raised if resultType is not SINGLE_NODE_TYPE.

stringValue of type DOMString, readonly
The value of this string result.
Exceptions on retrieval

XPathException

TYPE_ERR: raised if resultType is not STRING_TYPE.

Methods
getSetIterator
Creates an XPathSetIterator which may be used to iterate over the nodes of the set of this result.
Parameters
ordered of type boolean
The set must be iterated in document order.
Return Value

XPathSetIterator

An XPathSetIterator which may be used to iterate the node set.

Exceptions

XPathException

TYPE_ERR: raised if resultType is not NODE_SET_TYPE.

DOMException

INVALID_STATE_ERR: The document has been mutated since the result was returned.

getSetSnapshot
Creates an XPathSetSnapshot which lists the nodes of the set of this result. Unlike an iterator, after the snapshot has been requested, document mutation does not invalidate it.
Parameters
ordered of type boolean
The set must be listed in document order.
Return Value

XPathSetSnapshot

An XPathSetSnapshot which may be used to list the node set.

Exceptions

XPathException

TYPE_ERR: raised if resultType is not NODE_SET_TYPE.

DOMException

INVALID_STATE_ERR: The document has been mutated since the result was returned.

Interface XPathSetIterator

The XPathSetIterator interface iterates the node set resulting from evaluation of an XPath expression.


IDL Definition
interface XPathSetIterator {
  Node               nextNode()
                                        raises(DOMException);
};

Methods
nextNode
Returns the next node from the XPathResult node set. If there are no more nodes in the set to be returned by the iterator, this method returns null.
Return Value

Node

Returns the next node.

Exceptions

DOMException

INVALID_STATE_ERR: The document has been mutated since the node set result was returned.

No Parameters
Interface XPathSetSnapshot

The XPathSetSnapshot interface lists the node set resulting from an evaluation of an XPath expression as a static list that is not invalidated or changed by document mutation.

The individual nodes of a XPathSetSnapshot may be manipulated in the hierarchy and these changes are seen immediately by users referencing the nodes through the snapshot.


IDL Definition
interface XPathSetSnapshot {
  Node               item(in unsigned long index);
  readonly attribute unsigned long    length;
};

Attributes
length of type unsigned long, readonly
The number of nodes in the list. The range of valid child node indices is 0 to length-1 inclusive.
Methods
item
Returns the indexth item in the collection. If index is greater than or equal to the number of nodes in the list, this method returns null.
Parameters
index of type unsigned long
Index into the collection.
Return Value

Node

The node at the indexth position in the NodeList, or null if that is not a valid index.

No Exceptions
Interface XPathNamespace

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.


IDL Definition
interface XPathNamespace : Node {

  // XPathNodeType
  const unsigned short      XPATH_NAMESPACE_NODE           = 13;

  readonly attribute Element          ownerElement;
};

Definition group XPathNodeType

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.

Defined Constants
XPATH_NAMESPACE_NODE
The node is a Namespace.
Attributes
ownerElement of type Element, readonly
The Element 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.

30 August 2001

Appendix A: IDL Definitions

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-20010830/idl.zip

xpath.idl:

// 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;
  typedef dom::Element Element;

  interface XPathNSResolver;
  interface XPathResult;
  interface XPathExpression;
  interface XPathSetIterator;
  interface XPathSetSnapshot;

  exception XPathException {
    unsigned short   code;
  };
  // XPathExceptionCode
  const unsigned short      INVALID_EXPRESSION_ERR         = 1;
  const unsigned short      TYPE_ERR                       = 2;


  interface XPathEvaluator {
    XPathExpression    createExpression(in DOMString expression, 
                                        in XPathNSResolver resolver)
                                        raises(XPathException);
    XPathResult        createResult();
    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);
    XPathResult        evaluateExpression(in XPathExpression expression, 
                                          in Node contextNode, 
                                          in unsigned short type, 
                                          in XPathResult result)
                                        raises(XPathException);
  };

  interface XPathExpression {
  };

  interface XPathNSResolver {
    DOMString          lookupNamespaceURI(in DOMString prefix);
  };

  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      NODE_SET_TYPE                  = 4;
    const unsigned short      SINGLE_NODE_TYPE               = 5;

    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

    XPathSetIterator   getSetIterator(in boolean ordered)
                                        raises(XPathException, 
                                               dom::DOMException);
    XPathSetSnapshot   getSetSnapshot(in boolean ordered)
                                        raises(XPathException, 
                                               dom::DOMException);
  };

  interface XPathSetIterator {
    Node               nextNode()
                                        raises(dom::DOMException);
  };

  interface XPathSetSnapshot {
    Node               item(in unsigned long index);
    readonly attribute unsigned long    length;
  };

  interface XPathNamespace : Node {

    // XPathNodeType
    const unsigned short      XPATH_NAMESPACE_NODE           = 13;

    readonly attribute Element          ownerElement;
  };
};

#endif // _XPATH_IDL_

30 August 2001

Appendix B: Java Language Binding

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-20010830/java-binding.zip

B.1: Other XPath interfaces

org/w3c/dom/xpath/XPathException.java:

package org.w3c.dom.xpath;

public class XPathException extends RuntimeException {
    public XPathException(short code, String message) {
       super(message);
       this.code = code;
    }
    public short   code;
    // XPathExceptionCode
    public static final short INVALID_EXPRESSION_ERR    = 1;
    public static final short TYPE_ERR                  = 2;

}

org/w3c/dom/xpath/XPathEvaluator.java:

package org.w3c.dom.xpath;

import org.w3c.dom.Node;

public interface XPathEvaluator {
    public XPathExpression createExpression(String expression, 
                                            XPathNSResolver resolver)
                                            throws XPathException;

    public XPathResult createResult();

    public XPathNSResolver createNSResolver(Node nodeResolver);

    public XPathResult evaluate(String expression, 
                                Node contextNode, 
                                XPathNSResolver resolver, 
                                short type, 
                                XPathResult result)
                                throws XPathException;

    public XPathResult evaluateExpression(XPathExpression expression, 
                                          Node contextNode, 
                                          short type, 
                                          XPathResult result)
                                          throws XPathException;

}

org/w3c/dom/xpath/XPathExpression.java:

package org.w3c.dom.xpath;

public interface XPathExpression {
}

org/w3c/dom/xpath/XPathNSResolver.java:

package org.w3c.dom.xpath;

public interface XPathNSResolver {
    public String lookupNamespaceURI(String prefix);

}

org/w3c/dom/xpath/XPathResult.java:

package org.w3c.dom.xpath;

import org.w3c.dom.Node;
import org.w3c.dom.DOMException;

public interface XPathResult {
    // XPathResultType
    public static final short ANY_TYPE                  = 0;
    public static final short NUMBER_TYPE               = 1;
    public static final short STRING_TYPE               = 2;
    public static final short BOOLEAN_TYPE              = 3;
    public static final short NODE_SET_TYPE             = 4;
    public static final short SINGLE_NODE_TYPE          = 5;

    public short getResultType();

    public double getNumberValue()
                                     throws XPathException;

    public String getStringValue()
                                     throws XPathException;

    public boolean getBooleanValue()
                                     throws XPathException;

    public Node getSingleNodeValue()
                                     throws XPathException;

    public XPathSetIterator getSetIterator(boolean ordered)
                                           throws XPathException, DOMException;

    public XPathSetSnapshot getSetSnapshot(boolean ordered)
                                           throws XPathException, DOMException;

}

org/w3c/dom/xpath/XPathSetIterator.java:

package org.w3c.dom.xpath;

import org.w3c.dom.Node;
import org.w3c.dom.DOMException;

public interface XPathSetIterator {
    public Node nextNode()
                         throws DOMException;

}

org/w3c/dom/xpath/XPathSetSnapshot.java:

package org.w3c.dom.xpath;

import org.w3c.dom.Node;

public interface XPathSetSnapshot {
    public Node item(int index);

    public int getLength();

}

org/w3c/dom/xpath/XPathNamespace.java:

package org.w3c.dom.xpath;

import org.w3c.dom.Element;
import org.w3c.dom.Node;

public interface XPathNamespace extends Node {
    // XPathNodeType
    public static final short XPATH_NAMESPACE_NODE      = 13;

    public Element getOwnerElement();

}

30 August 2001

Appendix C: ECMAScript Language Binding

This appendix contains the complete ECMAScript [ECMAScript] binding for the Level 3 Document Object Model XPath definitions.

Prototype Object XPathException
The XPathException class has the following constants:
XPathException.INVALID_EXPRESSION_ERR
This constant is of type Number and its value is 1.
XPathException.TYPE_ERR
This constant is of type Number and its value is 2.
Object XPathException
The XPathException object has the following properties:
code
This property is of type Number.
Object XPathEvaluator
The XPathEvaluator object has the following methods:
createExpression(expression, resolver)
This method returns a XPathExpression object.
The expression parameter is of type String.
The resolver parameter is a XPathNSResolver object.
This method can raise a XPathException object.
createResult()
This method returns a XPathResult object.
createNSResolver(nodeResolver)
This method returns a XPathNSResolver object.
The nodeResolver parameter is a Node object.
evaluate(expression, contextNode, resolver, type, result)
This method returns a XPathResult object.
The expression parameter is of type String.
The contextNode parameter is a Node object.
The resolver parameter is a XPathNSResolver object.
The type parameter is of type Number.
The result parameter is a XPathResult object.
This method can raise a XPathException object.
evaluateExpression(expression, contextNode, type, result)
This method returns a XPathResult object.
The expression parameter is a XPathExpression object.
The contextNode parameter is a Node object.
The type parameter is of type Number.
The result parameter is a XPathResult object.
This method can raise a XPathException object.
Object XPathExpression
Object XPathNSResolver
The XPathNSResolver object has the following methods:
lookupNamespaceURI(prefix)
This method returns a String.
The prefix parameter is of type String.
Prototype Object XPathResult
The XPathResult class has the following constants:
XPathResult.ANY_TYPE
This constant is of type Number and its value is 0.
XPathResult.NUMBER_TYPE
This constant is of type Number and its value is 1.
XPathResult.STRING_TYPE
This constant is of type Number and its value is 2.
XPathResult.BOOLEAN_TYPE
This constant is of type Number and its value is 3.
XPathResult.NODE_SET_TYPE
This constant is of type Number and its value is 4.
XPathResult.SINGLE_NODE_TYPE
This constant is of type Number and its value is 5.
Object XPathResult
The XPathResult object has the following properties:
resultType
This read-only property is of type Number.
numberValue
This read-only property is a double object and can raise a XPathException object on retrieval.
stringValue
This read-only property is of type String and can raise a XPathException object on retrieval.
booleanValue
This read-only property is of type Boolean and can raise a XPathException object on retrieval.
singleNodeValue
This read-only property is a Node object and can raise a XPathException object on retrieval.
The XPathResult object has the following methods:
getSetIterator(ordered)
This method returns a XPathSetIterator object.
The ordered parameter is of type Boolean.
This method can raise a XPathException object or a DOMException object.
getSetSnapshot(ordered)
This method returns a XPathSetSnapshot object.
The ordered parameter is of type Boolean.
This method can raise a XPathException object or a DOMException object.
Object XPathSetIterator
The XPathSetIterator object has the following methods:
nextNode()
This method returns a Node object.
This method can raise a DOMException object.
Object XPathSetSnapshot
The XPathSetSnapshot object has the following properties:
length
This read-only property is of type Number.
The XPathSetSnapshot object has the following methods:
item(index)
This method returns a Node object.
The index parameter is of type Number.
Note: This object can also be dereferenced using square bracket notation (e.g. obj[1]). Dereferencing with an integer index is equivalent to invoking the item method with that index.
Prototype Object XPathNamespace
The XPathNamespace class has the following constants:
XPathNamespace.XPATH_NAMESPACE_NODE
This constant is of type Number and its value is 13.
Object XPathNamespace
XPathNamespace has the all the properties and methods of the Node object as well as the properties and methods defined below.
The XPathNamespace object has the following properties:
ownerElement
This read-only property is a Element object.

30 August 2001

Appendix D: Acknowledgements

Many people contributed to the DOM specifications (Level 1, 2 or 3), 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), Angel Diaz (IBM), Arnaud Le Hors (W3C and IBM), Ashok Malhotra (IBM and Microsoft), Ben Chang (Oracle), Bill Smith (Sun), Bill Shea (Merrill Lynch), Bob Sutor (IBM), Chris Lovett (Microsoft), Chris Wilson (Microsoft), David Brownell (Sun), David Ezell (Hewlett Packard Company), David Singer (IBM), Dimitris Dimitriadis (Improve AB), Don Park (invited), Elena Litani (IBM), Eric Vasilik (Microsoft), Gavin Nicol (INSO), Ian Jacobs (W3C), James Clark (invited), James Davidson (Sun), Jared Sorensen (Novell), Jeroen van Rotterdam (X-Hive Corporation), Joe Kesselman (IBM), Joe Lapp (webMethods), Joe Marini (Macromedia), Johnny Stenback (Netscape/AOL), Jon Ferraiolo (Adobe), 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), Mary Brady (NIST), 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), Rezaur Rahman (Intel), Rich Rollman (Microsoft), Rick Gessner (Netscape), Rick Jelliffe (invited), Rob Relyea (Microsoft), Scott Isaacs (Microsoft), Sharon Adler (INSO), Steve Byrne (JavaSoft), Tim Bray (invited), Tim Yu (Oracle), Tom Pixley (Netscape/AOL), Vidur Apparao (Netscape), Vinod Anupam (Lucent).

Thanks to all those who have helped to improve this specification by sending suggestions and corrections (Please, keep bugging us with your issues!).

D.1: Production Systems

This specification was written in XML. The HTML, OMG IDL, Java and ECMAScript 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.

30 August 2001

Glossary

Editors:
Arnaud Le Hors, W3C
Robert S. Sutor, IBM Research (for DOM Level 1)

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.

API
An API is an Application Programming Interface, a set of functions or methods used to access some functionality.
element
Each document contains one or more elements, the boundaries of which are either delimited by start-tags and end-tags, or, for empty elements by an empty-element tag. Each element has a type, identified by name, and may have a set of attributes. Each attribute has a name and a value. See Logical Structures in XML [XML].
live
An object is live if any change to the underlying document structure is reflected in the object.
model
A model is the actual data representation for the information at hand. Examples are the structural model and the style model representing the parse structure and the style information associated with a document. The model might be a tree, or a directed graph, or something else.
namespace prefix
A namespace prefix is a string that associates an element or attribute name with a namespace URI in XML. See namespace prefix in Namespaces in XML [XML Namespaces].
namespace URI
A namespace URI is a URI that identifies an XML namespace. This is called the namespace name in Namespaces in XML [XML Namespaces].
read only node
A read only node is a node that is immutable. This means its list of children, its content, and its attributes, when it is an element, cannot be changed in any way. However, a read only node can possibly be moved, when it is not itself contained in a read only node.
tokenized
The description given to various information items (for example, attribute values of various types, but not including the StringType CDATA) after having been processed by the XML processor. The process includes stripping leading and trailing white space, and replacing multiple space characters by one. See the definition of tokenized type.
well-formed document
A document is well-formed if it is tag valid and entities are limited to single elements (i.e., single sub-trees).

30 August 2001

References

For the latest version of any W3C specification please consult the list of W3C Technical Reports available at http://www.w3.org/TR.

F.1: Normative references

DOM Level 3 Core
W3C (World Wide Web Consortium) Document Object Model Level 3 Core Specification, August 2001. Available at http://www.w3.org/TR/2001/WD-DOM-Level-3-Core-20010605
ECMAScript
ISO (International Organization for Standardization). ISO/IEC 16262:1998. ECMAScript Language Specification. Available from ECMA (European Computer Manufacturers Association) at http://www.ecma.ch/ecma1/STAND/ECMA-262.HTM
XML Information set
W3C (World Wide Web Consortium) XML Information Set, August 2001. Available at http://www.w3.org/TR/2001/PR-xml-infoset-20010810
Java
Sun Microsystems Inc. The Java Language Specification, James Gosling, Bill Joy, and Guy Steele, September 1996. Available at http://java.sun.com/docs/books/jls
OMGIDL
OMG (Object Management Group) IDL (Interface Definition Language) defined in The Common Object Request Broker: Architecture and Specification, version 2.3.1, October 1999. Available from http://www.omg.org
XML
W3C (World Wide Web Consortium) Extensible Markup Language (XML) 1.0, October 2000. Available at http://www.w3.org/TR/2000/REC-xml-20001006
XML Namespaces
W3C (World Wide Web Consortium) Namespaces in XML, January 1999. Available at http://www.w3.org/TR/1999/REC-xml-names-19990114
XPath 1.0
W3C (World Wide Web Consortium) XML Path Language (XPath) Version 1.0, November 1999. Available at http://www.w3.org/TR/1999/REC-xpath-19991116.

30 August 2001

Index

ANY_TYPE API 1, 2
 
BOOLEAN_TYPE booleanValue
 
createExpression createNSResolver createResult
 
DOM Level 3 Core 1, 2, 3
 
ECMAScript element 1, 2, 3 evaluate
evaluateExpression
 
getSetIterator getSetSnapshot
 
INVALID_EXPRESSION_ERR item
 
Java
 
length live 1, 2 lookupNamespaceURI
 
model 1, 2
 
namespace prefix 1, 2, 3, 4, 5 namespace URI 1, 2, 3, 4 nextNode
NODE_SET_TYPE NUMBER_TYPE numberValue
 
OMGIDL ownerElement
 
read only node 1, 2 resultType
 
SINGLE_NODE_TYPE singleNodeValue STRING_TYPE
stringValue
 
tokenized TYPE_ERR
 
well-formed document
 
XML 1, 2 XML Information set 1, 2 XML Namespaces 1, 2, 3
XPath 1.0 1, 2 XPATH_NAMESPACE_NODE XPathEvaluator
XPathException XPathExpression XPathNamespace
XPathNSResolver XPathResult XPathSetIterator
XPathSetSnapshot