Document Object Model XPath 2.0

1 Introduction

Working drafts of the XPath 2.0 Data Model describe a data model that in many instances may be mapped to XPath 1.0, and vice versa, but this does not make an XPath 1.0 implementation the optimal representation of XPath 2.0, or vice versa.

It is expected that some implementers of the DOM XPath Module APIs will also want to implement XPath 2.0 in addition to the XPath 1.0 support which is defined by that module for the extended function set, the schema-typed results, or to implement other specifications that will be based upon the XPath 2.0 data model.

The design of the DOM XPath modules make it possible to extend the API set for XPath 2.0 support without compromising the use of these APIs for XPath 1.0 functionality.  The purpose of this note is to give early  implementers of XPath 2.0 a simple common starting point for interoperability and experimentation which could upon successful implementation lead to easier standardization.

2 Limits of this Note

A number of things were left out of the DOM XPath module in the interests of keeping the specification simple.  It was foreseen that standard API extensions could be defined for meeting additional requirements such as (re)invoking the XPath engine with more than a single node contained in the current context or adding custom variables and functions (see issue ...).  It would make sense for  implementers interested in standardizing these extensions to submit proposals as notes until such standardization is undertaken.  But these extensions are seen as orthogonal to the extensions required to support XPath 2.0 and are not needed in this note.

3 Separate Support for Different Versions

The intent of the APIs in this note is to enable implementations to separately permit implementation  of XPath 1.0 or 2.0.  If XPath 2.0 support is provided, this is requested using separate request codes.  An implementation may choose to support only XPath 1.0, only XPath 2.0, or support the request codes of both 1.0 and 2.0.  

Implementations which support both may share much  of the implementation underneath, but the results must be the type associated with the corresponding request.

All DOM XPath 3.0 XPathResult request types defined in that recommendation -- supported if DOMImplementation.hasFeature("xpath","3.0") returns true -- return XPathResult objects that represent the result of an XPath 1.0 query according to those specifications.

All DOM XPathResult2 request types defined in this note -- supported if DOMImplementation.hasFeature("xpath2","3.0") returns true -- return XPathResult2 objects  that represent the result of an XPath 2.0 query according to this note or any formal recommendation derived from this note.

4 Mapping DOM to XPath 2.0

Most of the details of mapping DOM to XPath as described in the Document Object Model XPath are applicable to XPath 2.0, but there are certain differences described here.

4.1 Document Order

XPath 2.0 results are sequences with an order defined by XPath 2.0, which is independent of any order defined by DOM or DOM XPath.  For this reason, the API-level support for order available in the XPathResult is not desirable in XPathResult2 results, which would compete with the definitions of the XPath 2.0 specification.

4.2 Namespace Nodes

XPath 2.0 seems to make namespace nodes less important than they were in XPath 1.0.  DOM XPath 2.0 extensions should not rule out namespace nodes, but should consider them only possibly necessary for maintaining backwards compatibility with XPath 1.0 and otherwise generally undesirable.  It is observed that where supported by XPath 2.0 implementations, attributes of namespace nodes may have to be adapted to better correspond to the XPath 2.0 specification.  Such adaptation may be best determined after the XPath 2.0 data model is completed and after there is experience with a DOM implementation of XPath 2.0.

4.3 Data Types

XPath 2.0 supports association of XML Schema data types with validated nodes of an XPath node hierarchy and with primitive values in returned sequences.  This replaces XPath 1.0 simple static data typing.

The static-type-specific request codes available at the API level in XPathResult are therefore not appropriate.  XPathResult2 combines schema-centric data typing with data conversion methods that better map XPath 2.0 data types to common programming language types.

DOM Level 3 Core defines XML Schema type information that is attached to nodes during validation, which is similar to the XPath 2.0 type information that is attached to nodes during validation.

5 New Interfaces

Interface XPathResult2

The XPathResult2 interface represents the result of the evaluation of an XPath 2.0 expression within the context of a particular node. Since evaluation of an XPath 2.0 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 XPathResult2 {

  // XPathResultType2
  const unsigned short      FIRST_RESULT                = 100;
  const unsigned short      ITERATOR_RESULT             = 101;
  const unsigned short      SNAPSHOT_RESULT             = 102;

  readonly attribute unsigned short  resultType;
  readonly attribute boolean         isNode;
  readonly attribute TypeInfo        typeInfo;
  readonly attribute double          asDouble;
                                        // raises(XPathException, DOMException) on retrieval
  readonly attribute int             asInt;
                                        // raises(XPathException, DOMException) on retrieval
  readonly attribute DOMString       asString;
                                        // raises(XPathException, DOMException) on retrieval
  readonly attribute boolean         asBoolean;
                                        // raises(XPathException, DOMException) on retrieval
  readonly attribute Node            asNode;
                                        // raises(XPathException, DOMException) on retrieval

  readonly attribute boolean         invalidIteratorState;
  readonly attribute unsigned long   snapshotLength;
                                        // raises(XPathException) on retrieval

  boolean            iterateNext()
                                        raises(XPathException, 
                                               DOMException);
  boolean            snapshotItem(in unsigned long index)
                                        raises(XPathException);
};

Definition group XPathResultType2

An integer indicating what type of result this is.

Defined Constants
FIRST_RESULT
The result is a sequence as defined by XPath 2.0 and will be accessed as a single current value or there will be no current value if the sequence is empty. Document modification does not invalidate the value, but may mean that the result no longer corresponds to the current document. This is a convenience that permits optimization since the implementation can stop once the first item in the resulting sequence has been found.
If there is more than one item in the actual result, the single item returned might not be the first in document order.
ITERATOR-RESULT
The result is a sequence as defined by XPath 2.0 that will be accessed iteratively. Document modification invalidates the iteration.
SNAPSHOT-RESULT
The result is a sequence as defined by XPath 2.0 that will be accessed as a snapshot list of values. Document modification does not invalidate the snapshot but may mean that reevaluation would not yield the same snapshot and any items in the snapshot may have been altered, moved, or removed from the document.

Attributes

asBoolean of type boolean, readonly
Conversion of the current result to boolean.
Exceptions on retrieval

XPathException

TYPE_ERR: raised if  cannot be properly converted to boolean.

DOMException

INVALID_STATE_ERR: There is no current result in the result.
asDouble of type double, readonly
Conversion of the current result to double. If the native double type of the DOM binding does not directly support the exact IEEE 754 result of the XPath expression, then it is up to the definition of the binding to specify how the XPath number is converted to the native binding number
Exceptions on retrieval

XPathException

TYPE_ERR: raised if current result cannot be properly converted to double.

DOMException

INVALID_STATE_ERR: There is no current result in the result.
asInt of type int, readonly
Conversion of the current result to int.
Exceptions on retrieval

XPathException

TYPE_ERR: raised if current result cannot be properly converted to int.

DOMException

INVALID_STATE_ERR: There is no current result in the result.
asNode of type Node, readonly
Retrieve the current node value..
Exceptions on retrieval

XPathException

TYPE_ERR: raised if current result is not a node.

DOMException

INVALID_STATE_ERR: There is no current result in the result.
asString of type DOMString, readonly
Conversion of the current result to string.
Exceptions on retrieval

XPathException

TYPE_ERR: raised if current result cannot be properly converted to string.

DOMException

INVALID_STATE_ERR: There is no current result in the result.
invalidIteratorState of type boolean, readonly
Signifies that the iterator has become invalid.
isNode of type boolean, readonly
True if the result has a current result and the value is a node.
resultType of type unsigned short, readonly
A code representing the type of this result, as defined by the type constants.
snapshotLength of type unsigned long, readonly
The number of items in the result snapshot. Valid values for snapshotItem indices are 0 to snapshotLength-1 inclusive.
Exceptions on retrieval

XPathException

TYPE_ERR: raised if resultType is not SNAPSHOT_RESULT .
typeInfo of type TypeInfo, readonly
The DOM type info of the current result node or value.
Methods
iterateNext
Iterates and returns true if the current result is the next item from the sequence or false if there are no more items.
Return Value

boolean

True if the current result is the next item from the sequence or false if there are no more items.
Exceptions

XPathException

TYPE_ERR: raised if resultType is not ITERATOR_RESULT.

DOMException

INVALID_STATE_ERR: The document has been mutated since the result was returned.
No Parameters
snapshotItem
Sets the current result to the indexth item in the snapshot collection. If index is greater than or equal to the number of items in the list, this method returns false. Unlike the iterator result, the snapshot does not become invalid, but may not correspond to the current document if it is mutated.
Parameters
index of type unsigned long
Index into the snapshot collection.
Return Value

boolean

True if the current result is the indexth position in the sequence or false if that is not a valid index.
Exceptions

XPathException

TYPE_ERR: raised if resultType is not SNAPSHOT_RESULT.