The CatalogFeatures holds a collection of features and properties.

Catalog Features
Feature	Description	Property Name	System Property [1]	Value [2]		Action
Feature	Description	Property Name	System Property [1]	Type	Value	Action
FILES	A semicolon-delimited list of URIs to locate the catalog files. The URIs must be absolute and have a URL protocol handler for the URI scheme.	javax.xml.catalog.files	javax.xml.catalog.files	String	URIs	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	String	`system`	Searches system entries for a match; Searches public entries when external identifier specifies only a public identifier
PREFER		javax.xml.catalog.prefer	N/A	String	`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	String	`true`	Loads alternative catalogs as needed.
DEFER		javax.xml.catalog.defer [4]	javax.xml.catalog.defer	String	`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	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.

Property Precedence

The Catalog Features follow the Property Precedence as described in the module summary with regards to the priority with which their values are retrieved from the various configuration sources such as the JAXP configuration file, system and API properties. In addition to the general configuration sources, the Catalog Features are further supported in the catalog file itself where they can be specified as attributes of the catalog and group entries. When the attributes are specified, they shall take preference over any of the other configuration sources. 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.

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

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

JAXP XML Processor Support

The Catalog Features are supported throughout the JAXP processors, including SAX and DOM (javax.xml.parsers), and StAX parsers (javax.xml.stream), Schema Validation (javax.xml.validation), and XML Transformation (javax.xml.transform). The features described above can be set through JAXP factories or processors that define a setProperty or setAttribute interface. For example, the following code snippet sets a URI to a catalog file on a SAX parser through the javax.xml.catalog.files property:

SAXParserFactory spf = SAXParserFactory.newInstance();
     spf.setFeature(XMLConstants.USE_CATALOG, true); [1]
     SAXParser parser = spf.newSAXParser();
     parser.setProperty(CatalogFeatures.Feature.FILES.getPropertyName(), "file:///etc/xml/catalog");

[1] Note that this statement is not required since the default value of USE_CATALOG is true.

The JAXP Processors' support for Catalog depends on both the USE_CATALOG feature and the existence of valid Catalog file(s). A JAXP processor will use the Catalog only when the feature is true and valid Catalog file(s) are specified through the javax.xml.catalog.files property. It will make no attempt to use the Catalog if either USE_CATALOG is set to false, or there is no Catalog file specified.

The JAXP processors will observe the default settings of the javax.xml.catalog.CatalogFeatures. The processors, for example, will report an Exception by default when no matching entry is found since the default value of the javax.xml.catalog.resolve property is strict.

The JAXP processors give preference to user-specified custom resolvers. If such a resolver is registered, it will be used over the CatalogResolver. If it returns null however, the processors will continue resolving with the CatalogResolver. If it returns an empty source, no attempt will be made by the CatalogResolver.

The Catalog support is available for any process in the JAXP library that supports a resolver. The following table lists all such processes.

Processes with Catalog Support

Processes with Catalog Support
Process	Catalog Entry Type	Example
DTDs and external entities	public, system	The following DTD reference: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> Can be resolved using the following Catalog entry: <public publicId="-//W3C//DTD XHTML 1.0 Strict//EN" uri="catalog/xhtml1-strict.dtd"/> or <systemSuffix systemIdSuffix="html1-strict.dtd" uri="catalog/xhtml1-strict.dtd"/>
XInclude	uri	The following XInclude element: <xi:include href="https://openjdk.org/xml/disclaimer.xml"/> can be resolved using a URI entry: <uri name="https://openjdk.org/xml/disclaimer.xml" uri="file:///pathto/local/disclaimer.xml"/> or <uriSuffix uriSuffix="disclaimer.xml" uri="file:///pathto/local/disclaimer.xml"/>
XSD import	uri	The following import element: <xsd:import namespace="https://openjdk.org/xsd/XSDImport_person" schemaLocation="https://openjdk.org/xsd/XSDImport_person.xsd"/> can be resolved using a URI entry: <uri name="https://openjdk.org/xsd/XSDImport_person.xsd" uri="file:///pathto/local/XSDImport_person.xsd"/> or <uriSuffix uriSuffix="XSDImport_person.xsd" uri="file:///pathto/local/XSDImport_person.xsd"/> or <uriSuffix uriSuffix="https://openjdk.org/xsd/XSDImport_person" uri="file:///pathto/local/XSDImport_person.xsd"/>
XSD include	uri	The following include element: <xsd:include schemaLocation="https://openjdk.org/xsd/XSDInclude_person.xsd"/> can be resolved using a URI entry: <uri name="https://openjdk.org/xsd/XSDInclude_person.xsd" uri="file:///pathto/local/XSDInclude_person.xsd"/> or <uriSuffix uriSuffix="XSDInclude_person.xsd" uri="file:///pathto/local/XSDInclude_person.xsd"/>
XSL import and include	uri	The following include element: <xsl:include href="https://openjdk.org/xsl/include.xsl"/> can be resolved using a URI entry: <uri name="https://openjdk.org/xsl/include.xsl" uri="file:///pathto/local/include.xsl"/> or <uriSuffix uriSuffix="include.xsl" uri="file:///pathto/local/include.xsl"/>
XSL document function	uri	The document in the following element: <xsl:variable name="dummy" select="document('https://openjdk.org/xsl/list.xml')"/> can be resolved using a URI entry: <uri name="https://openjdk.org/xsl/list.xml" uri="file:///pathto/local/list.xml"/> or <uriSuffix uriSuffix="list.xml" uri="file:///pathto/local/list.xml"/>

Modifier and Type	Class and Description
public static class	CatalogFeatures.Builder The Builder class for building the CatalogFeatures object.
public static enum	CatalogFeatures.Feature A Feature type as defined in the Catalog Features table.
pack-priv static enum	CatalogFeatures.State States of the settings of a property, in the order: default value, configuration file, jaxp system properties, and jaxp api properties

Modifier and Type	Field and Description
pack-priv static final String	CATALOG_DEFER The javax.xml.catalog.defer property as described in the property table above.
pack-priv static final String	CATALOG_FILES The constant name of the javax.xml.catalog.files property as described in the property table above.
pack-priv static final String	CATALOG_PREFER The javax.xml.catalog.prefer property as described in the property table above.
pack-priv static final String	CATALOG_RESOLVE The javax.xml.catalog.resolve property as described in the property table above.
pack-priv static final String	DEFER_FALSE
pack-priv static final String	DEFER_TRUE
pack-priv static final String	PREFER_PUBLIC
pack-priv static final String	PREFER_SYSTEM
pack-priv static final String	RESOLVE_CONTINUE
pack-priv static final String	RESOLVE_IGNORE
pack-priv static final String	RESOLVE_STRICT
private CatalogFeatures.State[]	states States of the settings for each property
private String[]	values Values of the properties

Access	Constructor and Description
private	CatalogFeatures() Private class constructor
pack-priv	CatalogFeatures(CatalogFeatures.Builder the builder to build the CatalogFeatures builder) Constructs a new CatalogFeatures instance with the builder.

Modifier and Type	Method and Description
public static CatalogFeatures.Builder	Returns: an instance of the builder builder() Returns an instance of the builder for creating the CatalogFeatures object.
public static CatalogFeatures	Returns: a default CatalogFeatures instance defaults() Returns a CatalogFeatures instance with default settings.
public String	Returns: the value of the feature get(CatalogFeatures.Feature the type of the Catalog feature cf) Returns the value of the specified feature.
private boolean	getSystemProperty(CatalogFeatures.Feature the type of the property cf, String the name of system property sysPropertyName) Reads from system properties, or those in jaxp.properties
private void	init() Initializes the supported properties
private void	readSystemProperties() Reads from system properties, or those in jaxp.properties
private void	setProperties(CatalogFeatures.Builder the CatalogFeatures builder builder) Sets properties by the Builder.
private void	setProperty(CatalogFeatures.Feature the index of the property feature, CatalogFeatures.State the state of the property state, String the value of the property value) Sets the value of a property, updates only if it shall override.

CATALOG_DEFER	back to summary
pack-priv static final String CATALOG_DEFER The javax.xml.catalog.defer property as described in the property table above.

CATALOG_FILES	back to summary
pack-priv static final String CATALOG_FILES The constant name of the javax.xml.catalog.files property as described in the property table above.

CATALOG_PREFER	back to summary
pack-priv static final String CATALOG_PREFER The javax.xml.catalog.prefer property as described in the property table above.

CATALOG_RESOLVE	back to summary
pack-priv static final String CATALOG_RESOLVE The javax.xml.catalog.resolve property as described in the property table above.

DEFER_FALSE	back to summary
pack-priv static final String DEFER_FALSE

DEFER_TRUE	back to summary
pack-priv static final String DEFER_TRUE

PREFER_PUBLIC	back to summary
pack-priv static final String PREFER_PUBLIC

PREFER_SYSTEM	back to summary
pack-priv static final String PREFER_SYSTEM

RESOLVE_CONTINUE	back to summary
pack-priv static final String RESOLVE_CONTINUE

RESOLVE_IGNORE	back to summary
pack-priv static final String RESOLVE_IGNORE

RESOLVE_STRICT	back to summary
pack-priv static final String RESOLVE_STRICT

states	back to summary
private CatalogFeatures.State[] states States of the settings for each property

values	back to summary
private String[] values Values of the properties

CatalogFeatures	back to summary
private CatalogFeatures() Private class constructor

CatalogFeatures	back to summary
pack-priv CatalogFeatures(CatalogFeatures.Builder builder) Constructs a new CatalogFeatures instance with the builder. Parameters builder:CatalogFeatures.Builder the builder to build the CatalogFeatures

Method Detail

builder	back to summary
public static CatalogFeatures.Builder builder() Returns an instance of the builder for creating the CatalogFeatures object. Returns:CatalogFeatures.Builder an instance of the builder

builder

back to summary

public static CatalogFeatures.Builder builder()

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

Returns:CatalogFeatures.Builder: an instance of the builder

defaults	back to summary
public static CatalogFeatures defaults() Returns a CatalogFeatures instance with default settings. Returns:CatalogFeatures a default CatalogFeatures instance

defaults

back to summary

public static CatalogFeatures defaults()

Returns a CatalogFeatures instance with default settings.

Returns:CatalogFeatures: a default CatalogFeatures instance

get	back to summary
public String get(CatalogFeatures.Feature cf) Returns the value of the specified feature. Parameters cf:CatalogFeatures.Feature the type of the Catalog feature Returns:String the value of the feature

get

back to summary

public String get(CatalogFeatures.Feature cf)

Returns the value of the specified feature.

Parameters

cf:CatalogFeatures.Feature: the type of the Catalog feature

Returns:String

the value of the feature

getSystemProperty	back to summary
private boolean getSystemProperty(CatalogFeatures.Feature cf, String sysPropertyName) Reads from system properties, or those in jaxp.properties Parameters cf:CatalogFeatures.Feature the type of the property sysPropertyName:String the name of system property

getSystemProperty

back to summary

private boolean getSystemProperty(CatalogFeatures.Feature cf, String sysPropertyName)

Reads from system properties, or those in jaxp.properties

Parameters

cf:CatalogFeatures.Feature: the type of the property
sysPropertyName:String: the name of system property

init	back to summary
private void init() Initializes the supported properties

readSystemProperties	back to summary
private void readSystemProperties() Reads from system properties, or those in jaxp.properties

setProperties	back to summary
private void setProperties(CatalogFeatures.Builder builder) Sets properties by the Builder. Parameters builder:CatalogFeatures.Builder the CatalogFeatures builder

setProperties

back to summary

private void setProperties(CatalogFeatures.Builder builder)

Sets properties by the Builder.

Parameters

builder:CatalogFeatures.Builder: the CatalogFeatures builder

setProperty	back to summary
private void setProperty(CatalogFeatures.Feature feature, CatalogFeatures.State state, String value) Sets the value of a property, updates only if it shall override. Parameters feature:CatalogFeatures.Feature the index of the property state:CatalogFeatures.State the state of the property value:String the value of the property Exceptions IllegalArgumentException: if the value is invalid

setProperty

back to summary

private void setProperty(CatalogFeatures.Feature feature, CatalogFeatures.State state, String value)

Sets the value of a property, updates only if it shall override.

Parameters

feature:CatalogFeatures.Feature: the index of the property
state:CatalogFeatures.State: the state of the property
value:String: the value of the property

Exceptions

IllegalArgumentException:: if the value is invalid

javax.xml.catalog back to summary

public Class CatalogFeatures.Builder

Class Inheritance

extends Object

java.lang.Object
javax.xml.catalog.CatalogFeatures.Builder

The Builder class for building the CatalogFeatures object.

Field Summary

Modifier and Type	Field and Description
pack-priv Map<CatalogFeatures.Feature, String>	values Values of the features supported by CatalogFeatures.

Constructor Summary

Access	Constructor and Description
private	Builder() Instantiation of Builder is not allowed.

Method Summary

Modifier and Type	Method and Description
public CatalogFeatures	Returns: an instance of CatalogFeatures build() Returns a CatalogFeatures object built by this builder.
public CatalogFeatures.Builder	Returns: this Builder instance with(CatalogFeatures.Feature the Feature to be set feature, String the value to be set for the Feature value) Sets the value to a specified Feature.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

values	back to summary
pack-priv Map<CatalogFeatures.Feature, String> values Values of the features supported by CatalogFeatures.

Constructor Detail

Builder	back to summary
private Builder() Instantiation of Builder is not allowed.

Method Detail

build	back to summary
public CatalogFeatures build() Returns a CatalogFeatures object built by this builder. Returns:CatalogFeatures an instance of CatalogFeatures

build

back to summary

public CatalogFeatures build()

Returns a CatalogFeatures object built by this builder.

Returns:CatalogFeatures: an instance of CatalogFeatures

with back to summary

with	back to summary
public CatalogFeatures.Builder with(CatalogFeatures.Feature feature, String value) Sets the value to a specified Feature. Parameters feature:CatalogFeatures.Feature the Feature to be set value:String the value to be set for the Feature Returns:CatalogFeatures.Builder this Builder instance Exceptions IllegalArgumentException: if the value is not valid for the Feature or has the wrong syntax for the `javax.xml.catalog.files` property

public CatalogFeatures.Builder with(CatalogFeatures.Feature feature, String value)

Sets the value to a specified Feature.

Parameters

feature:CatalogFeatures.Feature: the Feature to be set
value:String: the value to be set for the Feature

Returns:CatalogFeatures.Builder

this Builder instance

Exceptions

IllegalArgumentException:: if the value is not valid for the Feature or has the wrong syntax for the javax.xml.catalog.files property

javax.xml.catalog back to summary

public final Enum CatalogFeatures.Feature

Class Inheritance

extends Enum<CatalogFeatures.Feature>

java.lang.Object
java.lang.Enum
javax.xml.catalog.CatalogFeatures.Feature

A Feature type as defined in the Catalog Features table.

Field Summary

Modifier and Type	Field and Description
private final String	defaultValue
public static final CatalogFeatures.Feature	DEFER The `javax.xml.catalog.defer` property as described in item DEFER of the Catalog Features table.
public static final CatalogFeatures.Feature	FILES The `javax.xml.catalog.files` property as described in item FILES of the Catalog Features table.
private final boolean	hasSystem
private final String	name Hides java.lang.Enum.name.
public static final CatalogFeatures.Feature	PREFER The `javax.xml.catalog.prefer` property as described in item PREFER of the Catalog Features table.
public static final CatalogFeatures.Feature	RESOLVE The `javax.xml.catalog.resolve` property as described in item RESOLVE of the Catalog Features table.
private String	value

Constructor Summary

Access	Constructor and Description
private	Feature(String the name of the feature name, String the value of the feature value, boolean a flag to indicate whether the feature is supported with a System property hasSystem) Constructs a CatalogFeature instance.

Method Summary

Modifier and Type	Method and Description
public String	Returns: the default value of the property defaultValue() Returns the default value of the property.
pack-priv boolean	Returns: true if the specified property is the current property, false otherwise equalsPropertyName(String the name of a property propertyName) Checks whether the specified property is equal to the current property.
public String	Returns: the name of the System Property getPropertyName() Returns the name of the corresponding System Property.
pack-priv String	Returns: the value of the property getValue() Returns the value of the property.
pack-priv boolean	Returns: true it is supported, false otherwise hasSystemProperty() Checks whether System property is supported for the feature.
public static CatalogFeatures.Feature	valueOf(String name)
public static CatalogFeatures.Feature[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

defaultValue	back to summary
private final String defaultValue

DEFER	back to summary
public static final CatalogFeatures.Feature DEFER The `javax.xml.catalog.defer` property as described in item DEFER of the Catalog Features table.

FILES	back to summary
public static final CatalogFeatures.Feature FILES The `javax.xml.catalog.files` property as described in item FILES of the Catalog Features table.

hasSystem	back to summary
private final boolean hasSystem

name	back to summary
private final String name Hides java.lang.Enum.name.

PREFER	back to summary
public static final CatalogFeatures.Feature PREFER The `javax.xml.catalog.prefer` property as described in item PREFER of the Catalog Features table.

RESOLVE	back to summary
public static final CatalogFeatures.Feature RESOLVE The `javax.xml.catalog.resolve` property as described in item RESOLVE of the Catalog Features table.

value	back to summary
private String value

Constructor Detail

Feature	back to summary
private Feature(String name, String value, boolean hasSystem) Constructs a CatalogFeature instance. Parameters name:String the name of the feature value:String the value of the feature hasSystem:boolean a flag to indicate whether the feature is supported with a System property

Feature

back to summary

private Feature(String name, String value, boolean hasSystem)

Constructs a CatalogFeature instance.

Parameters

name:String: the name of the feature
value:String: the value of the feature
hasSystem:boolean: a flag to indicate whether the feature is supported with a System property

Method Detail

defaultValue	back to summary
public String defaultValue() Returns the default value of the property. Returns:String the default value of the property

defaultValue

back to summary

public String defaultValue()

Returns the default value of the property.

Returns:String: the default value of the property

equalsPropertyName	back to summary
pack-priv boolean equalsPropertyName(String propertyName) Checks whether the specified property is equal to the current property. Parameters propertyName:String the name of a property Returns:boolean true if the specified property is the current property, false otherwise

equalsPropertyName

back to summary

pack-priv boolean equalsPropertyName(String propertyName)

Checks whether the specified property is equal to the current property.

Parameters

propertyName:String: the name of a property

Returns:boolean

true if the specified property is the current property, false otherwise

getPropertyName

back to summary

public String getPropertyName()

Returns the name of the corresponding System Property.

Returns:String: the name of the System Property

getValue

back to summary

pack-priv String getValue()

Returns the value of the property.

Returns:String: the value of the property

hasSystemProperty

back to summary

pack-priv boolean hasSystemProperty()

Checks whether System property is supported for the feature.

Returns:boolean: true it is supported, false otherwise

valueOf	back to summary
public static CatalogFeatures.Feature valueOf(String name)

values	back to summary
public static CatalogFeatures.Feature[] values()

javax.xml.catalog back to summary

pack-priv final Enum CatalogFeatures.State

Class Inheritance

extends Enum<CatalogFeatures.State>

java.lang.Object
java.lang.Enum
javax.xml.catalog.CatalogFeatures.State

States of the settings of a property, in the order: default value, configuration file, jaxp system properties, and jaxp api properties

Field Summary

Modifier and Type	Field and Description
public static final CatalogFeatures.State	APIPROPERTY indicates the value of the feature is specified through the API.
public static final CatalogFeatures.State	CATALOGATTRIBUTE indicates the value of the feature is specified as a catalog attribute.
public static final CatalogFeatures.State	DEFAULT represents the default state of a feature.
public static final CatalogFeatures.State	JAXPDOTPROPERTIES indicates the value of the feature is read from jaxp.properties.
pack-priv final String	literal
public static final CatalogFeatures.State	SYSTEMPROPERTY indicates the value of the feature is read from its System property.

Constructor Summary

Access	Constructor and Description
private	State(String literal)

Method Summary

Modifier and Type	Method and Description
pack-priv String	literal()
public static CatalogFeatures.State	valueOf(String name)
public static CatalogFeatures.State[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

APIPROPERTY	back to summary
public static final CatalogFeatures.State APIPROPERTY indicates the value of the feature is specified through the API.

CATALOGATTRIBUTE	back to summary
public static final CatalogFeatures.State CATALOGATTRIBUTE indicates the value of the feature is specified as a catalog attribute.

DEFAULT	back to summary
public static final CatalogFeatures.State DEFAULT represents the default state of a feature.

JAXPDOTPROPERTIES	back to summary
public static final CatalogFeatures.State JAXPDOTPROPERTIES indicates the value of the feature is read from jaxp.properties.

literal	back to summary
pack-priv final String literal

SYSTEMPROPERTY	back to summary
public static final CatalogFeatures.State SYSTEMPROPERTY indicates the value of the feature is read from its System property.

Constructor Detail

State	back to summary
private State(String literal)

Method Detail

literal	back to summary
pack-priv String literal()

valueOf	back to summary
public static CatalogFeatures.State valueOf(String name)

values	back to summary
public static CatalogFeatures.State[] values()

public Class CatalogFeatures

Property Precedence

JAXP XML Processor Support

Processes with Catalog Support

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public Class CatalogFeatures.Builder

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Enum CatalogFeatures.Feature

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

pack-priv final Enum CatalogFeatures.State

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail