Class SecureDocumentBuilderFactory

java.lang.Object

org.apache.commons.xml.secure.SecureDocumentBuilderFactory

public final class SecureDocumentBuilderFactory
extends Object

Creates new, secure DocumentBuilderFactory instances.

Beyond the three universal guarantees on org.apache.commons.xml.secure, XInclude resolution is denied by default. When setXIncludeAware(true) is called on the returned factory, the parser will process xi:include elements but every external resource lookup is rejected. To permit specific trusted resources, install an EntityResolver on the DocumentBuilder that allow-lists them; any href the resolver does not explicitly allow stays blocked.

This class is not itself a DocumentBuilderFactory, so it inherits none of the static JAXP factory methods. A caller therefore cannot obtain an unsecured factory through this class by calling a method such as newDefaultInstance(). The secure factories are instances of a nested, non-public wrapper class.

See Also:

• org.apache.commons.xml.secure

Method Summary

Modifier and Type	Method	Description
static DocumentBuilderFactory	newDefaultInstance()	Returns a new, secure DocumentBuilderFactory of the system-default implementation.
static DocumentBuilderFactory	newDefaultNSInstance()	Returns a new, secure, namespace-aware DocumentBuilderFactory of the system-default implementation, enabling namespace awareness on newDefaultInstance(), the behavior DocumentBuilderFactory.newDefaultNSInstance() (Java 13 or later) is specified to have.
static DocumentBuilderFactory	newInstance()	Returns a new, secure DocumentBuilderFactory.
static DocumentBuilderFactory	newInstance(String factoryClassName, ClassLoader classLoader)	Returns a new, secure DocumentBuilderFactory of the given implementation class.
static DocumentBuilder	newNSDocumentBuilder()	Creates a new, secure, namespace-aware DocumentBuilder from newNSInstance().
static DocumentBuilderFactory	newNSInstance()	Returns a new, secure, namespace-aware DocumentBuilderFactory, enabling namespace awareness on newInstance(), the behavior DocumentBuilderFactory.newNSInstance() (Java 13 or later) is specified to have.
static DocumentBuilderFactory	newNSInstance(String factoryClassName, ClassLoader classLoader)	Returns a new, secure, namespace-aware DocumentBuilderFactory of the given implementation class, enabling namespace awareness on newInstance(String, ClassLoader), the behavior DocumentBuilderFactory.newNSInstance(String, ClassLoader) (Java 13 or later) is specified to have.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

newDefaultInstance

public static DocumentBuilderFactory newDefaultInstance()

Returns a new, secure DocumentBuilderFactory of the system-default implementation.

Obtained from DocumentBuilderFactory.newDefaultInstance() where the platform provides it (Java 9 or later), by instantiating the JDK's built-in implementation directly on Java 8, and by the standard newInstance() lookup where the platform provides neither (for example, Android, whose lookup is itself pinned to the platform implementation).

Returns:

A secure factory.

Throws:

IllegalStateException - Thrown if a required secure setting cannot be applied to the underlying implementation.

FactoryConfigurationError - Thrown from the newInstance() lookup this method falls back to on a platform that provides neither newDefaultInstance() nor the JDK's built-in implementation (for example, Android).

newDefaultNSInstance

public static DocumentBuilderFactory newDefaultNSInstance()

Returns a new, secure, namespace-aware DocumentBuilderFactory of the system-default implementation, enabling namespace awareness on newDefaultInstance(), the behavior DocumentBuilderFactory.newDefaultNSInstance() (Java 13 or later) is specified to have.

Returns:

A secure, namespace-aware factory.

Throws:

IllegalStateException - Thrown if a required secure setting cannot be applied to the underlying implementation.

FactoryConfigurationError - Thrown from the newInstance() lookup newDefaultInstance() falls back to on a platform that provides neither newDefaultInstance() nor the JDK's built-in implementation (for example, Android).

newInstance

public static DocumentBuilderFactory newInstance()

Returns a new, secure DocumentBuilderFactory.

Returns:

A secure factory.

Throws:

IllegalStateException - Thrown if a required secure setting cannot be applied to the underlying implementation.

IllegalStateException - Thrown if a (non-Android) factory cannot support the secure processing feature XMLConstants.FEATURE_SECURE_PROCESSING.

FactoryConfigurationError - Thrown from a factory in case of a service configuration error or if the implementation is not available or cannot be instantiated.

newInstance

public static DocumentBuilderFactory newInstance(String factoryClassName,
 ClassLoader classLoader)

Returns a new, secure DocumentBuilderFactory of the given implementation class.

Parameters:

factoryClassName - The fully qualified class name of the DocumentBuilderFactory implementation.

classLoader - The class loader used to load the factory class; null means the current thread's context class loader.

Returns:

A secure factory.

Throws:

IllegalStateException - Thrown if a required secure setting cannot be applied to the underlying implementation.

IllegalStateException - Thrown if a (non-Android) factory cannot support the secure processing feature XMLConstants.FEATURE_SECURE_PROCESSING.

FactoryConfigurationError - Thrown if factoryClassName is null or the factory class cannot be loaded or instantiated.

newNSDocumentBuilder

public static DocumentBuilder newNSDocumentBuilder()

Creates a new, secure, namespace-aware DocumentBuilder from newNSInstance().

No factory is cached: each call configures a fresh one. To parse many documents, keep the returned builder and call DocumentBuilder.reset() between documents. Reusing the builder saves more than caching the factory would, and reset() costs next to nothing while keeping handler state from leaking between parses. A builder is not thread-safe, so reuse it within one thread.

Returns:

A secure, namespace-aware builder.

Throws:

IllegalStateException - Thrown if a required secure setting cannot be applied to the underlying implementation, or if the implementation cannot create a builder.

FactoryConfigurationError - Thrown from a factory in case of a service configuration error or if the implementation is not available or cannot be instantiated.

Since:

1.1.0

newNSInstance

public static DocumentBuilderFactory newNSInstance()

Returns a new, secure, namespace-aware DocumentBuilderFactory, enabling namespace awareness on newInstance(), the behavior DocumentBuilderFactory.newNSInstance() (Java 13 or later) is specified to have.

Returns:

A secure, namespace-aware factory.

Throws:

IllegalStateException - Thrown if a required secure setting cannot be applied to the underlying implementation.

FactoryConfigurationError - Thrown from a factory in case of a service configuration error or if the implementation is not available or cannot be instantiated.

newNSInstance

public static DocumentBuilderFactory newNSInstance(String factoryClassName,
 ClassLoader classLoader)

Returns a new, secure, namespace-aware DocumentBuilderFactory of the given implementation class, enabling namespace awareness on newInstance(String, ClassLoader), the behavior DocumentBuilderFactory.newNSInstance(String, ClassLoader) (Java 13 or later) is specified to have.

Parameters:

factoryClassName - The fully qualified class name of the DocumentBuilderFactory implementation.

classLoader - The class loader used to load the factory class; null means the current thread's context class loader.

Returns:

A secure, namespace-aware factory.

Throws:

IllegalStateException - Thrown if a required secure setting cannot be applied to the underlying implementation.

FactoryConfigurationError - Thrown if factoryClassName is null or the factory class cannot be loaded or instantiated.