Package org.apache.commons.xml

Class XmlFactories

java.lang.Object
org.apache.commons.xml.XmlFactories
public final class XmlFactories extends Object
Entry point for obtaining hardened JAXP factories.

Every method on this class returns a fresh, hardened factory instance. No caching or pooling is performed; callers on a hot path are responsible for their own caching.

Hardening guarantees

Every factory returned by this class makes the same three guarantees, regardless of which JAXP implementation is on the classpath:

  • External DTDs are not fetched.
  • External entities are not resolved.
  • Internal entity expansion is bounded by the JDK's default limit, so DoS payloads such as Billion Laughs are rejected before they exhaust resources.

The guarantees hold whether or not the caller opts into DTD validation (setValidating(true)) or attaches a compiled XSD via setSchema: every external resource the validation would otherwise fetch (the DTD itself, an xsi:schemaLocation hint, an external entity referenced from the DTD) remains blocked.

Each method on this class adds factory-specific guarantees on top of the three above, documented on the corresponding newXxxFactory() method.

Caller-supplied URIs

A top-level URI passed directly by the caller is fetched as-is: StreamSource(systemId), DocumentBuilder.parse(String), or a SAXSource built from a system id all cause the JAXP implementation to open that URI without consulting the hardening layer. Use a URIResolver or EntityResolver if you need to restrict the top-level fetch.

Thread safety

The returned factories inherit the thread-safety properties of the underlying JAXP implementation, which in practice means they are not guaranteed to be thread-safe. Create a new factory per thread or synchronise externally.

This class itself is thread-safe: all methods are static and stateless.

  • Method Details

    • harden

      public static Source harden(Source source) throws TransformerConfigurationException
      Rewrites a Source so that any SAX parsing it triggers runs through an XmlFactories-hardened XMLReader.

      Only StreamSource and SAXSource without a reader are enriched with a hardened reader. Other kinds of sources are returned as-is.

      Parameters:
      source - the source to harden; never null.
      Returns:
      a hardened source.
      Throws:
      TransformerConfigurationException - if a hardened reader cannot be obtained.

    • harden

      public static XMLReader harden(XMLReader reader)
      Hardens an existing XMLReader.
      Parameters:
      reader - the reader to harden; never null.
      Returns:
      a hardened reader.
      Throws:
      IllegalStateException - if the reader's concrete class is not recognized by any bundled hardening recipe, or if the matching recipe cannot apply its settings to it.

    • newDocumentBuilderFactory

      public static DocumentBuilderFactory newDocumentBuilderFactory()
      Returns a fresh, hardened DocumentBuilderFactory.

      Enabling XInclude: setXIncludeAware(true) on its own does not make XInclude usable, because an included resource is fetched like any other external resource and is therefore blocked, failing the parse. A caller that genuinely wants XInclude must, in addition to enabling awareness, install a custom EntityResolver that permits those specific lookups.

      Returns:
      a hardened factory.
      Throws:
      IllegalStateException - if a required hardening setting cannot be applied to the underlying implementation.

    • newSAXParserFactory

      public static SAXParserFactory newSAXParserFactory()
      Returns a fresh, hardened SAXParserFactory.

      Beyond the three universal guarantees on XmlFactories, XInclude resolution is disabled. Calling setXIncludeAware(true) on the returned factory does not re-enable resolution; a parse that encounters an xi:include element fails.

      Returns:
      a hardened factory.
      Throws:
      IllegalStateException - if the underlying JAXP implementation is not recognized by any bundled hardening recipe, or if the matching recipe cannot apply its settings to it.

    • newSchemaFactory

      public static SchemaFactory newSchemaFactory()
      Returns a fresh, hardened SchemaFactory configured for W3C XML Schema (XMLConstants.W3C_XML_SCHEMA_NS_URI).

      Beyond the three universal guarantees on XmlFactories:

      • xs:import, xs:include and xs:redefine schemaLocation URIs are not resolved during schema compilation, and
      • xsi:schemaLocation / xsi:noNamespaceSchemaLocation hints in instance documents are not resolved during validation.

      The same guarantees apply to Validator and ValidatorHandler instances produced from the resulting Schema.

      Returns:
      a hardened factory.
      Throws:
      IllegalStateException - if the underlying Schema implementation is not recognized by any bundled hardening recipe, or if the matching recipe cannot apply its settings to it.

    • newTransformerFactory

      public static TransformerFactory newTransformerFactory()
      Returns a fresh, hardened TransformerFactory.

      Beyond the three universal guarantees on XmlFactories: xsl:import, xsl:include and document() URIs are not resolved.

      The guarantees apply to every parser the factory creates internally, both for stylesheet compilation and for source-document reading at Transformer.transform(Source, Result) time.

      Returns:
      a hardened factory.
      Throws:
      IllegalStateException - if the underlying TrAX implementation is not recognized by any bundled hardening recipe, or if the matching recipe cannot apply its settings to it.

    • newXMLInputFactory

      public static XMLInputFactory newXMLInputFactory()
      Returns a fresh, hardened XMLInputFactory.

      The three universal guarantees on XmlFactories apply; StAX exposes no additional vectors beyond them.

      Returns:
      a hardened factory.
      Throws:
      IllegalStateException - if the underlying StAX implementation is not recognized by any bundled hardening recipe, or if the matching recipe cannot apply its settings to it.

    • newXPathFactory

      public static XPathFactory newXPathFactory()
      Returns a fresh, hardened XPathFactory for the default XPath object model.

      Beyond the three universal guarantees on XmlFactories, URI-fetching XPath 3.1+ functions (doc(), collection(), unparsed-text()) are not resolved.

      Returns:
      a hardened factory.
      Throws:
      IllegalStateException - if the underlying XPath implementation is not recognized by any bundled hardening recipe, or if the matching recipe cannot apply its settings to it.