com.sleepycat.dbxml
Class XmlQueryContext

java.lang.Object
  com.sleepycat.dbxml.XmlQueryContext

public class XmlQueryContext

extends 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

static int	DeadValues A copy of the data stored in Berkeley DB XML is returned.
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

XmlQueryContext(XmlQueryContext o)
Copy constructor.

Method Summary

void	clearNamespaces() Remove all namespace mappings from the query context.
void	delete() Free the native resources associated with this object.
String	getBaseURI() Returns the base URI set for this XmlQueryContext object.
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.
String	getNamespace(String prefix) Returns the namespace URI for the specified prefix.
int	getReturnType() Retrieve the return type defined for this XmlQueryContext.
XmlValue	getVariableValue(String name) Returns the value that is bound to the specified variable.
XmlResults	getVariableValues(String name) Returns the XmlResults object representing the sequence of values that is bound to the specified variable.
void	removeNamespace(String prefix) Remove the namespace prefix to URI mapping for the specified prefix.
void	setBaseURI(String baseURI) Sets the base URI used for relative paths in query expressions.
void	setDefaultCollection(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(String prefix, String uri) Maps the specified URI to the specified namespace prefix.
void	setReturnType(int type) Set whether the query should return live or dead document values.
void	setVariableValue(String name, XmlResults value) Creates an externally-declared XQuery sequence variable by binding the specified XmlResults object to the specified variable name.
void	setVariableValue(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

DeadValues

public static final int DeadValues

A copy of the data stored in Berkeley DB XML is returned.

See Also:

Constant Field Values

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.

Method Detail

delete

public void delete()

Free the native resources associated with this object.

setNamespace

public void setNamespace(String prefix,
                         String uri)
                  throws XmlException

Maps the specified URI to the specified namespace prefix.

Parameters:

prefix - The namespace prefix.

uri - The namespace URI.

Throws:

XmlException

getNamespace

public String getNamespace(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(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

setDefaultCollection

public void setDefaultCollection(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 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(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 String getBaseURI()
                  throws XmlException

Returns the base URI set for this XmlQueryContext object.

Throws:

XmlException

setReturnType

public void setReturnType(int type)
                   throws XmlException

Set whether the query should return live or dead document values.

Parameters:

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

Throws:

XmlException

getReturnType

public int getReturnType()
                  throws XmlException

Retrieve the return type defined for this XmlQueryContext.

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

setVariableValue

public void setVariableValue(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(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(String name)
                          throws XmlException

Returns the value that is bound to the specified variable. If there is no value binding then the function returns false and 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(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 function returns false and value is set to the null value (XmlResults.isNull() returns true).

Parameters:

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

Throws:

XmlException