Class XPathCompiler
To construct an XPathCompiler, use the factory method
Processor.newXPathCompiler()
.
An XPathCompiler may be used repeatedly to compile multiple queries. Any changes made to the XPathCompiler (that is, to the static context) do not affect queries that have already been compiled. An XPathCompiler may be used concurrently in multiple threads, but it should not then be modified once initialized.
Changes to an XPathCompiler are cumulative. There is no simple way to reset the XPathCompiler to its initial state; instead, simply create a new XPathCompiler.
The XPathCompiler
has the ability to maintain a cache of compiled
expressions. This is active only if enabled by calling setCaching(boolean)
.
If caching is enabled, then the compiler will recognize an attempt to compile
the same expression twice, and will avoid the cost of recompiling it. The cache
is emptied by any method that changes the static context for subsequent expressions,
for example, setBaseURI(java.net.URI)
. Unless the cache is emptied,
it grows indefinitely: compiled expressions are never discarded.
- Since:
- 9.0
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionCompile an XPath expression, supplied as a character string.compilePattern
(String source) Compile an XSLT 2.0 pattern, supplied as a character string.void
declareCollation
(String uri, Collator collation) Bind a collation URI to a collationvoid
Declare the default collationvoid
declareNamespace
(String prefix, String uri) Declare a namespace binding as part of the static context for XPath expressions compiled using this XPathCompilervoid
declareVariable
(QName qname) Declare a variable as part of the static context for XPath expressions compiled using this XPathCompiler.void
declareVariable
(QName qname, ItemType itemType, OccurrenceIndicator occurrences) Declare a variable as part of the static context for XPath expressions compiled using this XPathCompiler.Compile and evaluate an XPath expression, supplied as a character string, with a given context item.evaluateSingle
(String expression, XdmItem contextItem) Compile and evaluate an XPath expression whose result is expected to be a single item, with a given context item.Get the static base URI for XPath expressions compiled using this XPathCompiler.Ask whether an XPath 2.0 or XPath 3.0 processor is being usedGet the Processor from which this XPathCompiler was constructedGet the required type of the context item.Escape-hatch method to get the underlying static context object used by the implementation.void
Import a schema namespace: that is, add the element and attribute declarations and type definitions contained in a given namespace to the static context for the XPath expression.boolean
Ask whether undeclared variables are allowed.boolean
Ask whether XPath 1.0 backwards compatibility mode is in force.boolean
Ask whether the compiler is maintaining a cache of compiled expressionsboolean
Ask whether XPath expressions compiled using this XPathCompiler are schema-aware.void
setAllowUndeclaredVariables
(boolean allow) Say whether undeclared variables are allowed.void
setBackwardsCompatible
(boolean option) Set whether XPath 1.0 backwards compatibility mode is to be used.void
setBaseURI
(URI uri) Set the static base URI for XPath expressions compiled using this XPathCompiler.void
setCaching
(boolean caching) Say whether the compiler should maintain a cache of compiled expressions.void
setDecimalFormatProperty
(QName format, String property, String value) Registers the required decimal format propertiesvoid
setLanguageVersion
(String version) Say whether an XPath 2.0 or XPath 3.0 processor is required.void
Declare the static type of the context item.void
setSchemaAware
(boolean schemaAware) Say whether XPath expressions compiled using this XPathCompiler are schema-aware.
-
Constructor Details
-
XPathCompiler
Protected constructor- Parameters:
processor
- the s9api Processor
-
-
Method Details
-
getProcessor
Get the Processor from which this XPathCompiler was constructed- Returns:
- the Processor to which this XPathCompiler belongs
- Since:
- 9.3
-
setBackwardsCompatible
public void setBackwardsCompatible(boolean option) Set whether XPath 1.0 backwards compatibility mode is to be used. In backwards compatibility mode, more implicit type conversions are allowed in XPath expressions, for example it is possible to compare a number with a string. The default is false (backwards compatibility mode is off).- Parameters:
option
- true if XPath 1.0 backwards compatibility is to be enabled, false if it is to be disabled.
-
isBackwardsCompatible
public boolean isBackwardsCompatible()Ask whether XPath 1.0 backwards compatibility mode is in force.- Returns:
- true if XPath 1.0 backwards compatibility is enabled, false if it is disabled.
-
setSchemaAware
public void setSchemaAware(boolean schemaAware) Say whether XPath expressions compiled using this XPathCompiler are schema-aware. They will automatically be schema-aware if the methodimportSchemaNamespace(String)
is called. An XPath expression must be marked as schema-aware if it is to handle typed (validated) input documents.- Parameters:
schemaAware
- true if expressions are to be schema-aware, false otherwise- Since:
- 9.3
-
isSchemaAware
public boolean isSchemaAware()Ask whether XPath expressions compiled using this XPathCompiler are schema-aware. They will automatically be schema-aware if the methodimportSchemaNamespace(String)
is called. An XPath expression must be marked as schema-aware if it is to handle typed (validated) input documents.- Returns:
- true if expressions are to be schema-aware, false otherwise
- Since:
- 9.3
-
setLanguageVersion
Say whether an XPath 2.0 or XPath 3.0 processor is required.- Parameters:
version
- Must be numerically equal to 1.0, 2.0 or 3.0. Currently support for XPath 3.0 is incomplete: check the release notes.Setting the option to 1.0 requests an XPath 2.0 processor running in 1.0 compatibility mode; this is equivalent to setting the language version to 2.0 and backwards compatibility mode to true.
- Throws:
IllegalArgumentException
- if the version is not numerically equal to 1.0, 2.0 or 3.0.- Since:
- 9.3
-
getLanguageVersion
Ask whether an XPath 2.0 or XPath 3.0 processor is being used- Returns:
- version: "2.0" or "3.0"
- Since:
- 9.3
-
setBaseURI
Set the static base URI for XPath expressions compiled using this XPathCompiler. The base URI is part of the static context, and is used to resolve any relative URIs appearing within an XPath expression, for example a relative URI passed as an argument to the doc() function. If no static base URI is supplied, then the current working directory is used.- Parameters:
uri
- the base URI to be set in the static context. This must be an absolute URI.
-
getBaseURI
Get the static base URI for XPath expressions compiled using this XPathCompiler. The base URI is part of the static context, and is used to resolve any relative URIs appearing within an XPath expression, for example a relative URI passed as an argument to the doc() function. If no static base URI has been explicitly set, this method returns null.- Returns:
- the base URI from the static context
-
declareNamespace
Declare a namespace binding as part of the static context for XPath expressions compiled using this XPathCompiler- Parameters:
prefix
- The namespace prefix. If the value is a zero-length string, this method sets the default namespace for elements and types.uri
- The namespace URI. It is possible to specify a zero-length string to "undeclare" a namespace; in this case the prefix will not be available for use, except in the case where the prefix is also a zero length string, in which case the absence of a prefix implies that the name is in no namespace.- Throws:
NullPointerException
- if either the prefix or uri is null.
-
importSchemaNamespace
Import a schema namespace: that is, add the element and attribute declarations and type definitions contained in a given namespace to the static context for the XPath expression.This method will not cause the schema to be loaded. That must be done separately, using the
SchemaManager
. This method will not fail if the schema has not been loaded (but in that case the set of declarations and definitions made available to the XPath expression is empty). The schema document for the specified namespace may be loaded before or after this method is called.This method does not bind a prefix to the namespace. That must be done separately, using the
declareNamespace(String, String)
method.- Parameters:
uri
- The schema namespace to be imported. To import declarations in a no-namespace schema, supply a zero-length string.- Since:
- 9.1
-
setAllowUndeclaredVariables
public void setAllowUndeclaredVariables(boolean allow) Say whether undeclared variables are allowed. By default, they are not allowed. When undeclared variables are allowed, it is not necessary to predeclare the variables that may be used in the XPath expression; instead, a variable is automatically declared when a reference to the variable is encountered within the expression.- Parameters:
allow
- true if undeclared variables are allowed, false if they are not allowed.- Since:
- 9.2
-
isAllowUndeclaredVariables
public boolean isAllowUndeclaredVariables()Ask whether undeclared variables are allowed. By default, they are not allowed. When undeclared variables are allowed, it is not necessary to predeclare the variables that may be used in the XPath expression; instead, a variable is automatically declared when a reference to the variable is encountered within the expression.- Returns:
- true if undeclared variables are allowed, false if they are not allowed.
- Since:
- 9.2
-
declareVariable
Declare a variable as part of the static context for XPath expressions compiled using this XPathCompiler. It is an error for the XPath expression to refer to a variable unless it has been declared. This method declares the existence of the variable, but it does not bind any value to the variable; that is done later, when the XPath expression is evaluated. The variable is allowed to have any type (that is, the required type isitem()*
).- Parameters:
qname
- The name of the variable, expressions as a QName
-
declareVariable
public void declareVariable(QName qname, ItemType itemType, OccurrenceIndicator occurrences) throws SaxonApiException Declare a variable as part of the static context for XPath expressions compiled using this XPathCompiler. It is an error for the XPath expression to refer to a variable unless it has been declared. This method declares the existence of the variable, and defines the required type of the variable, but it does not bind any value to the variable; that is done later, when the XPath expression is evaluated.- Parameters:
qname
- The name of the variable, expressed as a QNameitemType
- The required item type of the value of the variableoccurrences
- The allowed number of items in the sequence forming the value of the variable- Throws:
SaxonApiException
- if the requiredType is syntactically invalid or if it refers to namespace prefixes or schema components that are not present in the static context
-
setRequiredContextItemType
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 type of the context item- Since:
- 9.3
-
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.- Returns:
- the required type of the context item
- Since:
- 9.3
-
declareCollation
Bind a collation URI to a collation- Parameters:
uri
- the absolute collation URIcollation
- aCollator
object that implements the required collation- Throws:
IllegalArgumentException
- if an attempt is made to rebind the standard URI for the Unicode codepoint collation- Since:
- 9.4
-
declareDefaultCollation
Declare the default collation- Parameters:
uri
- the absolute URI of the default collation. This URI must have been bound to a collation using the methoddeclareCollation(String, Collator)
- Throws:
IllegalStateException
- if the collation URI has not been registered, unless it is the standard Unicode codepoint collation which is registered implicitly- Since:
- 9.4
-
setCaching
public void setCaching(boolean caching) Say whether the compiler should maintain a cache of compiled expressions.- Parameters:
caching
- if set to true, caching of compiled expressions is enabled. If set to false, any existing cache is cleared, and future compiled expressions will not be cached until caching is re-enabled. The cache is also cleared (but without disabling future caching) if any method is called that changes the static context for compiling expressions, for exampledeclareVariable(QName)
ordeclareNamespace(String, String)
.- Since:
- 9.3
-
isCaching
public boolean isCaching()Ask whether the compiler is maintaining a cache of compiled expressions- Returns:
- true if a cache is being maintained
- Since:
- 9.3
-
compile
Compile an XPath expression, supplied as a character string.- Parameters:
source
- A string containing the source text of the XPath expression- Returns:
- An XPathExecutable which represents the compiled xpath expression object. The XPathExecutable may be run as many times as required, in the same or a different thread. The XPathExecutable is not affected by any changes made to the XPathCompiler once it has been compiled.
- Throws:
SaxonApiException
- if any static error is detected while analyzing the expression
-
evaluate
Compile and evaluate an XPath expression, supplied as a character string, with a given context item.- Parameters:
expression
- A string containing the source text of the XPath expressioncontextItem
- The context item to be used for evaluating the expression. This may be null if the expression is to be evaluated with no context item.- Returns:
- the result of evaluating the XPath expression with this context item. Note that
the result is an iterable, so that it can be used in a construct such as
for (XdmItem item : xpath.evaluate("//x", doc) {...}
- Throws:
SaxonApiException
- if any static error is detected while analyzing the expression, or if any dynamic error is detected while evaluating it.- Since:
- 9.3
-
evaluateSingle
Compile and evaluate an XPath expression whose result is expected to be a single item, with a given context item. The expression is supplied as a character string.- Parameters:
expression
- A string containing the source text of the XPath expressioncontextItem
- The context item to be used for evaluating the expression. This may be null if the expression is to be evaluated with no context item.- Returns:
- the result of evaluating the XPath expression with this context item. If the result is a singleton it is returned as an XdmItem; if it is an empty sequence, the return value is null. If the expression returns a sequence of more than one item, any items after the first are ignored.
- Throws:
SaxonApiException
- if any static error is detected while analyzing the expression, or if any dynamic error is detected while evaluating it.- Since:
- 9.3
-
compilePattern
Compile an XSLT 2.0 pattern, supplied as a character string. The compiled pattern behaves as a boolean expression which, when evaluated in a particular context, returns true if the context node matches the pattern, and false if it does not. An error is reported if there is no context item or it the context item is not a node.- Parameters:
source
- A string conforming to the syntax of XSLT 2.0 patterns- Returns:
- An XPathExecutable representing an expression which evaluates to true when the context node matches the pattern, and false when it does not.
- Throws:
SaxonApiException
- if the pattern contains static errors: for example, if its syntax is incorrect, or if it refers to undeclared variables or namespaces- Since:
- 9.1
-
setDecimalFormatProperty
public void setDecimalFormatProperty(QName format, String property, String value) throws SaxonApiException Registers the required decimal format properties- Parameters:
format
- The name of the decimal formatproperty
- The decimal symbols name to updatevalue
- The value to update the decimal symbol property- Throws:
SaxonApiException
- if there are two conflicting definitions of the named decimal-format- Since:
- 9.4
-
getUnderlyingStaticContext
Escape-hatch method to get the underlying static context object used by the implementation.- Returns:
- the underlying static context object. In the current implementation this will always
be an instance of
IndependentContext
.This method provides an escape hatch to internal Saxon implementation objects that offer a finer and lower-level degree of control than the s9api classes and methods. Some of these classes and methods may change from release to release.
- Since:
- 9.1
-