Digester (Apache Tomcat 9.0.68 API Documentation)

Package org.apache.tomcat.util.digester

## Class Digester

- java.lang.Object
- - org.xml.sax.helpers.DefaultHandler
  - - org.xml.sax.ext.DefaultHandler2
    - - org.apache.tomcat.util.digester.Digester

- All Implemented Interfaces:
    `org.xml.sax.ContentHandler`, `org.xml.sax.DTDHandler`, `org.xml.sax.EntityResolver`, `org.xml.sax.ErrorHandler`, `org.xml.sax.ext.DeclHandler`, `org.xml.sax.ext.EntityResolver2`, `org.xml.sax.ext.LexicalHandler`

      public class Digester
      extends org.xml.sax.ext.DefaultHandler2

  A Digester processes an XML input stream by matching a series of element nesting patterns to execute Rules that have been added prior to the start of parsing. This package was inspired by the `XmlMapper` class that was part of Tomcat 3.0 and 3.1, but is organized somewhat differently.

  See the Digester Developer Guide for more information.

  IMPLEMENTATION NOTE - A single Digester instance may only be used within the context of a single thread at a time, and a call to `parse()` must be completed before another can be initiated even from the same thread.

  IMPLEMENTATION NOTE - A bug in Xerces 2.0.2 prevents the support of XML schema. You need Xerces 2.1/2.3 and up to make this class working with XML schema

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `Digester.EnvironmentPropertySource` | Deprecated. Use `EnvironmentPropertySource` This will be removed in Tomcat 10 onwards.
    `static interface` | `Digester.GeneratedCodeLoader` |

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected java.lang.StringBuilder` | `bodyText` | The body text of the current element.
    `protected ArrayStack<java.lang.StringBuilder>` | `bodyTexts` | The stack of body text string buffers for surrounding elements.
    `protected java.lang.ClassLoader` | `classLoader` | The class loader to use for instantiating application objects.
    `protected java.lang.StringBuilder` | `code` | Generated code.
    `protected boolean` | `configured` | Has this Digester been configured yet.
    `protected org.xml.sax.EntityResolver` | `entityResolver` | The EntityResolver used by the SAX parser.
    `protected java.util.HashMap<java.lang.String,​java.lang.String>` | `entityValidator` | The URLs of entityValidator that have been registered, keyed by the public identifier that corresponds.
    `protected org.xml.sax.ErrorHandler` | `errorHandler` | The application-supplied error handler that is notified when parsing warnings, errors, or fatal errors occur.
    `protected javax.xml.parsers.SAXParserFactory` | `factory` | The SAXParserFactory that is created the first time we need it.
    `protected java.util.Map<java.lang.Class<?>,​java.util.List<java.lang.String>>` | `fakeAttributes` | Fake attributes map (attributes are often used for object creation).
    `protected java.util.ArrayList<java.lang.Object>` | `known` |
    `protected org.xml.sax.Locator` | `locator` | The Locator associated with our parser.
    `protected Log` | `log` | The Log to which most logging calls will be made.
    `protected java.lang.String` | `match` | The current match pattern for nested element processing.
    `protected ArrayStack<java.util.List<Rule>>` | `matches` | Stack whose elements are List objects, each containing a list of Rule objects as returned from Rules.getMatch().
    `protected boolean` | `namespaceAware` | Do we want a "namespace aware" parser.
    `protected java.util.HashMap<java.lang.String,​ArrayStack<java.lang.String>>` | `namespaces` | Registered namespaces we are currently processing.
    `protected ArrayStack<java.lang.Object>` | `params` | The parameters stack being utilized by CallMethodRule and CallParamRule rules.
    `protected javax.xml.parsers.SAXParser` | `parser` | The SAXParser we will use to parse the input stream.
    `protected static IntrospectionUtils.PropertySource[]` | `propertySources` |
    `protected java.lang.String` | `publicId` | The public identifier of the DTD we are currently parsing under (if any).
    `protected org.xml.sax.XMLReader` | `reader` | The XMLReader used to parse digester rules.
    `protected java.lang.Object` | `root` | The "root" element of the stack (in other words, the last object that was popped.
    `protected Rules` | `rules` | The `Rules` implementation containing our collection of `Rule` instances and associated matching policy.
    `protected boolean` | `rulesValidation` | Warn on missing attributes and elements.
    `protected Log` | `saxLog` | The Log to which all SAX event related logging calls will be made.
    `protected static StringManager` | `sm` |
    `protected IntrospectionUtils.PropertySource[]` | `source` |
    `protected ArrayStack<java.lang.Object>` | `stack` | The object stack being constructed.
    `protected boolean` | `useContextClassLoader` | Do we want to use the Context ClassLoader when loading classes for instantiating new objects.
    `protected boolean` | `validating` | Do we want to use a validating parser.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Digester()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addCallMethod​(java.lang.String pattern, java.lang.String methodName)` | Add an "call method" rule for a method which accepts no arguments.
    `void` | `addCallMethod​(java.lang.String pattern, java.lang.String methodName, int paramCount)` | Add an "call method" rule for the specified parameters.
    `void` | `addCallParam​(java.lang.String pattern, int paramIndex)` | Add a "call parameter" rule for the specified parameters.
    `void` | `addFactoryCreate​(java.lang.String pattern, ObjectCreationFactory creationFactory, boolean ignoreCreateExceptions)` | Add a "factory create" rule for the specified parameters.
    `static void` | `addGeneratedClass​(java.lang.String className)` |
    `void` | `addObjectCreate​(java.lang.String pattern, java.lang.String className)` | Add an "object create" rule for the specified parameters.
    `void` | `addObjectCreate​(java.lang.String pattern, java.lang.String className, java.lang.String attributeName)` | Add an "object create" rule for the specified parameters.
    `void` | `addRule​(java.lang.String pattern, Rule rule)` | Register a new Rule matching the specified pattern.
    `void` | `addRuleSet​(RuleSet ruleSet)` | Register a set of Rule instances defined in a RuleSet.
    `void` | `addSetNext​(java.lang.String pattern, java.lang.String methodName, java.lang.String paramType)` | Add a "set next" rule for the specified parameters.
    `void` | `addSetProperties​(java.lang.String pattern)` | Add a "set properties" rule for the specified parameters.
    `void` | `addSetProperties​(java.lang.String pattern, java.lang.String[] excludes)` |
    `void` | `characters​(char[] buffer, int start, int length)` | Process notification of character data received from the body of an XML element.
    `void` | `clear()` | Clear the current contents of the object stack.
    `protected void` | `configure()` | Provide a hook for lazy configuration of this `Digester` instance.
    `org.xml.sax.SAXException` | `createSAXException​(java.lang.Exception e)` | Create a SAX exception which also understands about the location in the digester file where the exception occurs
    `org.xml.sax.SAXException` | `createSAXException​(java.lang.String message)` | Create a SAX exception which also understands about the location in the digester file where the exception occurs
    `org.xml.sax.SAXException` | `createSAXException​(java.lang.String message, java.lang.Exception e)` | Create a SAX exception which also understands about the location in the digester file where the exception occurs
    `void` | `endDocument()` | Process notification of the end of the document being reached.
    `void` | `endElement​(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName)` | Process notification of the end of an XML element being reached.
    `void` | `endGeneratingCode()` |
    `void` | `endPrefixMapping​(java.lang.String prefix)` | Process notification that a namespace prefix is going out of scope.
    `void` | `error​(org.xml.sax.SAXParseException exception)` | Forward notification of a parsing error to the application supplied error handler (if any).
    `void` | `fatalError​(org.xml.sax.SAXParseException exception)` | Forward notification of a fatal parsing error to the application supplied error handler (if any).
    `java.lang.String` | `findNamespaceURI​(java.lang.String prefix)` | Return the currently mapped namespace URI for the specified prefix, if any; otherwise return `null`.
    `java.lang.ClassLoader` | `getClassLoader()` | Return the class loader to be used for instantiating application objects when required.
    `int` | `getCount()` |
    `java.lang.String` | `getCurrentElementName()` |
    `org.xml.sax.Locator` | `getDocumentLocator()` | Gets the document locator associated with our parser.
    `org.xml.sax.EntityResolver` | `getEntityResolver()` | Return the Entity Resolver used by the SAX parser.
    `org.xml.sax.ErrorHandler` | `getErrorHandler()` |
    `javax.xml.parsers.SAXParserFactory` | `getFactory()` | SAX parser factory method.
    `java.util.Map<java.lang.Class<?>,​java.util.List<java.lang.String>>` | `getFakeAttributes()` |
    `static java.lang.String[]` | `getGeneratedClasses()` |
    `java.lang.StringBuilder` | `getGeneratedCode()` |
    `Log` | `getLogger()` |
    `java.lang.String` | `getMatch()` |
    `boolean` | `getNamespaceAware()` |
    `javax.xml.parsers.SAXParser` | `getParser()` |
    `java.lang.Object` | `getProperty​(java.lang.String property)` | Return the current value of the specified property for the underlying `XMLReader` implementation.
    `java.lang.String` | `getPublicId()` |
    `java.lang.Object` | `getRoot()` | When the Digester is being used as a SAXContentHandler, this method allows you to access the root object that has been created after parsing.
    `Rules` | `getRules()` | Return the `Rules` implementation object containing our rules collection and associated matching policy.
    `boolean` | `getRulesValidation()` |
    `Log` | `getSAXLogger()` | Gets the logger used for logging SAX-related information.
    `boolean` | `getUseContextClassLoader()` |
    `boolean` | `getValidating()` |
    `org.xml.sax.XMLReader` | `getXMLReader()` | Return the XMLReader to be used for parsing the input document.
    `void` | `ignorableWhitespace​(char[] buffer, int start, int len)` | Process notification of ignorable whitespace received from the body of an XML element.
    `boolean` | `isFakeAttribute​(java.lang.Object object, java.lang.String name)` | Determine if an attribute is a fake attribute.
    `static boolean` | `isGeneratedCodeLoaderSet()` |
    `static java.lang.Object` | `loadGeneratedClass​(java.lang.String className)` |
    `void` | `notationDecl​(java.lang.String name, java.lang.String publicId, java.lang.String systemId)` | Receive notification of a notation declaration event.
    `java.lang.Object` | `parse​(java.io.File file)` | Parse the content of the specified file using this Digester.
    `java.lang.Object` | `parse​(java.io.InputStream input)` | Parse the content of the specified input stream using this Digester.
    `java.lang.Object` | `parse​(org.xml.sax.InputSource input)` | Parse the content of the specified input source using this Digester.
    `java.lang.Object` | `peek()` | Return the top object on the stack without removing it.
    `java.lang.Object` | `peek​(int n)` | Return the n'th object down the stack, where 0 is the top element and [getCount()-1] is the bottom element.
    `java.lang.Object` | `peekParams()` | Return the top object on the parameters stack without removing it.
    `java.lang.Object` | `pop()` | Pop the top object off of the stack, and return it.
    `java.lang.Object` | `popParams()` | Pop the top object off of the parameters stack, and return it.
    `void` | `processingInstruction​(java.lang.String target, java.lang.String data)` | Process notification of a processing instruction that was encountered.
    `void` | `push​(java.lang.Object object)` | Push a new object onto the top of the object stack.
    `void` | `pushParams​(java.lang.Object object)` | Push a new object onto the top of the parameters stack.
    `void` | `register​(java.lang.String publicId, java.lang.String entityURL)` | Register the specified DTD URL for the specified public identifier.
    `static void` | `replaceSystemProperties()` |
    `void` | `reset()` |
    `org.xml.sax.InputSource` | `resolveEntity​(java.lang.String name, java.lang.String publicId, java.lang.String baseURI, java.lang.String systemId)` |
    `void` | `setClassLoader​(java.lang.ClassLoader classLoader)` | Set the class loader to be used for instantiating application objects when required.
    `void` | `setDocumentLocator​(org.xml.sax.Locator locator)` | Sets the document locator associated with our parser.
    `void` | `setEntityResolver​(org.xml.sax.EntityResolver entityResolver)` | Set the `EntityResolver` used by SAX when resolving public id and system id.
    `void` | `setErrorHandler​(org.xml.sax.ErrorHandler errorHandler)` | Set the error handler for this Digester.
    `void` | `setFakeAttributes​(java.util.Map<java.lang.Class<?>,​java.util.List<java.lang.String>> fakeAttributes)` | Set the fake attributes.
    `void` | `setFeature​(java.lang.String feature, boolean value)` | Sets a flag indicating whether the requested feature is supported by the underlying implementation of `org.xml.sax.XMLReader`.
    `static void` | `setGeneratedCodeLoader​(Digester.GeneratedCodeLoader generatedCodeLoader)` |
    `void` | `setKnown​(java.lang.Object object)` |
    `void` | `setLogger​(Log log)` | Set the current logger for this Digester.
    `void` | `setNamespaceAware​(boolean namespaceAware)` | Set the "namespace aware" flag for parsers we create.
    `static void` | `setPropertySource​(IntrospectionUtils.PropertySource propertySource)` |
    `static void` | `setPropertySource​(IntrospectionUtils.PropertySource[] propertySources)` |
    `void` | `setPublicId​(java.lang.String publicId)` | Set the public id of the current file being parse.
    `void` | `setRules​(Rules rules)` | Set the `Rules` implementation object containing our rules collection and associated matching policy.
    `void` | `setRulesValidation​(boolean rulesValidation)` | Set the rules validation flag.
    `void` | `setSAXLogger​(Log saxLog)` | Sets the logger used for logging SAX-related information.
    `void` | `setUseContextClassLoader​(boolean use)` | Determine whether to use the Context ClassLoader (the one found by calling `Thread.currentThread().getContextClassLoader()`) to resolve/load classes that are defined in various rules.
    `void` | `setValidating​(boolean validating)` | Set the validating parser flag.
    `void` | `skippedEntity​(java.lang.String name)` | Process notification of a skipped entity.
    `void` | `startDocument()` | Process notification of the beginning of the document being reached.
    `void` | `startDTD​(java.lang.String name, java.lang.String publicId, java.lang.String systemId)` |
    `void` | `startElement​(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes list)` | Process notification of the start of an XML element being reached.
    `void` | `startGeneratingCode()` |
    `void` | `startPrefixMapping​(java.lang.String prefix, java.lang.String namespaceURI)` | Process notification that a namespace prefix is coming in to scope.
    `java.lang.String` | `toVariableName​(java.lang.Object object)` |
    `void` | `unparsedEntityDecl​(java.lang.String name, java.lang.String publicId, java.lang.String systemId, java.lang.String notation)` | Receive notification of an unparsed entity declaration event.
    `void` | `warning​(org.xml.sax.SAXParseException exception)` | Forward notification of a parse warning to the application supplied error handler (if any).

    - ### Methods inherited from class org.xml.sax.ext.DefaultHandler2

      `attributeDecl, comment, elementDecl, endCDATA, endDTD, endEntity, externalEntityDecl, getExternalSubset, internalEntityDecl, resolveEntity, startCDATA, startEntity`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### propertySources

          protected static IntrospectionUtils.PropertySource[] propertySources

    - #### sm

          protected static final StringManager sm

    - #### source

          protected IntrospectionUtils.PropertySource[] source

    - #### bodyText

          protected java.lang.StringBuilder bodyText

      The body text of the current element.

    - #### bodyTexts

          protected ArrayStack<java.lang.StringBuilder> bodyTexts

      The stack of body text string buffers for surrounding elements.

    - #### matches

          protected ArrayStack<java.util.List<Rule>> matches

      Stack whose elements are List objects, each containing a list of Rule objects as returned from Rules.getMatch(). As each xml element in the input is entered, the matching rules are pushed onto this stack. After the end tag is reached, the matches are popped again. The depth of is stack is therefore exactly the same as the current "nesting" level of the input xml.
      Since:
        1.6

    - #### classLoader

          protected java.lang.ClassLoader classLoader

      The class loader to use for instantiating application objects. If not specified, the context class loader, or the class loader used to load Digester itself, is used, based on the value of the `useContextClassLoader` variable.

    - #### configured

          protected boolean configured

      Has this Digester been configured yet.

    - #### entityResolver

          protected org.xml.sax.EntityResolver entityResolver

      The EntityResolver used by the SAX parser. By default it use this class

    - #### entityValidator

          protected java.util.HashMap<java.lang.String,​java.lang.String> entityValidator

      The URLs of entityValidator that have been registered, keyed by the public identifier that corresponds.

    - #### errorHandler

          protected org.xml.sax.ErrorHandler errorHandler

      The application-supplied error handler that is notified when parsing warnings, errors, or fatal errors occur.

    - #### factory

          protected javax.xml.parsers.SAXParserFactory factory

      The SAXParserFactory that is created the first time we need it.

    - #### locator

          protected org.xml.sax.Locator locator

      The Locator associated with our parser.

    - #### match

          protected java.lang.String match

      The current match pattern for nested element processing.

    - #### namespaceAware

          protected boolean namespaceAware

      Do we want a "namespace aware" parser.

    - #### namespaces

          protected java.util.HashMap<java.lang.String,​ArrayStack<java.lang.String>> namespaces

      Registered namespaces we are currently processing. The key is the namespace prefix that was declared in the document. The value is an ArrayStack of the namespace URIs this prefix has been mapped to -- the top Stack element is the most current one. (This architecture is required because documents can declare nested uses of the same prefix for different Namespace URIs).

    - #### params

          protected ArrayStack<java.lang.Object> params

      The parameters stack being utilized by CallMethodRule and CallParamRule rules.

    - #### parser

          protected javax.xml.parsers.SAXParser parser

      The SAXParser we will use to parse the input stream.

    - #### publicId

          protected java.lang.String publicId

      The public identifier of the DTD we are currently parsing under (if any).

    - #### reader

          protected org.xml.sax.XMLReader reader

      The XMLReader used to parse digester rules.

    - #### root

          protected java.lang.Object root

      The "root" element of the stack (in other words, the last object that was popped.

    - #### rules

          protected Rules rules

      The `Rules` implementation containing our collection of `Rule` instances and associated matching policy. If not established before the first rule is added, a default implementation will be provided.

    - #### stack

          protected ArrayStack<java.lang.Object> stack

      The object stack being constructed.

    - #### useContextClassLoader

          protected boolean useContextClassLoader

      Do we want to use the Context ClassLoader when loading classes for instantiating new objects. Default is `false`.

    - #### validating

          protected boolean validating

      Do we want to use a validating parser.

    - #### rulesValidation

          protected boolean rulesValidation

      Warn on missing attributes and elements.

    - #### fakeAttributes

          protected java.util.Map<java.lang.Class<?>,​java.util.List<java.lang.String>> fakeAttributes

      Fake attributes map (attributes are often used for object creation).

    - #### log

          protected Log log

      The Log to which most logging calls will be made.

    - #### saxLog

          protected Log saxLog

      The Log to which all SAX event related logging calls will be made.

    - #### code

          protected java.lang.StringBuilder code

      Generated code.

    - #### known

          protected java.util.ArrayList<java.lang.Object> known

  - ### Constructor Detail

    - #### Digester

          public Digester()

  - ### Method Detail

    - #### setPropertySource

          public static void setPropertySource​(IntrospectionUtils.PropertySource propertySource)

    - #### setPropertySource

          public static void setPropertySource​(IntrospectionUtils.PropertySource[] propertySources)

    - #### addGeneratedClass

          public static void addGeneratedClass​(java.lang.String className)

    - #### getGeneratedClasses

          public static java.lang.String[] getGeneratedClasses()

    - #### isGeneratedCodeLoaderSet

          public static boolean isGeneratedCodeLoaderSet()

    - #### setGeneratedCodeLoader

          public static void setGeneratedCodeLoader​(Digester.GeneratedCodeLoader generatedCodeLoader)

    - #### loadGeneratedClass

          public static java.lang.Object loadGeneratedClass​(java.lang.String className)

    - #### replaceSystemProperties

          public static void replaceSystemProperties()

    - #### startGeneratingCode

          public void startGeneratingCode()

    - #### endGeneratingCode

          public void endGeneratingCode()

    - #### getGeneratedCode

          public java.lang.StringBuilder getGeneratedCode()

    - #### setKnown

          public void setKnown​(java.lang.Object object)

    - #### toVariableName

          public java.lang.String toVariableName​(java.lang.Object object)

    - #### findNamespaceURI

          public java.lang.String findNamespaceURI​(java.lang.String prefix)

      Return the currently mapped namespace URI for the specified prefix, if any; otherwise return `null`. These mappings come and go dynamically as the document is parsed.
      Parameters:
        `prefix` - Prefix to look up
      Returns:
        the namespace URI

    - #### getClassLoader

          public java.lang.ClassLoader getClassLoader()

      Return the class loader to be used for instantiating application objects when required. This is determined based upon the following rules:
      - The class loader set by `setClassLoader()`, if any
      - The thread context class loader, if it exists and the `useContextClassLoader` property is set to true
      - The class loader used to load the Digester class itself.
      Returns:
        the classloader

    - #### setClassLoader

          public void setClassLoader​(java.lang.ClassLoader classLoader)

      Set the class loader to be used for instantiating application objects when required.
      Parameters:
        `classLoader` - The new class loader to use, or `null` to revert to the standard rules

    - #### getCount

          public int getCount()

      Returns:
        the current depth of the element stack.

    - #### getCurrentElementName

          public java.lang.String getCurrentElementName()

      Returns:
        the name of the XML element that is currently being processed.

    - #### getErrorHandler

          public org.xml.sax.ErrorHandler getErrorHandler()

      Returns:
        the error handler for this Digester.

    - #### setErrorHandler

          public void setErrorHandler​(org.xml.sax.ErrorHandler errorHandler)

      Set the error handler for this Digester.
      Parameters:
        `errorHandler` - The new error handler

    - #### getFactory

          public javax.xml.parsers.SAXParserFactory getFactory()
                                                        throws org.xml.sax.SAXNotRecognizedException,
                                                               org.xml.sax.SAXNotSupportedException,
                                                               javax.xml.parsers.ParserConfigurationException

      SAX parser factory method.
      Returns:
        the SAXParserFactory we will use, creating one if necessary.
      Throws:
        `javax.xml.parsers.ParserConfigurationException` - Error creating parser
        `org.xml.sax.SAXNotSupportedException` - Error creating parser
        `org.xml.sax.SAXNotRecognizedException` - Error creating parser

    - #### setFeature

          public void setFeature​(java.lang.String feature,
                                 boolean value)
                          throws javax.xml.parsers.ParserConfigurationException,
                                 org.xml.sax.SAXNotRecognizedException,
                                 org.xml.sax.SAXNotSupportedException

      Sets a flag indicating whether the requested feature is supported by the underlying implementation of `org.xml.sax.XMLReader`. See http://www.saxproject.org/apidoc/xml/sax/package-summary.html#package-description for information about the standard SAX2 feature flags. In order to be effective, this method must be called before the `getParser()` method is called for the first time, either directly or indirectly.
      Parameters:
        `feature` - Name of the feature to set the status for
        `value` - The new value for this feature
      Throws:
        `javax.xml.parsers.ParserConfigurationException` - if a parser configuration error occurs
        `org.xml.sax.SAXNotRecognizedException` - if the property name is not recognized
        `org.xml.sax.SAXNotSupportedException` - if the property name is recognized but not supported

    - #### getLogger

          public Log getLogger()

      Returns:
        the current Logger associated with this instance of the Digester

    - #### setLogger

          public void setLogger​(Log log)

      Set the current logger for this Digester.
      Parameters:
        `log` - The logger that will be used

    - #### getSAXLogger

          public Log getSAXLogger()

      Gets the logger used for logging SAX-related information. Note the output is finely grained.
      Returns:
        the SAX logger
      Since:
        1.6

    - #### setSAXLogger

          public void setSAXLogger​(Log saxLog)

      Sets the logger used for logging SAX-related information. Note the output is finely grained.
      Parameters:
        `saxLog` - Log, not null
      Since:
        1.6

    - #### getMatch

          public java.lang.String getMatch()

      Returns:
        the current rule match path

    - #### getNamespaceAware

          public boolean getNamespaceAware()

      Returns:
        the "namespace aware" flag for parsers we create.

    - #### setNamespaceAware

          public void setNamespaceAware​(boolean namespaceAware)

      Set the "namespace aware" flag for parsers we create.
      Parameters:
        `namespaceAware` - The new "namespace aware" flag

    - #### setPublicId

          public void setPublicId​(java.lang.String publicId)

      Set the public id of the current file being parse.
      Parameters:
        `publicId` - the DTD/Schema public's id.

    - #### getPublicId

          public java.lang.String getPublicId()

      Returns:
        the public identifier of the DTD we are currently parsing under, if any.

    - #### getParser

          public javax.xml.parsers.SAXParser getParser()

      Returns:
        the SAXParser we will use to parse the input stream. If there is a problem creating the parser, return `null`.

    - #### getProperty

          public java.lang.Object getProperty​(java.lang.String property)
                                       throws org.xml.sax.SAXNotRecognizedException,
                                              org.xml.sax.SAXNotSupportedException

      Return the current value of the specified property for the underlying `XMLReader` implementation. See http://www.saxproject.org/apidoc/xml/sax/package-summary.html#package-description for information about the standard SAX2 properties.
      Parameters:
        `property` - Property name to be retrieved
      Returns:
        the property value
      Throws:
        `org.xml.sax.SAXNotRecognizedException` - if the property name is not recognized
        `org.xml.sax.SAXNotSupportedException` - if the property name is recognized but not supported

    - #### getRules

          public Rules getRules()

      Return the `Rules` implementation object containing our rules collection and associated matching policy. If none has been established, a default implementation will be created and returned.
      Returns:
        the rules

    - #### setRules

          public void setRules​(Rules rules)

      Set the `Rules` implementation object containing our rules collection and associated matching policy.
      Parameters:
        `rules` - New Rules implementation

    - #### getUseContextClassLoader

          public boolean getUseContextClassLoader()

      Returns:
        the boolean as to whether the context classloader should be used.

    - #### setUseContextClassLoader

          public void setUseContextClassLoader​(boolean use)

      Determine whether to use the Context ClassLoader (the one found by calling `Thread.currentThread().getContextClassLoader()`) to resolve/load classes that are defined in various rules. If not using Context ClassLoader, then the class-loading defaults to using the calling-class' ClassLoader.
      Parameters:
        `use` - determines whether to use Context ClassLoader.

    - #### getValidating

          public boolean getValidating()

      Returns:
        the validating parser flag.

    - #### setValidating

          public void setValidating​(boolean validating)

      Set the validating parser flag. This must be called before `parse()` is called the first time.
      Parameters:
        `validating` - The new validating parser flag.

    - #### getRulesValidation

          public boolean getRulesValidation()

      Returns:
        the rules validation flag.

    - #### setRulesValidation

          public void setRulesValidation​(boolean rulesValidation)

      Set the rules validation flag. This must be called before `parse()` is called the first time.
      Parameters:
        `rulesValidation` - The new rules validation flag.

    - #### getFakeAttributes

          public java.util.Map<java.lang.Class<?>,​java.util.List<java.lang.String>> getFakeAttributes()

      Returns:
        the fake attributes list.

    - #### isFakeAttribute

          public boolean isFakeAttribute​(java.lang.Object object,
                                         java.lang.String name)

      Determine if an attribute is a fake attribute.
      Parameters:
        `object` - The object
        `name` - The attribute name
      Returns:
        `true` if this is a fake attribute

    - #### setFakeAttributes

          public void setFakeAttributes​(java.util.Map<java.lang.Class<?>,​java.util.List<java.lang.String>> fakeAttributes)

      Set the fake attributes.
      Parameters:
        `fakeAttributes` - The new fake attributes.

    - #### getXMLReader

          public org.xml.sax.XMLReader getXMLReader()
                                             throws org.xml.sax.SAXException

      Return the XMLReader to be used for parsing the input document. FIX ME: there is a bug in JAXP/XERCES that prevent the use of a parser that contains a schema with a DTD.
      Returns:
        the XML reader
      Throws:
        `org.xml.sax.SAXException` - if no XMLReader can be instantiated

    - #### characters

          public void characters​(char[] buffer,
                                 int start,
                                 int length)
                          throws org.xml.sax.SAXException

      Process notification of character data received from the body of an XML element.
      Specified by:
        `characters` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `characters` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `buffer` - The characters from the XML document
        `start` - Starting offset into the buffer
        `length` - Number of characters from the buffer
      Throws:
        `org.xml.sax.SAXException` - if a parsing error is to be reported

    - #### endDocument

          public void endDocument()
                           throws org.xml.sax.SAXException

      Process notification of the end of the document being reached.
      Specified by:
        `endDocument` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `endDocument` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException` - if a parsing error is to be reported

    - #### endElement

          public void endElement​(java.lang.String namespaceURI,
                                 java.lang.String localName,
                                 java.lang.String qName)
                          throws org.xml.sax.SAXException

      Process notification of the end of an XML element being reached.
      Specified by:
        `endElement` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `endElement` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `namespaceURI` - - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
        `localName` - - The local name (without prefix), or the empty string if Namespace processing is not being performed.
        `qName` - - The qualified XML 1.0 name (with prefix), or the empty string if qualified names are not available.
      Throws:
        `org.xml.sax.SAXException` - if a parsing error is to be reported

    - #### endPrefixMapping

          public void endPrefixMapping​(java.lang.String prefix)
                                throws org.xml.sax.SAXException

      Process notification that a namespace prefix is going out of scope.
      Specified by:
        `endPrefixMapping` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `endPrefixMapping` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `prefix` - Prefix that is going out of scope
      Throws:
        `org.xml.sax.SAXException` - if a parsing error is to be reported

    - #### ignorableWhitespace

          public void ignorableWhitespace​(char[] buffer,
                                          int start,
                                          int len)
                                   throws org.xml.sax.SAXException

      Process notification of ignorable whitespace received from the body of an XML element.
      Specified by:
        `ignorableWhitespace` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `ignorableWhitespace` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `buffer` - The characters from the XML document
        `start` - Starting offset into the buffer
        `len` - Number of characters from the buffer
      Throws:
        `org.xml.sax.SAXException` - if a parsing error is to be reported

    - #### processingInstruction

          public void processingInstruction​(java.lang.String target,
                                            java.lang.String data)
                                     throws org.xml.sax.SAXException

      Process notification of a processing instruction that was encountered.
      Specified by:
        `processingInstruction` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `processingInstruction` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `target` - The processing instruction target
        `data` - The processing instruction data (if any)
      Throws:
        `org.xml.sax.SAXException` - if a parsing error is to be reported

    - #### getDocumentLocator

          public org.xml.sax.Locator getDocumentLocator()

      Gets the document locator associated with our parser.
      Returns:
        the Locator supplied by the document parser

    - #### setDocumentLocator

          public void setDocumentLocator​(org.xml.sax.Locator locator)

      Sets the document locator associated with our parser.
      Specified by:
        `setDocumentLocator` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `setDocumentLocator` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `locator` - The new locator

    - #### skippedEntity

          public void skippedEntity​(java.lang.String name)
                             throws org.xml.sax.SAXException

      Process notification of a skipped entity.
      Specified by:
        `skippedEntity` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `skippedEntity` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `name` - Name of the skipped entity
      Throws:
        `org.xml.sax.SAXException` - if a parsing error is to be reported

    - #### startDocument

          public void startDocument()
                             throws org.xml.sax.SAXException

      Process notification of the beginning of the document being reached.
      Specified by:
        `startDocument` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `startDocument` in class `org.xml.sax.helpers.DefaultHandler`
      Throws:
        `org.xml.sax.SAXException` - if a parsing error is to be reported

    - #### startElement

          public void startElement​(java.lang.String namespaceURI,
                                   java.lang.String localName,
                                   java.lang.String qName,
                                   org.xml.sax.Attributes list)
                            throws org.xml.sax.SAXException

      Process notification of the start of an XML element being reached.
      Specified by:
        `startElement` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `startElement` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `namespaceURI` - The Namespace URI, or the empty string if the element has no Namespace URI or if Namespace processing is not being performed.
        `localName` - The local name (without prefix), or the empty string if Namespace processing is not being performed.
        `qName` - The qualified name (with prefix), or the empty string if qualified names are not available.\
        `list` - The attributes attached to the element. If there are no attributes, it shall be an empty Attributes object.
      Throws:
        `org.xml.sax.SAXException` - if a parsing error is to be reported

    - #### startPrefixMapping

          public void startPrefixMapping​(java.lang.String prefix,
                                         java.lang.String namespaceURI)
                                  throws org.xml.sax.SAXException

      Process notification that a namespace prefix is coming in to scope.
      Specified by:
        `startPrefixMapping` in interface `org.xml.sax.ContentHandler`
      Overrides:
        `startPrefixMapping` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `prefix` - Prefix that is being declared
        `namespaceURI` - Corresponding namespace URI being mapped to
      Throws:
        `org.xml.sax.SAXException` - if a parsing error is to be reported

    - #### notationDecl

          public void notationDecl​(java.lang.String name,
                                   java.lang.String publicId,
                                   java.lang.String systemId)

      Receive notification of a notation declaration event.
      Specified by:
        `notationDecl` in interface `org.xml.sax.DTDHandler`
      Overrides:
        `notationDecl` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `name` - The notation name
        `publicId` - The public identifier (if any)
        `systemId` - The system identifier (if any)

    - #### unparsedEntityDecl

          public void unparsedEntityDecl​(java.lang.String name,
                                         java.lang.String publicId,
                                         java.lang.String systemId,
                                         java.lang.String notation)

      Receive notification of an unparsed entity declaration event.
      Specified by:
        `unparsedEntityDecl` in interface `org.xml.sax.DTDHandler`
      Overrides:
        `unparsedEntityDecl` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `name` - The unparsed entity name
        `publicId` - The public identifier (if any)
        `systemId` - The system identifier (if any)
        `notation` - The name of the associated notation

    - #### setEntityResolver

          public void setEntityResolver​(org.xml.sax.EntityResolver entityResolver)

      Set the `EntityResolver` used by SAX when resolving public id and system id. This must be called before the first call to `parse()`.
      Parameters:
        `entityResolver` - a class that implement the `EntityResolver` interface.

    - #### getEntityResolver

          public org.xml.sax.EntityResolver getEntityResolver()

      Return the Entity Resolver used by the SAX parser.
      Returns:
        Return the Entity Resolver used by the SAX parser.

    - #### resolveEntity

          public org.xml.sax.InputSource resolveEntity​(java.lang.String name,
                                                       java.lang.String publicId,
                                                       java.lang.String baseURI,
                                                       java.lang.String systemId)
                                                throws org.xml.sax.SAXException,
                                                       java.io.IOException

      Specified by:
        `resolveEntity` in interface `org.xml.sax.ext.EntityResolver2`
      Overrides:
        `resolveEntity` in class `org.xml.sax.ext.DefaultHandler2`
      Throws:
        `org.xml.sax.SAXException`
        `java.io.IOException`

    - #### startDTD

          public void startDTD​(java.lang.String name,
                               java.lang.String publicId,
                               java.lang.String systemId)
                        throws org.xml.sax.SAXException

      Specified by:
        `startDTD` in interface `org.xml.sax.ext.LexicalHandler`
      Overrides:
        `startDTD` in class `org.xml.sax.ext.DefaultHandler2`
      Throws:
        `org.xml.sax.SAXException`

    - #### error

          public void error​(org.xml.sax.SAXParseException exception)
                     throws org.xml.sax.SAXException

      Forward notification of a parsing error to the application supplied error handler (if any).
      Specified by:
        `error` in interface `org.xml.sax.ErrorHandler`
      Overrides:
        `error` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `exception` - The error information
      Throws:
        `org.xml.sax.SAXException` - if a parsing exception occurs

    - #### fatalError

          public void fatalError​(org.xml.sax.SAXParseException exception)
                          throws org.xml.sax.SAXException

      Forward notification of a fatal parsing error to the application supplied error handler (if any).
      Specified by:
        `fatalError` in interface `org.xml.sax.ErrorHandler`
      Overrides:
        `fatalError` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `exception` - The fatal error information
      Throws:
        `org.xml.sax.SAXException` - if a parsing exception occurs

    - #### warning

          public void warning​(org.xml.sax.SAXParseException exception)
                       throws org.xml.sax.SAXException

      Forward notification of a parse warning to the application supplied error handler (if any).
      Specified by:
        `warning` in interface `org.xml.sax.ErrorHandler`
      Overrides:
        `warning` in class `org.xml.sax.helpers.DefaultHandler`
      Parameters:
        `exception` - The warning information
      Throws:
        `org.xml.sax.SAXException` - if a parsing exception occurs

    - #### parse

          public java.lang.Object parse​(java.io.File file)
                                 throws java.io.IOException,
                                        org.xml.sax.SAXException

      Parse the content of the specified file using this Digester. Returns the root element from the object stack (if any).
      Parameters:
        `file` - File containing the XML data to be parsed
      Returns:
        the root object
      Throws:
        `java.io.IOException` - if an input/output error occurs
        `org.xml.sax.SAXException` - if a parsing exception occurs

    - #### parse

          public java.lang.Object parse​(org.xml.sax.InputSource input)
                                 throws java.io.IOException,
                                        org.xml.sax.SAXException

      Parse the content of the specified input source using this Digester. Returns the root element from the object stack (if any).
      Parameters:
        `input` - Input source containing the XML data to be parsed
      Returns:
        the root object
      Throws:
        `java.io.IOException` - if an input/output error occurs
        `org.xml.sax.SAXException` - if a parsing exception occurs

    - #### parse

          public java.lang.Object parse​(java.io.InputStream input)
                                 throws java.io.IOException,
                                        org.xml.sax.SAXException

      Parse the content of the specified input stream using this Digester. Returns the root element from the object stack (if any).
      Parameters:
        `input` - Input stream containing the XML data to be parsed
      Returns:
        the root object
      Throws:
        `java.io.IOException` - if an input/output error occurs
        `org.xml.sax.SAXException` - if a parsing exception occurs

    - #### register

          public void register​(java.lang.String publicId,
                               java.lang.String entityURL)

      Register the specified DTD URL for the specified public identifier. This must be called before the first call to `parse()`.

      `Digester` contains an internal `EntityResolver` implementation. This maps `PUBLICID`'s to URLs (from which the resource will be loaded). A common use case for this method is to register local URLs (possibly computed at runtime by a classloader) for DTDs. This allows the performance advantage of using a local version without having to ensure every `SYSTEM` URI on every processed xml document is local. This implementation provides only basic functionality. If more sophisticated features are required, using `setEntityResolver(org.xml.sax.EntityResolver)` to set a custom resolver is recommended.

      Note: This method will have no effect when a custom `EntityResolver` has been set. (Setting a custom `EntityResolver` overrides the internal implementation.)

      Parameters:
        `publicId` - Public identifier of the DTD to be resolved
        `entityURL` - The URL to use for reading this DTD

    - #### addRule

          public void addRule​(java.lang.String pattern,
                              Rule rule)

      Register a new Rule matching the specified pattern. This method sets the `Digester` property on the rule.

      Parameters:
        `pattern` - Element matching pattern
        `rule` - Rule to be registered

    - #### addRuleSet

          public void addRuleSet​(RuleSet ruleSet)

      Register a set of Rule instances defined in a RuleSet.
      Parameters:
        `ruleSet` - The RuleSet instance to configure from

    - #### addCallMethod

          public void addCallMethod​(java.lang.String pattern,
                                    java.lang.String methodName)

      Add an "call method" rule for a method which accepts no arguments.
      Parameters:
        `pattern` - Element matching pattern
        `methodName` - Method name to be called
      See Also:
        `CallMethodRule`

    - #### addCallMethod

          public void addCallMethod​(java.lang.String pattern,
                                    java.lang.String methodName,
                                    int paramCount)

      Add an "call method" rule for the specified parameters.
      Parameters:
        `pattern` - Element matching pattern
        `methodName` - Method name to be called
        `paramCount` - Number of expected parameters (or zero for a single parameter from the body of this element)
      See Also:
        `CallMethodRule`

    - #### addCallParam

          public void addCallParam​(java.lang.String pattern,
                                   int paramIndex)

      Add a "call parameter" rule for the specified parameters.
      Parameters:
        `pattern` - Element matching pattern
        `paramIndex` - Zero-relative parameter index to set (from the body of this element)
      See Also:
        `CallParamRule`

    - #### addFactoryCreate

          public void addFactoryCreate​(java.lang.String pattern,
                                       ObjectCreationFactory creationFactory,
                                       boolean ignoreCreateExceptions)

      Add a "factory create" rule for the specified parameters.
      Parameters:
        `pattern` - Element matching pattern
        `creationFactory` - Previously instantiated ObjectCreationFactory to be utilized
        `ignoreCreateExceptions` - when `true` any exceptions thrown during object creation will be ignored.
      See Also:
        `FactoryCreateRule`

    - #### addObjectCreate

          public void addObjectCreate​(java.lang.String pattern,
                                      java.lang.String className)

      Add an "object create" rule for the specified parameters.
      Parameters:
        `pattern` - Element matching pattern
        `className` - Java class name to be created
      See Also:
        `ObjectCreateRule`

    - #### addObjectCreate

          public void addObjectCreate​(java.lang.String pattern,
                                      java.lang.String className,
                                      java.lang.String attributeName)

      Add an "object create" rule for the specified parameters.
      Parameters:
        `pattern` - Element matching pattern
        `className` - Default Java class name to be created
        `attributeName` - Attribute name that optionally overrides the default Java class name to be created
      See Also:
        `ObjectCreateRule`

    - #### addSetNext

          public void addSetNext​(java.lang.String pattern,
                                 java.lang.String methodName,
                                 java.lang.String paramType)

      Add a "set next" rule for the specified parameters.
      Parameters:
        `pattern` - Element matching pattern
        `methodName` - Method name to call on the parent element
        `paramType` - Java class name of the expected parameter type (if you wish to use a primitive type, specify the corresponding Java wrapper class instead, such as `java.lang.Boolean` for a `boolean` parameter)
      See Also:
        `SetNextRule`

    - #### addSetProperties

          public void addSetProperties​(java.lang.String pattern)

      Add a "set properties" rule for the specified parameters.
      Parameters:
        `pattern` - Element matching pattern
      See Also:
        `SetPropertiesRule`

    - #### addSetProperties

          public void addSetProperties​(java.lang.String pattern,
                                       java.lang.String[] excludes)

    - #### clear

          public void clear()

      Clear the current contents of the object stack.

      Calling this method might allow another document of the same type to be correctly parsed. However this method was not intended for this purpose. In general, a separate Digester object should be created for each document to be parsed.

    - #### reset

          public void reset()

    - #### peek

          public java.lang.Object peek()

      Return the top object on the stack without removing it. If there are no objects on the stack, return `null`.
      Returns:
        the top object

    - #### peek

          public java.lang.Object peek​(int n)

      Return the n'th object down the stack, where 0 is the top element and [getCount()-1] is the bottom element. If the specified index is out of range, return `null`.
      Parameters:
        `n` - Index of the desired element, where 0 is the top of the stack, 1 is the next element down, and so on.
      Returns:
        the specified object

    - #### pop

          public java.lang.Object pop()

      Pop the top object off of the stack, and return it. If there are no objects on the stack, return `null`.
      Returns:
        the top object

    - #### push

          public void push​(java.lang.Object object)

      Push a new object onto the top of the object stack.
      Parameters:
        `object` - The new object

    - #### getRoot

          public java.lang.Object getRoot()

      When the Digester is being used as a SAXContentHandler, this method allows you to access the root object that has been created after parsing.
      Returns:
        the root object that has been created after parsing or null if the digester has not parsed any XML yet.

    - #### configure

          protected void configure()

      Provide a hook for lazy configuration of this `Digester` instance. The default implementation does nothing, but subclasses can override as needed.

      Note This method may be called more than once.

    - #### peekParams

          public java.lang.Object peekParams()

      Return the top object on the parameters stack without removing it. If there are no objects on the stack, return `null`.

      The parameters stack is used to store `CallMethodRule` parameters. See `params`.

      Returns:
        the top object on the parameters stack

    - #### popParams

          public java.lang.Object popParams()

      Pop the top object off of the parameters stack, and return it. If there are no objects on the stack, return `null`.

      The parameters stack is used to store `CallMethodRule` parameters. See `params`.

      Returns:
        the top object on the parameters stack

    - #### pushParams

          public void pushParams​(java.lang.Object object)

      Push a new object onto the top of the parameters stack.

      The parameters stack is used to store `CallMethodRule` parameters. See `params`.

      Parameters:
        `object` - The new object

    - #### createSAXException

          public org.xml.sax.SAXException createSAXException​(java.lang.String message,
                                                             java.lang.Exception e)

      Create a SAX exception which also understands about the location in the digester file where the exception occurs
      Parameters:
        `message` - The error message
        `e` - The root cause
      Returns:
        the new exception

    - #### createSAXException

          public org.xml.sax.SAXException createSAXException​(java.lang.Exception e)

      Create a SAX exception which also understands about the location in the digester file where the exception occurs
      Parameters:
        `e` - The root cause
      Returns:
        the new exception

    - #### createSAXException

          public org.xml.sax.SAXException createSAXException​(java.lang.String message)

      Create a SAX exception which also understands about the location in the digester file where the exception occurs
      Parameters:
        `message` - The error message
      Returns:
        the new exception