Package org.xmlresolver

Class ResolverFeature<T>

  • Type Parameters:
    T - The type of the feature.
    public class ResolverFeature<T>
extends java.lang.Object
    An individual resolver feature. The complete set of known features is instantiated as a collection of static final fields.

    • Field Detail

      • CATALOG_FILES

        public static final ResolverFeature<java.util.List<java.lang.String>> CATALOG_FILES
        Sets the list of catalog files.

      • CATALOG_ADDITIONS

        public static final ResolverFeature<java.util.List<java.lang.String>> CATALOG_ADDITIONS
        Sets the list of additional catalog files.

      • PREFER_PUBLIC

        public static final ResolverFeature<java.lang.Boolean> PREFER_PUBLIC
        Determines whether or not public IDs are preferred..

      • PREFER_PROPERTY_FILE

        public static final ResolverFeature<java.lang.Boolean> PREFER_PROPERTY_FILE
        Determines whether property file values are preferred over system property values.

        In earlier versions of this API, this was effectively always true. The default is now false which allows system property values to override property file values. Set this to true in your property file to preserve the old behavior.

      • ALLOW_CATALOG_PI

        public static final ResolverFeature<java.lang.Boolean> ALLOW_CATALOG_PI
        Determines whether the catalog PI in a document may change the list of catalog files to be consulted.

        It defaults to true, but there's a small performance cost. Each parse needs it's own copy of the configuration if you enable this feature (otherwise, the PI in one document might have an effect on other documents). If you know you aren't using the PI, it might be sensible to make this false.

      • ALWAYS_RESOLVE

        public static final ResolverFeature<java.lang.Boolean> ALWAYS_RESOLVE
        Should the resolver always return a resource, even when it didn't find it in the catalog?

        It defaults to true, but this is in violation of the entity resolver contract. The resolver should return null if it fails to find the resource. But some parsers don't follow redirects and therefore cannot http-to-https redirected URIs. And the source returned by the resolver contains additional, useful information.

        It's worth noting that the .NET contract for the resolver *is* that it always returns something, so there's that.

      • CACHE_DIRECTORY

        public static final ResolverFeature<java.lang.String> CACHE_DIRECTORY
        Sets the location of the cache directory.

        If the value is null, and CACHE_UNDER_HOME is false, no cache will be used.

      • CACHE_UNDER_HOME

        public static final ResolverFeature<java.lang.Boolean> CACHE_UNDER_HOME
        Determines if a default cache location of .xmlresolver.org/cache under the users home directory should be used for the cache.

        This only applies if CATALOG_CACHE is null.

      • URI_FOR_SYSTEM

        public static final ResolverFeature<java.lang.Boolean> URI_FOR_SYSTEM
        Determines whether or not uri catalog entries can be used to resolve external identifiers.

        This only applies if resolution fails through system and public entries.

      • MERGE_HTTPS

        public static final ResolverFeature<java.lang.Boolean> MERGE_HTTPS
        Determines whether http: and https: URIs compare the same.

        Historically, most web servers used http:, now most use https:. There are existing catalogs that can't practically be updated that use http: for system identifiers and URIs. But authors copying and pasting are likely to get https: URIs. If this option is true, then http: and https: are considred the same for the purpose of comparison in the catalog.

        This option has no effect on the URIs returned; it only influences catalog URI comparisons.

      • MASK_JAR_URIS

        public static final ResolverFeature<java.lang.Boolean> MASK_JAR_URIS
        Determines whether a classpath: or jar: URI is returned by the resolver.

        When the resolver finds a resource, for example a schema or a stylesheet, it returns the location of the resolved resource as the base URI for the resource. This enables the following common scenario:

        • Download a distribution and store it locally.
        • Create a catalog that maps from the entry point(s) into the local distribution: http://example.com/acme-schema/start/here -> /opt/acme-schema-1.0/here
        • Profit.

        A document requests http://example.com/acme-schema/start/here, the resolver returns /opt/achme-schema-1.0/here. When the schema attempts to import a library, the URI for that library is resolved against the base URI on the filesystem, a new path is constructed, and it all just works.

        Adding support for classpath and jar: URIs to XML Resolver 3.0 has enabled another very attractive scenario:

        • Put the distribution in a jar file with an included catalog.
        • Arrange for the project to depend on that jar file, so it'll be on the classpath.
        • Add classpath:/org/example/acme-schema/catalog.xml to your catalog list.
        • More profit!

        Trouble is, the resolved URI will be something like this:

        jar:file:///where/the/jar/is/acme-schema-1.0.jar!/org/example/acme-schema/here

        And the trouble with that is, Java doesn't think the classpath: and jar: URI schemes are hierarchical and won't resolve the URI for the imported library correctly. It will work just fine for any document that doesn't include parts with relative URIs. The DocBook schema, for example, is distributed as a single RELAX NG file, so it works. But the xslTNG stylesheets would not.

        If MASK_JAR_URIS is true, the resolver will return the local resource from the jar file, but will leave the URI unchanged. As long as the catalog has a mapping for all of the resources, and not just the entry point(s), this will do exactly the right thing.

        Often, this can be achieved with, for example, a rewrite rule:

        <rewriteURI uriStartString="http://example.com/acme-start/"
             rewritePrefix="acme-start/">

        Assuming the catalog is in a location where that rewrite prefix works, the entry point will be remapped and the local resource returned. The resource it imports will be resolved against the http: URI, but that will also be remapped, and everyone wins.

        You don't need to use a rewrite rule, you can use any combination of catalog rules you like as long as each of the requested URIs will be mapped.

      • CATALOG_LOADER_CLASS

        public static final ResolverFeature<java.lang.String> CATALOG_LOADER_CLASS
        Identifies the catalog loader class.

        The default catalog loader class is usually fine. The validating class can be used to enforce schema validity checks on loaded catalogs.

      • PARSE_RDDL

        public static final ResolverFeature<java.lang.Boolean> PARSE_RDDL
        Controls whether or not namespace documents will be parsed for RDDL annotations.

        If this feature is enabled, then if an attempt to get a namespace returns an HTML document, and if a nature and purpose has been specified in the request, the HTML document will be parsed for RDDL annotations. If a matching entry is found, the annotated URI will be used.

        In the LSResourceResolver, if the type of the request is the XML Schema or RELAX NG namespace, the purpose is assumed to be validation.

      • CLASSPATH_CATALOGS

        public static final ResolverFeature<java.lang.Boolean> CLASSPATH_CATALOGS
        Determines whether or not catalogs on the classpath should be loaded automatically.

        If this feature is enabled, then the resolver will attempt to find and load all of the catalogs named org/xmlresolver/catalog.xml on the classpath. These will be added to the of the catalogs loaded from properties.

      • CLASSLOADER

        public static final ResolverFeature<java.lang.ClassLoader> CLASSLOADER
        Identify the ClassLoader to use for accessing resources on the classpath.

        A ClassLoader is used to access the class path and load resources from the class path. By default the resolver configuration uses the class loader obtained from the class:

        getClass().getClassLoader()

        If you're using the resolver in an environment where an alternate class loader is required, you can specify it with this feature.

      • ARCHIVED_CATALOGS

        public static final ResolverFeature<java.lang.Boolean> ARCHIVED_CATALOGS
        Adds support for placing ZIP files on the catalog path.

        If enabled, then you can put ZIP files on the catalog path. The resolver will look for catalog.xml and org/xmlresolver/catalog.xml, using whichever it finds first. If it doesn't find either, the file is ignored.

      • THROW_URI_EXCEPTIONS

        public static final ResolverFeature<java.lang.Boolean> THROW_URI_EXCEPTIONS
        Allows the resolver to throw exceptions for invalid URIs.

        If enabled, when the resolver attempts to process a URI, if the processing raises an exception, that exception will be thrown rather than suppressed. For checked exceptions, such as URISyntaxException, what's thrown will be a IllegalArgumentException wrapping the underlying exception.

      • RESOLVER_LOGGER

        public static final ResolverFeature<ResolverLogger> RESOLVER_LOGGER
        Identifies the resolver logger.

        This feature can get and set an instance of the logger. The logger is usually configured with the RESOLVER_LOGGER_CLASS feature. If the logger has been configured via RESOLVER_LOGGER_CLASS, an attempt to get the RESOLVER_LOGGER will instantiate the class (if it hasn't already been instantiated).

      • DEFAULT_LOGGER_LOG_LEVEL

        public static final ResolverFeature<java.lang.String> DEFAULT_LOGGER_LOG_LEVEL
        Specify the logging level for the default logger.

        This feature only applies to the DefaultLogger (or other classes that use it). In particular, it has no effect if the SystemLogger is used. How that is configured depends on the concrete backend selected at runtime.

      • ACCESS_EXTERNAL_ENTITY

        public static final ResolverFeature<java.lang.String> ACCESS_EXTERNAL_ENTITY
        Specify the protocols allowed for entity lookup.

        This feature restricts the protocols that are allowed during entity resolution. If an attempt is made to resolve an entity and the system identifier for that entity uses a protocol not listed in this feature, the request is rejected. See JAXP 185.

        The keyword "all" allows all protocols. An empty list allows none.

      • ACCESS_EXTERNAL_DOCUMENT

        public static final ResolverFeature<java.lang.String> ACCESS_EXTERNAL_DOCUMENT
        Specify the protocols allowed for URI lookup.

        This feature restricts the protocols that are allowed during URI resolution. If an attempt is made to resolve a document and the URI for that document uses a protocol not listed in this feature, the request is rejected. See JAXP 185.

        The keyword "all" allows all protocols. An empty list allows none.

      • CACHE_ENABLED

        public static final ResolverFeature<java.lang.Boolean> CACHE_ENABLED
        Is the cache enabled?

        If the cache is not enabled, no attempt will be made to create or use a cache.

      • SAXPARSERFACTORY_CLASS

        public static final ResolverFeature<java.lang.String> SAXPARSERFACTORY_CLASS
        Identify the SAXParserFactory class.

        If unconfigured, parsers are created with XMLREADER_SUPPLIER.

        This feature and the XMLREADER_SUPPLIER are different mechanisms for configuring the same underlying feature: how does the resolver get an XML parser if it needs one? (For example, it needs one to parse the cache, but the ResolvingXMLFilter and ResolvingXMLReader also use this mechanism.)

        The SAXPARSERFACTORY_CLASS is initially null and the XMLREADER_SUPPLIER is used. The purpose of the SAXPARSERFACTORY_CLASS is to allow the factory to be configured with a property since the XMLREADER_SUPPLIER cannot.

        If a SAXPARSERFACTORY_CLASS is specified, it will be used in favor of the default XMLREADER_SUPPLIER. If an XMLREADER_SUPPLIER is explicitly set after the configuration is initialized, it will set this feature to null and take precedence.

      • XMLREADER_SUPPLIER

        public static final ResolverFeature<java.util.function.Supplier<org.xml.sax.XMLReader>> XMLREADER_SUPPLIER
        Configure the default XML reader.

        The default supplier is obtained with SAXParserFactory.newInstance() and the global mechanisms that it uses.

        This feature and the SAXPARSERFACTORY_CLASS are different mechanisms for configuring the same underlying feature: how does the resolver get an XML parser if it needs one? (For example, it needs one to parse the cache, but the ResolvingXMLFilter and ResolvingXMLReader also use this mechanism.)

        The SAXPARSERFACTORY_CLASS is initially null and the XMLREADER_SUPPLIER is used. The purpose of the SAXPARSERFACTORY_CLASS is to allow the factory to be configured with a property since the XMLREADER_SUPPLIER cannot.

        If a SAXPARSERFACTORY_CLASS is specified, it will be used in favor of the default XMLREADER_SUPPLIER. If an XMLREADER_SUPPLIER is explicitly set after the configuration is initialized, it will set this feature to null and take precedence.

      • FIX_WINDOWS_SYSTEM_IDENTIFIERS

        public static final ResolverFeature<java.lang.Boolean> FIX_WINDOWS_SYSTEM_IDENTIFIERS
        Fix backslashes in system identifiers on Windows?

        System identifiers are URIs and URIs may not contain un-escaped backslashes. However, Windows uses the backslash as the path separator and it's not uncommon for filenames to appear in system identifiers. If this flag is set, the resolver will coerce backslashes into forward slashes in system identifiers.

    • Method Detail

      • getName

        public java.lang.String getName()
        Get the name of the feature.
        Returns:
        The feature name.

      • getDefaultValue

        public T getDefaultValue()
        Get the default value of the feature.
        Returns:
        The feature default value.

      • byName

        public static ResolverFeature<?> byName​(java.lang.String name)
        Find a known static feature by name.
        Parameters:
        name - The feature name.
        Returns:
        The instance of that feature.

      • getNames

        public static java.util.Iterator<java.lang.String> getNames()
        Iterates over all of the known feature names.
        Returns:
        An iterator over the feature names.