Summary

Change the built-in Catalog's role in External Resource Resolution so that it only handles references that are remote to applications.

Problem

The JDK built-in Catalog was introduced in JDK 21 via JDK-8306055 as a part of the resolution process for XML external references. It is to be consulted after custom resolver and catalog to determine whether it can resolve an external resource. When unable to resolve, it may instruct the processor to continue processing or throw an exception.

However, the built-in Catalog, containing standard DTDs and XSDs defined by the Java platform or W3C XML specifications, does not handle custom or user-defined resources. Resources that are local and integral to applications should not have to go through the built-in catalog. In particular, the restriction the built-in catalog may apply to external resources should not prevent local resource from being resolved.

Solution

Remove the JDK built-in catalog from the process that handles resources local to applications. Resources that are local, for example, test.dtd called directly by test.xml, will continue to be processed as they were prior to the introduction of the built-in catalog.

The impact of this solution is minimal since because (1) the built-in catalog was introduced recently in JDK 21; (2) the built-in catalog does not handle user-defined resources.

This solution will allow applications to continue processing local resources when the built-in catalog's resolve property jdk.xml.jdkcatalog.resolve is set to strict.

Specification

--- a/src/java.xml/share/classes/module-info.java
+++ b/src/java.xml/share/classes/module-info.java
@@ -417,7 +417,9 @@
  * </ul>
  *
  * <h2 id="JDKCATALOG">JDK built-in Catalog</h2>
- * The JDK has a built-in catalog that hosts DTDs and XSDs list in the following table.
+ * The JDK has a built-in catalog that hosts DTDs and XSDs defined by the Java platform
+ * and W3C XML specifications, as list in the following table.
+ *
  * <table class="plain" id="JDKCatalog">
  * <caption>DTDs and XSDs in JDK built-in Catalog</caption>
  * <thead>
@@ -512,22 +514,31 @@
  * The catalog is loaded once when the first JAXP processor factory is created.
  *
  * <h3 id="JC_PROCESS">External Resource Resolution Process with the built-in Catalog</h3>
- * The JDK creates a {@link javax.xml.catalog.CatalogResolver CatalogResolver}
- * with the built-in catalog when needed. This CatalogResolver is used as the
- * default external resource resolver.
- * <p>
- * XML processors may use resolvers (such as {@link org.xml.sax.EntityResolver EntityResolver},
- * {@link javax.xml.stream.XMLResolver XMLResolver}, and {@link javax.xml.catalog.CatalogResolver CatalogResolver})
- * to handle external references. In the absence of the user-defined resolvers,
- * the JDK XML processors fall back to the default CatalogResolver to attempt to
- * find a resolution before making a connection to fetch the resources. The fall-back
- * also takes place if a user-defined resolver exists but allows the process to
- * continue when unable to resolve the resource.
- * <p>
- * If the default CatalogResolver is unable to locate a resource, it may signal
- * the XML processors to continue processing, or skip the resource, or
- * throw a CatalogException. The behavior is configured with the
- * <a href="#JDKCATALOG_RESOLVE">{@code jdk.xml.jdkcatalog.resolve}</a> property.
+ * XML processors handle external resources in the following order:
+ * <ul>
+ * <li>
+ * User-defined resolvers such as {@link org.xml.sax.EntityResolver EntityResolver}
+ * and {@link javax.xml.stream.XMLResolver XMLResolver}
+ * </li>
+ * <li>
+ * User-defined catalogs and with which {@link javax.xml.catalog.CatalogResolver CatalogResolver}
+ * created by the JDK
+ * </li>
+ * <li>
+ * The built-in Catalog when the resources are remote to the applications. User-defined
+ * resources, for example `myapp.dtd` in `<!ENTITY % foo SYSTEM "myapp.dtd">` that
+ * are local and relative to an XML file, do not go through the built-in catalog.
+ * </li>
+ * <li>
+ * Make a network connection and fetch the resource
+ * </li>
+ *
+ * During the process, each of the resolvers may decide whether the process shall
+ * continue if it is unable to resolve the resource. For the CatalogResolver,
+ * it is configured by using {@link javax.xml.catalog.CatalogFeatures CatalogFeatures}'s
+ * RESOLVE property, while for the built-in catalog,
+ * the <a href="#JDKCATALOG_RESOLVE">{@code jdk.xml.jdkcatalog.resolve}</a> property.
+ *
  *
  * <h2 id="IN_ISFP">Implementation Specific Properties</h2>
  * In addition to the standard <a href="#Conf_Properties">JAXP Properties</a>,