net.sf.saxon
Class Configuration

java.lang.Object
  |
  +--net.sf.saxon.Configuration
All Implemented Interfaces:
java.io.Serializable

public class Configuration
extends java.lang.Object
implements java.io.Serializable

This class holds details of user-selected configuration options for a transformation or query

See Also:
Serialized Form

Field Summary
static int DO_NOT_RECOVER
          Constant indicating that when a recoverable error occurs, the processor should not attempt to take the defined recovery action, but should terminate with an error.
static int RECOVER_SILENTLY
          Constant indicating that the processor should take the recovery action when a recoverable error occurs, with no warning message.
static int RECOVER_WITH_WARNINGS
          Constant indicating that the processor should produce a warning when a recoverable error occurs, and should then take the recovery action and continue.
static int XQUERY
          Constant indicating that the host language is XQuery
static int XSLT
          Constant indicating that the host language is XSLT
 
Constructor Summary
Configuration()
          Create a configuration object with default settings for all options
 
Method Summary
 void addQueryLibraryModule(StaticQueryContext module)
          Add an XQuery library module to the configuration
 void addSchema(SchemaMarker schema)
          Add a schema to the cache
 SchemaType getAttributeType(SchemaComponentMarker attributeDecl)
          Get the schema type corresponding to an attribute declaration
 ValidationContext getContainedValidationContext(ValidationContext outer, int fingerprint, boolean isType)
          Get a validation context nested within an existing validation context (XQuery only)
 Receiver getDocumentValidator(Receiver receiver, java.lang.String systemId, NamePool namePool, int validationMode)
          Get a document-level validator to add to a Receiver pipeline
 SchemaType getElementType(SchemaComponentMarker attributeDecl)
          Get the schema type corresponding to an element declaration
 Receiver getElementValidator(Receiver receiver, int nameCode, SchemaType schemaType, int validation, ValidationContext context, NamePool pool)
          Get a Receiver that can be used to validate an element
 javax.xml.transform.ErrorListener getErrorListener()
          Get the ErrorListener used in this configuration.
 int getHostLanguage()
          Get the host language used in this configuration.
static java.util.Locale getLocale(java.lang.String lang)
          Get a locale given a language code in XML format
 java.lang.String getMessageEmitterClass()
          Get the name of the class that will be instantiated to create a MessageEmitter, to process the output of xsl:message instructions.
 OutputURIResolver getOutputURIResolver()
          Get the OutputURIResolver that will be used to resolve URIs used in the href attribute of the xsl:result-document instruction.
 StaticQueryContext getQueryLibraryModule(java.lang.String namespace)
          Locate an XQuery library module in the configuration.
 int getRecoveryPolicy()
          Determine how recoverable run-time errors are to be handled.
 SchemaMarker getSchema(java.lang.String namespace)
          Get a schema from the cache.
 org.xml.sax.XMLReader getSourceParser()
          Get the parser for source documents
 java.lang.String getSourceParserClass()
          Get the name of the class that will be instantiated to create an XML parser for parsing source documents (for example, documents loaded using the document() or doc() functions).
 org.xml.sax.XMLReader getStyleParser()
          Get the parser for stylesheet documents
 java.lang.String getStyleParserClass()
          Get the name of the class that will be instantiated to create an XML parser for parsing stylesheet modules.
 NamePool getTargetNamePool()
          Get the target namepool to be used for stylesheets/queries and for source documents.
 TraceListener getTraceListener()
          Get the TraceListener used for run-time tracing of instruction execution.
 int getTreeModel()
          Get the Tree Model used by this Configuration.
 javax.xml.transform.URIResolver getURIResolver()
          Get the URIResolver used in this configuration
 boolean isAllowExternalFunctions()
          Determine whether calls to external Java functions are permitted.
 boolean isLineNumbering()
          Determine whether source documents will maintain line numbers, for the benefit of the saxon:line-number() extension function as well as run-time tracing.
 boolean isSchemaAware()
          Determine if the configuration is schema-aware
 boolean isSchemaValidation()
          Determine whether source documents (supplied as a StreamSource or SAXSource) should be subjected to schema validation
 boolean isStripsAllWhiteSpace()
          Determine whether whitespace-only text nodes are to be stripped unconditionally from source documents.
 boolean isTiming()
          Determine whether brief progress messages and timing information will be output to System.err
 boolean isTraceExternalFunctions()
          Determine whether calls on external functions are to be traced for diagnostic purposes.
 boolean isValidation()
          Determine whether the XML parser for source documents will be asked to perform DTD validation of source documents
static org.xml.sax.XMLReader makeParser(java.lang.String className)
          Create a new SAX XMLReader object using the class name provided.
 NodeTest makeSubstitutionGroupTest(SchemaComponentMarker elementDecl)
          Make a test for elements corresponding to a give element declaration
 java.lang.String readSchema(java.lang.String baseURI, java.lang.String schemaLocation, java.lang.String expected)
          Read a schema from a given schema location
 void setAllowExternalFunctions(boolean allowExternalFunctions)
          Determine whether calls to external Java functions are permitted.
 void setErrorListener(javax.xml.transform.ErrorListener listener)
          Set the ErrorListener to be used in this configuration.
 void setHostLanguage(int hostLanguage)
          Set the host language used in this configuration.
 void setLineNumbering(boolean lineNumbering)
          Determine whether source documents will maintain line numbers, for the benefit of the saxon:line-number() extension function as well as run-time tracing.
 void setMessageEmitterClass(java.lang.String messageEmitterClass)
          Set the name of the class that will be instantiated to create a MessageEmitter, to process the output of xsl:message instructions.
 void setOutputURIResolver(OutputURIResolver outputURIResolver)
          Set the OutputURIResolver that will be used to resolve URIs used in the href attribute of the xsl:result-document instruction.
 void setRecoveryPolicy(int recoveryPolicy)
          Determine how recoverable run-time errors are to be handled.
 void setSchemaValidation(boolean validate)
          Indicate whether source documents (supplied as a StreamSource or SAXSource) should be subjected to schema validation
 void setSourceParserClass(java.lang.String sourceParserClass)
          Set the name of the class that will be instantiated to create an XML parser for parsing source documents (for example, documents loaded using the document() or doc() functions).
 void setStripsAllWhiteSpace(boolean stripsAllWhiteSpace)
          Determine whether whitespace-only text nodes are to be stripped unconditionally from source documents.
 void setStyleParserClass(java.lang.String styleParserClass)
          Set the name of the class that will be instantiated to create an XML parser for parsing stylesheet modules.
 void setTargetNamePool(NamePool targetNamePool)
          Set the NamePool to be used for stylesheets/queries and for source documents.
 void setTiming(boolean timing)
          Determine whether brief progress messages and timing information will be output to System.err
 void setTraceExternalFunctions(boolean traceExternalFunctions)
          Determine whether calls on external functions are to be traced for diagnostic purposes.
 void setTraceListener(TraceListener traceListener)
          Set the TraceListener to be used for run-time tracing of instruction execution.
 void setTreeModel(int treeModel)
          Set the Tree Model used by this Configuration.
 void setURIResolver(javax.xml.transform.URIResolver resolver)
          Set the URIResolver to be used in this configuration.
 void setValidation(boolean validation)
          Determine whether the XML parser for source documents will be asked to perform DTD validation of source documents
 int validateAttribute(int nameCode, java.lang.CharSequence value, int validation)
          Validate an attribute value
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

RECOVER_SILENTLY

public static final int RECOVER_SILENTLY
Constant indicating that the processor should take the recovery action when a recoverable error occurs, with no warning message.

See Also:
Constant Field Values

RECOVER_WITH_WARNINGS

public static final int RECOVER_WITH_WARNINGS
Constant indicating that the processor should produce a warning when a recoverable error occurs, and should then take the recovery action and continue.

See Also:
Constant Field Values

DO_NOT_RECOVER

public static final int DO_NOT_RECOVER
Constant indicating that when a recoverable error occurs, the processor should not attempt to take the defined recovery action, but should terminate with an error.

See Also:
Constant Field Values

XSLT

public static final int XSLT
Constant indicating that the host language is XSLT

See Also:
Constant Field Values

XQUERY

public static final int XQUERY
Constant indicating that the host language is XQuery

See Also:
Constant Field Values
Constructor Detail

Configuration

public Configuration()
Create a configuration object with default settings for all options

Method Detail

isSchemaAware

public boolean isSchemaAware()
Determine if the configuration is schema-aware


getHostLanguage

public int getHostLanguage()
Get the host language used in this configuration. The possible values are XSLT and XQUERY.

Returns:
Configuration.XSLT or Configuration.XQUERY

setHostLanguage

public void setHostLanguage(int hostLanguage)
Set the host language used in this configuration. The possible values are XSLT and XQUERY.

Parameters:
hostLanguage - Configuration.XSLT or Configuration.XQUERY

getURIResolver

public javax.xml.transform.URIResolver getURIResolver()
Get the URIResolver used in this configuration

Returns:
the URIResolver. If no URIResolver has been set explicitly, the default URIResolver is used.

setURIResolver

public void setURIResolver(javax.xml.transform.URIResolver resolver)
Set the URIResolver to be used in this configuration. This will be used to resolve the URIs used statically (e.g. by xsl:include) and also the URIs used dynamically by functions such as document() and doc(). Note that the URIResolver does not resolve the URI in the sense of RFC 2396 (which is also the sense in which the resolve-uri() function uses the term): rather it dereferences an absolute URI to obtain an actual resource, which is returned as a Source object.

Parameters:
resolver - The URIResolver to be used.

getErrorListener

public javax.xml.transform.ErrorListener getErrorListener()
Get the ErrorListener used in this configuration. If no ErrorListener has been supplied explicitly, the default ErrorListener is used.

Returns:
the ErrorListener.

setErrorListener

public void setErrorListener(javax.xml.transform.ErrorListener listener)
Set the ErrorListener to be used in this configuration. The ErrorListener is informed of all static and dynamic errors detected, and can decide whether run-time warnings are to be treated as fatal.

Parameters:
listener - the ErrorListener to be used

getTreeModel

public int getTreeModel()
Get the Tree Model used by this Configuration. This is either Builder.STANDRD_TREE or Builder.TINY_TREE. The default (confusingly) is Builder.TINY_TREE.

Returns:
the selected Tree Model

setTreeModel

public void setTreeModel(int treeModel)
Set the Tree Model used by this Configuration. This is either Builder.STANDRD_TREE or Builder.TINY_TREE. The default (confusingly) is Builder.TINY_TREE.

Parameters:
treeModel - the selected Tree Model

isLineNumbering

public boolean isLineNumbering()
Determine whether source documents will maintain line numbers, for the benefit of the saxon:line-number() extension function as well as run-time tracing.

Returns:
true if line numbers are maintained in source documents

setLineNumbering

public void setLineNumbering(boolean lineNumbering)
Determine whether source documents will maintain line numbers, for the benefit of the saxon:line-number() extension function as well as run-time tracing.

Parameters:
lineNumbering - true if line numbers are maintained in source documents

getTraceListener

public TraceListener getTraceListener()
Get the TraceListener used for run-time tracing of instruction execution.

Returns:
the TraceListener, or null if none is in use.

setTraceListener

public void setTraceListener(TraceListener traceListener)
Set the TraceListener to be used for run-time tracing of instruction execution.

Parameters:
traceListener - The TraceListener to be used.

getRecoveryPolicy

public int getRecoveryPolicy()
Determine how recoverable run-time errors are to be handled. This applies only if the standard ErrorListener is used. The options are RECOVER_SILENTLY, RECOVER_WITH_WARNINGS, or DO_NOT_RECOVER.

Returns:
the current recovery policy

setRecoveryPolicy

public void setRecoveryPolicy(int recoveryPolicy)
Determine how recoverable run-time errors are to be handled. This applies only if the standard ErrorListener is used. The options are RECOVER_SILENTLY, RECOVER_WITH_WARNINGS, or DO_NOT_RECOVER.

Parameters:
recoveryPolicy - the recovery policy to be used.

getMessageEmitterClass

public java.lang.String getMessageEmitterClass()
Get the name of the class that will be instantiated to create a MessageEmitter, to process the output of xsl:message instructions.

Returns:
the full class name of the message emitter class.

setMessageEmitterClass

public void setMessageEmitterClass(java.lang.String messageEmitterClass)
Set the name of the class that will be instantiated to create a MessageEmitter, to process the output of xsl:message instructions.

Parameters:
messageEmitterClass - the full class name of the message emitter class. This must implement net.sf.saxon.event.Emitter.

getSourceParserClass

public java.lang.String getSourceParserClass()
Get the name of the class that will be instantiated to create an XML parser for parsing source documents (for example, documents loaded using the document() or doc() functions).

Returns:
the fully qualified name of the XML parser class

setSourceParserClass

public void setSourceParserClass(java.lang.String sourceParserClass)
Set the name of the class that will be instantiated to create an XML parser for parsing source documents (for example, documents loaded using the document() or doc() functions).

Parameters:
sourceParserClass - the fully qualified name of the XML parser class. This must implement the SAX2 XMLReader interface.

getStyleParserClass

public java.lang.String getStyleParserClass()
Get the name of the class that will be instantiated to create an XML parser for parsing stylesheet modules.

Returns:
the fully qualified name of the XML parser class

setStyleParserClass

public void setStyleParserClass(java.lang.String styleParserClass)
Set the name of the class that will be instantiated to create an XML parser for parsing stylesheet modules.

Parameters:
styleParserClass - the fully qualified name of the XML parser class

getOutputURIResolver

public OutputURIResolver getOutputURIResolver()
Get the OutputURIResolver that will be used to resolve URIs used in the href attribute of the xsl:result-document instruction.

Returns:
the OutputURIResolver. If none has been supplied explicitly, the default OutputURIResolver is returned.

setOutputURIResolver

public void setOutputURIResolver(OutputURIResolver outputURIResolver)
Set the OutputURIResolver that will be used to resolve URIs used in the href attribute of the xsl:result-document instruction.

Parameters:
outputURIResolver - the OutputURIResolver to be used.

isTiming

public boolean isTiming()
Determine whether brief progress messages and timing information will be output to System.err

Returns:
true if these messages are to be output.

setTiming

public void setTiming(boolean timing)
Determine whether brief progress messages and timing information will be output to System.err

Parameters:
timing - true if these messages are to be output.

isAllowExternalFunctions

public boolean isAllowExternalFunctions()
Determine whether calls to external Java functions are permitted.

Returns:
true if such calls are permitted.

setAllowExternalFunctions

public void setAllowExternalFunctions(boolean allowExternalFunctions)
Determine whether calls to external Java functions are permitted. Allowing external function calls is potentially a security risk if the stylesheet or Query is untrusted, as it allows arbitrary Java methods to be invoked, which can examine or modify the contents of filestore and other resources on the machine where the query/stylesheet is executed

Parameters:
allowExternalFunctions - true if external function calls are to be permitted.

isTraceExternalFunctions

public boolean isTraceExternalFunctions()
Determine whether calls on external functions are to be traced for diagnostic purposes.

Returns:
true if tracing is enabled for calls to external Java functions

setTraceExternalFunctions

public void setTraceExternalFunctions(boolean traceExternalFunctions)
Determine whether calls on external functions are to be traced for diagnostic purposes.

Parameters:
traceExternalFunctions - true if tracing is to be enabled for calls to external Java functions

isValidation

public boolean isValidation()
Determine whether the XML parser for source documents will be asked to perform DTD validation of source documents

Returns:
true if DTD validation is requested.

setValidation

public void setValidation(boolean validation)
Determine whether the XML parser for source documents will be asked to perform DTD validation of source documents

Parameters:
validation - true if DTD validation is to be requested.

isSchemaValidation

public boolean isSchemaValidation()
Determine whether source documents (supplied as a StreamSource or SAXSource) should be subjected to schema validation

Returns:
true if source documents should be validated

setSchemaValidation

public void setSchemaValidation(boolean validate)
Indicate whether source documents (supplied as a StreamSource or SAXSource) should be subjected to schema validation

Parameters:
validate - true if source documents should be validated

getTargetNamePool

public NamePool getTargetNamePool()
Get the target namepool to be used for stylesheets/queries and for source documents.

Returns:
the target name pool. If no NamePool has been specified explicitly, the default NamePool is returned.

setTargetNamePool

public void setTargetNamePool(NamePool targetNamePool)
Set the NamePool to be used for stylesheets/queries and for source documents.

Parameters:
targetNamePool - The NamePool to be used.

isStripsAllWhiteSpace

public boolean isStripsAllWhiteSpace()
Determine whether whitespace-only text nodes are to be stripped unconditionally from source documents.

Returns:
true if all whitespace-only text nodes are stripped.

setStripsAllWhiteSpace

public void setStripsAllWhiteSpace(boolean stripsAllWhiteSpace)
Determine whether whitespace-only text nodes are to be stripped unconditionally from source documents.

Parameters:
stripsAllWhiteSpace - if all whitespace-only text nodes are to be stripped.

getSourceParser

public org.xml.sax.XMLReader getSourceParser()
                                      throws javax.xml.transform.TransformerFactoryConfigurationError
Get the parser for source documents

javax.xml.transform.TransformerFactoryConfigurationError

getStyleParser

public org.xml.sax.XMLReader getStyleParser()
                                     throws javax.xml.transform.TransformerFactoryConfigurationError
Get the parser for stylesheet documents

javax.xml.transform.TransformerFactoryConfigurationError

readSchema

public java.lang.String readSchema(java.lang.String baseURI,
                                   java.lang.String schemaLocation,
                                   java.lang.String expected)
                            throws javax.xml.transform.TransformerConfigurationException
Read a schema from a given schema location

Returns:
the target namespace of the schema
javax.xml.transform.TransformerConfigurationException

addSchema

public void addSchema(SchemaMarker schema)
               throws javax.xml.transform.TransformerConfigurationException
Add a schema to the cache

javax.xml.transform.TransformerConfigurationException

getSchema

public SchemaMarker getSchema(java.lang.String namespace)
Get a schema from the cache. Return null if not found.


getDocumentValidator

public Receiver getDocumentValidator(Receiver receiver,
                                     java.lang.String systemId,
                                     NamePool namePool,
                                     int validationMode)
Get a document-level validator to add to a Receiver pipeline

Parameters:
receiver - The receiver to which events should be sent after validation
systemId - the base URI of the document being validated
namePool - the namePool to be used by the validator
validationMode - for example Validation.STRICT or Validation.STRIP
Returns:
A Receiver to which events can be sent for validation

getElementValidator

public Receiver getElementValidator(Receiver receiver,
                                    int nameCode,
                                    SchemaType schemaType,
                                    int validation,
                                    ValidationContext context,
                                    NamePool pool)
                             throws javax.xml.transform.TransformerException
Get a Receiver that can be used to validate an element

Parameters:
receiver -
nameCode -
schemaType -
validation -
pool -
Returns:
The supplied receiver, indicating that with this configuration, no validation is performed.
javax.xml.transform.TransformerException

getContainedValidationContext

public ValidationContext getContainedValidationContext(ValidationContext outer,
                                                       int fingerprint,
                                                       boolean isType)
                                                throws XPathException
Get a validation context nested within an existing validation context (XQuery only)

XPathException

validateAttribute

public int validateAttribute(int nameCode,
                             java.lang.CharSequence value,
                             int validation)
                      throws ValidationException
Validate an attribute value

Parameters:
nameCode - the name of the attribute
value - the value of the attribute as a string
validation - STRICT or LAX
Returns:
the type annotation to apply to the attribute node
Throws:
ValidationException - if the value is invalid

getAttributeType

public SchemaType getAttributeType(SchemaComponentMarker attributeDecl)
Get the schema type corresponding to an attribute declaration


getElementType

public SchemaType getElementType(SchemaComponentMarker attributeDecl)
Get the schema type corresponding to an element declaration


makeSubstitutionGroupTest

public NodeTest makeSubstitutionGroupTest(SchemaComponentMarker elementDecl)
Make a test for elements corresponding to a give element declaration


addQueryLibraryModule

public void addQueryLibraryModule(StaticQueryContext module)
Add an XQuery library module to the configuration


getQueryLibraryModule

public StaticQueryContext getQueryLibraryModule(java.lang.String namespace)
Locate an XQuery library module in the configuration.

Parameters:
namespace - the module namespace URI
Returns:
the StaticQueryContext representing the module, or null if the module namespace is unknown

makeParser

public static org.xml.sax.XMLReader makeParser(java.lang.String className)
                                        throws javax.xml.transform.TransformerFactoryConfigurationError
Create a new SAX XMLReader object using the class name provided.
The named class must exist and must implement the org.xml.sax.XMLReader or Parser interface.
This method returns an instance of the parser named.

Parameters:
className - A string containing the name of the SAX parser class, for example "com.microstar.sax.LarkDriver"
Returns:
an instance of the Parser class named, or null if it is not loadable or is not a Parser.
javax.xml.transform.TransformerFactoryConfigurationError

getLocale

public static java.util.Locale getLocale(java.lang.String lang)
Get a locale given a language code in XML format