public class XmlResults
extends java.lang.Object
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 and Description |
---|
XmlResults(XmlResults results)
Copy constructor.
|
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.
|
public XmlResults(XmlResults results) throws XmlException
XmlException
public XmlEventWriter asEventWriter() throws XmlException
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.XmlException
public void delete()
public void isNull() throws XmlException
XmlException
public boolean hasNext() throws XmlException
XmlException
public boolean hasPrevious() throws XmlException
XmlException
public XmlValue next() throws XmlException
null
.XmlException
public XmlValue previous() throws XmlException
null
XmlException
public XmlValue peek() throws XmlException
XmlException
public boolean next(XmlDocument document) throws XmlException
false
.document
- An object that is to be filled with the next valueXmlException
public boolean previous(XmlDocument document) throws XmlException
false
.document
- An object that is to be filled with the previous valueXmlException
public boolean peek(XmlDocument document) throws XmlException
XmlException
public void reset() throws XmlException
next()
method will return the first value in the result set.XmlException
public int size() throws XmlException
If the query was processed with lazy evaluation, a call to this method throws an exception.
XmlException
public void add(XmlValue value) throws XmlException
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()
).XmlException
public int getEvaluationType() throws XmlException
XmlResults
object. It
is either Eager (XmlQueryContext.Eager
) or
Lazy (XmlQueryContext.Lazy
), depending on how it
was created.XmlException
public XmlResults copyResults() throws XmlException
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.
XmlException
public void concatResults(XmlResults from) throws XmlException
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()
.
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.XmlException
Copyright (c) 2004,2014 Oracle. All rights reserved.