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
The following commit(s) were added to refs/heads/main by this push:
new 8b58e9e Javadoc: Propagate FactoryConfigurationError from
DocumentBuilderFactory.newInstance()
8b58e9e is described below
commit 8b58e9ec6166d57d1bb875c95182e145b3ffbfc1
Author: Gary Gregory <[email protected]>
AuthorDate: Wed Aug 26 12:25:07 2026 -0400
Javadoc: Propagate FactoryConfigurationError from
DocumentBuilderFactory.newInstance()
---
.../commons/xml/FallbackIgnoreURIResolver.java | 11 +++++++++++
.../commons/xml/HardeningTransformerFactory.java | 9 +++++++++
.../org/apache/commons/xml/HardeningXPath.java | 15 ++++++++++++++
.../commons/xml/HardeningXPathExpression.java | 23 ++++++++++++++++++----
.../java/org/apache/commons/xml/XmlFactories.java | 3 +++
5 files changed, 57 insertions(+), 4 deletions(-)
diff --git
a/src/main/java/org/apache/commons/xml/FallbackIgnoreURIResolver.java
b/src/main/java/org/apache/commons/xml/FallbackIgnoreURIResolver.java
index 72b36d0..cd28c64 100644
--- a/src/main/java/org/apache/commons/xml/FallbackIgnoreURIResolver.java
+++ b/src/main/java/org/apache/commons/xml/FallbackIgnoreURIResolver.java
@@ -20,6 +20,7 @@
import java.util.function.Supplier;
import javax.xml.parsers.DocumentBuilderFactory;
+import javax.xml.parsers.FactoryConfigurationError;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.transform.Source;
import javax.xml.transform.TransformerException;
@@ -52,9 +53,19 @@ final class FallbackIgnoreURIResolver implements URIResolver
{
* Backing for the default ignore outcome. Consumers parse the resolved
{@link Source}, and an empty character stream is not a well-formed XML document
* (XSLTC rejects it for {@code document()} and for an ignored {@code
xsl:include}/{@code xsl:import}), so the default supplier answers with a
well-formed
* empty document that evaluates to no content. It is never mutated, so
one instance serves every resolution.
+ *
+ * @see #newEmptyDocument()
*/
private static final Document EMPTY_DOCUMENT = newEmptyDocument();
+ /**
+ * Creates a new empty document.
+ *
+ * @return a new empty document.
+ * @throws HardeningException Thrown if a {@link DocumentBuilder}
cannot be created which satisfies the configuration requested.
+ * @throws FactoryConfigurationError Thrown from {@link
DocumentBuilderFactory} in case of a {@link java.util.ServiceConfigurationError
service
+ * configuration error} or if the
implementation is not available or cannot be instantiated.
+ */
private static Document newEmptyDocument() {
try {
return
DocumentBuilderFactory.newInstance().newDocumentBuilder().newDocument();
diff --git
a/src/main/java/org/apache/commons/xml/HardeningTransformerFactory.java
b/src/main/java/org/apache/commons/xml/HardeningTransformerFactory.java
index 5dd22c3..55a4c10 100644
--- a/src/main/java/org/apache/commons/xml/HardeningTransformerFactory.java
+++ b/src/main/java/org/apache/commons/xml/HardeningTransformerFactory.java
@@ -22,6 +22,7 @@
import java.util.function.Supplier;
import javax.xml.parsers.DocumentBuilderFactory;
+import javax.xml.parsers.FactoryConfigurationError;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.transform.ErrorListener;
import javax.xml.transform.Source;
@@ -81,6 +82,8 @@ final class HardeningTransformerFactory extends
SAXTransformerFactory {
* @param source The source to scan for an associated stylesheet.
* @return A {@link DOMSource} for a reader-less source, otherwise the
result of {@link SAXParserHardener#hardenSource(Source)}.
* @throws TransformerConfigurationException if the source cannot be
parsed.
+ * @throws FactoryConfigurationError Thrown from {@link
DocumentBuilderFactory} in case of a {@link java.util.ServiceConfigurationError
service
+ * configuration error} or if the
implementation is not available or cannot be instantiated.
*/
private static Source hardenSourceToDom(final Source source) throws
TransformerConfigurationException {
if (source instanceof StreamSource || source instanceof SAXSource &&
((SAXSource) source).getXMLReader() == null) {
@@ -148,6 +151,12 @@ private static Templates unwrap(final Templates templates)
{
delegate.setURIResolver(floor);
}
+ /**
+ * {@inheritDoc}
+ *
+ * @throws FactoryConfigurationError Thrown from {@link
DocumentBuilderFactory} 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)
throws TransformerConfigurationException {
diff --git a/src/main/java/org/apache/commons/xml/HardeningXPath.java
b/src/main/java/org/apache/commons/xml/HardeningXPath.java
index 32b2475..c800b03 100644
--- a/src/main/java/org/apache/commons/xml/HardeningXPath.java
+++ b/src/main/java/org/apache/commons/xml/HardeningXPath.java
@@ -23,6 +23,7 @@
import javax.xml.namespace.NamespaceContext;
import javax.xml.namespace.QName;
import javax.xml.parsers.DocumentBuilderFactory;
+import javax.xml.parsers.FactoryConfigurationError;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.xpath.XPath;
import javax.xml.xpath.XPathExpression;
@@ -57,6 +58,8 @@ final class HardeningXPath implements XPath {
* @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 {@link
DocumentBuilderFactory} in case of a {@link java.util.ServiceConfigurationError
service
+ * configuration error} or if the
implementation is not available or cannot be instantiated.
*/
static Document parse(final InputSource source) throws
XPathExpressionException {
Objects.requireNonNull(source, "source");
@@ -87,11 +90,23 @@ public XPathExpression compile(final String expression)
throws XPathExpressionEx
return compiled == null ? null : new
HardeningXPathExpression(compiled);
}
+ /**
+ * {@inheritDoc}
+ *
+ * @throws FactoryConfigurationError Thrown from {@link
DocumentBuilderFactory} 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 {
return delegate.evaluate(expression, parse(source));
}
+ /**
+ * {@inheritDoc}
+ *
+ * @throws FactoryConfigurationError Thrown from {@link
DocumentBuilderFactory} 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 {
return delegate.evaluate(expression, parse(source), returnType);
diff --git a/src/main/java/org/apache/commons/xml/HardeningXPathExpression.java
b/src/main/java/org/apache/commons/xml/HardeningXPathExpression.java
index 15de2bd..58c42cb 100644
--- a/src/main/java/org/apache/commons/xml/HardeningXPathExpression.java
+++ b/src/main/java/org/apache/commons/xml/HardeningXPathExpression.java
@@ -20,6 +20,8 @@
import java.util.Objects;
import javax.xml.namespace.QName;
+import javax.xml.parsers.DocumentBuilderFactory;
+import javax.xml.parsers.FactoryConfigurationError;
import javax.xml.xpath.XPathExpression;
import javax.xml.xpath.XPathExpressionException;
@@ -27,10 +29,11 @@
/**
* {@link XPathExpression} wrapper that applies the same {@link InputSource}
rewrite as {@link HardeningXPath} to the compiled evaluation entry points.
- *
- * <p>{@link HardeningXPath#compile(String)} returns one of these, so {@link
#evaluate(InputSource)} and {@link #evaluate(InputSource, QName)} build the
- * document through a hardened, namespace-aware parser instead of the engine's
own; the {@code evaluateExpression} default methods added by Java 9 route
- * through these overloads as well.</p>
+ * <p>
+ * {@link HardeningXPath#compile(String)} returns one of these, so {@link
#evaluate(InputSource)} and {@link #evaluate(InputSource, QName)} build the
document
+ * through a hardened, namespace-aware parser instead of the engine's own; the
{@code evaluateExpression} default methods added by Java 9 route through these
+ * overloads as well.
+ * </p>
*/
final class HardeningXPathExpression implements XPathExpression {
@@ -46,11 +49,23 @@ final class HardeningXPathExpression implements
XPathExpression {
this.delegate = Objects.requireNonNull(delegate, "delegate");
}
+ /**
+ * {@inheritDoc}
+ *
+ * @throws FactoryConfigurationError Thrown from {@link
DocumentBuilderFactory} 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 {
return delegate.evaluate(HardeningXPath.parse(source));
}
+ /**
+ * {@inheritDoc}
+ *
+ * @throws FactoryConfigurationError Thrown from {@link
DocumentBuilderFactory} 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 {
return delegate.evaluate(HardeningXPath.parse(source), returnType);
diff --git a/src/main/java/org/apache/commons/xml/XmlFactories.java
b/src/main/java/org/apache/commons/xml/XmlFactories.java
index 65b69ac..a85501c 100644
--- a/src/main/java/org/apache/commons/xml/XmlFactories.java
+++ b/src/main/java/org/apache/commons/xml/XmlFactories.java
@@ -19,6 +19,7 @@
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
+import javax.xml.parsers.FactoryConfigurationError;
import javax.xml.parsers.SAXParserFactory;
import javax.xml.stream.XMLInputFactory;
import javax.xml.transform.TransformerFactory;
@@ -91,6 +92,8 @@ public final class XmlFactories {
*
* @return A hardened factory.
* @throws IllegalStateException if a required hardening setting cannot be
applied to the underlying implementation.
+ * @throws FactoryConfigurationError Thrown from {@link
DocumentBuilderFactory} 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());
