Saxon.Api
Class FeatureKeys
-
public abstract class FeatureKeys
FeatureKeys
defines a set of constants, representing the names of Saxon configuration
options which can be supplied to the Saxon implementations of the JAXP
interfaces TransformerFactory
, SchemaFactory
, Validator
, and ValidationHandler
,
and to other interfaces such as the s9api net.sf.saxon.s9api.Processor
Field Summary |
|
---|---|
string | ALLOW_EXTERNAL_FUNCTIONS Not applicable to SaxonCS |
string | ALLOW_MULTITHREADING ALLOW_MULTITHREADING determines whether multi-threading is allowed. |
string | ALLOW_OLD_JAVA_URI_FORMAT Not applicable to SaxonCS |
string | ALLOW_SYNTAX_EXTENSIONS This flag must be set to enable use of extensions to XPath, XQuery and XSLT syntax that go beyond what is allowed by the extensibility mechanisms in the spec. In some cases these extensions are experimental and may not be carried forward to future Saxon releases. |
string | ALLOW_UNRESOLVED_SCHEMA_COMPONENTS The W3C XSD specification (both 1.0 and 1.1) states that an unresolved reference to an absent schema component does not automatically make the schema invalid; the schema should be usable for validation provided that the missing components are not actually needed in a particular validation episode. |
string | ALLOWED_PROTOCOLS Not applicable to SaxonCS |
string | ASSERTIONS_CAN_SEE_COMMENTS ASSERTIONS_CAN_SEE_COMMENTS determines whether comment and processing instructions in a document being validated are visible to assertions in an XSD 1.1 schema. |
string | COLLATION_URI_RESOLVER The supplied |
string | COLLATION_URI_RESOLVER_CLASS Not applicable to SaxonCS |
string | COLLECTION_FINDER Not applicable to SaxonCS |
string | COLLECTION_FINDER_CLASS Not applicable to SaxonCS |
string | COMPILE_WITH_TRACING If run-time tracing of stylesheet or query execution is required, then the code must be compiled with tracing enabled. |
string | CONFIGURATION This attribute cannot be set on the net.sf.saxon.Configuration itself,
but it can be set on various JAXP factory objects such as a
|
string | CONFIGURATION_FILE Defines a configuration file to be applied to the configuration. |
string | DEBUG_BYTE_CODE Not applicable to SaxonCS |
string | DEBUG_BYTE_CODE_DIR Not applicable to SaxonCS |
string | DEFAULT_COLLATION This option determines the collation that is used for comparing strings when no explicit collation is requested. It is not necessary for this collation to exist (or to have been registered) when setting this option; it only needs to exist by the time it is used. |
string | DEFAULT_COLLECTION This determines the collection that is used when the |
string | DEFAULT_COUNTRY This determines the country that is used by |
string | DEFAULT_LANGUAGE This option determines the language that is used by |
string | DEFAULT_REGEX_ENGINE Not applicable to SaxonCS |
string | DISABLE_XSL_EVALUATE This option disables the |
string | DISPLAY_BYTE_CODE Not applicable to SaxonCS |
string | DTD_VALIDATION If true, the XML parser is requested to perform validation of source documents against their DTD. Default is false. |
string | DTD_VALIDATION_RECOVERABLE Not applicable to SaxonCS |
string | EAGER_EVALUATION Forces Saxon to do eager evaluation of expressions in contexts where normally it would do lazy evaluation, for example when evaluating variables and function results. This can make for easier debugging. |
string | ENTITY_RESOLVER_CLASS Not applicable to SaxonCS |
string | ENVIRONMENT_VARIABLE_RESOLVER Setting the |
string | ENVIRONMENT_VARIABLE_RESOLVER_CLASS Not applicable to SaxonCS |
string | ERROR_LISTENER_CLASS Not applicable to SaxonCS |
string | EXPAND_ATTRIBUTE_DEFAULTS
|
string | EXPATH_FILE_DELETE_TEMPORARY_FILES Not applicable to SaxonCS |
string | GENERATE_BYTE_CODE Not applicable to SaxonCS |
string | IGNORE_SAX_SOURCE_PARSER Not applicable to SaxonCS |
string | IMPLICIT_SCHEMA_IMPORTS
|
string | LAZY_CONSTRUCTION_MODE Not applicable to SaxonCS |
string | LICENSE_FILE_LOCATION
|
string | LINE_NUMBERING Default is false. If true, line and column number information is retained for all
source documents. This information is accessible using the
|
string | MARK_DEFAULTED_ATTRIBUTES Not applicable to SaxonCS |
string | MAX_COMPILED_CLASSES Not applicable to SaxonCS |
string | MESSAGE_EMITTER_CLASS Not applicable to SaxonCS |
string | MODULE_URI_RESOLVER Affects XQuery only. An instance of a user-written class implementing Saxon's
net.sf.saxon.lib.ModuleURIResolver interface. This is used to
process any URIs used in |
string | MODULE_URI_RESOLVER_CLASS Not applicable to SaxonCS |
string | MONITOR_HOT_SPOT_BYTE_CODE Not applicable to SaxonCS |
string | MULTIPLE_SCHEMA_IMPORTS Affects schema construction (whether for standalone validation, or in the context of XSLT or XQuery). |
string | NAME_POOL Indicates that the supplied |
string | OCCURRENCE_LIMITS
|
string | OPTIMIZATION_LEVEL Allows individual optimizations to be enabled or disabled selectively. |
string | OUTPUT_URI_RESOLVER Not applicable to SaxonCS |
string | OUTPUT_URI_RESOLVER_CLASS Not applicable to SaxonCS |
string | PRE_EVALUATE_DOC_FUNCTION If true, calls on the |
string | RECOGNIZE_URI_QUERY_PARAMETERS True if the |
string | RECOVERY_POLICY At one time this property controlled how recoverable errors were handled (fatal error, warning, or ignored). XSLT 3.0 has eliminated all recoverable errors from the specification, so the property is deprecated from Saxon 10.0. |
string | RECOVERY_POLICY_NAME At one time this property controlled how recoverable errors were handled (fatal error, warning, or ignored). XSLT 3.0 has eliminated all recoverable errors from the specification, so the property is deprecated from Saxon 10.0. |
string | REGEX_BACKTRACKING_LIMIT This property sets a limit on the amount of backtracking performed during regular expression evaluation. |
string | RESOURCE_RESOLVER The supplied implementation of |
string | RESOURCE_RESOLVER_CLASS Not applicable to SaxonCS |
string | RESULT_DOCUMENT_THREADS Indicates the maximum number of threads to be used for processing
|
string | RETAIN_DTD_ATTRIBUTE_TYPES Not applicable to SaxonCS |
string | RETAIN_NODE_FOR_DIAGNOSTICS By default, Saxon attempts to ensure that the run-time code contains no links to the original source stylesheet tree. This allows the garbage collector to free memory. |
string | SCHEMA_URI_RESOLVER The supplied |
string | SCHEMA_URI_RESOLVER_CLASS Not applicable to SaxonCS |
string | SCHEMA_VALIDATION Indicates whether and how schema validation should be applied to source documents. |
string | SCHEMA_VALIDATION_MODE Indicates whether and how schema validation should be applied to source documents. |
string | SERIALIZER_FACTORY_CLASS Not applicable to SaxonCS |
string | SOURCE_PARSER_CLASS Not applicable to SaxonCS |
string | SOURCE_RESOLVER_CLASS Not applicable to SaxonCS |
string | STABLE_COLLECTION_URI
|
string | STABLE_UNPARSED_TEXT
|
string | STANDARD_ERROR_OUTPUT_FILE
|
string | STREAMABILITY The |
string | STREAMING_FALLBACK If the |
string | STRICT_STREAMABILITY Causes the XSLT processor to verify that constructs that are declared streamable are in fact "guaranteed streamable" according to the W3C rules. |
string | STRIP_WHITESPACE Indicates whether all whitespace, no whitespace, or whitespace in elements defined in a DTD or schema as having element-only content should be stripped from source documents. |
string | STYLE_PARSER_CLASS Not applicable to SaxonCS |
string | SUPPRESS_EVALUATION_EXPIRY_WARNING This is set to true to suppress the warning otherwise issued by command-line interfaces indicating that an evaluation license is in use and is due to expire in a set number of days. |
string | SUPPRESS_XPATH_WARNINGS Suppresses all warnings issued by the XPath and XQuery parsers. |
string | SUPPRESS_XSLT_NAMESPACE_CHECK This is set to true to suppress the warning when there is no commonality between the namespaces used in stylesheet match patterns and the namespaces used in the source document. |
string | THRESHOLD_FOR_COMPILING_TYPES Not applicable to SaxonCS |
string | THRESHOLD_FOR_FUNCTION_INLINING Saxon-EE performs inlining of user-defined functions that are sufficiently simple: they must not be recursive, and they must be below a certain size. This option defines the size. |
string | THRESHOLD_FOR_HOTSPOT_BYTE_CODE Not applicable to SaxonCS |
string | TIMING This is set to true to cause basic timing and tracing information to be output to the standard error output stream. |
string | TRACE_EXTERNAL_FUNCTIONS Not applicable to SaxonCS |
string | TRACE_LISTENER The |
string | TRACE_LISTENER_CLASS Not applicable to SaxonCS |
string | TRACE_LISTENER_OUTPUT_FILE When trace listening is switched on (for example by using -T on the command line), this file will be supplied to the trace listener to use as the output destination. If the option is not supplied, trace listener output is sent to the standard error stream. |
string | TRACE_OPTIMIZER_DECISIONS If this option is set, Saxon will output (to the standard error output) detailed information about the rewrites to the expression tree made by the optimizer. This information is mainly useful for internal system debugging, but it is also possible to digest it to analyze the ways in which the expression has been optimized for the purpose of performance analysis and tuning. |
string | TREE_MODEL Selects an implementation of the Saxon tree model. The default is
|
string | TREE_MODEL_NAME Selects an implementation of the Saxon tree model. The default is
|
string | UNPARSED_TEXT_URI_RESOLVER The supplied |
string | UNPARSED_TEXT_URI_RESOLVER_CLASS Not applicable to SaxonCS |
string | URI_RESOLVER_CLASS Not applicable to SaxonCS |
string | USE_PI_DISABLE_OUTPUT_ESCAPING Not applicable to SaxonCS |
string | USE_TYPED_VALUE_CACHE This option is relevant only when the TinyTree is used; it determines whether (for a validated document) a cache will be maintained containing the typed values of nodes. |
string | USE_XSI_SCHEMA_LOCATION This option determines whether or not to use the |
string | VALIDATION_COMMENTS This option determines whether non-fatal validation errors in XQuery or XSLT result
documents should result in comments being inserted into the result tree. The
command-line flag |
string | VALIDATION_WARNINGS This option indicates (if true) that errors occuring while validating a final result tree are not to be treated as fatal. |
string | VERSION_WARNING Indicates whether a warning message should be notified (to the
|
string | XINCLUDE Not applicable to SaxonCS |
string | XML_PARSER_FEATURE Not applicable to SaxonCS |
string | XML_PARSER_PROPERTY Not applicable to SaxonCS |
string | XML_VERSION This determines the XML version used by the |
string | XPATH_VERSION_FOR_XSD The XSD 1.1 specification states that XPath version 2.0 is used for expressions appearing in assertions and type alternatives. This option allows XPath 3.0 or 3.1 to be used instead. |
string | XPATH_VERSION_FOR_XSLT The XSLT 3.0 specification states that processors are required to support XPath 3.0 expressions within stylesheets, together with some extensions (maps) selected from the XPath 3.1 specification. Support for the full syntax of XPath 3.1 is optional, but it is the default in Saxon. This option allows a different XPath language level to be selected. |
string | XQUERY_ALLOW_UPDATE Determines whether XQuery Update syntax is accepted. |
string | XQUERY_CONSTRUCTION_MODE This option defines the default value of the construction mode in the XQuery static context (overridable in the query prolog). |
string | XQUERY_DEFAULT_ELEMENT_NAMESPACE This property defines the default namespace for elements and types that are not qualified by a namespace prefix. |
string | XQUERY_DEFAULT_FUNCTION_NAMESPACE This property defines the default namespace for function names that are not qualified by a namespace prefix. |
string | XQUERY_EMPTY_LEAST This property defines how the empty sequence is handled in XQuery sorting (the "order
by" clause). If true, |
string | XQUERY_INHERIT_NAMESPACES This property defines the default value of the |
string | XQUERY_MULTIPLE_MODULE_IMPORTS If the value is false, then when an |
string | XQUERY_PRESERVE_BOUNDARY_SPACE This property defines whether "boundary space" (insignificant space in direct element constructors) should be retained or not. |
string | XQUERY_PRESERVE_NAMESPACES This property defines whether unused namespace declarations are retained by XQuery element copy operations. |
string | XQUERY_REQUIRED_CONTEXT_ITEM_TYPE This property defines the default expected context item type for a query. |
string | XQUERY_SCHEMA_AWARE A query will automatically be schema-aware if it contains an |
string | XQUERY_STATIC_ERROR_LISTENER_CLASS Not applicable to SaxonCS |
string | XQUERY_VERSION This property determines the version of XQuery used by the
|
string | XSD_VERSION This property determines the version of XML Schema used by the
|
string | XSLT_ENABLE_ASSERTIONS This property indicates whether assertions (XSLT 3.0 xsl:assert instructions) are enabled or disabled. They are disabled by default. Setting this property on causes assertions to be enabled at compile time for all XSLT packages compiled using the default configuration options. |
string | XSLT_INITIAL_MODE This property indicates the name of a mode within a stylesheet in which execution (using template rules) should begin. |
string | XSLT_INITIAL_TEMPLATE This property indicates the name of a named template within a stylesheet where execution should begin. |
string | XSLT_SCHEMA_AWARE This property indicates whether stylesheets should be compiled with the ability to
handle schema-typed input documents. By default a stylesheet is compiled to handle
such input if it contains an |
string | XSLT_STATIC_ERROR_LISTENER_CLASS Not applicable to SaxonCS |
string | XSLT_STATIC_URI_RESOLVER_CLASS Not applicable to SaxonCS |
string | XSLT_VERSION This property determines the version of XSLT to be supported by default. |
string | ZIP_URI_PATTERN Not applicable to SaxonCS |
Field Detail
ALLOW_MULTITHREADING
ALLOW_MULTITHREADING determines whether multi-threading is allowed.
If true (the default), the presence of the attribute saxon:threads="N"
on an xsl:for-each
instruction, when running under Saxon-EE, causes
multi-threaded execution. If set to false, the value of the
saxon:threads
argument is ignored.
Setting the value to false also disables asynchronous processing of
xsl:result-document
instructions.
The default value is true if Saxon-EE is in use, false otherwise.
ALLOW_SYNTAX_EXTENSIONS
This flag must be set to enable use of extensions to XPath, XQuery and XSLT syntax that go beyond what is allowed by the extensibility mechanisms in the spec. In some cases these extensions are experimental and may not be carried forward to future Saxon releases.
Syntax extensions in Saxon 10 include the use of type aliases (type(...)
where
an item type is expected, and declare type NAME = item-type
in the XQuery Prolog);
and simple inline functions (for example .{. + 1}
).
ALLOW_UNRESOLVED_SCHEMA_COMPONENTS
The W3C XSD specification (both 1.0 and 1.1) states that an unresolved reference to an absent schema component does not automatically make the schema invalid; the schema should be usable for validation provided that the missing components are not actually needed in a particular validation episode.
However, the W3C XSD conformance tests treat such an unresolved reference as an error; the test is expected to report the schema as invalid. And this is the way most schema processors actually operate, and probably what most users would expect.
By default, the Saxon schema processor reports an unresolved reference as an error in the schema.
If this option is set, then Saxon attempts to repair the schema so that
it is usable for validation, by substituting the missing components with default
components: for example if an attribute declaration refers to a type that has
not been defined, then xs:error
is substituted, making any instance
of the attribute invalid.
ASSERTIONS_CAN_SEE_COMMENTS
ASSERTIONS_CAN_SEE_COMMENTS determines whether comment and processing instructions in a document being validated are visible to assertions in an XSD 1.1 schema.
If the value is false (the default), comments and processing instructions are stripped from the view of the document that is made visible to the XPath expression that implements the assertion. If this creates adjacent text nodes, they are collapsed into a single text node.
If the value is true, then comments and processing instructions are visible to the XPath assertion.
COLLATION_URI_RESOLVER
The supplied CollationURIResolver
is used to process any collation URIs
found in the query or stylesheet, returning an object of class
net.sf.saxon.lib.StringCollator that implements the requested
collation.
COMPILE_WITH_TRACING
If run-time tracing of stylesheet or query execution is required, then the code must be compiled with tracing enabled.
Default is false. This option causes code to be
compiled that makes calls to a net.sf.saxon.lib.TraceListener, but this
has no effect unless a TraceListener
is registered at execution
time.
CONFIGURATION
This attribute cannot be set on the net.sf.saxon.Configuration itself,
but it can be set on various JAXP factory objects such as a
TransformerFactory
or DocumentBuilderFactory
, to
ensure that several such factories use the same Configuration
.
Note that other configuration options are held in the Configuration
object,
so setting this attribute will cancel all others that have been set. Also, if two
factories share the same Configuration
, then setting an attribute on
one affects all the others.
CONFIGURATION_FILE
Defines a configuration file to be applied to the configuration.
This attribute cannot be set on the net.sf.saxon.Configuration itself, but it can be
set on various JAXP factory objects such as a TransformerFactory
or
DocumentBuilderFactory
. It is particularly useful when running
transformations via the Ant xslt task, where it can be set as follows to define all
configuration settings:
<factory name="net.sf.saxon.TransformerFactoryImpl"> <attribute
name="http://saxon.sf.net/feature/configuration-file"
value="c:/saxon/config.xml"/> </factory>
DEFAULT_COLLATION
This option determines the collation that is used for comparing strings when no explicit collation is requested. It is not necessary for this collation to exist (or to have been registered) when setting this option; it only needs to exist by the time it is used.
In XSLT it is possible to override this setting using the
[xsl:]default-collation
attribute on any stylesheet element. In
XQuery, it can be overridden using the declare default collation
declaration in the query prolog, or via a setter method in class
net.sf.saxon.query.StaticQueryContext.
If no value is specified, the Unicode codepoint collation is used.
DEFAULT_COLLECTION
This determines the collection that is used when the fn:collection()
function is called with no arguments; the effect is the same as if it were called
passing the URI that is the value of this configuration property.
DEFAULT_COUNTRY
This determines the country that is used by format-date()
and similar
functions if no country code is supplied explicitly. If no value is given for this
property, the default is taken from the Java Locale, which in turn typically depends
on settings for the current user in the operating system.
DEFAULT_LANGUAGE
This option determines the language that is used by format-date()
,
xsl:number
and similar constructs if no language code is supplied
explicitly. If no value is given for this property, the default is taken from the
Java Locale, which in turn typically depends on settings for the current user in the
operating system.
DISABLE_XSL_EVALUATE
This option disables the xsl:evaluate
instruction.
If set at stylesheet compile time, the feature is statically disabled. If set at run-time it is dynamically disabled. (These terms are defined in the XSLT 3.0 spec.) By default, the feature is enabled.
The XSLT 3.0 specification requires conformant processors to provide a way of
disabling xsl:evaluate
. This shouldn't be taken as meaning that
xsl:evaluate
poses particular security risks. The main reason for disabling it
is if you want to carry out static analysis or inspection of stylesheet code to see
what
features it uses. But if you're doing such inspection, it's not difficult to check
that
xsl:evaluate
is only being used to execute trusted code. Note also that
fn:transform()
can similarly be used to execute dynamically-constructed code,
and there is no switch to disable that function.
DTD_VALIDATION
If true, the XML parser is requested to perform validation of source documents against their DTD. Default is false.
This option establishes a default for use whenever source documents (not stylesheets
or schema documents) are parsed. The option can be overridden for individual
documents by setting the net.sf.saxon.lib.ParseOptions for that
individual document, for example from a URIResolver
.
EAGER_EVALUATION
Forces Saxon to do eager evaluation of expressions in contexts where normally it would do lazy evaluation, for example when evaluating variables and function results. This can make for easier debugging.
Note that this only applies to situations where Saxon would normally save a Closure
object as the result of an expression. It does not prevent Saxon from using pipelined
evaluation of
intermediate expressions using iterators.
ENVIRONMENT_VARIABLE_RESOLVER
Setting the ENVIRONMENT_VARIABLE_RESOLVER
causes the supplied object to
be registered as the environment variable resolver for the
Configuration
. The setting is global: it affects all queries and
transformations using this configuration.
The environment variable resolver is used when the XPath functions
available-environment-variables()
or
environment-variable()
are called. Saxon essentially delegates the
evaluation of the function to the external resolver.
ENVIRONMENT_VARIABLE_RESOLVER_CLASS
Not applicable to SaxonCS
EXPAND_ATTRIBUTE_DEFAULTS
EXPAND_ATTRIBUTE_DEFAULTS
determines whether fixed and default values
defined in a schema or DTD will be expanded (both on input and on output documents,
if validation is requested).
By default (and for conformance with the specification) validation against a DTD or schema will cause default values defined in the schema or DTD to be inserted into the document. Setting this feature to false suppresses this behavior. In the case of DTD-defined defaults this only works if the XML parser reports whether each attribute was specified in the source or generated by expanding a default value. Not all XML parsers report this information.
EXPATH_FILE_DELETE_TEMPORARY_FILES
Not applicable to SaxonCS
IMPLICIT_SCHEMA_IMPORTS
IMPLICIT_SCHEMA_IMPORTS
allows reference to schema components without an xs:import
for the relevant namespace being
present in the containing schema document.
This only works if the referenced components are already present among the schema components known to the configuration, perhaps because they were part of a different schema, or because there are cyclic references within a schema.
This option is not conformant with the XSD specification, which requires explicit
xs:import
declarations
for all cross-namespace component references. However, some "industry-standard" schemas
are known to violate this rule,
and setting this option allows such schemas to be loaded by Saxon.
LICENSE_FILE_LOCATION
LICENSE_FILE_LOCATION
holds the filename in which the Saxon license file
is held.
This is the full file name, for example c:/saxon/license/license.lic
.
Setting this property causes Saxon to
immediately read the specified file and register the license data, assuming it can
be found at this location. The property is not recognized for reading, and it is not
recognized for writing except in Saxon-PE and Saxon-EE.
LINE_NUMBERING
Default is false. If true, line and column number information is retained for all
source documents. This information is accessible using the
saxon:line-number()
and saxon:column-number()
extension functions.
Note that the information is only as good as the XML parser supplies. SAX parsers generally report the position of an element node using the line and column number of the ">" character that forms the last character of the start tag.
When this option is set, location information attached to a node (system ID, line number, and column number) is retained when the node is copied. This has the side effect that the base URI of a node is also copied, which in some cases runs contrary to the XSLT or XQuery specification.
MODULE_URI_RESOLVER
Affects XQuery only. An instance of a user-written class implementing Saxon's
net.sf.saxon.lib.ModuleURIResolver interface. This is used to
process any URIs used in import module
directives in XQuery.
MULTIPLE_SCHEMA_IMPORTS
Affects schema construction (whether for standalone validation, or in the context of XSLT or XQuery).
If set to true, the schema processor attempts to fetch a schema
document appearing in an xs:import
directive, whether or not a schema
for that namespace has already been loaded, unless the absolute URI formed from the
schemaLocation
is the same as the absolute URI that was used to
load that namespace. If set to false, the schema processor ignores the
schemaLocation
on an xs:import
declaration if schema
components for the requested namespace are already available. Note that setting the
value to true might cause spurious errors due to like-named schema components being
loaded more than once. On the other hand, setting the value to false might result
in
validation failing because schema components are missing.
Note: Both settings are conformant with the W3C recommendation, which leaves the
details implementation-defined. It is possible (and advisable) to write schemas in
such a way that this setting makes no difference, by ensuring that all imports for
a
particular namespace go via a "home" schema document for that namespace, where the
home schema document contains xs:include
declarations for all the
schema documents defining components in that namespace.
NAME_POOL
Indicates that the supplied NamePool
should be used as the target
(run-time) NamePool
by all stylesheets compiled (using
newTemplates()
) after this call on setAttribute
.
Normally a single system-allocated NamePool
is used for all stylesheets
compiled while the Java VM remains loaded; this attribute allows user control over
the allocation of name pools. Note that source trees used as input to a
transformation must be built using the same NamePool
that is used when
the stylesheet is compiled: this will happen automatically if the input to a
transformation is supplied as a SAXSource
or StreamSource
but it is under user control if you build the source tree yourself.
This option can be used to make two Configuration
objects share a
NamePool
even though they differ in other respects.
OCCURRENCE_LIMITS
OCCURRENCE_LIMITS
determines the largest values of
minOccurs
and maxOccurs
that can be accommodated when
compiling an "expanded" finite state machine to represent an XSD content model
grammar.
These limits do not apply in the common cases where the grammar can be
implemented using a counting finite-state-machine, but in those cases where this is
not possible, any minOccurs
value greater than the first integer is
reduced to the value of the first integer, and any maxOccurs
value
greater than the second integer is treated as "unbounded".
Setting these values too high may cause an OutOfMemoryException
since
the size of the finite state machine constructed by Saxon increases linearly with
the values of minOccurs
and maxOccurs
.
OPTIMIZATION_LEVEL
Allows individual optimizations to be enabled or disabled selectively.
There is a set of single-letter flags identifying particular optimizations:
- c: no longer used
- e: cache regular expressions
- f: inline functions
- g: extract global variables
- j: just-in-time compilation of template rules
- k: create keys
- l: loop lifting
- m: miscellaneous
- n: constant folding
- r: template rule-sets
- s: extract common subexpressions
- v: inline variables
- w: create switch statements
- x: index predicates
A value such as gs
runs with only the selected optimizations;
-gs
runs with the selected optimizations disabled and all others enabled. The
value 0
suppresses all optimizations. The default is full optimization; this
feature allows optimization to be suppressed in cases where reducing compile time
is
important, or where optimization gets in the way of debugging, or causes extension
functions with side-effects to behave unpredictably. (Note however, that even with
no optimization, lazy evaluation may still cause the evaluation order to be not as
expected.)
Note that disabling optimizations may prevent streamed execution. This is because there are cases where streamed execution is only possible because the optimizer is able to detect that sorting nodes into document order is unnecessary.
PRE_EVALUATE_DOC_FUNCTION
If true, calls on the doc()
and document()
functions, if
their arguments are known at compile time, will be evaluated at compile time, and
the resulting document will be stored as part of the Saxon
net.sf.saxon.Configuration and shared by all queries and
transformations running within that Configuration
.
This is useful for reference documents that have stable content and are used by many different queries and transformations. The default is false, which means each query or transformation will reload the document from disk.
In XSLT 3.0 a better way of having external documents pre-loaded at stylesheet compile time is to use the new facility of static global variables.
This feature should not be enabled when stylesheets are exported to a SEF file, since embedded source documents within a SEF file cannot always be accurately reconstructed.
When URIs are pre-evaluated, neither the ResourceResolver
associated
with the relevant Compiler
, nor the relevant run-time ResourceResolver
are used to resolve the URI. Only the Configuration-level ResourceResolver
is used.
RECOGNIZE_URI_QUERY_PARAMETERS
True if the doc()
or document()
are to recognize query parameters included in the
URI (for example, ?validation=strict
). The
default is false.
The allowed parameters are: validation=strict|lax|strip
to perform schema
validation (see Validation of
source documents); strip-space=yes|ignorable|no
to control whitespace
stripping (see Whitespace
stripping in source documents); parser=full.class.name
to
determine the name of the parser (XMLReader) to be used (see Controlling parsing of source
documents); and xinclude=yes|no
to control whether XInclude
processing takes place, assuming the XML parser supports it (see XInclude processing).
RECOVERY_POLICY
At one time this property controlled how recoverable errors were handled (fatal error, warning, or ignored). XSLT 3.0 has eliminated all recoverable errors from the specification, so the property is deprecated from Saxon 10.0.
RECOVERY_POLICY_NAME
At one time this property controlled how recoverable errors were handled (fatal error, warning, or ignored). XSLT 3.0 has eliminated all recoverable errors from the specification, so the property is deprecated from Saxon 10.0.
REGEX_BACKTRACKING_LIMIT
This property sets a limit on the amount of backtracking performed during regular expression evaluation.
The default is 10000000 (ten million) which typically represents an evaluation time of about ten seconds. After this time, evaluation of the regular expression will fail rather than making further attempts to find a match. If this limit is reached, it often suggests that there might be a better way of writing the regular expression. The value can be set to -1 (minus one) to mean "unlimited".
Excessive backtracking is usually caused by nested loops in the regular expression,
combined with processing
of long input strings. Try to ensure that when nested loops are used, there is an
unambiguous condition that causes
the inner loop to terminate. For example (/[^/]*)+
is fine (it matches a sequence of path segments separated
by /
characters), because the presence of /
forces the inner loop to terminate. By contrast,
(/.*)+
matches the same input, but in many different ways, which could lead to excessive
backtracking
to no useful purpose.
RESOURCE_RESOLVER
The supplied implementation of ResourceResolver
is used to
resolve URIs. The default implementation uses XML Catalog files.
The Saxon resource resolver is used by the entity resolver, URI resolver,
unparsed text resolver, and other resolvers that resolve URIs to resources.
RESULT_DOCUMENT_THREADS
Indicates the maximum number of threads to be used for processing
xsl:result-document
instructions in parallel. If the maximum number
of threads are already in use, the xsl:result-document
instruction will
be executed synchronously within its parent thread.
The default value is initialized to
Runtime.getRuntime().availableProcessors()
which is intended to
represent the number of "processors" (under some definition) available from the
hardware.
The limit applies per Configuration
. If multiple workloads are running
on the same server under separate Saxon Configuration
objects, then it
may be desirable to lower the limit.
Setting a value of zero or one suppresses multithreading entirely. This can also be
achieved (for a specific xsl:result-document
instruction) by setting
the attribute saxon:asynchronous="no"
in the stylesheet. Suppressing
multithreading may be desirable in a stylesheet that calls extension functions with
side-effects.
RETAIN_NODE_FOR_DIAGNOSTICS
By default, Saxon attempts to ensure that the run-time code contains no links to the original source stylesheet tree. This allows the garbage collector to free memory.
If this option is set, then Location
objects held in the run-time expression tree may contain a link
to an element node in the source stylesheet, enabling a user-written ErrorReporter
to produce
improved diagnostics. This may be an appropriate setting to use, for example, in an
IDE.
This setting can also be useful to get improved location information for compile-time errors in cases where reliable line numbers are not available for the source stylesheet. This might happen, for example, if the source stylesheet is preprocessed before compilation, or if it is retrieved from an XML database.
Links to source nodes are not retained in an exported SEF file, regardless of this setting.
SCHEMA_URI_RESOLVER
The supplied SchemaURIResolver
will be used to resolve URIs of schema
documents referenced in xsl:import-schema
declarations in XSLT,
import schema
in XQuery, references from one schema document to
another using xs:include
or xs:import
, and references from
an instance document to a schema using xsi:schemaLocation
.
SCHEMA_VALIDATION
Indicates whether and how schema validation should be applied to source documents.
SCHEMA_VALIDATION_MODE
Indicates whether and how schema validation should be applied to source documents.
STABLE_COLLECTION_URI
STABLE_COLLECTION_URI
, if set, indicates that collections returned by
the fn:collection()
and fn:uri-collection()
functions
should be stable, that is, repeated calls on these functions with the same
collection URI (within the scope of a single query or transformation) should return
identical results.
Setting this option may be expensive because it requires that the entire collection be saved in memory; it is rarely necessary in practice, but is required for strict conformance with the W3C specifications.
It is also possible to indicate that a collection is stable by means of the
CollectionFinder
API.
STABLE_UNPARSED_TEXT
STABLE_UNPARSED_TEXT
, if set, indicates that the results returned by
repeated calls of unparsed-text()
, unparsed-text-lines()
,
and unparsed-text-available()
are consistent: calling these functions
twice during the evaluation of a stylesheet or query will return the same
results.
Setting this option may be expensive because it requires that the file contents be saved in memory; it is rarely necessary in practice, but is required for strict conformance with the W3C specifications.
STANDARD_ERROR_OUTPUT_FILE
STANDARD_ERROR_OUTPUT_FILE
is the name of a file to which Saxon will
redirect output that would otherwise go to the operating system standard error
stream (System.err). This is the fallback destination for various tracing and
diagnostic output. In some cases a more specific mechanism exists to select the
destination for particular kinds of output.
Note that if the Configuration
is used in more than one processing
thread, the messages from different threads will be interleaved in the output file.
A more selective approach is to use a different ErrorListener
in
different processing threads, and arrange for each ErrorListener
to
write to its own logging destination.
STREAMABILITY
The STREAMABILITY
option can be used to disable streaming.
In earlier Saxon releases a third value "extended" was supported, to enable Saxon streaming extensions. Since nearly all these extensions found their way into the W3C specification, the distinction between "standard" and "extended" became meaningless, so the value "extended" has been dropped.
The value "off" causes Saxon to behave as a non-streaming processor; that is, it does not analyze constructs that are declared streamable, and it processes them as if streaming were not requested. This is the only option available when using a Saxon version or license that does not enable streaming.
The value "standard" is a misnomer. For strict adherence to W3C streamability rules,
set the property STRICT_STREAMABILITY
. The streamability rules applied
by default are (in nearly all cases) identical to the W3C rules, but by default they
are applied to the expression tree after type-checking and optimization, which makes
some constructs streamable that would not be so otherwise.
Whichever option is chosen, the STREAMING_FALLBACK
option can be used to
control what happens when code is deemed non-streamable; it provides a choice
between throwing a static (compile-time) error, and falling back to a non-streaming
implementation.
STREAMING_FALLBACK
If the STREAMING_FALLBACK
option is set, then constructs for which
streaming is requested (such as templates in a streaming mode, the
xsl:source-document
instruction with attribute
streamable="yes"
, and streamable accumulators) will be executed in
non-streaming mode if the code is not actually streamable. A compile-time warning
will always be given when the fallback option is taken.
STRICT_STREAMABILITY
Causes the XSLT processor to verify that constructs that are declared streamable are in fact "guaranteed streamable" according to the W3C rules.
Normally, Saxon performs a variety of simplifications and optimizations on the
expression tree before performing streamability analysis. Sometimes these tree
rewrites will turn a non-streamable expression into a streamable one. An obvious
example is variable inlining: the expression let $x := ./item/price return
sum($x)
is not streamable, but the rewritten form
sum(./item/price)
is.
The XSLT 3.0 specification requires conformant streaming processors to have a mode of operation in which the streamability rules are enforced as they appear in the spec, and this option enables this mode.
This analysis is expensive, and should only be used during development when testing stylesheet code for portability. When this mode is enabled, Saxon applies the streamability rules at the earliest possible stage of processing; it then performs its normal type checking and optimization phases, before doing a second stage of streamability analysis to construct a streamed execution plan.
STRIP_WHITESPACE
Indicates whether all whitespace, no whitespace, or whitespace in elements defined in a DTD or schema as having element-only content should be stripped from source documents.
The default is "ignorable". This whitespace stripping is additional to
any stripping done as a result of the xsl:strip-space
declaration in an
XSLT stylesheet.
SUPPRESS_EVALUATION_EXPIRY_WARNING
This is set to true to suppress the warning otherwise issued by command-line interfaces indicating that an evaluation license is in use and is due to expire in a set number of days.
SUPPRESS_XPATH_WARNINGS
Suppresses all warnings issued by the XPath and XQuery parsers.
Examples of warnings that are suppressed are the warning produced when keywords such
as true
and return
are interpreted as element names.
SUPPRESS_XSLT_NAMESPACE_CHECK
This is set to true to suppress the warning when there is no commonality between the namespaces used in stylesheet match patterns and the namespaces used in the source document.
THRESHOLD_FOR_FUNCTION_INLINING
Saxon-EE performs inlining of user-defined functions that are sufficiently simple: they must not be recursive, and they must be below a certain size. This option defines the size.
The value is (roughly) the number of nodes in the expression tree representing the function body. This includes both explicit subexpressions, and subexpressions added by Saxon itself to perform implicit operations such as type checking or conversion of function arguments. The default value is 100.
THRESHOLD_FOR_HOTSPOT_BYTE_CODE
Not applicable to SaxonCS
TIMING
This is set to true to cause basic timing and tracing information to be output to the standard error output stream.
The name of the feature is poorly chosen, since much
of the information that is output has nothing to do with timing, for example the
names of output files for xsl:result-document
are traced, as are the
names of schema documents loaded.
TRACE_LISTENER
The TraceListener
will be notified of significant events occurring
during a query or transformation, for tracing or debugging purposes.
Setting a TraceListener
automatically sets the
FeatureKeys.COMPILE_WITH_TRACING option.
Avoid this option if more than one transformation or query is running concurrently:
use the feature FeatureKeys.TRACE_LISTENER_CLASS
instead. Alternatively, it is possible to set a TraceListener
for an
individual query or transformation.
TRACE_LISTENER_OUTPUT_FILE
When trace listening is switched on (for example by using -T on the command line), this file will be supplied to the trace listener to use as the output destination. If the option is not supplied, trace listener output is sent to the standard error stream.
TRACE_OPTIMIZER_DECISIONS
If this option is set, Saxon will output (to the standard error output) detailed information about the rewrites to the expression tree made by the optimizer. This information is mainly useful for internal system debugging, but it is also possible to digest it to analyze the ways in which the expression has been optimized for the purpose of performance analysis and tuning.
TREE_MODEL
Selects an implementation of the Saxon tree model. The default is
TINY_TREE
.
For running XQuery Update, use the linked tree, because it is the only implementation that is updateable.
TREE_MODEL_NAME
Selects an implementation of the Saxon tree model. The default is
tinyTree
.
For running XQuery Update, use the linked tree, because it is the only implementation that is updateable.
UNPARSED_TEXT_URI_RESOLVER
The supplied UnparsedTextURIResolver
will be used to resolve
(dereference) all URIs specifed in calls to the unparsed-text()
,
unparsed-text-lines()
, and unparsed-text-available()
functions.
UNPARSED_TEXT_URI_RESOLVER_CLASS
Not applicable to SaxonCS
USE_PI_DISABLE_OUTPUT_ESCAPING
Not applicable to SaxonCS
USE_TYPED_VALUE_CACHE
This option is relevant only when the TinyTree is used; it determines whether (for a validated document) a cache will be maintained containing the typed values of nodes.
Typed values are held in the cache only for elements and attributes whose type is other than string, untypedAtomic, or anyURI. The default value is true. Setting this value to false can reduce memory requirements at the cost of requiring recomputation of typed values on each access.
USE_XSI_SCHEMA_LOCATION
This option determines whether or not to use the xsi:schemaLocation
and xsi:noNamespaceSchemaLocation
attributes in an instance
document to locate a schema for validation.
Note, these attribute are only consulted if validation is requested; the presence of one of these attributes never by itself triggers validation.
VALIDATION_COMMENTS
This option determines whether non-fatal validation errors in XQuery or XSLT result
documents should result in comments being inserted into the result tree. The
command-line flag -outval:recover
sets both this option and the
FeatureKeys.VALIDATION_WARNINGS option.
VALIDATION_WARNINGS
This option indicates (if true) that errors occuring while validating a final result tree are not to be treated as fatal.
Regardless of the setting of this option, all validation errors are reported to the
error()
method of the ErrorListener
, and validation is
terminated if the error()
method throws an exception, or if the error
limit set in the ParseOptions
object is reached.
This option primarily controls what happens at the end of a validation episode. If the validation episode detected one or more validation errors, then when this option is off, an exception is thrown, which will normally result in any query or stylesheet failing with a dynamic error, and no output file being written. If the option is on, no exception is thrown, and the output is written as if validation had been successful. Note in this case that any type annotations present in a result document are unreliable.
If this option is set when running XSLT or XQuery, it is ignored as far as input files are concerned: validation errors in input files are still fatal. However, if the option is set and a validation error occurs in a final output file, the output file is still written and the process terminates as if successful.
The detailed interpretation of this option changed in Saxon 9.5.
VERSION_WARNING
Indicates whether a warning message should be notified (to the
ErrorListener
) if running Saxon against an XSLT stylesheet that
specifies version="1.0"
.
From Saxon 9.8, the warning is no longer output (since XSLT 3.0 does not require it), so this option is ignored.
XML_VERSION
This determines the XML version used by the Configuration
.
Note that source documents specifying xml version="1.0"
or
"1.1"
are accepted regardless of this setting. The effect of this
switch is to change the validation rules for types such as xs:Name
and
xs:NCName
, to change the characters allowed in names within XPath
expressions (etc.), to change the meaning of \i
and \c
in
regular expressions, and to determine whether the serializer allows XML 1.1
documents to be constructed.
The default is 1.0.
SaxonCS uses the System.Xml
parser, which does not support XML 1.1.
XPATH_VERSION_FOR_XSD
The XSD 1.1 specification states that XPath version 2.0 is used for expressions appearing in assertions and type alternatives. This option allows XPath 3.0 or 3.1 to be used instead.
The recognized values are the integers 20, 30, and 31 representing versions 2.0, 3.0, and 3.1 respectively.
XPATH_VERSION_FOR_XSLT
The XSLT 3.0 specification states that processors are required to support XPath 3.0 expressions within stylesheets, together with some extensions (maps) selected from the XPath 3.1 specification. Support for the full syntax of XPath 3.1 is optional, but it is the default in Saxon. This option allows a different XPath language level to be selected.
The integer values 20, 30, and 31 denote XPath 2.0, 3.0, and 3.1 respectively, while the value 305 denotes XPath 3.0 with the extensions defined in the XSLT 3.0 specification.
XQUERY_ALLOW_UPDATE
Determines whether XQuery Update syntax is accepted.
If true, update syntax is accepted, if false, it is not accepted. Setting the value to true does not mean that the query has to use update syntax, only that it may do so.
From Saxon 9.6, XQuery Update syntax and XQuery 3.0 syntax can be mixed, although this combination is not defined by any W3C specification at the time of writing.
This option can be set for a particular XQuery compilation. When the option is set
at
the Configuration
level, it acts as a default.
On the command line, this option is combined with the option "discard" which indicates that updates are allowed, but the updates are not written back to filestore. This does not correspond to any option in the Java API, where writing an updated document back to filestore only happens if explicitly requested.
XQUERY_CONSTRUCTION_MODE
This option defines the default value of the construction mode in the XQuery static context (overridable in the query prolog).
This option can be set for a particular XQuery compilation. When the option is set
at
the Configuration
level, it acts as a default.
XQUERY_DEFAULT_ELEMENT_NAMESPACE
This property defines the default namespace for elements and types that are not qualified by a namespace prefix.
This option can be set for a particular XQuery compilation. When the option is set
at
the Configuration
level, it acts as a default.
XQUERY_DEFAULT_FUNCTION_NAMESPACE
This property defines the default namespace for function names that are not qualified by a namespace prefix.
This option can be set for a particular XQuery compilation. When the option is set
at
the Configuration
level, it acts as a default.
XQUERY_EMPTY_LEAST
This property defines how the empty sequence is handled in XQuery sorting (the "order
by" clause). If true, ()
comes at the start of the sorted sequence; if
false, it comes last.
This option can be set for a particular XQuery compilation. When the option is set
at
the Configuration
level, it acts as a default.
XQUERY_INHERIT_NAMESPACES
This property defines the default value of the inherit-namespaces
property in the XQuery static context.
This option can be set for a particular XQuery compilation. When the option is set
at
the Configuration
level, it acts as a default.
XQUERY_MULTIPLE_MODULE_IMPORTS
If the value is false, then when an import module
declaration is
encountered for a module URI that is already among the known loaded modules (or
modules in the process of being compiled), the import module
is treated
as a reference to the existing module. If the value is true, the system first checks
whether the supplied "location hints" match the known location of the existing
module, and the existing module is used only if there is a match.
XQUERY_PRESERVE_BOUNDARY_SPACE
This property defines whether "boundary space" (insignificant space in direct element constructors) should be retained or not.
This option can be set for a particular XQuery compilation. When the option is set
at
the Configuration
level, it acts as a default.
XQUERY_PRESERVE_NAMESPACES
This property defines whether unused namespace declarations are retained by XQuery element copy operations.
This option can be set for a particular XQuery compilation. When the option is set
at
the Configuration
level, it acts as a default.
XQUERY_REQUIRED_CONTEXT_ITEM_TYPE
This property defines the default expected context item type for a query.
This option can be set for a particular XQuery compilation. When the option is set
at
the Configuration
level, it acts as a default.
XQUERY_SCHEMA_AWARE
A query will automatically be schema-aware if it contains an import
schema
declaration. This property allows a query to be marked as
schema-aware even if it contains no import schema
declaration. It is
necessary for a query to be compiled as schema-aware if it is to handle typed
(validated) input documents in which nodes have type annotations based on their
schema-defined type.
This option can be set for a particular XQuery compilation. When the option is set
at
the Configuration
level, it acts as a default.
XQUERY_STATIC_ERROR_LISTENER_CLASS
Not applicable to SaxonCS
XQUERY_VERSION
This property determines the version of XQuery used by the
Configuration
.
Indicates the version of XQuery syntax that is accepted. From Saxon 9.8, an XQuery 3.1 processor is always used by default. So setting this property to a value less than 3.1 is no longer allowed. The value "4.0" enables experimental syntax extensions that are under discussion in the XML community, and subject to change.
XSD_VERSION
This property determines the version of XML Schema used by the
Configuration
.
From Saxon 9.8, the default is XSD 1.1. If XSD 1.0 is selected, XSD 1.1 features will be rejected, with the exception of the version control attributes that allow sections of the schema to be marked as requiring XSD 1.0 or XSD 1.1.
XSLT_ENABLE_ASSERTIONS
This property indicates whether assertions (XSLT 3.0 xsl:assert instructions) are enabled or disabled. They are disabled by default. Setting this property on causes assertions to be enabled at compile time for all XSLT packages compiled using the default configuration options.
This option can be set for a particular XSLT compilation. When the option is set at
the Configuration
level (or on a TransformerFactory
), it
acts as a default.
If assertions have been enabled at compile time for a particular package, they can
still be disabled at run-time (for all packages) by setting an option on the
Xslt30Transformer
. But if assertions were disabled at compile time,
enabling them at run-time has no effect.
XSLT_INITIAL_MODE
This property indicates the name of a mode within a stylesheet in which execution (using template rules) should begin.
This option can be set for a particular XSLT transformation. When the option is set
at the Configuration
(or on a TransformerFactory
), it acts
as a default.
XSLT_INITIAL_TEMPLATE
This property indicates the name of a named template within a stylesheet where execution should begin.
This option can be set for a particular XSLT transformation. When the option is set
at the Configuration
level (or on a TransformerFactory
),
it acts as a default.
Specifically, if the transformation is performed using the transform()
method of class net.sf.saxon.s9api.XsltTransformer
, then the transformation
will proceed by calling the relevant named template, rather than by applying templates
to the supplied source node. It will also affect other APIs built on top of the
XsltTransformer
, notably the JAXP transformation interface, which in turn
is used by many higher-level interfaces such as Ant. Indeed, the main purpose of this
configuration option is to allow named-template stylesheet invocation using the JAXP
interface, which was designed without this feature in mind.
This configuration option is ignored when using an net.sf.saxon.s9api.Xslt30Transformer
,
or other interfaces built on top of an Xslt30Transformer
, for example the
net.sf.saxon.Transform
command line interface.
XSLT_SCHEMA_AWARE
This property indicates whether stylesheets should be compiled with the ability to
handle schema-typed input documents. By default a stylesheet is compiled to handle
such input if it contains an xsl:import-schema
instruction, and not
otherwise. It is necessary for a stylesheet to be compiled as schema-aware if it is
to handle typed (validated) input documents in which nodes have type annotations
based on their schema-defined type.
This option can be set for a particular XSLT compilation. When the option is set at
the Configuration
level (or on a TransformerFactory
), it
acts as a default.
XSLT_STATIC_ERROR_LISTENER_CLASS
Not applicable to SaxonCS
XSLT_STATIC_URI_RESOLVER_CLASS
Not applicable to SaxonCS
XSLT_VERSION
This property determines the version of XSLT to be supported by default.
From Saxon 9.8, an XSLT 3.0 processor is always used by default. So setting this property to a value less than 3.0 has no effect.
The value 4.0 enables experimental syntax extensions, under discussion in the XML community, which are subject to change.