Package com.adaptris.core.util

Class DocumentBuilderFactoryBuilder

  • public class DocumentBuilderFactoryBuilder
extends java.lang.Object
    Allows simple configuration of a DocumentBuilderFactory.

    For security reasons the default behaviour is to mitigate against XXE attacks and the like. It is still possible to explicitly configure whatever behaviour is required, but we no longer rely on the underlying DocumentBuilderFactory defaults. As a result the vanilla configuration for a DocumentBuilderFactory that is created by this class will have the following defaults:

    Note that the static convenience methods have also been modified to reflect this behaviour. There are the two new newLenientInstance() and newLenientInstanceIfNull(DocumentBuilderFactoryBuilder) methods if the more secure default is not appropriate.

    In the adapter configuration file this class is aliased as xml-document-builder-configuration which is the preferred alternative to the fully qualified classname when building your configuration.

    • Field Detail

    • Constructor Detail

      • DocumentBuilderFactoryBuilder

        public DocumentBuilderFactoryBuilder()

    • Method Detail

      • newRestrictedInstance

        public static final DocumentBuilderFactoryBuilder newRestrictedInstance()
        Create a New instance that disables Entityrefs and also mitigates against XXE via http://apache.org/xml/features/disallow-doctype-decl = true. This is added as a convenience so you don't have to keep configuring it if XXE is a bit of a bother for you.
        Returns:
        a new instance.

      • newLenientInstance

        public static final DocumentBuilderFactoryBuilder newLenientInstance()
        Return a DocumentBuilderFactoryBuilder instance that explicitly does not mitigate against XXE and is also namespace aware.

        This is included for completeness, it's not expected that you'll want to use this, however if you were using newInstance() and you don't like the new defaults then well, here it is.

        Returns:
        a new instance

      • configure

        public javax.xml.parsers.DocumentBuilderFactory configure​(javax.xml.parsers.DocumentBuilderFactory f)
                                                   throws javax.xml.parsers.ParserConfigurationException
        Configure a document builder factory
        Parameters:
        f -
        Returns:
        a reconfigured document builder factory
        Throws:
        javax.xml.parsers.ParserConfigurationException

      • configure

        public javax.xml.parsers.DocumentBuilder configure​(javax.xml.parsers.DocumentBuilder db)
        Configure a document builder.
        Parameters:
        db -
        Returns:
        a reconfigured document builder

      • newDocumentBuilder

        public javax.xml.parsers.DocumentBuilder newDocumentBuilder​(javax.xml.parsers.DocumentBuilderFactory f)
                                                     throws javax.xml.parsers.ParserConfigurationException
        Convenience to create a new DocumentBuilder instance.
        Parameters:
        f - a DocumentBuilderFactory
        Returns:
        a configured DocumentBuilder
        Throws:
        javax.xml.parsers.ParserConfigurationException
        See Also:
        configure(DocumentBuilder), configure(DocumentBuilderFactory)

      • build

        public javax.xml.parsers.DocumentBuilderFactory build()
                                               throws javax.xml.parsers.ParserConfigurationException
        Create a DocumentBuilderFactory.

        If all you're doing is creating a DocumentBuilder straight after calling this method, don't forget to call configure(DocumentBuilder) to make sure you configure the underlying DocumentBuilder with any configured getEntityResolver().

        Throws:
        javax.xml.parsers.ParserConfigurationException

      • getFeatures

        @NonNull
public @NonNull KeyValuePairSet getFeatures()
        Calls DocumentBuilderFactory.setFeature(String, boolean) for each value defined.

        No validation of the features is done and are passed as-is through to the underlying DocumentBuilderFactory.

        Since:
        4.0 By default the XML Feature "http://apache.org/xml/features/disallow-doctype-decl" will be set to true to disable doctype declarations.

      • setFeatures

        public void setFeatures​(@NonNull
                        @NonNull KeyValuePairSet features)
        Calls DocumentBuilderFactory.setFeature(String, boolean) for each value defined.

        No validation of the features is done and are passed as-is through to the underlying DocumentBuilderFactory.

        Since:
        4.0 By default the XML Feature "http://apache.org/xml/features/disallow-doctype-decl" will be set to true to disable doctype declarations.

      • getValidating

        public java.lang.Boolean getValidating()
        Calls DocumentBuilderFactory.setValidating(boolean) if non-null

      • setValidating

        public void setValidating​(java.lang.Boolean validating)
        Calls DocumentBuilderFactory.setValidating(boolean) if non-null

      • getNamespaceAware

        public java.lang.Boolean getNamespaceAware()
        Calls DocumentBuilderFactory.setNamespaceAware(boolean) if non null

      • setNamespaceAware

        public void setNamespaceAware​(java.lang.Boolean namespaceAware)
        Calls DocumentBuilderFactory.setNamespaceAware(boolean) if non null

      • getIgnoreWhitespace

        public java.lang.Boolean getIgnoreWhitespace()
        Calls DocumentBuilderFactory.setIgnoringElementContentWhitespace(boolean) if non-null

      • setIgnoreWhitespace

        public void setIgnoreWhitespace​(java.lang.Boolean ignoreWhitespace)
        Calls DocumentBuilderFactory.setIgnoringElementContentWhitespace(boolean) if non-null

      • getExpandEntityReferences

        public java.lang.Boolean getExpandEntityReferences()
        Wraps DocumentBuilderFactory.setExpandEntityReferences(boolean).
        Since:
        4.0 If not specified, then the default is 'false' so that we mitigate against XXE attacks when parsing XML.

      • setExpandEntityReferences

        public void setExpandEntityReferences​(java.lang.Boolean expandEntityReferences)
        Wraps DocumentBuilderFactory.setExpandEntityReferences(boolean).
        Since:
        4.0 If not specified, then the default is 'false' so that we mitigate against XXE attacks when parsing XML.

      • getIgnoreComments

        public java.lang.Boolean getIgnoreComments()
        Calls DocumentBuilderFactory.setIgnoringComments(boolean) if non-null

      • setIgnoreComments

        public void setIgnoreComments​(java.lang.Boolean ignoreComments)
        Calls DocumentBuilderFactory.setIgnoringComments(boolean) if non-null

      • getCoalescing

        public java.lang.Boolean getCoalescing()
        Calls DocumentBuilderFactory.setCoalescing(boolean) if non-null

      • setCoalescing

        public void setCoalescing​(java.lang.Boolean coalescing)
        Calls DocumentBuilderFactory.setCoalescing(boolean) if non-null

      • getXincludeAware

        public java.lang.Boolean getXincludeAware()
        Calls DocumentBuilderFactory.setXIncludeAware(boolean) if non-null

      • setXincludeAware

        public void setXincludeAware​(java.lang.Boolean xincludeAware)
        Calls DocumentBuilderFactory.setXIncludeAware(boolean) if non-null

      • getEntityResolver

        public org.xml.sax.EntityResolver getEntityResolver()
        Calls DocumentBuilder.setEntityResolver(EntityResolver) if non-null.

      • setEntityResolver

        public void setEntityResolver​(org.xml.sax.EntityResolver entityResolver)
        Calls DocumentBuilder.setEntityResolver(EntityResolver) if non-null.