net.sf.saxon.s9api
Class XQueryCompiler

java.lang.Object
  net.sf.saxon.s9api.XQueryCompiler

public class XQueryCompiler
extends Object

An XQueryCompiler object allows XQuery 1.0 queries to be compiled. The compiler holds information that represents the static context for the compilation.

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 be used concurrently in multiple threads, but it should not then be modified once initialized.

Method Summary

XQueryExecutable	compile(String query) Compile a query supplied as a string
void	declareNamespace(String prefix, String uri) Declare a namespace binding as part of the static context for queries compiled using this XQueryCompiler.
URI	getBaseURI() Get the static base URI for the query
ErrorListener	getErrorListener() Get the ErrorListener being used during this compilation episode
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.
ItemType	getRequiredContextItemType() Get the required type of the context item.
boolean	isCompileWithTracing() Ask whether trace hooks are included in the compiled code.
void	setBaseURI(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	setErrorListener(ErrorListener listener) Set the ErrorListener to be used during this query compilation episode
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.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setBaseURI

public void setBaseURI(URI baseURI)

Set the static base URI for the query

Parameters:

baseURI - the static base URI

getBaseURI

public URI getBaseURI()

Get the static base URI for the query

Returns:

the static base URI

setErrorListener

public void setErrorListener(ErrorListener listener)

Set the ErrorListener to be used during this query compilation episode

Parameters:

listener - The error listener to be used. This is notified of all errors detected during the compilation.

getErrorListener

public ErrorListener getErrorListener()

Get the ErrorListener being used during this compilation episode

Returns:

listener The error listener in use. This is notified of all errors detected during the compilation. If no user-supplied ErrorListener has been set, returns the system-supplied ErrorListener.

setCompileWithTracing

public void setCompileWithTracing(boolean option)

Set whether trace hooks are to be included in the compiled code. To use tracing, it is necessary both to compile the code with trace hooks included, and to supply a TraceListener at run-time

Parameters:

option - true if trace code is to be compiled in, false otherwise

isCompileWithTracing

public boolean isCompileWithTracing()

Ask whether trace hooks are included in the compiled code.

Returns:

true if trace hooks are included, false if not.

setModuleURIResolver

public void setModuleURIResolver(ModuleURIResolver resolver)

Set a user-defined ModuleURIResolver for resolving URIs used in import module declarations in the XQuery prolog. This will override any ModuleURIResolver that was specified as part of the configuration.

Parameters:

resolver - the ModuleURIResolver to be used

getModuleURIResolver

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

Returns:

the registered ModuleURIResolver

declareNamespace

public void declareNamespace(String prefix,
                             String uri)

Declare a namespace binding as part of the static context for queries compiled using this XQueryCompiler. This binding may be overridden by a binding that appears in the query prolog. The namespace binding will form part of the static context of the query, but it will not be copied into result trees unless the prefix is actually used in an element or attribute name.

Parameters:

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.

Throws:

NullPointerException - if either the prefix or uri is null.

IllegalArgumentException - in the event of an invalid declaration of the XML namespace

setRequiredContextItemType

public void setRequiredContextItemType(ItemType type)

Declare the static type of the context item. If this type is declared, and if a context item is supplied when the query is invoked, then the context item must conform to this type (no type conversion will take place to force it into this type).

Parameters:

type - the required type of the context item

getRequiredContextItemType

public ItemType getRequiredContextItemType()

Get the required type of the context item. If no type has been explicitly declared for the context item, an instance of AnyItemType (representing the type item()) is returned.

Returns:

the required type of the context item

compile

public XQueryExecutable compile(String query)
                         throws SaxonApiException

Compile a query supplied as a string

Parameters:

query - the text of the query

Returns:

an XQueryExecutable representing the compiled query

Throws:

SaxonApiException - if the query compilation fails with a static error