From e7bad6e19e5c7736f1ae38c8fe6cd6308e0b6137 Mon Sep 17 00:00:00 2001 From: Elliotte Rusty Harold Date: Wed, 2 Sep 2026 10:24:27 -0400 Subject: [PATCH] Fix Javadoc issues per Oracle conventions --- .../secure/FallbackIgnoreEntityResolver2.java | 26 ++-- .../FallbackIgnoreLSResourceResolver.java | 6 +- .../xml/secure/FallbackIgnoreURIResolver.java | 20 +-- .../xml/secure/FallbackIgnoreXMLResolver.java | 6 +- .../xml/secure/MethodHandleFactory.java | 24 ++-- .../commons/xml/secure/SaxonProvider.java | 10 +- .../xml/secure/SecureDocumentBuilder.java | 4 +- .../secure/SecureDocumentBuilderFactory.java | 106 ++++++++-------- .../commons/xml/secure/SecureException.java | 26 ++-- .../commons/xml/secure/SecureSAXParser.java | 4 +- .../xml/secure/SecureSAXParserFactory.java | 120 ++++++++++-------- .../commons/xml/secure/SecureSchema.java | 6 +- .../xml/secure/SecureSchemaFactory.java | 68 +++++----- .../commons/xml/secure/SecureTemplates.java | 12 +- .../xml/secure/SecureTemplatesHandler.java | 10 +- .../commons/xml/secure/SecureTransformer.java | 16 +-- .../xml/secure/SecureTransformerFactory.java | 94 +++++++------- .../xml/secure/SecureTransformerHandler.java | 10 +- .../commons/xml/secure/SecureValidator.java | 10 +- .../xml/secure/SecureValidatorHandler.java | 4 +- .../commons/xml/secure/SecureXMLFilter.java | 16 ++- .../xml/secure/SecureXMLInputFactory.java | 48 +++---- .../commons/xml/secure/SecureXMLReader.java | 6 +- .../commons/xml/secure/SecureXPath.java | 30 ++--- .../xml/secure/SecureXPathExpression.java | 14 +- .../xml/secure/SecureXPathFactory.java | 86 +++++++------ 26 files changed, 407 insertions(+), 375 deletions(-) diff --git a/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreEntityResolver2.java b/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreEntityResolver2.java index 50e6e4dd..63f4404b 100644 --- a/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreEntityResolver2.java +++ b/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreEntityResolver2.java @@ -55,9 +55,9 @@ final class FallbackIgnoreEntityResolver2 extends DefaultHandler2 { /** * Resolves {@code systemId} against {@code baseURI}. * - * @param baseURI The absolute base URI to resolve against, or {@code null} if none is available. - * @param systemId The system identifier, possibly relative to {@code baseURI}. - * @return The absolutized system identifier, or {@code systemId} unchanged when it cannot or need not be resolved. + * @param baseURI the absolute base URI to resolve against, or {@code null} if none is available + * @param systemId the system identifier, possibly relative to {@code baseURI} + * @return the absolutized system identifier, or {@code systemId} unchanged when it cannot or need not be resolved */ private static String absolutize(final String baseURI, final String systemId) { if (systemId == null || baseURI == null) { @@ -79,7 +79,7 @@ private static String absolutize(final String baseURI, final String systemId) { /** * 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. + * @param delegate the caller-supplied resolver, or {@code null} for a pure ignore-all floor */ FallbackIgnoreEntityResolver2(final EntityResolver delegate) { this.delegate = delegate; @@ -88,7 +88,7 @@ private static String absolutize(final String baseURI, final String systemId) { /** * 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}. + * @return the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null} */ EntityResolver getDelegate() { return delegate; @@ -105,13 +105,13 @@ public InputSource getExternalSubset(final String name, final String baseURI) th * fetched nor leaked and the parse continues with no replacement text. The returned source echoes the requested identifiers (with {@code systemId} * absolutized): the parser reads the empty byte stream, but Xerces still derives the entity's base URI from the system id and fails on a {@code null} one. * - * @param name The entity name, or {@code null} on the 2-arg resolution path. - * @param publicId The public identifier, or {@code null} if none. - * @param baseURI The base URI for relative resolution, or {@code null}. - * @param systemId The system identifier of the unresolved entity. - * @return an empty {@link InputSource} carrying the requested identifiers. - * @throws SAXException when {@value SecureException#THROW_ON_UNRESOLVED} is set: unresolved references are rejected instead of resolved to empty. - * @throws IOException never by the default implementation. + * @param name the entity name, or {@code null} on the 2-arg resolution path + * @param publicId the public identifier, or {@code null} if none + * @param baseURI the base URI for relative resolution, or {@code null} + * @param systemId the system identifier of the unresolved entity + * @return an empty {@link InputSource} carrying the requested identifiers + * @throws IOException never by the default implementation + * @throws SAXException when {@value SecureException#THROW_ON_UNRESOLVED} is set: unresolved references are rejected instead of resolved to empty */ private InputSource onUnresolved(final String name, final String publicId, final String baseURI, final String systemId) throws SAXException { if (SecureException.throwOnUnresolved()) { @@ -148,7 +148,7 @@ private InputSource resolveWithDelegate(final String name, final String publicId /** * Replaces the caller resolver consulted ahead of the floor; lets a single floor instance back successive {@code setEntityResolver} calls. * - * @param delegate The caller-supplied resolver, or {@code null} for a pure ignore-all floor. + * @param delegate the caller-supplied resolver, or {@code null} for a pure ignore-all floor */ void setDelegate(final EntityResolver delegate) { this.delegate = delegate; diff --git a/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreLSResourceResolver.java b/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreLSResourceResolver.java index 06ae99e7..3d943169 100644 --- a/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreLSResourceResolver.java +++ b/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreLSResourceResolver.java @@ -52,7 +52,7 @@ final class FallbackIgnoreLSResourceResolver implements LSResourceResolver { /** * 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}. + * @param delegate optional caller-supplied resolver to consult first; may be {@code null} */ FallbackIgnoreLSResourceResolver(final LSResourceResolver delegate) { this.delegate = delegate; @@ -61,7 +61,7 @@ final class FallbackIgnoreLSResourceResolver implements LSResourceResolver { /** * 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}. + * @return the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null} */ LSResourceResolver getDelegate() { return delegate; @@ -91,7 +91,7 @@ public LSInput resolveResource(final String type, final String namespaceURI, fin /** * Sets the delegate to consult first, replacing any previous delegate. A {@code null} value removes the delegate and leaves a pure ignore-all floor. * - * @param delegate The delegate to consult first, or {@code null} for a pure ignore-all floor. + * @param delegate the delegate to consult first, or {@code null} for a pure ignore-all floor */ void setDelegate(final LSResourceResolver delegate) { this.delegate = delegate; 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 1e67c384..778c9082 100644 --- a/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreURIResolver.java +++ b/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreURIResolver.java @@ -61,9 +61,9 @@ final class FallbackIgnoreURIResolver implements URIResolver { * received cannot surface in another resolution. *

* - * @param factory the factory to create the document builder with. - * @return a new empty document. - * @throws IllegalStateException Thrown if the factory cannot supply a {@link javax.xml.parsers.DocumentBuilder} satisfying its configuration. + * @param factory the factory to create the document builder with + * @return a new empty document + * @throws IllegalStateException thrown if the factory cannot supply a {@link javax.xml.parsers.DocumentBuilder} satisfying its configuration */ private static Document newEmptyDocument(final DocumentBuilderFactory factory) { try { @@ -89,9 +89,9 @@ private static Document newEmptyDocument(final DocumentBuilderFactory factory) { /** * Constructs a new resolver. * - * @param delegate the resolver to delegate resolution to; may be {@code null}. - * @param emptySource the empty-{@link Source} supplier for the ignore outcome, or {@code null} for the default empty DOM document. - * @param overrideDefaultParser whether the opted-in rewrite should use the pluggable parser lookup instead of the platform's built-in parser, read at each resolution. + * @param delegate the resolver to delegate resolution to; may be {@code null} + * @param emptySource the empty-{@link Source} supplier for the ignore outcome, or {@code null} for the default empty DOM document + * @param overrideDefaultParser whether the opted-in rewrite should use the pluggable parser lookup instead of the platform's built-in parser, read at each resolution */ FallbackIgnoreURIResolver(final URIResolver delegate, final Supplier emptySource, final BooleanSupplier overrideDefaultParser) { this.delegate = delegate; @@ -103,7 +103,7 @@ private static Document newEmptyDocument(final DocumentBuilderFactory factory) { /** * 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}. + * @return the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null} */ URIResolver getDelegate() { return delegate; @@ -112,8 +112,8 @@ URIResolver getDelegate() { /** * {@inheritDoc} * - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated */ @Override public Source resolve(final String href, final String base) throws TransformerException { @@ -131,7 +131,7 @@ public Source resolve(final String href, final String base) throws TransformerEx /** * Sets the delegate to consult first, replacing any previous delegate. A {@code null} value removes the delegate and leaves a pure ignore-all floor. * - * @param delegate The delegate to consult first, or {@code null} for a pure ignore-all floor. + * @param delegate the delegate to consult first, or {@code null} for a pure ignore-all floor */ void setDelegate(final URIResolver delegate) { this.delegate = delegate; diff --git a/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreXMLResolver.java b/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreXMLResolver.java index 93a5c4c6..0cac4769 100644 --- a/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreXMLResolver.java +++ b/src/main/java/org/apache/commons/xml/secure/FallbackIgnoreXMLResolver.java @@ -45,7 +45,7 @@ final class FallbackIgnoreXMLResolver implements XMLResolver { /** * 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}. + * @param delegate optional caller-supplied resolver to consult first; may be {@code null} */ FallbackIgnoreXMLResolver(final XMLResolver delegate) { this.delegate = delegate; @@ -54,7 +54,7 @@ final class FallbackIgnoreXMLResolver implements XMLResolver { /** * 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}. + * @return the delegate provided by the constructor or set by {@link #setDelegate}, may be {@code null} */ XMLResolver getDelegate() { return delegate; @@ -78,7 +78,7 @@ public Object resolveEntity(final String publicID, final String systemID, final * A null value removes the delegate and leaves a pure ignore-all floor. *

* - * @param delegate The delegate to consult first, replacing any previous delegate. + * @param delegate the delegate to consult first, replacing any previous delegate */ void setDelegate(final XMLResolver delegate) { this.delegate = delegate; 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 2e2f3e30..724b3ec4 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 { /** * 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 Thrown if a security manager is present and it refuses access. - * @throws NullPointerException Thrown 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 NullPointerException thrown if any argument is null + * @throws SecurityException thrown if a security manager is present and it refuses access */ static MethodHandle findStatic(final Class refcAndReturnType, final String name) { try { @@ -56,13 +56,13 @@ static MethodHandle findStatic(final Class refcAndReturnType, final String na * running platform does not have it. *

* - * @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 refuses access. - * @throws NullPointerException Thrown 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 NullPointerException thrown if any argument is null + * @throws SecurityException thrown if a security manager is present and it refuses access */ 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/SaxonProvider.java b/src/main/java/org/apache/commons/xml/secure/SaxonProvider.java index ac555992..1efb9044 100644 --- a/src/main/java/org/apache/commons/xml/secure/SaxonProvider.java +++ b/src/main/java/org/apache/commons/xml/secure/SaxonProvider.java @@ -91,7 +91,9 @@ private static final class SecureConfiguration extends Configuration { private static final String JDK_DEFAULT_PARSER = "#DEFAULT"; - /** Collection-level ignore: {@code fn:collection()} and {@code fn:uri-collection()} resolve to an empty collection instead of fetching. */ + /** + * Collection-level ignore: {@code fn:collection()} and {@code fn:uri-collection()} resolve to an empty collection instead of fetching. + */ private static final CollectionFinder EMPTY_COLLECTION_FINDER = (context, collectionURI) -> { if (SecureException.throwOnUnresolved()) { throw new XPathException(SecureException.forbidden("collection", null, null, collectionURI, null)); @@ -144,7 +146,7 @@ static XPathFactory configure(final XPathFactory factory) { /** * The empty-{@link Source} shape Saxon's consumers expect, for the {@link FallbackIgnoreURIResolver} floor the TrAX wrapper installs. * - * @return a supplier for Saxon's empty {@link Source}. + * @return a supplier for Saxon's empty {@link Source} */ static Supplier emptySourceSupplier() { return SaxonProviderConfigurer.emptySourceSupplier(); @@ -154,8 +156,8 @@ static Supplier emptySourceSupplier() { * Tests whether the factory class is Saxon's, by package prefix, so public subclasses such as {@code net.sf.saxon.BasicTransformerFactory} route to the * same locked-down {@link Configuration} as the factory registered for JAXP lookup. * - * @param factoryClass The factory implementation class. - * @return Whether the class lives in Saxon's open-source or commercial packages. + * @param factoryClass the factory implementation class + * @return whether the class lives in Saxon's open-source or commercial packages */ static boolean isSaxon(final Class factoryClass) { final String name = factoryClass.getName(); diff --git a/src/main/java/org/apache/commons/xml/secure/SecureDocumentBuilder.java b/src/main/java/org/apache/commons/xml/secure/SecureDocumentBuilder.java index 069f3833..6c988707 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureDocumentBuilder.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureDocumentBuilder.java @@ -46,8 +46,8 @@ final class SecureDocumentBuilder extends DocumentBuilder { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @throws NullPointerException if {@code delegate} is {@code null} */ SecureDocumentBuilder(final DocumentBuilder delegate) { this.delegate = Objects.requireNonNull(delegate, "delegate"); 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 42a5e43a..4462b965 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureDocumentBuilderFactory.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureDocumentBuilderFactory.java @@ -61,8 +61,8 @@ private static final class Wrapper extends DocumentBuilderFactory { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @throws NullPointerException if {@code delegate} is {@code null} */ private Wrapper(final DocumentBuilderFactory delegate) { this.delegate = Objects.requireNonNull(delegate, "delegate"); @@ -173,12 +173,18 @@ public void setXIncludeAware(final boolean state) { delegate.setXIncludeAware(state); } } - /** Class name of Android's Harmony-based {@link DocumentBuilderFactory}, which exposes no secure surface. */ + /** + * Class name of Android's Harmony-based {@link DocumentBuilderFactory}, which exposes no secure surface. + */ private static final String ANDROID_DOCUMENT_BUILDER_FACTORY = "org.apache.harmony.xml.parsers.DocumentBuilderFactoryImpl"; - /** System property naming the {@link DocumentBuilderFactory} implementation, the JDK's own mechanism for reconfiguring the default parser. */ + /** + * System property naming the {@link DocumentBuilderFactory} implementation, the JDK's own mechanism for reconfiguring the default parser. + */ private static final String DOM_FACTORY_ID = "javax.xml.parsers.DocumentBuilderFactory"; - /** Class name of the JDK's built-in default implementation, the Java 8 fallback for {@link #newDefaultInstance()}. */ + /** + * Class name of the JDK's built-in default implementation, the Java 8 fallback for {@link #newDefaultInstance()}. + */ static final String JDK_DOCUMENT_BUILDER_FACTORY = "com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl"; private static final MethodHandle MH_newDefaultInstance = MethodHandleFactory.findStatic(DocumentBuilderFactory.class, "newDefaultInstance"); @@ -186,8 +192,8 @@ public void setXIncludeAware(final boolean state) { /** * Enables namespace awareness on the given factory; the {@code NSInstance} counterpart of each factory method routes its result through here. * - * @param factory the factory to configure; never {@code null}. - * @return The given factory, namespace-aware. + * @param factory the factory to configure; never {@code null} + * @return the given factory, namespace-aware */ private static DocumentBuilderFactory makeNSAware(final DocumentBuilderFactory factory) { factory.setNamespaceAware(true); @@ -203,10 +209,10 @@ private static DocumentBuilderFactory makeNSAware(final DocumentBuilderFactory f * (for example, Android, whose lookup is itself pinned to the platform implementation). *

* - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws FactoryConfigurationError Thrown from the {@link #newInstance()} lookup this method falls back to on a platform that provides neither - * {@code newDefaultInstance()} nor the JDK's built-in implementation (for example Android). + * @return a secure factory + * @throws FactoryConfigurationError thrown from the {@link #newInstance()} lookup this method falls back to on a platform that provides neither + * {@code newDefaultInstance()} nor the JDK's built-in implementation (for example Android) + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ public static DocumentBuilderFactory newDefaultInstance() { if (MH_newDefaultInstance != null) { @@ -225,10 +231,10 @@ public static DocumentBuilderFactory newDefaultInstance() { * Returns a new, secure, namespace-aware {@link DocumentBuilderFactory} of the system-default implementation, enabling namespace awareness on * {@link #newDefaultInstance()}, the behavior {@code DocumentBuilderFactory.newDefaultNSInstance()} (Java 13 or later) is specified to have. * - * @return A secure, namespace-aware factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws FactoryConfigurationError Thrown from the {@link #newInstance()} lookup {@link #newDefaultInstance()} falls back to on a platform that provides - * neither {@code newDefaultInstance()} nor the JDK's built-in implementation (for example Android). + * @return a secure, namespace-aware factory + * @throws FactoryConfigurationError thrown from the {@link #newInstance()} lookup {@link #newDefaultInstance()} falls back to on a platform that provides + * neither {@code newDefaultInstance()} nor the JDK's built-in implementation (for example Android) + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ public static DocumentBuilderFactory newDefaultNSInstance() { return makeNSAware(newDefaultInstance()); @@ -237,12 +243,12 @@ public static DocumentBuilderFactory newDefaultNSInstance() { /** * Returns a new, secure {@link DocumentBuilderFactory}. * - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws IllegalStateException Thrown if a (non-Android) factory cannot support the secure processing feature - * {@link XMLConstants#FEATURE_SECURE_PROCESSING}. - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service configuration error} or if the - * implementation is not available or cannot be instantiated. + * @return a secure factory + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service configuration error} or if the + * implementation is not available or cannot be instantiated + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation + * @throws IllegalStateException thrown if a (non-Android) factory cannot support the secure processing feature + * {@link XMLConstants#FEATURE_SECURE_PROCESSING} */ public static DocumentBuilderFactory newInstance() { return secure(DocumentBuilderFactory.newInstance()); @@ -251,13 +257,13 @@ public static DocumentBuilderFactory newInstance() { /** * Returns a new, secure {@link DocumentBuilderFactory} of the given implementation class. * - * @param factoryClassName The fully qualified class name of the {@link DocumentBuilderFactory} implementation. - * @param classLoader The class loader used to load the factory class; {@code null} means the current thread's context class loader. - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws IllegalStateException Thrown if a (non-Android) factory cannot support the secure processing feature - * {@link XMLConstants#FEATURE_SECURE_PROCESSING}. - * @throws FactoryConfigurationError Thrown if {@code factoryClassName} is {@code null} or the factory class cannot be loaded or instantiated. + * @param factoryClassName the fully qualified class name of the {@link DocumentBuilderFactory} implementation + * @param classLoader the class loader used to load the factory class; {@code null} means the current thread's context class loader + * @return a secure factory + * @throws FactoryConfigurationError thrown if {@code factoryClassName} is {@code null} or the factory class cannot be loaded or instantiated + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation + * @throws IllegalStateException thrown if a (non-Android) factory cannot support the secure processing feature + * {@link XMLConstants#FEATURE_SECURE_PROCESSING} */ public static DocumentBuilderFactory newInstance(final String factoryClassName, final ClassLoader classLoader) { return secure(DocumentBuilderFactory.newInstance(factoryClassName, classLoader)); @@ -267,10 +273,10 @@ public static DocumentBuilderFactory newInstance(final String factoryClassName, * Returns a new, secure, namespace-aware {@link DocumentBuilderFactory}, enabling namespace awareness on {@link #newInstance()}, the behavior * {@code DocumentBuilderFactory.newNSInstance()} (Java 13 or later) is specified to have. * - * @return A secure, namespace-aware factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service configuration error} or if the - * implementation is not available or cannot be instantiated. + * @return a secure, namespace-aware factory + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service configuration error} or if the + * implementation is not available or cannot be instantiated + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ public static DocumentBuilderFactory newNSInstance() { return makeNSAware(newInstance()); @@ -284,11 +290,11 @@ public static DocumentBuilderFactory newNSInstance() { * reconfiguring the default parser, so it is honored through the standard lookup rather than bypassed. *

* - * @param overrideDefaultParser whether {@value SecureSAXParserFactory#OVERRIDE_DEFAULT_PARSER} on the originating factory asks to override the JDK's default parser. - * @return A secure, namespace-aware factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service configuration error} or if the - * implementation is not available or cannot be instantiated. + * @param overrideDefaultParser whether {@value SecureSAXParserFactory#OVERRIDE_DEFAULT_PARSER} on the originating factory asks to override the JDK's default parser + * @return a secure, namespace-aware factory + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service configuration error} or if the + * implementation is not available or cannot be instantiated + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ static DocumentBuilderFactory newNSInstance(final boolean overrideDefaultParser) { return overrideDefaultParser || System.getProperty(DOM_FACTORY_ID) != null ? newNSInstance() : newDefaultNSInstance(); @@ -299,11 +305,11 @@ static DocumentBuilderFactory newNSInstance(final boolean overrideDefaultParser) * {@link #newInstance(String, ClassLoader)}, the behavior {@code DocumentBuilderFactory.newNSInstance(String, ClassLoader)} (Java 13 or later) is specified * to have. * - * @param factoryClassName The fully qualified class name of the {@link DocumentBuilderFactory} implementation. - * @param classLoader The class loader used to load the factory class; {@code null} means the current thread's context class loader. - * @return A secure, namespace-aware factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws FactoryConfigurationError Thrown if {@code factoryClassName} is {@code null} or the factory class cannot be loaded or instantiated. + * @param factoryClassName the fully qualified class name of the {@link DocumentBuilderFactory} implementation + * @param classLoader the class loader used to load the factory class; {@code null} means the current thread's context class loader + * @return a secure, namespace-aware factory + * @throws FactoryConfigurationError thrown if {@code factoryClassName} is {@code null} or the factory class cannot be loaded or instantiated + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ public static DocumentBuilderFactory newNSInstance(final String factoryClassName, final ClassLoader classLoader) { return makeNSAware(newInstance(factoryClassName, classLoader)); @@ -324,9 +330,9 @@ public static DocumentBuilderFactory newNSInstance(final String factoryClassName * needed here. A caller can chain its own resolver onto the floor to allow-list resources, but cannot remove it. * * - * @param factory The factory to secure. - * @return A new secure factory or the original factory, as-is, if it is a known Android factory. - * @throws SecureException Thrown if a (non-Android) factory cannot support the secure processing feature {@link XMLConstants#FEATURE_SECURE_PROCESSING}. + * @param factory the factory to secure + * @return a new secure factory or the original factory, as-is, if it is a known Android factory + * @throws SecureException thrown if a (non-Android) factory cannot support the secure processing feature {@link XMLConstants#FEATURE_SECURE_PROCESSING} */ static DocumentBuilderFactory secure(final DocumentBuilderFactory factory) { // Android exposes no FSP, ACCESS_EXTERNAL_* or attribute API, and KXmlParser drops user-defined entities; nothing to apply. @@ -344,11 +350,11 @@ static DocumentBuilderFactory secure(final DocumentBuilderFactory factory) { /** * Sets a feature on the given factory, throwing a {@link SecureException} if the implementation does not recognize it. * - * @param factory The factory to secure. - * @param feature The feature to set. - * @param value The value to set. - * @throws SecureException Thrown if this factory cannot support this feature. - * @throws NullPointerException Thrown if the {@code feature} parameter is null. + * @param factory the factory to secure + * @param feature the feature to set + * @param value the value to set + * @throws NullPointerException thrown if the {@code feature} parameter is null + * @throws SecureException thrown if this factory cannot support this feature */ private static void setFeature(final DocumentBuilderFactory factory, final String feature, final boolean value) { try { diff --git a/src/main/java/org/apache/commons/xml/secure/SecureException.java b/src/main/java/org/apache/commons/xml/secure/SecureException.java index bcfae3c8..a0e0ce54 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureException.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureException.java @@ -47,11 +47,11 @@ final class SecureException extends IllegalStateException { /** * Builds the standard exception for a rejected secure setting. - * @param name the name of the feature, attribute or property that could not be set. - * @param target the factory, parser, validator or reader that rejected the setting; its concrete class names the offending implementation. - * @param cause the original checked or unchecked exception from the JAXP implementation. * - * @return the exception to throw. + * @param name the name of the feature, attribute or property that could not be set + * @param target the factory, parser, validator or reader that rejected the setting; its concrete class names the offending implementation + * @param cause the original checked or unchecked exception from the JAXP implementation + * @return the exception to throw */ static SecureException featureFailed(final String name, final Object target, final Throwable cause) { return new SecureException("Failed to set feature '" + name + "' on " + target.getClass().getName(), cause); @@ -60,12 +60,12 @@ static SecureException featureFailed(final String name, final Object target, fin /** * Builds the standard "forbidden" message shared by every resolver floor when {@link #throwOnUnresolved()} rejects an unresolved reference. * - * @param type the resource kind, or {@code null} if not applicable. - * @param namespace the namespace (or, for Woodstox, the entity name), or {@code null}. - * @param publicId the public identifier, or {@code null} if none. - * @param systemId the system identifier of the denied resource. - * @param baseURI the base URI for relative resolution, or {@code null}. - * @return the message naming the denied lookup and the enabling property. + * @param type the resource kind, or {@code null} if not applicable + * @param namespace the namespace (or, for Woodstox, the entity name), or {@code null} + * @param publicId the public identifier, or {@code null} if none + * @param systemId the system identifier of the denied resource + * @param baseURI the base URI for relative resolution, or {@code null} + * @return the message naming the denied lookup and the enabling property */ static String forbidden(final String type, final String namespace, final String publicId, final String systemId, final String baseURI) { return String.format("External resource fetch forbidden by %s: type=%s, namespace=%s, publicId=%s, systemId=%s, baseURI=%s", @@ -78,8 +78,8 @@ static String forbidden(final String type, final String namespace, final String *

Every supported implementation provides a reader as a routine capability, so the wrapped {@code ParserConfigurationException} or * {@code SAXException} signals a broken environment, not a per-parse condition — hence unchecked.

* - * @param cause the original checked exception from the JAXP implementation. - * @return the exception to throw. + * @param cause the original checked exception from the JAXP implementation + * @return the exception to throw */ static SecureException readerFailed(final Throwable cause) { return new SecureException("Failed to create a secure XMLReader", cause); @@ -90,7 +90,7 @@ static SecureException readerFailed(final Throwable cause) { * *

Read per resolution, so the {@value SecureException#THROW_ON_UNRESOLVED} system property also toggles factories that already exist.

* - * @return {@code true} when the {@value SecureException#THROW_ON_UNRESOLVED} system property is set. + * @return {@code true} when the {@value SecureException#THROW_ON_UNRESOLVED} system property is set */ static boolean throwOnUnresolved() { return Boolean.getBoolean(SecureException.THROW_ON_UNRESOLVED); diff --git a/src/main/java/org/apache/commons/xml/secure/SecureSAXParser.java b/src/main/java/org/apache/commons/xml/secure/SecureSAXParser.java index 363da5c2..9518506c 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureSAXParser.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureSAXParser.java @@ -50,8 +50,8 @@ final class SecureSAXParser extends SAXParser { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @throws NullPointerException if {@code delegate} is {@code null} */ SecureSAXParser(final SAXParser delegate) { this.delegate = Objects.requireNonNull(delegate, "delegate"); 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 fd3320b7..0ff053ad 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureSAXParserFactory.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureSAXParserFactory.java @@ -94,8 +94,8 @@ private static final class Wrapper extends SAXParserFactory { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @throws NullPointerException if {@code delegate} is {@code null} */ private Wrapper(final SAXParserFactory delegate) { this.delegate = Objects.requireNonNull(delegate, "delegate"); @@ -156,13 +156,19 @@ public void setXIncludeAware(final boolean state) { delegate.setXIncludeAware(state); } } - /** Class name of Android's Expat-backed {@link XMLReader}. */ + /** + * Class name of Android's Expat-backed {@link XMLReader}. + */ private static final String ANDROID_EXPAT_READER = "org.apache.harmony.xml.ExpatReader"; - /** Class name of Android's Harmony-based {@link SAXParserFactory}, backed by the native Expat parser. */ + /** + * Class name of Android's Harmony-based {@link SAXParserFactory}, backed by the native Expat parser. + */ private static final String ANDROID_SAX_PARSER_FACTORY = "org.apache.harmony.xml.parsers.SAXParserFactoryImpl"; - /** Class name of the JDK's built-in default implementation, the Java 8 fallback for {@link #newDefaultInstance()}. */ + /** + * Class name of the JDK's built-in default implementation, the Java 8 fallback for {@link #newDefaultInstance()}. + */ static final String JDK_SAX_PARSER_FACTORY = "com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl"; /** @@ -171,7 +177,9 @@ public void setXIncludeAware(final boolean state) { */ static final String OVERRIDE_DEFAULT_PARSER = "jdk.xml.overrideDefaultParser"; - /** System property naming the {@link SAXParserFactory} implementation, the JDK's own mechanism for reconfiguring the default parser. */ + /** + * System property naming the {@link SAXParserFactory} implementation, the JDK's own mechanism for reconfiguring the default parser. + */ private static final String SAX_FACTORY_ID = "javax.xml.parsers.SAXParserFactory"; private static final MethodHandle MH_newDefaultInstance = MethodHandleFactory.findStatic(SAXParserFactory.class, "newDefaultInstance"); @@ -179,8 +187,8 @@ public void setXIncludeAware(final boolean state) { /** * Enables namespace awareness on the given factory; the {@code NSInstance} counterpart of each factory method routes its result through here. * - * @param factory the factory to configure; never {@code null}. - * @return The given factory, namespace-aware. + * @param factory the factory to configure; never {@code null} + * @return the given factory, namespace-aware */ private static SAXParserFactory makeNSAware(final SAXParserFactory factory) { factory.setNamespaceAware(true); @@ -196,10 +204,10 @@ private static SAXParserFactory makeNSAware(final SAXParserFactory factory) { * (for example, Android, whose lookup is itself pinned to the platform implementation). *

* - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws FactoryConfigurationError Thrown from the {@link #newInstance()} lookup this method falls back to on a platform that provides neither - * {@code newDefaultInstance()} nor the JDK's built-in implementation (for example Android). + * @return a secure factory + * @throws FactoryConfigurationError thrown from the {@link #newInstance()} lookup this method falls back to on a platform that provides neither + * {@code newDefaultInstance()} nor the JDK's built-in implementation (for example Android) + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ public static SAXParserFactory newDefaultInstance() { if (MH_newDefaultInstance != null) { @@ -218,10 +226,10 @@ public static SAXParserFactory newDefaultInstance() { * Returns a new, secure, namespace-aware {@link SAXParserFactory} of the system-default implementation, enabling namespace awareness on * {@link #newDefaultInstance()}, the behavior {@code SAXParserFactory.newDefaultNSInstance()} (Java 13 or later) is specified to have. * - * @return A secure, namespace-aware factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws FactoryConfigurationError Thrown from the {@link #newInstance()} lookup {@link #newDefaultInstance()} falls back to on a platform that provides - * neither {@code newDefaultInstance()} nor the JDK's built-in implementation (for example Android). + * @return a secure, namespace-aware factory + * @throws FactoryConfigurationError thrown from the {@link #newInstance()} lookup {@link #newDefaultInstance()} falls back to on a platform that provides + * neither {@code newDefaultInstance()} nor the JDK's built-in implementation (for example Android) + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ public static SAXParserFactory newDefaultNSInstance() { return makeNSAware(newDefaultInstance()); @@ -230,10 +238,10 @@ public static SAXParserFactory newDefaultNSInstance() { /** * Returns a new, secure {@link SAXParserFactory}. * - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws FactoryConfigurationError Thrown from {@link SAXParserFactory} in case of a {@link java.util.ServiceConfigurationError service configuration - * error} or if the implementation is not available or cannot be instantiated. + * @return a secure factory + * @throws FactoryConfigurationError thrown from {@link SAXParserFactory} in case of a {@link java.util.ServiceConfigurationError service configuration + * error} or if the implementation is not available or cannot be instantiated + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ public static SAXParserFactory newInstance() { return secure(SAXParserFactory.newInstance()); @@ -242,11 +250,11 @@ public static SAXParserFactory newInstance() { /** * Returns a new, secure {@link SAXParserFactory} of the given implementation class. * - * @param factoryClassName The fully qualified class name of the {@link SAXParserFactory} implementation. - * @param classLoader The class loader used to load the factory class; {@code null} means the current thread's context class loader. - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws FactoryConfigurationError Thrown if {@code factoryClassName} is {@code null} or the factory class cannot be loaded or instantiated. + * @param factoryClassName the fully qualified class name of the {@link SAXParserFactory} implementation + * @param classLoader the class loader used to load the factory class; {@code null} means the current thread's context class loader + * @return a secure factory + * @throws FactoryConfigurationError thrown if {@code factoryClassName} is {@code null} or the factory class cannot be loaded or instantiated + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ public static SAXParserFactory newInstance(final String factoryClassName, final ClassLoader classLoader) { return secure(SAXParserFactory.newInstance(factoryClassName, classLoader)); @@ -256,10 +264,10 @@ public static SAXParserFactory newInstance(final String factoryClassName, final * Returns a new, secure, namespace-aware {@link SAXParserFactory}, enabling namespace awareness on {@link #newInstance()}, the behavior * {@code SAXParserFactory.newNSInstance()} (Java 13 or later) is specified to have. * - * @return A secure, namespace-aware factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws FactoryConfigurationError Thrown from {@link SAXParserFactory} in case of a {@link java.util.ServiceConfigurationError service configuration - * error} or if the implementation is not available or cannot be instantiated. + * @return a secure, namespace-aware factory + * @throws FactoryConfigurationError thrown from {@link SAXParserFactory} in case of a {@link java.util.ServiceConfigurationError service configuration + * error} or if the implementation is not available or cannot be instantiated + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ public static SAXParserFactory newNSInstance() { return makeNSAware(newInstance()); @@ -273,11 +281,11 @@ public static SAXParserFactory newNSInstance() { * parser, so it is honored through the standard lookup rather than bypassed. *

* - * @param overrideDefaultParser whether {@value #OVERRIDE_DEFAULT_PARSER} on the originating factory asks to override the JDK's default parser. - * @return A secure, namespace-aware factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service configuration error} or if the - * implementation is not available or cannot be instantiated. + * @param overrideDefaultParser whether {@value #OVERRIDE_DEFAULT_PARSER} on the originating factory asks to override the JDK's default parser + * @return a secure, namespace-aware factory + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service configuration error} or if the + * implementation is not available or cannot be instantiated + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ static SAXParserFactory newNSInstance(final boolean overrideDefaultParser) { return overrideDefaultParser || System.getProperty(SAX_FACTORY_ID) != null ? newNSInstance() : newDefaultNSInstance(); @@ -287,11 +295,11 @@ static SAXParserFactory newNSInstance(final boolean overrideDefaultParser) { * Returns a new, secure, namespace-aware {@link SAXParserFactory} of the given implementation class, enabling namespace awareness on * {@link #newInstance(String, ClassLoader)}, the behavior {@code SAXParserFactory.newNSInstance(String, ClassLoader)} (Java 13 or later) is specified to have. * - * @param factoryClassName The fully qualified class name of the {@link SAXParserFactory} implementation. - * @param classLoader The class loader used to load the factory class; {@code null} means the current thread's context class loader. - * @return A secure, namespace-aware factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws FactoryConfigurationError Thrown if {@code factoryClassName} is {@code null} or the factory class cannot be loaded or instantiated. + * @param factoryClassName the fully qualified class name of the {@link SAXParserFactory} implementation + * @param classLoader the class loader used to load the factory class; {@code null} means the current thread's context class loader + * @return a secure, namespace-aware factory + * @throws FactoryConfigurationError thrown if {@code factoryClassName} is {@code null} or the factory class cannot be loaded or instantiated + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ public static SAXParserFactory newNSInstance(final String factoryClassName, final ClassLoader classLoader) { return makeNSAware(newInstance(factoryClassName, classLoader)); @@ -301,12 +309,12 @@ public static SAXParserFactory newNSInstance(final String factoryClassName, fina * Creates a new secure, namespace-aware {@link XMLReader} for the TrAX, XPath and schema wrappers to parse sources with, from the factory * {@link #newNSInstance(boolean)} selects. * - * @param overrideDefaultParser whether {@value #OVERRIDE_DEFAULT_PARSER} on the originating factory asks to override the JDK's default parser. - * @return a secure reader. - * @throws IllegalStateException Thrown if the underlying implementation cannot provide a secure reader; providing one is a routine capability of every - * supported implementation, so a failure signals a broken environment, not a per-parse condition. - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @param overrideDefaultParser whether {@value #OVERRIDE_DEFAULT_PARSER} on the originating factory asks to override the JDK's default parser + * @return a secure reader + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated + * @throws IllegalStateException thrown if the underlying implementation cannot provide a secure reader; providing one is a routine capability of every + * supported implementation, so a failure signals a broken environment, not a per-parse condition */ static XMLReader newXMLReader(final boolean overrideDefaultParser) { try { @@ -336,8 +344,8 @@ static XMLReader newXMLReader(final boolean overrideDefaultParser) { * chain its own resolver onto the floor to allow-list resources, but cannot remove it. * * - * @param factory the factory to secure; never {@code null}. - * @return a secure factory. + * @param factory the factory to secure; never {@code null} + * @return a secure factory */ static SAXParserFactory secure(final SAXParserFactory factory) { // Required: enables the implementation's security manager, which carries the limits. Android's Expat rejects FSP, so it is skipped there. @@ -355,12 +363,12 @@ static SAXParserFactory secure(final SAXParserFactory factory) { * as-is. Used by the TrAX and schema wrappers to route every source they parse through the secure SAX path. *

* - * @param source the source to secure; never {@code null}. - * @param overrideDefaultParser whether {@value #OVERRIDE_DEFAULT_PARSER} on the originating factory asks to override the JDK's default parser. - * @return a secure source. - * @throws IllegalStateException Thrown if the underlying implementation cannot provide a secure reader. - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @param source the source to secure; never {@code null} + * @param overrideDefaultParser whether {@value #OVERRIDE_DEFAULT_PARSER} on the originating factory asks to override the JDK's default parser + * @return a secure source + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated + * @throws IllegalStateException thrown if the underlying implementation cannot provide a secure reader */ static Source secure(final Source source, final boolean overrideDefaultParser) { if (source instanceof StreamSource || source instanceof SAXSource && ((SAXSource) source).getXMLReader() == null) { @@ -373,9 +381,9 @@ static Source secure(final Source source, final boolean overrideDefaultParser) { /** * Secures an existing {@link XMLReader}. * - * @param reader The reader to secure; never {@code null}. - * @return A secure reader. - * @throws IllegalStateException if a required secure setting cannot be applied to the underlying implementation. + * @param reader the reader to secure; never {@code null} + * @return a secure reader + * @throws IllegalStateException if a required secure setting cannot be applied to the underlying implementation */ static XMLReader secure(final XMLReader reader) { if (reader instanceof SecureXMLReader) { diff --git a/src/main/java/org/apache/commons/xml/secure/SecureSchema.java b/src/main/java/org/apache/commons/xml/secure/SecureSchema.java index eaccf80f..9d213592 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureSchema.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureSchema.java @@ -41,9 +41,9 @@ final class SecureSchema extends Schema { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @param overrideDefaultParser whether the produced Validators' source rewrites should use the pluggable parser lookup instead of the platform's built-in parser. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @param overrideDefaultParser whether the produced Validators' source rewrites should use the pluggable parser lookup instead of the platform's built-in parser + * @throws NullPointerException if {@code delegate} is {@code null} */ SecureSchema(final Schema delegate, final boolean overrideDefaultParser) { this.delegate = Objects.requireNonNull(delegate, "delegate"); 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 58c063da..a026a587 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureSchemaFactory.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureSchemaFactory.java @@ -96,8 +96,8 @@ private static final class Wrapper extends SchemaFactory { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @throws NullPointerException if {@code delegate} is {@code null} */ private Wrapper(final SchemaFactory delegate) { this.delegate = Objects.requireNonNull(delegate, "delegate"); @@ -140,8 +140,8 @@ public Schema newSchema() throws SAXException { /** * {@inheritDoc} * - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated */ @Override public Schema newSchema(final Source[] schemas) throws SAXException { @@ -154,7 +154,7 @@ public Schema newSchema(final Source[] schemas) throws SAXException { *

The JDK implementation of {@link SchemaFactory} uses the JDK parsers while {@value SecureSAXParserFactory#OVERRIDE_DEFAULT_PARSER} is unset or * {@code false}.

* - * @return {@code true} if parsers should be created via {@code newInstance()}. + * @return {@code true} if parsers should be created via {@code newInstance()} */ private boolean overrideDefaultParser() { try { @@ -167,11 +167,11 @@ private boolean overrideDefaultParser() { /** * Secures every schema source through {@link SecureSAXParserFactory#secure(Source, boolean)}. * - * @param schemas the schema sources to secure; must not be {@code null}. - * @return a new array of secure sources. - * @throws IllegalStateException Thrown if the underlying implementation cannot provide a secure reader. - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @param schemas the schema sources to secure; must not be {@code null} + * @return a new array of secure sources + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated + * @throws IllegalStateException thrown if the underlying implementation cannot provide a secure reader */ private Source[] secure(final Source[] schemas) { final Source[] secure = new Source[schemas.length]; @@ -205,7 +205,9 @@ public void setResourceResolver(final LSResourceResolver resourceResolver) { } } - /** Class name of the JDK's built-in default implementation, the Java 8 fallback for {@link #newDefaultInstance()}. */ + /** + * Class name of the JDK's built-in default implementation, the Java 8 fallback for {@link #newDefaultInstance()}. + */ private static final String JDK_SCHEMA_FACTORY = "com.sun.org.apache.xerces.internal.jaxp.validation.XMLSchemaFactory"; private static final MethodHandle MH_newDefaultInstance = MethodHandleFactory.findStatic(SchemaFactory.class, "newDefaultInstance"); @@ -218,10 +220,10 @@ public void setResourceResolver(final LSResourceResolver resourceResolver) { * whose lookup falls back to exactly the Xerces implementation this library recognizes). *

* - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws IllegalArgumentException Thrown from the {@link #newInstance(String)} lookup this method falls back to on a platform that provides neither - * {@code newDefaultInstance()} nor the JDK's built-in implementation (for example Android). + * @return a secure factory + * @throws IllegalArgumentException thrown from the {@link #newInstance(String)} lookup this method falls back to on a platform that provides neither + * {@code newDefaultInstance()} nor the JDK's built-in implementation (for example Android) + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ public static SchemaFactory newDefaultInstance() { if (MH_newDefaultInstance != null) { @@ -239,11 +241,11 @@ public static SchemaFactory newDefaultInstance() { /** * Returns a new, secure {@link SchemaFactory} for the given schema language. * - * @param schemaLanguage The schema language, as accepted by {@link SchemaFactory#newInstance(String)}. - * @return A secure factory. - * @throws IllegalArgumentException Thrown if no implementation of the schema language is available. - * @throws NullPointerException Thrown if {@code schemaLanguage} is {@code null}. - * @throws SchemaFactoryConfigurationError Thrown if a configuration error is encountered. + * @param schemaLanguage the schema language, as accepted by {@link SchemaFactory#newInstance(String)} + * @return a secure factory + * @throws IllegalArgumentException thrown if no implementation of the schema language is available + * @throws NullPointerException thrown if {@code schemaLanguage} is {@code null} + * @throws SchemaFactoryConfigurationError thrown if a configuration error is encountered */ public static SchemaFactory newInstance(final String schemaLanguage) { return secure(SchemaFactory.newInstance(schemaLanguage)); @@ -252,13 +254,13 @@ public static SchemaFactory newInstance(final String schemaLanguage) { /** * Returns a new, secure {@link SchemaFactory} of the given implementation class. * - * @param schemaLanguage The schema language, as accepted by {@link SchemaFactory#newInstance(String)}. - * @param factoryClassName The fully qualified class name of the {@link SchemaFactory} implementation. - * @param classLoader The class loader used to load the factory class; {@code null} means the current thread's context class loader. - * @return A secure factory. - * @throws IllegalArgumentException Thrown if {@code factoryClassName} is {@code null}, or if the factory class cannot be loaded or instantiated, or does - * not support {@code schemaLanguage}. - * @throws NullPointerException Thrown if {@code schemaLanguage} is {@code null}. + * @param schemaLanguage the schema language, as accepted by {@link SchemaFactory#newInstance(String)} + * @param factoryClassName the fully qualified class name of the {@link SchemaFactory} implementation + * @param classLoader the class loader used to load the factory class; {@code null} means the current thread's context class loader + * @return a secure factory + * @throws IllegalArgumentException thrown if {@code factoryClassName} is {@code null}, or if the factory class cannot be loaded or instantiated, or does + * not support {@code schemaLanguage} + * @throws NullPointerException thrown if {@code schemaLanguage} is {@code null} */ public static SchemaFactory newInstance(final String schemaLanguage, final String factoryClassName, final ClassLoader classLoader) { return secure(SchemaFactory.newInstance(schemaLanguage, factoryClassName, classLoader)); @@ -272,8 +274,8 @@ public static SchemaFactory newInstance(final String schemaLanguage, final Strin * 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.

* - * @param factory the factory to secure; never {@code null}. - * @return a secure factory. + * @param factory the factory to secure; never {@code null} + * @return a secure factory */ static SchemaFactory secure(final SchemaFactory factory) { return new Wrapper(factory); @@ -282,10 +284,10 @@ static SchemaFactory secure(final SchemaFactory factory) { /** * Sets a feature on the delegate, failing closed: an implementation that cannot accept it yields no factory rather than an unsecured one. * - * @param factory the factory to configure; never {@code null}. - * @param feature the feature name. - * @param value the value to set. - * @throws SecureException if the implementation rejects the feature. + * @param factory the factory to configure; never {@code null} + * @param feature the feature name + * @param value the value to set + * @throws SecureException if the implementation rejects the feature */ private static void setFeature(final SchemaFactory factory, final String feature, final boolean value) { try { 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 66eb84fe..dc261b5c 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureTemplates.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureTemplates.java @@ -60,11 +60,11 @@ final class SecureTemplates implements Templates { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @param uriResolver the compile-time URIResolver snapshot to restore onto Transformers produced from the compiled Templates; may be {@code null}. - * @param emptySource the empty-{@link Source} supplier for the produced Transformers. - * @param overrideDefaultParser whether the produced Transformers' source rewrites should use the pluggable parser lookup instead of the platform's built-in parser. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @param uriResolver the compile-time URIResolver snapshot to restore onto Transformers produced from the compiled Templates; may be {@code null} + * @param emptySource the empty-{@link Source} supplier for the produced Transformers + * @param overrideDefaultParser whether the produced Transformers' source rewrites should use the pluggable parser lookup instead of the platform's built-in parser + * @throws NullPointerException if {@code delegate} is {@code null} */ SecureTemplates(final Templates delegate, final URIResolver uriResolver, final Supplier emptySource, final boolean overrideDefaultParser) { this.delegate = Objects.requireNonNull(delegate, "delegate"); @@ -76,7 +76,7 @@ final class SecureTemplates implements Templates { /** * Gets the wrapped implementation Templates, for factory methods whose implementations cast {@code newTransformer()} to their own type. * - * @return the wrapped {@link Templates} implementation, never {@code null}. + * @return the wrapped {@link Templates} implementation, never {@code null} */ Templates getDelegate() { return delegate; diff --git a/src/main/java/org/apache/commons/xml/secure/SecureTemplatesHandler.java b/src/main/java/org/apache/commons/xml/secure/SecureTemplatesHandler.java index bdb04ba1..19a1c100 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureTemplatesHandler.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureTemplatesHandler.java @@ -59,11 +59,11 @@ final class SecureTemplatesHandler implements TemplatesHandler { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @param uriResolver the compile-time URIResolver snapshot to restore onto Transformers produced from the compiled Templates; may be {@code null}. - * @param emptySource the empty-{@link Source} supplier for the produced Templates; may be {@code null} for the default empty DOM document. - * @param overrideDefaultParser whether the produced Templates' source rewrites should use the pluggable parser lookup instead of the platform's built-in parser. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @param uriResolver the compile-time URIResolver snapshot to restore onto Transformers produced from the compiled Templates; may be {@code null} + * @param emptySource the empty-{@link Source} supplier for the produced Templates; may be {@code null} for the default empty DOM document + * @param overrideDefaultParser whether the produced Templates' source rewrites should use the pluggable parser lookup instead of the platform's built-in parser + * @throws NullPointerException if {@code delegate} is {@code null} */ SecureTemplatesHandler(final TemplatesHandler delegate, final URIResolver uriResolver, final Supplier emptySource, final boolean overrideDefaultParser) { diff --git a/src/main/java/org/apache/commons/xml/secure/SecureTransformer.java b/src/main/java/org/apache/commons/xml/secure/SecureTransformer.java index dfa94732..f9ba1163 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureTransformer.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureTransformer.java @@ -59,11 +59,11 @@ final class SecureTransformer extends Transformer { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @param uriResolver the compile-time URIResolver snapshot to seed the floor with; may be {@code null}. - * @param emptySource the empty-{@link Source} supplier for the produced Transformers; {@code null} for the default empty DOM document. - * @param overrideDefaultParser whether the source rewrites should use the pluggable parser lookup instead of the platform's built-in parser. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @param uriResolver the compile-time URIResolver snapshot to seed the floor with; may be {@code null} + * @param emptySource the empty-{@link Source} supplier for the produced Transformers; {@code null} for the default empty DOM document + * @param overrideDefaultParser whether the source rewrites should use the pluggable parser lookup instead of the platform's built-in parser + * @throws NullPointerException if {@code delegate} is {@code null} */ SecureTransformer(final Transformer delegate, final URIResolver uriResolver, final Supplier emptySource, final boolean overrideDefaultParser) { this.delegate = Objects.requireNonNull(delegate, "delegate"); @@ -138,9 +138,9 @@ public void setURIResolver(final URIResolver resolver) { /** * {@inheritDoc} * - * @throws IllegalStateException Thrown if the underlying implementation cannot provide a secure reader. - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service configuration error} or - * if the implementation is not available or cannot be instantiated. + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service configuration error} or + * if the implementation is not available or cannot be instantiated + * @throws IllegalStateException thrown if the underlying implementation cannot provide a secure reader */ @Override public void transform(final Source xmlSource, final Result outputTarget) throws TransformerException { 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 eac32f6d..54cb3dbe 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureTransformerFactory.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureTransformerFactory.java @@ -123,8 +123,8 @@ private static final class Wrapper extends SAXTransformerFactory { /** * Whether the delegate is Apache Xalan (either its interpretive or its XSLTC factory), whose {@code getAssociatedStylesheet} ignores a SAXSource reader. * - * @param factory The delegate factory. - * @return Whether the delegate is an {@code org.apache.xalan.} implementation. + * @param factory the delegate factory + * @return whether the delegate is an {@code org.apache.xalan.} implementation */ private static boolean isXalan(final SAXTransformerFactory factory) { return factory.getClass().getName().startsWith("org.apache.xalan."); @@ -135,8 +135,8 @@ private static boolean isXalan(final SAXTransformerFactory factory) { * {@code TransformerFactory.getFeature} cannot signal an unrecognized name (it returns {@code false}), while every implementation rejects a * {@code setFeature} for a name it does not support (Xalan with {@link TransformerConfigurationException}, Saxon with its own unchecked exception). * - * @param factory The delegate factory. - * @return Whether the delegate recognizes the feature. + * @param factory the delegate factory + * @return whether the delegate recognizes the feature */ private static boolean probeOverrideDefaultParser(final SAXTransformerFactory factory) { try { @@ -161,14 +161,16 @@ private static Templates unwrap(final Templates templates) { private final FallbackIgnoreURIResolver floor; - /** Whether the delegate recognizes {@value SecureSAXParserFactory#OVERRIDE_DEFAULT_PARSER}; its value is read per created product, like the JDK. */ + /** + * Whether the delegate recognizes {@value SecureSAXParserFactory#OVERRIDE_DEFAULT_PARSER}; its value is read per created product, like the JDK. + */ private final boolean supportsOverrideDefaultParser; /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @throws NullPointerException if {@code delegate} is {@code null} */ private Wrapper(final SAXTransformerFactory delegate) { this(delegate, null); @@ -177,10 +179,10 @@ private Wrapper(final SAXTransformerFactory delegate) { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} * @param emptySource the empty-{@link Source} supplier for the resolver floor, threaded onto every produced Templates/Transformer; {@code null} means the - * default empty DOM. - * @throws NullPointerException if {@code delegate} is {@code null}. + * default empty DOM + * @throws NullPointerException if {@code delegate} is {@code null} */ private Wrapper(final SAXTransformerFactory delegate, final Supplier emptySource) { this.delegate = Objects.requireNonNull(delegate, "delegate"); @@ -199,10 +201,10 @@ private Wrapper(final SAXTransformerFactory delegate, final Supplier emp * {@link SAXSource} naming the absolutized URI; compiling it, the one documented use of this method, would then fetch it. Saxon already floors the href * itself and returns an empty source, so flooring here is also what makes the engines agree.

* - * @param associated The delegate's result; {@code null} when no PI matched. - * @param base The system id of the scanned document, the base the href was resolved against. - * @return The caller resolver's source for an opted-in href, an empty source otherwise, or {@code null} when no PI matched. - * @throws TransformerConfigurationException if the floor rejects the href, which it does when {@value SecureException#THROW_ON_UNRESOLVED} is set. + * @param associated the delegate's result; {@code null} when no PI matched + * @param base the system id of the scanned document, the base the href was resolved against + * @return the caller resolver's source for an opted-in href, an empty source otherwise, or {@code null} when no PI matched + * @throws TransformerConfigurationException if the floor rejects the href, which it does when {@value SecureException#THROW_ON_UNRESOLVED} is set */ private Source floorAssociated(final Source associated, final String base) throws TransformerConfigurationException { if (associated == null || associated.getSystemId() == null) { @@ -219,8 +221,8 @@ private Source floorAssociated(final Source associated, final String base) throw /** * {@inheritDoc} * - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated */ @Override public Source getAssociatedStylesheet(final Source source, final String media, final String title, final String charset) @@ -254,8 +256,8 @@ public URIResolver getURIResolver() { /** * {@inheritDoc} * - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated */ @Override public Templates newTemplates(final Source source) throws TransformerConfigurationException { @@ -282,8 +284,8 @@ public Transformer newTransformer() throws TransformerConfigurationException { /** * {@inheritDoc} * - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated */ @Override public Transformer newTransformer(final Source source) throws TransformerConfigurationException { @@ -300,8 +302,8 @@ public TransformerHandler newTransformerHandler() throws TransformerConfiguratio /** * {@inheritDoc} * - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated */ @Override public TransformerHandler newTransformerHandler(final Source source) throws TransformerConfigurationException { @@ -317,8 +319,8 @@ public TransformerHandler newTransformerHandler(final Templates templates) throw /** * {@inheritDoc} * - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated */ @Override public XMLFilter newXMLFilter(final Source source) throws TransformerConfigurationException { @@ -338,7 +340,7 @@ public XMLFilter newXMLFilter(final Templates templates) throws TransformerConfi *

The JDK implementation of {@link TransformerFactory} uses the JDK parsers while {@value SecureSAXParserFactory#OVERRIDE_DEFAULT_PARSER} is unset * or {@code false}.

* - * @return {@code true} if parsers should be created via {@code newInstance()}. + * @return {@code true} if parsers should be created via {@code newInstance()} */ private boolean overrideDefaultParser() { return !supportsOverrideDefaultParser || delegate.getFeature(SecureSAXParserFactory.OVERRIDE_DEFAULT_PARSER); @@ -356,12 +358,12 @@ private TransformerHandler secure(final TransformerHandler handler) { *

A {@link SAXSource} carrying the caller's own reader is pre-parsed here too, unlike everywhere else in this class: an engine that reaches this * method drops that reader anyway, so honoring it is not among the options — the choice is only between this parse and the engine's unsecured one.

* - * @param source The source to scan for an associated stylesheet. - * @return A {@link DOMSource} for a stream or SAX source, otherwise the result of {@link SecureSAXParserFactory#secure(Source, boolean)}. - * @throws TransformerConfigurationException if the source cannot be parsed. - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. - * @throws SecureException Thrown if a (non-Android) factory cannot support the secure processing feature {@link XMLConstants#FEATURE_SECURE_PROCESSING}. + * @param source the source to scan for an associated stylesheet + * @return a {@link DOMSource} for a stream or SAX source, otherwise the result of {@link SecureSAXParserFactory#secure(Source, boolean)} + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated + * @throws SecureException thrown if a (non-Android) factory cannot support the secure processing feature {@link XMLConstants#FEATURE_SECURE_PROCESSING} + * @throws TransformerConfigurationException if the source cannot be parsed */ private Source secureSourceToDom(final Source source) throws TransformerConfigurationException { if (source instanceof StreamSource || source instanceof SAXSource) { @@ -401,7 +403,9 @@ public void setURIResolver(final URIResolver resolver) { } } - /** Class name of the JDK's built-in default implementation, the Java 8 fallback for {@link #newDefaultInstance()}. */ + /** + * Class name of the JDK's built-in default implementation, the Java 8 fallback for {@link #newDefaultInstance()}. + */ private static final String JDK_TRANSFORMER_FACTORY = "com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl"; private static final MethodHandle MH_newDefaultInstance = MethodHandleFactory.findStatic(TransformerFactory.class, "newDefaultInstance"); @@ -423,10 +427,10 @@ public void setURIResolver(final URIResolver resolver) { * implementation directly on Java 8. *

* - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws TransformerFactoryConfigurationError Thrown if the running platform provides neither {@code newDefaultInstance()} nor the JDK's built-in - * implementation (for example Android). + * @return a secure factory + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation + * @throws TransformerFactoryConfigurationError thrown if the running platform provides neither {@code newDefaultInstance()} nor the JDK's built-in + * implementation (for example Android) */ public static TransformerFactory newDefaultInstance() { if (MH_newDefaultInstance != null) { @@ -440,8 +444,8 @@ public static TransformerFactory newDefaultInstance() { /** * Returns a new, secure {@link TransformerFactory}. * - * @return A secure factory. - * @throws IllegalStateException if a required secure setting cannot be applied to the underlying implementation. + * @return a secure factory + * @throws IllegalStateException if a required secure setting cannot be applied to the underlying implementation */ public static TransformerFactory newInstance() { return secure(TransformerFactory.newInstance()); @@ -450,11 +454,11 @@ public static TransformerFactory newInstance() { /** * Returns a new, secure {@link TransformerFactory} of the given implementation class. * - * @param factoryClassName The fully qualified class name of the {@link TransformerFactory} implementation. - * @param classLoader The class loader used to load the factory class; {@code null} means the current thread's context class loader. - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws TransformerFactoryConfigurationError Thrown if {@code factoryClassName} is {@code null} or the factory class cannot be loaded or instantiated. + * @param factoryClassName the fully qualified class name of the {@link TransformerFactory} implementation + * @param classLoader the class loader used to load the factory class; {@code null} means the current thread's context class loader + * @return a secure factory + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation + * @throws TransformerFactoryConfigurationError thrown if {@code factoryClassName} is {@code null} or the factory class cannot be loaded or instantiated */ public static TransformerFactory newInstance(final String factoryClassName, final ClassLoader classLoader) { return secure(TransformerFactory.newInstance(factoryClassName, classLoader)); @@ -482,8 +486,8 @@ public static TransformerFactory newInstance(final String factoryClassName, fina * {@link org.apache.commons.xml.secure}-secured reader instead. * * - * @param factory the factory to secure; never {@code null}. - * @return a secure factory. + * @param factory the factory to secure; never {@code null} + * @return a secure factory */ static TransformerFactory secure(final TransformerFactory factory) { // Required: enables secure processing (XSLTC runtime limits; Xalan's extension-function block). 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 c71bd980..e8aa3f18 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureTransformerHandler.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureTransformerHandler.java @@ -51,11 +51,11 @@ final class SecureTransformerHandler implements TransformerHandler { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @param uriResolver the compile-time URIResolver snapshot to restore onto the live transformer; may be {@code null}. - * @param emptySource the empty-{@link Source} supplier for the produced Transformer's floor; {@code null} means the default empty DOM. - * @param overrideDefaultParser whether the live transformer's source rewrites should use the pluggable parser lookup instead of the platform's built-in parser. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @param uriResolver the compile-time URIResolver snapshot to restore onto the live transformer; may be {@code null} + * @param emptySource the empty-{@link Source} supplier for the produced Transformer's floor; {@code null} means the default empty DOM + * @param overrideDefaultParser whether the live transformer's source rewrites should use the pluggable parser lookup instead of the platform's built-in parser + * @throws NullPointerException if {@code delegate} is {@code null} */ SecureTransformerHandler(final TransformerHandler delegate, final URIResolver uriResolver, final Supplier emptySource, final boolean overrideDefaultParser) { diff --git a/src/main/java/org/apache/commons/xml/secure/SecureValidator.java b/src/main/java/org/apache/commons/xml/secure/SecureValidator.java index 784b0f18..672fa607 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureValidator.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureValidator.java @@ -51,9 +51,9 @@ final class SecureValidator extends Validator { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @param overrideDefaultParser whether the source rewrites should use the pluggable parser lookup instead of the platform's built-in parser. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @param overrideDefaultParser whether the source rewrites should use the pluggable parser lookup instead of the platform's built-in parser + * @throws NullPointerException if {@code delegate} is {@code null} */ SecureValidator(final Validator delegate, final boolean overrideDefaultParser) { this.delegate = Objects.requireNonNull(delegate, "delegate"); @@ -114,8 +114,8 @@ public void setResourceResolver(final LSResourceResolver resourceResolver) { /** * {@inheritDoc} * - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated */ @Override public void validate(final Source source, final Result result) throws SAXException, IOException { diff --git a/src/main/java/org/apache/commons/xml/secure/SecureValidatorHandler.java b/src/main/java/org/apache/commons/xml/secure/SecureValidatorHandler.java index e07f0685..51efad3c 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureValidatorHandler.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureValidatorHandler.java @@ -46,8 +46,8 @@ final class SecureValidatorHandler extends ValidatorHandler { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @throws NullPointerException if {@code delegate} is {@code null} */ SecureValidatorHandler(final ValidatorHandler delegate) { this.delegate = Objects.requireNonNull(delegate, "delegate"); 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 87418723..89a81424 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureXMLFilter.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureXMLFilter.java @@ -52,8 +52,8 @@ final class SecureXMLFilter extends XMLFilterImpl implements ErrorListener { /** * Bridges a TrAX report to the SAX callback shape. * - * @param e the reported exception. - * @return The original {@link SAXParseException} where one is the cause, otherwise a synthetic one carrying the locator. + * @param e the reported exception + * @return the original {@link SAXParseException} where one is the cause, otherwise a synthetic one carrying the locator */ private static SAXParseException toSAXParseException(final TransformerException e) { final Throwable cause = e.getCause(); @@ -73,8 +73,8 @@ private static SAXParseException toSAXParseException(final TransformerException /** * Constructs a new instance. * - * @param templates the templates to wrap; must not be {@code null}. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param templates the templates to wrap; must not be {@code null} + * @throws NullPointerException if {@code delegate} is {@code null} */ SecureXMLFilter(final SecureTemplates templates) { this.templates = Objects.requireNonNull(templates, "templates"); @@ -110,8 +110,8 @@ public void fatalError(final TransformerException e) throws TransformerException /** * {@inheritDoc} * - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated */ @Override public void parse(final InputSource input) throws SAXException, IOException { @@ -151,7 +151,9 @@ public void parse(final InputSource input) throws SAXException, IOException { } } - /** Forwards a transformation warning to the caller-set {@link org.xml.sax.ErrorHandler}; the transformation continues unless that handler throws. */ + /** + * Forwards a transformation warning to the caller-set {@link org.xml.sax.ErrorHandler}; the transformation continues unless that handler throws. + */ @Override public void warning(final TransformerException e) throws TransformerException { try { 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 e4fc358a..0c938c67 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureXMLInputFactory.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureXMLInputFactory.java @@ -93,8 +93,8 @@ private static XMLResolver unwrap(final XMLResolver resolver) { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @throws NullPointerException if {@code delegate} is {@code null} */ private Wrapper(final XMLInputFactory delegate) { this.delegate = Objects.requireNonNull(delegate, "delegate"); @@ -223,8 +223,8 @@ public void setProperty(final String name, final Object value) { /** * Routes a caller-set resolver for the property {@code name} behind the floor currently installed on that hook. * - * @param name The resolver-valued property being set. - * @param resolver The caller's resolver, or their own {@link FallbackIgnoreXMLResolver} to take control. + * @param name the resolver-valued property being set + * @param resolver the caller's resolver, or their own {@link FallbackIgnoreXMLResolver} to take control */ private void setResolverProperty(final String name, final XMLResolver resolver) { if (resolver instanceof FallbackIgnoreXMLResolver) { @@ -254,7 +254,9 @@ public void setXMLResolver(final XMLResolver resolver) { /** Woodstox property: resolver consulted for undeclared entity references. */ static final String WSTX_UNDECLARED_ENTITY_RESOLVER = "com.ctc.wstx.undeclaredEntityResolver"; - /** Class name of the JDK's built-in default implementation, the Java 8 fallback for {@link #newDefaultFactory()}. */ + /** + * Class name of the JDK's built-in default implementation, the Java 8 fallback for {@link #newDefaultFactory()}. + */ private static final String JDK_XML_INPUT_FACTORY = "com.sun.xml.internal.stream.XMLInputFactoryImpl"; private static final MethodHandle MH_newDefaultInstance = MethodHandleFactory.findStatic(XMLInputFactory.class, "newDefaultFactory"); @@ -266,10 +268,10 @@ public void setXMLResolver(final XMLResolver resolver) { * implementation directly on Java 8. *

* - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws FactoryConfigurationError Thrown if the running platform provides neither {@code newDefaultFactory()} nor the JDK's built-in implementation - * (for example Android). + * @return a secure factory + * @throws FactoryConfigurationError thrown if the running platform provides neither {@code newDefaultFactory()} nor the JDK's built-in implementation + * (for example Android) + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ public static XMLInputFactory newDefaultFactory() { if (MH_newDefaultInstance != null) { @@ -287,9 +289,9 @@ public static XMLInputFactory newDefaultFactory() { /** * 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. - * @throws FactoryConfigurationError Thrown if an instance of this factory cannot be loaded. + * @return a secure factory + * @throws FactoryConfigurationError thrown if an instance of this factory cannot be loaded + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ public static XMLInputFactory newFactory() { // XMLInputFactory.newInstance, not newFactory: the same specified lookup, but Android's StAX API predates newFactory. @@ -299,12 +301,12 @@ public static XMLInputFactory newFactory() { /** * Returns a new, secure {@link XMLInputFactory} resolved from the given factory id. * - * @param factoryId The name of the factory to find; a system property or service id to look up, not the class name of the implementation. - * @param classLoader The class loader used in the lookup; {@code null} means the current thread's context class loader. - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws FactoryConfigurationError Thrown in case of a service configuration error or if the implementation is not available or cannot be instantiated. - * @throws NullPointerException Thrown if {@code factoryId} is {@code null}. + * @param factoryId the name of the factory to find; a system property or service id to look up, not the class name of the implementation + * @param classLoader the class loader used in the lookup; {@code null} means the current thread's context class loader + * @return a secure factory + * @throws FactoryConfigurationError thrown in case of a service configuration error or if the implementation is not available or cannot be instantiated + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation + * @throws NullPointerException thrown if {@code factoryId} is {@code null} */ public static XMLInputFactory newFactory(final String factoryId, final ClassLoader classLoader) { return secure(XMLInputFactory.newFactory(factoryId, classLoader)); @@ -313,9 +315,9 @@ public static XMLInputFactory newFactory(final String factoryId, final ClassLoad /** * Returns a new, secure {@link XMLInputFactory}. * - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws FactoryConfigurationError Thrown if an instance of this factory cannot be loaded. + * @return a secure factory + * @throws FactoryConfigurationError thrown if an instance of this factory cannot be loaded + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation */ public static XMLInputFactory newInstance() { return secure(XMLInputFactory.newInstance()); @@ -328,8 +330,8 @@ public static XMLInputFactory newInstance() { * every entity-resolution hook, leaving the standard {@code SUPPORT_DTD} / {@code IS_SUPPORTING_EXTERNAL_ENTITIES} defaults untouched; see the wrapper's * Javadoc for the per-implementation hook routing.

* - * @param factory the factory to secure; never {@code null}. - * @return a secure factory. + * @param factory the factory to secure; never {@code null} + * @return a secure factory */ static XMLInputFactory secure(final XMLInputFactory factory) { // The wrapper installs the non-removable ignore-all resolver floor that resolves every external DTD and entity to empty content. diff --git a/src/main/java/org/apache/commons/xml/secure/SecureXMLReader.java b/src/main/java/org/apache/commons/xml/secure/SecureXMLReader.java index 6531bd07..44992865 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureXMLReader.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureXMLReader.java @@ -49,8 +49,8 @@ class SecureXMLReader implements XMLReader { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @throws NullPointerException if {@code delegate} is {@code null} */ SecureXMLReader(final XMLReader delegate) { this.delegate = Objects.requireNonNull(delegate, "delegate"); @@ -66,7 +66,7 @@ public ContentHandler getContentHandler() { /** * Gets the wrapped reader, so tests can observe which parser implementation a rewrite picked. * - * @return The wrapped reader. + * @return the wrapped reader */ XMLReader getDelegate() { return delegate; diff --git a/src/main/java/org/apache/commons/xml/secure/SecureXPath.java b/src/main/java/org/apache/commons/xml/secure/SecureXPath.java index 19f834d0..250e794f 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureXPath.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureXPath.java @@ -54,14 +54,14 @@ final class SecureXPath implements XPath { * Parses the source through a secure, namespace-aware {@link javax.xml.parsers.DocumentBuilder}, mirroring the namespace awareness of the parser the * engine would have provisioned. * - * @param source The document to evaluate against. - * @param overrideDefaultParser Whether the document build should use the pluggable parser lookup instead of the platform's built-in parser. - * @return The parsed document. - * @throws NullPointerException if {@code source} is {@code null}, per the {@link XPath} contract. - * @throws XPathExpressionException if the source cannot be parsed. - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. - * @throws SecureException Thrown if a (non-Android) factory cannot support the secure processing feature {@link XMLConstants#FEATURE_SECURE_PROCESSING}. + * @param source the document to evaluate against + * @param overrideDefaultParser whether the document build should use the pluggable parser lookup instead of the platform's built-in parser + * @return the parsed document + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated + * @throws NullPointerException if {@code source} is {@code null}, per the {@link XPath} contract + * @throws SecureException thrown if a (non-Android) factory cannot support the secure processing feature {@link XMLConstants#FEATURE_SECURE_PROCESSING} + * @throws XPathExpressionException if the source cannot be parsed */ static Document parse(final InputSource source, final boolean overrideDefaultParser) throws XPathExpressionException { Objects.requireNonNull(source, "source"); @@ -82,9 +82,9 @@ static Document parse(final InputSource source, final boolean overrideDefaultPar /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @param overrideDefaultParser whether the {@link InputSource} document builds should use the pluggable parser lookup instead of the platform's built-in parser. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @param overrideDefaultParser whether the {@link InputSource} document builds should use the pluggable parser lookup instead of the platform's built-in parser + * @throws NullPointerException if {@code delegate} is {@code null} */ SecureXPath(final XPath delegate, final boolean overrideDefaultParser) { this.delegate = Objects.requireNonNull(delegate, "delegate"); @@ -100,8 +100,8 @@ public XPathExpression compile(final String expression) throws XPathExpressionEx /** * {@inheritDoc} * - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated */ @Override public String evaluate(final String expression, final InputSource source) throws XPathExpressionException { @@ -111,8 +111,8 @@ public String evaluate(final String expression, final InputSource source) throws /** * {@inheritDoc} * - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated */ @Override public Object evaluate(final String expression, final InputSource source, final QName returnType) throws XPathExpressionException { diff --git a/src/main/java/org/apache/commons/xml/secure/SecureXPathExpression.java b/src/main/java/org/apache/commons/xml/secure/SecureXPathExpression.java index 002d603c..0327832b 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureXPathExpression.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureXPathExpression.java @@ -46,9 +46,9 @@ final class SecureXPathExpression implements XPathExpression { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @param overrideDefaultParser whether the {@link InputSource} document builds should use the pluggable parser lookup instead of the platform's built-in parser. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @param overrideDefaultParser whether the {@link InputSource} document builds should use the pluggable parser lookup instead of the platform's built-in parser + * @throws NullPointerException if {@code delegate} is {@code null} */ SecureXPathExpression(final XPathExpression delegate, final boolean overrideDefaultParser) { this.delegate = Objects.requireNonNull(delegate, "delegate"); @@ -58,8 +58,8 @@ final class SecureXPathExpression implements XPathExpression { /** * {@inheritDoc} * - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated */ @Override public String evaluate(final InputSource source) throws XPathExpressionException { @@ -69,8 +69,8 @@ public String evaluate(final InputSource source) throws XPathExpressionException /** * {@inheritDoc} * - * @throws FactoryConfigurationError Thrown from a factory in case of a {@link java.util.ServiceConfigurationError service - * configuration error} or if the implementation is not available or cannot be instantiated. + * @throws FactoryConfigurationError thrown from a factory in case of a {@link java.util.ServiceConfigurationError service + * configuration error} or if the implementation is not available or cannot be instantiated */ @Override public Object evaluate(final InputSource source, final QName returnType) throws XPathExpressionException { 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 d7ca9a65..d047b6f8 100644 --- a/src/main/java/org/apache/commons/xml/secure/SecureXPathFactory.java +++ b/src/main/java/org/apache/commons/xml/secure/SecureXPathFactory.java @@ -62,8 +62,8 @@ private static final class Wrapper extends XPathFactory { /** * Constructs a new instance. * - * @param delegate the delegate to wrap; must not be {@code null}. - * @throws NullPointerException if {@code delegate} is {@code null}. + * @param delegate the delegate to wrap; must not be {@code null} + * @throws NullPointerException if {@code delegate} is {@code null} */ private Wrapper(final XPathFactory delegate) { this.delegate = Objects.requireNonNull(delegate, "delegate"); @@ -82,8 +82,8 @@ public boolean getFeature(final String name) throws XPathFactoryConfigurationExc * delegate's own limits ({@code jdk.xml.xpath*}) behind an {@code UnsupportedOperationException}. *

* - * @param name the property name. - * @return the delegate's value for the property. + * @param name the property name + * @return the delegate's value for the property */ public String getProperty(final String name) { if (MH_getProperty == null) { @@ -111,7 +111,7 @@ public XPath newXPath() { * {@code false}. *

* - * @return {@code true} if parsers should be created via {@code newInstance()}. + * @return {@code true} if parsers should be created via {@code newInstance()} */ private boolean overrideDefaultParser() { try { @@ -131,8 +131,8 @@ public void setFeature(final String name, final boolean value) throws XPathFacto * {@code @Override}. The {@code jdk.xml.xpath*} limits reached this way are processing limits like any other: an operator may tighten them, and * loosening one is reconfiguration. * - * @param name the property name. - * @param value the value to set. + * @param name the property name + * @param value the value to set */ public void setProperty(final String name, final String value) { if (MH_setProperty == null) { @@ -155,15 +155,21 @@ public void setXPathVariableResolver(final XPathVariableResolver resolver) { } } - /** Class name of the JDK's built-in default implementation, the Java 8 fallback for {@link #newDefaultInstance()}. */ + /** + * Class name of the JDK's built-in default implementation, the Java 8 fallback for {@link #newDefaultInstance()}. + */ private static final String JDK_XPATH_FACTORY = "com.sun.org.apache.xpath.internal.jaxp.XPathFactoryImpl"; 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. */ + /** + * {@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. */ + /** + * {@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); @@ -174,10 +180,10 @@ public void setXPathVariableResolver(final XPathVariableResolver resolver) { * implementation directly on Java 8. *

* - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws RuntimeException Thrown if the running platform provides neither {@code newDefaultInstance()} nor the JDK's built-in implementation (for - * example Android). + * @return a secure factory + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation + * @throws RuntimeException thrown if the running platform provides neither {@code newDefaultInstance()} nor the JDK's built-in implementation (for + * example Android) */ public static XPathFactory newDefaultInstance() { if (MH_newDefaultInstance != null) { @@ -195,9 +201,9 @@ public static XPathFactory newDefaultInstance() { /** * Returns a new, secure {@link XPathFactory} for the default XPath object model. * - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws RuntimeException Thrown if there is a failure in creating an {@link XPathFactory} for the default object model. + * @return a secure factory + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation + * @throws RuntimeException thrown if there is a failure in creating an {@link XPathFactory} for the default object model */ public static XPathFactory newInstance() { return secure(XPathFactory.newInstance()); @@ -206,12 +212,12 @@ public static XPathFactory newInstance() { /** * Returns a new, secure {@link XPathFactory} for the given object model. * - * @param uri The underlying object model identifier, as accepted by {@link XPathFactory#newInstance(String)}. - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws XPathFactoryConfigurationException Thrown if no implementation of the object model is available. - * @throws NullPointerException Thrown if {@code uri} is {@code null}. - * @throws IllegalArgumentException Thrown if {@code uri} is empty. + * @param uri the underlying object model identifier, as accepted by {@link XPathFactory#newInstance(String)} + * @return a secure factory + * @throws IllegalArgumentException thrown if {@code uri} is empty + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation + * @throws NullPointerException thrown if {@code uri} is {@code null} + * @throws XPathFactoryConfigurationException thrown if no implementation of the object model is available */ public static XPathFactory newInstance(final String uri) throws XPathFactoryConfigurationException { return secure(XPathFactory.newInstance(uri)); @@ -220,15 +226,15 @@ public static XPathFactory newInstance(final String uri) throws XPathFactoryConf /** * Returns a new, secure {@link XPathFactory} of the given implementation class. * - * @param uri The underlying object model identifier, as accepted by {@link XPathFactory#newInstance(String)}. - * @param factoryClassName The fully qualified class name of the {@link XPathFactory} implementation. - * @param classLoader The class loader used to load the factory class; {@code null} means the current thread's context class loader. - * @return A secure factory. - * @throws IllegalStateException Thrown if a required secure setting cannot be applied to the underlying implementation. - * @throws XPathFactoryConfigurationException Thrown if {@code factoryClassName} is {@code null}, or if the factory class cannot be loaded or - * instantiated, or does not support {@code uri}. - * @throws NullPointerException Thrown if {@code uri} is {@code null}. - * @throws IllegalArgumentException Thrown if {@code uri} is empty. + * @param uri the underlying object model identifier, as accepted by {@link XPathFactory#newInstance(String)} + * @param factoryClassName the fully qualified class name of the {@link XPathFactory} implementation + * @param classLoader the class loader used to load the factory class; {@code null} means the current thread's context class loader + * @return a secure factory + * @throws IllegalArgumentException thrown if {@code uri} is empty + * @throws IllegalStateException thrown if a required secure setting cannot be applied to the underlying implementation + * @throws NullPointerException thrown if {@code uri} is {@code null} + * @throws XPathFactoryConfigurationException thrown if {@code factoryClassName} is {@code null}, or if the factory class cannot be loaded or + * instantiated, or does not support {@code uri} */ public static XPathFactory newInstance(final String uri, final String factoryClassName, final ClassLoader classLoader) throws XPathFactoryConfigurationException { @@ -254,9 +260,9 @@ public static XPathFactory newInstance(final String uri, final String factoryCla * the engine never parses. * * - * @param factory The factory to secure. - * @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. + * @param factory the factory to secure + * @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) { if (SaxonProvider.isSaxon(factory.getClass())) { @@ -272,11 +278,11 @@ static XPathFactory secure(final XPathFactory factory) { /** * Sets a feature on the given factory, throwing a {@link SecureException} if the implementation does not recognize it. * - * @param factory The factory to secure. - * @param feature The feature to set. - * @param value The value to set. - * @throws SecureException Thrown if this {@link XPathFactory} or the {@code XPath}s it creates cannot support this feature or if {@code feature} is - * {@code null}. + * @param factory the factory to secure + * @param feature the feature to set + * @param value the value to set + * @throws SecureException thrown if this {@link XPathFactory} or the {@code XPath}s it creates cannot support this feature or if {@code feature} is + * {@code null} */ private static void setFeature(final XPathFactory factory, final String feature, final boolean value) { try {