org.exist.xmldb
Interface XQueryService

All Superinterfaces:
Configurable, Service, XQueryService

public interface XQueryService
extends XQueryService

Execute XQuery expressions on the database. This interface is similar to XPathQueryService, but provides additional methods to compile an XQuery into an internal representation, which can be executed repeatedly. Since XQuery scripts can be very large, compiling an expression in advance can save a lot of time.

Author:
Wolfgang Meier (wolfgang@exist-db.org)

Method Summary
 CompiledExpression compile(String query)
          Compiles the specified XQuery and returns a handle to the compiled code, which can then be passed to execute(CompiledExpression).
 CompiledExpression compileAndCheck(String query)
          Tries to compile the specified XQuery and returns a handle to the compiled code, which can then be passed to execute(CompiledExpression).
 void declareVariable(String qname, Object initialValue)
          Declare a global, external XQuery variable and assign a value to it.
 void dump(CompiledExpression expression, Writer writer)
          Return a diagnostic dump of the query.
 ResourceSet execute(CompiledExpression expression)
          Execute a compiled XQuery.
 ResourceSet execute(Source source)
           
 ResourceSet execute(XMLResource res, CompiledExpression expression)
           
 String getNamespace(String prefix)
          Returns the URI string associated with prefix from the internal namespace map.
 ResourceSet query(String query)
          Execute the specified query and return the results as a ResourceSet.
 ResourceSet query(XMLResource res, String query)
          Process a query based on the result of a previous query.
 void removeNamespace(String ns)
          Removes the namespace mapping associated with prefix from the internal namespace map.
 void setModuleLoadPath(String path)
           
 void setNamespace(String prefix, String namespace)
          Sets a namespace mapping in the internal namespace map used to evaluate queries.
 void setXPathCompatibility(boolean backwardsCompatible)
          Enable or disable XPath 1.0 compatibility mode.
 
Methods inherited from interface org.xmldb.api.modules.XQueryService
clearNamespaces, queryResource
 
Methods inherited from interface org.xmldb.api.base.Service
getName, getVersion, setCollection
 
Methods inherited from interface org.xmldb.api.base.Configurable
getProperty, setProperty
 

Method Detail

query

ResourceSet query(String query)
                  throws XMLDBException
Execute the specified query and return the results as a ResourceSet.

Specified by:
query in interface XQueryService
Parameters:
query -
Throws:
XMLDBException

query

ResourceSet query(XMLResource res,
                  String query)
                  throws XMLDBException
Process a query based on the result of a previous query. The XMLResource contains the result received from a previous query.

Parameters:
res - an XMLResource as obtained from a previous query.
query - the XPath query
Throws:
XMLDBException

compile

CompiledExpression compile(String query)
                           throws XMLDBException
Compiles the specified XQuery and returns a handle to the compiled code, which can then be passed to execute(CompiledExpression). Note: CompiledExpression is not thread safe. Please make sure you don't call the same compiled expression from two threads at the same time.

Specified by:
compile in interface XQueryService
Parameters:
query -
Throws:
XMLDBException

compileAndCheck

CompiledExpression compileAndCheck(String query)
                                   throws XMLDBException,
                                          XPathException
Tries to compile the specified XQuery and returns a handle to the compiled code, which can then be passed to execute(CompiledExpression). If a static error is detected, an XPathException will be thrown.

Parameters:
query -
Throws:
XMLDBException
XPathException

execute

ResourceSet execute(Source source)
                    throws XMLDBException
Throws:
XMLDBException

execute

ResourceSet execute(CompiledExpression expression)
                    throws XMLDBException
Execute a compiled XQuery. The implementation should pass all namespaces and variables declared through XQueryService to the compiled XQuery code. Note: CompiledExpression is not thread safe. Please make sure you don't call the same compiled expression from two threads at the same time.

Specified by:
execute in interface XQueryService
Parameters:
expression -
Throws:
XMLDBException

execute

ResourceSet execute(XMLResource res,
                    CompiledExpression expression)
                    throws XMLDBException
Throws:
XMLDBException

getNamespace

String getNamespace(String prefix)
                    throws XMLDBException
Returns the URI string associated with prefix from the internal namespace map. If prefix is null or empty the URI for the default namespace will be returned. If a mapping for the prefix can not be found null is returned.

Specified by:
getNamespace in interface XQueryService
Parameters:
prefix - The prefix to retrieve from the namespace map.
Returns:
The URI associated with prefix
Throws:
XMLDBException - with expected error codes.
ErrorCodes.VENDOR_ERROR for any vendor specific errors that occur.

setNamespace

void setNamespace(String prefix,
                  String namespace)
                  throws XMLDBException
Sets a namespace mapping in the internal namespace map used to evaluate queries. If prefix is null or empty the default namespace is associated with the provided URI. A null or empty uri results in an exception being thrown.

Specified by:
setNamespace in interface XQueryService
Parameters:
prefix - The prefix to set in the map. If prefix is empty or null the default namespace will be associated with the provided URI.
namespace - The URI for the namespace to be associated with prefix.
Throws:
XMLDBException - with expected error codes.
ErrorCodes.VENDOR_ERROR for any vendor specific errors that occur.
TODO: probably need some special error here.

removeNamespace

void removeNamespace(String ns)
                     throws XMLDBException
Removes the namespace mapping associated with prefix from the internal namespace map. If prefix is null or empty the mapping for the default namespace will be removed.

Specified by:
removeNamespace in interface XQueryService
Parameters:
ns - The prefix to remove from the namespace map. If prefix is null or empty the mapping for the default namespace will be removed.
Throws:
XMLDBException - with expected error codes.
ErrorCodes.VENDOR_ERROR for any vendor specific errors that occur.

declareVariable

void declareVariable(String qname,
                     Object initialValue)
                     throws XMLDBException
Declare a global, external XQuery variable and assign a value to it. The variable has the same status as a variable declare through the declare variable statement in the XQuery prolog. The variable can be referenced inside the XQuery expression as $variable. For example, if you declare a variable with
        declareVariable("name", "HAMLET");
 
you may use the variable in an XQuery expression as follows:
        //SPEECH[SPEAKER=$name]
 
Any Java object may be passed as initial value. The implementation will try to map the Java object into a corresponding XQuery value. In particular, all basic Java types (Integer, Long, Double, String) should be mapped into the corresponding XML Schema atomic types. A Java array is mapped to an XQuery sequence. The implemenation should also recognize all DOM node types. As a special case, an XMLResource as obtained from a ResourceSet will be converted into a node.

Specified by:
declareVariable in interface XQueryService
Parameters:
qname - a valid QName by which the variable is identified. Any prefix should have been mapped to a namespace, using setNamespace(String, String). For example, if a variable is called x:name, a prefix/namespace mapping should have been defined for prefix x before calling this method.
initialValue - the initial value, which is assigned to the variable
Throws:
XMLDBException

setXPathCompatibility

void setXPathCompatibility(boolean backwardsCompatible)
Enable or disable XPath 1.0 compatibility mode. In XPath 1.0 compatibility mode, some XQuery expressions will behave different. In particular, additional automatic type conversions will be applied to the operands of numeric operators.

Specified by:
setXPathCompatibility in interface XQueryService
Parameters:
backwardsCompatible -

setModuleLoadPath

void setModuleLoadPath(String path)
Specified by:
setModuleLoadPath in interface XQueryService

dump

void dump(CompiledExpression expression,
          Writer writer)
          throws XMLDBException
Return a diagnostic dump of the query. The query should have been executed before calling this function.

Parameters:
expression -
writer -
Throws:
XMLDBException


Copyright (C) The eXist-db Project. All rights reserved.