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-secure-xml.git
commit 8af16727e33b29860e57f23a59ec9b91509a72d3 Author: Gary Gregory <[email protected]> AuthorDate: Wed Sep 2 07:36:57 2026 -0400 Javadoc Fix grammar, word salads, and so on. --- .../xml/secure/FallbackIgnoreURIResolver.java | 16 ++++---- .../commons/xml/secure/MethodHandleFactory.java | 31 +++++++------- .../xml/secure/SecureDocumentBuilderFactory.java | 5 +-- .../commons/xml/secure/SecureSAXParserFactory.java | 2 +- .../commons/xml/secure/SecureSchemaFactory.java | 9 ++--- .../apache/commons/xml/secure/SecureTemplates.java | 2 +- .../xml/secure/SecureTransformerFactory.java | 31 ++++++++------ .../xml/secure/SecureTransformerHandler.java | 2 +- .../apache/commons/xml/secure/SecureXMLFilter.java | 2 +- .../commons/xml/secure/SecureXMLInputFactory.java | 47 +++++++++++----------- .../commons/xml/secure/SecureXPathFactory.java | 31 +++++++------- .../commons/xml/secure/AttackTestSupport.java | 2 +- .../commons/xml/secure/BillionLaughsTest.java | 2 +- .../xml/secure/EntityResolverFloorTest.java | 2 +- .../xml/secure/ExternalParameterEntityTest.java | 2 +- .../xml/secure/SaxonXPathExternalCallsTest.java | 2 +- .../apache/commons/xml/secure/XIncludeTest.java | 2 +- 17 files changed, 96 insertions(+), 94 deletions(-) diff --git a/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreURIResolver.java b/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreURIResolver.java index ccda148..1e67c38 100644 --- a/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreURIResolver.java +++ b/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreURIResolver.java @@ -52,14 +52,14 @@ final class FallbackIgnoreURIResolver implements URIResolver { /** * Creates the empty document backing the default ignore outcome. - * - * <p>Consumers parse the resolved {@link Source}, - * and an empty character stream is not a well-formed XML document - * (XSLTC rejects it for {@code document()} and for an ignored {@code xsl:include}/{@code xsl:import}), - * so the default supplier answers with a well-formed empty document that evaluates to no content.</p> - * - * <p>The document escapes to the consumer with the resolved {@link Source}, so each resolution gets its own: whatever a consumer does to a document it - * received cannot surface in another resolution.</p> + * <p> + * Consumers parse the resolved {@link Source}, and an empty character stream is not a well-formed XML document (XSLTC rejects it for {@code document()} and + * for an ignored {@code xsl:include}/{@code xsl:import}), so the default supplier answers with a well-formed empty document that evaluates to no content. + * </p> + * <p> + * The document is exposed to the consumer with the resolved {@link Source}, so each resolution gets its own: whatever a consumer does to a document it + * received cannot surface in another resolution. + * </p> * * @param factory the factory to create the document builder with. * @return a new empty document. diff --git a/src/main/java/org/apache/commons/xml/secure/MethodHandleFactory.java b/src/main/java/org/apache/commons/xml/secure/MethodHandleFactory.java index d2fd64e..2e2f3e3 100644 --- a/src/main/java/org/apache/commons/xml/secure/MethodHandleFactory.java +++ b/src/main/java/org/apache/commons/xml/secure/MethodHandleFactory.java @@ -35,11 +35,11 @@ interface ThrowableCallable<V> { /** * Finds a static method handle for the given class, method name, where the class is also the return type. * - * @param refcAndReturnType the class to search for the method and the return type. - * @param name the name of the method. - * @return the method handle, or {@code null} if not found. - * @throws SecurityException if a security manager is present and it <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>. - * @throws NullPointerException if any argument is null. + * @param refcAndReturnType The class to search for the method and the return type. + * @param name The name of the method. + * @return The method handle, or {@code null} if not found. + * @throws SecurityException Thrown if a security manager is present and it <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>. + * @throws NullPointerException Thrown if any argument is null. */ static MethodHandle findStatic(final Class<?> refcAndReturnType, final String name) { try { @@ -51,17 +51,18 @@ static MethodHandle findStatic(final Class<?> refcAndReturnType, final String na /** * Finds an instance method handle for the given class, method name and signature. + * <p> + * Used to reach a method a later Java release added to a class this library compiles against an earlier one; the handle is {@code null} where the + * running platform does not have it. + * </p> * - * <p>Used to reach a method a later Java release added to a class this library compiles against at an earlier one; the handle is {@code null} where the - * running platform does not have it.</p> - * - * @param refc the class to search for the method. - * @param name the name of the method. - * @param returnType the method's return type. - * @param parameterTypes the method's parameter types. - * @return the method handle, or {@code null} if not found. - * @throws SecurityException if a security manager is present and it <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>. - * @throws NullPointerException if any argument is null. + * @param refc The class to search for the method. + * @param name The name of the method. + * @param returnType The method's return type. + * @param parameterTypes The method's parameter types. + * @return The method handle, or {@code null} if not found. + * @throws SecurityException Thrown if a security manager is present and it <a href="MethodHandles.Lookup.html#secmgr">refuses access</a>. + * @throws NullPointerException Thrown if any argument is null. */ static MethodHandle findVirtual(final Class<?> refc, final String name, final Class<?> returnType, final Class<?>... parameterTypes) { try { diff --git a/src/main/java/org/apache/commons/xml/secure/SecureDocumentBuilderFactory.java b/src/main/java/org/apache/commons/xml/secure/SecureDocumentBuilderFactory.java index df08d18..42a5e43 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureDocumentBuilderFactory.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureDocumentBuilderFactory.java @@ -51,11 +51,8 @@ public final class SecureDocumentBuilderFactory { * {@link DocumentBuilderFactory} wrapper that keeps an ignore-all {@link EntityResolver} floor on every {@link DocumentBuilder} produced. * <p> * Wraps each produced builder in a {@link SecureDocumentBuilder}; required when the underlying factory carries no resolver of its own and does not honor - * JAXP 1.5 {@code ACCESS_EXTERNAL_*} (e.g. the external Xerces distribution). A caller-set resolver is routed through the floor rather than replacing it. Kept - * as a standalone wrapper so any secure class can reuse the floor. + * JAXP 1.5 {@code ACCESS_EXTERNAL_*} (e.g. the external Xerces distribution). A caller-set resolver is routed through the floor rather than replacing it. * </p> - * - * @see org.apache.commons.xml.secure */ private static final class Wrapper extends DocumentBuilderFactory { diff --git a/src/main/java/org/apache/commons/xml/secure/SecureSAXParserFactory.java b/src/main/java/org/apache/commons/xml/secure/SecureSAXParserFactory.java index bd06c78..fd3320b 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureSAXParserFactory.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureSAXParserFactory.java @@ -352,7 +352,7 @@ static SAXParserFactory secure(final SAXParserFactory factory) { * Rewrites a {@link Source} so that any SAX parsing it triggers runs through a secure {@link XMLReader}. * <p> * Only a {@link StreamSource} or a {@link SAXSource} without a reader is enriched with a secure, namespace-aware reader; other source kinds are returned - * as-is. Used by the TrAX and schema wrappers to route every source they parse through the SAX secure path. + * as-is. Used by the TrAX and schema wrappers to route every source they parse through the secure SAX path. * </p> * * @param source the source to secure; never {@code null}. diff --git a/src/main/java/org/apache/commons/xml/secure/SecureSchemaFactory.java b/src/main/java/org/apache/commons/xml/secure/SecureSchemaFactory.java index adcbd4a..58c063d 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureSchemaFactory.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureSchemaFactory.java @@ -82,12 +82,9 @@ public final class SecureSchemaFactory { * reader, so {@code FEATURE_SECURE_PROCESSING} is set on the factory as well, which is what installs that bound on external Xerces (the stock JDK applies * it unconditionally). The JAXP 1.5 {@code ACCESS_EXTERNAL_*} properties are still not set explicitly: the resolver floor already blocks the same fetches on * every implementation, and the JDK 8 {@code SchemaFactory} has a bug whereby those properties keep blocking even when a caller's own resolver would grant - * the access. The floor is a non-removable - * lower bound: a caller-set {@link LSResourceResolver} is routed through it (opting a specific lookup in by returning a non-{@code null} result) rather than - * replacing it, so the securing (or the floor) cannot be dropped by swapping the resolver. + * access. The floor is a non-removable lower bound: a caller-set {@link LSResourceResolver} is routed through it (opting a specific lookup in by returning a + * non-{@code null} result) rather than replacing it, so the securing (or the floor) cannot be dropped by swapping the resolver. * </p> - * - * @see org.apache.commons.xml.secure */ private static final class Wrapper extends SchemaFactory { @@ -272,7 +269,7 @@ public static SchemaFactory newInstance(final String schemaLanguage, final Strin * * <p>Unlike the other factory types there is no per-implementation branching: schema compilation and validation reach external resources only through the * resolver hook, so wrapping the factory with a non-removable ignore-all resolver floor is enough on every implementation. The reader used to parse schema - * and instance documents is secure separately, through {@link SecureSAXParserFactory#secure(javax.xml.transform.Source, boolean)}; the factory carries + * and instance documents is secured separately, through {@link SecureSAXParserFactory#secure(javax.xml.transform.Source, boolean)}; the factory carries * {@code FEATURE_SECURE_PROCESSING} for the one limit that reader cannot supply, the loader's content-model expansion.</p> * * @param factory the factory to secure; never {@code null}. diff --git a/src/main/java/org/apache/commons/xml/secure/SecureTemplates.java b/src/main/java/org/apache/commons/xml/secure/SecureTemplates.java index b7362a7..66eb84f 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureTemplates.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureTemplates.java @@ -33,7 +33,7 @@ * <p> * Both Apache Xalan 2.7 and stock-JDK XSLTC fail to propagate the factory's URIResolver through {@code Templates.newTransformer()}: the produced runtime * Transformer has a null URIResolver unless the caller sets one, leaving runtime {@code document()} calls unguarded. Snapshotting the resolver at compile time - * and restoring it onto the runtime Transformer matches the JAXP-conformant intuition that the factory's resolver is the default for any Transformer the + * and restoring it onto the runtime Transformer matches the JAXP-conformant expectation that the factory's resolver is the default for any Transformer the * factory ultimately produces. * </p> */ diff --git a/src/main/java/org/apache/commons/xml/secure/SecureTransformerFactory.java b/src/main/java/org/apache/commons/xml/secure/SecureTransformerFactory.java index bc2bbd9..eac32f6 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureTransformerFactory.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureTransformerFactory.java @@ -88,11 +88,14 @@ public final class SecureTransformerFactory { * {@link TransformerFactory} wrapper that rewrites every Source-taking entry point through {@link SecureSAXParserFactory#secure(Source, boolean)} before * delegating. * - * <p>Used by providers whose underlying TrAX implementation pulls a new {@code SAXParserFactory.newInstance()} for any Source that is not already a + * <p> + * Used by providers whose underlying TrAX implementation pulls a new {@code SAXParserFactory.newInstance()} for any Source that is not already a * {@link SAXSource} carrying its own {@link XMLReader}, and only sets {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING FSP} on the resulting reader. - * Wrapping the factory and rewriting the Source upstream guarantees the parse runs through an {@link org.apache.commons.xml.secure}-secured reader instead.</p> - * - * <p>Three layers cooperate:</p> + * Wrapping the factory and rewriting the Source upstream guarantees the parse runs through an {@link org.apache.commons.xml.secure}-secured reader instead. + * </p> + * <p> + * Three layers cooperate: + * </p> * <ol> * <li>{@link SecureTransformerFactory} rewrites the Source on every entry point that compiles a stylesheet or transforms a one-shot input.</li> * <li>{@link SecureTemplates} returns a {@link SecureTransformer} from {@link Templates#newTransformer()} so runtime source parsing is also covered, and @@ -100,11 +103,12 @@ public final class SecureTransformerFactory { * {@code Templates}).</li> * <li>{@link SecureTransformer} rewrites the Source on every {@link Transformer#transform(Source, javax.xml.transform.Result)} call.</li> * </ol> - * - * <p>The {@link SAXTransformerFactory} extension products ride the same wrappers: {@code newTransformerHandler}/{@code newTemplatesHandler} products are + * <p> + * The {@link SAXTransformerFactory} extension products ride the same wrappers: {@code newTransformerHandler}/{@code newTemplatesHandler} products are * wrapped ({@link SecureTransformerHandler}, {@link SecureTemplatesHandler}) so the {@link Transformer}/{@link Templates} they expose carry the resolver * floor, and {@code newXMLFilter} returns a {@link SecureXMLFilter} composed from these wrappers instead of the implementation's filter, which would - * self-provision an unsecured input reader.</p> + * self-provision an unsecured input reader. + * </p> * * <h2>Caveats</h2> * <ul> @@ -113,8 +117,6 @@ public final class SecureTransformerFactory { * caller sets on a returned {@link XMLFilter}. The exception is {@code getAssociatedStylesheet} on an engine that drops the reader (Apache Xalan, and * the JDK's XSLTC on Java 8): there the document is pre-parsed into a DOM instead, since the reader would otherwise be replaced by the engine's own.</li> * </ul> - * - * @see org.apache.commons.xml.secure */ private static final class Wrapper extends SAXTransformerFactory { @@ -406,10 +408,11 @@ public void setURIResolver(final URIResolver resolver) { /** * {@code true} on Java 8, detected by the absence of {@code TransformerFactory.newDefaultInstance()}, which arrived in Java 9. - * - * <p>The JDK's XSLTC only began honoring the {@link XMLReader} carried by a {@link SAXSource} in {@code getAssociatedStylesheet} in 8u162; through 8u152 it + * <p> + * The JDK's XSLTC only began honoring the {@link XMLReader} carried by a {@link SAXSource} in {@code getAssociatedStylesheet} in 8u162; through 8u152 it * provisions its own parser, exactly as Apache Xalan does. Java 8 as a whole is used as the boundary rather than the patch level: the two are - * indistinguishable through any API, and a runtime that old has already chosen correctness of configuration over the cost of a DOM pre-parse.</p> + * indistinguishable through any API, and such an old runtime has already chosen correctness of configuration over the cost of a DOM pre-parse. + * </p> */ private static final boolean JAVA_8 = MH_newDefaultInstance == null; @@ -460,7 +463,9 @@ public static TransformerFactory newInstance(final String factoryClassName, fina /** * Capability-driven secure for any {@link TransformerFactory} on the classpath. * - * <p>Rather than branching on the implementation class, this method probes what the factory supports and adapts:</p> + * <p> + * Rather than branching on the implementation class, this method probes what the factory supports and adapts: + * </p> * <ul> * <li><strong>Saxon</strong> ({@code net.sf.saxon}): recognized by package prefix and handed to {@link SaxonProvider#configure(TransformerFactory)} for the * channels the standard JAXP knobs cannot close (reflection-based extension functions, the collection finder, the internal SAX parser). It is then diff --git a/src/main/java/org/apache/commons/xml/secure/SecureTransformerHandler.java b/src/main/java/org/apache/commons/xml/secure/SecureTransformerHandler.java index c8cf1f2..c71bd98 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureTransformerHandler.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureTransformerHandler.java @@ -44,7 +44,7 @@ final class SecureTransformerHandler implements TransformerHandler { private final TransformerHandler delegate; /** - * Wraps the handler's LIVE transformer; constructing it installs the resolver floor that the handler's own transform then runs under. + * Wraps the handler's live transformer; constructing it installs the resolver floor that the handler's own transform then runs under. */ private final SecureTransformer transformer; diff --git a/src/main/java/org/apache/commons/xml/secure/SecureXMLFilter.java b/src/main/java/org/apache/commons/xml/secure/SecureXMLFilter.java index 8af7779..8741872 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureXMLFilter.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureXMLFilter.java @@ -95,7 +95,7 @@ public void error(final TransformerException e) throws TransformerException { /** * Forwards a fatal transformation error to the caller-set {@link org.xml.sax.ErrorHandler}, then fails the parse like a SAX parser does after - * {@code fatalError}: some implementations' lenient default listeners would otherwise only print and truncate the parse silently. + * {@code fatalError}: some implementations' lenient default listeners would otherwise only print and abort the parse silently. */ @Override public void fatalError(final TransformerException e) throws TransformerException { diff --git a/src/main/java/org/apache/commons/xml/secure/SecureXMLInputFactory.java b/src/main/java/org/apache/commons/xml/secure/SecureXMLInputFactory.java index aa57196..e4fc358 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureXMLInputFactory.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureXMLInputFactory.java @@ -49,29 +49,30 @@ public final class SecureXMLInputFactory { /** - * {@link XMLInputFactory} wrapper that installs a non-removable {@link FallbackIgnoreXMLResolver} floor on the delegate's entity-resolution hook and keeps it - * non-removable by the caller. - * - * <p>The constructor installs the floor through {@code setXMLResolver}, which every implementation routes external resolution through (Woodstox fans it out to - * both its DTD-subset and entity resolvers). Woodstox keeps one hook outside that fan-out, {@value SecureXMLInputFactory#WSTX_UNDECLARED_ENTITY_RESOLVER}, which is - * deliberately left empty: emptying the external subset leaves any entity it declared undeclared, and Woodstox then rejects the reference. The rejection is - * implementation-prescribed and keeps the resource just as unfetched as the empty resolution the other implementations produce; a caller who wants those - * references resolved can still set the property, and their resolver lands behind a floor like on every other resolver hook.</p> - * - * <p>Every resolver-valued entry point ({@link #setXMLResolver(XMLResolver)}, {@code setProperty(XMLInputFactory.RESOLVER, ...)} and the Woodstox + * {@link XMLInputFactory} wrapper that installs a non-removable {@link FallbackIgnoreXMLResolver} floor on the delegate's entity-resolution hook so the + * caller cannot remove it. + * <p> + * The constructor installs the floor through {@code setXMLResolver}, which every implementation routes external resolution through (Woodstox fans it out to + * both its DTD-subset and entity resolvers). Woodstox keeps one hook outside that fan-out, {@value SecureXMLInputFactory#WSTX_UNDECLARED_ENTITY_RESOLVER}, + * which is deliberately left empty: emptying the external subset leaves any entity it declared undeclared, and Woodstox then rejects the reference. The + * rejection is implementation-prescribed and keeps the resource unfetched, like the empty resolution the other implementations produce; a caller who wants + * those references resolved can still set the property, and their resolver lands behind a floor like on every other resolver hook. + * </p> + * <p> + * Every resolver-valued entry point ({@link #setXMLResolver(XMLResolver)}, {@code setProperty(XMLInputFactory.RESOLVER, ...)} and the Woodstox * {@code com.ctc.wstx.*Resolver} keys) is routed uniformly: a caller who supplies their own {@link FallbackIgnoreXMLResolver} takes control and it is - * passed straight to the delegate; otherwise the caller's resolver is wrapped in a new floor installed on that hook, so the caller's opt-in cannot be removed - * by dropping the resolver. This matters because Woodstox does not chain resolvers: when a resolver returns {@code null}, {@code DefaultInputResolver} falls - * through to fetching the systemId URL itself, so a caller-set resolver that returns {@code null} must still land behind the floor. {@link #getXMLResolver()} and - * {@code getProperty} report the caller's resolver unwrapped.</p> - * - * <p>The floor on a hook is replaced rather than mutated, which is what keeps each hook and each reader independent. Woodstox routes - * {@code setXMLResolver} to both its DTD-subset and entity hooks, so one floor object sits on several of them, and it copies that reference into every - * reader it creates; setting a delegate on the object in place would therefore also answer hooks the caller never named, and would change the resolution - * policy of readers already created, including ones parsing on another thread. Installing a new floor leaves both untouched: a hook keeps whatever floor it - * was given, and a reader keeps the one it captured when it was created.</p> - * - * @see org.apache.commons.xml.secure + * passed straight to the delegate; otherwise the caller's resolver is wrapped in a new floor installed on that hook, so the caller's opt-in cannot be + * removed by dropping the resolver. This matters because Woodstox does not chain resolvers: when a resolver returns {@code null}, + * {@code DefaultInputResolver} falls through to fetching the systemId URL itself, so a caller-set resolver that returns {@code null} must still land behind + * the floor. {@link #getXMLResolver()} and {@code getProperty} report the caller's resolver unwrapped. + * </p> + * <p> + * The floor on a hook is replaced rather than mutated, which is what keeps each hook and each reader independent. Woodstox routes {@code setXMLResolver} to + * both its DTD-subset and entity hooks, so one floor object sits on several of them, and it copies that reference into every reader it creates; setting a + * delegate on the object in place would therefore also answer hooks the caller never named, and would change the resolution policy of readers already + * created, including ones parsing on another thread. Installing a new floor leaves both untouched: a hook keeps whatever floor it was given, and a reader + * keeps the one it captured when it was created. + * </p> */ private static final class Wrapper extends XMLInputFactory { @@ -284,7 +285,7 @@ public static XMLInputFactory newDefaultFactory() { } /** - * Returns a new, secure {@link XMLInputFactory}, as by {@link XMLInputFactory#newFactory()}. + * Returns a new, secure {@link XMLInputFactory}, like {@link XMLInputFactory#newFactory()}. * * @return A secure factory. * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. diff --git a/src/main/java/org/apache/commons/xml/secure/SecureXPathFactory.java b/src/main/java/org/apache/commons/xml/secure/SecureXPathFactory.java index b324971..d7ca9a6 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureXPathFactory.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureXPathFactory.java @@ -49,12 +49,11 @@ public final class SecureXPathFactory { /** * {@link XPathFactory} wrapper that returns a {@link SecureXPath} from {@link #newXPath()}. - * - * <p>Required because {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} on the factory governs only the XPath engine: the stock JDK and Apache Xalan - * implement the {@link org.xml.sax.InputSource}-taking {@code evaluate} entry points by provisioning an internal document parser the feature does not reach. - * The wrapper performs that document build itself through a secure parser instead; see {@link SecureXPath}.</p> - * - * @see org.apache.commons.xml.secure + * <p> + * Required because {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} on the factory governs only the XPath engine: the stock JDK and Apache Xalan + * implement the {@link org.xml.sax.InputSource}-taking {@code evaluate} entry points by provisioning an internal document parser the feature does not + * reach. The wrapper performs that document build itself through a secure parser instead; see {@link SecureXPath}. + * </p> */ private static final class Wrapper extends XPathFactory { @@ -77,10 +76,11 @@ public boolean getFeature(final String name) throws XPathFactoryConfigurationExc /** * Reports a property of the delegate, the Java 18 {@code XPathFactory.getProperty(String)}. - * - * <p>Not marked {@code @Override}: this library compiles against the Java 8 API, where {@link XPathFactory} declares no such method, so the annotation + * <p> + * Not marked {@code @Override}: this library compiles against the Java 8 API, where {@link XPathFactory} declares no such method, so the annotation * would not compile. At run time on Java 18 or later it overrides the inherited method, which would otherwise answer for the wrapper and hide the - * delegate's own limits ({@code jdk.xml.xpath*}) behind an {@code UnsupportedOperationException}.</p> + * delegate's own limits ({@code jdk.xml.xpath*}) behind an {@code UnsupportedOperationException}. + * </p> * * @param name the property name. * @return the delegate's value for the property. @@ -106,9 +106,10 @@ public XPath newXPath() { /** * Tests whether parsers should be instantiated via {@code newInstance()} instead of {@code newDefaultInstance()}. - * - * <p>The JDK implementation of {@link XPathFactory} uses the JDK parsers while {@value SecureSAXParserFactory#OVERRIDE_DEFAULT_PARSER} is unset or - * {@code false}.</p> + * <p> + * The JDK implementation of {@link XPathFactory} uses the JDK parsers while {@value SecureSAXParserFactory#OVERRIDE_DEFAULT_PARSER} is unset or + * {@code false}. + * </p> * * @return {@code true} if parsers should be created via {@code newInstance()}. */ @@ -159,10 +160,10 @@ public void setXPathVariableResolver(final XPathVariableResolver resolver) { private static final MethodHandle MH_newDefaultInstance = MethodHandleFactory.findStatic(XPathFactory.class, "newDefaultInstance"); - /** {@code XPathFactory.getProperty(String)}, added in Java 18; {@code null} on earlier releases, where the method does not exist to be called. */ + /** {@code XPathFactory.getProperty(String)}, added in Java 18; {@code null} on earlier releases, where the method does not exist. */ private static final MethodHandle MH_getProperty = MethodHandleFactory.findVirtual(XPathFactory.class, "getProperty", String.class, String.class); - /** {@code XPathFactory.setProperty(String, String)}, added in Java 18; {@code null} on earlier releases, where the method does not exist to be called. */ + /** {@code XPathFactory.setProperty(String, String)}, added in Java 18; {@code null} on earlier releases, where the method does not exist. */ private static final MethodHandle MH_setProperty = MethodHandleFactory.findVirtual(XPathFactory.class, "setProperty", void.class, String.class, String.class); @@ -254,7 +255,7 @@ public static XPathFactory newInstance(final String uri, final String factoryCla * </ul> * * @param factory The factory to secure. - * @return A new secure factory or the original factory, secure, if it is a known Saxon factory. + * @return A new secure factory or the original factory, as-is, if it is a known Saxon factory. * @throws SecureException Thrown if this {@link XPathFactory} or the {@code XPath}s it creates cannot support this feature. */ static XPathFactory secure(final XPathFactory factory) { diff --git a/src/test/java/org/apache/commons/xml/secure/AttackTestSupport.java b/src/test/java/org/apache/commons/xml/secure/AttackTestSupport.java index 77e5e7d..d869713 100644 --- a/src/test/java/org/apache/commons/xml/secure/AttackTestSupport.java +++ b/src/test/java/org/apache/commons/xml/secure/AttackTestSupport.java @@ -78,7 +78,7 @@ * <p>The permissive-side positive controls mirror the secure-side verbs with an {@code assertPermissive*} prefix: {@code assertPermissive*Parses} for direct * parsing, {@code assertPermissive*Compiles} for {@link SchemaFactory} / {@link TransformerFactory} compilation, {@code assertPermissiveTransformerTransforms} * for {@code Transformer.transform}, {@code assertPermissiveValidatorValidates} for {@code Validator.validate}. Both sides perform the same operation; the - * prefix marks which factory secure level the assertion is set against.</p> + * prefix marks which secure factory level the assertion is set against.</p> * * <p>Schema and Templates assertions take a {@link Source} so the same helper covers both inline-string payloads and resource-backed wrappers; build the * source via {@link #streamSource(String)} for a string payload or {@link #resourceSource(String)} for a file under {@code src/test/resources/leaked/}. The diff --git a/src/test/java/org/apache/commons/xml/secure/BillionLaughsTest.java b/src/test/java/org/apache/commons/xml/secure/BillionLaughsTest.java index 7865cf0..ab655ba 100644 --- a/src/test/java/org/apache/commons/xml/secure/BillionLaughsTest.java +++ b/src/test/java/org/apache/commons/xml/secure/BillionLaughsTest.java @@ -26,7 +26,7 @@ * * <p>Each {@code secure*} test asserts the library blocks the payload; * its {@code unconfigured*} positive control asserts the same payload parses once the limit is disabled, - * so a block reflects the secure rather than a broken wrapper. + * so a block reflects the securing rather than a broken wrapper. * The library pins no custom entity-expansion limit; each parser keeps its own secure-processing default, which varies by implementation: * {@code 2,500} (stock JDK), * {@code 64,000} (external Xerces under {@code FEATURE_SECURE_PROCESSING}), diff --git a/src/test/java/org/apache/commons/xml/secure/EntityResolverFloorTest.java b/src/test/java/org/apache/commons/xml/secure/EntityResolverFloorTest.java index a3e6641..b09c277 100644 --- a/src/test/java/org/apache/commons/xml/secure/EntityResolverFloorTest.java +++ b/src/test/java/org/apache/commons/xml/secure/EntityResolverFloorTest.java @@ -78,7 +78,7 @@ class EntityResolverFloorTest { /** * Allow-all resolver: it denies nothing, resolving whatever {@code systemId} it is handed by opening it as a URL. It nonetheless cannot resolve a bare * relative reference such as {@code referenced.xml}, because a plain {@link EntityResolver} (unlike {@link org.xml.sax.ext.EntityResolver2}) is given no - * base URI and the SAX2 contract promises it an already-absolutized {@code systemId}. So the resolution fails not from any deny decision but because the + * base URI and the SAX 2 contract promises it an already-absolutized {@code systemId}. So the resolution fails not from any deny decision but because the * resolver was never handed the whole URL: it succeeds only if the floor absolutizes the XInclude href against the base before consulting the caller. */ private static final EntityResolver RESOLVE_ALL = (publicId, systemId) -> { diff --git a/src/test/java/org/apache/commons/xml/secure/ExternalParameterEntityTest.java b/src/test/java/org/apache/commons/xml/secure/ExternalParameterEntityTest.java index 2ccc4e5..b62da43 100644 --- a/src/test/java/org/apache/commons/xml/secure/ExternalParameterEntityTest.java +++ b/src/test/java/org/apache/commons/xml/secure/ExternalParameterEntityTest.java @@ -40,7 +40,7 @@ * <p>The wrapper declares a parameter entity {@code %xxe;} pointing at {@code src/test/resources/leaked/referenced.dtd} and immediately references it in the * internal subset; once expanded, the entity declarations from {@code referenced.dtd} (in particular {@code <!ENTITY leaked "...">}) become part of the * document's DTD. Each wrapper body then references {@code &leaked;}, and a secure parser resolves the parameter-entity expansion to empty, which leaves - * {@code &leaked;} undeclared. This is the one payload in the suite with a genuinely undeclared entity, so the secure outcome is dual: the parser either + * {@code &leaked;} undeclared. This is the one payload in the suite with a genuinely undeclared entity, so the secure outcome is twofold: the parser either * skips the undefined reference (no leak) or rejects it (per XML 1.0 section 4.1 the reference is an unreported validity constraint here, but the JDK's parser * reports it as a well-formedness error and Woodstox rejects undeclared references unconditionally). Either way the external DTD is never fetched. An * unconfigured parser fetches and resolves it, and the parse succeeds.</p> diff --git a/src/test/java/org/apache/commons/xml/secure/SaxonXPathExternalCallsTest.java b/src/test/java/org/apache/commons/xml/secure/SaxonXPathExternalCallsTest.java index b6ff607..9eef91a 100644 --- a/src/test/java/org/apache/commons/xml/secure/SaxonXPathExternalCallsTest.java +++ b/src/test/java/org/apache/commons/xml/secure/SaxonXPathExternalCallsTest.java @@ -34,7 +34,7 @@ * * <p>Saxon ships several XPath 3.1 functions that open arbitrary URIs during evaluation. None require a context node; each is triggered purely by the string * URI it receives. They are <em>not</em> classified as extension functions in Saxon's vocabulary, so disabling {@code ALLOW_EXTERNAL_FUNCTIONS} is not enough - * to block them; a complete secure has to close the URI-resolution path.</p> + * to block them; a complete securing has to close the URI-resolution path.</p> * * <p>Each fixture under {@code src/test/resources/leaked/} contains the {@link #MARKER} string. The tests dispatch the URI-fetching function at the file's URL * and check whether the marker reaches the result.</p> diff --git a/src/test/java/org/apache/commons/xml/secure/XIncludeTest.java b/src/test/java/org/apache/commons/xml/secure/XIncludeTest.java index 3426bef..3101b44 100644 --- a/src/test/java/org/apache/commons/xml/secure/XIncludeTest.java +++ b/src/test/java/org/apache/commons/xml/secure/XIncludeTest.java @@ -56,7 +56,7 @@ class XIncludeTest { /** * Allow-lists the two fixture URLs, returning the appropriate in-memory content for each: {@link #RESOLVED_MARKER} * wrapped as XML for {@link #REFERENCED_XML}, and as plain text for {@link #REFERENCED_TEXT}. Anything else returns - * {@code null} so the securing's ignore-all floor empties it. Mirrors a caller allow-listing trusted resources. + * {@code null} so the securing's ignore-all floor resolves it to empty. Mirrors a caller allow-listing trusted resources. */ private static final class AllowListResolver implements EntityResolver {
