public class XQueryCompiler
extends java.lang.Object
To construct an XQueryCompiler, use the factory method Processor.newXQueryCompiler()
.
An XQueryCompiler may be used repeatedly to compile multiple queries. Any changes made to the XQueryCompiler (that is, to the static context) do not affect queries that have already been compiled. An XQueryCompiler may in principle be used concurrently in multiple threads, but in practice this is best avoided because all instances will share the same ErrorListener and it will therefore be difficult to establish which error messages are associated with each compilation..
Modifier | Constructor and Description |
---|---|
protected |
XQueryCompiler(Processor processor)
Protected constructor
|
Modifier and Type | Method and Description |
---|---|
XQueryExecutable |
compile(java.io.File query)
Compile a query supplied as a file
|
XQueryExecutable |
compile(java.io.InputStream query)
Compile a query supplied as an InputStream
|
XQueryExecutable |
compile(java.io.Reader query)
Compile a query supplied as a Reader
|
XQueryExecutable |
compile(java.lang.String query)
Compile a query supplied as a string.
|
void |
compileLibrary(java.io.File query)
Compile a library module supplied as a file.
|
void |
compileLibrary(java.io.InputStream query)
Compile a library module supplied as an InputStream.
|
void |
compileLibrary(java.io.Reader query)
Compile a library module supplied as a Reader.
|
void |
compileLibrary(java.lang.String query)
Compile a library module supplied as a string.
|
void |
declareCollation(java.lang.String uri,
java.text.Collator collation)
Deprecated.
since 9.6. Collations are now held globally. If this method is called, the effect
is to update the pool of collations held globally by the Processor.
|
void |
declareDefaultCollation(java.lang.String uri)
Declare the default collation
|
void |
declareNamespace(java.lang.String prefix,
java.lang.String uri)
Declare a namespace binding as part of the static context for queries compiled using this
XQueryCompiler.
|
java.net.URI |
getBaseURI()
Get the static base URI for the query
|
java.lang.String |
getEncoding()
Get the encoding previously set for the supplied query.
|
javax.xml.transform.ErrorListener |
getErrorListener()
Get the ErrorListener being used during this compilation episode
|
java.lang.String |
getLanguageVersion()
Ask whether an XQuery 1.0 or XQuery 3.0 or XQuery 3.1 processor is being used
|
ModuleURIResolver |
getModuleURIResolver()
Get the user-defined ModuleURIResolver for resolving URIs used in
import module
declarations in the XQuery prolog; returns null if none has been explicitly set either
here or in the Saxon Configuration. |
Processor |
getProcessor()
Get the Processor from which this XQueryCompiler was constructed
|
ItemType |
getRequiredContextItemType()
Get the required type of the context item.
|
StaticQueryContext |
getUnderlyingStaticContext()
Get the underlying
StaticQueryContext object that maintains the static context
information on behalf of this XQueryCompiler. |
boolean |
isCompileWithTracing()
Ask whether trace hooks are included in the compiled code.
|
boolean |
isSchemaAware()
Ask whether schema-awareness has been requested either by means of a call on
setSchemaAware(boolean) |
boolean |
isStreaming()
Ask whether the streaming option has been set, that is, whether
subsequent calls on compile() will compile queries to be capable
of executing in streaming mode.
|
boolean |
isUpdatingEnabled()
Ask whether the query is allowed to use XQuery Update syntax
|
void |
setBaseURI(java.net.URI baseURI)
Set the static base URI for the query
|
void |
setCompileWithTracing(boolean option)
Set whether trace hooks are to be included in the compiled code.
|
void |
setEncoding(java.lang.String encoding)
Set the encoding of the supplied query.
|
void |
setErrorList(java.util.List<StaticError> errorList)
List of errors.
|
void |
setErrorListener(javax.xml.transform.ErrorListener listener)
Set the ErrorListener to be used during this query compilation episode
|
void |
setLanguageVersion(java.lang.String value)
Deprecated.
in 9.8; the only XQuery version supported is "3.1", and any other value is
ignored with a warning.
|
void |
setModuleURIResolver(ModuleURIResolver resolver)
Set a user-defined ModuleURIResolver for resolving URIs used in
import module
declarations in the XQuery prolog. |
void |
setRequiredContextItemType(ItemType type)
Declare the static type of the context item.
|
void |
setSchemaAware(boolean schemaAware)
Say that the query must be compiled to be schema-aware, even if it contains no
"import schema" declarations.
|
void |
setStreaming(boolean option)
Say whether the query should be compiled and evaluated to use streaming.
|
void |
setUpdatingEnabled(boolean updating)
Say whether the query is allowed to be updating.
|
protected XQueryCompiler(Processor processor)
processor
- the Saxon Processorpublic Processor getProcessor()
public void setBaseURI(java.net.URI baseURI)
baseURI
- the static base URI; or null to indicate that no base URI is availablepublic java.net.URI getBaseURI()
public void setErrorListener(javax.xml.transform.ErrorListener listener)
listener
- The error listener to be used. This is notified of all errors detected during the
compilation. Static errors (as defined in the XQuery specification) are notified
to the ErrorListener.fatalError(javax.xml.transform.TransformerException)
method.
Warnings are notified to the ErrorListener.warning(javax.xml.transform.TransformerException)
.
Any exception thrown by these methods is ignored.public javax.xml.transform.ErrorListener getErrorListener()
public void setCompileWithTracing(boolean option)
option
- true if trace code is to be compiled in, false otherwisepublic boolean isCompileWithTracing()
public void setModuleURIResolver(ModuleURIResolver resolver)
import module
declarations in the XQuery prolog.
This will override any ModuleURIResolver that was specified as part of the configuration.resolver
- the ModuleURIResolver to be usedpublic ModuleURIResolver getModuleURIResolver()
import module
declarations in the XQuery prolog; returns null if none has been explicitly set either
here or in the Saxon Configuration.public void setEncoding(java.lang.String encoding)
String
or as a Reader
. If no value
is set, the query processor will attempt to infer the encoding, defaulting to UTF-8 if no
information is available.encoding
- the encoding of the supplied query, for example "iso-8859-1"public java.lang.String getEncoding()
setEncoding(String)
, or null
if no value has been set. Note that this is not necessarily the actual encoding of the query.public void setUpdatingEnabled(boolean updating)
updating
- true if the query is allowed to use the XQuery Update facility
(requires Saxon-EE). If set to false, the query must not be an updating query. If set
to true, it may be either an updating or a non-updating query.java.lang.UnsupportedOperationException
- if updating is requested and the Saxon Configuration does
not support updating, either because it is not an EnterpriseConfiguration, or because no license
key is available.public boolean isUpdatingEnabled()
public void setSchemaAware(boolean schemaAware)
schemaAware
- If true, the stylesheet will be compiled with schema-awareness
enabled even if it contains no xsl:import-schema declarations. If false, the stylesheet
is treated as schema-aware only if it contains one or more xsl:import-schema declarations.
Note that setting the value to false does not disable use of an import-schema declaration.public boolean isSchemaAware()
setSchemaAware(boolean)
public void setStreaming(boolean option)
option
- if true, the compiler will attempt to compile a query to be
capable of executing in streaming mode. If the query cannot be streamed,
a compile-time exception is reported. In streaming mode, the source
document is supplied as a stream, and no tree is built in memory. The default
is false.
When setStreaming(true) is specified, this has the additional side-effect of setting the required context item type to "document-node()"
public boolean isStreaming()
public void setLanguageVersion(java.lang.String value)
value
- Must be "3.1"; any other value is ignored with a warning.public java.lang.String getLanguageVersion()
public void declareNamespace(java.lang.String prefix, java.lang.String uri)
prefix
- The namespace prefix. If the value is a zero-length string, this method sets the default
namespace for elements and types.uri
- The namespace URI. It is possible to specify a zero-length string to "undeclare" a namespace;
in this case the prefix will not be available for use, except in the case where the prefix
is also a zero length string, in which case the absence of a prefix implies that the name
is in no namespace.java.lang.NullPointerException
- if either the prefix or uri is null.java.lang.IllegalArgumentException
- in the event of an invalid declaration of the XML namespacepublic void declareCollation(java.lang.String uri, java.text.Collator collation)
uri
- the absolute collation URIcollation
- a Collator
object that implements the required collationjava.lang.IllegalArgumentException
- if an attempt is made to rebind the standard URI
for the Unicode codepoint collationpublic void declareDefaultCollation(java.lang.String uri)
uri
- the absolute URI of the default collation. This URI must have been bound to a collation
using the method declareCollation(String, java.text.Collator)
, or it must be
one that is recognized implicitly, such as a UCA collationjava.lang.NullPointerException
- if the collation URI is nulljava.lang.IllegalStateException
- if the collation URI has not been registered, unless it is the standard
Unicode codepoint collation which is registered implicitlypublic void setRequiredContextItemType(ItemType type)
type
- the required type of the context itempublic ItemType getRequiredContextItemType()
public void compileLibrary(java.lang.String query) throws SaxonApiException
The base URI of the query should be supplied by calling setBaseURI(java.net.URI)
Separate compilation of library modules is supported only under Saxon-EE
query
- the text of the querySaxonApiException
- if the query compilation fails with a static errorpublic void compileLibrary(java.io.File query) throws SaxonApiException, java.io.IOException
The encoding of the input stream may be specified using setEncoding(String)
;
if this has not been set, the compiler determines the encoding from the version header of the
query, and if that too is absent, it assumes UTF-8.
Separate compilation of library modules is supported only under Saxon-EE
query
- the file containing the query. The URI corresponding to this file will be used as the
base URI of the query, overriding any URI supplied using setBaseURI(java.net.URI)
(but not
overriding any base URI specified within the query prolog)SaxonApiException
- if the query compilation fails with a static errorjava.io.IOException
- if the file does not exist or cannot be readpublic void compileLibrary(java.io.Reader query) throws SaxonApiException
The base URI of the query should be supplied by calling setBaseURI(java.net.URI)
Separate compilation of library modules is supported only under Saxon-EE
query
- the text of the querySaxonApiException
- if the query compilation fails with a static errorpublic void compileLibrary(java.io.InputStream query) throws SaxonApiException
The encoding of the input stream may be specified using setEncoding(String)
;
if this has not been set, the compiler determines the encoding from the version header of the
query, and if that too is absent, it assumes UTF-8.
The base URI of the query should be supplied by calling setBaseURI(java.net.URI)
Separate compilation of library modules is supported only under Saxon-EE
query
- the text of the querySaxonApiException
- if the query compilation fails with a static errorpublic XQueryExecutable compile(java.lang.String query) throws SaxonApiException
The base URI of the query should be supplied by calling setBaseURI(java.net.URI)
If the query contains static errors, these will be notified to the registered ErrorListener
.
More than one static error may be reported. If any static errors have been reported, this method
will exit with an exception, but the exception will only contain a summary message. The default
ErrorListener
writes details of each error to the System.err
output stream.
query
- the text of the querySaxonApiException
- if the query compilation fails with a static errorpublic XQueryExecutable compile(java.io.File query) throws SaxonApiException, java.io.IOException
query
- the file containing the query. The URI corresponding to this file will be used as the
base URI of the query, overriding any URI supplied using setBaseURI(java.net.URI)
(but not
overriding any base URI specified within the query prolog)SaxonApiException
- if the query compilation fails with a static errorjava.io.IOException
- if the file does not exist or cannot be readpublic XQueryExecutable compile(java.io.InputStream query) throws SaxonApiException, java.io.IOException
The base URI of the query should be supplied by calling setBaseURI(java.net.URI)
query
- the input stream on which the query is supplied. This will be consumed by this methodSaxonApiException
- if the query compilation fails with a static errorjava.io.IOException
- if the file does not exist or cannot be readpublic XQueryExecutable compile(java.io.Reader query) throws SaxonApiException, java.io.IOException
The base URI of the query should be supplied by calling setBaseURI(java.net.URI)
query
- the input stream on which the query is supplied. This will be consumed by this methodSaxonApiException
- if the query compilation fails with a static errorjava.io.IOException
- if the file does not exist or cannot be readpublic StaticQueryContext getUnderlyingStaticContext()
StaticQueryContext
object that maintains the static context
information on behalf of this XQueryCompiler. This method provides an escape hatch to internal Saxon
implementation objects that offer a finer and lower-level degree of control than the s9api classes and
methods. Some of these classes and methods may change from release to release.public void setErrorList(java.util.List<StaticError> errorList)
By supplying a custom List with a user-written add() method, it is possible to intercept error conditions as they occur.
errorList
- Copyright (c) 2004-2018 Saxonica Limited. All rights reserved.