net.sf.saxon.query
Class StaticQueryContext

java.lang.Object
  net.sf.saxon.query.StaticQueryContext

All Implemented Interfaces:

StaticContext

public class StaticQueryContext
extends Object
implements StaticContext

StaticQueryContext is the implementation of StaticContext used when processing XQuery expressions.

The StaticQueryContext object has two different usages. The application constructs a StaticQueryContext and initializes it with information about the context, for example, default namespaces, base URI, and so on. When a query is compiled using this StaticQueryContext, the query parser makes a copy of the StaticQueryContext and uses this internally, modifying it with information obtained from the query prolog, as well as information such as namespace and variable declarations that can occur at any point in the query. The query parser does not modify the original StaticQueryContext supplied by the calling application, which may therefore be used for compiling multiple queries, serially or even in multiple threads.

This class forms part of Saxon's published XQuery API. Note that some of the methods are intended for use internally by the query processor itself: these are labelled as such. Methods that are considered stable are labelled with the JavaDoc "since" tag. The value 8.4 indicates a method introduced at or before Saxon 8.4; other values indicate the version at which the method was introduced.

In the longer term, this entire API may at some stage be superseded by a proposed standard Java API for XQuery.

Since:

8.4

Constructor Summary

StaticQueryContext(Configuration config)
Create a StaticQueryContext using a given Configuration.

StaticQueryContext(Configuration config, StaticQueryContext importer)
Create a StaticQueryContext for a library module.

Method Summary

void	addImportedNamespace(String uri) Register that this module imports a particular module namespace
void	addImportedSchema(String targetNamespace) Add an imported schema to this static context.
void	bindUnboundFunctionCalls() Bind function calls that could not be bound when first encountered.
void	bindUnboundVariables() Bind unbound variables (these are typically variables that reference another module participating in a same-namespace cycle, since local forwards references are not allowed
VariableReference	bindVariable(int fingerprint) Bind a variable used in a query to the expression in which it is declared.
DocumentInfo	buildDocument(Source source) Convenience method for building Saxon's internal representation of a source XML document.
void	checkImportedType(SequenceType importedType, Declaration declaration) Check that a SequenceType used in the definition of an imported variable or function is available in the importing module
String	checkURIForPrefix(String prefix) Get the URI for a prefix if there is one, return null if not.
void	clearPassiveNamespaces() Clear all the declared passive namespaces, except for the standard ones (xml, saxon, etc)
XQueryExpression	compileQuery(InputStream source, String encoding) Prepare an XQuery query for subsequent evaluation.
XQueryExpression	compileQuery(Reader source) Prepare an XQuery query for subsequent evaluation.
XQueryExpression	compileQuery(String query) Prepare an XQuery query for subsequent evaluation.
StaticQueryContext	copy() Make a copy of this StaticQueryContext.
void	declareActiveNamespace(String prefix, String uri) Declare an active namespace, that is, a namespace which as well as affecting the static context of the query, will also be copied to the result tree when element constructors are evaluated.
void	declareCollation(String name, Comparator comparator) Declare a named collation.
void	declareCollation(String name, StringCollator comparator) Declare a named collation.
void	declareDefaultCollation(String name) Set the default collation.
void	declareFunction(XQueryFunction function) Register a user-defined XQuery function.
void	declarePassiveNamespace(String prefix, String uri, boolean explicit) Declare a namespace whose prefix can be used in expressions.
void	declareVariable(VariableDeclaration var) Declare a global variable.
void	explainGlobalFunctions(PrintStream out) Output "explain" information about each declared function.
void	explainGlobalVariables(PrintStream out) Produce "explain" output for all global variables.
void	fixupGlobalFunctions() Fixup all references to global functions.
List	fixupGlobalVariables(SlotManager globalVariableMap) Fixup all references to global variables.
int[]	getActiveNamespaceCodes() Get an array containing the namespace codes of all active namespaces.
CollationMap	getAllCollations() Get a HashMap that maps all registered collations to Comparators.
String	getBaseURI() Get the Base URI of the query, for resolving any relative URI's used in the expression.
StringCollator	getCollation(String name) Get a named collation.
Configuration	getConfiguration() Get the Configuration options
int	getConstructionMode() Get the current validation mode
String	getDefaultCollationName() Get the name of the default collation.
String	getDefaultElementNamespace() Get the default XPath namespace for elements and types
String	getDefaultFunctionNamespace() Get the default function namespace
ErrorListener	getErrorListener() Get the ErrorListener in use for this static context
Executable	getExecutable() Get the Executable, an object representing the compiled query and its environment.
NamespaceResolver	getExternalNamespaceResolver() Get the external namespace resolver that has been registered using setExternalNamespaceResolver(), if any.
FunctionLibrary	getFunctionLibrary() Get the function library containing all the in-scope functions available in this static context (that is, the functions available in this query module).
XQueryFunctionLibrary	getGlobalFunctionLibrary()
SlotManager	getGlobalStackFrameMap() Get the stack frame map for global variables.
ImportedFunctionLibrary	getImportedFunctionLibrary()
Set	getImportedSchemaNamespaces() Get the set of imported schemas
int	getLineNumber() Get the line number of the expression within that container.
XQueryFunctionLibrary	getLocalFunctionLibrary() Get the functions declared locally within this module
LocationMap	getLocationMap() Get the LocationMap, an data structure used to identify the location of compiled expressions within the query source text.
String	getLocationURI() Get the location URI for a module
String	getModuleNamespace() Get the namespace of the current library module.
short	getModuleNamespaceCode() Get the namesapce code of the current library module.
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 on the StaticQueryContext or on the Configuration.
Iterator	getModuleVariables() Get global variables declared in this module
NamePool	getNamePool() Get the NamePool used for compiling expressions
NamespaceResolver	getNamespaceResolver() Get a copy of the Namespace Context.
ItemType	getRequiredContextItemType() Get the required type of the context item.
SlotManager	getStackFrameMap() Get the stack frame map for local variables in the "main" query expression.
String	getSystemId() Get the system ID of the container of the expression.
StaticQueryContext	getTopLevelModule(StaticQueryContext start) Get the Static Query Context for the top-level module.
String	getURIForPrefix(String prefix) Get the URI for a prefix.
UserFunction	getUserDefinedFunction(String uri, String localName, int arity) Get the function with a given name and arity.
boolean	importsNamespace(String uri) Test whether this module directly imports a particular namespace
boolean	importsNamespaceIndirectly(String uri) Test whether this module imports a particular namespace directly or indirectly
boolean	isAllowedBuiltInType(AtomicType type) Determine whether a built-in type is available in this context.
boolean	isImportedSchema(String namespace) Get the schema for a given namespace, if it has been imported
boolean	isInBackwardsCompatibleMode() Determine whether Backwards Compatible Mode is used
boolean	isInheritNamespaces() Get the namespace inheritance mode
boolean	isMainModule() Test whether this is a "main" module, in the sense of the XQuery language specification
boolean	isPreserveNamespaces() Get the namespace copy mode
void	issueWarning(String s, SourceLocator locator) Issue a compile-time warning.
boolean	isTopLevelModule() Test whether this is a "top-level" module.
Iterator	iterateImportedNamespaces() Get an iterator over all the module namespaces that this module imports
void	lookForModuleCycles(Stack referees, int lineNumber) Look for module cycles.
XPathContext	makeEarlyEvaluationContext() Construct a dynamic context for early evaluation of constant subexpressions
static StaticQueryContext	makeStaticQueryContext(String baseURI, Executable executable, StaticQueryContext importer, String query, String namespaceURI, boolean allowCycles) Supporting method to load a query module.
boolean	mayImport(String namespace) Check whether this module is allowed to import a module with namespace N.
void	reportFatalError(XPathException err) Report a fatal error in the query (via the registered ErrorListener)
void	reset() Reset the state of this StaticQueryContext to an uninitialized state
void	setBaseURI(String baseURI) Set the Base URI of the query
void	setConfiguration(Configuration config) Deprecated. This method serves no purpose, since it is not possible to change the configuration once the StaticQueryContext has been initialized.
void	setConstructionMode(int mode) Set the construction mode for this module
void	setDefaultElementNamespace(String uri) Set the default element namespace
void	setDefaultFunctionNamespace(String defaultFunctionNamespace) Set the default function namespace
void	setErrorListener(ErrorListener listener) Set the ErrorListener to be used to report compile-time errors in a query.
void	setExecutable(Executable executable) Set the executable.
void	setExternalNamespaceResolver(NamespaceResolver resolver) Set an external namespace resolver.
void	setFunctionLibraryList(FunctionLibraryList functionLibrary) Set the function library used for binding any function call appearing within the query module.
void	setInheritNamespaces(boolean inherit) Set the namespace inheritance mode
void	setLocationURI(String uri) Set the location URI for a module
void	setModuleNamespace(String uri) Set the namespace for a library module.
void	setModuleURIResolver(ModuleURIResolver resolver) Set a user-defined ModuleURIResolver for resolving URIs used in "import module" declarations in the XQuery prolog.
void	setPreserveNamespaces(boolean inherit) Set the namespace copy mode
void	setRequiredContextItemType(ItemType type) Declare the static type of the context item.
void	typeCheckGlobalVariables(List compiledVars) Get references to undeclared variables.
void	undeclareNamespace() Undeclare the most recently-declared active namespace.

Methods inherited from class java.lang.Object

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

Constructor Detail

StaticQueryContext

public StaticQueryContext(Configuration config)

Create a StaticQueryContext using a given Configuration. This creates a StaticQueryContext for a main module (that is, a module that is not a library module).

Since:

8.4

StaticQueryContext

public StaticQueryContext(Configuration config,
                          StaticQueryContext importer)

Create a StaticQueryContext for a library module.

Parameters:

importer - the module that imported this module. This may be null, in which case the library module is treated as a "top-level" library module.

Method Detail

reset

public void reset()

Reset the state of this StaticQueryContext to an uninitialized state

Since:

8.4

isTopLevelModule

public boolean isTopLevelModule()

Test whether this is a "top-level" module. This is true for a main module and also for a module directly imported into an XSLT stylesheet. It may also be true in future for independently-compiled modules

isMainModule

public boolean isMainModule()

Test whether this is a "main" module, in the sense of the XQuery language specification

mayImport

public boolean mayImport(String namespace)

Check whether this module is allowed to import a module with namespace N. Note that before calling this we have already handled the exception case where a module imports another in the same namespace (this is the only case where cycles are allowed, though as a late change to the spec they are no longer useful, since they cannot depend on each other cyclically)

getGlobalFunctionLibrary

public XQueryFunctionLibrary getGlobalFunctionLibrary()

getImportedFunctionLibrary

public ImportedFunctionLibrary getImportedFunctionLibrary()

addImportedNamespace

public void addImportedNamespace(String uri)

Register that this module imports a particular module namespace

importsNamespace

public boolean importsNamespace(String uri)

Test whether this module directly imports a particular namespace

importsNamespaceIndirectly

public boolean importsNamespaceIndirectly(String uri)

Test whether this module imports a particular namespace directly or indirectly

iterateImportedNamespaces

public Iterator iterateImportedNamespaces()

Get an iterator over all the module namespaces that this module imports

getTopLevelModule

public StaticQueryContext getTopLevelModule(StaticQueryContext start)

Get the Static Query Context for the top-level module. This will normally be a main module, but in the case of saxon:import-query it will be the library module that is imported into the stylesheet

copy

public StaticQueryContext copy()

Make a copy of this StaticQueryContext. The StaticQueryContext that is constructed by a user application and passed to Saxon when a query is compiled should not be modified by the query compiler. Saxon therefore makes a copy of the StaticQueryContext and uses this copy internally, to capture any changes to the StaticQueryContext defined in the query prolog.

Returns:

a copy of this StaticQueryContext

setConfiguration

public void setConfiguration(Configuration config)

Deprecated. This method serves no purpose, since it is not possible to change the configuration once the StaticQueryContext has been initialized.

Set the Configuration options

Throws:

IllegalArgumentException - if the configuration supplied is different from the existing configuration

Since:

8.4

getConfiguration

public Configuration getConfiguration()

Get the Configuration options

Specified by:

getConfiguration in interface StaticContext

Since:

8.4

makeEarlyEvaluationContext

public XPathContext makeEarlyEvaluationContext()

Construct a dynamic context for early evaluation of constant subexpressions

Specified by:

makeEarlyEvaluationContext in interface StaticContext

buildDocument

public DocumentInfo buildDocument(Source source)
                           throws XPathException

Convenience method for building Saxon's internal representation of a source XML document. The document will be built using Configuration (and NamePool) associated with this StaticQueryContext.

This method is retained for backwards compatibility; however, it is merely a wrapper around the method Configuration.buildDocument(javax.xml.transform.Source), which should be called in preference.

Parameters:

source - Any javax.xml.transform.Source object representing the document against which queries will be executed. Note that a Saxon DocumentInfo (indeed any NodeInfo) can be used as a Source. To use a third-party DOM Document as a source, create an instance of DOMSource to wrap it.

For additional control over the way in which the source document is processed, supply an AugmentedSource object and set appropriate options on the object.

Returns:

the DocumentInfo representing the root node of the resulting document object.

Throws:

XPathException

Since:

8.4

compileQuery

public XQueryExpression compileQuery(String query)
                              throws XPathException

Prepare an XQuery query for subsequent evaluation. The source text of the query is supplied as a String. The base URI of the query is taken from the static context, and defaults to the current working directory.

Note that this interface makes caller responsible for decoding the query and presenting it as a string of characters. This means it is likely that any encoding specified in the query prolog will be ignored.

Parameters:

query - The XQuery query to be evaluated, supplied as a string.

Returns:

an XQueryExpression object representing the prepared expression

Throws:

XPathException - if the syntax of the expression is wrong, or if it references namespaces, variables, or functions that have not been declared, or contains other static errors.

Since:

8.4

compileQuery

public XQueryExpression compileQuery(Reader source)
                              throws XPathException,
                                     IOException

Prepare an XQuery query for subsequent evaluation. The Query is supplied in the form of a Reader. The base URI of the query is taken from the static context, and defaults to the current working directory.

Note that this interface makes the Reader responsible for decoding the query and presenting it as a stream of characters. This means it is likely that any encoding specified in the query prolog will be ignored. Also, some implementations of Reader cannot handle a byte order mark.

Parameters:

source - A Reader giving access to the text of the XQuery query to be compiled.

Returns:

an XPathExpression object representing the prepared expression.

Throws:

XPathException - if the syntax of the expression is wrong, or if it references namespaces, variables, or functions that have not been declared, or any other static error is reported.

IOException - if a failure occurs reading the supplied input.

Since:

8.4

compileQuery

public XQueryExpression compileQuery(InputStream source,
                                     String encoding)
                              throws XPathException,
                                     IOException

Prepare an XQuery query for subsequent evaluation. The Query is supplied in the form of a InputStream, with an optional encoding. If the encoding is not specified, the query parser attempts to obtain the encoding by inspecting the input stream: it looks specifically for a byte order mark, and for the encoding option in the version declaration of an XQuery prolog. The encoding defaults to UTF-8. The base URI of the query is taken from the static context, and defaults to the current working directory.

Parameters:

source - An InputStream giving access to the text of the XQuery query to be compiled, as a stream of octets

encoding - The encoding used to translate characters to octets in the query source. The parameter may be null: in this case the query parser attempts to infer the encoding by inspecting the source, and if that fails, it assumes UTF-8 encoding

Returns:

an XPathExpression object representing the prepared expression.

Throws:

XPathException - if the syntax of the expression is wrong, or if it references namespaces, variables, or functions that have not been declared, or any other static error is reported.

IOException - if a failure occurs reading the supplied input.

Since:

8.5

getExecutable

public Executable getExecutable()

Get the Executable, an object representing the compiled query and its environment.

This method is intended for internal use only.

Returns:

the Executable

setExecutable

public void setExecutable(Executable executable)

Set the executable.

This method is intended for internal use only.

Parameters:

executable - the Executable

getLocationMap

public LocationMap getLocationMap()

Get the LocationMap, an data structure used to identify the location of compiled expressions within the query source text.

This method is intended for internal use only.

Specified by:

getLocationMap in interface StaticContext

Returns:

the LocationMap

declarePassiveNamespace

public void declarePassiveNamespace(String prefix,
                                    String uri,
                                    boolean explicit)
                             throws StaticError

Declare a namespace whose prefix can be used in expressions. This is a passive namespace, it won't be copied into the result tree. Passive namespaces are never undeclared, and active namespaces override them.

Parameters:

prefix - The namespace prefix. Must not be null.

uri - The namespace URI. Must not be null. The value "" (zero-length string) is used to undeclare a namespace; it is not an error if there is no existing binding for the namespace prefix.

explicit - This parameter is set to true when Saxon calls the method internally to define a namespace declared within the query prolog. It should normally be set to false in the case of a call from a user application.

Throws:

StaticError

Since:

8.4

declareActiveNamespace

public void declareActiveNamespace(String prefix,
                                   String uri)

Declare an active namespace, that is, a namespace which as well as affecting the static context of the query, will also be copied to the result tree when element constructors are evaluated. When searching for a prefix-URI binding, active namespaces are searched first, then passive namespaces. Active namespaces may be undeclared (in reverse sequence) using undeclareNamespace().

This method is intended for internal use only.

undeclareNamespace

public void undeclareNamespace()

Undeclare the most recently-declared active namespace. This method is called when a namespace declaration goes out of scope (while processing an element end tag). It is NOT called when an XML 1.1-style namespace undeclaration is encountered.

This method is intended for internal use only.

See Also:

declareActiveNamespace(String, String)

clearPassiveNamespaces

public void clearPassiveNamespaces()

Clear all the declared passive namespaces, except for the standard ones (xml, saxon, etc)

Since:

8.4

setExternalNamespaceResolver

public void setExternalNamespaceResolver(NamespaceResolver resolver)

Set an external namespace resolver. If a namespace prefix cannot be resolved using any other mechanism, then as a last resort the external namespace resolver is called to obtain a URI for the given prefix.

Note that the external namespace resolver is used only for namespace prefixes that are resolved at compile time. Where namespace prefixes are resolved at run-time (which happens very rarely with XQuery: the only case is to resolve the computed name used in a computed element or attribute constructor), the external namespace resolver is not invoked.

Although the supplied object must implement the NamespaceResolver interface, the only method actually used is the method NamespaceResolver.getURIForPrefix(String, boolean). Other methods may throw an UnsupportedOperationException.

getExternalNamespaceResolver

public NamespaceResolver getExternalNamespaceResolver()

Get the external namespace resolver that has been registered using setExternalNamespaceResolver(), if any.

getURIForPrefix

public String getURIForPrefix(String prefix)
                       throws XPathException

Get the URI for a prefix. This method is used by the XQuery parser to resolve namespace prefixes.

This method is intended primarily for internal use.

Specified by:

getURIForPrefix in interface StaticContext

Parameters:

prefix - The prefix

Returns:

the corresponding namespace URI

Throws:

XPathException - if the prefix has not been declared

checkURIForPrefix

public String checkURIForPrefix(String prefix)

Get the URI for a prefix if there is one, return null if not. This method is used by the XQuery parser to resolve namespace prefixes.

This method is intended primarily for internal use.

Parameters:

prefix - The prefix. Supply "" to obtain the default namespace.

Returns:

the corresponding namespace URI, or null if the prefix has not been declared. If the prefix is "" and the default namespace is the non-namespace, return "".

getActiveNamespaceCodes

public int[] getActiveNamespaceCodes()

Get an array containing the namespace codes of all active namespaces.

This method is for internal use only.

getNamespaceResolver

public NamespaceResolver getNamespaceResolver()

Get a copy of the Namespace Context. This method is used internally by the query parser when a construct is encountered that needs to save the namespace context for use at run-time.

This method is for internal use only.

Specified by:

getNamespaceResolver in interface StaticContext

Returns:

a namespace resolver.

getDefaultFunctionNamespace

public String getDefaultFunctionNamespace()

Get the default function namespace

Specified by:

getDefaultFunctionNamespace in interface StaticContext

Returns:

the default function namespace (defaults to the fn: namespace)

Since:

8.4

setDefaultFunctionNamespace

public void setDefaultFunctionNamespace(String defaultFunctionNamespace)

Set the default function namespace

Parameters:

defaultFunctionNamespace - The namespace to be used for unprefixed function calls

Since:

8.4

setDefaultElementNamespace

public void setDefaultElementNamespace(String uri)
                                throws StaticError

Set the default element namespace

Throws:

StaticError

Since:

8.4

getDefaultElementNamespace

public String getDefaultElementNamespace()

Get the default XPath namespace for elements and types

Specified by:

getDefaultElementNamespace in interface StaticContext

Since:

8.9 Modified in 8.9 to return the namespace URI as a string rather than an integer code

setModuleNamespace

public void setModuleNamespace(String uri)

Set the namespace for a library module.

This method is for internal use only.

getModuleNamespace

public String getModuleNamespace()

Get the namespace of the current library module.

This method is intended primarily for internal use.

Returns:

the module namespace, or null if this is a main module

getModuleNamespaceCode

public short getModuleNamespaceCode()

Get the namesapce code of the current library module.

This method is intended primarily for internal use.

Returns:

the module namespace, or null if this is a main module

setLocationURI

public void setLocationURI(String uri)

Set the location URI for a module

getLocationURI

public String getLocationURI()

Get the location URI for a module

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 be used for resolving URIs in XQuery "import module" declarations, overriding any ModuleURIResolver that was specified as part of the configuration.

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 on the StaticQueryContext or on the Configuration.

setInheritNamespaces

public void setInheritNamespaces(boolean inherit)

Set the namespace inheritance mode

Parameters:

inherit - true if namespaces are inherited, false if not

Since:

8.4

isInheritNamespaces

public boolean isInheritNamespaces()

Get the namespace inheritance mode

Returns:

true if namespaces are inherited, false if not

Since:

8.4

setPreserveNamespaces

public void setPreserveNamespaces(boolean inherit)

Set the namespace copy mode

Parameters:

inherit - true if namespaces are preserved, false if not

Since:

8.4

isPreserveNamespaces

public boolean isPreserveNamespaces()

Get the namespace copy mode

Returns:

true if namespaces are preserved, false if not

Since:

8.4

declareCollation

public void declareCollation(String name,
                             Comparator comparator)

Declare a named collation. Collations are only available in a query if this method has been called externally to declare the collation and associate it with an implementation, in the form of a Java Comparator. The default collation is the Unicode codepoint collation, unless otherwise specified.

Parameters:

name - The name of the collation (technically, a URI)

comparator - The Java Comparator used to implement the collating sequence

Since:

8.4.

declareCollation

public void declareCollation(String name,
                             StringCollator comparator)

Declare a named collation. Collations are only available in a query if this method has been called externally to declare the collation and associate it with an implementation, in the form of a Java StringCollator. The default collation is the Unicode codepoint collation, unless otherwise specified.

Parameters:

name - The name of the collation (technically, a URI)

comparator - The Java Comparator used to implement the collating sequence

Since:

8.9.

declareDefaultCollation

public void declareDefaultCollation(String name)

Set the default collation.

Parameters:

name - The collation name, as specified in the query prolog. The name is not validated until it is used.

Since:

8.4. Changed in 8.6 so it no longer validates the collation name: this is because the base URI is not necessarily known at the point where the default collation is declared.

getCollation

public StringCollator getCollation(String name)

Get a named collation.

Specified by:

getCollation in interface StaticContext

Parameters:

name - the name of the collation, as an absolute URI

Returns:

the collation identified by the given name, as set previously using declareCollation. If no collation with this name has been declared, the method calls the CollationURIResolver to locate a collation with this name. Return null if no collation with this name is found.

Since:

8.4

getDefaultCollationName

public String getDefaultCollationName()

Get the name of the default collation.

Specified by:

getDefaultCollationName in interface StaticContext

Returns:

the name of the default collation; or the name of the codepoint collation if no default collation has been defined. The name is returned in the form it was specified; that is, it is not yet resolved against the base URI. (This is because the base URI declaration can follow the default collation declaration in the query prolog.) If no default collation has been specified, the "default default" (that is, the Unicode codepoint collation) is returned.

Since:

8.4

getAllCollations

public CollationMap getAllCollations()

Get a HashMap that maps all registered collations to Comparators. Note that this returns a snapshot copy of the data held by the static context. This method is provided for internal use by the query processor.

This method is intended for internal use.

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 context item type

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.

getGlobalStackFrameMap

public SlotManager getGlobalStackFrameMap()

Get the stack frame map for global variables.

This method is intended for internal use.

declareVariable

public void declareVariable(VariableDeclaration var)
                     throws StaticError

Declare a global variable. A variable must normally be declared before an expression referring to it is compiled, but there are exceptions where a set of modules in the same namespace import each other cyclically. Global variables are normally declared in the Query Prolog, but they can also be predeclared using this API. All global variables are held in the StaticQueryContext for the main module. The fact that a global variable is present therefore does not mean that it is visible: there are two additional conditions (a) the namespace must be imported into the module where the reference appears, and (b) the declaration must not be in the same module and textually after the reference.

Note that the same VariableDeclation object cannot be used with more than one query. This is because the VariableDeclaration is modified internally to hold a list of references to all the places where the variable is used.

Throws:

StaticError

Since:

8.4

fixupGlobalVariables

public List fixupGlobalVariables(SlotManager globalVariableMap)
                          throws StaticError

Fixup all references to global variables.

This method is for internal use by the Query Parser only.

Throws:

StaticError

lookForModuleCycles

public void lookForModuleCycles(Stack referees,
                                int lineNumber)
                         throws XPathException

Look for module cycles. This is a restriction introduced in the PR specification because of difficulties in defining the formal semantics.

[Definition: A module M1 directly depends on another module M2 (different from M1) if a variable or function declared in M1 depends on a variable or function declared in M2.] It is a static error [err:XQST0093] to import a module M1 if there exists a sequence of modules M1 ... Mi ... M1 such that each module directly depends on the next module in the sequence (informally, if M1 depends on itself through some chain of module dependencies.)

Throws:

XPathException

getModuleVariables

public Iterator getModuleVariables()

Get global variables declared in this module

Returns:

an Iterator whose items are GlobalVariableDefinition objects

typeCheckGlobalVariables

public void typeCheckGlobalVariables(List compiledVars)
                              throws StaticError

Get references to undeclared variables. return a list of XPathException objects, one for each undeclared variable

Throws:

StaticError

explainGlobalVariables

public void explainGlobalVariables(PrintStream out)

Produce "explain" output for all global variables.

This method is intended primarily for internal use.

getStackFrameMap

public SlotManager getStackFrameMap()

Get the stack frame map for local variables in the "main" query expression.

This method is intended for internal use only.

getNamePool

public NamePool getNamePool()

Get the NamePool used for compiling expressions

Specified by:

getNamePool in interface StaticContext

Since:

8.4

issueWarning

public void issueWarning(String s,
                         SourceLocator locator)

Issue a compile-time warning. This method is used during XQuery expression compilation to output warning conditions.

This method is intended for internal use only.

Specified by:

issueWarning in interface StaticContext

setBaseURI

public void setBaseURI(String baseURI)

Set the Base URI of the query

Since:

8.4

getSystemId

public String getSystemId()

Get the system ID of the container of the expression. Used to construct error messages. Note that the systemID and the Base URI are currently identical, but they might be distinguished in the future.

Specified by:

getSystemId in interface StaticContext

Returns:

the Base URI

Since:

8.4

getBaseURI

public String getBaseURI()

Get the Base URI of the query, for resolving any relative URI's used in the expression. Note that the systemID and the Base URI are currently identical, but they might be distinguished in the future. Used by the document() function.

Specified by:

getBaseURI in interface StaticContext

Returns:

the base URI of the query

Since:

8.4

getLineNumber

public int getLineNumber()

Get the line number of the expression within that container. Used to construct error messages. This method is provided to satisfy the StaticContext interface, but the value is meaningful only for XPath expressions within a document such as a stylesheet.

Specified by:

getLineNumber in interface StaticContext

Returns:

-1 always

bindVariable

public VariableReference bindVariable(int fingerprint)
                               throws StaticError

Bind a variable used in a query to the expression in which it is declared.

This method is provided for use by the XQuery parser, and it should not be called by the user of the API, or overridden, unless variables are to be declared using a mechanism other than the declareVariable method of this class.

Specified by:

bindVariable in interface StaticContext

Parameters:

fingerprint - the name of the variable

Returns:

a VariableReference representing the variable reference, suitably initialized to refer to the corresponding variable declaration

Throws:

StaticError

setFunctionLibraryList

public void setFunctionLibraryList(FunctionLibraryList functionLibrary)

Set the function library used for binding any function call appearing within the query module.

This method is available for use by advanced applications. The details of the FunctionLibrary interface are subject to change. Applications using this interface take responsibility for ensuring that the results conform to the constraints imposed by the XQuery language specification, for example that one function within a query module can call other functions defined in the same query module.

Parameters:

functionLibrary - the FunctionLibrary to be used. This will typically be a FunctionLibraryList; in most cases it will be a slightly modified copy of a FunctionLibraryList constructed by the system and obtained using the getFunctionLibrary() method.

See Also:

FunctionLibraryList

getFunctionLibrary

public FunctionLibrary getFunctionLibrary()

Get the function library containing all the in-scope functions available in this static context (that is, the functions available in this query module).

This method is provided for use by advanced applications. The details of the interface are subject to change.

Specified by:

getFunctionLibrary in interface StaticContext

Returns:

the FunctionLibrary used. For XQuery, this will always be a FunctionLibraryList.

See Also:

FunctionLibraryList

getLocalFunctionLibrary

public XQueryFunctionLibrary getLocalFunctionLibrary()

Get the functions declared locally within this module

declareFunction

public void declareFunction(XQueryFunction function)
                     throws StaticError

Register a user-defined XQuery function.

This method is intended for internal use only.

Throws:

StaticError

bindUnboundFunctionCalls

public void bindUnboundFunctionCalls()
                              throws XPathException

Bind function calls that could not be bound when first encountered. These will either be forwards references to functions declared later in the same query module, or in modules that are being imported recursively, or errors.

This method is for internal use only.

Throws:

StaticError - if a function call refers to a function that has not been declared

XPathException

fixupGlobalFunctions

public void fixupGlobalFunctions()
                          throws XPathException

Fixup all references to global functions. This method is called on completion of query parsing. Each XQueryFunction is required to bind all references to that function to the object representing the run-time executable code of the function.

This method is for internal use only.

Throws:

XPathException

explainGlobalFunctions

public void explainGlobalFunctions(PrintStream out)
                            throws XPathException

Output "explain" information about each declared function.

This method is intended primarily for internal use.

Throws:

XPathException

getUserDefinedFunction

public UserFunction getUserDefinedFunction(String uri,
                                           String localName,
                                           int arity)

Get the function with a given name and arity. This method is provided so that XQuery functions can be called directly from a Java application. Note that there is no type checking or conversion of arguments when this is done: the arguments must be provided in exactly the form that the function signature declares them.

Parameters:

uri - the uri of the function name

localName - the local part of the function name

arity - the number of arguments.

Since:

8.4

bindUnboundVariables

public void bindUnboundVariables()
                          throws XPathException

Bind unbound variables (these are typically variables that reference another module participating in a same-namespace cycle, since local forwards references are not allowed

Throws:

XPathException

isInBackwardsCompatibleMode

public boolean isInBackwardsCompatibleMode()

Determine whether Backwards Compatible Mode is used

Specified by:

isInBackwardsCompatibleMode in interface StaticContext

Returns:

false; XPath 1.0 compatibility mode is not supported in XQuery

Since:

8.4

addImportedSchema

public void addImportedSchema(String targetNamespace)

Add an imported schema to this static context. A query module can reference types in a schema provided two conditions are satisfied: the schema containing those types has been loaded into the Configuration, and the target namespace has been imported by this query module. This method achieves the second of these conditions. It does not cause the schema to be loaded.

Parameters:

targetNamespace - The target namespace of the schema to be added

Since:

8.4

isImportedSchema

public boolean isImportedSchema(String namespace)

Get the schema for a given namespace, if it has been imported

Specified by:

isImportedSchema in interface StaticContext

Parameters:

namespace - The namespace of the required schema. Supply "" for a no-namespace schema.

Returns:

The schema if found, or null if not found.

Since:

8.4

getImportedSchemaNamespaces

public Set getImportedSchemaNamespaces()

Get the set of imported schemas

Specified by:

getImportedSchemaNamespaces in interface StaticContext

Returns:

a Set, the set of URIs representing the names of imported schemas

isAllowedBuiltInType

public boolean isAllowedBuiltInType(AtomicType type)

Determine whether a built-in type is available in this context. This method caters for differences between host languages as to which set of types are built in.

Specified by:

isAllowedBuiltInType in interface StaticContext

Parameters:

type - the supposedly built-in type. This will always be a type in the XS or XDT namespace.

Returns:

true if this type can be used in this static context

setConstructionMode

public void setConstructionMode(int mode)

Set the construction mode for this module

Parameters:

mode - one of Validation.STRIP, Validation.PRESERVE

Since:

8.4

getConstructionMode

public int getConstructionMode()

Get the current validation mode

Returns:

one of Validation.STRIP, Validation.PRESERVE

Since:

8.4

makeStaticQueryContext

public static StaticQueryContext makeStaticQueryContext(String baseURI,
                                                        Executable executable,
                                                        StaticQueryContext importer,
                                                        String query,
                                                        String namespaceURI,
                                                        boolean allowCycles)
                                                 throws StaticError

Supporting method to load a query module. Used also by saxon:import-query in XSLT.

This method is intended for internal use only.

Parameters:

baseURI - The base URI and location URI of the module

executable - The Executable

importer - The importing query module (used to check for cycles). This is null when loading a query module from XSLT.

query - The text of the query, after decoding and normalizing line endings

namespaceURI - namespace of the query module to be loaded

Returns:

The StaticQueryContext representing the loaded query module

Throws:

StaticError

setErrorListener

public void setErrorListener(ErrorListener listener)

Set the ErrorListener to be used to report compile-time errors in a query. This will also be the default for the run-time error listener used to report dynamic errors

getErrorListener

public ErrorListener getErrorListener()

Get the ErrorListener in use for this static context

reportFatalError

public void reportFatalError(XPathException err)

Report a fatal error in the query (via the registered ErrorListener)

checkImportedType

public void checkImportedType(SequenceType importedType,
                              Declaration declaration)
                       throws StaticError

Check that a SequenceType used in the definition of an imported variable or function is available in the importing module

Throws:

StaticError