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

Package org.apache.commons.xml.secure

# Class SecureTransformerFactory

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

public final class SecureTransformerFactory extends Object
Creates new, secure `TransformerFactory` instances.

Beyond the three universal guarantees on `org.apache.commons.xml.secure`: `xsl:import`, `xsl:include` and `document()` URIs are not resolved.

The guarantees govern what the transform reads, not what it writes: an output instruction like `xsl:result-document` still writes wherever the stylesheet directs, so an untrusted stylesheet's output destinations must be restricted outside the library.

The guarantees apply to every parser the factory creates internally for the standard `TransformerFactory` entry points: stylesheet compilation (`newTemplates(Source)`, `newTransformer(Source)`) and source-document reading at `Transformer.transform(Source, Result)` time.

The `href` an `xml-stylesheet` processing instruction names is content of the document being scanned, so `getAssociatedStylesheet` treats it as any other content-named reference: install a `URIResolver` resolving that href to compile the stylesheet it points at. Without one the returned `Source` carries empty content rather than naming the URI, so compiling it cannot fetch a stylesheet the parsed document chose.

The `SAXTransformerFactory` extension methods (`newTransformerHandler(..)`, `newTemplatesHandler()`, `newXMLFilter(..)`), if reachable by casting the returned factory, produce objects carrying the same guarantees.

This class is not itself a `TransformerFactory`, 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 TransformerFactory`
  `newDefaultInstance()`
  Returns a new, secure `TransformerFactory` of the system-default implementation.
  `static TransformerFactory`
  `newInstance()`
  Returns a new, secure `TransformerFactory`.
  `static TransformerFactory`
  `newInstance(String factoryClassName, ClassLoader classLoader)`
  Returns a new, secure `TransformerFactory` 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 TransformerFactory newDefaultInstance()
    Returns a new, secure `TransformerFactory` of the system-default implementation.

    Obtained from `TransformerFactory.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.
      `TransformerFactoryConfigurationError` - Thrown if the running platform provides neither `newDefaultInstance()` nor the JDK's built-in implementation (for example Android).

  - ### newInstance

    public static TransformerFactory newInstance()
    Returns a new, secure `TransformerFactory`.
    Returns:
      A secure factory.
    Throws:
      `IllegalStateException` - Thrown if a required secure setting cannot be applied to the underlying implementation.

  - ### newInstance

    public static TransformerFactory newInstance(String factoryClassName, ClassLoader classLoader)
    Returns a new, secure `TransformerFactory` of the given implementation class.
    Parameters:
      `factoryClassName` - The fully qualified class name of the `TransformerFactory` 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.
      `TransformerFactoryConfigurationError` - Thrown if `factoryClassName` is `null` or the factory class cannot be loaded or instantiated.