Class SecureSAXParserFactory

java.lang.Object
org.apache.commons.xml.secure.SecureSAXParserFactory
public final class SecureSAXParserFactory extends Object
Creates new, secure SAXParserFactory 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 XMLReader that allow-lists them; any href the resolver does not explicitly allow stays blocked.

This class is not itself a SAXParserFactory, 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:

  • Method Details

    • newDefaultInstance

      public static SAXParserFactory newDefaultInstance()
      Returns a new, secure SAXParserFactory of the system-default implementation.

      Obtained from SAXParserFactory.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 SAXParserFactory newDefaultNSInstance()
      Returns a new, secure, namespace-aware SAXParserFactory of the system-default implementation, enabling namespace awareness on newDefaultInstance(), the behavior SAXParserFactory.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 SAXParserFactory newInstance()
      Returns a new, secure SAXParserFactory.
      Returns:
      A secure factory.
      Throws:
      IllegalStateException - Thrown if a required secure setting cannot be applied to the underlying implementation.
      FactoryConfigurationError - Thrown from SAXParserFactory in case of a service configuration error or if the implementation is not available or cannot be instantiated.

    • newInstance

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

    • newNSInstance

      public static SAXParserFactory newNSInstance()
      Returns a new, secure, namespace-aware SAXParserFactory, enabling namespace awareness on newInstance(), the behavior SAXParserFactory.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 SAXParserFactory in case of a service configuration error or if the implementation is not available or cannot be instantiated.

    • newNSInstance

      public static SAXParserFactory newNSInstance(String factoryClassName, ClassLoader classLoader)
      Returns a new, secure, namespace-aware SAXParserFactory of the given implementation class, enabling namespace awareness on newInstance(String, ClassLoader), the behavior SAXParserFactory.newNSInstance(String, ClassLoader) (Java 13 or later) is specified to have.
      Parameters:
      factoryClassName - The fully qualified class name of the SAXParserFactory 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.

    • newNSSAXParser

      public static SAXParser newNSSAXParser()
      Creates a new, secure, namespace-aware SAXParser from newNSInstance().

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

      Returns:
      A secure, namespace-aware parser.
      Throws:
      IllegalStateException - Thrown if a required secure setting cannot be applied to the underlying implementation, or if the implementation cannot create a parser.
      FactoryConfigurationError - Thrown from SAXParserFactory in case of a service configuration error or if the implementation is not available or cannot be instantiated.
      Since:
      1.1.0

    • newNSXMLReader

      public static XMLReader newNSXMLReader()
      Creates a new, secure, namespace-aware XMLReader from newNSInstance(), with no content handler registered.

      No factory is cached: each call configures a fresh one. To parse many documents, keep the returned reader and parse each document with it. Reusing the reader saves more than caching the factory would. Handlers set on the reader stay set between parses, and a reader is not thread-safe, so reuse it within one thread.

      Returns:
      A secure, namespace-aware reader.
      Throws:
      IllegalStateException - Thrown if a required secure setting cannot be applied to the underlying implementation, or if the implementation cannot create a reader.
      FactoryConfigurationError - Thrown from SAXParserFactory in case of a service configuration error or if the implementation is not available or cannot be instantiated.
      Since:
      1.1.0

    • newNSXMLReader

      public static XMLReader newNSXMLReader(ContentHandler handler)
      Creates a new, secure, namespace-aware XMLReader from newNSInstance().

      No factory is cached: each call configures a fresh one. To parse many documents, keep the returned reader and parse each document with it. Reusing the reader saves more than caching the factory would. Handlers set on the reader stay set between parses, and a reader is not thread-safe, so reuse it within one thread.

      Parameters:
      handler - The content handler to register on the reader, or null to register none.
      Returns:
      A secure, namespace-aware reader.
      Throws:
      IllegalStateException - Thrown if a required secure setting cannot be applied to the underlying implementation, or if the implementation cannot create a reader.
      FactoryConfigurationError - Thrown from SAXParserFactory in case of a service configuration error or if the implementation is not available or cannot be instantiated.
      Since:
      1.1.0