StaticQueryContext contains information used to build a StaticContext for use when processing XQuery
expressions.
Despite its name,
StaticQueryContext
no longer implements the
StaticContext
interface, which means it cannot be used directly by Saxon when parsing a query. Instead it is first copied
to create a
QueryModule
object, which does implement the
StaticContext
interface.
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. 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.
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(Source)
, which should be called in preference.
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.
- the DocumentInfo representing the root node of the resulting document object.
clearNamespaces
public void clearNamespaces()
Clear all the user-declared namespaces
clearPassiveNamespaces
public void clearPassiveNamespaces()
since 9.0 - use clearNamespaces()
Clear all the declared passive namespaces, except for the standard ones (xml, saxon, etc)
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.
source
- An InputStream giving access to the text of the XQuery query to be compiled, as a stream
of octetsencoding
- 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
- an XPathExpression object representing the prepared expression.
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.
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.
source
- A Reader giving access to the text of the XQuery query to be compiled.
- an XPathExpression object representing the prepared expression.
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.
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.
query
- The XQuery query to be evaluated, supplied as a string.
- an XQueryExpression object representing the prepared expression
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.
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.
name
- The name of the collation (technically, a URI)comparator
- The Java Comparator used to implement the collating sequence
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.
name
- The name of the collation (technically, a URI)comparator
- The Java Comparator used to implement the collating sequence
declareDefaultCollation
public void declareDefaultCollation(String name)
Set the default collation.
name
- The collation name, as specified in the query prolog. The name
is not validated until it is used.
- 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.
declareNamespace
public void declareNamespace(String prefix,
String uri)
Declare a namespace whose prefix can be used in expressions. This is
equivalent to declaring a prefix in the Query prolog.
Any namespace declared in the Query prolog overrides a namespace declared using
this API.
prefix
- The namespace prefix. Must not be null. Setting this to "" means that the
namespace will be used as the default namespace for elements and types.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.
declarePassiveNamespace
public void declarePassiveNamespace(String prefix,
String uri,
boolean explicit)
throws XPathException
since 9.0. Use declareNamespace(String,String)
Declare a namespace whose prefix can be used in expressions. This is
equivalent to declaring a prefix in the Query prolog. The term "passive"
was a term from a draft XQuery proposal indicating a namespace that won't
be copied into the result tree. Passive namespaces are never undeclared.
Any namespace declared in the Query prolog overrides a namespace declared using
this API.
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
- Must be false (the value true was previously reserved for internal use, but is
no longer permitted)
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.
- the CollationMap containing all the collations defined in this static context
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.
- the base URI of the query
getCollation
public StringCollator getCollation(String name)
Get a named collation.
name
- the name of the collation, as an absolute URI
- 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.
getCollationMap
public CollationMap getCollationMap()
Get the collation map
- the collation map, which identifies all the known collations
getConfiguration
public Configuration getConfiguration()
Get the Configuration options
getConstructionMode
public int getConstructionMode()
Get the current construction mode
getDefaultCollationName
public String getDefaultCollationName()
Get the name of the default collation.
- 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.
getDefaultElementNamespace
public String getDefaultElementNamespace()
Get the default namespace for elements and types
- the namespace URI to be used as the default namespace for elements and types
- 8.9 Modified in 8.9 to return the namespace URI as a string rather than an integer code
getDefaultFunctionNamespace
public String getDefaultFunctionNamespace()
Get the default function namespace
- the default function namespace (defaults to the fn: namespace)
getErrorListener
public ErrorListener getErrorListener()
Get the ErrorListener in use for this static context
- the registered ErrorListener
getExecutable
public Executable getExecutable()
Get the executable containing this query
- the executable (or null if not set)
getExternalNamespaceResolver
public NamespaceResolver getExternalNamespaceResolver()
Get the external namespace resolver that has been registered using
setExternalNamespaceResolver(), if any.
- the external namespace resolver
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.
- the registered ModuleURIResolver
getNamePool
public NamePool getNamePool()
Get the NamePool used for compiling expressions
getNamespaceForPrefix
public String getNamespaceForPrefix(String prefix)
Get the namespace URI for a given prefix, which must have been declared using the method
declareNamespace(String,String)
. Note that this method will not call the external namespace resolver
to resolve the prefix.
prefix
- the namespace prefix, or "" to represent the null prefix
- the namespace URI. Returns "" to represent the non-namespace,
null to indicate that the prefix has not been declared
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.
- the required type of the context item
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.
getUserDeclaredNamespaces
protected HashMap getUserDeclaredNamespaces()
Get the map of user-declared namespaces
- the user-declared namespaces
isCompileWithTracing
public boolean isCompileWithTracing()
Ask whether compile-time generation of trace code was requested
- true if compile-time generation of code was requested
isEmptyLeast
public boolean isEmptyLeast()
Ask what is the option for where an empty sequence appears in the collation order, if not otherwise
specified in the "order by" clause
- true if the empty sequence is considered less than any other value (the default),
false if it is considered greater than any other value
isGeneratingJavaCode
public boolean isGeneratingJavaCode()
Ask whether this query is to be optimized with a view to generating Java code.
This inhibits some rewrites to constructs for which code generation is not possible.
- true if Java code is to be generated as the final output
isInheritNamespaces
public boolean isInheritNamespaces()
Get the namespace inheritance mode
- true if namespaces are inherited, false if not
isPreserveBoundarySpace
public boolean isPreserveBoundarySpace()
Ask whether the policy for boundary space is "preserve" or "strip"
- true if the policy is to preserve boundary space, false if it is to strip it
isPreserveNamespaces
public boolean isPreserveNamespaces()
Get the namespace copy mode
- true if namespaces are preserved, false if not
iterateDeclaredPrefixes
public Iterator iterateDeclaredPrefixes()
- an iterator that returns the namespace prefixes that have been explicitly declared, as
strings. The default namespace for elements and types will be included, using the prefix "".
reset
public void reset()
Reset the state of this StaticQueryContext to an uninitialized state
setBaseURI
public void setBaseURI(String baseURI)
Set the Base URI of the query
baseURI
- the base URI of the query
setCompileWithTracing
public void setCompileWithTracing(boolean trace)
Request compile-time generation of trace code (or not)
trace
- true if compile-time generation of trace code is required
setConfiguration
public void setConfiguration(Configuration config)
Set the Configuration options
config
- the Saxon Configuration
setConstructionMode
public void setConstructionMode(int mode)
Set the construction mode for this module
setDefaultElementNamespace
public void setDefaultElementNamespace(String uri)
throws XPathException
Set the default element namespace
uri
- the namespace URI to be used as the default namespace for elements and types
setDefaultFunctionNamespace
public void setDefaultFunctionNamespace(String defaultFunctionNamespace)
Set the default function namespace
defaultFunctionNamespace
- The namespace to be used for unprefixed function calls
setEmptyLeast
public void setEmptyLeast(boolean least)
Set the option for where an empty sequence appears in the collation order, if not otherwise
specified in the "order by" clause
least
- true if the empty sequence is considered less than any other value (the default),
false if it is considered greater than any other value
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
listener
- the ErrorListener to be used
setExecutable
public void setExecutable(Executable executable)
Set the Executable to contain this query. Normally a query constitutes its own Executable,
and the executable will then be created automatically. This method is used when the query is to
share the same executable as a host program, specifically, an XSLT stylesheet that imports the
query.
executable
- the executable
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.
Changed in Saxon 9.0 so that the namespaces resolved by the external namespace resolver
are available at run-time, just like namespaces declared in the query prolog. In consequence,
the supplied NamespaceResolver must now implement the
NamespaceResolver.iteratePrefixes()
method.
resolver
- the external namespace resolver
setGeneratingJavaCode
public void setGeneratingJavaCode(boolean generateCode)
Indicate that the query should be optimized with a view to generating Java code.
This inhibits some rewrites to constructs for which code generation is not possible.
generateCode
- true if Java code is to be generated as the final output
setInheritNamespaces
public void setInheritNamespaces(boolean inherit)
Set the namespace inheritance mode
inherit
- true if namespaces are inherited, 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 be used for resolving URIs in XQuery "import module" declarations, overriding
any ModuleURIResolver that was specified as part of the configuration.
resolver
- the ModuleURIResolver to be used
setPreserveBoundarySpace
public void setPreserveBoundarySpace(boolean preserve)
Set the policy for preserving boundary space
preserve
- true if boundary space is to be preserved, false if it is to be stripped
setPreserveNamespaces
public void setPreserveNamespaces(boolean inherit)
Set the namespace copy mode
inherit
- true if namespaces are preserved, false if not
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).
type
- the required type of the context item