Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DbXML version 1.2.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sleepycat.dbxml
Class XmlResults

    java.lang.Object
      com.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 `XmlValue`s, 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`

Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DbXML version 1.2.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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