Qizx/Open v0.4

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.


Nested Class Summary
static interface XQueryProcessor.PauseHandler
          An object used to pause execution.
 
Field Summary
static Namespace EXTENSIONS_NS
           
static java.lang.String EXTENSIONS_URI
           
static java.lang.String XSLT_OUTPUT_FILE
           
 
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).
 XQuery compileQuery(java.lang.CharSequence textInput, java.lang.String uri, Log log)
          Parses and checks a query from a text input.
 XQuery compileQuery(java.io.File input, Log log)
          Helper for compiling a query from a file.
 XQuery compileQuery(java.io.Reader input, java.lang.String uri, Log log)
          Helper for compiling a query from a stream.
 Value eval(java.lang.String expression, Focus focus, EvalContext context)
          Compiles and executes a simple expression in the context specified.
 Value executeQuery(XQuery query)
          Executes a query in the static and dynamic environment provided by this processor.
 void executeQuery(XQuery query, java.io.Writer output)
          Executes a query with direct output to a serial XML stream (with the default serialization options).
 void executeQuery(XQuery 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 pauseExecution(XQueryProcessor.PauseHandler pause)
          Requests asynchronously a pause in execution.
 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 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 uri)
          Defines the input() sequence by a collection URI.
 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(java.lang.String xmlSource)
          Defines the input() sequence by a XML fragment.
 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:system-property(name) or by any application.
 void stopExecution()
          Stops a running execution.
static QName toLocalNS(java.lang.String name)
          Utility for use with predefineGlobal and initGlobal: convert a NCName to a QName in 'local' namespace.
 IDocument xslTransform(Node source, java.lang.String templates, java.util.Properties parameters, java.util.Properties options)
          Runs a XSLT transformation on an element (internal use).
 
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

XSLT_OUTPUT_FILE

public static final java.lang.String XSLT_OUTPUT_FILE
See Also:
Constant Field Values
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.


setInput

public void setInput(java.lang.String xmlSource)
              throws XQueryException
Defines the input() sequence by a XML fragment.

Parameters:
xmlSource - a fragment of XML to be parsed and used as implicit input.
XQueryException

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 uri)
                        throws XQueryException
Defines the input() sequence by a collection URI. Implemented only in XQuest.

XQueryException

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:system-property(name) or by any application.

Parameters:
name - of a property
property - value of the property to store.

getSysProperty

public java.lang.Object getSysProperty(java.lang.String name)
Retrieves a previously defined system property.

Parameters:
name - of a property
Returns:
the stored property, or null if not found.

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 in the predefined static context. The initial value must then be set by a variant of initGlobal() suitable for the type specified.

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 XQuery 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 XQuery 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 XQuery 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(XQuery 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(XQuery 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(XQuery 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 or a SAXEventReceiver.
XQueryException

executeQuery

public void executeQuery(XQuery 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(XQuery query) for more details

XQueryException

stopExecution

public void stopExecution()
Stops a running execution. Must of course be called by another thread.


pauseExecution

public void pauseExecution(XQueryProcessor.PauseHandler pause)
Requests asynchronously a pause in execution. Upon reception of this request, the processor calls the 'pauseAt' method of the PauseHandler interface, then suspends execution by waiting on the PauseHandler object. Therefore a notify() has to be done on the handler to restart it.


eval

public Value eval(java.lang.String expression,
                  Focus focus,
                  EvalContext context)
           throws XQueryException
Compiles and executes a simple expression in the context specified. The expression has access to the global context but not to local variables.

XQueryException

xslTransform

public IDocument xslTransform(Node source,
                              java.lang.String templates,
                              java.util.Properties parameters,
                              java.util.Properties options)
                       throws javax.xml.transform.TransformerException,
                              XQueryException
Runs a XSLT transformation on an element (internal use).

Parameters:
source - node on which the transformation is applied.
templates - URI of a stylesheet (resolved by the Module Manager).
parameters - a set name/value pairs specifying initial values for global xsl:param in the stylesheet.
options - a set name/value pairs specifying options for the transformation:
  • 'output-file': name of an output file for the transformation; in that case a null tree is returned and a StreamResult is used.
  • standard JAXP "output keys"
  • other options specific to the XSLT engine can be accepted.
Returns:
a Document in memory, or null if the options specify an output file.
javax.xml.transform.TransformerException
XQueryException

 Copyright Xavier FRANC 2003-2004