|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object net.sf.saxon.query.StaticQueryContext
public class StaticQueryContext
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.
Constructor Summary | |
---|---|
protected |
StaticQueryContext()
Private constructor used when copying a context |
|
StaticQueryContext(Configuration config)
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). |
|
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)
Deprecated. since 9.2: use Configuration.buildDocument(javax.xml.transform.Source) |
void |
clearDeclaredGlobalVariables()
Clear all declared global variables |
void |
clearNamespaces()
Clear all the user-declared namespaces |
void |
clearPassiveNamespaces()
Deprecated. since 9.0 - use clearNamespaces() |
void |
compileLibrary(InputStream source,
String encoding)
Prepare an XQuery library module for subsequent evaluation. |
void |
compileLibrary(Reader source)
Prepare an XQuery library module for subsequent evaluation. |
void |
compileLibrary(String query)
Compile an XQuery library module for subsequent evaluation. |
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. |
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)
Deprecated. since 9.0. Use declareNamespace(java.lang.String, java.lang.String) |
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. |
CodeInjector |
getCodeInjector()
Get any CodeInjector that has been registered |
StringCollator |
getCollation(String name)
Get a named collation. |
CollationMap |
getCollationMap()
Get the collation map |
QueryLibrary |
getCompiledLibrary(String namespace)
Get a previously compiled library module |
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 |
FunctionLibrary |
getExtensionFunctionLibrary()
Get any extension function library that was previously set. |
NamespaceResolver |
getExternalNamespaceResolver()
Get the external namespace resolver that has been registered using setExternalNamespaceResolver(), if any. |
DecimalValue |
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 declareNamespace(java.lang.String, java.lang.String) . |
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 |
isSchemaAware()
Ask whether this query is schema-aware |
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 declareNamespace(java.lang.String, java.lang.String) |
void |
reset()
Reset the state of this StaticQueryContext to an uninitialized state |
void |
setBaseURI(String baseURI)
Set the Base URI of the query |
void |
setCodeInjector(CodeInjector injector)
Request that the parser should insert custom code into the expression tree by calling a supplied CodeInjector to process each expression as it is parsed, for example for tracing or performance measurement |
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 |
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(DecimalValue 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 |
setSchemaAware(boolean aware)
Say whether this query is schema-aware |
void |
setUpdatingEnabled(boolean updating)
Say whether the query is allowed to be updating. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
protected StaticQueryContext()
public StaticQueryContext(Configuration config)
config
- the Saxon Configurationpublic StaticQueryContext(Configuration config, boolean initial)
This method is primarily for internal use. The recommended way to create a StaticQueryContext is by using the factory method Configuration.newStaticQueryContext().
config
- the Saxon Configurationinitial
- if set, this is the StaticQueryContext owned by the Configurationpublic StaticQueryContext(StaticQueryContext c)
c
- the StaticQueryContext to be copiedMethod Detail |
---|
public void reset()
public void setConfiguration(Configuration config)
config
- the Saxon Configuration
IllegalArgumentException
- if the configuration supplied is different from the existing
configurationpublic Configuration getConfiguration()
public Executable getExecutable()
public void setSchemaAware(boolean aware)
aware
- true if this query is schema-awarepublic boolean isSchemaAware()
public void setBaseURI(String baseURI)
baseURI
- the base URI of the querypublic DocumentInfo buildDocument(Source source) throws XPathException
Configuration.buildDocument(javax.xml.transform.Source)
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.
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.
XPathException
public void setLanguageVersion(DecimalValue version)
version
- The XQuery language version. Must be "1.0" or "3.0" (the value 1.1 is also
accepted temporarily).
Note that XQuery 3.0 language features cannot be used with XQuery Updates. The Query
Prolog must also specify version="3.0".public DecimalValue getLanguageVersion()
public FunctionLibrary getExtensionFunctionLibrary()
public boolean isCompileWithTracing()
public void setCompileWithTracing(boolean trace)
trace
- true if compile-time generation of trace code is requiredpublic void setCodeInjector(CodeInjector injector)
injector
- the CodeInjector to be used. May be null, in which case
no code is injectedpublic CodeInjector getCodeInjector()
public boolean isUpdating()
public void setGeneratingJavaCode(boolean generateCode)
generateCode
- true if Java code is to be generated as the final outputpublic boolean isGeneratingJavaCode()
public void setInheritNamespaces(boolean inherit)
inherit
- true if namespaces are inherited, false if notpublic boolean isInheritNamespaces()
public void setPreserveNamespaces(boolean inherit)
inherit
- true if namespaces are preserved, false if notpublic boolean isPreserveNamespaces()
public void setConstructionMode(int mode)
mode
- one of Validation.STRIP
, Validation.PRESERVE
public int getConstructionMode()
Validation.STRIP
, Validation.PRESERVE
public XQueryExpression compileQuery(String query) throws XPathException
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.
query
- The XQuery query to be evaluated, supplied as a string.
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.public XQueryExpression compileQuery(Reader source) throws XPathException, IOException
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.
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.public XQueryExpression compileQuery(InputStream source, String encoding) throws XPathException, IOException
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
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.public void compileLibrary(String query) throws XPathException
XPathException
public void compileLibrary(Reader source) throws XPathException, IOException
XPathException
IOException
public void compileLibrary(InputStream source, String encoding) throws XPathException, IOException
XPathException
IOException
public QueryLibrary getCompiledLibrary(String namespace)
namespace
- the module namespace
public void declareNamespace(String prefix, String uri)
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.
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/"public void declarePassiveNamespace(String prefix, String uri, boolean explicit) throws XPathException
declareNamespace(java.lang.String, java.lang.String)
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)
XPathException
public void clearNamespaces()
protected HashMap<String,String> getUserDeclaredNamespaces()
public void clearPassiveNamespaces()
clearNamespaces()
public Iterator<String> iterateDeclaredPrefixes()
declareNamespace(java.lang.String, java.lang.String)
public String getNamespaceForPrefix(String prefix)
declareNamespace(java.lang.String, java.lang.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
public void setExternalNamespaceResolver(NamespaceResolver resolver)
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 resolverpublic NamespaceResolver getExternalNamespaceResolver()
public String getDefaultFunctionNamespace()
public void setDefaultFunctionNamespace(String defaultFunctionNamespace)
defaultFunctionNamespace
- The namespace to be used for unprefixed function callspublic void setDefaultElementNamespace(String uri)
uri
- the namespace URI to be used as the default namespace for elements and typespublic String getDefaultElementNamespace()
public void declareGlobalVariable(StructuredQName qName, SequenceType type, ValueRepresentation value, boolean external) throws XPathException
qName
- the qualified name of the variabletype
- the declared type of the variablevalue
- 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.
NullPointerException
- if the value is null, unless the variable is external
XPathException
- if the value of the variable is not consistent with its type.public Iterator iterateDeclaredGlobalVariables()
GlobalVariableDefinition
public void clearDeclaredGlobalVariables()
public void setModuleURIResolver(ModuleURIResolver resolver)
resolver
- the ModuleURIResolver to be usedpublic ModuleURIResolver getModuleURIResolver()
public void declareCollation(String name, Comparator comparator)
name
- The name of the collation (technically, a URI)comparator
- The Java Comparator used to implement the collating sequencepublic void declareCollation(String name, StringCollator comparator)
name
- The name of the collation (technically, a URI)comparator
- The Java Comparator used to implement the collating sequencepublic void declareDefaultCollation(String name)
name
- The collation name, as specified in the query prolog. The name
is not validated until it is used.
NullPointerException
- if the supplied value is nullpublic StringCollator getCollation(String name)
name
- the name of the collation, as an absolute URI
NullPointerException
- if the collation name argument is null.public CollationMap getCollationMap()
public String getDefaultCollationName()
public CollationMap getAllCollations()
public void setRequiredContextItemType(ItemType type)
type
- the required type of the context itempublic ItemType getRequiredContextItemType()
public NamePool getNamePool()
public String getSystemId()
public String getBaseURI()
public void setPreserveBoundarySpace(boolean preserve)
preserve
- true if boundary space is to be preserved, false if it is to be strippedpublic boolean isPreserveBoundarySpace()
public void setEmptyLeast(boolean least)
least
- true if the empty sequence is considered less than any other value (the default),
false if it is considered greater than any other valuepublic boolean isEmptyLeast()
public void setErrorListener(ErrorListener listener)
listener
- the ErrorListener to be usedpublic ErrorListener getErrorListener()
public void setUpdatingEnabled(boolean updating)
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.public boolean isUpdatingEnabled()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |