SecureDocumentBuilderFactory (Apache Commons Secure XML 1.0.0 API)
Description: declaration: package: org.apache.commons.xml.secure, class: SecureDocumentBuilderFactory

Package org.apache.commons.xml.secure

# 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 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 java.lang.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.

  - ### 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.