Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DbXML version 1.2.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sleepycat.dbxml
Class XmlQueryContext

    java.lang.Object
      com.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 `XmlValue`s 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 `XmlValue`s of type UNREF==XmlValue_NODE. The `XmlValue`s 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 `XmlValue`s 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`

Package | Class | Use | Tree | Deprecated | Index | Help
| Berkeley DbXML version 1.2.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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