You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xerces.apache.org by el...@apache.org on 2002/09/19 00:03:18 UTC
cvs commit: xml-xerces/java/src/org/w3c/dom/xpath XPathEvaluator.java XPathException.java XPathExpression.java XPathNSResolver.java XPathNamespace.java XPathResult.java
elena 2002/09/18 15:03:18
Modified: java/src/org/w3c/dom/ls DOMBuilder.java
DOMBuilderFilter.java DOMEntityResolver.java
DOMImplementationLS.java DOMInputSource.java
DOMWriter.java DOMWriterFilter.java DocumentLS.java
LSLoadEvent.java LSProgressEvent.java
ParseErrorEvent.java
Added: java/src/org/w3c/dom/xpath XPathEvaluator.java
XPathException.java XPathExpression.java
XPathNSResolver.java XPathNamespace.java
XPathResult.java
Log:
Adding DOM Level 3 XPath to the org.w3c.dom.xpath package.
These are experimental interfaces and maybe modified or removed in the future
Revision Changes Path
1.5 +2 -2 xml-xerces/java/src/org/w3c/dom/ls/DOMBuilder.java
Index: DOMBuilder.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/DOMBuilder.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- DOMBuilder.java 26 Aug 2002 21:51:19 -0000 1.4
+++ DOMBuilder.java 18 Sep 2002 22:03:17 -0000 1.5
@@ -18,11 +18,11 @@
import org.apache.xerces.dom3.DOMErrorHandler;
/**
- * DOM Level 3 WD Experimental:
+ * <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
- * or obsoleted by other documents at any time.
+ * or obsoleted by other documents at any time.</strong> <p>
* A interface to an object that is able to build a DOM tree from various
* input sources.
* <p><code>DOMBuilder</code> provides an API for parsing XML documents and
1.4 +2 -2 xml-xerces/java/src/org/w3c/dom/ls/DOMBuilderFilter.java
Index: DOMBuilderFilter.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/DOMBuilderFilter.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- DOMBuilderFilter.java 26 Aug 2002 21:51:19 -0000 1.3
+++ DOMBuilderFilter.java 18 Sep 2002 22:03:17 -0000 1.4
@@ -16,11 +16,11 @@
import org.w3c.dom.Node;
/**
- * DOM Level 3 WD Experimental:
+ * <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
- * or obsoleted by other documents at any time.
+ * or obsoleted by other documents at any time.</strong> <p>
* <code>DOMBuilderFilter</code>s provide applications the ability to examine
* nodes as they are being constructed during a parse. As each node is
* examined, it may be modified or removed, or the entire parse may be
1.4 +2 -2 xml-xerces/java/src/org/w3c/dom/ls/DOMEntityResolver.java
Index: DOMEntityResolver.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/DOMEntityResolver.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- DOMEntityResolver.java 26 Aug 2002 21:51:19 -0000 1.3
+++ DOMEntityResolver.java 18 Sep 2002 22:03:17 -0000 1.4
@@ -13,11 +13,11 @@
package org.w3c.dom.ls;
/**
- * DOM Level 3 WD Experimental:
+ * <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
- * or obsoleted by other documents at any time.
+ * or obsoleted by other documents at any time.</strong> <p>
* <code>DOMEntityResolver</code> Provides a way for applications to redirect
* references to external entities.
* <p>Applications needing to implement customized handling for external
1.4 +2 -2 xml-xerces/java/src/org/w3c/dom/ls/DOMImplementationLS.java
Index: DOMImplementationLS.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/DOMImplementationLS.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- DOMImplementationLS.java 26 Aug 2002 21:51:19 -0000 1.3
+++ DOMImplementationLS.java 18 Sep 2002 22:03:17 -0000 1.4
@@ -15,11 +15,11 @@
import org.w3c.dom.DOMException;
/**
- * DOM Level 3 WD Experimental:
+ * <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
- * or obsoleted by other documents at any time.
+ * or obsoleted by other documents at any time.</strong> <p>
* <code>DOMImplementationLS</code> contains the factory methods for creating
* objects that implement the <code>DOMBuilder</code> (parser) and
* <code>DOMWriter</code> (serializer) interfaces.
1.4 +2 -2 xml-xerces/java/src/org/w3c/dom/ls/DOMInputSource.java
Index: DOMInputSource.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/DOMInputSource.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- DOMInputSource.java 26 Aug 2002 21:51:19 -0000 1.3
+++ DOMInputSource.java 18 Sep 2002 22:03:17 -0000 1.4
@@ -13,11 +13,11 @@
package org.w3c.dom.ls;
/**
- * DOM Level 3 WD Experimental:
+ * <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
- * or obsoleted by other documents at any time.
+ * or obsoleted by other documents at any time.</strong> <p>
* This interface represents a single input source for an XML entity.
* <p> This interface allows an application to encapsulate information about
* an input source in a single object, which may include a public
1.5 +2 -2 xml-xerces/java/src/org/w3c/dom/ls/DOMWriter.java
Index: DOMWriter.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/DOMWriter.java,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- DOMWriter.java 26 Aug 2002 21:51:19 -0000 1.4
+++ DOMWriter.java 18 Sep 2002 22:03:17 -0000 1.5
@@ -17,11 +17,11 @@
import org.apache.xerces.dom3.DOMErrorHandler;
/**
- * DOM Level 3 WD Experimental:
+ * <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
- * or obsoleted by other documents at any time.
+ * or obsoleted by other documents at any time.</strong> <p>
* <code>DOMWriter</code> provides an API for serializing (writing) a DOM
* document out in an XML document. The XML data is written to an output
* stream, the type of which depends on the specific language bindings in
1.4 +2 -2 xml-xerces/java/src/org/w3c/dom/ls/DOMWriterFilter.java
Index: DOMWriterFilter.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/DOMWriterFilter.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- DOMWriterFilter.java 26 Aug 2002 21:51:19 -0000 1.3
+++ DOMWriterFilter.java 18 Sep 2002 22:03:17 -0000 1.4
@@ -15,11 +15,11 @@
import org.w3c.dom.traversal.NodeFilter;
/**
- * DOM Level 3 WD Experimental:
+ * <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
- * or obsoleted by other documents at any time.
+ * or obsoleted by other documents at any time.</strong> <p>
* <code>DOMWriterFilter</code>s provide applications the ability to examine
* nodes as they are being serialized. <code>DOMWriterFilter</code> lets the
* application decide what nodes should be serialized or not.
1.4 +2 -2 xml-xerces/java/src/org/w3c/dom/ls/DocumentLS.java
Index: DocumentLS.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/DocumentLS.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- DocumentLS.java 26 Aug 2002 21:51:19 -0000 1.3
+++ DocumentLS.java 18 Sep 2002 22:03:17 -0000 1.4
@@ -16,11 +16,11 @@
import org.w3c.dom.DOMException;
/**
- * DOM Level 3 WD Experimental:
+ * <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
- * or obsoleted by other documents at any time.
+ * or obsoleted by other documents at any time.</strong> <p>
* The <code>DocumentLS</code> interface provides a mechanism by which the
* content of a document can be replaced with the DOM tree produced when
* loading a URI, or parsing a string. The expectation is that an instance
1.4 +2 -2 xml-xerces/java/src/org/w3c/dom/ls/LSLoadEvent.java
Index: LSLoadEvent.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/LSLoadEvent.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- LSLoadEvent.java 26 Aug 2002 21:51:19 -0000 1.3
+++ LSLoadEvent.java 18 Sep 2002 22:03:17 -0000 1.4
@@ -16,11 +16,11 @@
import org.w3c.dom.events.Event;
/**
- * DOM Level 3 WD Experimental:
+ * <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
- * or obsoleted by other documents at any time.
+ * or obsoleted by other documents at any time.</strong> <p>
* This interface represents a load event object that signals the completion
* of a document load.
* <p>See also the <a href='http://www.w3.org/TR/2002/WD-DOM-Level-3-LS-20020725'>Document Object Model (DOM) Level 3 Load
1.4 +2 -2 xml-xerces/java/src/org/w3c/dom/ls/LSProgressEvent.java
Index: LSProgressEvent.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/LSProgressEvent.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- LSProgressEvent.java 26 Aug 2002 21:51:19 -0000 1.3
+++ LSProgressEvent.java 18 Sep 2002 22:03:17 -0000 1.4
@@ -15,11 +15,11 @@
import org.w3c.dom.events.Event;
/**
- * DOM Level 3 WD Experimental:
+ * <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
- * or obsoleted by other documents at any time.
+ * or obsoleted by other documents at any time.</strong> <p>
* This interface represents a progress event object that notifies the
* application about progress as a document is parsed. It extends the
* <code>Event</code> interface defined in .
1.4 +2 -3 xml-xerces/java/src/org/w3c/dom/ls/ParseErrorEvent.java
Index: ParseErrorEvent.java
===================================================================
RCS file: /home/cvs/xml-xerces/java/src/org/w3c/dom/ls/ParseErrorEvent.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ParseErrorEvent.java 23 Aug 2002 20:14:40 -0000 1.3
+++ ParseErrorEvent.java 18 Sep 2002 22:03:17 -0000 1.4
@@ -16,12 +16,11 @@
import org.apache.xerces.dom3.DOMError;
/**
- * DOM Level 3 WD Experimental:
+ * <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
- * or obsoleted by other documents at any time.
- * <p>
+ * or obsoleted by other documents at any time.</strong> <p>
* ParseErrorEvent is the event that is fired if there's an error in the XML
* document being parsed.
* <p>See also the <a href='http://www.w3.org/TR/2002/WD-DOM-Level-3-ASLS-20020409'>Document Object Model (DOM) Level 3 Abstract Schemas and Load
1.1 xml-xerces/java/src/org/w3c/dom/xpath/XPathEvaluator.java
Index: XPathEvaluator.java
===================================================================
/*
* Copyright (c) 2002 World Wide Web Consortium,
* (Massachusetts Institute of Technology, Institut National de
* Recherche en Informatique et en Automatique, Keio University). All
* Rights Reserved. This program is distributed under the W3C's Software
* Intellectual Property License. This program is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY; without even
* the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE.
* See W3C License http://www.w3.org/Consortium/Legal/ for more details.
*/
package org.w3c.dom.xpath;
import org.w3c.dom.Node;
import org.w3c.dom.DOMException;
/**
* <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
* or obsoleted by other documents at any time.</strong> <p>
* <code>XPathEvaluator</code>, which will provide evaluation of XPath 1.0
* expressions with no specialized extension functions or variables. It is
* expected that the <code>XPathEvaluator</code> interface will be
* implemented on the same object which implements the <code>Document</code>
* interface in an implementation which supports the XPath DOM module.
* <code>XPathEvaluator</code> implementations may be available from other
* sources that may provide support for special extension functions or
* variables which are not defined in this specification. The methods of
* XPathExpression should be named with more-XPath- specific names because
* the interface will often be implemented by the same object which
* implements document.No change.The point of interfaces is to localize the
* implementing namespace. This would make the method names unnecessarily
* long and complex even though there are no conflicts in the interface
* itself. The new core method getInterface is designed for discovering
* interfaces of additional modules that may not be directly implemented on
* the objects to which they are attached. This could be used to implement
* XPath on a separate object. The user only refers to the separate
* interfaces and not the proprietary aggregate implementation.Should entity
* refs be supported so that queries can be made on them?No change.We will
* not do this now. They are not part of the XPath data model. Note that
* they may be present in the hierarchy of returned nodes, but may not
* directly be requested or returned in the node set.What does createResult
* create when one wants to reuse the XPath?It is not useful.Removed method.
* Should ordering be a separate flag, or a type of result that can be
* requested. As a type of result, it can be better optimized in
* implementations.It makes sense as a type of result. Changed.Removed
* method.Implementing XPathEvaluator on Document can be a problem due to
* conflicts in the names of the methods.The working group finds no better
* solution. GetInterface in Level 3 permits the object to be implemented
* separately. We should be committed to this. We will leave this issue open
* to see if we get more feedback on it.How does this interface adapt to
* XPath 2.0 and other query languages.No change.This interface is not
* intended to adapt to XPath 2.0 or other languages. The models of these
* are likely to be incompatible enough to require new APIs.For alternate
* implementations that can use this API, it can be obtained from different
* sources.Support for custom variables and functions would be very useful.
* No change.It is possible for an implementation to supply alternative
* sources of an XPathEvaluator that can be customized with a custom
* variable and function context. We do not specify how this is
* accomplished. It is too complex to address in this version of the XPath
* DOM.
* <p>See also the <a href='http://www.w3.org/TR/2002/WD-DOM-Level-3-XPath-20020328'>Document Object Model (DOM) Level 3 XPath Specification</a>.
*/
public interface XPathEvaluator {
/**
* 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.createExpression should not raise
* exceptions about type coercion.This was already fixed in the public
* draft.
* @param expression The XPath expression string to be parsed.
* @param resolver The <code>resolver</code> permits translation of
* prefixes within the XPath expression into appropriate namespace URIs
* . If this is specified as <code>null</code>, any namespace prefix
* within the expression will result in <code>DOMException</code>
* being thrown with the code <code>NAMESPACE_ERR</code>.
* @return The compiled form of the XPath expression.
* @exception XPathException
* INVALID_EXPRESSION_ERR: Raised if the expression is not legal
* according to the rules of the <code>XPathEvaluator</code>i
* @exception DOMException
* NAMESPACE_ERR: Raised if the expression contains namespace prefixes
* which cannot be resolved by the specified
* <code>XPathNSResolver</code>.
*/
public XPathExpression createExpression(String expression,
XPathNSResolver resolver)
throws XPathException, DOMException;
/**
* 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 by calling the
* method <code>lookupNamespacePrefix</code> on <code>Node</code>.It
* should be possible to create an XPathNSResolver that does not rely on
* a node, but which implements a map of resolutions that can be added
* to by the application.No change.The application can easily create
* this, which was why the interface was designed as it is. The
* specification will not require a specific factory at this time for
* application populated maps.There should be type restrictions on which
* types of nodes may be adapted by createNSResolver.No change.The
* namespace methods on the Node interface of the Level 3 core may be
* called without exception on all node types. In some cases no non-null
* namespace resolution will ever be returned. That is what may also be
* expected of this adapter.
* @param nodeResolver The node to be used as a context for namespace
* resolution.
* @return <code>XPathNSResolver</code> which resolves namespaces with
* respect to the definitions in scope for a specified node.
*/
public XPathNSResolver createNSResolver(Node nodeResolver);
/**
* Evaluates an XPath expression string and returns a result of the
* specified type if possible.An exception needs to be raised when an
* XPath expression is evaluated on a node such as an EntityReference
* which cannot serve as an XPath context node.Done: NOT_SUPPORTED_ERR.A
* description is needed of what happens when the node passed to the
* evaluation function is a Text or CDATASection in the DOM case where
* the text may be fragmented between text nodes.Done.Eliminate the
* evaluate method from XPathEvaluator, forcing everyone to create
* expressions.No change.Any implementor can easily implement it by
* creating an expression. Having it available as a separate routine is
* a convenience and may be an optimization as well in some cases.Revert
* to multiple evaluateAs methods instead of passing a type code.No
* change.This is an alternative which eliminates a method argument
* while adding methods, but the type code is used to designate the type
* on returns anyway and using it as an argument to specify any coercion
* seems natural to many.Error exceptions are needed when there is a
* mismatch between the implementation of XPathEvaluator and the context
* node being evaluated.Done: WRONG_DOCUMENT_ERRConcern that the XPath
* API should only support natural results of XPath expression, without
* convenience coercion or alternative representations. Any special
* thing such as ordering should be added later to resultNo change.We
* have significant use cases for returning alternative types and
* representations by explicit request in advance.Eliminate the reusable
* result argument.No change.No. We have use cases for it, and there is
* already an implementation showing there is nothing wrong with it.
* State that the XPathNSResolver argument may be a function in
* Javascript.Yes.There is an exception when there is a problem parsing
* the expression, but none when there is a problem evaluating the
* expression.No change.If the expression parsing was OK, then the worst
* that can happen is an empty result is returned.When requesting any
* type, the implementation should be permitted to return any type of
* node set, i.e. ordered or unordered, it finds convenient.No change.
* The iterator it returns may contain ordered results, but identifying
* it as such produces undesirable results, because it would create
* complexity for the user -- requiring checking two types to see if the
* result was a node set -- or incompatibility caused by assuming it was
* always the one returned by a particular implementation the developer
* was using.NAMESPACE_ERR description is not appropriate to the way it
* is being used here.Make the description of NAMESPACE_ERR in the core
* specification more general.Should the INVALID_EXPRESSION_ERR be
* INVALID_SYNTAX_ERR?No change.We can improve the description of the
* error, but the name is appropriate as-is. It covers not only syntax
* errors but expression errors, such as when the implementation has no
* custom functions or variables but the expression specifies custom
* functions or variables.
* @param expression The XPath expression string to be parsed and
* evaluated.
* @param contextNode The <code>context</code> is context node for the
* evaluation of this XPath expression. If the XPathEvaluator was
* obtained by casting the <code>Document</code> then this must be
* owned by the same document and must be a <code>Document</code>,
* <code>Element</code>, <code>Attribute</code>, <code>Text</code>,
* <code>CDATASection</code>, <code>Comment</code>,
* <code>ProcessingInstruction</code>, or <code>XPathNamespace</code>
* node. If the context node is a <code>Text</code> or a
* <code>CDATASection</code>, 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.
* @param resolver The <code>resolver</code> permits translation of
* prefixes within the XPath expression into appropriate namespace URIs
* . If this is specified as <code>null</code>, any namespace prefix
* within the expression will result in <code>DOMException</code>
* being thrown with the code <code>NAMESPACE_ERR</code>.
* @param type If a specific <code>type</code> is specified, then the
* result will be coerced to return the specified type relying on
* XPath type conversions and fail if the desired coercion is not
* possible. This must be one of the type codes of
* <code>XPathResult</code>.
* @param result The <code>result</code> specifies a specific
* <code>XPathResult</code> which may be reused and returned by this
* method. If this is specified as <code>null</code>or the
* implementation cannot reuse the specified result, a new
* <code>XPathResult</code> will be constructed and returned.
* @return The result of the evaluation of the XPath expression.
* @exception XPathException
* INVALID_EXPRESSION_ERR: Raised if the expression is not legal
* according to the rules of the <code>XPathEvaluator</code>i
* <br>TYPE_ERR: Raised if the result cannot be converted to return the
* specified type.
* @exception DOMException
* NAMESPACE_ERR: Raised if the expression contains namespace prefixes
* which cannot be resolved by the specified
* <code>XPathNSResolver</code>.
* <br>WRONG_DOCUMENT_ERR: The Node is from a document that is not
* supported by this XPathEvaluator.
* <br>NOT_SUPPORTED_ERR: The Node is not a type permitted as an XPath
* context node.
*/
public Object evaluate(String expression,
Node contextNode,
XPathNSResolver resolver,
short type,
Object result)
throws XPathException, DOMException;
}
1.1 xml-xerces/java/src/org/w3c/dom/xpath/XPathException.java
Index: XPathException.java
===================================================================
/*
* Copyright (c) 2002 World Wide Web Consortium,
* (Massachusetts Institute of Technology, Institut National de
* Recherche en Informatique et en Automatique, Keio University). All
* Rights Reserved. This program is distributed under the W3C's Software
* Intellectual Property License. This program is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY; without even
* the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE.
* See W3C License http://www.w3.org/Consortium/Legal/ for more details.
*/
package org.w3c.dom.xpath;
/**
* <meta name="usage" content="experimental"/>
* <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
* or obsoleted by other documents at any time.</strong> <p>
* A new exception has been created for exceptions specific to these XPath
* interfaces.
* <p>See also the <a href='http://www.w3.org/TR/2002/WD-DOM-Level-3-XPath-20020328'>Document Object Model (DOM) Level 3 XPath Specification</a>.
*/
public class XPathException extends RuntimeException {
public XPathException(short code, String message) {
super(message);
this.code = code;
}
public short code;
// XPathExceptionCode
/**
* If the expression has a syntax error or otherwise is not a legal
* expression according to the rules of the specific
* <code>XPathEvaluator</code>. If the <code>XPathEvaluator</code> was
* obtained by casting the document, the expression must be XPath 1.0
* with no special extension functions.A separate exception should be
* raised if there are problems resolving namespaces.Yes. These now
* raise DOMException with the code NAMESPACE_ERR.
*/
public static final short INVALID_EXPRESSION_ERR = 1;
/**
* If the expression cannot be converted to return the specified type.
*/
public static final short TYPE_ERR = 2;
}
1.1 xml-xerces/java/src/org/w3c/dom/xpath/XPathExpression.java
Index: XPathExpression.java
===================================================================
/*
* Copyright (c) 2002 World Wide Web Consortium,
* (Massachusetts Institute of Technology, Institut National de
* Recherche en Informatique et en Automatique, Keio University). All
* Rights Reserved. This program is distributed under the W3C's Software
* Intellectual Property License. This program is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY; without even
* the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE.
* See W3C License http://www.w3.org/Consortium/Legal/ for more details.
*/
package org.w3c.dom.xpath;
import org.w3c.dom.Node;
import org.w3c.dom.DOMException;
/**
* <meta name="usage" content="experimental"/>
* <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
* or obsoleted by other documents at any time.</strong> <p>
* The <code>XPathExpression</code> interface represents a parsed and resolved
* XPath expression.The evaluateExpression method should be moved to the
* XPathExpression interface so you do not have to use / pass two interfaces
* just to use it.Done.XPathExpression should have a public reference to the
* XPathEvaluator that created it.No change.Lacks justification.
* <p>See also the <a href='http://www.w3.org/TR/2002/WD-DOM-Level-3-XPath-20020328'>Document Object Model (DOM) Level 3 XPath Specification</a>.
*/
public interface XPathExpression {
/**
* Evaluates this XPath expression and returns a result.
* @param contextNode The <code>context</code> is context node for the
* evaluation of this XPath expression.If the XPathEvaluator was
* obtained by casting the <code>Document</code> then this must be
* owned by the same document and must be a <code>Document</code>,
* <code>Element</code>, <code>Attribute</code>, <code>Text</code>,
* <code>CDATASection</code>, <code>Comment</code>,
* <code>ProcessingInstruction</code>, or <code>XPathNamespace</code>
* node.If the context node is a <code>Text</code> or a
* <code>CDATASection</code>, 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.
* @param type If a specific <code>type</code> 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 <code>XPathResult</code>.
* @param result The <code>result</code> specifies a specific
* <code>XPathResult</code> which may be reused and returned by this
* method. If this is specified as <code>null</code>or the
* implementation cannot reuse the specified result, a new
* <code>XPathResult</code> will be constructed and returned.
* @return The result of the evaluation of the XPath expression.
* @exception XPathException
* TYPE_ERR: Raised if the result cannot be converted to return the
* specified type.
* @exception DOMException
* WRONG_DOCUMENT_ERR: The Node is from a document that is not supported
* by the XPathExpression that created this
* <code>XPathExpression</code>.
* <br>NOT_SUPPORTED_ERR: The Node is not a type permitted as an XPath
* context node.
*/
public Object evaluate(Node contextNode,
short type,
Object result)
throws XPathException, DOMException;
}
1.1 xml-xerces/java/src/org/w3c/dom/xpath/XPathNSResolver.java
Index: XPathNSResolver.java
===================================================================
/*
* Copyright (c) 2002 World Wide Web Consortium,
* (Massachusetts Institute of Technology, Institut National de
* Recherche en Informatique et en Automatique, Keio University). All
* Rights Reserved. This program is distributed under the W3C's Software
* Intellectual Property License. This program is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY; without even
* the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE.
* See W3C License http://www.w3.org/Consortium/Legal/ for more details.
*/
package org.w3c.dom.xpath;
/**
* <meta name="usage" content="experimental"/>
* <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
* or obsoleted by other documents at any time.</strong> <p>
* The <code>XPathNSResolver</code> interface permit <code>prefix</code>
* strings in the expression to be properly bound to
* <code>namespaceURI</code> strings. <code>XPathEvaluator</code> can
* construct an implementation of <code>XPathNSResolver</code> from a node,
* or the interface may be implemented by any application.
* <p>See also the <a href='http://www.w3.org/TR/2002/WD-DOM-Level-3-XPath-20020328'>Document Object Model (DOM) Level 3 XPath Specification</a>.
*/
public interface XPathNSResolver {
/**
* Look up the namespace URI associated to the given namespace prefix. The
* XPath evaluator must never call this with a <code>null</code> or
* empty argument, because the result of doing this is undefined.Null /
* empty prefix passed to XPathNSResolver should return default
* namespace.Do not permit <code>null</code>to be passed in invocation,
* allowing the implementation, if shared, to do anything it wants with
* a passed <code>null</code>.It would be confusing to specify more than
* this since the resolution of namespaces for XPath expressions never
* requires the default namespace.Null returns are problematic.No change.
* They should be adequately addressed in core. Some implementations
* have not properly supported them, but they will be fixed to be
* compliant. Bindings are still free to choose alternative
* representations of <code>null</code>where required.
* @param prefix The prefix to look for.
* @return Returns the associated namespace URI or <code>null</code> if
* none is found.
*/
public String lookupNamespaceURI(String prefix);
}
1.1 xml-xerces/java/src/org/w3c/dom/xpath/XPathNamespace.java
Index: XPathNamespace.java
===================================================================
/*
* Copyright (c) 2002 World Wide Web Consortium,
* (Massachusetts Institute of Technology, Institut National de
* Recherche en Informatique et en Automatique, Keio University). All
* Rights Reserved. This program is distributed under the W3C's Software
* Intellectual Property License. This program is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY; without even
* the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE.
* See W3C License http://www.w3.org/Consortium/Legal/ for more details.
*/
package org.w3c.dom.xpath;
import org.w3c.dom.Element;
import org.w3c.dom.Node;
/**
* <meta name="usage" content="experimental"/>
* <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
* or obsoleted by other documents at any time.</strong> <p>
* The <code>XPathNamespace</code> interface is returned by
* <code>XPathResult</code> 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
* <code>DOMException</code> with the code <code>HIERARCHY_REQUEST_ERR</code>
* . This node is read only, so methods or setting of attributes that would
* mutate the node result in a DOMException with the code
* <code>NO_MODIFICATION_ALLOWED_ERR</code>.
* <p>The core specification describes attributes of the <code>Node</code>
* interface that are different for different node node types but does not
* describe <code>XPATH_NAMESPACE_NODE</code>, so here is a description of
* those attributes for this node type. All attributes of <code>Node</code>
* not described in this section have a <code>null</code> or
* <code>false</code> value.
* <p><code>ownerDocument</code> matches the <code>ownerDocument</code> of the
* <code>ownerElement</code> even if the element is later adopted.
* <p><code>prefix</code> is the prefix of the namespace represented by the
* node.
* <p><code>nodeName</code> is the same as <code>prefix</code>.
* <p><code>nodeType</code> is equal to <code>XPATH_NAMESPACE_NODE</code>.
* <p><code>namespaceURI</code> is the namespace URI of the namespace
* represented by the node.
* <p><code>adoptNode</code>, <code>cloneNode</code>, and
* <code>importNode</code> fail on this node type by raising a
* <code>DOMException</code> with the code <code>NOT_SUPPORTED_ERR</code>.
* importNode should also fail on XPathNamespace nodes.This was already
* fixed in the public draft.The Namespace node should be added to DOM Level
* 3 core and should be available via a read-only NamedNodeMap on element to
* reduce the confusion of adding a special node type for XPath.No change.
* There are no known problems with this add-on node type and uses beyond
* XPath are not anticipated.<code>Node.namespaceValue</code> should be
* identical to Node.namespaceURI and not <code>null</code>.No change.It is
* not clear why it should be this way since the infoset does not dictate it.
* <p>See also the <a href='http://www.w3.org/TR/2002/WD-DOM-Level-3-XPath-20020328'>Document Object Model (DOM) Level 3 XPath Specification</a>.
*/
public interface XPathNamespace extends Node {
// XPathNodeType
/**
* The node is a <code>Namespace</code>.
*/
public static final short XPATH_NAMESPACE_NODE = 13;
/**
* The <code>Element</code> 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.
*/
public Element getOwnerElement();
}
1.1 xml-xerces/java/src/org/w3c/dom/xpath/XPathResult.java
Index: XPathResult.java
===================================================================
/*
* Copyright (c) 2002 World Wide Web Consortium,
* (Massachusetts Institute of Technology, Institut National de
* Recherche en Informatique et en Automatique, Keio University). All
* Rights Reserved. This program is distributed under the W3C's Software
* Intellectual Property License. This program is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY; without even
* the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE.
* See W3C License http://www.w3.org/Consortium/Legal/ for more details.
*/
package org.w3c.dom.xpath;
import org.w3c.dom.Node;
import org.w3c.dom.DOMException;
/**
* <meta name="usage" content="experimental"/>
* <strong>DOM Level 3 WD Experimental:
* The DOM Level 3 specification is at the stage
* of Working Draft, which represents work in
* progress and thus may be updated, replaced,
* or obsoleted by other documents at any time.</strong> <p>
* The <code>XPathResult</code> 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.Should there be a flag on the result to
* say whether an iteration has become invalid?Yes.Added the boolean
* attribute <code>invalidIteratorState</code>Should there be a reset method
* on the result in case someone wants to iterate the result multiple times?
* It may be more trouble than it is worth, because the user can request a
* new query. See if there are use cases.It might be better to consolidate
* the interfaces and just move the snapshot and iterator functions to the
* result object.Yes.The result of the consolidation looks good and unless
* there are great objections, this is how it will be.There is concern that
* the result cannot represent multiple strings, which is a possible result
* of XPath 2.0. on them?No change.This is not part of the XPath 1.0 data
* model. We cannot plan well for the XPath 2.0 data model at this point.
* Most likely a new API will be required for XPath 2.0
* <p>See also the <a href='http://www.w3.org/TR/2002/WD-DOM-Level-3-XPath-20020328'>Document Object Model (DOM) Level 3 XPath Specification</a>.
*/
public interface XPathResult {
// XPathResultType
/**
* 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.
* <br>If the natural result is a node set when <code>ANY_TYPE</code> was
* requested, then <code>UNORDERED_NODE_ITERATOR_TYPE</code> is always
* the resulting type. Any other representation of a node set must be
* explicitly requested.
*/
public static final short ANY_TYPE = 0;
/**
* The result is a number as defined by . Document modification does not
* invalidate the number, but may mean that reevaluation would not yield
* the same number.
*/
public static final short NUMBER_TYPE = 1;
/**
* The result is a string as defined by . Document modification does not
* invalidate the string, but may mean that the string no longer
* corresponds to the current document.
*/
public static final short STRING_TYPE = 2;
/**
* The result is a boolean as defined by . Document modification does not
* invalidate the boolean, but may mean that reevaluation would not
* yield the same boolean.
*/
public static final short BOOLEAN_TYPE = 3;
/**
* The result is a node set as defined by that will be accessed
* iteratively, which may not produce nodes in a particular order.
* Document modification invalidates the iteration.
* <br>This is the default type returned if the result is a node set and
* <code>ANY_TYPE</code> is requested.
*/
public static final short UNORDERED_NODE_ITERATOR_TYPE = 4;
/**
* The result is a node set as defined by that will be accessed
* iteratively, which will produce document-ordered nodes. Document
* modification invalidates the iteration.
*/
public static final short ORDERED_NODE_ITERATOR_TYPE = 5;
/**
* The result is a node set as defined by 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.
*/
public static final short UNORDERED_NODE_SNAPSHOT_TYPE = 6;
/**
* The result is a node set as defined by 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.
*/
public static final short ORDERED_NODE_SNAPSHOT_TYPE = 7;
/**
* The result is a node set as defined by and will be accessed as a
* single node, which may be <code>null</code>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 any node in the in the resulting set has been found.
* <br>If there are more than one node in the actual result, the single
* node returned may not be the first in document order.
*/
public static final short ANY_UNORDERED_NODE_TYPE = 8;
/**
* The result is a node set as defined by and will be accessed as a
* single node, which may be <code>null</code> 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.
* <br>If there are more than one node in the actual result, the single
* node returned will be the first in document order.
*/
public static final short FIRST_ORDERED_NODE_TYPE = 9;
/**
* A code representing the type of this result, as defined by the type
* constants.
*/
public short getResultType();
/**
* The value of this number result.
* @exception XPathException
* TYPE_ERR: raised if <code>resultType</code> is not
* <code>NUMBER_TYPE</code>.
*/
public double getNumberValue()
throws XPathException;
/**
* The value of this string result.
* @exception XPathException
* TYPE_ERR: raised if <code>resultType</code> is not
* <code>STRING_TYPE</code>.
*/
public String getStringValue()
throws XPathException;
/**
* The value of this boolean result.
* @exception XPathException
* TYPE_ERR: raised if <code>resultType</code> is not
* <code>BOOLEAN_TYPE</code>.
*/
public boolean getBooleanValue()
throws XPathException;
/**
* The value of this single node result, which may be <code>null</code>.
* @exception XPathException
* TYPE_ERR: raised if <code>resultType</code> is not
* <code>ANY_UNORDERED_NODE_TYPE</code> or
* <code>FIRST_ORDERED_NODE_TYPE</code>.
*/
public Node getSingleNodeValue()
throws XPathException;
/**
* Signifies that the iterator has become invalid. True if
* <code>resultType</code> is <code>UNORDERED_NODE_ITERATOR_TYPE</code>
* or <code>ORDERED_NODE_ITERATOR_TYPE</code> and the document has been
* modified since this result was returned.
*/
public boolean getInvalidIteratorState();
/**
* The number of nodes in the result snapshot. Valid values for
* snapshotItem indices are <code>0</code> to
* <code>snapshotLength-1</code> inclusive.
* @exception XPathException
* TYPE_ERR: raised if <code>resultType</code> is not
* <code>UNORDERED_NODE_SNAPSHOT_TYPE</code> or
* <code>ORDERED_NODE_SNAPSHOT_TYPE</code>.
*/
public int getSnapshotLength()
throws XPathException;
/**
* Iterates and returns the next node from the node set or
* <code>null</code>if there are no more nodes.
* @return Returns the next node.
* @exception XPathException
* TYPE_ERR: raised if <code>resultType</code> is not
* <code>UNORDERED_NODE_ITERATOR_TYPE</code> or
* <code>ORDERED_NODE_ITERATOR_TYPE</code>.
* @exception DOMException
* INVALID_STATE_ERR: The document has been mutated since the result was
* returned.
*/
public Node iterateNext()
throws XPathException, DOMException;
/**
* Returns the <code>index</code>th item in the snapshot collection. If
* <code>index</code> is greater than or equal to the number of nodes in
* the list, this method returns <code>null</code>. Unlike the iterator
* result, the snapshot does not become invalid, but may not correspond
* to the current document if it is mutated.
* @param index Index into the snapshot collection.
* @return The node at the <code>index</code>th position in the
* <code>NodeList</code>, or <code>null</code> if that is not a valid
* index.
* @exception XPathException
* TYPE_ERR: raised if <code>resultType</code> is not
* <code>UNORDERED_NODE_SNAPSHOT_TYPE</code> or
* <code>ORDERED_NODE_SNAPSHOT_TYPE</code>.
*/
public Node snapshotItem(int index)
throws XPathException;
}
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-cvs-help@xml.apache.org