001 /*
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
003 *
004 * This code is free software; you can redistribute it and/or modify it
005 * under the terms of the GNU General Public License version 2 only, as
006 * published by the Free Software Foundation. Sun designates this
007 * particular file as subject to the "Classpath" exception as provided
008 * by Sun in the LICENSE file that accompanied this code.
009 *
010 * This code is distributed in the hope that it will be useful, but WITHOUT
011 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
012 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
013 * version 2 for more details (a copy is included in the LICENSE file that
014 * accompanied this code).
015 *
016 * You should have received a copy of the GNU General Public License version
017 * 2 along with this work; if not, write to the Free Software Foundation,
018 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
019 *
020 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
021 * CA 95054 USA or visit www.sun.com if you need additional information or
022 * have any questions.
023 */
024
025 /*
026 * This file is available under and governed by the GNU General Public
027 * License version 2 only, as published by the Free Software Foundation.
028 * However, the following notice accompanied the original version of this
029 * file and, per its terms, should not be removed:
030 *
031 * Copyright (c) 2002 World Wide Web Consortium,
032 * (Massachusetts Institute of Technology, Institut National de
033 * Recherche en Informatique et en Automatique, Keio University). All
034 * Rights Reserved. This program is distributed under the W3C's Software
035 * Intellectual Property License. This program is distributed in the
036 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
037 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
038 * PURPOSE.
039 * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
040 */
041
042 package org.w3c.dom.xpath;
043
044 import org.w3c.dom.Node;
045 import org.w3c.dom.DOMException;
046
047 /**
048 * The <code>XPathResult</code> interface represents the result of the
049 * evaluation of an XPath 1.0 expression within the context of a particular
050 * node. Since evaluation of an XPath expression can result in various
051 * result types, this object makes it possible to discover and manipulate
052 * the type and value of the result.
053 * <p>See also the <a href='http://www.w3.org/2002/08/WD-DOM-Level-3-XPath-20020820'>Document Object Model (DOM) Level 3 XPath Specification</a>.
054 */
055 public interface XPathResult {
056 // XPathResultType
057 /**
058 * This code does not represent a specific type. An evaluation of an XPath
059 * expression will never produce this type. If this type is requested,
060 * then the evaluation returns whatever type naturally results from
061 * evaluation of the expression.
062 * <br>If the natural result is a node set when <code>ANY_TYPE</code> was
063 * requested, then <code>UNORDERED_NODE_ITERATOR_TYPE</code> is always
064 * the resulting type. Any other representation of a node set must be
065 * explicitly requested.
066 */
067 public static final short ANY_TYPE = 0;
068 /**
069 * The result is a number as defined by . Document modification does not
070 * invalidate the number, but may mean that reevaluation would not yield
071 * the same number.
072 */
073 public static final short NUMBER_TYPE = 1;
074 /**
075 * The result is a string as defined by . Document modification does not
076 * invalidate the string, but may mean that the string no longer
077 * corresponds to the current document.
078 */
079 public static final short STRING_TYPE = 2;
080 /**
081 * The result is a boolean as defined by . Document modification does not
082 * invalidate the boolean, but may mean that reevaluation would not
083 * yield the same boolean.
084 */
085 public static final short BOOLEAN_TYPE = 3;
086 /**
087 * The result is a node set as defined by that will be accessed
088 * iteratively, which may not produce nodes in a particular order.
089 * Document modification invalidates the iteration.
090 * <br>This is the default type returned if the result is a node set and
091 * <code>ANY_TYPE</code> is requested.
092 */
093 public static final short UNORDERED_NODE_ITERATOR_TYPE = 4;
094 /**
095 * The result is a node set as defined by that will be accessed
096 * iteratively, which will produce document-ordered nodes. Document
097 * modification invalidates the iteration.
098 */
099 public static final short ORDERED_NODE_ITERATOR_TYPE = 5;
100 /**
101 * The result is a node set as defined by that will be accessed as a
102 * snapshot list of nodes that may not be in a particular order.
103 * Document modification does not invalidate the snapshot but may mean
104 * that reevaluation would not yield the same snapshot and nodes in the
105 * snapshot may have been altered, moved, or removed from the document.
106 */
107 public static final short UNORDERED_NODE_SNAPSHOT_TYPE = 6;
108 /**
109 * The result is a node set as defined by that will be accessed as a
110 * snapshot list of nodes that will be in original document order.
111 * Document modification does not invalidate the snapshot but may mean
112 * that reevaluation would not yield the same snapshot and nodes in the
113 * snapshot may have been altered, moved, or removed from the document.
114 */
115 public static final short ORDERED_NODE_SNAPSHOT_TYPE = 7;
116 /**
117 * The result is a node set as defined by and will be accessed as a
118 * single node, which may be <code>null</code>if the node set is empty.
119 * Document modification does not invalidate the node, but may mean that
120 * the result node no longer corresponds to the current document. This
121 * is a convenience that permits optimization since the implementation
122 * can stop once any node in the in the resulting set has been found.
123 * <br>If there are more than one node in the actual result, the single
124 * node returned might not be the first in document order.
125 */
126 public static final short ANY_UNORDERED_NODE_TYPE = 8;
127 /**
128 * The result is a node set as defined by and will be accessed as a
129 * single node, which may be <code>null</code> if the node set is empty.
130 * Document modification does not invalidate the node, but may mean that
131 * the result node no longer corresponds to the current document. This
132 * is a convenience that permits optimization since the implementation
133 * can stop once the first node in document order of the resulting set
134 * has been found.
135 * <br>If there are more than one node in the actual result, the single
136 * node returned will be the first in document order.
137 */
138 public static final short FIRST_ORDERED_NODE_TYPE = 9;
139
140 /**
141 * A code representing the type of this result, as defined by the type
142 * constants.
143 */
144 public short getResultType();
145
146 /**
147 * The value of this number result. If the native double type of the DOM
148 * binding does not directly support the exact IEEE 754 result of the
149 * XPath expression, then it is up to the definition of the binding
150 * binding to specify how the XPath number is converted to the native
151 * binding number.
152 * @exception XPathException
153 * TYPE_ERR: raised if <code>resultType</code> is not
154 * <code>NUMBER_TYPE</code>.
155 */
156 public double getNumberValue() throws XPathException;
157
158 /**
159 * The value of this string result.
160 * @exception XPathException
161 * TYPE_ERR: raised if <code>resultType</code> is not
162 * <code>STRING_TYPE</code>.
163 */
164 public String getStringValue() throws XPathException;
165
166 /**
167 * The value of this boolean result.
168 * @exception XPathException
169 * TYPE_ERR: raised if <code>resultType</code> is not
170 * <code>BOOLEAN_TYPE</code>.
171 */
172 public boolean getBooleanValue() throws XPathException;
173
174 /**
175 * The value of this single node result, which may be <code>null</code>.
176 * @exception XPathException
177 * TYPE_ERR: raised if <code>resultType</code> is not
178 * <code>ANY_UNORDERED_NODE_TYPE</code> or
179 * <code>FIRST_ORDERED_NODE_TYPE</code>.
180 */
181 public Node getSingleNodeValue() throws XPathException;
182
183 /**
184 * Signifies that the iterator has become invalid. True if
185 * <code>resultType</code> is <code>UNORDERED_NODE_ITERATOR_TYPE</code>
186 * or <code>ORDERED_NODE_ITERATOR_TYPE</code> and the document has been
187 * modified since this result was returned.
188 */
189 public boolean getInvalidIteratorState();
190
191 /**
192 * The number of nodes in the result snapshot. Valid values for
193 * snapshotItem indices are <code>0</code> to
194 * <code>snapshotLength-1</code> inclusive.
195 * @exception XPathException
196 * TYPE_ERR: raised if <code>resultType</code> is not
197 * <code>UNORDERED_NODE_SNAPSHOT_TYPE</code> or
198 * <code>ORDERED_NODE_SNAPSHOT_TYPE</code>.
199 */
200 public int getSnapshotLength() throws XPathException;
201
202 /**
203 * Iterates and returns the next node from the node set or
204 * <code>null</code>if there are no more nodes.
205 * @return Returns the next node.
206 * @exception XPathException
207 * TYPE_ERR: raised if <code>resultType</code> is not
208 * <code>UNORDERED_NODE_ITERATOR_TYPE</code> or
209 * <code>ORDERED_NODE_ITERATOR_TYPE</code>.
210 * @exception DOMException
211 * INVALID_STATE_ERR: The document has been mutated since the result was
212 * returned.
213 */
214 public Node iterateNext() throws XPathException, DOMException;
215
216 /**
217 * Returns the <code>index</code>th item in the snapshot collection. If
218 * <code>index</code> is greater than or equal to the number of nodes in
219 * the list, this method returns <code>null</code>. Unlike the iterator
220 * result, the snapshot does not become invalid, but may not correspond
221 * to the current document if it is mutated.
222 * @param index Index into the snapshot collection.
223 * @return The node at the <code>index</code>th position in the
224 * <code>NodeList</code>, or <code>null</code> if that is not a valid
225 * index.
226 * @exception XPathException
227 * TYPE_ERR: raised if <code>resultType</code> is not
228 * <code>UNORDERED_NODE_SNAPSHOT_TYPE</code> or
229 * <code>ORDERED_NODE_SNAPSHOT_TYPE</code>.
230 */
231 public Node snapshotItem(int index) throws XPathException;
232
233 }
|