Source for org.w3c.dom.xpath.XPathResult

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