com.sleepycat.dbxml

Class XmlResults

java.lang.Object

com.sleepycat.dbxml.XmlResults

public class XmlResults
extends java.lang.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() 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.

In an eager result set the iterator logically points "between" values which means that alternating between calls to next() and previous() will return the same value.

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

Constructors

Constructor and Description
XmlResults(XmlResults results) Copy constructor.

Method Summary

Modifier and Type	Method and Description
void	add(XmlValue value) Adds the specified XmlValue to the end of the results set.
XmlEventWriter	asEventWriter() Returns an instance of XmlEventWriter that can be used to write events to construct content in the XmlResults object.
void	concatResults(XmlResults from) Concatenates the XmlValue objects from one XmlResults instance into another.
XmlResults	copyResults() Returns a copy of the XmlResults object.
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

asEventWriter

public XmlEventWriter asEventWriter()
                             throws XmlException

Returns an instance of XmlEventWriter that can be used to write events to construct content in the XmlResults object. Multiple nodes and/or atomic values can be written. The XmlResults object can then be bound to a variable using XmlQueryContext.setVariableValue(String,XmlResults) and used in queries. The XmlResults instance must be newly constructed from XmlManager.createResults() and empty or an exception is thrown. Please note that only one active XmlEventWriter is allowed for an XmlResults object.

Throws:

XmlException

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

copyResults

public XmlResults copyResults()
                       throws XmlException

Returns a copy of the XmlResults object. The copy is a new, eager object that includes transient copies of all XmlValue objects from the current object. The copies no longer reference database objects. This means that they can be used outside of transactions, but also means that operations on the new object will not affect containers. This interface copies a single XmlResults object. Multiple objects can be concatenated into a single XmlResults using concatResults(com.sleepycat.dbxml.XmlResults). Resources associated with the returned object must eventually be released by calling delete().

If the current XmlResults is eagerly evaluated it is reset before and after use by calling reset(). Lazily evaluated results sets are not reset and are iterated.

Throws:

XmlException

concatResults

public void concatResults(XmlResults from)
                   throws XmlException

Concatenates the XmlValue objects from one XmlResults instance into another.

The current result set must be eagerly evaluated and may be empty or not. Copied values are appended to the set and no longer reference database objects. This means that they can be used outside of transactions, but also means that operations on the new object will not affect containers. Existing XmlValue objects in the instance are not modified. Resources associated with the XmlResults instance must eventually be released by calling delete().

Parameters:

from - The object from which values are copied. If it is eagerly evaluated it is reset before and after use by calling reset(). Lazily evaluated results sets are not reset and are iterated.

Throws:

XmlException