com.sleepycat.dbxml

Class XmlQueryContext

java.lang.Object

com.sleepycat.dbxml.XmlQueryContext

public class XmlQueryContext
extends java.lang.Object

The XmlQueryContext class encapsulates the context within which a query is performed against an XmlContainer. The context includes namespace mappings, variable bindings, and flags that indicate how the query result set should be determined and returned to the caller. Multiple queries can be executed within the same XmlQueryContext; however, XmlQueryContext is not thread-safe, and can only be used by one thread at a time.

XmlQueryContext objects are created using XmlManager.createQueryContext(int, int).

XmlQueryContext allows you to define whether queries executed within the context are to be evaluated lazily or eagerly, and whether the query is to return live or dead values. For detailed descriptions of these parameters see setReturnType(int) and setEvaluationType(int). Note that these values are also set when you create a query context using XmlManager.createQueryContext(int, int).

The XQuery syntax permits expressions to refer to, as well as define namespace prefixes. The XmlQueryContext class provides namespace management methods so that the caller may manage the namespace prefix to URI mapping. By default the prefix "dbxml" is defined to be "http://www.sleepycat.com/2002/dbxml".

The XQuery syntax also permits expressions to refer to externally defined variables. The XmlQueryContext class provides methods that allow the caller to manage the externally-declared variable to value bindings.

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.

Field Summary

Fields

Modifier and Type	Field and Description
static int	Eager The query is executed and its resultant values are derived and stored in-memory before evaluation of the query is completed.
static int	Lazy Minimal processing is performed before evaluation of the query is completed, and the remaining processing is deferred until the result set is enumerated.
static int	LiveValues A reference to the data stored in Berkeley DB XML is returned.

Constructor Summary

Constructors

Constructor and Description
XmlQueryContext(XmlQueryContext o) Copy constructor.

Method Summary

Modifier and Type	Method and Description
void	clearNamespaces() Remove all namespace mappings from the query context.
java.lang.String	getBaseURI() Returns the base URI set for this XmlQueryContext object.
XmlDebugListener	getDebugListener() Gets the XmlDebugListener associated with this query context.
java.lang.String	getDefaultCollection() Returns the default collection for use in fn:collection() with no arguments in an XQuery expression.
int	getEvaluationType() Returns the evaluation type defined for this XmlQueryContext.
java.lang.String	getNamespace(java.lang.String prefix) Returns the namespace URI for the specified prefix.
int	getQueryTimeoutSeconds() Returns the query timeout value set in setQueryTimeoutSeconds(int).
int	getReturnType() Retrieve the return type defined for this XmlQueryContext.
XmlValue	getVariableValue(java.lang.String name) Returns the value that is bound to the specified variable.
XmlResults	getVariableValues(java.lang.String name) Returns the XmlResults object representing the sequence of values that is bound to the specified variable.
void	interruptQuery() Interrupt the in-progress query using this XmlQueryContext.
void	removeNamespace(java.lang.String prefix) Remove the namespace prefix to URI mapping for the specified prefix.
void	setBaseURI(java.lang.String baseURI) Sets the base URI used for relative paths in query expressions.
void	setDebugListener(XmlDebugListener listener) Associates an XmlDebugListener instance with the query context in order to debug queries.
void	setDefaultCollection(java.lang.String uri) Sets the default collection for use in fn:collection() with no arguments in an XQuery expression.
void	setEvaluationType(int type) Allows the application to set the query evaluation type to "eager" or "lazy".
void	setNamespace(java.lang.String prefix, java.lang.String uri) Maps the specified URI to the specified namespace prefix.
void	setQueryTimeoutSeconds(int seconds) Sets the query timeout value for queries using this XmlQueryContext.
void	setReturnType(int type) Sets the return type of the query.
void	setVariableValue(java.lang.String name, XmlResults value) Creates an externally-declared XQuery sequence variable by binding the specified XmlResults object to the specified variable name.
void	setVariableValue(java.lang.String name, XmlValue value) Creates an externally-declared XQuery variable by binding the specified value to the specified variable name.

Methods inherited from class java.lang.Object

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

Field Detail

LiveValues

public static final int LiveValues

A reference to the data stored in Berkeley DB XML is returned.

See Also:

Constant Field Values

Eager

public static final int Eager

The query is executed and its resultant values are derived and stored in-memory before evaluation of the query is completed.

See Also:

Constant Field Values

Lazy

public static final int Lazy

Minimal processing is performed before evaluation of the query is completed, and the remaining processing is deferred until the result set is enumerated.

See Also:

Constant Field Values

Constructor Detail

XmlQueryContext

public XmlQueryContext(XmlQueryContext o)
                throws XmlException

Copy constructor.

Throws:

XmlException

Method Detail

setNamespace

public void setNamespace(java.lang.String prefix,
                         java.lang.String uri)
                  throws XmlException

Maps the specified URI to the specified namespace prefix.

Parameters:

prefix - The namespace prefix. If prefix is null, the uri will be treated as the default element namespace.

uri - The namespace URI.

Throws:

XmlException

getNamespace

public java.lang.String getNamespace(java.lang.String prefix)
                              throws XmlException

Returns the namespace URI for the specified prefix. An empty string is returned if no URI is defined for the prefix.

Parameters:

prefix - The namespace prefix whose URI mapping is required.

Throws:

XmlException

removeNamespace

public void removeNamespace(java.lang.String prefix)
                     throws XmlException

Remove the namespace prefix to URI mapping for the specified prefix. A call to this method with a prefix that has no existing mapping is ignored.

Parameters:

prefix - The namespace prefix to be removed.

Throws:

XmlException

clearNamespaces

public void clearNamespaces()
                     throws XmlException

Remove all namespace mappings from the query context.

Throws:

XmlException

getDebugListener

public XmlDebugListener getDebugListener()
                                  throws XmlException

Gets the XmlDebugListener associated with this query context.

Returns:

The XmlDebugListener associated with this query context, or null if there is none.

Throws:

XmlException

setDebugListener

public void setDebugListener(XmlDebugListener listener)
                      throws XmlException

Associates an XmlDebugListener instance with the query context in order to debug queries. In order to prepare a query that contains debugging information an XmlDebugListener must be set on the XmlQueryContext used when the query is prepared. A different XmlDebugListener object (or none) can be set for the query evaluation.

Parameters:

listener - The XmlDebugListener to be used.

Throws:

XmlException

setDefaultCollection

public void setDefaultCollection(java.lang.String uri)
                          throws XmlException

Sets the default collection for use in fn:collection() with no arguments in an XQuery expression.

Parameters:

uri - The URI representing the container.

Throws:

XmlException

getDefaultCollection

public java.lang.String getDefaultCollection()
                                      throws XmlException

Returns the default collection for use in fn:collection() with no arguments in an XQuery expression.

Throws:

XmlException

setBaseURI

public void setBaseURI(java.lang.String baseURI)
                throws XmlException

Sets the base URI used for relative paths in query expressions. For example, a base URI of 'file:///export/expression', and a relative path of '../another/expression', resolves to 'file:///export/another/expression'.

Parameters:

baseURI - The base URI, as a string.

Throws:

XmlException

getBaseURI

public java.lang.String getBaseURI()
                            throws XmlException

Returns the base URI set for this XmlQueryContext object.

Throws:

XmlException

setReturnType

public void setReturnType(int type)
                   throws XmlException

Sets the return type of the query.

Parameters:

type - The type parameter specifies which of documents or values to return, and must be set to LiveValues.

Throws:

XmlException

getReturnType

public int getReturnType()
                  throws XmlException

Retrieve the return type defined for this XmlQueryContext. Always returns LiveValues.

Throws:

XmlException

setEvaluationType

public void setEvaluationType(int type)
                       throws XmlException

Allows the application to set the query evaluation type to "eager" or "lazy". Eager evaluation means that the whole query is executed and its resultant values derived and stored in-memory before evaluation of the query is completed. Lazy evaluation means that minimal processing is performed before the query is completed, and the remaining processing is deferred until the result set is enumerated. As each call to XmlResults.next() is called the next resultant value is determined.

Parameters:

type - The evaluation type must be specified as either: Eager or Lazy.

Throws:

XmlException

getEvaluationType

public int getEvaluationType()
                      throws XmlException

Returns the evaluation type defined for this XmlQueryContext.

Throws:

XmlException

getQueryTimeoutSeconds

public int getQueryTimeoutSeconds()
                           throws XmlException

Returns the query timeout value set in setQueryTimeoutSeconds(int).

Throws:

XmlException

setQueryTimeoutSeconds

public void setQueryTimeoutSeconds(int seconds)
                            throws XmlException

Sets the query timeout value for queries using this XmlQueryContext.

Throws:

XmlException

interruptQuery

public void interruptQuery()
                    throws XmlException

Interrupt the in-progress query using this XmlQueryContext.

Throws:

XmlException

setVariableValue

public void setVariableValue(java.lang.String name,
                             XmlValue value)
                      throws XmlException

Creates an externally-declared XQuery variable by binding the specified value to the specified variable name.

This method may be called at any time during the life of the application.

Parameters:

name - The name of the variable to bind. Within the XQuery query, the variable can be referenced using the normal $name syntax.

value - The value to bind to the named variable.

Throws:

XmlException

setVariableValue

public void setVariableValue(java.lang.String name,
                             XmlResults value)
                      throws XmlException

Creates an externally-declared XQuery sequence variable by binding the specified XmlResults object to the specified variable name.

This method allows a sequence of values to be bound to an XQuery variable.

Parameters:

name - The name of the variable to bind. Within the XQuery query, the variable can be referenced using the normal $name syntax.

value - The set of values to bind to the named variable.

Throws:

XmlException

getVariableValue

public XmlValue getVariableValue(java.lang.String name)
                          throws XmlException

Returns the value that is bound to the specified variable. If there is no value binding then the value is set to the null value (XmlValue.isNull() returns true).

Parameters:

name - The name of the variable whose value is required.

Throws:

XmlException

getVariableValues

public XmlResults getVariableValues(java.lang.String name)
                             throws XmlException

Returns the XmlResults object representing the sequence of values that is bound to the specified variable. If there is no value binding then the value is set to the null value (XmlResults.isNull() returns true).

Parameters:

name - The name of the variable whose value is required.

Throws:

XmlException