com.saxonica.config
Class ProfessionalConfiguration

java.lang.Object
  extended by net.sf.saxon.Configuration
      extended by com.saxonica.config.ProfessionalConfiguration
All Implemented Interfaces:
Serializable, SourceResolver
Direct Known Subclasses:
EnterpriseConfiguration

public class ProfessionalConfiguration
extends Configuration

This class holds details of user-selected configuration options for a set of transformations and/or queries. When running XSLT, the preferred way of setting configuration options is via the JAXP TransformerFactory interface, but the Configuration object provides a finer level of control. As yet there is no standard API for XQuery, so the only way of setting Configuration information is to use the methods on this class directly.

As well as holding configuration settings, this class acts as a factory for classes providing service in particular areas: error handling, URI resolution, and the like. Some of these services are chosen on the basis of the current platform (Java or .NET), some vary depending whether the environment is schema-aware or not.

The Configuration provides access to a NamePool which is used to manage all the names used in stylesheets, queries, schemas, and source and documents: the NamePool allocates integer codes to these names allowing efficient storage and comparison. Normally there will be a one-to-one relationship between a NamePool and a Configuration. It is possible, however, for several Configuration objects to share the same NamePool. Until Saxon 8.9, by default all Configuration objects shared a single NamePool unless configured otherwise; this changed in 8.9 so that the default is to allocate a new NamePool for each Configuration.

The Configuration establishes the scope within which node identity is managed. Every document belongs to a Configuration, and every node has a distinct identity within that Configuration. In consequence, it is not possible for any query or transformation to manipulate multiple documents unless they all belong to the same Configuration.

Saxon-EE has a subclass of the Configuration class which provides the additional services needed for schema-aware processing. The EnterpriseConfiguration also holds a cache of loaded schema components used for compiling schema-aware transformations and queries, and for validating instance documents.

Since Saxon 8.4, the JavaDoc documentation for Saxon attempts to identify interfaces that are considered stable, and will only be changed in a backwards-incompatible way if there is an overriding reason to do so. These interfaces and methods are labelled with the JavaDoc "since" tag. The value 8.n indicates a method in this category that was introduced in Saxon version 8.n: or in the case of 8.4, that was present in Saxon 8.4 and possibly in earlier releases. (In some cases, these methods have been unchanged for a long time.) Methods without a "since" tag, although public, are provided for internal use or for use by advanced users, and are subject to change from one release to the next. The presence of a "since" tag on a class or interface indicates that there are one or more methods in the class that are considered stable; it does not mean that all methods are stable.

Since:
9.2
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class net.sf.saxon.Configuration
Configuration.LicenseFeature
 
Field Summary
protected  String[] externalModelNames
          External object models supported in Saxon-PE and Saxon-EE
protected  String[] externalNodeClassNames
           
 
Fields inherited from class net.sf.saxon.Configuration
configurationClass, DO_NOT_RECOVER, JAVA_APPLICATION, optimizationLevel, optimizer, RECOVER_SILENTLY, RECOVER_WITH_WARNINGS, styleNodeFactory, vendorFunctionLibrary, XML_SCHEMA, XML10, XML11, XPATH, XQUERY, XSD10, XSD11, xsdVersion, XSLT
 
Constructor Summary
ProfessionalConfiguration()
          Create a Saxon Professional Edition configuration object with default settings for all options.
 
Method Summary
 void addExtensionBinders(FunctionLibraryList list)
          Add the registered extension binders to a function library.
 Configuration copy()
          Copy an existing Configuration to create a new Configuration.
protected  void copyTo(Configuration sc)
           
 void declareBuiltInExtensionElementNamespaces()
          Declare the built-in XSLT extension element namespaces
 void displayLicenseMessage()
          Display a message about the license status.
 String getEditionCode()
          Get the edition code identifying this configuration: "HE", "PE" or "EE"
 FunctionLibrary getExtensionBinder(String scheme)
          Get the FunctionLibrary used to bind calls on extension functions on the specified platform.
 ExtensionElementFactory getExtensionElementFactory(String namespace)
          Get the XSLT extension element factory for a given namespace
protected  String getFeature(String name)
          This method is called to read a feature of the license.
 StyleNodeFactory getStyleNodeFactory()
          Factory method to get the StyleNodeFactory, used for constructing elements in a stylesheet document
 VendorFunctionLibrary getVendorFunctionLibrary()
          Get the FunctionLibrary used to bind calls on Saxon-defined extension functions
 boolean isLicensed()
          Determine if the functionality available in this configuration is licensed.
 boolean isLicensedFeature(int feature)
          Determine if a particular feature is licensed.
 boolean isSchemaAware(int language)
          Deprecated. since 9.2: use isLicensedFeature() instead
 boolean isUnlicensed()
          Ask if the configuration is known to be unlicensed
 Receiver makeEmitter(String clarkName, Controller controller)
          Get a configuration-defined output method.
static Configuration makeProfessionalConfiguration(ClassLoader classLoader, String className)
          Static method to instantiate a professional configuration.
 UnconstructedDocument makeUnconstructedDocument(DocumentInstr instr, XPathContext context)
          Make an "unconstructed" (that is, lazily-constructed) document node
 UnconstructedElement makeUnconstructedElement(ElementCreator instr, XPathContext context)
          Make an "unconstructed" (that is, lazily-constructed) element node
 StaticQueryContext newStaticQueryContext()
          Get a new StaticQueryContext (which is also the factory class for creating a query parser)
 UserFunction newUserFunction(boolean memoFunction)
          Make a UserFunction object.
 Source resolveSource(Source source, Configuration config)
          Resolve a Source.
 void setExtensionBinder(String scheme, FunctionLibrary binder)
          Set the FunctionLibrary used to bind calls on extension functions.
 void setExtensionElementNamespace(String namespace, String className)
          Set a namespace used to refer to a library of XSLT extension elements
 void supplyLicenseKey(BufferedReader reader)
          This method allows the contents of a license key to be supplied programmatically.
protected  boolean testFeature(int feature)
           
 
Methods inherited from class net.sf.saxon.Configuration
addSchemaSource, addSchemaSource, buildDocument, buildDocument, checkTypeDerivationIsOK, exportComponents, getAnnotationStripper, getAttributeDeclaration, getCharacterSetFactory, getClass, getCollationMap, getCollationURIResolver, getCollectionURIResolver, getConfiguration, getConfigurationProperty, getConversionContext, getDebugger, getDefaultCollection, getDefaultCountry, getDefaultLanguage, getDefaultSerializationProperties, getDefaultStaticQueryContext, getDefaultXsltCompilerInfo, getDocumentNumberAllocator, getDocumentValidator, getDOMLevel, getDynamicLoader, getElementDeclaration, getElementValidator, getErrorListener, getExtensionsOfType, getExternalObjectModel, getExternalObjectModel, getExternalObjectModels, getExternalObjectType, getGlobalDocumentPool, getHostLanguage, getImportedNamespaces, getInstance, getIntegratedFunctionLibrary, getLocale, getLocalizerFactory, getMessageEmitterClass, getModuleURIResolver, getNameChecker, getNamePool, getOptimizer, getOutputURIResolver, getParseOptions, getPlatform, getProcessor, getProductTitle, getRecoveryPolicy, getSchemaType, getSchemaURIResolver, getSchemaValidationMode, getSerializerFactory, getSourceParser, getSourceParserClass, getSourceResolver, getStandardModuleURIResolver, getStripsWhiteSpace, getStyleParser, getStyleParserClass, getSystemURIResolver, getTraceListener, getTraceListenerClass, getTreeModel, getTypeHierarchy, getURIResolver, getXMLVersion, getXsdVersion, importComponents, init, instantiateClassName, isAllowExternalFunctions, isCompatible, isCompileWithTracing, isExpandAttributeDefaults, isLazyConstructionMode, isLineNumbering, isMultiThreading, isOptimizerTracing, isRetainDTDAttributeTypes, isSchemaAvailable, isStripsAllWhiteSpace, isTiming, isTraceExternalFunctions, isValidation, isValidationWarnings, isVersionWarning, isXIncludeAware, loadSchema, makeCollator, makeConfiguration, makeDocumentProjector, makeLicensedConfiguration, makeNumberer, makeParser, makePipelineConfiguration, makeSchemaAwareConfiguration, makeSlotManager, makeStreamingTransformer, makeTraceListener, makeTraceListener, makeURIResolver, newConfiguration, newPendingUpdateList, readConfiguration, readInlineSchema, readMultipleSchemas, readSchema, registerExtensionFunction, registerExternalObjectModel, reportFatalError, reuseSourceParser, reuseStyleParser, sealNamespace, setAllowExternalFunctions, setCollationURIResolver, setCollectionURIResolver, setCompileWithTracing, setConfigurationProperty, setDebugger, setDefaultCollection, setDefaultCountry, setDefaultLanguage, setDefaultSerializationProperties, setDocumentNumberAllocator, setDOMLevel, setDynamicLoader, setErrorListener, setExpandAttributeDefaults, setHostLanguage, setLazyConstructionMode, setLineNumbering, setLocalizerFactory, setMessageEmitterClass, setModuleURIResolver, setModuleURIResolver, setMultiThreading, setNamePool, setOptimizerTracing, setOutputURIResolver, setParameterizedURIResolver, setProcessor, setRecoveryPolicy, setRetainDTDAttributeTypes, setSchemaURIResolver, setSchemaValidationMode, setSerializerFactory, setSourceParserClass, setSourceResolver, setStripsAllWhiteSpace, setStripsWhiteSpace, setStyleParserClass, setTiming, setTraceExternalFunctions, setTraceListener, setTraceListenerClass, setTreeModel, setURIResolver, setValidation, setValidationWarnings, setVersionWarning, setXIncludeAware, setXMLVersion, unravel, useTypedValueCache, validateAttribute
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

externalModelNames

protected String[] externalModelNames
External object models supported in Saxon-PE and Saxon-EE


externalNodeClassNames

protected String[] externalNodeClassNames
Constructor Detail

ProfessionalConfiguration

public ProfessionalConfiguration()
Create a Saxon Professional Edition configuration object with default settings for all options.

Since:
9.2
Method Detail

makeProfessionalConfiguration

public static Configuration makeProfessionalConfiguration(ClassLoader classLoader,
                                                          String className)
                                                   throws RuntimeException
Static method to instantiate a professional configuration.

On the .NET platform, this method should not be called unless it is known that the assembly saxon9sa.dll has already been loaded. This can be achieved by an appropriate call on Assembly.Load(): for an example, see the C# Configuration.cs class in the Saxon.Api namespace.

This method fails if Saxon-EE cannot be loaded, but it does not fail if there is no license available. In that case it returns a schema-aware configuration object, but any attempt to use schema-aware processing will fail.

Parameters:
classLoader - - the class loader to be used. If null, the context class loader for the current thread is used.
className - - the name of the schema aware configuration class. Defaults to "com.saxonica.EnterpriseConfiguration" if null is supplied. This allows an assembly qualified name to be supplied under .NET. The class, once instantiated, must be an instance of Configuration, but despite the name of this method there is nothing that requires it to be schema-aware.
Returns:
the new ProfessionalConfiguration
Throws:
RuntimeException - if the Saxon-EE product cannot be loaded
Since:
9.2 (renamed from makeSchemaAwareConfiguration)

getEditionCode

public String getEditionCode()
Get the edition code identifying this configuration: "HE", "PE" or "EE"

Overrides:
getEditionCode in class Configuration

copy

public Configuration copy()
Copy an existing Configuration to create a new Configuration. This is a shallow copy. The new Configuration will share all the option settings of the old; it will also share the same NamePool, and the same DocumentNumberAllocator. If this configuration is schema-aware then the new one will also be schema-aware, and will share the same Schema manager and so on. (So any schema component loaded into one configuration will affect both).

Note that creating a new ProfessionalConfiguration using this method can be significantly cheaper than creating one from scratch, because it avoids the need to verify the Saxon license key if this has already been done.

Overrides:
copy in class Configuration
Returns:
a shallow copy of this Configuration

copyTo

protected void copyTo(Configuration sc)
Overrides:
copyTo in class Configuration

supplyLicenseKey

public void supplyLicenseKey(BufferedReader reader)
This method allows the contents of a license key to be supplied programmatically. This must be a license file as issued to authorized OEM distributors of Saxon-EE.

Parameters:
reader - A reader that will be used to read the contents of the license file (for example, a StringReader)
Throws:
IllegalArgumentException - if the key supplied is not a valid OEM license key

getFeature

protected String getFeature(String name)
This method is called to read a feature of the license. This method should be called only if the caller requires access to the feature.

Parameters:
name - the name of the requested feature
Returns:
the feature value of the license.
Throws:
RuntimeException - if no license is available

isLicensed

public boolean isLicensed()
Determine if the functionality available in this configuration is licensed.

Overrides:
isLicensed in class Configuration
Returns:
true if a valid license file is installed, regardless of what functionality it offers
Since:
9.2

isLicensedFeature

public final boolean isLicensedFeature(int feature)
Determine if a particular feature is licensed.

Overrides:
isLicensedFeature in class Configuration
Parameters:
feature - the feature in question, identified by a constant in class {#LicenseFeature}

testFeature

protected boolean testFeature(int feature)

isUnlicensed

public boolean isUnlicensed()
Ask if the configuration is known to be unlicensed


isSchemaAware

public final boolean isSchemaAware(int language)
Deprecated. since 9.2: use isLicensedFeature() instead

Determine if the configuration is schema-aware

Overrides:
isSchemaAware in class Configuration
Parameters:
language - the processing language for which schema-aware processing is required
Returns:
true if the configuration is schema-aware
Since:
8.4

displayLicenseMessage

public void displayLicenseMessage()
Display a message about the license status. Used from command-line tools only.

Overrides:
displayLicenseMessage in class Configuration

getStyleNodeFactory

public StyleNodeFactory getStyleNodeFactory()
Factory method to get the StyleNodeFactory, used for constructing elements in a stylesheet document

Overrides:
getStyleNodeFactory in class Configuration
Returns:
the StyleNodeFactory used in this Configuration

newStaticQueryContext

public StaticQueryContext newStaticQueryContext()
Get a new StaticQueryContext (which is also the factory class for creating a query parser)

Overrides:
newStaticQueryContext in class Configuration
Returns:
a new StaticQueryContext

setExtensionBinder

public void setExtensionBinder(String scheme,
                               FunctionLibrary binder)
Set the FunctionLibrary used to bind calls on extension functions. This allows the rules for identifying extension functions to be customized (in principle, it would allow support for extension functions in other languages to be provided).

When an application supplies its own FunctionLibrary for binding extension functions, this replaces the default binding mechanism for Java extension functions, namely JavaExtensionLibrary. It thus disables the function libraries for built-in Saxon extensions and for EXSLT extensions. It is possible to create a function library that adds to the existing mechanisms, rather than replacing them, by supplying as the FunctionLibrary a FunctionLibraryList that itself contains two FunctionLibrary objects: a JavaExtensionLibrary, and a user-written FunctionLibrary.

Parameters:
scheme - The scheme served by the extension binder. Typically this will be one of "java" or "clitype". However, user-defined extension binders for other schemes can be registered. Note that the scheme name does not have to be related to the actual namespace used in function calls; all registered function libraries have the opportunity to bind any extension function call. The significance is purely local to this class: setting an extension binder for a given scheme replaces the existing extension binder for that scheme. The two schemes used by Saxon itself are "java" for dynamically-bound Java extension functions, and "clitype" for dynamically-bound .NET extension functions
binder - The FunctionLibrary object used to locate implementations of extension functions, based on their name and arity

getExtensionBinder

public FunctionLibrary getExtensionBinder(String scheme)
Get the FunctionLibrary used to bind calls on extension functions on the specified platform.

This mechanism is for advanced users only, and the details are subject to change.

Parameters:
scheme - The URI scheme served by the extension binder. This will typically be one of "java" or "clitype". On the Java platform, the only scheme currently supported is "java"; on the .NET platform, the "java" and "clitype" schemes coexist.
Returns:
the registered FunctionLibrary for extension functions if one has been registered; or null otherwise

addExtensionBinders

public void addExtensionBinders(FunctionLibraryList list)
Add the registered extension binders to a function library. This method is intended primarily for internal use

Overrides:
addExtensionBinders in class Configuration

getVendorFunctionLibrary

public VendorFunctionLibrary getVendorFunctionLibrary()
Get the FunctionLibrary used to bind calls on Saxon-defined extension functions

Overrides:
getVendorFunctionLibrary in class Configuration
Returns:
the FunctionLibrary used for extension functions in the Saxon library.

newUserFunction

public UserFunction newUserFunction(boolean memoFunction)
Make a UserFunction object. This method is for internal use.

Overrides:
newUserFunction in class Configuration
Parameters:
memoFunction - true if the function is to be a memo function, This option is ignored in Saxon-HE.

declareBuiltInExtensionElementNamespaces

public void declareBuiltInExtensionElementNamespaces()
Declare the built-in XSLT extension element namespaces


setExtensionElementNamespace

public void setExtensionElementNamespace(String namespace,
                                         String className)
                                  throws XPathException
Set a namespace used to refer to a library of XSLT extension elements

Parameters:
namespace - the namespace used for the extension elements
className - the classname of the implementation of the ExtensionElementFactory that instantiates extension elements in this namespace
Throws:
XPathException
Since:
9.2

getExtensionElementFactory

public ExtensionElementFactory getExtensionElementFactory(String namespace)
Get the XSLT extension element factory for a given namespace

Parameters:
namespace - the namespace URI of the extension element
Returns:
the corresponding extension element factory if one has been registered, or null otherwise
Since:
9.2

resolveSource

public Source resolveSource(Source source,
                            Configuration config)
                     throws XPathException
Resolve a Source.

Specified by:
resolveSource in interface SourceResolver
Overrides:
resolveSource in class Configuration
Parameters:
source - A source object, typically the source supplied as the first argument to Transformer.transform(javax.xml.transform.Source, javax.xml.transform.Result) or similar methods.
config - The Configuration. This provides the SourceResolver with access to configuration information; it also allows the SourceResolver to invoke the resolveSource() method on the Configuration object as a fallback implementation.
Returns:
a source object that Saxon knows how to process. This must be an instance of one of the classes StreamSource, SAXSource, DOMSource, AugmentedSource, NodeInfo, or PullSource. Return null if the Source object is not recognized
Throws:
XPathException - if the Source object is recognized but cannot be processed

makeEmitter

public Receiver makeEmitter(String clarkName,
                            Controller controller)
                     throws XPathException
Get a configuration-defined output method.

Overrides:
makeEmitter in class Configuration
Parameters:
clarkName - the QName of the user-supplied ContentHandler (requested as a prefixed value of the method attribute in xsl:output, or anywhere that serialization parameters are allowed), encoded in Clark format as {uri}local
controller - the Controller. Allows a local class loader to be used.
Returns:
a Receiver that implements the method, or null if the method URI is not recognized
Throws:
XPathException

makeUnconstructedElement

public UnconstructedElement makeUnconstructedElement(ElementCreator instr,
                                                     XPathContext context)
                                              throws XPathException
Make an "unconstructed" (that is, lazily-constructed) element node

Overrides:
makeUnconstructedElement in class Configuration
Parameters:
instr - the instruction that creates the element
context - the dynamic evaluation context
Returns:
the lazily constructed element node
Throws:
XPathException

makeUnconstructedDocument

public UnconstructedDocument makeUnconstructedDocument(DocumentInstr instr,
                                                       XPathContext context)
                                                throws XPathException
Make an "unconstructed" (that is, lazily-constructed) document node

Overrides:
makeUnconstructedDocument in class Configuration
Parameters:
instr - the instruction that creates the document node
context - the dynamic evaluation context
Returns:
the lazily constructed document node
Throws:
XPathException


Copyright (c) Saxonica Limited. All rights reserved.