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 0377950 Javadoc: Propagate FactoryConfigurationError from
XPathFactory.newInstance()
0377950 is described below
commit 03779509933f9616b66aaa97a9c912479f8764cd
Author: Gary Gregory <[email protected]>
AuthorDate: Wed Aug 26 12:39:41 2026 -0400
Javadoc: Propagate FactoryConfigurationError from
XPathFactory.newInstance()
---
.../commons/xml/FallbackIgnoreURIResolver.java | 8 ++++++-
.../apache/commons/xml/HardeningSchemaFactory.java | 16 +++++++++++++
.../apache/commons/xml/HardeningTransformer.java | 7 ++++++
.../commons/xml/HardeningTransformerFactory.java | 28 ++++++++++++++++++++--
.../org/apache/commons/xml/HardeningValidator.java | 7 ++++++
.../org/apache/commons/xml/HardeningXMLFilter.java | 7 ++++++
.../org/apache/commons/xml/HardeningXPath.java | 6 ++---
.../commons/xml/HardeningXPathExpression.java | 5 ++--
.../org/apache/commons/xml/SAXParserHardener.java | 11 ++++++---
.../java/org/apache/commons/xml/XmlFactories.java | 4 +++-
10 files changed, 86 insertions(+), 13 deletions(-)
diff --git
a/src/main/java/org/apache/commons/xml/FallbackIgnoreURIResolver.java
b/src/main/java/org/apache/commons/xml/FallbackIgnoreURIResolver.java
index cd28c64..debd391 100644
--- a/src/main/java/org/apache/commons/xml/FallbackIgnoreURIResolver.java
+++ b/src/main/java/org/apache/commons/xml/FallbackIgnoreURIResolver.java
@@ -63,7 +63,7 @@ final class FallbackIgnoreURIResolver implements URIResolver {
*
* @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
+ * @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.
*/
private static Document newEmptyDocument() {
@@ -110,6 +110,12 @@ URIResolver getDelegate() {
return delegate;
}
+ /**
+ * {@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.
+ */
@Override
public Source resolve(final String href, final String base) throws
TransformerException {
final Source resolved = delegate != null ? delegate.resolve(href,
base) : null;
diff --git a/src/main/java/org/apache/commons/xml/HardeningSchemaFactory.java
b/src/main/java/org/apache/commons/xml/HardeningSchemaFactory.java
index c517265..c55fe91 100644
--- a/src/main/java/org/apache/commons/xml/HardeningSchemaFactory.java
+++ b/src/main/java/org/apache/commons/xml/HardeningSchemaFactory.java
@@ -19,6 +19,7 @@
import java.util.Objects;
+import javax.xml.parsers.FactoryConfigurationError;
import javax.xml.transform.Source;
import javax.xml.transform.TransformerConfigurationException;
import javax.xml.validation.Schema;
@@ -55,6 +56,15 @@
*/
final class HardeningSchemaFactory extends SchemaFactory {
+ /**
+ * Hardens every schema source through {@link
SAXParserHardener#hardenSource(Source)}.
+ *
+ * @param schemas the schema sources to harden; must not be {@code null}.
+ * @return a new array of hardened sources.
+ * @throws SAXException if any source cannot be hardened.
+ * @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.
+ */
private static Source[] harden(final Source[] schemas) throws SAXException
{
final Source[] hardened = new Source[schemas.length];
try {
@@ -113,6 +123,12 @@ public Schema newSchema() throws SAXException {
return new HardeningSchema(delegate.newSchema());
}
+ /**
+ * {@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.
+ */
@Override
public Schema newSchema(final Source[] schemas) throws SAXException {
return new HardeningSchema(delegate.newSchema(harden(schemas)));
diff --git a/src/main/java/org/apache/commons/xml/HardeningTransformer.java
b/src/main/java/org/apache/commons/xml/HardeningTransformer.java
index 1210f8f..e0b8bcd 100644
--- a/src/main/java/org/apache/commons/xml/HardeningTransformer.java
+++ b/src/main/java/org/apache/commons/xml/HardeningTransformer.java
@@ -21,6 +21,7 @@
import java.util.Properties;
import java.util.function.Supplier;
+import javax.xml.parsers.FactoryConfigurationError;
import javax.xml.transform.ErrorListener;
import javax.xml.transform.Result;
import javax.xml.transform.Source;
@@ -127,6 +128,12 @@ public void setURIResolver(final URIResolver resolver) {
floor.setDelegate(resolver);
}
+ /**
+ * {@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.
+ */
@Override
public void transform(final Source xmlSource, final Result outputTarget)
throws TransformerException {
try {
diff --git
a/src/main/java/org/apache/commons/xml/HardeningTransformerFactory.java
b/src/main/java/org/apache/commons/xml/HardeningTransformerFactory.java
index 55a4c10..2b9745c 100644
--- a/src/main/java/org/apache/commons/xml/HardeningTransformerFactory.java
+++ b/src/main/java/org/apache/commons/xml/HardeningTransformerFactory.java
@@ -82,7 +82,7 @@ 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
+ * @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.
*/
private static Source hardenSourceToDom(final Source source) throws
TransformerConfigurationException {
@@ -154,7 +154,7 @@ private static Templates unwrap(final Templates templates) {
/**
* {@inheritDoc}
*
- * @throws FactoryConfigurationError Thrown from {@link
DocumentBuilderFactory} in case of a {@link java.util.ServiceConfigurationError
service
+ * @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
@@ -189,6 +189,12 @@ private TransformerHandler hardenHandler(final
TransformerHandler handler) {
return handler == null ? null : new
HardeningTransformerHandler(handler, getURIResolver(), emptySource);
}
+ /**
+ * {@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.
+ */
@Override
public Templates newTemplates(final Source source) throws
TransformerConfigurationException {
final Templates templates =
delegate.newTemplates(SAXParserHardener.hardenSource(source));
@@ -208,6 +214,12 @@ public Transformer newTransformer() throws
TransformerConfigurationException {
return transformer == null ? null : new
HardeningTransformer(transformer, getURIResolver(), emptySource);
}
+ /**
+ * {@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.
+ */
@Override
public Transformer newTransformer(final Source source) throws
TransformerConfigurationException {
final Transformer transformer =
delegate.newTransformer(SAXParserHardener.hardenSource(source));
@@ -219,6 +231,12 @@ public TransformerHandler newTransformerHandler() throws
TransformerConfiguratio
return hardenHandler(delegate.newTransformerHandler());
}
+ /**
+ * {@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.
+ */
@Override
public TransformerHandler newTransformerHandler(final Source source)
throws TransformerConfigurationException {
return
hardenHandler(delegate.newTransformerHandler(SAXParserHardener.hardenSource(source)));
@@ -230,6 +248,12 @@ public TransformerHandler newTransformerHandler(final
Templates templates) throw
return
hardenHandler(delegate.newTransformerHandler(unwrap(templates)));
}
+ /**
+ * {@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.
+ */
@Override
public XMLFilter newXMLFilter(final Source source) throws
TransformerConfigurationException {
final Templates templates = newTemplates(source);
diff --git a/src/main/java/org/apache/commons/xml/HardeningValidator.java
b/src/main/java/org/apache/commons/xml/HardeningValidator.java
index 96d651b..6c61c7b 100644
--- a/src/main/java/org/apache/commons/xml/HardeningValidator.java
+++ b/src/main/java/org/apache/commons/xml/HardeningValidator.java
@@ -20,6 +20,7 @@
import java.io.IOException;
import java.util.Objects;
+import javax.xml.parsers.FactoryConfigurationError;
import javax.xml.transform.Result;
import javax.xml.transform.Source;
import javax.xml.transform.TransformerConfigurationException;
@@ -103,6 +104,12 @@ public void setResourceResolver(final LSResourceResolver
resourceResolver) {
floor.setDelegate(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.
+ */
@Override
public void validate(final Source source, final Result result) throws
SAXException, IOException {
try {
diff --git a/src/main/java/org/apache/commons/xml/HardeningXMLFilter.java
b/src/main/java/org/apache/commons/xml/HardeningXMLFilter.java
index 05de4f7..a8ad74b 100644
--- a/src/main/java/org/apache/commons/xml/HardeningXMLFilter.java
+++ b/src/main/java/org/apache/commons/xml/HardeningXMLFilter.java
@@ -20,6 +20,7 @@
import java.io.IOException;
import java.util.Objects;
+import javax.xml.parsers.FactoryConfigurationError;
import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerException;
import javax.xml.transform.sax.SAXResult;
@@ -55,6 +56,12 @@ final class HardeningXMLFilter extends XMLFilterImpl {
this.templates = Objects.requireNonNull(templates, "templates");
}
+ /**
+ * {@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.
+ */
@Override
public void parse(final InputSource input) throws SAXException,
IOException {
final ContentHandler handler = getContentHandler();
diff --git a/src/main/java/org/apache/commons/xml/HardeningXPath.java
b/src/main/java/org/apache/commons/xml/HardeningXPath.java
index c800b03..fe84b19 100644
--- a/src/main/java/org/apache/commons/xml/HardeningXPath.java
+++ b/src/main/java/org/apache/commons/xml/HardeningXPath.java
@@ -58,7 +58,7 @@ 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
+ * @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.
*/
static Document parse(final InputSource source) throws
XPathExpressionException {
@@ -93,7 +93,7 @@ public XPathExpression compile(final String expression)
throws XPathExpressionEx
/**
* {@inheritDoc}
*
- * @throws FactoryConfigurationError Thrown from {@link
DocumentBuilderFactory} in case of a {@link java.util.ServiceConfigurationError
service
+ * @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
@@ -104,7 +104,7 @@ public String evaluate(final String expression, final
InputSource source) throws
/**
* {@inheritDoc}
*
- * @throws FactoryConfigurationError Thrown from {@link
DocumentBuilderFactory} in case of a {@link java.util.ServiceConfigurationError
service
+ * @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
diff --git a/src/main/java/org/apache/commons/xml/HardeningXPathExpression.java
b/src/main/java/org/apache/commons/xml/HardeningXPathExpression.java
index 58c42cb..579bfa9 100644
--- a/src/main/java/org/apache/commons/xml/HardeningXPathExpression.java
+++ b/src/main/java/org/apache/commons/xml/HardeningXPathExpression.java
@@ -20,7 +20,6 @@
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;
@@ -52,7 +51,7 @@ final class HardeningXPathExpression implements
XPathExpression {
/**
* {@inheritDoc}
*
- * @throws FactoryConfigurationError Thrown from {@link
DocumentBuilderFactory} in case of a {@link java.util.ServiceConfigurationError
service
+ * @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
@@ -63,7 +62,7 @@ public String evaluate(final InputSource source) throws
XPathExpressionException
/**
* {@inheritDoc}
*
- * @throws FactoryConfigurationError Thrown from {@link
DocumentBuilderFactory} in case of a {@link java.util.ServiceConfigurationError
service
+ * @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
diff --git a/src/main/java/org/apache/commons/xml/SAXParserHardener.java
b/src/main/java/org/apache/commons/xml/SAXParserHardener.java
index 08f874b..5f4752e 100644
--- a/src/main/java/org/apache/commons/xml/SAXParserHardener.java
+++ b/src/main/java/org/apache/commons/xml/SAXParserHardener.java
@@ -122,13 +122,16 @@ static XMLReader hardenReader(final XMLReader reader) {
/**
* Rewrites a {@link Source} so that any SAX parsing it triggers runs
through a hardened {@link XMLReader}.
- *
- * <p>Only a {@link StreamSource} or a {@link SAXSource} without a reader
is enriched with a hardened, namespace-aware reader; other source kinds are
returned
- * as-is. Used by the TrAX and schema wrappers to route every source they
parse through the SAX hardening path.</p>
+ * <p>
+ * Only a {@link StreamSource} or a {@link SAXSource} without a reader is
enriched with a hardened, namespace-aware reader; other source kinds are
returned
+ * as-is. Used by the TrAX and schema wrappers to route every source they
parse through the SAX hardening path.
+ * </p>
*
* @param source the source to harden; never {@code null}.
* @return a hardened source.
* @throws TransformerConfigurationException if a hardened reader cannot
be obtained.
+ * @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.
*/
static Source hardenSource(final Source source) throws
TransformerConfigurationException {
if (source instanceof StreamSource || source instanceof SAXSource &&
((SAXSource) source).getXMLReader() == null) {
@@ -143,6 +146,8 @@ static Source hardenSource(final Source source) throws
TransformerConfigurationE
*
* @return a hardened reader.
* @throws TransformerConfigurationException if a hardened reader cannot
be obtained.
+ * @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.
*/
static XMLReader newHardenedReader() throws
TransformerConfigurationException {
try {
diff --git a/src/main/java/org/apache/commons/xml/XmlFactories.java
b/src/main/java/org/apache/commons/xml/XmlFactories.java
index a85501c..8f3ed31 100644
--- a/src/main/java/org/apache/commons/xml/XmlFactories.java
+++ b/src/main/java/org/apache/commons/xml/XmlFactories.java
@@ -92,7 +92,7 @@ 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
+ * @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() {
@@ -111,6 +111,8 @@ public static DocumentBuilderFactory
newDocumentBuilderFactory() {
*
* @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.
*/
public static SAXParserFactory newSAXParserFactory() {
return SAXParserHardener.harden(SAXParserFactory.newInstance());
