javax.xml.catalog

Class CatalogFeatures

java.lang.Object

javax.xml.catalog.CatalogFeatures

public class CatalogFeatures
extends Object

The CatalogFeatures holds a collection of features and properties.

Catalog Features

Feature	Description	Property Name	System Property [1]	jaxp.properties [1]	Value [2]		Action
					Type	Value
FILES	A semicolon-delimited list of catalog files. Relative file paths are considered relative to ${user.dir}.	javax.xml.catalog.files	javax.xml.catalog.files	javax.xml.catalog.files	String	File paths	Reads the first catalog as the current catalog; Loads others if no match is found in the current catalog including delegate catalogs if any.
PREFER	Indicates the preference between the public and system identifiers. The default value is public [3].	javax.xml.catalog.prefer	N/A	N/A	String	system	Searches system entries for a match; Searches public entries when external identifier specifies only a public identifier
						public	Searches system entries for a match; Searches public entries when there is no matching system entry.
DEFER	Indicates that the alternative catalogs including those specified in delegate entries or nextCatalog are not read until they are needed. The default value is true.	javax.xml.catalog.defer [4]	javax.xml.catalog.defer	javax.xml.catalog.defer	String	true	Loads alternative catalogs as needed.
						false	Loads all catalogs[5].
RESOLVE	Determines the action if there is no matching entry found after all of the specified catalogs are exhausted. The default is strict.	javax.xml.catalog.resolve [4]	javax.xml.catalog.resolve	javax.xml.catalog.resolve	String	strict	Throws CatalogException if there is no match.
						continue	Allows the XML parser to continue as if there is no match.
						ignore	Tells the XML parser to skip the external references if there no match.

[1] There is no System property for the features that marked as "N/A".

[2] The value shall be exactly as listed in this table, case-sensitive. Any unspecified value will result in IllegalArgumentException.

[3] The Catalog specification defined complex rules on the prefer attribute. Although the prefer can be public or system, the specification actually made system the preferred option, that is, no matter the option, a system entry is always used if found. Public entries are only considered if the prefer is public and system entries are not found. It is therefore recommended that the prefer attribute be set as public (which is the default).

[4] Although non-standard attributes in the OASIS Catalog specification, defer and resolve are recognized by the Java Catalog API the same as the prefer as being an attribute in the catalog entry of the main catalog. Note that only the attributes specified for the catalog entry of the main Catalog file will be used.

[5] If the intention is to share an entire catalog store, it may be desirable to set the property javax.xml.catalog.defer to false to allow the entire catalog to be pre-loaded.

Scope and Order

Features and properties can be set through the catalog file, the Catalog API, system properties, and jaxp.properties, with a preference in the same order.

Properties that are specified as attributes in the catalog file for the catalog and group entries shall take preference over any of the other settings. For example, if a prefer attribute is set in the catalog file as in <catalog prefer="public">, any other input for the "prefer" property is not necessary or will be ignored.

Properties set through the Catalog API override those that may have been set by system properties and/or in jaxp.properties. In case of multiple interfaces, the latest in a procedure shall take preference. For CatalogFeatures.Feature.FILES, this means that the path(s) specified through the methods of the CatalogManager will override any that may have been entered through the CatalogFeatures.Builder.

System properties when set shall override those in jaxp.properties.

The jaxp.properties file is typically in the conf directory of the Java installation. The file is read only once by the JAXP implementation and its values are then cached for future use. If the file does not exist when the first attempt is made to read from it, no further attempts are made to check for its existence. It is not possible to change the value of any properties in jaxp.properties after it has been read.

A CatalogFeatures instance can be created through its builder as illustrated in the following sample code:

                CatalogFeatures f = CatalogFeatures.builder()
                        .with(Feature.FILES, "catalog.xml")
                        .with(Feature.PREFER, "public")
                        .with(Feature.DEFER, "true")
                        .with(Feature.RESOLVE, "ignore")
                        .build();
 

Since:

9

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CatalogFeatures.Builder The Builder class for building the CatalogFeatures object.
static class	CatalogFeatures.Feature A Feature type as defined in the Catalog Features table.

Method Summary

Modifier and Type	Method and Description
static CatalogFeatures.Builder	builder() Returns an instance of the builder for creating the CatalogFeatures object.
static CatalogFeatures	defaults() Returns a CatalogFeatures instance with default settings.
String	get(CatalogFeatures.Feature cf) Returns the value of the specified feature.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

defaults

public static CatalogFeatures defaults()

Returns a CatalogFeatures instance with default settings.

Returns:

a default CatalogFeatures instance

get

public String get(CatalogFeatures.Feature cf)

Returns the value of the specified feature.

Parameters:

cf - the type of the Catalog feature

Returns:

the value of the feature

builder

public static CatalogFeatures.Builder builder()

Returns an instance of the builder for creating the CatalogFeatures object.

Returns:

an instance of the builder