| Feature | *Description | *Property Name | *System Property [1] | *jaxp.properties [1] | *Value [2] | *Action | *|
|---|---|---|---|---|---|---|---|
| Type | *Value | *||||||
| 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 | *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 | *N/A | *String | *{@code system} | ** Searches system entries for a match; Searches public entries when * external identifier specifies only a public identifier | *
| {@code 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 | *{@code true} | ** Loads alternative catalogs as needed. * | *
| {@code 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 | *{@code strict} | ** Throws CatalogException if there is no match. * | *
| {@code continue} | ** Allows the XML parser to continue as if there is no match. * | *||||||
| {@code 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 {@link 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, * {@code defer} and {@code resolve} are recognized by the Java Catalog API the * same as the {@code 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 {@code javax.xml.catalog.defer} to false to allow the entire * catalog to be pre-loaded. * *
* 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 {@code prefer} attribute is set in the catalog file as in
* {@code
* Properties set through the Catalog API override those that may have been set
* by system properties and/or in {@code jaxp.properties}. In case of multiple
* interfaces, the latest in a procedure shall take preference. For
* {@link Feature#FILES}, this means that the URI(s) specified through the methods
* of the {@link CatalogManager} will override any that may have been entered
* through the {@link Builder}.
*
*
* System properties when set shall override those in {@code jaxp.properties}.
*
* The {@code 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 {@code jaxp.properties} after it has been read.
*
* A CatalogFeatures instance can be created through its builder as illustrated
* in the following sample code:
*
* [1] Note that this statement is not required since the default value of
* {@link javax.xml.XMLConstants#USE_CATALOG USE_CATALOG} is true.
*
*
* The JAXP Processors' support for Catalog depends on both the
* {@link javax.xml.XMLConstants#USE_CATALOG 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 {@code javax.xml.catalog.files} property. It will make no attempt to use
* the Catalog if either {@link javax.xml.XMLConstants#USE_CATALOG USE_CATALOG}
* is set to false, or there is no Catalog file specified.
*
*
* The JAXP processors will observe the default settings of the
* {@link 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 {@code 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.
*
* {@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 ({@link javax.xml.parsers}), and StAX parsers ({@link javax.xml.stream}),
* Schema Validation ({@link javax.xml.validation}), and XML Transformation
* ({@link 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 {@code javax.xml.catalog.files} property:
*
* {@code
* 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");
* }
* Processes with Catalog Support
*
*
*
*
* @since 9
*/
public class CatalogFeatures {
/**
* The constant name of the javax.xml.catalog.files property as described
* in the property table above.
*/
static final String CATALOG_FILES = "javax.xml.catalog.files";
/**
* The javax.xml.catalog.prefer property as described
* in the property table above.
*/
static final String CATALOG_PREFER = "javax.xml.catalog.prefer";
/**
* The javax.xml.catalog.defer property as described
* in the property table above.
*/
static final String CATALOG_DEFER = "javax.xml.catalog.defer";
/**
* The javax.xml.catalog.resolve property as described
* in the property table above.
*/
static final String CATALOG_RESOLVE = "javax.xml.catalog.resolve";
//values for the prefer property
static final String PREFER_SYSTEM = "system";
static final String PREFER_PUBLIC = "public";
//values for the defer property
static final String DEFER_TRUE = "true";
static final String DEFER_FALSE = "false";
//values for the Resolve property
static final String RESOLVE_STRICT = "strict";
static final String RESOLVE_CONTINUE = "continue";
static final String RESOLVE_IGNORE = "ignore";
/**
* A Feature type as defined in the
* Catalog Features table.
*/
public static enum Feature {
/**
* The {@code javax.xml.catalog.files} property as described in
* item FILES of the
* Catalog Features table.
*/
FILES(CATALOG_FILES, null, true),
/**
* The {@code javax.xml.catalog.prefer} property as described in
* item PREFER of the
* Catalog Features table.
*/
PREFER(CATALOG_PREFER, PREFER_PUBLIC, false),
/**
* The {@code javax.xml.catalog.defer} property as described in
* item DEFER of the
* Catalog Features table.
*/
DEFER(CATALOG_DEFER, DEFER_TRUE, true),
/**
* The {@code javax.xml.catalog.resolve} property as described in
* item RESOLVE of the
* Catalog Features table.
*/
RESOLVE(CATALOG_RESOLVE, RESOLVE_STRICT, true);
private final String name;
private final String defaultValue;
private String value;
private final boolean hasSystem;
/**
* Constructs a CatalogFeature instance.
* @param name the name of the feature
* @param value the value of the feature
* @param hasSystem a flag to indicate whether the feature is supported
* with a System property
*/
Feature(String name, String value, boolean hasSystem) {
this.name = name;
this.defaultValue = value;
this.hasSystem = hasSystem;
}
/**
* Checks whether the specified property is equal to the current property.
* @param propertyName the name of a property
* @return true if the specified property is the current property, false
* otherwise
*/
boolean equalsPropertyName(String propertyName) {
return name.equals(propertyName);
}
/**
* Returns the name of the corresponding System Property.
*
* @return the name of the System Property
*/
public String getPropertyName() {
return name;
}
/**
* Returns the default value of the property.
* @return the default value of the property
*/
public String defaultValue() {
return defaultValue;
}
/**
* Returns the value of the property.
* @return the value of the property
*/
String getValue() {
return value;
}
/**
* Checks whether System property is supported for the feature.
* @return true it is supported, false otherwise
*/
boolean hasSystemProperty() {
return hasSystem;
}
}
/**
* States of the settings of a property, in the order: default value,
* jaxp.properties file, jaxp system properties, and jaxp api properties
*/
static enum State {
/** represents the default state of a feature. */
DEFAULT("default"),
/** indicates the value of the feature is read from jaxp.properties. */
JAXPDOTPROPERTIES("jaxp.properties"),
/** indicates the value of the feature is read from its System property. */
SYSTEMPROPERTY("system property"),
/** indicates the value of the feature is specified through the API. */
APIPROPERTY("property"),
/** indicates the value of the feature is specified as a catalog attribute. */
CATALOGATTRIBUTE("catalog attribute");
final String literal;
State(String literal) {
this.literal = literal;
}
String literal() {
return literal;
}
}
/**
* Values of the properties
*/
private String[] values;
/**
* States of the settings for each property
*/
private State[] states;
/**
* Private class constructor
*/
private CatalogFeatures() {
}
/**
* Returns a CatalogFeatures instance with default settings.
* @return a default CatalogFeatures instance
*/
public static CatalogFeatures defaults() {
return CatalogFeatures.builder().build();
}
/**
* Constructs a new CatalogFeatures instance with the builder.
*
* @param builder the builder to build the CatalogFeatures
*/
CatalogFeatures(Builder builder) {
init();
setProperties(builder);
}
/**
* Returns the value of the specified feature.
*
* @param cf the type of the Catalog feature
* @return the value of the feature
*/
public String get(Feature cf) {
return values[cf.ordinal()];
}
/**
* Initializes the supported properties
*/
private void init() {
values = new String[Feature.values().length];
states = new State[Feature.values().length];
for (Feature cf : Feature.values()) {
setProperty(cf, State.DEFAULT, cf.defaultValue());
}
//read system properties or jaxp.properties
readSystemProperties();
}
/**
* Sets properties by the Builder.
* @param builder the CatalogFeatures builder
*/
private void setProperties(Builder builder) {
builder.values.entrySet().stream().forEach((entry) -> {
setProperty(entry.getKey(), State.APIPROPERTY, entry.getValue());
});
}
/**
* Sets the value of a property, updates only if it shall override.
*
* @param index the index of the property
* @param state the state of the property
* @param value the value of the property
* @throws IllegalArgumentException if the value is invalid
*/
private void setProperty(Feature feature, State state, String value) {
int index = feature.ordinal();
if (value != null && value.length() != 0) {
if (state != State.APIPROPERTY) {
Util.validateFeatureInput(feature, value);
}
if (states[index] == null || state.compareTo(states[index]) >= 0) {
values[index] = value;
states[index] = state;
}
}
}
/**
* Reads from system properties, or those in jaxp.properties
*/
private void readSystemProperties() {
for (Feature cf : Feature.values()) {
getSystemProperty(cf, cf.getPropertyName());
}
}
/**
* Reads from system properties, or those in jaxp.properties
*
* @param cf the type of the property
* @param sysPropertyName the name of system property
*/
private boolean getSystemProperty(Feature cf, String sysPropertyName) {
if (cf.hasSystemProperty()) {
String value = SecuritySupport.getSystemProperty(sysPropertyName);
if (value != null && !value.isEmpty()) {
setProperty(cf, State.SYSTEMPROPERTY, value);
return true;
}
value = SecuritySupport.readJAXPProperty(sysPropertyName);
if (value != null && !value.isEmpty()) {
setProperty(cf, State.JAXPDOTPROPERTIES, value);
return true;
}
}
return false;
}
/**
* Returns an instance of the builder for creating the CatalogFeatures object.
*
* @return an instance of the builder
*/
public static Builder builder() {
return new CatalogFeatures.Builder();
}
/**
* The Builder class for building the CatalogFeatures object.
*/
public static class Builder {
/**
* Values of the features supported by CatalogFeatures.
*/
Map
*
*
*
* Process
* Catalog Entry Type
* Example
*
*
* DTDs and external entities
* public, system
*
*
* {@literal
The following DTD reference:
Can be resolved using the following Catalog entry:
*
*
* XInclude
* uri
*
*
* {@literal
The following XInclude element:
*
*
* XSD import
* uri
*
*
* {@literal
The following import element:
*
*
* XSD include
* uri
*
*
* {@literal
The following include element:
*
*
* XSL import and include
* uri
*
*
* {@literal
The following include element:
*
*
*
* XSL document function
* uri
*
*
* {@literal
The document in the following element:
*