## org.exist.xmldb
Interface XQueryService

All Superinterfaces:
  Configurable, Service, XQueryService

All Known Implementing Classes:
  LocalXPathQueryService, RemoteXPathQueryService

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)

Field Summary

Fields inherited from interface org.xmldb.api.modules.XQueryService
`SERVICE_NAME`

Method Summary
`CompiledExpression` `compile(java.lang.String query)` Compiles the specified XQuery and returns a handle to the compiled code, which can then be passed to `execute(CompiledExpression)`.
`CompiledExpression` `compileAndCheck(java.lang.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(java.lang.String qname, java.lang.Object initialValue)` Declare a global, external XQuery variable and assign a value to it.
`void` `dump(CompiledExpression expression, java.io.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)`
`java.lang.String` `getNamespace(java.lang.String prefix)` Returns the URI string associated with `prefix` from the internal namespace map.
`ResourceSet` `query(java.lang.String query)` Execute the specified query and return the results as a `ResourceSet`.
`ResourceSet` `query(XMLResource res, java.lang.String query)` Process a query based on the result of a previous query.
`void` `removeNamespace(java.lang.String ns)` Removes the namespace mapping associated with `prefix` from the internal namespace map.
`void` `setModuleLoadPath(java.lang.String path)`
`void` `setNamespace(java.lang.String prefix, java.lang.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

    public ResourceSet query(java.lang.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

    public ResourceSet query(XMLResource res,
                             java.lang.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

    public CompiledExpression compile(java.lang.String query)
                               throws XMLDBException

  Compiles the specified XQuery and returns a handle to the compiled code, which can then be passed to `execute(CompiledExpression)`.

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

### compileAndCheck

    public CompiledExpression compileAndCheck(java.lang.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

    public ResourceSet execute(Source source)
                        throws XMLDBException

  Throws:
    `XMLDBException`

### execute

    public 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.

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

### execute

    public ResourceSet execute(XMLResource res,
                               CompiledExpression expression)
                        throws XMLDBException

  Throws:
    `XMLDBException`

### getNamespace

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

    public void setNamespace(java.lang.String prefix,
                             java.lang.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

    public void removeNamespace(java.lang.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

    public void declareVariable(java.lang.String qname,
                                java.lang.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

    public 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

    public void setModuleLoadPath(java.lang.String path)

  Specified by:
    `setModuleLoadPath` in interface `XQueryService`

### dump

    public void dump(CompiledExpression expression,
                     java.io.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) Wolfgang Meier. All rights reserved.