This is an automated email from the ASF dual-hosted git repository. garydgregory pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/commons-xml.git
commit 62c1a13a46a02232dbc4c95c43af0aa024688ef8 Author: Gary Gregory <[email protected]> AuthorDate: Wed Aug 26 12:42:53 2026 -0400 Javadoc: Propagate SchemaFactoryConfigurationError from SchemaFactory.newInstance(String) --- .../java/org/apache/commons/xml/XmlFactories.java | 115 +++++++++++---------- 1 file changed, 62 insertions(+), 53 deletions(-) diff --git a/src/main/java/org/apache/commons/xml/XmlFactories.java b/src/main/java/org/apache/commons/xml/XmlFactories.java index 8f3ed31..a60adb6 100644 --- a/src/main/java/org/apache/commons/xml/XmlFactories.java +++ b/src/main/java/org/apache/commons/xml/XmlFactories.java @@ -24,6 +24,7 @@ import javax.xml.stream.XMLInputFactory; import javax.xml.transform.TransformerFactory; import javax.xml.validation.SchemaFactory; +import javax.xml.validation.SchemaFactoryConfigurationError; import javax.xml.xpath.XPathFactory; /** @@ -75,25 +76,27 @@ public final class XmlFactories { /** * System property that switches unresolved external references from the default empty resolution to a thrown exception. - * - * <p>How to enable: set {@code -Dorg.apache.commons.xml.throwOnUnresolved=true}. The property is read at resolution time, so it also applies to factories - * created before it was set; references resolved by a caller-supplied resolver are unaffected.</p> + * <p> + * How to enable: set {@code -Dorg.apache.commons.xml.throwOnUnresolved=true}. The property is read at resolution time, so it also applies to factories + * created before it was set; references resolved by a caller-supplied resolver are unaffected. + * </p> */ static final String THROW_ON_UNRESOLVED = "org.apache.commons.xml.throwOnUnresolved"; /** * Returns a new, hardened {@link DocumentBuilderFactory}. - * - * <p>Beyond the three universal guarantees on {@link XmlFactories}, XInclude resolution is denied by default. - * When {@link DocumentBuilderFactory#setXIncludeAware(boolean) setXIncludeAware(true)} is called on the returned - * factory, the parser will process {@code xi:include} elements but every external resource lookup is rejected. - * To permit specific trusted resources, install an {@link org.xml.sax.EntityResolver EntityResolver} on the - * {@link DocumentBuilder} that allow-lists them; any href the resolver does not explicitly allow stays blocked.</p> + * <p> + * Beyond the three universal guarantees on {@link XmlFactories}, XInclude resolution is denied by default. When + * {@link DocumentBuilderFactory#setXIncludeAware(boolean) setXIncludeAware(true)} is called on the returned factory, the parser will process + * {@code xi:include} elements but every external resource lookup is rejected. To permit specific trusted resources, install an + * {@link org.xml.sax.EntityResolver EntityResolver} on the {@link DocumentBuilder} that allow-lists them; any href the resolver does not explicitly allow + * stays blocked. + * </p> * * @return A hardened factory. - * @throws IllegalStateException if a required hardening 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. + * @throws IllegalStateException if a required hardening 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. */ public static DocumentBuilderFactory newDocumentBuilderFactory() { return DocumentBuilderHardener.harden(DocumentBuilderFactory.newInstance()); @@ -101,18 +104,17 @@ public static DocumentBuilderFactory newDocumentBuilderFactory() { /** * Returns a new, hardened {@link SAXParserFactory}. - * - * <p>Beyond the three universal guarantees on {@link XmlFactories}, XInclude resolution is denied by default. - * When {@link SAXParserFactory#setXIncludeAware(boolean) setXIncludeAware(true)} is called on the returned - * factory, the parser will process {@code xi:include} elements but every external resource lookup is rejected. - * To permit specific trusted resources, install an {@link org.xml.sax.EntityResolver EntityResolver} on the - * {@link org.xml.sax.XMLReader} that allow-lists them; any href the resolver does not explicitly allow stays - * blocked.</p> + * <p> + * Beyond the three universal guarantees on {@link XmlFactories}, XInclude resolution is denied by default. When + * {@link SAXParserFactory#setXIncludeAware(boolean) setXIncludeAware(true)} is called on the returned factory, the parser will process {@code xi:include} + * elements but every external resource lookup is rejected. To permit specific trusted resources, install an {@link org.xml.sax.EntityResolver + * EntityResolver} on the {@link org.xml.sax.XMLReader} that allow-lists them; any href the resolver does not explicitly allow stays blocked. + * </p> * * @return A hardened factory. - * @throws IllegalStateException if a required hardening 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. + * @throws IllegalStateException if a required hardening 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. */ public static SAXParserFactory newSAXParserFactory() { return SAXParserHardener.harden(SAXParserFactory.newInstance()); @@ -120,21 +122,23 @@ public static SAXParserFactory newSAXParserFactory() { /** * Returns a new, hardened {@link SchemaFactory} for the given schema language. - * - * <p>Beyond the three universal guarantees on {@link XmlFactories}:</p> - * + * <p> + * Beyond the three universal guarantees on {@link XmlFactories}: + * </p> * <ul> - * <li>{@code xs:import}, {@code xs:include} and {@code xs:redefine} schemaLocation URIs are not resolved during schema compilation, and</li> - * <li>{@code xsi:schemaLocation} / {@code xsi:noNamespaceSchemaLocation} hints in instance documents are not resolved during validation.</li> + * <li>{@code xs:import}, {@code xs:include} and {@code xs:redefine} schemaLocation URIs are not resolved during schema compilation, and</li> + * <li>{@code xsi:schemaLocation} / {@code xsi:noNamespaceSchemaLocation} hints in instance documents are not resolved during validation.</li> * </ul> - * - * <p>The same guarantees apply to {@link javax.xml.validation.Validator} and {@link javax.xml.validation.ValidatorHandler} instances produced from the - * resulting {@link javax.xml.validation.Schema}.</p> + * <p> + * The same guarantees apply to {@link javax.xml.validation.Validator} and {@link javax.xml.validation.ValidatorHandler} instances produced from the + * resulting {@link javax.xml.validation.Schema}. + * </p> * * @param schemaLanguage The schema language, as accepted by {@link SchemaFactory#newInstance(String)}. * @return A hardened factory. - * @throws IllegalArgumentException if no implementation of the schema language is available. - * @throws NullPointerException if {@code schemaLanguage} is {@code null}. + * @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 newSchemaFactory(final String schemaLanguage) { return new HardeningSchemaFactory(SchemaFactory.newInstance(schemaLanguage)); @@ -142,21 +146,23 @@ public static SchemaFactory newSchemaFactory(final String schemaLanguage) { /** * Returns a new, hardened {@link TransformerFactory}. - * - * <p>Beyond the three universal guarantees on {@link XmlFactories}: {@code xsl:import}, {@code xsl:include} and {@code document()} URIs are not - * resolved.</p> - * - * <p>The guarantees govern what the transform reads, not what it writes: an output instruction like {@code xsl:result-document} still writes wherever the - * stylesheet directs, so an untrusted stylesheet's output destinations must be restricted outside the library.</p> - * - * <p>The guarantees apply to every parser the factory creates internally for the standard {@link TransformerFactory} entry points: stylesheet compilation + * <p> + * Beyond the three universal guarantees on {@link XmlFactories}: {@code xsl:import}, {@code xsl:include} and {@code document()} URIs are not resolved. + * </p> + * <p> + * The guarantees govern what the transform reads, not what it writes: an output instruction like {@code xsl:result-document} still writes wherever the + * stylesheet directs, so an untrusted stylesheet's output destinations must be restricted outside the library. + * </p> + * <p> + * The guarantees apply to every parser the factory creates internally for the standard {@link TransformerFactory} entry points: stylesheet compilation * ({@link TransformerFactory#newTemplates(javax.xml.transform.Source) newTemplates(Source)}, * {@link TransformerFactory#newTransformer(javax.xml.transform.Source) newTransformer(Source)}) and source-document reading at - * {@code Transformer.transform(Source, Result)} time.</p> - * - * <p>The {@link javax.xml.transform.sax.SAXTransformerFactory} extension methods - * ({@code newTransformerHandler(..)}, {@code newTemplatesHandler()}, {@code newXMLFilter(..)}), if reachable by casting the returned factory, produce - * objects carrying the same guarantees.</p> + * {@code Transformer.transform(Source, Result)} time. + * </p> + * <p> + * The {@link javax.xml.transform.sax.SAXTransformerFactory} extension methods ({@code newTransformerHandler(..)}, {@code newTemplatesHandler()}, + * {@code newXMLFilter(..)}), if reachable by casting the returned factory, produce objects carrying the same guarantees. + * </p> * * @return A hardened factory. * @throws IllegalStateException if a required hardening setting cannot be applied to the underlying implementation. @@ -167,8 +173,9 @@ public static TransformerFactory newTransformerFactory() { /** * Returns a new, hardened {@link XMLInputFactory}. - * - * <p>The three universal guarantees on {@link XmlFactories} apply; StAX exposes no additional vectors beyond them.</p> + * <p> + * The three universal guarantees on {@link XmlFactories} apply; StAX exposes no additional vectors beyond them. + * </p> * * @return A hardened factory. * @throws IllegalStateException if a required hardening setting cannot be applied to the underlying implementation. @@ -179,12 +186,14 @@ public static XMLInputFactory newXMLInputFactory() { /** * Returns a new, hardened {@link XPathFactory} for the default XPath object model. - * - * <p>Beyond the three universal guarantees on {@link XmlFactories}, URI-fetching XPath 3.1+ functions ({@code doc()}, {@code collection()}, - * {@code unparsed-text()}) are not resolved.</p> - * - * <p>The guarantees also cover the document parse behind {@code XPath.evaluate(String, InputSource)} and {@code XPathExpression.evaluate(InputSource)}: - * the input document is built through a hardened, namespace-aware {@link javax.xml.parsers.DocumentBuilder} instead of the engine's internal parser.</p> + * <p> + * Beyond the three universal guarantees on {@link XmlFactories}, URI-fetching XPath 3.1+ functions ({@code doc()}, {@code collection()}, + * {@code unparsed-text()}) are not resolved. + * </p> + * <p> + * The guarantees also cover the document parse behind {@code XPath.evaluate(String, InputSource)} and {@code XPathExpression.evaluate(InputSource)}: the + * input document is built through a hardened, namespace-aware {@link javax.xml.parsers.DocumentBuilder} instead of the engine's internal parser. + * </p> * * @return A hardened factory. * @throws IllegalStateException if a required hardening setting cannot be applied to the underlying implementation.
