net.sf.saxon.query
public class StaticQueryContext extends Object
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.
Since: 8.4
Constructor Summary | |
---|---|
protected | StaticQueryContext()
Private constructor used when copying a context |
StaticQueryContext(Configuration config)
Create a StaticQueryContext using a given Configuration. | |
StaticQueryContext(Configuration config, boolean initial)
Create a StaticQueryContext using a given Configuration. | |
StaticQueryContext(StaticQueryContext c)
Create a copy of a supplied StaticQueryContext |
Method Summary | |
---|---|
DocumentInfo | buildDocument(Source source)
Convenience method for building Saxon's internal representation of a source XML
document. |
void | clearDeclaredGlobalVariables()
Clear all declared global variables |
void | clearNamespaces()
Clear all the user-declared namespaces
|
void | clearPassiveNamespaces()
Clear all the declared passive namespaces, except for the standard ones (xml, saxon, etc)
|
QueryLibrary | compileLibrary(String query)
Compile an XQuery library module for subsequent evaluation. |
QueryLibrary | compileLibrary(Reader source)
Prepare an XQuery library module for subsequent evaluation. |
QueryLibrary | compileLibrary(InputStream source, String encoding)
Prepare an XQuery library module for subsequent evaluation. |
XQueryExpression | compileQuery(String query)
Prepare an XQuery query for subsequent evaluation. |
XQueryExpression | compileQuery(Reader source)
Prepare an XQuery query for subsequent evaluation. |
XQueryExpression | compileQuery(InputStream source, String encoding)
Prepare an XQuery query for subsequent evaluation. |
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 | declareGlobalVariable(StructuredQName qName, SequenceType type, ValueRepresentation value, boolean external)
Declare a global variable. |
void | declareNamespace(String prefix, String uri)
Declare a namespace whose prefix can be used in expressions. |
void | declarePassiveNamespace(String prefix, String uri, boolean explicit)
Declare a namespace whose prefix can be used in expressions. |
CollationMap | getAllCollations()
Get a CollationMap 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. |
CollationMap | getCollationMap()
Get the collation map |
Configuration | getConfiguration()
Get the Configuration options |
int | getConstructionMode()
Get the current construction mode
|
String | getDefaultCollationName()
Get the name of the default collation.
|
String | getDefaultElementNamespace()
Get the default 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 containing this query |
NamespaceResolver | getExternalNamespaceResolver()
Get the external namespace resolver that has been registered using
setExternalNamespaceResolver(), if any. |
String | getLanguageVersion()
Get the language version |
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. |
NamePool | getNamePool()
Get the NamePool used for compiling expressions |
String | getNamespaceForPrefix(String prefix)
Get the namespace URI for a given prefix, which must have been declared using the method
StaticQueryContext. |
ItemType | getRequiredContextItemType()
Get the required type of the context item. |
String | getSystemId()
Get the system ID of the container of the expression. |
protected HashMap<String,String> | getUserDeclaredNamespaces()
Get the map of user-declared namespaces |
boolean | isCompileWithTracing()
Ask whether compile-time generation of trace code was requested |
boolean | isEmptyLeast()
Ask where an empty sequence should appear in the collation order, if not otherwise
specified in the "order by" clause |
boolean | isGeneratingJavaCode()
Ask whether this query is to be optimized with a view to generating Java code.
|
boolean | isInheritNamespaces()
Get the namespace inheritance mode
|
boolean | isPreserveBoundarySpace()
Ask whether the policy for boundary space is "preserve" or "strip" |
boolean | isPreserveNamespaces()
Get the namespace copy mode
|
boolean | isUpdating()
Ask whether XQuery Update is allowed |
boolean | isUpdatingEnabled()
Ask whether the query is allowed to be updating |
Iterator | iterateDeclaredGlobalVariables()
Iterate over all the declared global variables |
Iterator<String> | iterateDeclaredPrefixes()
Get the namespace prefixes that have been declared using the method |
protected QueryParser | newQueryParser(boolean updating, String languageVersion)
Get a new QueryParser
|
void | reset()
Reset the state of this StaticQueryContext to an uninitialized state
|
void | setBaseURI(String baseURI)
Set the Base URI of the query |
void | setCompileWithTracing(boolean trace)
Request compile-time generation of trace code (or not) |
void | setConfiguration(Configuration config)
Set the Configuration options |
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 | 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 |
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 to contain this query. |
void | setExternalNamespaceResolver(NamespaceResolver resolver)
Set an external namespace resolver. |
void | setGeneratingJavaCode(boolean generateCode)
Indicate that the query should be optimized with a view to generating Java code.
|
void | setInheritNamespaces(boolean inherit)
Set the namespace inheritance mode
|
void | setLanguageVersion(String version)
Set the language version. |
void | setModuleURIResolver(ModuleURIResolver resolver)
Set a user-defined ModuleURIResolver for resolving URIs used in "import module"
declarations in the XQuery prolog.
|
void | setPreserveBoundarySpace(boolean preserve)
Set the policy for preserving boundary space |
void | setPreserveNamespaces(boolean inherit)
Set the namespace copy mode
|
void | setRequiredContextItemType(ItemType type)
Declare the static type of the context item. |
void | setUpdatingEnabled(boolean updating)
Say whether the query is allowed to be updating. |
Deprecated: since 9.2. Use config.newStaticQueryContext(). This will create a StaticQueryContext with capabilities appropriate to the configuration (for example, offering XQuery 1.1 support).
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).Parameters: config the Saxon Configuration
Since: 8.4
This method is primarily for internal use. The recommended way to create a StaticQueryContext is by using the factory method Configuration.newStaticQueryContext().
Parameters: config the Saxon Configuration initial if set, this is the StaticQueryContext owned by the Configuration
Parameters: c the StaticQueryContext to be copied
Deprecated: since 9.2: use Configuration
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, 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 For additional control over the way in which the source document is processed,
supply an DocumentInfo
(indeed any NodeInfo
)
can be used as a Source. To use a third-party DOM Document as a source, create an instance of
javax.xml.transform.dom.DOMSource DOMSource
to wrap it.
AugmentedSource
object and set appropriate
options on the object.
Returns: the DocumentInfo representing the root node of the resulting document object.
Since: 8.4
Since: 9.1
Since: 9.0
Deprecated: since 9.0 - use StaticQueryContext
Clear all the declared passive namespaces, except for the standard ones (xml, saxon, etc)Since: 8.4
Since: 9.2
Since: 9.2
Since: 9.2
Note that this interface makes the 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: net.sf.saxon.trans.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
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: net.sf.saxon.trans.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.
Since: 8.4
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: net.sf.saxon.trans.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.
Since: 8.5
Parameters: name The name of the collation (technically, a URI) comparator The Java Comparator used to implement the collating sequence
Since: 8.4.
Parameters: name The name of the collation (technically, a URI) comparator The Java Comparator used to implement the collating sequence
Since: 8.9.
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.
Parameters: qName the qualified name of the variable type the declared type of the variable value the initial value of the variable. May be null if the variable is external. external true if the variable is external, that is, if its value may be set at run-time.
Throws: NullPointerException if the value is null, unless the variable is external XPathException if the value of the variable is not consistent with its type.
Since: 9.1
Parameters: 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.
Throws: NullPointerException if either the prefix or URI is null IllegalArgumentException if the prefix is "xml" and the namespace is not the XML namespace, or vice versa; or if the prefix is "xmlns", or the URI is "http://www.w3.org/2000/xmlns/"
Since: 9.0
Deprecated: since 9.0. Use StaticQueryContext
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.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 Must be false (the value true was previously reserved for internal use, but is no longer permitted)
Since: 8.4
Returns: the CollationMap containing all the collations defined in this static context
Returns: the base URI of the query
Since: 8.4
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
Returns: the collation map, which identifies all the known collations
Returns: the Saxon configuration
Since: 8.4
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
Returns: the namespace URI to be used as the default namespace for elements and types
Since: 8.9 Modified in 8.9 to return the namespace URI as a string rather than an integer code
Returns: the default function namespace (defaults to the fn: namespace)
Since: 8.4
Returns: the registered ErrorListener
Returns: the executable (or null if not set)
Returns: the external namespace resolver
Returns: the language version. Either "1.0" or "1.1". Default is "1.0".
Since: 9.2.
Returns: the registered ModuleURIResolver
Returns: the name pool
Since: 8.4
Parameters: prefix the namespace prefix, or "" to represent the null prefix
Returns: the namespace URI. Returns "" to represent the non-namespace, null to indicate that the prefix has not been declared
Returns: the required type of the context item
Returns: the Base URI
Since: 8.4
Returns: the user-declared namespaces
Returns: true if compile-time generation of code was requested
Since: 9.0
Returns: true if the empty sequence is considered less than any other value (the default), false if it is considered greater than any other value
Since: 9.0
Returns: true if Java code is to be generated as the final output
Returns: true if namespaces are inherited, false if not
Since: 8.4
Returns: true if the policy is to preserve boundary space, false if it is to strip it
Since: 9.0
Returns: true if namespaces are preserved, false if not
Since: 8.4
Returns: true if the query is allowed to use the XQuery Update facility. Note that this does not necessarily mean that the query is an updating query; but if the value is false, the it must definitely be non-updating.
Since: 9.1
Returns: an iterator over all the global variables that have been declared. They are returned as instances of class GlobalVariableDefinition
Since: 9.1
Returns: 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 "".
Since: 9.0
Parameters: updating indicates whether or not XQuery update syntax may be used. Note that XQuery Update is supported only in Saxon-EE languageVersion
Returns: the QueryParser
Throws: UnsupportedOperationException if a parser that supports update syntax is requested on Saxon-B
Since: 8.4
Parameters: baseURI the base URI of the query
Since: 8.4
Parameters: trace true if compile-time generation of trace code is required
Since: 9.0
Parameters: config the Saxon Configuration
Throws: IllegalArgumentException if the configuration supplied is different from the existing configuration
Since: 8.4
Parameters: uri the namespace URI to be used as the default namespace for elements and types
Since: 8.4
Parameters: defaultFunctionNamespace The namespace to be used for unprefixed function calls
Since: 8.4
Parameters: 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
Since: 9.0
Parameters: listener the ErrorListener to be used
Parameters: executable the executable
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 iteratePrefixes method.
Parameters: resolver the external namespace resolver
Parameters: generateCode true if Java code is to be generated as the final output
Parameters: inherit true if namespaces are inherited, false if not
Since: 8.4
Parameters: version The XQuery language version. Must be "1.0" or "1.1". Currently the only 1.1 language feature supported is try/catch, and that only in Saxon-EE. Note that XQuery 1.1 language features cannot be used with XQuery Updates. The Query Prolog must also specify version="1.1".
Since: 9.2
Parameters: resolver the ModuleURIResolver to be used
Parameters: preserve true if boundary space is to be preserved, false if it is to be stripped
Since: 9.0
Parameters: inherit true if namespaces are preserved, false if not
Since: 8.4
Parameters: type the required type of the context item
Parameters: updating true if the query is allowed to use the XQuery Update facility (requires Saxon-EE). If set to false, the query must not be an updating query. If set to true, it may be either an updating or a non-updating query.
Since: 9.1