|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object net.sf.saxon.s9api.XPathCompiler
public class XPathCompiler
An XPathCompiler object allows XPath queries to be compiled. The compiler holds information that represents the static context for an XPath expression.
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.
Constructor Summary | |
---|---|
protected |
XPathCompiler(Processor processor)
Protected constructor |
Method Summary | |
---|---|
XPathExecutable |
compile(String source)
Compile an XPath expression, supplied as a character string. |
XPathExecutable |
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 collation |
void |
declareDefaultCollation(String uri)
Declare the default collation |
void |
declareNamespace(String prefix,
String uri)
Declare a namespace binding as part of the static context for XPath expressions compiled using this XPathCompiler |
void |
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. |
XdmValue |
evaluate(String expression,
XdmItem contextItem)
Compile and evaluate an XPath expression, supplied as a character string, with a given context item. |
XdmItem |
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. |
URI |
getBaseURI()
Get the static base URI for XPath expressions compiled using this XPathCompiler. |
String |
getLanguageVersion()
Ask whether an XPath 2.0 or XPath 3.0 processor is being used |
Processor |
getProcessor()
Get the Processor from which this XPathCompiler was constructed |
ItemType |
getRequiredContextItemType()
Get the required type of the context item. |
StaticContext |
getUnderlyingStaticContext()
Escape-hatch method to get the underlying static context object used by the implementation. |
void |
importSchemaNamespace(String uri)
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 |
isAllowUndeclaredVariables()
Ask whether undeclared variables are allowed. |
boolean |
isBackwardsCompatible()
Ask whether XPath 1.0 backwards compatibility mode is in force. |
boolean |
isCaching()
Ask whether the compiler is maintaining a cache of compiled expressions |
boolean |
isSchemaAware()
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 properties |
void |
setLanguageVersion(String version)
Say whether an XPath 2.0 or XPath 3.0 processor is required. |
void |
setRequiredContextItemType(ItemType type)
Declare the static type of the context item. |
void |
setSchemaAware(boolean schemaAware)
Say whether XPath expressions compiled using this XPathCompiler are schema-aware. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
protected XPathCompiler(Processor processor)
processor
- the s9api ProcessorMethod Detail |
---|
public Processor getProcessor()
public void setBackwardsCompatible(boolean option)
option
- true if XPath 1.0 backwards compatibility is to be enabled, false if it is to
be disabled.public boolean isBackwardsCompatible()
public void setSchemaAware(boolean schemaAware)
importSchemaNamespace(String)
is called. An XPath expression
must be marked as schema-aware if it is to handle typed (validated)
input documents.
schemaAware
- true if expressions are to be schema-aware, false otherwisepublic boolean isSchemaAware()
importSchemaNamespace(String)
is called. An XPath expression
must be marked as schema-aware if it is to handle typed (validated)
input documents.
public void setLanguageVersion(String version)
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.
IllegalArgumentException
- if the version is not numerically equal to 1.0, 2.0 or 3.0.public String getLanguageVersion()
public void setBaseURI(URI uri)
uri
- the base URI to be set in the static context. This must be an absolute URI.public URI getBaseURI()
public void declareNamespace(String prefix, String uri)
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.
NullPointerException
- if either the prefix or uri is null.public void importSchemaNamespace(String uri)
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.
uri
- The schema namespace to be imported. To import declarations in a no-namespace schema,
supply a zero-length string.public void setAllowUndeclaredVariables(boolean allow)
allow
- true if undeclared variables are allowed, false if they are not allowed.public boolean isAllowUndeclaredVariables()
public void declareVariable(QName qname)
item()*
).
qname
- The name of the variable, expressions as a QNamepublic void declareVariable(QName qname, ItemType itemType, OccurrenceIndicator occurrences) throws SaxonApiException
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
SaxonApiException
- if the requiredType is syntactically invalid or if it refers to namespace
prefixes or schema components that are not present in the static contextpublic void setRequiredContextItemType(ItemType type)
type
- the required type of the context itempublic ItemType getRequiredContextItemType()
public void declareCollation(String uri, Collator collation)
uri
- the absolute collation URIcollation
- a Collator
object that implements the required collation
IllegalArgumentException
- if an attempt is made to rebind the standard URI
for the Unicode codepoint collationpublic void declareDefaultCollation(String uri)
uri
- the absolute URI of the default collation. This URI must have been bound to a collation
using the method declareCollation(String, Collator)
IllegalStateException
- if the collation URI has not been registered, unless it is the standard
Unicode codepoint collation which is registered implicitlypublic void setCaching(boolean caching)
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 example declareVariable(QName)
or
declareNamespace(String, String)
.public boolean isCaching()
public XPathExecutable compile(String source) throws SaxonApiException
source
- A string containing the source text of the XPath expression
SaxonApiException
- if any static error is detected while analyzing the expressionpublic XdmValue evaluate(String expression, XdmItem contextItem) throws SaxonApiException
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.
for (XdmItem item : xpath.evaluate("//x", doc) {...}
SaxonApiException
- if any static error is detected while analyzing the expression,
or if any dynamic error is detected while evaluating it.public XdmItem evaluateSingle(String expression, XdmItem contextItem) throws SaxonApiException
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.
SaxonApiException
- if any static error is detected while analyzing the expression,
or if any dynamic error is detected while evaluating it.public XPathExecutable compilePattern(String source) throws SaxonApiException
source
- A string conforming to the syntax of XSLT 2.0 patterns
SaxonApiException
- if the pattern contains static errors: for example, if its syntax is incorrect,
or if it refers to undeclared variables or namespacespublic void setDecimalFormatProperty(QName format, String property, String value) throws SaxonApiException
format
- The name of the decimal formatproperty
- The decimal symbols name to updatevalue
- The value to update the decimal symbol property
SaxonApiException
- if there are two conflicting definitions of the named decimal-formatpublic StaticContext getUnderlyingStaticContext()
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.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |