XPathResult


1   /*
2    * Copyright (c) 2002 World Wide Web Consortium,
3    * (Massachusetts Institute of Technology, Institut National de
4    * Recherche en Informatique et en Automatique, Keio University). All
5    * Rights Reserved. This program is distributed under the W3C's Software
6    * Intellectual Property License. This program is distributed in the
7    * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
8    * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
9    * PURPOSE.
10   * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
11   */
12  
13  package org.w3c.dom.xpath;
14  
15  
16  import org.w3c.dom.Node  ;
17  import org.w3c.dom.DOMException  ;
18  
19  /**
20   * The <code>XPathResult</code> interface represents the result of the 
21   * evaluation of an XPath 1.0 expression within the context of a particular 
22   * node. Since evaluation of an XPath expression can result in various 
23   * result types, this object makes it possible to discover and manipulate 
24   * the type and value of the result.
25   * <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>.
26   */
27  public interface XPathResult {
28      // XPathResultType
29      /**
30       * This code does not represent a specific type. An evaluation of an XPath 
31       * expression will never produce this type. If this type is requested, 
32       * then the evaluation returns whatever type naturally results from 
33       * evaluation of the expression. 
34       * <br>If the natural result is a node set when <code>ANY_TYPE</code> was 
35       * requested, then <code>UNORDERED_NODE_ITERATOR_TYPE</code> is always 
36       * the resulting type. Any other representation of a node set must be 
37       * explicitly requested.
38       */
39      public static final short ANY_TYPE                  = 0;
40      /**
41       * The result is a number as defined by . Document modification does not 
42       * invalidate the number, but may mean that reevaluation would not yield 
43       * the same number.
44       */
45      public static final short NUMBER_TYPE               = 1;
46      /**
47       * The result is a string as defined by . Document modification does not 
48       * invalidate the string, but may mean that the string no longer 
49       * corresponds to the current document.
50       */
51      public static final short STRING_TYPE               = 2;
52      /**
53       * The result is a boolean as defined by . Document modification does not 
54       * invalidate the boolean, but may mean that reevaluation would not 
55       * yield the same boolean.
56       */
57      public static final short BOOLEAN_TYPE              = 3;
58      /**
59       * The result is a node set as defined by  that will be accessed 
60       * iteratively, which may not produce nodes in a particular order. 
61       * Document modification invalidates the iteration.
62       * <br>This is the default type returned if the result is a node set and 
63       * <code>ANY_TYPE</code> is requested.
64       */
65      public static final short UNORDERED_NODE_ITERATOR_TYPE = 4;
66      /**
67       * The result is a node set as defined by  that will be accessed 
68       * iteratively, which will produce document-ordered nodes. Document 
69       * modification invalidates the iteration.
70       */
71      public static final short ORDERED_NODE_ITERATOR_TYPE = 5;
72      /**
73       * The result is a node set as defined by  that will be accessed as a 
74       * snapshot list of nodes that may not be in a particular order. 
75       * Document modification does not invalidate the snapshot but may mean 
76       * that reevaluation would not yield the same snapshot and nodes in the 
77       * snapshot may have been altered, moved, or removed from the document.
78       */
79      public static final short UNORDERED_NODE_SNAPSHOT_TYPE = 6;
80      /**
81       * The result is a node set as defined by  that will be accessed as a 
82       * snapshot list of nodes that will be in original document order. 
83       * Document modification does not invalidate the snapshot but may mean 
84       * that reevaluation would not yield the same snapshot and nodes in the 
85       * snapshot may have been altered, moved, or removed from the document.
86       */
87      public static final short ORDERED_NODE_SNAPSHOT_TYPE = 7;
88      /**
89       * The result is a node set as defined by  and will be accessed as a 
90       * single node, which may be <code>null</code>if the node set is empty. 
91       * Document modification does not invalidate the node, but may mean that 
92       * the result node no longer corresponds to the current document. This 
93       * is a convenience that permits optimization since the implementation 
94       * can stop once any node in the in the resulting set has been found.
95       * <br>If there are more than one node in the actual result, the single 
96       * node returned might not be the first in document order.
97       */
98      public static final short ANY_UNORDERED_NODE_TYPE   = 8;
99      /**
100      * The result is a node set as defined by  and will be accessed as a 
101      * single node, which may be <code>null</code> if the node set is empty. 
102      * Document modification does not invalidate the node, but may mean that 
103      * the result node no longer corresponds to the current document. This 
104      * is a convenience that permits optimization since the implementation 
105      * can stop once the first node in document order of the resulting set 
106      * has been found.
107      * <br>If there are more than one node in the actual result, the single 
108      * node returned will be the first in document order.
109      */
110     public static final short FIRST_ORDERED_NODE_TYPE   = 9;
111 
112     /**
113      * A code representing the type of this result, as defined by the type 
114      * constants.
115      */
116     public short getResultType();
117 
118     /**
119      * The value of this number result. If the native double type of the DOM 
120      * binding does not directly support the exact IEEE 754 result of the 
121      * XPath expression, then it is up to the definition of the binding 
122      * binding to specify how the XPath number is converted to the native 
123      * binding number.
124      * @exception XPathException
125      *   TYPE_ERR: raised if <code>resultType</code> is not 
126      *   <code>NUMBER_TYPE</code>.
127      */
128     public double getNumberValue()
129                              throws XPathException;
130 
131     /**
132      * The value of this string result.
133      * @exception XPathException
134      *   TYPE_ERR: raised if <code>resultType</code> is not 
135      *   <code>STRING_TYPE</code>.
136      */
137     public String   getStringValue()
138                              throws XPathException;
139 
140     /**
141      * The value of this boolean result.
142      * @exception XPathException
143      *   TYPE_ERR: raised if <code>resultType</code> is not 
144      *   <code>BOOLEAN_TYPE</code>.
145      */
146     public boolean getBooleanValue()
147                              throws XPathException;
148 
149     /**
150      * The value of this single node result, which may be <code>null</code>.
151      * @exception XPathException
152      *   TYPE_ERR: raised if <code>resultType</code> is not 
153      *   <code>ANY_UNORDERED_NODE_TYPE</code> or 
154      *   <code>FIRST_ORDERED_NODE_TYPE</code>.
155      */
156     public Node   getSingleNodeValue()
157                              throws XPathException;
158 
159     /**
160      * Signifies that the iterator has become invalid. True if 
161      * <code>resultType</code> is <code>UNORDERED_NODE_ITERATOR_TYPE</code> 
162      * or <code>ORDERED_NODE_ITERATOR_TYPE</code> and the document has been 
163      * modified since this result was returned.
164      */
165     public boolean getInvalidIteratorState();
166 
167     /**
168      * The number of nodes in the result snapshot. Valid values for 
169      * snapshotItem indices are <code>0</code> to 
170      * <code>snapshotLength-1</code> inclusive.
171      * @exception XPathException
172      *   TYPE_ERR: raised if <code>resultType</code> is not 
173      *   <code>UNORDERED_NODE_SNAPSHOT_TYPE</code> or 
174      *   <code>ORDERED_NODE_SNAPSHOT_TYPE</code>.
175      */
176     public int getSnapshotLength()
177                              throws XPathException;
178 
179     /**
180      * Iterates and returns the next node from the node set or 
181      * <code>null</code>if there are no more nodes.
182      * @return Returns the next node.
183      * @exception XPathException
184      *   TYPE_ERR: raised if <code>resultType</code> is not 
185      *   <code>UNORDERED_NODE_ITERATOR_TYPE</code> or 
186      *   <code>ORDERED_NODE_ITERATOR_TYPE</code>.
187      * @exception DOMException
188      *   INVALID_STATE_ERR: The document has been mutated since the result was 
189      *   returned.
190      */
191     public Node   iterateNext()
192                             throws XPathException, DOMException  ;
193 
194     /**
195      * Returns the <code>index</code>th item in the snapshot collection. If 
196      * <code>index</code> is greater than or equal to the number of nodes in 
197      * the list, this method returns <code>null</code>. Unlike the iterator 
198      * result, the snapshot does not become invalid, but may not correspond 
199      * to the current document if it is mutated.
200      * @param index Index into the snapshot collection.
201      * @return The node at the <code>index</code>th position in the 
202      *   <code>NodeList</code>, or <code>null</code> if that is not a valid 
203      *   index.
204      * @exception XPathException
205      *   TYPE_ERR: raised if <code>resultType</code> is not 
206      *   <code>UNORDERED_NODE_SNAPSHOT_TYPE</code> or 
207      *   <code>ORDERED_NODE_SNAPSHOT_TYPE</code>.
208      */
209     public Node   snapshotItem(int index)
210                              throws XPathException;
211 
212 }
213
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags