This is an automated email from the ASF dual-hosted git repository. garydgregory pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/commons-xml.git
commit a2a3a316c855f7eea6c746c8350d7e283cc81941 Author: Gary Gregory <[email protected]> AuthorDate: Wed Aug 26 07:59:14 2026 -0400 Javadoc --- .../commons/xml/FallbackIgnoreEntityResolver2.java | 40 +++++++++++++-------- .../xml/FallbackIgnoreLSResourceResolver.java | 21 ++++++++--- .../commons/xml/FallbackIgnoreURIResolver.java | 41 +++++++++++++++------- .../commons/xml/FallbackIgnoreXMLResolver.java | 10 ++++++ 4 files changed, 81 insertions(+), 31 deletions(-) diff --git a/src/main/java/org/apache/commons/xml/FallbackIgnoreEntityResolver2.java b/src/main/java/org/apache/commons/xml/FallbackIgnoreEntityResolver2.java index 0b036b9..676f3a5 100644 --- a/src/main/java/org/apache/commons/xml/FallbackIgnoreEntityResolver2.java +++ b/src/main/java/org/apache/commons/xml/FallbackIgnoreEntityResolver2.java @@ -30,9 +30,10 @@ /** * Entity resolver that consults an optional caller-supplied resolver and ignores (resolves to empty) whatever the caller does not resolve. - * - * <p>The canonical hardening floor, and the entity-resolution counterpart of the JAXP 1.5 {@code ACCESS_EXTERNAL_*} properties. Every floor - * ({@link FallbackIgnoreLSResourceResolver}, {@link FallbackIgnoreURIResolver} and {@link FallbackIgnoreXMLResolver}) shares two defining properties:</p> + * <p> + * The canonical hardening floor, and the entity-resolution counterpart of the JAXP 1.5 {@code ACCESS_EXTERNAL_*} properties. Every floor + * ({@link FallbackIgnoreLSResourceResolver}, {@link FallbackIgnoreURIResolver} and {@link FallbackIgnoreXMLResolver}) shares two defining properties: + * </p> * <ol> * <li><strong>Non-removable, and it wraps the resolver the caller sets.</strong> The hardened wrappers install one and route a caller-set resolver through * {@code setDelegate} rather than letting it replace the floor, so the caller's resolver is consulted first but cannot remove the floor underneath it.</li> @@ -40,15 +41,17 @@ * all). This is where a floor departs from stock JAXP: normally an unresolved lookup falls back to the processor's built-in resolution and the resource is * <em>fetched</em>; a floor instead resolves it to <em>empty</em> content, so the parse continues without the external fetch and without a leak.</li> * </ol> - * - * <p>The hardened DOM and SAX wrappers install one of these and, when the caller sets their own {@link EntityResolver}, route it through {@link #setDelegate} + * <p> + * The hardened DOM and SAX wrappers install one of these and, when the caller sets their own {@link EntityResolver}, route it through {@link #setDelegate} * rather than letting it replace the floor. A caller therefore opts a specific resource in by returning a non-{@code null} {@link InputSource} from their * resolver; anything they leave unresolved (a {@code null} return, or no caller resolver at all) goes to {@link #onUnresolved}, which returns empty content by - * default.</p> - * - * <p>It extends {@link DefaultHandler2} so it is also usable as a {@link org.xml.sax.ext.LexicalHandler}; {@link #getExternalSubset} therefore inherits the + * default. + * </p> + * <p> + * It extends {@link DefaultHandler2} so it is also usable as a {@link org.xml.sax.ext.LexicalHandler}; {@link #getExternalSubset} therefore inherits the * {@code DefaultHandler2} "no synthetic subset" default. Only {@link #resolveEntity(String, String, String, String) resolveEntity} (the actual external fetch) - * reaches the ignore fallback.</p> + * reaches the ignore fallback. + * </p> */ class FallbackIgnoreEntityResolver2 extends DefaultHandler2 { @@ -76,10 +79,20 @@ private static String absolutize(final String baseURI, final String systemId) { */ private EntityResolver delegate; + /** + * Constructs a new ignore-all floor with an optional caller-supplied resolver. + * + * @param delegate The caller-supplied resolver, or {@code null} for a pure ignore-all floor. + */ FallbackIgnoreEntityResolver2(final EntityResolver delegate) { this.delegate = delegate; } + /** + * Gets the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}. + * + * @return The delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}. + */ final EntityResolver getDelegate() { return delegate; } @@ -97,8 +110,7 @@ final EntityResolver getDelegate() { * @throws SAXException when {@value XmlFactories#THROW_ON_UNRESOLVED} is set: unresolved references are rejected instead of resolved to empty. * @throws IOException never by the default implementation. */ - protected InputSource onUnresolved(final String name, final String publicId, final String baseURI, final String systemId) - throws SAXException, IOException { + protected InputSource onUnresolved(final String name, final String publicId, final String baseURI, final String systemId) throws SAXException, IOException { if (HardeningException.throwOnUnresolved()) { throw new SAXException(HardeningException.forbidden(name, null, publicId, systemId, baseURI)); } @@ -120,11 +132,11 @@ public final InputSource resolveEntity(final String name, final String publicId, return resolved != null ? resolved : onUnresolved(name, publicId, baseURI, systemId); } - private InputSource resolveWithDelegate(final String name, final String publicId, final String baseURI, - final String systemId) throws SAXException, IOException { + private InputSource resolveWithDelegate(final String name, final String publicId, final String baseURI, final String systemId) + throws SAXException, IOException { if (delegate != null) { return delegate instanceof EntityResolver2 ? ((EntityResolver2) delegate).resolveEntity(name, publicId, baseURI, systemId) : - // We need to resolve the systemId against baseURI, because a plain EntityResolver expects an absolute URI. + // We need to resolve the systemId against baseURI, because a plain EntityResolver expects an absolute URI. delegate.resolveEntity(publicId, absolutize(baseURI, systemId)); } return null; diff --git a/src/main/java/org/apache/commons/xml/FallbackIgnoreLSResourceResolver.java b/src/main/java/org/apache/commons/xml/FallbackIgnoreLSResourceResolver.java index 3b98643..3c0d764 100644 --- a/src/main/java/org/apache/commons/xml/FallbackIgnoreLSResourceResolver.java +++ b/src/main/java/org/apache/commons/xml/FallbackIgnoreLSResourceResolver.java @@ -27,11 +27,12 @@ /** * {@link LSResourceResolver} floor: consults an optional caller-supplied resolver and ignores (resolves to empty) whatever the caller does not resolve. - * - * <p>The schema-compile counterpart of {@link FallbackIgnoreEntityResolver2}. The hardened {@link javax.xml.validation.SchemaFactory}, {@link - * javax.xml.validation.Validator} and {@link javax.xml.validation.ValidatorHandler} wrappers install one of these and route a caller-set resolver through - * {@link #setDelegate} rather than letting it replace the floor. A caller opts a specific resource in by returning a non-{@code null} {@link LSInput}; - * anything left unresolved resolves to an empty {@link LSInput}, so the external resource is neither fetched nor leaked.</p> + * <p> + * The schema-compile counterpart of {@link FallbackIgnoreEntityResolver2}. The hardened {@link javax.xml.validation.SchemaFactory}, + * {@link javax.xml.validation.Validator} and {@link javax.xml.validation.ValidatorHandler} wrappers install one of these and route a caller-set resolver + * through {@link #setDelegate} rather than letting it replace the floor. A caller opts a specific resource in by returning a non-{@code null} {@link LSInput}; + * anything left unresolved resolves to an empty {@link LSInput}, so the external resource is neither fetched nor leaked. + * </p> */ final class FallbackIgnoreLSResourceResolver implements LSResourceResolver { @@ -48,10 +49,20 @@ private static DOMImplementationLS domImplementationLS() { private LSResourceResolver delegate; + /** + * Constructs a new resolver that consults the given delegate and ignores whatever it does not resolve. + * + * @param delegate optional caller-supplied resolver to consult first; may be {@code null}. + */ FallbackIgnoreLSResourceResolver(final LSResourceResolver delegate) { this.delegate = delegate; } + /** + * Gets the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}. + * + * @return The delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}. + */ LSResourceResolver getDelegate() { return delegate; } diff --git a/src/main/java/org/apache/commons/xml/FallbackIgnoreURIResolver.java b/src/main/java/org/apache/commons/xml/FallbackIgnoreURIResolver.java index 31da5dc..edcd78f 100644 --- a/src/main/java/org/apache/commons/xml/FallbackIgnoreURIResolver.java +++ b/src/main/java/org/apache/commons/xml/FallbackIgnoreURIResolver.java @@ -30,18 +30,21 @@ /** * {@link URIResolver} floor: consults an optional caller-supplied resolver and ignores (resolves to empty) whatever the caller does not resolve. - * - * <p>The XSLT counterpart of {@link FallbackIgnoreEntityResolver2}, guarding {@code xsl:import}/{@code xsl:include} at compile time and {@code document()} at + * <p> + * The XSLT counterpart of {@link FallbackIgnoreEntityResolver2}, guarding {@code xsl:import}/{@code xsl:include} at compile time and {@code document()} at * transform time. The hardened {@link javax.xml.transform.TransformerFactory} and {@link javax.xml.transform.Transformer} wrappers install one of these and * route a caller-set resolver through {@link #setDelegate} rather than letting it replace the floor. A caller opts a specific URI in by returning a - * non-{@code null} {@link Source}; anything left unresolved resolves to an empty {@link Source}, so the external resource is neither fetched nor leaked.</p> - * - * <p>The shape of that empty {@link Source} is supplied by the caller: the default is a well-formed empty DOM document (which every stock TrAX consumer - * accepts), while the Saxon path supplies {@code EmptySource.getInstance()} so its consumers get the "empty" shape they expect.</p> - * - * <p>An opted-in {@link javax.xml.transform.stream.StreamSource} or reader-less {@link javax.xml.transform.sax.SAXSource} is rewritten to carry a hardened - * reader before it is returned, so the implementation parses the opted-in content on the same floor instead of with an internal reader at its own defaults. A - * {@link javax.xml.transform.dom.DOMSource} or a {@link javax.xml.transform.sax.SAXSource} carrying the caller's own reader is returned as-is.</p> + * non-{@code null} {@link Source}; anything left unresolved resolves to an empty {@link Source}, so the external resource is neither fetched nor leaked. + * </p> + * <p> + * The shape of that empty {@link Source} is supplied by the caller: the default is a well-formed empty DOM document (which every stock TrAX consumer accepts), + * while the Saxon path supplies {@code EmptySource.getInstance()} so its consumers get the "empty" shape they expect. + * </p> + * <p> + * An opted-in {@link javax.xml.transform.stream.StreamSource} or reader-less {@link javax.xml.transform.sax.SAXSource} is rewritten to carry a hardened reader + * before it is returned, so the implementation parses the opted-in content on the same floor instead of with an internal reader at its own defaults. A + * {@link javax.xml.transform.dom.DOMSource} or a {@link javax.xml.transform.sax.SAXSource} carrying the caller's own reader is returned as-is. + * </p> */ final class FallbackIgnoreURIResolver implements URIResolver { @@ -62,15 +65,24 @@ private static Document newEmptyDocument() { private URIResolver delegate; - /** Produces the empty {@link Source} returned for an unresolved reference; a new value per call keeps callers from mutating a shared Source. */ + /** + * Produces the empty {@link Source} returned for an unresolved reference; a new value per call keeps callers from mutating a shared Source. + */ private final Supplier<Source> emptySource; + /** + * Constructs a new resolver. + * + * @param delegate optional caller-supplied resolver to consult first; may be {@code null}. + */ FallbackIgnoreURIResolver(final URIResolver delegate) { this(delegate, null); } /** - * @param delegate the resolver to delegate resolution to. + * Constructs a new resolver. + * + * @param delegate the resolver to delegate resolution to. * @param emptySource the empty-{@link Source} supplier for the ignore outcome, or {@code null} for the default empty DOM document. */ FallbackIgnoreURIResolver(final URIResolver delegate, final Supplier<Source> emptySource) { @@ -78,6 +90,11 @@ private static Document newEmptyDocument() { this.emptySource = emptySource != null ? emptySource : () -> new DOMSource(EMPTY_DOCUMENT); } + /** + * Gets the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}. + * + * @return The delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}. + */ URIResolver getDelegate() { return delegate; } diff --git a/src/main/java/org/apache/commons/xml/FallbackIgnoreXMLResolver.java b/src/main/java/org/apache/commons/xml/FallbackIgnoreXMLResolver.java index 94c24c8..b055a2a 100644 --- a/src/main/java/org/apache/commons/xml/FallbackIgnoreXMLResolver.java +++ b/src/main/java/org/apache/commons/xml/FallbackIgnoreXMLResolver.java @@ -41,10 +41,20 @@ final class FallbackIgnoreXMLResolver implements XMLResolver { private XMLResolver delegate; + /** + * Constructs a new resolver that consults the given delegate and ignores whatever it does not resolve. + * + * @param delegate optional caller-supplied resolver to consult first; may be {@code null}. + */ FallbackIgnoreXMLResolver(final XMLResolver delegate) { this.delegate = delegate; } + /** + * Gets the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}. + * + * @return The delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null}. + */ XMLResolver getDelegate() { return delegate; }
