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. The result of a query is a collection of XmlValue objects, which may represent any one of the supported types, or documents.

An XmlResults object is normally created by executing a query. There are several ways that a query is performed. One is to call XmlManager.query(java.lang.String, com.sleepycat.dbxml.XmlQueryContext, com.sleepycat.dbxml.XmlDocumentConfig) directly. This mechanism is appropriate for one-shot queries that will not be repeated.

A second approach is to create an XmlQueryExpression using XmlManager.prepare(java.lang.String, com.sleepycat.dbxml.XmlQueryContext). You then execute the query expression using XmlQueryExpression.execute(com.sleepycat.dbxml.XmlQueryContext). This approach is appropriate for queries that will be performed more than once as it means that the expense of compiling the query can be amortized across multiple queries.

An empty XmlResults object can be created using XmlManager.createResults(). This object can then be assigned XmlValue objects, and used in further operations.

Note that when you perform a query, you must provide an XmlQueryContext object. Using this object, you can indicate whether you want the query to be performed eagerly or lazily. If eager evaluation is specified (the default), then the resultant values are stored within the XmlResults object. If lazy evaluation is selected, then the resultant values will be computed as needed. In this case the XmlResults object will maintain a reference to the affected containers (XmlContainer), query context XmlQueryContext), and expression (XmlQueryExpression).

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

A copy constructor is 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.

This object is not thread-safe, and can only be safely used by one thread at a time in an application.

Constructor Summary

XmlResults(XmlResults results)
Copy constructor.

Method Summary

void	add(XmlValue value) Adds the specified XmlValue to the end of the results set.
void	delete() Free the native resources associated with this object.
int	getEvaluationType() Gets the evaluation type of the XmlResults object.
boolean	hasNext() Returns true if there is another element in the results set.
boolean	hasPrevious() Returns true if there is a previous element in the results set.
void	isNull() Return true if this is an uninitialized object
XmlValue	next() Retrieves the next value in the result set.
boolean	next(XmlDocument document) Retrieves the next value in the result set as a document.
XmlValue	peek() Returns the current element in the results set without moving the internal iterator.
boolean	peek(XmlDocument document) Returns the current element in the results set as an XmlDocument without moving the internal iterator.
XmlValue	previous() Retrieves the previous value in the result set.
boolean	previous(XmlDocument document) Retrieves the next value in the result set as a document.
void	reset() A call to this method resets the result set iterator, so that a subsequent call to next() method will return the first value in the result set.
int	size() If a query was processed with eager evaluation, a call to this 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(XmlResults results)
           throws XmlException

Copy constructor.

Throws:

XmlException

Method Detail

delete

public void delete()

Free the native resources associated with this object.

isNull

public void isNull()
            throws XmlException

Return true if this is an uninitialized object

Throws:

XmlException

hasNext

public boolean hasNext()
                throws XmlException

Returns true if there is another element in the results set.

Throws:

XmlException

hasPrevious

public boolean hasPrevious()
                    throws XmlException

Returns true if there is a previous element in the results set.

Throws:

XmlException

next

public XmlValue next()
              throws XmlException

Retrieves the next value in the result set. When no more values remain in the result set, returns null.

Throws:

XmlException

previous

public XmlValue previous()
                  throws XmlException

Retrieves the previous value in the result set. When the first value in the results set has been reached, returns null

Throws:

XmlException

peek

public XmlValue peek()
              throws XmlException

Returns the current element in the results set without moving the internal iterator.

Throws:

XmlException

next

public boolean next(XmlDocument document)
             throws XmlException

Retrieves the next value in the result set as a document. When no more values remain in the result set, returns false.

Parameters:

document - An object that is to be filled with the next value

Throws:

XmlException

previous

public boolean previous(XmlDocument document)
                 throws XmlException

Retrieves the next value in the result set as a document. When the first value in the results set has been reached, returns false.

Parameters:

document - An object that is to be filled with the previous value

Throws:

XmlException

peek

public boolean peek(XmlDocument document)
             throws XmlException

Returns the current element in the results set as an XmlDocument without moving the internal iterator.

Throws:

XmlException

reset

public void reset()
           throws XmlException

A call to this method resets the result set iterator, so that a subsequent call to next() method will return the first value in the result set.

Throws:

XmlException

size

public int size()
         throws XmlException

If a query was processed with eager evaluation, a call to this method returns the number of values in the result set.

If the query was processed with lazy evaluation, a call to this method throws an exception.

Throws:

XmlException

add

public void add(XmlValue value)
         throws XmlException

Adds the specified XmlValue to the end of the results set. Note that if the XmlResults object was created as the result of a lazy evaluation, this method throws an exception. This method is used primarily for application resolution of collections in queries (see XmlResolver and XmlManager.createResults()).

Throws:

XmlException

getEvaluationType

public int getEvaluationType()
                      throws XmlException

Gets the evaluation type of the XmlResults object. It is either Eager (XmlQueryContext.Eager) or Lazy (XmlQueryContext.Lazy), depending on how it was created.

Throws:

XmlException