net.sf.saxon.query
Class StaticQueryContext

java.lang.Object
  extended bynet.sf.saxon.query.StaticQueryContext
All Implemented Interfaces:
StaticContext

public class StaticQueryContext
extends java.lang.Object
implements StaticContext

StaticQueryContext is the implementation of StaticContext used when processing XQuery expressions. Note that some of the methods are intended for use internally by the query processor itself.

Note that a StaticQueryContext object may be initialized with context information that the query can use, but it is also modified when a query is compiled against it: for example, namespaces, variables, and functions declared in the query prolog are registered in the static context. Therefore, a StaticQueryContext object should not be used to compile more than one query.


Constructor Summary
StaticQueryContext(Configuration config)
          Create a StaticQueryContext using the default NamePool
 
Method Summary
 void addImportedSchema(java.lang.String targetNamespace)
          Add an imported schema to this static context.
protected  void bindUnboundFunctionCalls()
          Bind function calls that could not be bound when first encountered.
 VariableDeclaration bindVariable(int fingerprint)
          Bind a variable used in a query to the expression in which it is declared.
 DocumentInfo buildDocument(javax.xml.transform.Source source)
          Convenience method for building Saxon's internal representation of a source XML document.
 java.lang.String checkURIForPrefix(java.lang.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(java.io.Reader source)
          Prepare an XQuery query for subsequent evaluation.
 XQueryExpression compileQuery(java.lang.String query)
          Prepare an XQuery query for subsequent evaluation.
 void declareActiveNamespace(java.lang.String prefix, java.lang.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(java.lang.String name, java.util.Comparator comparator)
          Declare a named collation.
 void declareDefaultCollation(java.lang.String name)
          Set the default collation.
 void declareFunction(XQueryFunction function)
          Register a user-defined XQuery function
 void declarePassiveNamespace(java.lang.String prefix, java.lang.String uri, boolean explicit)
          Declare a namespace whose prefix can be used in expressions.
 void declareVariable(VariableDeclaration var)
          Declare a global variable.
 void explainGlobalFunctions()
          Output "explain" information about each declared function
 void explainGlobalVariables()
          Produce "explain" output for all global variables
protected  void fixupGlobalFunctions()
          Fixup all references to global functions.
 void fixupGlobalVariables(SlotManager globalVariableMap)
          Fixup all references to global variables.
 int[] getActiveNamespaceCodes()
          Get an array containing the namespace codes of all active namespaces.
 java.util.HashMap getAllCollations()
          Get a HashMap that maps all registered collations to Comparators.
 java.lang.String getBaseURI()
          Get the Base URI of the query, for resolving any relative URI's used in the expression.
 java.util.Comparator getCollation(java.lang.String name)
          Get a named collation.
 Configuration getConfiguration()
          Get the Configuration options
 int getConstructionMode()
          Get the current validation mode
 java.lang.String getDefaultCollationName()
          Get the name of the default collation.
 short getDefaultElementNamespace()
          Get the default XPath namespace, as a namespace URI code that can be looked up in the NamePool
 java.lang.String getDefaultFunctionNamespace()
          Get the default function namespace
 Executable getExecutable()
           
 java.util.Iterator getFunctionDefinitions()
          Get an iterator over the Functions defined in this module
 FunctionLibrary getFunctionLibrary()
          Get the function library containing all the in-scope functions available in this static context
 SlotManager getGlobalStackFrameMap()
          Get the stack frame map for global variables
 int getLineNumber()
          Get the line number of the expression within that container.
 LocationMap getLocationMap()
          Get the location map
 java.lang.String getModuleNamespace()
          Get the namespace of the current library module.
 short getModuleNamespaceCode()
          Get the namesapce code of the current library module.
 NamePool getNamePool()
          Get the NamePool used for compiling expressions
 NamespaceResolver getNamespaceResolver()
          Get a copy of the Namespace Context.
 SlotManager getStackFrameMap()
          Get the stack frame map for local variables in the "main" query expression
 java.lang.String getSystemId()
          Get the system ID of the container of the expression.
 java.lang.String getURIForPrefix(java.lang.String prefix)
          Get the URI for a prefix.
 UserFunction getUserDefinedFunction(java.lang.String uri, java.lang.String localName, int arity)
          Get the function with a given name and arity.
 java.util.Iterator getVariableDeclarations()
          Get an iterator over the variables defined in this module
 boolean isImportedSchema(java.lang.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 isPreserveNamespaces()
          Get the namespace copy mode
 void issueWarning(java.lang.String s, javax.xml.transform.SourceLocator locator)
          Issue a compile-time warning.
protected  StaticQueryContext loadModule(java.lang.String namespaceURI, java.lang.String locationURI)
          Load another query module
static StaticQueryContext loadQueryModule(Configuration config, Executable executable, java.lang.String baseURI, java.lang.String namespaceURI, java.lang.String locationURI, StaticQueryContext importer)
          Supporting method to load a query module.
 void reset()
          Reset the state of this StaticQueryContext to an uninitialized state
 void setBaseURI(java.lang.String baseURI)
          Set the Base URI of the query
 void setConfiguration(Configuration config)
          Set the Configuration options
 void setConstructionMode(int mode)
          Add a new validation mode to the stack of validation modes
 void setDefaultElementNamespace(java.lang.String uri)
          Set the default element namespace
 void setDefaultFunctionNamespace(java.lang.String defaultFunctionNamespace)
          Set the default function namespace
 void setExecutable(Executable executable)
           
 void setInheritNamespaces(boolean inherit)
          Set the namespace inheritance mode
 void setModuleNamespace(java.lang.String uri)
          Set the namespace for a library module
 void setPreserveNamespaces(boolean inherit)
          Set the namespace copy mode
 void undeclareNamespace()
          Undeclare the most recently-declared active namespace
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

StaticQueryContext

public StaticQueryContext(Configuration config)
Create a StaticQueryContext using the default NamePool

Method Detail

reset

public void reset()
Reset the state of this StaticQueryContext to an uninitialized state


setConfiguration

public void setConfiguration(Configuration config)
Set the Configuration options


getConfiguration

public Configuration getConfiguration()
Get the Configuration options

Specified by:
getConfiguration in interface StaticContext

buildDocument

public DocumentInfo buildDocument(javax.xml.transform.Source source)
                           throws XPathException
Convenience method for building Saxon's internal representation of a source XML document. The document will be built using the default NamePool, which means that any process that uses it must also use the default NamePool.

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

compileQuery

public XQueryExpression compileQuery(java.lang.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.

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.
java.lang.IllegalStateException - if the StaticQueryContext has been used to compile another query and has not been reset using reset()

compileQuery

public XQueryExpression compileQuery(java.io.Reader source)
                              throws XPathException,
                                     java.io.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.

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.
java.io.IOException - if a failure occurs reading the supplied input.
java.lang.IllegalStateException - if the StaticQueryContext has been used to compile another query and has not been reset using reset()

getExecutable

public Executable getExecutable()

setExecutable

public void setExecutable(Executable executable)

getLocationMap

public LocationMap getLocationMap()
Description copied from interface: StaticContext
Get the location map

Specified by:
getLocationMap in interface StaticContext

declarePassiveNamespace

public void declarePassiveNamespace(java.lang.String prefix,
                                    java.lang.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.
explicit -
Throws:
StaticError

declareActiveNamespace

public void declareActiveNamespace(java.lang.String prefix,
                                   java.lang.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().


undeclareNamespace

public void undeclareNamespace()
Undeclare the most recently-declared active namespace

See Also:
declareActiveNamespace(String, String)

clearPassiveNamespaces

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


getURIForPrefix

public java.lang.String getURIForPrefix(java.lang.String prefix)
                                 throws XPathException
Get the URI for a prefix. This method is used by the XQuery parser to resolve namespace prefixes.

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 java.lang.String checkURIForPrefix(java.lang.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.

Parameters:
prefix - The prefix
Returns:
the corresponding namespace URI, or null if the prefix has not been declared.

getActiveNamespaceCodes

public int[] getActiveNamespaceCodes()
Get an array containing the namespace codes of all active namespaces.


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.

Specified by:
getNamespaceResolver in interface StaticContext
Returns:
a namespace resolver.

getDefaultFunctionNamespace

public java.lang.String getDefaultFunctionNamespace()
Get the default function namespace

Specified by:
getDefaultFunctionNamespace in interface StaticContext
Returns:
the default function namespace (defaults to the fn: namespace)

setDefaultFunctionNamespace

public void setDefaultFunctionNamespace(java.lang.String defaultFunctionNamespace)
Set the default function namespace

Parameters:
defaultFunctionNamespace - The namespace to be used for unprefixed function calls

setDefaultElementNamespace

public void setDefaultElementNamespace(java.lang.String uri)
                                throws StaticError
Set the default element namespace

Throws:
StaticError

getDefaultElementNamespace

public short getDefaultElementNamespace()
Get the default XPath namespace, as a namespace URI code that can be looked up in the NamePool

Specified by:
getDefaultElementNamespace in interface StaticContext

setModuleNamespace

public void setModuleNamespace(java.lang.String uri)
Set the namespace for a library module


getModuleNamespace

public java.lang.String getModuleNamespace()
Get the namespace of the current library module.

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.

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

setInheritNamespaces

public void setInheritNamespaces(boolean inherit)
Set the namespace inheritance mode

Parameters:
inherit - true if namespaces are inherited, false if not

isInheritNamespaces

public boolean isInheritNamespaces()
Get the namespace inheritance mode

Returns:
true if namespaces are inherited, false if not

setPreserveNamespaces

public void setPreserveNamespaces(boolean inherit)
Set the namespace copy mode

Parameters:
inherit - true if namespaces are preserved, false if not

isPreserveNamespaces

public boolean isPreserveNamespaces()
Get the namespace copy mode

Returns:
true if namespaces are preserved, false if not

declareCollation

public void declareCollation(java.lang.String name,
                             java.util.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

declareDefaultCollation

public void declareDefaultCollation(java.lang.String name)
                             throws XPathException
Set the default collation. The collation that is specified must be one that has been previously registered using the declareCollation() method.

Parameters:
name - The collation name
Throws:
XPathException - if the collation name has not been registered

getCollation

public java.util.Comparator getCollation(java.lang.String name)
Get a named collation.

Specified by:
getCollation in interface StaticContext
Parameters:
name - The name of the required collation. Supply null to get the default collation.
Returns:
the collation identified by the given name, as set previously using declareCollation. Return null if no collation with this name is found.

getDefaultCollationName

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

getAllCollations

public java.util.HashMap 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.


getGlobalStackFrameMap

public SlotManager getGlobalStackFrameMap()
Get the stack frame map for global variables


declareVariable

public void declareVariable(VariableDeclaration var)
                     throws StaticError
Declare a global variable. A variable must be declared before an expression referring to it is compiled. Global variables are normally declared in the Query Prolog, but they can also be predeclared using this API.

Throws:
StaticError

fixupGlobalVariables

public void fixupGlobalVariables(SlotManager globalVariableMap)
                          throws StaticError
Fixup all references to global variables. This method is for internal use by the Query Parser only.

Throws:
StaticError

explainGlobalVariables

public void explainGlobalVariables()
Produce "explain" output for all global variables


getVariableDeclarations

public java.util.Iterator getVariableDeclarations()
Get an iterator over the variables defined in this module

Returns:
an Iterator, whose items are VariableDeclaration objects. It returns all variables known to this module including those imported from elsewhere; they can be distinguished by their namespace. The variables are returned in order of declaration.

getStackFrameMap

public SlotManager getStackFrameMap()
Get the stack frame map for local variables in the "main" query expression


getNamePool

public NamePool getNamePool()
Get the NamePool used for compiling expressions

Specified by:
getNamePool in interface StaticContext

issueWarning

public void issueWarning(java.lang.String s,
                         javax.xml.transform.SourceLocator locator)
Issue a compile-time warning. This method is used during XQuery expression compilation to output warning conditions.

Specified by:
issueWarning in interface StaticContext

setBaseURI

public void setBaseURI(java.lang.String baseURI)
Set the Base URI of the query


getSystemId

public java.lang.String getSystemId()
Get the system ID of the container of the expression. Used to construct error messages.

Specified by:
getSystemId in interface StaticContext
Returns:
the Base URI

getBaseURI

public java.lang.String getBaseURI()
Get the Base URI of the query, for resolving any relative URI's used in the expression. Used by the document() function.

Specified by:
getBaseURI in interface StaticContext
Returns:
"" always

getLineNumber

public int getLineNumber()
Get the line number of the expression within that container. Used to construct error messages.

Specified by:
getLineNumber in interface StaticContext
Returns:
-1 always

bindVariable

public VariableDeclaration 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
Throws:
StaticError

getFunctionLibrary

public FunctionLibrary getFunctionLibrary()
Get the function library containing all the in-scope functions available in this static context

Specified by:
getFunctionLibrary in interface StaticContext

declareFunction

public void declareFunction(XQueryFunction function)
                     throws StaticError
Register a user-defined XQuery function

Throws:
StaticError

bindUnboundFunctionCalls

protected void bindUnboundFunctionCalls()
                                 throws StaticError
Bind function calls that could not be bound when first encountered. These will either be forwards references to functions declared later in the query, or errors. This method is for internal use.

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

getFunctionDefinitions

public java.util.Iterator getFunctionDefinitions()
Get an iterator over the Functions defined in this module

Returns:
an Iterator, whose items are XQueryFunction objects. It returns all function known to this module including those imported from elsewhere; they can be distinguished by their namespace.

fixupGlobalFunctions

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

Throws:
XPathException

explainGlobalFunctions

public void explainGlobalFunctions()
                            throws XPathException
Output "explain" information about each declared function

Throws:
XPathException

getUserDefinedFunction

public UserFunction getUserDefinedFunction(java.lang.String uri,
                                           java.lang.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.

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

addImportedSchema

public void addImportedSchema(java.lang.String targetNamespace)
Add an imported schema to this static context.

Parameters:
targetNamespace - The target namespace of the schema to be added

isImportedSchema

public boolean isImportedSchema(java.lang.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.

setConstructionMode

public void setConstructionMode(int mode)
Add a new validation mode to the stack of validation modes


getConstructionMode

public int getConstructionMode()
Get the current validation mode


loadModule

protected StaticQueryContext loadModule(java.lang.String namespaceURI,
                                        java.lang.String locationURI)
                                 throws StaticError
Load another query module

Throws:
StaticError

loadQueryModule

public static StaticQueryContext loadQueryModule(Configuration config,
                                                 Executable executable,
                                                 java.lang.String baseURI,
                                                 java.lang.String namespaceURI,
                                                 java.lang.String locationURI,
                                                 StaticQueryContext importer)
                                          throws StaticError
Supporting method to load a query module. Used also by saxon:import-query in XSLT.

Parameters:
config - The configuration
executable - The Executation
baseURI - The base URI of the invoking module
namespaceURI - namespace of the query module to be loaded
locationURI - location hint of the query module to be loaded
importer - The importing query module (used to check for cycles)
Returns:
The StaticQueryContext representing the loaded query module
Throws:
StaticError