Overview | Package | Class | Tree | Deprecated | Index | Help
| Qizx/Open v0.3
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## net.xfra.qizxopen.xquery
Class XQueryProcessor

    java.lang.Object
      |
      +--net.xfra.qizxopen.xquery.XQueryProcessor

Direct Known Subclasses:
  SAXXQueryProcessor

public class XQueryProcessor
extends java.lang.Object

Main interface to XML Query services.

XQueryProcessor provides a static environment to compile a query from some text source, and a dynamic environment (in particular a Document Manager) to execute this query.

The standard way for using it is as follows:

- Instantiate a XQueryProcessor using one of the constructors.
- compile a query using one form of `compileQuery`. A message `Log` has to be instantiated and passed to these methods. This yields a compiled `Query` object.
- Execute the query one or several times using one of the `executeQuery` methods.

Miscellaneous optional informations can be set through specialized methods for use in the static or dynamic query contexts: global variable values, default collation, implicit timezone, document input, base URI, default serialization output.

XQueryProcessors can share a common `ModuleManager` or `DocumentManager`. It avoids redundant compilation or document loading in an environment where many processors use the same queries or documents. The way to achieve this is to create a "master" processor with its own ModuleManager and DocumentManager and to use it in the proper constructor for each needed instance.

Field Summary
`static Namespace` | `EXTENSIONS_NS`
`static java.lang.String` | `EXTENSIONS_URI`

Constructor Summary
`XQueryProcessor()` Creation without Module Manager and Document Manager.
`XQueryProcessor(java.lang.String moduleBaseURI, java.lang.String baseURI)` Simple creation with private Module Manager and Document Manager.
`XQueryProcessor(XQueryProcessor master)` Creates a new XQueryProcessor from a "master" processor, inheriting and sharing the document manager, module manager, predefined functions and global variables.

Method Summary
`void` | `authorizeClass(java.lang.String className)` Allow a Java class to be used as extension (more precisely, its public methods can be called as extension functions).
`Query` | `compileQuery(java.lang.CharSequence textInput, java.lang.String uri, Log log)` Parses and checks a query from a text input.
`Query` | `compileQuery(java.io.File input, Log log)` Helper for compiling a query from a file.
`Query` | `compileQuery(java.io.Reader input, java.lang.String uri, Log log)` Helper for compiling a query from a stream.
`Value` | `executeQuery(Query query)` Executes a query in the static and dynamic environment provided by this processor.
`void` | `executeQuery(Query query, java.io.Writer output)` Executes a query with direct output to a serial XML stream (with the default serialization options).
`void` | `executeQuery(Query query, XMLEventReceiver receiver)` Executes a query with direct output to a serial XML event receiver (SAX or XML stream).
`DocumentManager` | `getDocumentManager()` Returns the current Document Manager.
`ModuleManager` | `getModuleManager()` Returns the current Module Manager.
`java.lang.Object` | `getSysProperty(java.lang.String name)` Retrieves a previously defined system property.
`java.lang.String` | `getVersion()` Gets the current version of the XML Query engine.
`void` | `initGlobal(QName varName, boolean value)` Convenience method.
`void` | `initGlobal(QName varName, double value)` Convenience method.
`void` | `initGlobal(QName varName, long value)` Convenience method.
`void` | `initGlobal(QName varName, java.lang.Object value)` Convenience method.
`void` | `initGlobal(QName varName, java.lang.String value)` Convenience method.
`void` | `initGlobal(QName varName, java.lang.String[] value)` Convenience method.
`void` | `initGlobal(QName varName, Value value)` Sets an initial value for a global variable.
`void` | `predefineGlobal(QName varName, Type type)` Defines a global variable in the predefined static context.
`void` | `predefineGlobal(java.lang.String varName, Type type)` Defines a global variable (with 'local' namespace) in the predefined static context.
`void` | `predefineNamespace(java.lang.String prefix, java.lang.String uri)` Defines a namespace mapping visible by queries compiled with this processor.
`void` | `registerCollation(java.lang.String uri, java.text.Collator collator)` Registers a custom collation for use in the processed queries.
`void` | `resetDeclarations()` Clears all predefined variables added, and initial values for globals.
`void` | `setCollectionInput(java.lang.String url)` Defines the input() sequence by a collection URI (not yet implemented).
`void` | `setDefaultCollation(java.lang.String uri)` Defines the URI of the default collation.
`void` | `setDefaultOutput(java.io.PrintWriter output)` Defines the default output channel for serialization.
`void` | `setDocumentInput(java.lang.String docURI)` Defines the input() sequence by a document URI.
`void` | `setDocumentManager(DocumentManager documentManager)` Defines the Document Manager.
`void` | `setImplicitTimezone(java.lang.String duration)` Defines the implicit timezone in xs:duration format.
`void` | `setInput(Node inputDoc)` Defines a single node as the root of a document returned by the XQuery function input().
`void` | `setLog(Log log)` Defines a runtime log.
`void` | `setModuleManager(ModuleManager moduleManager)` Sets up the Module Manager.
`void` | `setSysProperty(java.lang.String name, java.lang.Object property)` Defines a property, a named object that can be retrieved by the extension function x:get-app-property(name) or by any application.
`static QName` | `toLocalNS(java.lang.String name)` Utility for use with predefineGlobal and initGlobal: convert a NCName to a QName in 'local' namespace.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### EXTENSIONS_URI

    public static java.lang.String EXTENSIONS_URI

### EXTENSIONS_NS

    public static Namespace EXTENSIONS_NS

Constructor Detail

### XQueryProcessor

    public XQueryProcessor()

  Creation without Module Manager and Document Manager.

  These objects must be specified before execution.

### XQueryProcessor

    public XQueryProcessor(java.lang.String moduleBaseURI,
                           java.lang.String baseURI)
                    throws java.io.IOException

  Simple creation with private Module Manager and Document Manager.

Parameters:
  `baseURI` - default base URI (also used for Document Manager)
  `moduleBaseURI` - base URI used to resolve module locations
Throws:
  `java.io.IOException` - thrown by ModuleManager or DocumentManager constructors.

### XQueryProcessor

    public XQueryProcessor(XQueryProcessor master)

  Creates a new XQueryProcessor from a "master" processor, inheriting and sharing the document manager, module manager, predefined functions and global variables.

Parameters:
  `master` - a XQueryProcessor used as template.

Method Detail

### getVersion

    public java.lang.String getVersion()

  Gets the current version of the XML Query engine.

### setModuleManager

    public void setModuleManager(ModuleManager moduleManager)

  Sets up the Module Manager.

### getModuleManager

    public ModuleManager getModuleManager()

  Returns the current Module Manager.

### setDocumentManager

    public void setDocumentManager(DocumentManager documentManager)

  Defines the Document Manager.

### getDocumentManager

    public DocumentManager getDocumentManager()

  Returns the current Document Manager.

### setDocumentInput

    public void setDocumentInput(java.lang.String docURI)
                          throws XQueryException

  Defines the input() sequence by a document URI.

  Parameters:
    `docURI` - uri of a document to be opened or parsed and used as implicit input. This URI can be relative to the document base URI (if the default Document Manager is used).
    `XQueryException`

### setCollectionInput

    public void setCollectionInput(java.lang.String url)

  Defines the input() sequence by a collection URI (not yet implemented).

### setInput

    public void setInput(Node inputDoc)

  Defines a single node as the root of a document returned by the XQuery function input(). For internal usage.

### setDefaultOutput

    public void setDefaultOutput(java.io.PrintWriter output)

  Defines the default output channel for serialization.

### setLog

    public void setLog(Log log)

  Defines a runtime log.

### setSysProperty

    public void setSysProperty(java.lang.String name,
                               java.lang.Object property)

  Defines a property, a named object that can be retrieved by the extension function x:get-app-property(name) or by any application.

### getSysProperty

    public java.lang.Object getSysProperty(java.lang.String name)

  Retrieves a previously defined system property.

### resetDeclarations

    public void resetDeclarations()

  Clears all predefined variables added, and initial values for globals.

### predefineGlobal

    public void predefineGlobal(QName varName,
                                Type type)

  Defines a global variable in the predefined static context. The initial value must then be set by a variant of initGlobal() suitable to the type.

  Parameters:
    `varName` - local name of the variable.
    `type` - assigned to the variable.

### predefineGlobal

    public void predefineGlobal(java.lang.String varName,
                                Type type)

  Defines a global variable (with 'local' namespace) in the predefined static context. The initial value must then be set by a variant of initGlobal() suitable to the type.

  Parameters:
    `varName` - local name of the variable.
    `type` - assigned to the variable.

### initGlobal

    public void initGlobal(QName varName,
                           Value value)

  Sets an initial value for a global variable. This is not attached to a particular query, so it does not raise an error if the variable doesn't exist.

  Parameters:
    `varName` - qualified name of the variable (can be in the namespace of a module or 'local').
    `value` - provided initial value: must be compatible with the declared type (not checked immediately). If the value is a string, an attempt to cast to the proper type will be made.

### toLocalNS

    public static QName toLocalNS(java.lang.String name)

  Utility for use with predefineGlobal and initGlobal: convert a NCName to a QName in 'local' namespace.

### initGlobal

    public void initGlobal(QName varName,
                           boolean value)

  Convenience method. See `initGlobal(QName varName, Value value)`.

### initGlobal

    public void initGlobal(QName varName,
                           long value)

  Convenience method. See `initGlobal(QName varName, Value value)`.

### initGlobal

    public void initGlobal(QName varName,
                           double value)

  Convenience method. See `initGlobal(QName varName, Value value)`.

### initGlobal

    public void initGlobal(QName varName,
                           java.lang.String value)

  Convenience method. See `initGlobal(QName varName, Value value)`.

### initGlobal

    public void initGlobal(QName varName,
                           java.lang.String[] value)

  Convenience method. See `initGlobal(QName varName, Value value)`.

### initGlobal

    public void initGlobal(QName varName,
                           java.lang.Object value)

  Convenience method. See `initGlobal(QName varName, Value value)`.

### predefineNamespace

    public void predefineNamespace(java.lang.String prefix,
                                   java.lang.String uri)

  Defines a namespace mapping visible by queries compiled with this processor.

### registerCollation

    public void registerCollation(java.lang.String uri,
                                  java.text.Collator collator)

  Registers a custom collation for use in the processed queries.

### setDefaultCollation

    public void setDefaultCollation(java.lang.String uri)

  Defines the URI of the default collation.

### setImplicitTimezone

    public void setImplicitTimezone(java.lang.String duration)

  Defines the implicit timezone in xs:duration format.

  Parameters:
    `duration` - for example "PT4H30M" or "-PT5H". If not specified, the implicit timezone is taken from the system default.

### authorizeClass

    public void authorizeClass(java.lang.String className)

  Allow a Java class to be used as extension (more precisely, its public methods can be called as extension functions).

  Caution: using this method enforces an explicit control: all classes to be used as extensions must then be explicitly declared. This is a security feature.

  Parameters:
    `className` - fully qualified name of Java class, for example

        java.io.File

### compileQuery

    public Query compileQuery(java.lang.CharSequence textInput,
                              java.lang.String uri,
                              Log log)
                       throws XQueryException

  Parses and checks a query from a text input. Errors are reported through the log.

  Parameters:
    `textInput` - the actual text to parse
    `uri` - of the query source (for messages), or null if not applicable.
    `log` - message collector
  Returns:
    the parsed and type-checked query if no error is detected.
  Throws:
    `SyntaxException` - as soon as a syntax error is detected.
    `XQueryException` - at end of compilation if static errors have been detected (error details are reported through the Log).

### compileQuery

    public Query compileQuery(java.io.Reader input,
                              java.lang.String uri,
                              Log log)
                       throws XQueryException,
                              java.io.IOException

  Helper for compiling a query from a stream. See `compileQuery(java.lang.CharSequence, java.lang.String, net.xfra.qizxopen.xquery.Log)`

  Parameters:
    `input` - query source
    `uri` - uri of the source (can be a dummy value)
    `log` - message collector
    `XQueryException`
    `java.io.IOException`

### compileQuery

    public Query compileQuery(java.io.File input,
                              Log log)
                       throws XQueryException,
                              java.io.IOException

  Helper for compiling a query from a file. See `compileQuery(java.lang.CharSequence, java.lang.String, net.xfra.qizxopen.xquery.Log)`

  Parameters:
    `input` - query source
    `log` - message collector
    `XQueryException`
    `java.io.IOException`

### executeQuery

    public Value executeQuery(Query query)
                       throws XQueryException

  Executes a query in the static and dynamic environment provided by this processor. The Document Manager is used for access to documents by the XQuery function doc(), the `setDocumentInput(java.lang.String)` or `setCollectionInput(java.lang.String)` methods define the data accessible by the XQuery function input().

  Parameters:
    `query` - a query compiled with compileQuery. May be used by several threads.
  Returns:
    the evaluated value. Enumerates items and their value.
  Throws:
    `EvalException` - run-time exception. A stack trace can be obtained from the exception.
    `XQueryException` - other exception. Happens only in serious cases.

### executeQuery

    public void executeQuery(Query query,
                             XMLEventReceiver receiver)
                      throws XQueryException

  Executes a query with direct output to a serial XML event receiver (SAX or XML stream). The query must evaluate as a single Node, otherwise an EvalException is raised.

  See `executeQuery(Query query)` for more details

  Parameters:
    `query` - a query compiled with compileQuery. May be used by several threads.
    `receiver` - a handler for generated events. In practice a XMLSerializer, HTMLSerializer or SAXEventReceiver.
    `XQueryException`

### executeQuery

    public void executeQuery(Query query,
                             java.io.Writer output)
                      throws XQueryException

  Executes a query with direct output to a serial XML stream (with the default serialization options). The query must evaluate as a single Node, otherwise an EvalException is raised.

  See `executeQuery(Query query)` for more details

    `XQueryException`

Overview | Package | Class | Tree | Deprecated | Index | Help
| Copyright Xavier FRANC 2003-2004
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD