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 and do not provide an indication of whether the requested adjustment was made. 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.

  • 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()
    Make 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)
    Set 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 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)
    Set 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, try 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, try 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 Details

    • allowDTD

      T allowDTD​(boolean v)
      Whether to allow a DTD at all.
    • 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, try passing the supplied value with each URI from names in order until one is not rejected by the underlying parser.
    • defaults

      T defaults()
      Make 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, try 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)
      Set 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)
      Set 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.