Berkeley DbXML
version 1.2.1

com.sleepycat.dbxml
Class XmlQueryContext

java.lang.Object
  extended bycom.sleepycat.dbxml.XmlQueryContext

public class XmlQueryContext
extends Object


Field Summary
static int CandidateDocuments
          Return documents that may match the query expression.
static int Eager
          The query is executed and its resultant values are derived and stored in-memory before a call to XmlContainer.queryWithXPath returns.
static int Lazy
          Minimal processing is performed before XmlContainer.queryWithXPath returns, and the remaining processing is deferred until the result set is enumerated.
static int ResultDocuments
          Return documents that match the XPath expression.
static int ResultDocumentsAndValues
          Return both the nodes from the documents that match the query expression, and the matching documents.
static int ResultValues
          Return nodes from the documents that match the XPath expression.
 
Constructor Summary
XmlQueryContext(int returnType, int evaluationType)
          The XmlQueryContext class encapsulates the context within which a query is performed against an XmlContainer.
 
Method Summary
 void clearNamespaces()
          The XmlQueryContext.clearNamespaces method removes all current namespace prefix to URI mappings from the query context.
 void delete()
           
 int getEvaluationType()
          Discover the evaluation type defined for this XmlQueryContext.
 String getNamespace(String prefix)
          The XmlQueryContext.getNamespace method returns the namespace URI for the specified prefix.
 int getReturnType()
          Discover the return type defined for this XmlQueryContext.
 XmlValue getVariableValue(String name)
          The XmlQueryContext.getVariableValue method returns the value that is bound to the specified variable.
 boolean getWithMetaData()
          Discover whether or not document metadata will be materialised before the query is performed.
 void removeNamespace(String prefix)
          The XmlQueryContext.removeNamespace method removes the namespace prefix to URI mapping for the specified prefix.
 void setEvaluationType(int type)
          The XmlQueryContext.setEvaluationType method allows the application to set the query evaluation type to "eager" or "lazy".
 void setNamespace(String prefix, String uri)
          The XmlQueryContext.setNamespace method maps the specified URI to the specified namespace prefix.
 void setReturnType(int type)
          The XmlQueryContext.setReturnType method allows the application to define whether the query should return documents, or values, or both.
 void setVariableValue(String name, XmlValue value)
          The XmlQueryContext.setVariableValue method binds the specified value to the specified variable.
 void setWithMetaData(boolean withMetaData)
          The XmlQueryContext.setWithMetaData method allows the application to define whether the document metadata should be materialised as attributes of the root node before a query is performed.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ResultDocuments

public static final int ResultDocuments
Return documents that match the XPath expression.


ResultValues

public static final int ResultValues
Return nodes from the documents that match the XPath expression.


CandidateDocuments

public static final int CandidateDocuments
Return documents that may match the query expression.


ResultDocumentsAndValues

public static final int ResultDocumentsAndValues
Return both the nodes from the documents that match the query expression, and the matching documents.


Eager

public static final int Eager
The query is executed and its resultant values are derived and stored in-memory before a call to XmlContainer.queryWithXPath returns.


Lazy

public static final int Lazy
Minimal processing is performed before XmlContainer.queryWithXPath returns, and the remaining processing is deferred until the result set is enumerated.

Constructor Detail

XmlQueryContext

public XmlQueryContext(int returnType,
                       int evaluationType)
                throws XmlException
The XmlQueryContext class encapsulates the context within which a query is performed against an XmlContainer. The context includes a namespace mapping, 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.

The XmlQueryContext constructor accepts parameters that define whether queries executed within the context are to be evaluated lazily or eagerly, and whether the query is to return candidate documents, result documents, or result values. For detailed descriptions of these parameters see XmlQueryContext.setReturnType and XmlQueryContext.setEvaluationType.

The XPath query syntax permits expressions to refer to namespace prefixes, but not to define them. 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 XPath syntax also permits expressions to refer to variables, but not to define them. The XmlQueryContext class provides methods that allow the caller to manage the variable to value bindings.

A copy constructor and assignment operator are 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.

Parameters:
returnType - The type parameter specifies which of documents or values to return, and must be set to one of the following values:
evaluationType - The evaluation type must be specified as either:
Throws:
XmlException
Method Detail

delete

public void delete()

setNamespace

public void setNamespace(String prefix,
                         String uri)
                  throws XmlException
The XmlQueryContext.setNamespace method 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
The XmlQueryContext.getNamespace method returns the namespace URI for the specified prefix. An empty string is returned if no URI is defined for the prefix.

Parameters:
prefix - The name of the namespace prefix whose URI mapping is required.
Returns:
the namespace URI for the specified prefix, or an empty string if no URI is defined for that prefix.

Throws:
XmlException

removeNamespace

public void removeNamespace(String prefix)
                     throws XmlException
The XmlQueryContext.removeNamespace method removes the namespace prefix to URI mapping for the specified prefix. A call to this method with a prefix that has with no existing mapping is ignored.

Parameters:
prefix - The namespace prefix to be removed.
Throws:
XmlException

clearNamespaces

public void clearNamespaces()
                     throws XmlException
The XmlQueryContext.clearNamespaces method removes all current namespace prefix to URI mappings from the query context.

Throws:
XmlException

setVariableValue

public void setVariableValue(String name,
                             XmlValue value)
                      throws XmlException
The XmlQueryContext.setVariableValue method binds the specified value to the specified variable.

Parameters:
name - The name of the variable to bind.
value - The value to bind to the named variable.
Throws:
XmlException

setReturnType

public void setReturnType(int type)
                   throws XmlException
The XmlQueryContext.setReturnType method allows the application to define whether the query should return documents, or values, or both.

The ResultDocuments return type instructs the query processor to select documents from the container that match the query expression. A document is said to match the query if the execution of the query over the document would return a value for that document. The query returns an XmlResults object that contains a list of XmlValues of type XmlValue.DOCUMENT.

The ResultValues return type instructs the query processor to select documents from the container that match the query expression, and to return the result of executing the query over the document. The query returns an XmlResults object that contains a list of XmlValues of type UNREF==XmlValue_NODE. The XmlValues contain deep copies of the result nodes, meaning that all descendant child nodes are also copied.

The ResultDocumentsAndValues return type instructs the query processor to return both documents and values. It behaves just as ResultValues does, returning an XmlResults object that contains a list of XmlValues of type UNREF==XmlValue_NODE. The difference being that the containing XmlDocument can be retrieved by calling the XmlValue.asDocument method.

The CandidateDocuments return type instructs the query processor to return documents that match the query, but only using the available indices. Under normal processing the matching documents returned from the indices are filtered through a query processor that applies the query against the document. For some query expressions the caller might know that the candidate set is equivalent to the result set. For these expressions there is no need to pass the candidate documents through a filter to eliminate false positives. The query processor can identify some query expressions of this nature, but not all. The CandidateDocuments return type allows the client application to do its own false-positive elimination.

Parameters:
type - The type parameter specifies which of documents or values to return, and must be set to one of the following values:
Throws:
XmlException

getReturnType

public int getReturnType()
                  throws XmlException
Discover the return type defined for this XmlQueryContext.

Returns:
Returns the return type defined for this XmlQueryContext.

Throws:
XmlException

setEvaluationType

public void setEvaluationType(int type)
                       throws XmlException
The XmlQueryContext.setEvaluationType method 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 the call to XmlContainer.queryWithXPath returns. Lazy evaluation means that minimal processing is performed before XmlContainer.queryWithXPath returns, 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:
Throws:
XmlException

getEvaluationType

public int getEvaluationType()
                      throws XmlException
Discover the evaluation type defined for this XmlQueryContext.

Returns:
Returns the evaluation type defined for this XmlQueryContext.

Throws:
XmlException

setWithMetaData

public void setWithMetaData(boolean withMetaData)
                     throws XmlException
The XmlQueryContext.setWithMetaData method allows the application to define whether the document metadata should be materialised as attributes of the root node before a query is performed. By default, the metadata is added. Adding the metadata has some cost, and if it is not necessary for correctness of the query, leaving it off is more efficient.

Parameters:
withMetaData - The withMetaData parameter specifies whether or not to add the document metadata prior to the query.
Throws:
XmlException

getWithMetaData

public boolean getWithMetaData()
                        throws XmlException
Discover whether or not document metadata will be materialised before the query is performed. The default is true.

.

Returns:
Returns the boolean value set in the XmlQueryContext object.

Throws:
XmlException

getVariableValue

public XmlValue getVariableValue(String name)
                          throws XmlException
The XmlQueryContext.getVariableValue method returns the value that is bound to the specified variable. If there is no value binding then the function returns null.

Parameters:
name - The name of the variable whose value is required.
Returns:
Returns the value bound to the variable.
Throws:
XmlException

Berkeley DbXML
version 1.2.1

Copyright (c) 1996-2003 Sleepycat Software, Inc. - All rights reserved.