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 is a Candidate
Recommendation of "DOM Level 3 XPath" and is based on the feedback
received during the Last Call period. The DOM Working Group
expects to request that the Director advance this specification to
Proposed Recommendation after the DOM Working Group documents two
interoperable implementations of at least one normative binding.
Basic tests of features of this specification will be produced and
used in this effort. The two implementations must be produced by
different organizations. The Working Group expects to satisfy those
requirements by 26 May 2003 and afterwards submit the tests
to the DOM Test Suite.
Please send reviews before the review period ends to the public
mailing list www-dom@w3.org. An
archive is available at http://lists.w3.org/Archives/Public/www-dom/.
Individuals or organizations are also invited to send a message
to the public mailing list if they intend to produce an
implementation of this module.
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, W3C.
This document has been produced as part of the W3C DOM Activity. The
authors of this document are the DOM Working Group members.
An implementation
report is also available.
Patent disclosures relevant to this specification may be found
on the Working Group's patent
disclosure page.
A list of current W3C
Recommendations and other technical documents can be found at
http://www.w3.org/TR.
W3C Copyright Notices and
Licenses
Copyright © 2003 World Wide Web Consortium, (Massachusetts Institute
of Technology, European Research Consortium for
Informatics and Mathematics, 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.
W3C® Document Copyright Notice and License
Note: This section is a copy of the W3C®
Document Notice and License and could be found at
http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231.
Copyright © 2003 World Wide Web Consortium, (Massachusetts Institute
of Technology, European Research Consortium for
Informatics and Mathematics, Keio University). All Rights
Reserved.
http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231
Public documents on the W3C site are provided by the copyright
holders under the following license. 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 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:
- A link or URL to the original W3C document.
- The pre-existing copyright notice of the original author, or if
it doesn't exist, a notice (hypertext is preferred, but a textual
representation is permitted) of the form: "Copyright ©
[$date-of-document] World Wide Web Consortium, (Massachusetts Institute
of Technology, European Research Consortium for
Informatics and Mathematics, Keio University). All Rights Reserved.
http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231"
- 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.
W3C® Software Copyright Notice and License
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/2002/copyright-software-20021231
Copyright © 2003 World Wide Web Consortium, (Massachusetts Institute
of Technology, European Research Consortium for
Informatics and Mathematics, Keio University). All Rights
Reserved.
http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
This work (and included software, documentation such as READMEs,
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 copy, modify, and distribute 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:
- The full text of this NOTICE in a location viewable to users of
the redistributed or derivative work.
- Any pre-existing intellectual property disclaimers, notices, or
terms and conditions. If none exist, the W3C® Short
Software Notice should be included (hypertext is preferred,
text is permitted) within the body of any redistributed or
derivative code.
- Notice of any changes or modifications to the 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.
1. Document Object Model XPath
- Editor:
- Ray Whitmer, Netscape/AOL
1.1. Introduction
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.
1.2. Mapping DOM to XPath
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.
1.2.1. Element Nodes
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.
1.2.2. Attribute Nodes
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.
1.2.3. Namespace Nodes
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.
1.2.4. 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 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.
1.2.5. Entity Reference
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.
1.2.7. Processing Instruction
Nodes
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.
1.2.8. Document order
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.
1.4. Interfaces
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".
- Exception XPathException
-
A new exception has been created for exceptions specific to
these XPath interfaces.
IDL Definition-
- Definition group XPathExceptionCode
-
- Defined Constants
-
INVALID_EXPRESSION_ERR- If the expression has a syntax error or otherwise is not a
legal expression according to the rules of the specific
XPathEvaluator or
contains specialized extension functions or variables not supported
by this implementation.
TYPE_ERR- If the expression cannot be converted to return the specified
type.
- Interface XPathEvaluator
-
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.
IDL Definition-
- 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 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.
Exceptions
|
XPathException
|
INVALID_EXPRESSION_ERR: Raised if the expression is not legal
according to the rules of the XPathEvaluator.
|
|
DOMException
|
NAMESPACE_ERR: Raised if the expression contains namespace prefixes
which cannot be resolved by the specified XPathNSResolver.
|
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. This
adapter works like the DOM Level 3 method
lookupNamespaceURI 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.
Parameters
nodeResolver of type
Node- The node to be used as a context for namespace
resolution.
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. 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 XPathNSResolver- The
resolver 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
short- If a specific
type is specified, then the result
will be returned as the corresponding type.
For XPath 1.0 results, this must be one of the codes of the XPathResult
interface.
result of type
DOMObject- The
result 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.
For XPath 1.0 results, this object will be of type XPathResult.
Return Value
|
DOMObject
|
The result of the evaluation of the XPath expression.
For XPath 1.0 results, this object will be of type XPathResult.
|
Exceptions
|
XPathException
|
INVALID_EXPRESSION_ERR: Raised if the expression is not legal
according to the rules of the XPathEvaluatori
TYPE_ERR: Raised if the result cannot be converted to return the
specified type.
|
|
DOMException
|
NAMESPACE_ERR: Raised if the expression contains namespace prefixes
which cannot be resolved by the specified XPathNSResolver.
WRONG_DOCUMENT_ERR: The Node is from a document that is not
supported by this XPathEvaluator.
NOT_SUPPORTED_ERR: The Node is not a type permitted as an XPath
context node or the request type is not permitted by this
XPathEvaluator.
|
- Interface XPathExpression
-
The XPathExpression interface represents a parsed
and resolved XPath expression.
IDL Definition-
- Methods
-
evaluate-
Evaluates this XPath expression and returns a
result.
Parameters
contextNode of type
Node- The
context 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.
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
DOMObject- The
result 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.
For XPath 1.0 results, this object will be of type XPathResult.
Return Value
|
DOMObject
|
The result of the evaluation of the XPath expression.
For XPath 1.0 results, this object will be of type XPathResult.
|
Exceptions
|
XPathException
|
TYPE_ERR: Raised if the result cannot be converted to return the
specified type.
|
|
DOMException
|
WRONG_DOCUMENT_ERR: The Node is from a document that is not
supported by the XPathEvaluator that created this
XPathExpression.
NOT_SUPPORTED_ERR: The Node is not a type permitted as an XPath
context node or the request type is not permitted by this
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-
- Methods
-
lookupNamespaceURI-
Look up the
namespace URI
associated to the given
namespace prefix.
The XPath evaluator must never call this with a
null
or empty argument, because the result of doing this is undefined.
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 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.
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 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);
};
- Definition group XPathResultType
-
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.
- 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 returns whatever type naturally
results from evaluation of the expression.
If the natural result is a node set when ANY_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_TYPE- The result is a node
set as defined by [XPath 1.0] and will be accessed as a
single node, which may be
nullif 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.
If there is more than one node in the actual result, the single
node returned might not be the first in document order.
BOOLEAN_TYPE- The result is a boolean
as defined by [XPath 1.0]. Document modification
does not invalidate the boolean, but may mean that reevaluation
would not yield the same boolean.
FIRST_ORDERED_NODE_TYPE- The result is a node
set as defined by [XPath 1.0] and will be accessed as a
single node, which may be
null 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.
If there are more than one node in the actual result, the single
node returned will be the first in document order.
NUMBER_TYPE- The result is a number
as defined by [XPath 1.0]. Document modification
does not invalidate the number, but may mean that reevaluation
would not yield the same number.
ORDERED_NODE_ITERATOR_TYPE- The result is a node set as defined by [XPath 1.0]
that will be accessed iteratively, which will produce
document-ordered nodes. Document modification invalidates the
iteration.
ORDERED_NODE_SNAPSHOT_TYPE- The result is a node
set as defined by [XPath 1.0] that will be accessed as a
snapshot list of nodes that will be in original document order.
Document modification does not invalidate the snapshot but may mean
that reevaluation would not yield the same snapshot and nodes in
the snapshot may have been altered, moved, or removed from the
document.
STRING_TYPE- The result is a string
as defined by [XPath 1.0]. Document modification
does not invalidate the string, but may mean that the string no
longer corresponds to the current document.
UNORDERED_NODE_ITERATOR_TYPE- The result is a node
set as defined by [XPath 1.0] that will be accessed
iteratively, which may not produce nodes in a particular order.
Document modification invalidates the iteration.
This is the default type returned if the result is a node set and
ANY_TYPE is requested.
UNORDERED_NODE_SNAPSHOT_TYPE- The result is a node
set as defined by [XPath 1.0] that will be accessed as a
snapshot list of nodes that may not be in a particular order.
Document modification does not invalidate the snapshot but may mean
that reevaluation would not yield the same snapshot and nodes in
the snapshot may have been altered, moved, or removed from the
document.
- Attributes
-
booleanValue of type
boolean, readonly- The value of this boolean result.
invalidIteratorState
of type boolean, readonly- Signifies that the iterator has become invalid. True if
resultType 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- The value of this number result. 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.
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.
Exceptions on retrieval
|
XPathException
|
TYPE_ERR: raised if resultType is not
ANY_UNORDERED_NODE_TYPE or
FIRST_ORDERED_NODE_TYPE.
|
snapshotLength of type
unsigned long, readonly- The number of nodes 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
UNORDERED_NODE_SNAPSHOT_TYPE or
ORDERED_NODE_SNAPSHOT_TYPE.
|
stringValue of type
DOMString, readonly- The value of this string result.
- Methods
-
iterateNext-
Iterates and returns the next node from the
node set or
nullif there are no more nodes.
Return Value
|
Node
|
Returns the next node.
|
Exceptions
|
XPathException
|
TYPE_ERR: raised if resultType is not
UNORDERED_NODE_ITERATOR_TYPE or
ORDERED_NODE_ITERATOR_TYPE.
|
|
DOMException
|
INVALID_STATE_ERR: The document has been mutated since the
result was returned.
|
No Parameters
snapshotItem-
Returns the
indexth 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.
Parameters
index of type
unsigned long- Index into the snapshot collection.
Return Value
|
Node
|
The node at the indexth position in the
NodeList, or null if that is not a valid
index.
|
Exceptions
|
XPathException
|
TYPE_ERR: raised if resultType is not
UNORDERED_NODE_SNAPSHOT_TYPE or
ORDERED_NODE_SNAPSHOT_TYPE.
|
- 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
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.
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.
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 and invited expert), 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 former Chair), Ramesh
Lekshmynarayanan (Merrill Lynch), Ray Whitmer (iMall, Excite@Home,
and Netscape/AOL, Chair), 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!).
Special thanks to the DOM Conformance Test Suites
contributors: Curt Arnold, Fred Drake, Mary Brady (NIST), Rick
Rivello (NIST), Robert Clary (Netscape).
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.