Module org.postgresql.pljava
Package org.postgresql.pljava

Interface Adjusting.XML.Parsing<T extends Adjusting.XML.Parsing<T>>

  • All Known Subinterfaces:
    Adjusting.XML.DOMSource, Adjusting.XML.Result<T>, Adjusting.XML.SAXResult, Adjusting.XML.SAXSource, Adjusting.XML.Source<T>, Adjusting.XML.SourceResult, Adjusting.XML.StAXSource, Adjusting.XML.StreamResult
    Enclosing class:
    Adjusting.XML
    public static interface Adjusting.XML.Parsing<T extends Adjusting.XML.Parsing<T>>
    Interface with methods to adjust the restrictions on XML parsing that are commonly considered when XML content might be from untrusted sources.

    The adjusting methods are best-effort; not all of the adjustments are available for all flavors of Source or Result or for all parser implementations or versions the Java runtime may supply. Cases where a requested adjustment has not been made are handled as follows:

    Any sequence of adjustment calls will ultimately be followed by a get. During the sequence of adjustments, exceptions caught are added to a signaling list or to a quiet list, where "added to" means that if either list has a first exception, any caught later are attached to that exception with addSuppressed.

    For each adjustment (and depending on the type of underlying Source or Result), one or more exception types will be 'expected' as indications that an identifying key or value for that adjustment was not recognized. This implementation may continue trying to apply the adjustment, using other keys that have at times been used to identify it. Expected exceptions caught during these attempts form a temporary list (a first exception and those attached to it by addSuppressed). Once any such attempt succeeds, the adjustment is considered made, and any temporary expected exceptions list from the adjustment is discarded. If no attempt succeeded, the temporary list is retained, by adding its head exception to the quiet list.

    Any exceptions caught that are not instances of any of the 'expected' types are added to the signaling list.

    When get is called, the head exception on the signaling list, if any, is thrown. Otherwise, the head exception on the quiet list, if any, is logged at WARNING level.

    During a chain of adjustments, lax() can be called to tailor the handling of the quiet list. A lax() call applies to whatever exceptions have been added to the quiet list up to that point. To discard them, call lax(true); to move them to the signaling list, call lax(false).

    • Method Summary

      Modifier and Type Method Description
      T accessExternalDTD​(String protocols)
      Protocol schemes allowed in the URL of an external DTD to be fetched.
      T accessExternalSchema​(String protocols)
      Protocol schemes allowed in the URL of an external schema to be fetched.
      T allowDTD​(boolean v)
      Whether to allow a DTD at all.
      T defaults()
      Makes a best effort to apply the recommended, restrictive defaults from the OWASP cheat sheet, to the extent they are supported by the underlying parser, runtime, and version.
      T elementAttributeLimit​(int limit)
      Maximum number of attributes on an element, with a negative or zero value indicating no limit.
      T entityExpansionLimit​(int limit)
      Maximum number of entity expansions, with a negative or zero value indicating no limit.
      T entityReplacementLimit​(int limit)
      Limit on total number of nodes in all entity referenced, with a negative or zero value indicating no limit.
      T entityResolver​(EntityResolver resolver)
      Sets an EntityResolver of the type used by SAX and DOM (optional operation).
      T expandEntityReferences​(boolean v)
      Whether to expand entity references in the document to their declared replacement content.
      T externalGeneralEntities​(boolean v)
      Whether to retrieve external "general" entities (those that can be used in the document body) declared in the DTD.
      T externalParameterEntities​(boolean v)
      Whether to retrieve external "parameter" entities (those declared with a % and usable only within the DTD) declared in the DTD.
      T ignoreDTD()
      Specifies that any DTD should be ignored (neither processed nor rejected as an error).
      T lax​(boolean discard)
      Tailors the treatment of 'quiet' exceptions during a chain of best-effort adjustments.
      T loadExternalDTD​(boolean v)
      Whether to retrieve any external DTD subset declared in the DTD.
      T maxElementDepth​(int depth)
      Maximum element depth, with a negative or zero value indicating no limit.
      T maxGeneralEntitySizeLimit​(int limit)
      Maximum size of any general entities, with a negative or zero value indicating no limit.
      T maxParameterEntitySizeLimit​(int limit)
      Maximum size of any parameter entities (including the result of nesting parameter entities), with a negative or zero value indicating no limit.
      T maxXMLNameLimit​(int limit)
      Maximum size of XML names (including element and attribute names, namespace prefix, and namespace URI even though that isn't an XML name), with a negative or zero value indicating no limit.
      T schema​(Schema schema)
      Sets a Schema to be applied during SAX or DOM parsing (optional operation).
      T setFirstSupportedFeature​(boolean value, String... names)
      For a feature that may have been identified by more than one URI in different parsers or versions, tries passing the supplied value with each URI from names in order until one is not rejected by the underlying parser.
      T setFirstSupportedProperty​(Object value, String... names)
      For a parser property (in DOM parlance, attribute) that may have been identified by more than one URI in different parsers or versions, tries passing the supplied value with each URI from names in order until one is not rejected by the underlying parser.
      T totalEntitySizeLimit​(int limit)
      Limit on total size of all entities, general or parameter, with a negative or zero value indicating no limit.
      T xIncludeAware​(boolean v)
      Whether to honor XInclude syntax in the document.

    • Method Detail

      • allowDTD

        T allowDTD​(boolean v)
        Whether to allow a DTD at all.

      • ignoreDTD

        T ignoreDTD()
        Specifies that any DTD should be ignored (neither processed nor rejected as an error).

        This treatment is available in Java 22 and later. In earlier Java versions, this will not succeed. Where it is supported, the most recent call of this method or of allowDTD will be honored.

      • externalGeneralEntities

        T externalGeneralEntities​(boolean v)
        Whether to retrieve external "general" entities (those that can be used in the document body) declared in the DTD.

      • externalParameterEntities

        T externalParameterEntities​(boolean v)
        Whether to retrieve external "parameter" entities (those declared with a % and usable only within the DTD) declared in the DTD.

      • loadExternalDTD

        T loadExternalDTD​(boolean v)
        Whether to retrieve any external DTD subset declared in the DTD.

      • xIncludeAware

        T xIncludeAware​(boolean v)
        Whether to honor XInclude syntax in the document.

      • expandEntityReferences

        T expandEntityReferences​(boolean v)
        Whether to expand entity references in the document to their declared replacement content.

      • setFirstSupportedFeature

        T setFirstSupportedFeature​(boolean value,
                           String... names)
        For a feature that may have been identified by more than one URI in different parsers or versions, tries passing the supplied value with each URI from names in order until one is not rejected by the underlying parser.

      • defaults

        T defaults()
        Makes a best effort to apply the recommended, restrictive defaults from the OWASP cheat sheet, to the extent they are supported by the underlying parser, runtime, and version.

        Equivalent to: 

         allowDTD(false).externalGeneralEntities(false)
 .externalParameterEntities(false).loadExternalDTD(false)
 .xIncludeAware(false).expandEntityReferences(false)

      • setFirstSupportedProperty

        T setFirstSupportedProperty​(Object value,
                            String... names)
        For a parser property (in DOM parlance, attribute) that may have been identified by more than one URI in different parsers or versions, tries passing the supplied value with each URI from names in order until one is not rejected by the underlying parser.

        A property differs from a feature in taking a value of some specified type, rather than being simply enabled/disabled with a boolean.

      • elementAttributeLimit

        T elementAttributeLimit​(int limit)
        Maximum number of attributes on an element, with a negative or zero value indicating no limit.

      • entityExpansionLimit

        T entityExpansionLimit​(int limit)
        Maximum number of entity expansions, with a negative or zero value indicating no limit.

      • entityReplacementLimit

        T entityReplacementLimit​(int limit)
        Limit on total number of nodes in all entity referenced, with a negative or zero value indicating no limit.

      • maxElementDepth

        T maxElementDepth​(int depth)
        Maximum element depth, with a negative or zero value indicating no limit.

      • maxGeneralEntitySizeLimit

        T maxGeneralEntitySizeLimit​(int limit)
        Maximum size of any general entities, with a negative or zero value indicating no limit.

      • maxParameterEntitySizeLimit

        T maxParameterEntitySizeLimit​(int limit)
        Maximum size of any parameter entities (including the result of nesting parameter entities), with a negative or zero value indicating no limit.

      • maxXMLNameLimit

        T maxXMLNameLimit​(int limit)
        Maximum size of XML names (including element and attribute names, namespace prefix, and namespace URI even though that isn't an XML name), with a negative or zero value indicating no limit.

      • totalEntitySizeLimit

        T totalEntitySizeLimit​(int limit)
        Limit on total size of all entities, general or parameter, with a negative or zero value indicating no limit.

      • accessExternalDTD

        T accessExternalDTD​(String protocols)
        Protocol schemes allowed in the URL of an external DTD to be fetched.
        Parameters:
        protocols - Empty string to deny all external DTD access, the string "all" to allow fetching by any protocol, or a comma-separated, case insensitive list of protocols to allow. A protocol name prefixed with "jar:" is also a protocol name.

      • accessExternalSchema

        T accessExternalSchema​(String protocols)
        Protocol schemes allowed in the URL of an external schema to be fetched.
        Parameters:
        protocols - Empty string to deny all external DTD access, the string "all" to allow fetching by any protocol, or a comma-separated, case insensitive list of protocols to allow. A protocol name prefixed with "jar:" is also a protocol name.

      • entityResolver

        T entityResolver​(EntityResolver resolver)
        Sets an EntityResolver of the type used by SAX and DOM (optional operation).

        This method only succeeds for a SAXSource or DOMSource (or a StreamResult, where the resolver is set on the parser that will verify the content written). Unlike the best-effort behavior of most methods in this interface, this one will report failure with an exception.

        If the StAX API is wanted, a StAX XMLResolver should be set instead, using setFirstSupportedProperty with the property name XMLInputFactory.RESOLVER.

        Parameters:
        resolver - an instance of org.xml.sax.EntityResolver
        Throws:
        UnsupportedOperationException - if not supported by the underlying flavor of source or result.

      • schema

        T schema​(Schema schema)
        Sets a Schema to be applied during SAX or DOM parsing (optional operation).

        This method only succeeds for a SAXSource or DOMSource (or a StreamResult, where the schema is set on the parser that will verify the content written). Unlike the best-effort behavior of most methods in this interface, this one will report failure with an exception.

        In the SAX case, this must be called before other methods of this interface.

        Parameters:
        schema - an instance of javax.xml.validation.Schema
        Throws:
        UnsupportedOperationException - if not supported by the underlying flavor of source or result.
        IllegalStateException - if the underlying implementation is SAX-based and another method from this interface has been called already.

      • lax

        T lax​(boolean discard)
        Tailors the treatment of 'quiet' exceptions during a chain of best-effort adjustments.

        See the class description for an explanation of the signaling and quiet lists.

        This method applies to whatever exceptions may have been added to the quiet list by best-effort adjustments made up to that point. They can be moved to the signaling list with lax(false), or simply discarded with lax(true). In either case, the quiet list is left empty when lax returns.

        At the time a get method is later called, any exception at the head of the signaling list will be thrown (possibly wrapped in an exception permitted by get's throws clause), with any later exceptions on that list retrievable from the head exception with getSuppressed. Otherwise, any exception at the head of the quiet list (again with any later ones attached as its suppressed list) will be logged at WARNING level.