com.sleepycat.dbxml

Class XmlQueryExpression

java.lang.Object

com.sleepycat.dbxml.XmlQueryExpression

public class XmlQueryExpression
extends java.lang.Object

An XmlQueryExpression represents a parsed XQuery expression. It is created by a call to XmlManager.prepare(java.lang.String, com.sleepycat.dbxml.XmlQueryContext). Parsed XQuery expressions are useful because they allow the cost of query parsing and optimization to be amortized over many evaluations. If indices of a container that may be referenced by a parsed XQuery expression are modified (e.g. add/drop an index) the XmlQueryExpression object should be regenerated by the application.

The 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.

There are two basic forms of the execute method: one that takes an XmlValue object, and another that does not. For methods that do not take an XmlValue, the XQuery must restrict the scope of the query using either the collection() or the doc() XQuery navigation functions, or an exception is thrown.

For those forms of the execute method that take an XmlValue, the query is applied against that object.

This object is free-threaded, and can be safely shared among threads, once created. Each thread should use an unshared XmlQueryContext object for calls to execute(com.sleepycat.dbxml.XmlQueryContext).

Constructor Summary

Constructors

Constructor and Description
XmlQueryExpression(XmlQueryExpression queryExpression) Copy constructor.

Method Summary

Modifier and Type	Method and Description
void	delete() Free the native resources associated with this object.
XmlResults	execute(XmlQueryContext queryContext) Evaluates the XQuery expression against the containers and documents identified by the query.
XmlResults	execute(XmlQueryContext queryContext, XmlDocumentConfig config) Evaluates the XQuery expression against the containers and documents identified by the query, with configuration.
XmlResults	execute(XmlTransaction txn, XmlQueryContext queryContext) Evaluates the XQuery expression against the containers and documents identified by the query, from within the scope of the provided XmlTransaction object.
XmlResults	execute(XmlTransaction txn, XmlQueryContext queryContext, XmlDocumentConfig config) Evaluates the XQuery expression against the containers and documents identified by the query, from within the scope of the provided XmlTransaction object, with configuration.
XmlResults	execute(XmlTransaction txn, XmlValue contextItem, XmlQueryContext queryContext) Evaluates the XQuery expression against the provided context item in the given query context, from within the scope of the provided XmlTransaction object.
XmlResults	execute(XmlTransaction txn, XmlValue contextItem, XmlQueryContext queryContext, XmlDocumentConfig config) Evaluates the XQuery expression against the provided context item, from within the scope of the provided XmlTransaction object.
XmlResults	execute(XmlValue contextItem, XmlQueryContext queryContext) Evaluates the XQuery expression against the provided context item in the given query context.
XmlResults	execute(XmlValue contextItem, XmlQueryContext queryContext, XmlDocumentConfig config) Evaluates the XQuery expression against the provided context item in the given query context with configuration.
java.lang.String	getQuery() Returns the query as a string.
java.lang.String	getQueryPlan() Returns the query plan as a string.
boolean	isUpdateExpression() Returns true if the query is an updating expression.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XmlQueryExpression

public XmlQueryExpression(XmlQueryExpression queryExpression)
                   throws XmlException

Copy constructor.

Throws:

XmlException

Method Detail

delete

public void delete()

Free the native resources associated with this object.

execute

public XmlResults execute(XmlQueryContext queryContext)
                   throws XmlException

Evaluates the XQuery expression against the containers and documents identified by the query.

Parameters:

queryContext - The XmlQueryContext to use for this evaluation.

Throws:

XmlException

execute

public XmlResults execute(XmlQueryContext queryContext,
                          XmlDocumentConfig config)
                   throws XmlException

Evaluates the XQuery expression against the containers and documents identified by the query, with configuration.

Parameters:

queryContext - The XmlQueryContext to use for this evaluation.

config - The configuration settings for the execution.

Throws:

XmlException

execute

public XmlResults execute(XmlTransaction txn,
                          XmlQueryContext queryContext)
                   throws XmlException

Evaluates the XQuery expression against the containers and documents identified by the query, from within the scope of the provided XmlTransaction object.

Parameters:

txn - If the operation is to be transaction-protected, the txn parameter is an XmlTransaction handle returned from XmlManager.createTransaction().

queryContext - The XmlQueryContext to use for this evaluation.

Throws:

XmlException

execute

public XmlResults execute(XmlTransaction txn,
                          XmlQueryContext queryContext,
                          XmlDocumentConfig config)
                   throws XmlException

Evaluates the XQuery expression against the containers and documents identified by the query, from within the scope of the provided XmlTransaction object, with configuration.

Parameters:

txn - If the operation is to be transaction-protected, the txn parameter is an XmlTransaction handle returned from XmlManager.createTransaction().

queryContext - The XmlQueryContext to use for this evaluation.

config - The configuration settings for the execution.

Throws:

XmlException

execute

public XmlResults execute(XmlValue contextItem,
                          XmlQueryContext queryContext)
                   throws XmlException

Evaluates the XQuery expression against the provided context item in the given query context.

Parameters:

contextItem - The XmlValue object to perform the query against.

queryContext - The XmlQueryContext to use for this evaluation.

Throws:

XmlException

execute

public XmlResults execute(XmlValue contextItem,
                          XmlQueryContext queryContext,
                          XmlDocumentConfig config)
                   throws XmlException

Evaluates the XQuery expression against the provided context item in the given query context with configuration.

Parameters:

contextItem - The XmlValue object to perform the query against.

queryContext - The XmlQueryContext to use for this evaluation.

config - The configuration settings for the execution.

Throws:

XmlException

execute

public XmlResults execute(XmlTransaction txn,
                          XmlValue contextItem,
                          XmlQueryContext queryContext)
                   throws XmlException

Evaluates the XQuery expression against the provided context item in the given query context, from within the scope of the provided XmlTransaction object.

Parameters:

txn - If the operation is to be transaction-protected, the txn parameter is an XmlTransaction handle returned from XmlManager.createTransaction().

contextItem - The XmlValue object to perform the query against.

queryContext - The XmlQueryContext to use for this evaluation.

Throws:

XmlException

execute

public XmlResults execute(XmlTransaction txn,
                          XmlValue contextItem,
                          XmlQueryContext queryContext,
                          XmlDocumentConfig config)
                   throws XmlException

Evaluates the XQuery expression against the provided context item, from within the scope of the provided XmlTransaction object.

Parameters:

txn - If the operation is to be transaction-protected, the txn parameter is an XmlTransaction handle returned from XmlManager.createTransaction().

contextItem - The XmlValue object to perform the query against.

queryContext - The XmlQueryContext to use for this evaluation.

config - The configuration settings for the execution.

Throws:

XmlException

getQuery

public java.lang.String getQuery()
                          throws XmlException

Returns the query as a string.

Throws:

XmlException

getQueryPlan

public java.lang.String getQueryPlan()
                              throws XmlException

Returns the query plan as a string.

Throws:

XmlException

isUpdateExpression

public boolean isUpdateExpression()
                           throws XmlException

Returns true if the query is an updating expression.

Throws:

XmlException