Qizx/Open v0.3

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:

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

 Copyright Xavier FRANC 2003-2004