Berkeley DbXML
version 1.2.1

com.sleepycat.dbxml
Class XmlResults

java.lang.Object
  extended bycom.sleepycat.dbxml.XmlResults

public class XmlResults
extends Object

The XmlResults class encapsulates the results of a query that has been executed against an XmlContainer. The result of a query is a collection of XmlValues, which may be either strings, numbers, booleans, node lists, or documents. If the query context specified a return type of xmlquerycontext_resultvalues, the result values will be of type XmlValue.STRING, XmlValue.NUMBER, XmlValue.BOOLEAN, or XmlValue.NODE, otherwise they will be of type XmlValue.DOCUMENT.

An XmlResults object is created by calling the XmlContainer.queryWithXPath method. If the query context specified eager evaluation, then the resultant values are stored within the XmlResults object. If lazy expression was selected, then the resultant values will be computed as needed. In this case the XmlResults object will maintain a reference to the container (XmlContainer), query context (XmlQueryContext), and expression (XmlQueryExpression).

The XmlResults class provides an iteration interface through the XmlResults.next method. XmlResults.next method returns false and the null value when no more results are available (XmlValue.isNull method returns true). If eager evaluation was selected then XmlResults.reset method can be called to reset the iterator, and the subsequent call to the XmlResults.next method will return the first value of the result set.

The copy constructor and assignment operator are provided for this class. The class is implemented using a handle-body idiom. When a handle is copied both handles maintain a reference to the same body.


Constructor Summary
XmlResults(XmlQueryContext context, DbTxn txn)
           
 
Method Summary
 void add(XmlValue value)
           
 void delete()
           
 XmlValue next()
          The XmlResults.next method retrieves the next value in the result set.
 XmlValue next(DbTxn txn)
           
 boolean next(XmlDocument document)
           
 boolean next(XmlDocument document, XmlValue value)
           
 boolean nextDocument(DbTxn txn, XmlDocument document)
           
 boolean nextDocumentAndValue(DbTxn txn, XmlDocument document, XmlValue value)
           
 void reset()
          If a query was processed with eager evaluation, a call to the XmlResults.reset method resets the result set iterator, so that a subsequent call to XmlResults.next method will return the first value in the result set.
 int size()
          If a query was processed with eager evaluation, a call to the XmlResults.size method returns the number of values in the result set.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XmlResults

public XmlResults(XmlQueryContext context,
                  DbTxn txn)
           throws XmlException
Method Detail

delete

public void delete()

next

public XmlValue next()
              throws XmlException
The XmlResults.next method retrieves the next value in the result set. When no more values remain in the result set, the XmlResults.next method returns false.

Three implementations of the XmlResults.next method are provided. Their usage depends upon the settings of the XmlQueryContext passed through the XmlContainer.queryWithXPath method. If the context return type was set to ResultValues then next(value) should be used. If the return type was set to ResultDocuments then next(document) can be used as a convenience. If ResultDocumentsAndValues was set then next(document,value) should be used.

If a query was processed with eager evaluation, a call to the XmlResults.reset method resets the result set iterator, so that a subsequent call to XmlResults.next returns the first value in the result set.

Returns:
The XmlResults.next method retrieves the next value in the result set. When no more values remain in the result set, the XmlResults.next method returns false.

Throws:
XmlException - The XmlResults.next method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • A lazily evaluated XmlResults found that the underlying container was closed.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.
  • The document could not be returned as a DOM.

  • next

    public boolean next(XmlDocument document)
                 throws XmlException
    Parameters:
    document - The XmlDocument into which the next document in the result set is to be placed.
    Returns:
    Returns the next document in the result set.

    Throws:
    XmlException - The XmlResults.next method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • A lazily evaluated XmlResults found that the underlying container was closed.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.
  • The document could not be returned as a DOM.

  • next

    public boolean next(XmlDocument document,
                        XmlValue value)
                 throws XmlException
    Parameters:
    value - The XmlValue into which the next value in the result set is to be placed.
    document - The XmlDocument into which the next document in the result set is to be placed.
    Returns:
    Returns the next document and value in the result set.

    Throws:
    XmlException - The XmlResults.next method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • A lazily evaluated XmlResults found that the underlying container was closed.
  • An error occurred in an underlying Berkeley DB database. The XmlException.getDbError method will return the error code for the error.
  • The document could not be returned as a DOM.

  • next

    public XmlValue next(DbTxn txn)
                  throws XmlException
    Throws:
    XmlException

    nextDocument

    public boolean nextDocument(DbTxn txn,
                                XmlDocument document)
                         throws XmlException
    Throws:
    XmlException

    nextDocumentAndValue

    public boolean nextDocumentAndValue(DbTxn txn,
                                        XmlDocument document,
                                        XmlValue value)
                                 throws XmlException
    Throws:
    XmlException

    reset

    public void reset()
               throws XmlException
    If a query was processed with eager evaluation, a call to the XmlResults.reset method resets the result set iterator, so that a subsequent call to XmlResults.next method will return the first value in the result set. If the query was processed with lazy evaluation then a call to XmlResults.reset method throws an exception.

    Throws:
    XmlException - The XmlResults.reset method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The method can only be called on eagerly evaluated result sets.

  • size

    public int size()
    If a query was processed with eager evaluation, a call to the XmlResults.size method returns the number of values in the result set. If the query was processed with lazy evaluation, a call to XmlResults.size throws an exception.

    Returns:
    Returns the number of values in the result set.
    Throws:
    XmlException - The XmlResults.size method may fail and throw XmlException, encapsulating one of the following non-zero errors:
  • The method can only be called on eagerly evaluated result sets.

  • add

    public void add(XmlValue value)
             throws XmlException
    Throws:
    XmlException

    Berkeley DbXML
    version 1.2.1

    Copyright (c) 1996-2003 Sleepycat Software, Inc. - All rights reserved.