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

Package org.apache.commons.xml.secure

# Class SecureXPathFactory

java.lang.Object
org.apache.commons.xml.secure.SecureXPathFactory

public final class SecureXPathFactory extends Object
Creates new, secure `XPathFactory` instances.

Beyond the three universal guarantees on `org.apache.commons.xml.secure`, URI-fetching XPath 3.1+ functions (`doc()`, `collection()`, `unparsed-text()`) are not resolved.

The guarantees also cover the document parse behind `XPath.evaluate(String, InputSource)` and `XPathExpression.evaluate(InputSource)`: the input document is built through a secure, namespace-aware `DocumentBuilder` instead of the engine's internal parser.

This class is not itself a `XPathFactory`, 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 XPathFactory`
  `newDefaultInstance()`
  Returns a new, secure `XPathFactory` of the system-default implementation, supporting the default XPath object model.
  `static XPathFactory`
  `newInstance()`
  Returns a new, secure `XPathFactory` for the default XPath object model.
  `static XPathFactory`
  `newInstance(String uri)`
  Returns a new, secure `XPathFactory` for the given object model.
  `static XPathFactory`
  `newInstance(String uri, String factoryClassName, ClassLoader classLoader)`
  Returns a new, secure `XPathFactory` of the given implementation class.

  ### Methods inherited from class java.lang.Object

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

- ## Method Details

  - ### newDefaultInstance

    public static XPathFactory newDefaultInstance()
    Returns a new, secure `XPathFactory` of the system-default implementation, supporting the default XPath object model.

    Obtained from `XPathFactory.newDefaultInstance()` where the platform provides it (Java 9 or later), and by instantiating the JDK's built-in implementation directly on Java 8.

    Returns:
      A secure factory.
    Throws:
      `IllegalStateException` - Thrown if a required secure setting cannot be applied to the underlying implementation.
      `RuntimeException` - Thrown if the running platform provides neither `newDefaultInstance()` nor the JDK's built-in implementation (for example Android).

  - ### newInstance

    public static XPathFactory newInstance()
    Returns a new, secure `XPathFactory` for the default XPath object model.
    Returns:
      A secure factory.
    Throws:
      `IllegalStateException` - Thrown if a required secure setting cannot be applied to the underlying implementation.
      `RuntimeException` - Thrown if there is a failure in creating an `XPathFactory` for the default object model.

  - ### newInstance

    public static XPathFactory newInstance(String uri) throws XPathFactoryConfigurationException
    Returns a new, secure `XPathFactory` for the given object model.
    Parameters:
      `uri` - The underlying object model identifier, as accepted by `XPathFactory.newInstance(String)`.
    Returns:
      A secure factory.
    Throws:
      `IllegalStateException` - Thrown if a required secure setting cannot be applied to the underlying implementation.
      `XPathFactoryConfigurationException` - Thrown if no implementation of the object model is available.
      `NullPointerException` - Thrown if `uri` is `null`.
      `IllegalArgumentException` - Thrown if `uri` is empty.

  - ### newInstance

    public static XPathFactory newInstance(String uri, String factoryClassName, ClassLoader classLoader) throws XPathFactoryConfigurationException
    Returns a new, secure `XPathFactory` of the given implementation class.
    Parameters:
      `uri` - The underlying object model identifier, as accepted by `XPathFactory.newInstance(String)`.
      `factoryClassName` - The fully qualified class name of the `XPathFactory` 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.
      `XPathFactoryConfigurationException` - Thrown if `factoryClassName` is `null`, or if the factory class cannot be loaded or instantiated, or does not support `uri`.
      `NullPointerException` - Thrown if `uri` is `null`.
      `IllegalArgumentException` - Thrown if `uri` is empty.