Package org.apache.commons.digester3

Class Digester

  • All Implemented Interfaces:
    org.xml.sax.ContentHandler, org.xml.sax.DTDHandler, org.xml.sax.EntityResolver, org.xml.sax.ErrorHandler
    public class Digester
extends org.xml.sax.helpers.DefaultHandler

    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.

    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.

    A Digester instance should not be used for parsing more than one input document. The problem is that the Digester class has quite a few member variables whose values "evolve" as SAX events are received during a parse. When reusing the Digester instance, all these members must be reset back to their initial states before the second parse begins. The "clear()" method makes a stab at resetting these, but it is actually rather a difficult problem. If you are determined to reuse Digester instances, then at the least you should call the clear() method before each parse, and must call it if the Digester parse terminates due to an exception during a parse.

    LEGACY IMPLEMENTATION NOTE - When using the legacy XML schema support (instead of using the Schema class), 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 work with the legacy XML schema support.

    This package was inspired by the XmlMapper class that was part of Tomcat 3.0 and 3.1, but is organized somewhat differently.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.util.List<org.xml.sax.InputSource> inputSources
      List of InputSource instances created by a createInputSourceFromURL() method call.
      protected static java.lang.String W3C_XML_SCHEMA
      The schema language supported.

    • Constructor Summary

      Constructors 
      Constructor Description
      Digester()
      Construct a new Digester with default properties.
      Digester​(javax.xml.parsers.SAXParser parser)
      Construct a new Digester, allowing a SAXParser to be passed in.
      Digester​(org.xml.sax.XMLReader reader)
      Construct a new Digester, allowing an XMLReader to be passed in.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addBeanPropertySetter​(java.lang.String pattern)
      Add a "bean property setter" rule for the specified parameters.
      void addBeanPropertySetter​(java.lang.String pattern, java.lang.String propertyName)
      Add a "bean property setter" rule for the specified parameters.
      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 addCallMethod​(java.lang.String pattern, java.lang.String methodName, int paramCount, java.lang.Class<?>[] paramTypes)
      Add an "call method" rule for the specified parameters.
      void addCallMethod​(java.lang.String pattern, java.lang.String methodName, int paramCount, java.lang.String[] paramTypes)
      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 addCallParam​(java.lang.String pattern, int paramIndex, boolean fromStack)
      Add a "call parameter" rule.
      void addCallParam​(java.lang.String pattern, int paramIndex, int stackIndex)
      Add a "call parameter" rule that sets a parameter from the stack.
      void addCallParam​(java.lang.String pattern, int paramIndex, java.lang.String attributeName)
      Add a "call parameter" rule for the specified parameters.
      void addCallParamPath​(java.lang.String pattern, int paramIndex)
      Add a "call parameter" rule that sets a parameter from the current Digester matching path.
      void addFactoryCreate​(java.lang.String pattern, java.lang.Class<? extends ObjectCreationFactory<?>> clazz)
      Add a "factory create" rule for the specified parameters.
      void addFactoryCreate​(java.lang.String pattern, java.lang.Class<? extends ObjectCreationFactory<?>> clazz, boolean ignoreCreateExceptions)
      Add a "factory create" rule for the specified parameters.
      void addFactoryCreate​(java.lang.String pattern, java.lang.Class<? extends ObjectCreationFactory<?>> clazz, java.lang.String attributeName)
      Add a "factory create" rule for the specified parameters.
      void addFactoryCreate​(java.lang.String pattern, java.lang.Class<? extends ObjectCreationFactory<?>> clazz, java.lang.String attributeName, boolean ignoreCreateExceptions)
      Add a "factory create" rule for the specified parameters.
      void addFactoryCreate​(java.lang.String pattern, java.lang.String className)
      Add a "factory create" rule for the specified parameters.
      void addFactoryCreate​(java.lang.String pattern, java.lang.String className, boolean ignoreCreateExceptions)
      Add a "factory create" rule for the specified parameters.
      void addFactoryCreate​(java.lang.String pattern, java.lang.String className, java.lang.String attributeName)
      Add a "factory create" rule for the specified parameters.
      void addFactoryCreate​(java.lang.String pattern, java.lang.String className, java.lang.String attributeName, boolean ignoreCreateExceptions)
      Add a "factory create" rule for the specified parameters.
      void addFactoryCreate​(java.lang.String pattern, ObjectCreationFactory<?> creationFactory)
      Add a "factory create" rule for the specified parameters.
      void addFactoryCreate​(java.lang.String pattern, ObjectCreationFactory<?> creationFactory, boolean ignoreCreateExceptions)
      Add a "factory create" rule for the specified parameters.
      void addObjectCreate​(java.lang.String pattern, java.lang.Class<?> clazz)
      Add an "object create" rule for the specified parameters.
      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 attributeName, java.lang.Class<?> clazz)
      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 addObjectParam​(java.lang.String pattern, int paramIndex, java.lang.Object paramObj)
      Add a "call parameter" rule that sets a parameter from a caller-provided object.
      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 addSetNestedProperties​(java.lang.String pattern)
      Adds an SetNestedPropertiesRule.
      void addSetNestedProperties​(java.lang.String pattern, java.lang.String[] elementNames, java.lang.String[] propertyNames)
      Adds an SetNestedPropertiesRule.
      void addSetNestedProperties​(java.lang.String pattern, java.lang.String elementName, java.lang.String propertyName)
      Adds an SetNestedPropertiesRule.
      void addSetNext​(java.lang.String pattern, java.lang.String methodName)
      Add a "set next" rule for the specified parameters.
      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[] attributeNames, java.lang.String[] propertyNames)
      Add a "set properties" rule with overridden parameters.
      void addSetProperties​(java.lang.String pattern, java.lang.String attributeName, java.lang.String propertyName)
      Add a "set properties" rule with a single overridden parameter.
      void addSetProperty​(java.lang.String pattern, java.lang.String name, java.lang.String value)
      Add a "set property" rule for the specified parameters.
      void addSetRoot​(java.lang.String pattern, java.lang.String methodName)
      Add SetRootRule with the specified parameters.
      void addSetRoot​(java.lang.String pattern, java.lang.String methodName, java.lang.String paramType)
      Add SetRootRule with the specified parameters.
      void addSetTop​(java.lang.String pattern, java.lang.String methodName)
      Add a "set top" rule for the specified parameters.
      void addSetTop​(java.lang.String pattern, java.lang.String methodName, java.lang.String paramType)
      Add a "set top" rule for the specified parameters.
      <T> java.util.concurrent.Future<T> asyncParse​(java.io.File file)
      Creates a Callable instance that parse the content of the specified reader using this Digester.
      <T> java.util.concurrent.Future<T> asyncParse​(java.io.InputStream input)
      Creates a Callable instance that parse the content of the specified reader using this Digester.
      <T> java.util.concurrent.Future<T> asyncParse​(java.io.Reader reader)
      Creates a Callable instance that parse the content of the specified reader using this Digester.
      <T> java.util.concurrent.Future<T> asyncParse​(java.lang.String uri)
      Creates a Callable instance that parse the content of the specified reader using this Digester.
      <T> java.util.concurrent.Future<T> asyncParse​(java.net.URL url)
      Creates a Callable instance that parse the content of the specified reader using this Digester.
      <T> java.util.concurrent.Future<T> asyncParse​(org.xml.sax.InputSource input)
      Creates a Callable instance that parse the content of the specified reader using this Digester.
      void characters​(char[] buffer, int start, int length)
      protected void cleanup()
      Clean up allocated resources after parsing is complete.
      void clear()
      Clear the current contents of the default object stack, the param stack, all named stacks, and other internal variables.
      protected void configure()
      Provide a hook for lazy configuration of this Digester instance.
      org.xml.sax.InputSource createInputSourceFromURL​(java.lang.String url)
      Convenience method that creates an InputSource from the string version of a URL.
      org.xml.sax.InputSource createInputSourceFromURL​(java.net.URL url)
      Given a URL, return an InputSource that reads from that URL.
      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()
      void endElement​(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName)
      void endPrefixMapping​(java.lang.String prefix)
      void error​(org.xml.sax.SAXParseException exception)
      void fatalError​(org.xml.sax.SAXParseException exception)
      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()
      Return the current depth of the element stack.
      java.lang.String getCurrentElementName()
      Return the name of the XML element that is currently being processed.
      java.util.Map<java.lang.String,​java.lang.String> getCurrentNamespaces()
      Get the most current namespaces for all prefixes.
      org.xml.sax.ContentHandler getCustomContentHandler()
      returns the custom SAX ContentHandler where events are redirected.
      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()
      Return the error handler for this Digester.
      java.util.concurrent.ExecutorService getExecutorService()
      Returns the executor service used to run asynchronous parse method.
      javax.xml.parsers.SAXParserFactory getFactory()
      Return the SAXParserFactory we will use, creating one if necessary.
      boolean getFeature​(java.lang.String feature)
      Returns a flag indicating whether the requested feature is supported by the underlying implementation of org.xml.sax.XMLReader.
      org.apache.commons.logging.Log getLogger()
      Return the current Logger associated with this instance of the Digester
      java.lang.String getMatch()
      Return the current rule match path
      java.util.Stack<java.util.List<Rule>> getMatches()
      Return a Stack whose elements are List objects, each containing a list of Rule objects as returned from Rules.getMatch().
      boolean getNamespaceAware()
      Return the "namespace aware" flag for parsers we create.
      javax.xml.parsers.SAXParser getParser()
      Return the SAXParser we will use to parse the input stream.
      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()
      Return the public identifier of the DTD we are currently parsing under, if any.
      <T> T getRoot()
      Returns the root element of the tree of objects created as a result of applying the rule objects to the input XML.
      java.lang.String getRuleNamespaceURI()
      Return the namespace URI that will be applied to all subsequently added Rule objects.
      Rules getRules()
      Return the Rules implementation object containing our rules collection and associated matching policy.
      org.apache.commons.logging.Log getSAXLogger()
      Gets the logger used for logging SAX-related information.
      StackAction getStackAction()
      Return the callback object which is invoked whenever an object is pushed onto a digester object stack, or popped off one.
      Substitutor getSubstitutor()
      Gets the Substitutor used to convert attributes and body text.
      boolean getUseContextClassLoader()
      Return the boolean as to whether the context ClassLoader should be used.
      boolean getValidating()
      Return the validating parser flag.
      boolean getXIncludeAware()
      Return the XInclude-aware flag for parsers we create.
      org.xml.sax.XMLReader getXMLReader()
      Return the XMLReader to be used for parsing the input document.
      javax.xml.validation.Schema getXMLSchema()
      Return the XML Schema used when parsing.
      void ignorableWhitespace​(char[] buffer, int start, int len)
      protected void initialize()
      Provides a hook for lazy initialization of this Digester instance.
      boolean isConfigured()
      Checks the Digester instance has been configured.
      boolean isEmpty​(java.lang.String stackName)
      Is the stack with the given name empty?
      void notationDecl​(java.lang.String name, java.lang.String publicId, java.lang.String systemId)
      <T> T parse​(java.io.File file)
      Parse the content of the specified file using this Digester.
      <T> T parse​(java.io.InputStream input)
      Parse the content of the specified input stream using this Digester.
      <T> T parse​(java.io.Reader reader)
      Parse the content of the specified reader using this Digester.
      <T> T parse​(java.lang.String uri)
      Parse the content of the specified URI using this Digester.
      <T> T parse​(java.net.URL url)
      Parse the content of the specified URL using this Digester.
      <T> T parse​(org.xml.sax.InputSource input)
      Parse the content of the specified input source using this Digester.
      <T> T peek()
      Return the top object on the stack without removing it.
      <T> T peek​(int n)
      Return the n'th object down the stack, where 0 is the top element and [getCount()-1] is the bottom element.
      <T> T peek​(java.lang.String stackName)
      Gets the top object from the stack with the given name.
      <T> T peek​(java.lang.String stackName, int n)
      Gets the top object from the stack with the given name.
      java.lang.Object[] peekParams()
      Return the top object on the parameters stack without removing it.
      java.lang.Object[] peekParams​(int n)
      Return the n'th object down the parameters stack, where 0 is the top element and [getCount()-1] is the bottom element.
      <T> T pop()
      Pop the top object off of the stack, and return it.
      <T> T pop​(java.lang.String stackName)
      Pops (gets and removes) the top object from the stack with the given name.
      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)
      <T> void push​(java.lang.String stackName, T value)
      Pushes the given object onto the stack with the given name.
      <T> void push​(T 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)
      Convenience method that registers the string version of an entity URL instead of a URL version.
      void register​(java.lang.String publicId, java.net.URL entityURL)
      Register the specified DTD URL for the specified public identifier.
      void registerAll​(java.util.Map<java.lang.String,​java.net.URL> entityValidator)
      Convenience method that registers DTD URLs for the specified public identifiers.
      void resetRoot()
      This method allows the "root" variable to be reset to null.
      org.xml.sax.InputSource resolveEntity​(java.lang.String publicId, java.lang.String systemId)
      void setClassLoader​(java.lang.ClassLoader classLoader)
      Set the class loader to be used for instantiating application objects when required.
      void setCustomContentHandler​(org.xml.sax.ContentHandler handler)
      Redirects (or cancels redirecting) of SAX ContentHandler events to an external object.
      void setDocumentLocator​(org.xml.sax.Locator locator)
      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 setExecutorService​(java.util.concurrent.ExecutorService executorService)
      Sets the executor service to run asynchronous parse method.
      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.
      void setLogger​(org.apache.commons.logging.Log log)
      Set the current logger for this Digester.
      void setNamespaceAware​(boolean namespaceAware)
      Set the "namespace aware" flag for parsers we create.
      void setProperty​(java.lang.String property, java.lang.Object value)
      Set the current value of the specified property for the underlying XMLReader implementation.
      void setPublicId​(java.lang.String publicId)
      Set the public id of the current file being parse.
      void setRuleNamespaceURI​(java.lang.String ruleNamespaceURI)
      Set the namespace URI that will be applied to all subsequently added Rule objects.
      void setRules​(Rules rules)
      Set the Rules implementation object containing our rules collection and associated matching policy.
      void setSAXLogger​(org.apache.commons.logging.Log saxLog)
      Sets the logger used for logging SAX-related information.
      void setStackAction​(StackAction stackAction)
      Define a callback object which is invoked whenever an object is pushed onto a digester object stack, or popped off one.
      void setSubstitutor​(Substitutor substitutor)
      Sets the Substitutor to be used to convert attributes and body text.
      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 setXIncludeAware​(boolean xincludeAware)
      Set the XInclude-aware flag for parsers we create.
      void setXMLSchema​(javax.xml.validation.Schema schema)
      Set the XML Schema to be used when parsing.
      void skippedEntity​(java.lang.String name)
      void startDocument()
      void startElement​(java.lang.String namespaceURI, java.lang.String localName, java.lang.String qName, org.xml.sax.Attributes list)
      void startPrefixMapping​(java.lang.String prefix, java.lang.String namespaceURI)
      void unparsedEntityDecl​(java.lang.String name, java.lang.String publicId, java.lang.String systemId, java.lang.String notation)
      void warning​(org.xml.sax.SAXParseException exception)

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • inputSources

        protected java.util.List<org.xml.sax.InputSource> inputSources

        List of InputSource instances created by a createInputSourceFromURL() method call. These represent open input streams that need to be closed to avoid resource leaks, as well as potentially locked JAR files on Windows.

    • Constructor Detail

      • Digester

        public Digester()
        Construct a new Digester with default properties.

      • Digester

        public Digester​(javax.xml.parsers.SAXParser parser)
        Construct a new Digester, allowing a SAXParser to be passed in. This allows Digester to be used in environments which are unfriendly to JAXP1.1 (such as WebLogic 6.0). This may help in places where you are able to load JAXP 1.1 classes yourself.
        Parameters:
        parser - The SAXParser used to parse XML streams

      • Digester

        public Digester​(org.xml.sax.XMLReader reader)
        Construct a new Digester, allowing an XMLReader to be passed in. This allows Digester to be used in environments which are unfriendly to JAXP1.1 (such as WebLogic 6.0). Note that if you use this option you have to configure namespace and validation support yourself, as these properties only affect the SAXParser and emtpy constructor.
        Parameters:
        reader - The XMLReader used to parse XML streams

    • Method Detail

      • 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 currently mapped namespace URI for the specified prefix

      • 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 class loader to be used for instantiating application objects.

      • 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()
        Return the current depth of the element stack.
        Returns:
        the current depth of the element stack.

      • getCurrentElementName

        public java.lang.String getCurrentElementName()
        Return the name of the XML element that is currently being processed.
        Returns:
        the name of the XML element that is currently being processed.

      • getErrorHandler

        public org.xml.sax.ErrorHandler getErrorHandler()
        Return the error handler for this Digester.
        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()
        Return the SAXParserFactory we will use, creating one if necessary.
        Returns:
        the SAXParserFactory we will use, creating one if necessary.

      • getFeature

        public boolean getFeature​(java.lang.String feature)
                   throws javax.xml.parsers.ParserConfigurationException,
                          org.xml.sax.SAXNotRecognizedException,
                          org.xml.sax.SAXNotSupportedException
        Returns a flag indicating whether the requested feature is supported by the underlying implementation of org.xml.sax.XMLReader. See the saxproject website for information about the standard SAX2 feature flags.
        Parameters:
        feature - Name of the feature to inquire about
        Returns:
        true, if the requested feature is supported by the underlying implementation of org.xml.sax.XMLReader, false otherwise
        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

      • 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 the saxproject website 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 org.apache.commons.logging.Log getLogger()
        Return the current Logger associated with this instance of the Digester
        Returns:
        the current Logger associated with this instance of the Digester

      • setLogger

        public void setLogger​(org.apache.commons.logging.Log log)
        Set the current logger for this Digester.
        Parameters:
        log - the current logger for this Digester.

      • getSAXLogger

        public org.apache.commons.logging.Log getSAXLogger()
        Gets the logger used for logging SAX-related information. Note the output is finely grained.
        Returns:
        the logger used for logging SAX-related information
        Since:
        1.6

      • setSAXLogger

        public void setSAXLogger​(org.apache.commons.logging.Log saxLog)
        Sets the logger used for logging SAX-related information. Note the output is finely grained.
        Parameters:
        saxLog - the logger used for logging SAX-related information, not null
        Since:
        1.6

      • getMatch

        public java.lang.String getMatch()
        Return the current rule match path
        Returns:
        the current rule match path

      • getMatches

        public java.util.Stack<java.util.List<Rule>> getMatches()
        Return a Stack whose elements are List objects, each containing a list of Rule objects as returned from Rules.getMatch().
        Returns:
        a Stack whose elements are List objects, each containing a list of Rule objects as returned from Rules.getMatch().
        Since:
        3.0

      • getNamespaceAware

        public boolean getNamespaceAware()
        Return the "namespace aware" flag for parsers we create.
        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

      • getXIncludeAware

        public boolean getXIncludeAware()
        Return the XInclude-aware flag for parsers we create. XInclude functionality additionally requires namespace-awareness.
        Returns:
        The XInclude-aware flag
        Since:
        2.0
        See Also:
        getNamespaceAware()

      • setXIncludeAware

        public void setXIncludeAware​(boolean xincludeAware)
        Set the XInclude-aware flag for parsers we create. This additionally requires namespace-awareness.
        Parameters:
        xincludeAware - The new XInclude-aware flag
        Since:
        2.0
        See Also:
        setNamespaceAware(boolean)

      • 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()
        Return the public identifier of the DTD we are currently parsing under, if any.
        Returns:
        the public identifier of the DTD we are currently parsing under, if any.

      • getRuleNamespaceURI

        public java.lang.String getRuleNamespaceURI()
        Return the namespace URI that will be applied to all subsequently added Rule objects.
        Returns:
        the namespace URI that will be applied to all subsequently added Rule objects.

      • setRuleNamespaceURI

        public void setRuleNamespaceURI​(java.lang.String ruleNamespaceURI)
        Set the namespace URI that will be applied to all subsequently added Rule objects.
        Parameters:
        ruleNamespaceURI - Namespace URI that must match on all subsequently added rules, or null for matching regardless of the current namespace URI

      • getParser

        public javax.xml.parsers.SAXParser getParser()
        Return the SAXParser we will use to parse the input stream. If there is a problem creating the parser, return null.
        Returns:
        the SAXParser we will use to parse the input stream

      • 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 the saxproject website for information about the standard SAX2 properties.
        Parameters:
        property - Property name to be retrieved
        Returns:
        the current value of the specified property for the underlying XMLReader implementation.
        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

      • setProperty

        public void setProperty​(java.lang.String property,
                        java.lang.Object value)
                 throws org.xml.sax.SAXNotRecognizedException,
                        org.xml.sax.SAXNotSupportedException
        Set the current value of the specified property for the underlying XMLReader implementation. See the saxproject website for information about the standard SAX2 properties.
        Parameters:
        property - Property name to be set
        value - Property value to be set
        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 implementation object.

      • setRules

        public void setRules​(Rules rules)
        Set the Rules implementation object containing our rules collection and associated matching policy.
        Parameters:
        rules - New Rules implementation

      • getXMLSchema

        public javax.xml.validation.Schema getXMLSchema()
        Return the XML Schema used when parsing.
        Returns:
        The Schema instance in use.
        Since:
        2.0

      • setXMLSchema

        public void setXMLSchema​(javax.xml.validation.Schema schema)
        Set the XML Schema to be used when parsing.
        Parameters:
        schema - The Schema instance to use.
        Since:
        2.0

      • getUseContextClassLoader

        public boolean getUseContextClassLoader()
        Return the boolean as to whether the context ClassLoader should be used.
        Returns:
        true, if the context ClassLoader should be used, false otherwise.

      • 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()
        Return the validating parser flag.
        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.

      • getXMLReader

        public org.xml.sax.XMLReader getXMLReader()
                                   throws org.xml.sax.SAXException
        Return the XMLReader to be used for parsing the input document. FIXME: there is a bug in JAXP/XERCES that prevent the use of a parser that contains a schema with a DTD.
        Returns:
        the XMLReader to be used for parsing the input document.
        Throws:
        org.xml.sax.SAXException - if no XMLReader can be instantiated

      • getSubstitutor

        public Substitutor getSubstitutor()
        Gets the Substitutor used to convert attributes and body text.
        Returns:
        the Substitutor used to convert attributes and body text, null if not substitutions are to be performed.

      • setSubstitutor

        public void setSubstitutor​(Substitutor substitutor)
        Sets the Substitutor to be used to convert attributes and body text.
        Parameters:
        substitutor - the Substitutor to be used to convert attributes and body text or null if not substitution of these values is to be performed.

      • setCustomContentHandler

        public void setCustomContentHandler​(org.xml.sax.ContentHandler handler)
        Redirects (or cancels redirecting) of SAX ContentHandler events to an external object.

        When this object's customContentHandler is non-null, any SAX events received from the parser will simply be passed on to the specified object instead of this object handling them. This allows Rule classes to take control of the SAX event stream for a while in order to do custom processing. Such a rule should save the old value before setting a new one, and restore the old value in order to resume normal digester processing.

        An example of a Rule which needs this feature is NodeCreateRule.

        Note that saving the old value is probably not needed as it should always be null; a custom rule that wants to take control could only have been called when there was no custom content handler. But it seems cleaner to properly save/restore the value and maybe some day this will come in useful.

        Note also that this is not quite equivalent to 

         digester.getXMLReader().setContentHandler( handler )
        for these reasons:
        • Some xml parsers don't like having setContentHandler called after parsing has started. The Aelfred parser is one example.
        • Directing the events via the Digester object potentially allows us to log information about those SAX events at the digester level.
        Parameters:
        handler - the custom SAX ContentHandler where events are redirected.
        Since:
        1.7

      • setStackAction

        public void setStackAction​(StackAction stackAction)
        Define a callback object which is invoked whenever an object is pushed onto a digester object stack, or popped off one.
        Parameters:
        stackAction - the callback object which is invoked whenever an object is pushed onto a digester object stack, or popped off one.
        Since:
        1.8

      • getStackAction

        public StackAction getStackAction()
        Return the callback object which is invoked whenever an object is pushed onto a digester object stack, or popped off one.
        Returns:
        the callback object which is invoked whenever an object is pushed onto a digester object stack, or popped off one.
        Since:
        1.8
        See Also:
        setStackAction(StackAction)

      • getCurrentNamespaces

        public java.util.Map<java.lang.String,​java.lang.String> getCurrentNamespaces()
        Get the most current namespaces for all prefixes.
        Returns:
        Map A map with namespace prefixes as keys and most current namespace URIs for the corresponding prefixes as values
        Since:
        1.8

      • getExecutorService

        public java.util.concurrent.ExecutorService getExecutorService()
        Returns the executor service used to run asynchronous parse method.
        Returns:
        the executor service used to run asynchronous parse method
        Since:
        3.1

      • setExecutorService

        public void setExecutorService​(java.util.concurrent.ExecutorService executorService)
        Sets the executor service to run asynchronous parse method.
        Parameters:
        executorService - the executor service to run asynchronous parse method
        Since:
        3.1

      • characters

        public void characters​(char[] buffer,
                       int start,
                       int length)
                throws org.xml.sax.SAXException
        Specified by:
        characters in interface org.xml.sax.ContentHandler
        Overrides:
        characters in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException

      • endDocument

        public void endDocument()
                 throws org.xml.sax.SAXException
        Specified by:
        endDocument in interface org.xml.sax.ContentHandler
        Overrides:
        endDocument in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException

      • endElement

        public void endElement​(java.lang.String namespaceURI,
                       java.lang.String localName,
                       java.lang.String qName)
                throws org.xml.sax.SAXException
        Specified by:
        endElement in interface org.xml.sax.ContentHandler
        Overrides:
        endElement in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException

      • endPrefixMapping

        public void endPrefixMapping​(java.lang.String prefix)
                      throws org.xml.sax.SAXException
        Specified by:
        endPrefixMapping in interface org.xml.sax.ContentHandler
        Overrides:
        endPrefixMapping in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException

      • ignorableWhitespace

        public void ignorableWhitespace​(char[] buffer,
                                int start,
                                int len)
                         throws org.xml.sax.SAXException
        Specified by:
        ignorableWhitespace in interface org.xml.sax.ContentHandler
        Overrides:
        ignorableWhitespace in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException

      • processingInstruction

        public void processingInstruction​(java.lang.String target,
                                  java.lang.String data)
                           throws org.xml.sax.SAXException
        Specified by:
        processingInstruction in interface org.xml.sax.ContentHandler
        Overrides:
        processingInstruction in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException

      • 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)
        Specified by:
        setDocumentLocator in interface org.xml.sax.ContentHandler
        Overrides:
        setDocumentLocator in class org.xml.sax.helpers.DefaultHandler

      • skippedEntity

        public void skippedEntity​(java.lang.String name)
                   throws org.xml.sax.SAXException
        Specified by:
        skippedEntity in interface org.xml.sax.ContentHandler
        Overrides:
        skippedEntity in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException

      • startDocument

        public void startDocument()
                   throws org.xml.sax.SAXException
        Specified by:
        startDocument in interface org.xml.sax.ContentHandler
        Overrides:
        startDocument in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException

      • 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
        Specified by:
        startElement in interface org.xml.sax.ContentHandler
        Overrides:
        startElement in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException

      • startPrefixMapping

        public void startPrefixMapping​(java.lang.String prefix,
                               java.lang.String namespaceURI)
                        throws org.xml.sax.SAXException
        Specified by:
        startPrefixMapping in interface org.xml.sax.ContentHandler
        Overrides:
        startPrefixMapping in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException

      • notationDecl

        public void notationDecl​(java.lang.String name,
                         java.lang.String publicId,
                         java.lang.String systemId)
        Specified by:
        notationDecl in interface org.xml.sax.DTDHandler
        Overrides:
        notationDecl in class org.xml.sax.helpers.DefaultHandler

      • unparsedEntityDecl

        public void unparsedEntityDecl​(java.lang.String name,
                               java.lang.String publicId,
                               java.lang.String systemId,
                               java.lang.String notation)
        Specified by:
        unparsedEntityDecl in interface org.xml.sax.DTDHandler
        Overrides:
        unparsedEntityDecl in class org.xml.sax.helpers.DefaultHandler

      • 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:
        the Entity Resolver used by the SAX parser.

      • resolveEntity

        public org.xml.sax.InputSource resolveEntity​(java.lang.String publicId,
                                             java.lang.String systemId)
                                      throws org.xml.sax.SAXException
        Specified by:
        resolveEntity in interface org.xml.sax.EntityResolver
        Overrides:
        resolveEntity in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException

      • error

        public void error​(org.xml.sax.SAXParseException exception)
           throws org.xml.sax.SAXException
        Specified by:
        error in interface org.xml.sax.ErrorHandler
        Overrides:
        error in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException

      • fatalError

        public void fatalError​(org.xml.sax.SAXParseException exception)
                throws org.xml.sax.SAXException
        Specified by:
        fatalError in interface org.xml.sax.ErrorHandler
        Overrides:
        fatalError in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException

      • warning

        public void warning​(org.xml.sax.SAXParseException exception)
             throws org.xml.sax.SAXException
        Specified by:
        warning in interface org.xml.sax.ErrorHandler
        Overrides:
        warning in class org.xml.sax.helpers.DefaultHandler
        Throws:
        org.xml.sax.SAXException

      • parse

        public <T> T 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).
        Type Parameters:
        T - the type used to auto-cast the returned object to the assigned variable type
        Parameters:
        file - File containing the XML data to be parsed
        Returns:
        the root element from the object stack (if any)
        Throws:
        java.io.IOException - if an input/output error occurs
        org.xml.sax.SAXException - if a parsing exception occurs

      • asyncParse

        public <T> java.util.concurrent.Future<T> asyncParse​(java.io.File file)
        Creates a Callable instance that parse the content of the specified reader using this Digester.
        Type Parameters:
        T - The result type returned by the returned Future's get method
        Parameters:
        file - File containing the XML data to be parsed
        Returns:
        a Future that can be used to track when the parse has been fully processed.
        Since:
        3.1
        See Also:
        parse(File)

      • parse

        public <T> T 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).
        Type Parameters:
        T - the type used to auto-cast the returned object to the assigned variable type
        Parameters:
        input - Input source containing the XML data to be parsed
        Returns:
        the root element from the object stack (if any)
        Throws:
        java.io.IOException - if an input/output error occurs
        org.xml.sax.SAXException - if a parsing exception occurs

      • asyncParse

        public <T> java.util.concurrent.Future<T> asyncParse​(org.xml.sax.InputSource input)
        Creates a Callable instance that parse the content of the specified reader using this Digester.
        Type Parameters:
        T - The result type returned by the returned Future's get method
        Parameters:
        input - Input source containing the XML data to be parsed
        Returns:
        a Future that can be used to track when the parse has been fully processed.
        Since:
        3.1
        See Also:
        parse(InputSource)

      • parse

        public <T> T 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).
        Type Parameters:
        T - the type used to auto-cast the returned object to the assigned variable type
        Parameters:
        input - Input stream containing the XML data to be parsed
        Returns:
        the root element from the object stack (if any)
        Throws:
        java.io.IOException - if an input/output error occurs
        org.xml.sax.SAXException - if a parsing exception occurs

      • asyncParse

        public <T> java.util.concurrent.Future<T> asyncParse​(java.io.InputStream input)
        Creates a Callable instance that parse the content of the specified reader using this Digester.
        Type Parameters:
        T - The result type returned by the returned Future's get method
        Parameters:
        input - Input stream containing the XML data to be parsed
        Returns:
        a Future that can be used to track when the parse has been fully processed.
        Since:
        3.1
        See Also:
        parse(InputStream)

      • parse

        public <T> T parse​(java.io.Reader reader)
            throws java.io.IOException,
                   org.xml.sax.SAXException
        Parse the content of the specified reader using this Digester. Returns the root element from the object stack (if any).
        Type Parameters:
        T - the type used to auto-cast the returned object to the assigned variable type
        Parameters:
        reader - Reader containing the XML data to be parsed
        Returns:
        the root element from the object stack (if any)
        Throws:
        java.io.IOException - if an input/output error occurs
        org.xml.sax.SAXException - if a parsing exception occurs

      • asyncParse

        public <T> java.util.concurrent.Future<T> asyncParse​(java.io.Reader reader)
        Creates a Callable instance that parse the content of the specified reader using this Digester.
        Type Parameters:
        T - The result type returned by the returned Future's get method
        Parameters:
        reader - Reader containing the XML data to be parsed
        Returns:
        a Future that can be used to track when the parse has been fully processed.
        Since:
        3.1
        See Also:
        parse(Reader)

      • parse

        public <T> T parse​(java.lang.String uri)
            throws java.io.IOException,
                   org.xml.sax.SAXException
        Parse the content of the specified URI using this Digester. Returns the root element from the object stack (if any).
        Type Parameters:
        T - the type used to auto-cast the returned object to the assigned variable type
        Parameters:
        uri - URI containing the XML data to be parsed
        Returns:
        the root element from the object stack (if any)
        Throws:
        java.io.IOException - if an input/output error occurs
        org.xml.sax.SAXException - if a parsing exception occurs

      • asyncParse

        public <T> java.util.concurrent.Future<T> asyncParse​(java.lang.String uri)
        Creates a Callable instance that parse the content of the specified reader using this Digester.
        Type Parameters:
        T - The result type returned by the returned Future's get method
        Parameters:
        uri - URI containing the XML data to be parsed
        Returns:
        a Future that can be used to track when the parse has been fully processed.
        Since:
        3.1
        See Also:
        parse(String)

      • parse

        public <T> T parse​(java.net.URL url)
            throws java.io.IOException,
                   org.xml.sax.SAXException
        Parse the content of the specified URL using this Digester. Returns the root element from the object stack (if any).
        Type Parameters:
        T - the type used to auto-cast the returned object to the assigned variable type
        Parameters:
        url - URL containing the XML data to be parsed
        Returns:
        the root element from the object stack (if any)
        Throws:
        java.io.IOException - if an input/output error occurs
        org.xml.sax.SAXException - if a parsing exception occurs
        Since:
        1.8

      • asyncParse

        public <T> java.util.concurrent.Future<T> asyncParse​(java.net.URL url)
        Creates a Callable instance that parse the content of the specified reader using this Digester.
        Type Parameters:
        T - The result type returned by the returned Future's get method
        Parameters:
        url - URL containing the XML data to be parsed
        Returns:
        a Future that can be used to track when the parse has been fully processed.
        Since:
        3.1
        See Also:
        parse(URL)

      • register

        public void register​(java.lang.String publicId,
                     java.net.URL 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
        Since:
        1.8

      • register

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

        Convenience method that registers the string version of an entity URL instead of a URL version.

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

      • registerAll

        public void registerAll​(java.util.Map<java.lang.String,​java.net.URL> entityValidator)
        Convenience method that registers DTD URLs for the specified public identifiers.
        Parameters:
        entityValidator - The URLs of entityValidator that have been registered, keyed by the public identifier that corresponds.
        Since:
        3.0

      • createInputSourceFromURL

        public org.xml.sax.InputSource createInputSourceFromURL​(java.net.URL url)
                                                 throws java.io.IOException
        Given a URL, return an InputSource that reads from that URL.

        Ideally this function would not be needed and code could just use new InputSource(entityURL). Unfortunately it appears that when the entityURL points to a file within a jar archive a caching mechanism inside the InputSource implementation causes a file-handle to the jar file to remain open. On Windows systems this then causes the jar archive file to be locked on disk ("in use") which makes it impossible to delete the jar file - and that really stuffs up "undeploy" in webapps in particular.

        In JDK1.4 and later, Apache XercesJ is used as the xml parser. The InputSource object provided is converted into an XMLInputSource, and eventually passed to an instance of XMLDocumentScannerImpl to specify the source data to be converted into tokens for the rest of the XMLReader code to handle. XMLDocumentScannerImpl calls fEntityManager.startDocumentEntity(source), where fEntityManager is declared in ancestor class XMLScanner to be an XMLEntityManager. In that class, if the input source stream is null, then: 

         URL location = new URL( expandedSystemId );
 URLConnection connect = location.openConnection();
 if ( connect instanceof HttpURLConnection )
 {
     setHttpProperties( connect, xmlInputSource );
 }
 stream = connect.getInputStream();
        This method pretty much duplicates the standard behaviour, except that it calls URLConnection.setUseCaches(false) before opening the connection.
        Parameters:
        url - The URL has to be read
        Returns:
        The InputSource that reads from the input URL
        Throws:
        java.io.IOException - if any error occurs while reading the input URL
        Since:
        1.8

      • createInputSourceFromURL

        public org.xml.sax.InputSource createInputSourceFromURL​(java.lang.String url)
                                                 throws java.io.IOException

        Convenience method that creates an InputSource from the string version of a URL.

        Parameters:
        url - URL for which to create an InputSource
        Returns:
        The InputSource that reads from the input URL
        Throws:
        java.io.IOException - if any error occurs while reading the input URL
        Since:
        1.8

      • 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

      • addBeanPropertySetter

        public void addBeanPropertySetter​(java.lang.String pattern)
        Add a "bean property setter" rule for the specified parameters.
        Parameters:
        pattern - Element matching pattern
        See Also:
        BeanPropertySetterRule

      • addBeanPropertySetter

        public void addBeanPropertySetter​(java.lang.String pattern,
                                  java.lang.String propertyName)
        Add a "bean property setter" rule for the specified parameters.
        Parameters:
        pattern - Element matching pattern
        propertyName - Name of property to set
        See Also:
        BeanPropertySetterRule

      • 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

      • addCallMethod

        public void addCallMethod​(java.lang.String pattern,
                          java.lang.String methodName,
                          int paramCount,
                          java.lang.String[] paramTypes)
        Add an "call method" rule for the specified parameters. If paramCount is set to zero the rule will use the body of the matched element as the single argument of the method, unless paramTypes is null or empty, in this case the rule will call the specified method with no arguments.
        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)
        paramTypes - Set of Java class names for the types of the expected parameters (if you wish to use a primitive type, specify the corresonding Java wrapper class instead, such as java.lang.Boolean for a boolean parameter)
        See Also:
        CallMethodRule

      • addCallMethod

        public void addCallMethod​(java.lang.String pattern,
                          java.lang.String methodName,
                          int paramCount,
                          java.lang.Class<?>[] paramTypes)
        Add an "call method" rule for the specified parameters. If paramCount is set to zero the rule will use the body of the matched element as the single argument of the method, unless paramTypes is null or empty, in this case the rule will call the specified method with no arguments.
        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)
        paramTypes - The Java class names of the arguments (if you wish to use a primitive type, specify the corresonding Java wrapper class instead, such as java.lang.Boolean for a boolean parameter)
        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

      • addCallParam

        public void addCallParam​(java.lang.String pattern,
                         int paramIndex,
                         java.lang.String attributeName)
        Add a "call parameter" rule for the specified parameters.
        Parameters:
        pattern - Element matching pattern
        paramIndex - Zero-relative parameter index to set (from the specified attribute)
        attributeName - Attribute whose value is used as the parameter value
        See Also:
        CallParamRule

      • addCallParam

        public void addCallParam​(java.lang.String pattern,
                         int paramIndex,
                         boolean fromStack)
        Add a "call parameter" rule. This will either take a parameter from the stack or from the current element body text.
        Parameters:
        pattern - Element matching pattern
        paramIndex - The zero-relative parameter number
        fromStack - Should the call parameter be taken from the top of the stack?
        See Also:
        CallParamRule

      • addCallParam

        public void addCallParam​(java.lang.String pattern,
                         int paramIndex,
                         int stackIndex)
        Add a "call parameter" rule that sets a parameter from the stack. This takes a parameter from the given position on the stack.
        Parameters:
        pattern - Element matching pattern
        paramIndex - The zero-relative parameter number
        stackIndex - set the call parameter to the stackIndex'th object down the stack, where 0 is the top of the stack, 1 the next element down and so on
        See Also:
        CallMethodRule

      • addCallParamPath

        public void addCallParamPath​(java.lang.String pattern,
                             int paramIndex)
        Add a "call parameter" rule that sets a parameter from the current Digester matching path. This is sometimes useful when using rules that support wildcards.
        Parameters:
        pattern - the pattern that this rule should match
        paramIndex - The zero-relative parameter number
        See Also:
        CallMethodRule

      • addObjectParam

        public void addObjectParam​(java.lang.String pattern,
                           int paramIndex,
                           java.lang.Object paramObj)
        Add a "call parameter" rule that sets a parameter from a caller-provided object. This can be used to pass constants such as strings to methods; it can also be used to pass mutable objects, providing ways for objects to do things like "register" themselves with some shared object.

        Note that when attempting to locate a matching method to invoke, the true type of the paramObj is used, so that despite the paramObj being passed in here as type Object, the target method can declare its parameters as being the true type of the object (or some ancestor type, according to the usual type-conversion rules).

        Parameters:
        pattern - Element matching pattern
        paramIndex - The zero-relative parameter number
        paramObj - Any arbitrary object to be passed to the target method.
        Since:
        1.6
        See Also:
        CallMethodRule

      • addFactoryCreate

        public void addFactoryCreate​(java.lang.String pattern,
                             java.lang.String className)
        Add a "factory create" rule for the specified parameters. Exceptions thrown during the object creation process will be propagated.
        Parameters:
        pattern - Element matching pattern
        className - Java class name of the object creation factory class
        See Also:
        FactoryCreateRule

      • addFactoryCreate

        public void addFactoryCreate​(java.lang.String pattern,
                             java.lang.Class<? extends ObjectCreationFactory<?>> clazz)
        Add a "factory create" rule for the specified parameters. Exceptions thrown during the object creation process will be propagated.
        Parameters:
        pattern - Element matching pattern
        clazz - Java class of the object creation factory class
        See Also:
        FactoryCreateRule

      • addFactoryCreate

        public void addFactoryCreate​(java.lang.String pattern,
                             java.lang.String className,
                             java.lang.String attributeName)
        Add a "factory create" rule for the specified parameters. Exceptions thrown during the object creation process will be propagated.
        Parameters:
        pattern - Element matching pattern
        className - Java class name of the object creation factory class
        attributeName - Attribute name which, if present, overrides the value specified by className
        See Also:
        FactoryCreateRule

      • addFactoryCreate

        public void addFactoryCreate​(java.lang.String pattern,
                             java.lang.Class<? extends ObjectCreationFactory<?>> clazz,
                             java.lang.String attributeName)
        Add a "factory create" rule for the specified parameters. Exceptions thrown during the object creation process will be propagated.
        Parameters:
        pattern - Element matching pattern
        clazz - Java class of the object creation factory class
        attributeName - Attribute name which, if present, overrides the value specified by className
        See Also:
        FactoryCreateRule

      • addFactoryCreate

        public void addFactoryCreate​(java.lang.String pattern,
                             ObjectCreationFactory<?> creationFactory)
        Add a "factory create" rule for the specified parameters. Exceptions thrown during the object creation process will be propagated.
        Parameters:
        pattern - Element matching pattern
        creationFactory - Previously instantiated ObjectCreationFactory to be utilized
        See Also:
        FactoryCreateRule

      • addFactoryCreate

        public void addFactoryCreate​(java.lang.String pattern,
                             java.lang.String className,
                             boolean ignoreCreateExceptions)
        Add a "factory create" rule for the specified parameters.
        Parameters:
        pattern - Element matching pattern
        className - Java class name of the object creation factory class
        ignoreCreateExceptions - when true any exceptions thrown during object creation will be ignored.
        See Also:
        FactoryCreateRule

      • addFactoryCreate

        public void addFactoryCreate​(java.lang.String pattern,
                             java.lang.Class<? extends ObjectCreationFactory<?>> clazz,
                             boolean ignoreCreateExceptions)
        Add a "factory create" rule for the specified parameters.
        Parameters:
        pattern - Element matching pattern
        clazz - Java class of the object creation factory class
        ignoreCreateExceptions - when true any exceptions thrown during object creation will be ignored.
        See Also:
        FactoryCreateRule

      • addFactoryCreate

        public void addFactoryCreate​(java.lang.String pattern,
                             java.lang.String className,
                             java.lang.String attributeName,
                             boolean ignoreCreateExceptions)
        Add a "factory create" rule for the specified parameters.
        Parameters:
        pattern - Element matching pattern
        className - Java class name of the object creation factory class
        attributeName - Attribute name which, if present, overrides the value specified by className
        ignoreCreateExceptions - when true any exceptions thrown during object creation will be ignored.
        See Also:
        FactoryCreateRule

      • addFactoryCreate

        public void addFactoryCreate​(java.lang.String pattern,
                             java.lang.Class<? extends ObjectCreationFactory<?>> clazz,
                             java.lang.String attributeName,
                             boolean ignoreCreateExceptions)
        Add a "factory create" rule for the specified parameters.
        Parameters:
        pattern - Element matching pattern
        clazz - Java class of the object creation factory class
        attributeName - Attribute name which, if present, overrides the value specified by className
        ignoreCreateExceptions - when true any exceptions thrown during object creation will be ignored.
        See Also:
        FactoryCreateRule

      • 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.Class<?> clazz)
        Add an "object create" rule for the specified parameters.
        Parameters:
        pattern - Element matching pattern
        clazz - Java class 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

      • addObjectCreate

        public void addObjectCreate​(java.lang.String pattern,
                            java.lang.String attributeName,
                            java.lang.Class<?> clazz)
        Add an "object create" rule for the specified parameters.
        Parameters:
        pattern - Element matching pattern
        attributeName - Attribute name that optionally overrides
        clazz - Default Java class to be created the default Java class name to be created
        See Also:
        ObjectCreateRule

      • addSetNestedProperties

        public void addSetNestedProperties​(java.lang.String pattern,
                                   java.lang.String elementName,
                                   java.lang.String propertyName)
        Adds an SetNestedPropertiesRule.
        Parameters:
        pattern - register the rule with this pattern
        elementName - elment name that a property maps to
        propertyName - property name of the element mapped from
        Since:
        1.6

      • addSetNestedProperties

        public void addSetNestedProperties​(java.lang.String pattern,
                                   java.lang.String[] elementNames,
                                   java.lang.String[] propertyNames)
        Adds an SetNestedPropertiesRule.
        Parameters:
        pattern - register the rule with this pattern
        elementNames - elment names that (in order) map to properties
        propertyNames - property names that (in order) elements are mapped to
        Since:
        1.6

      • addSetNext

        public void addSetNext​(java.lang.String pattern,
                       java.lang.String methodName)
        Add a "set next" rule for the specified parameters.
        Parameters:
        pattern - Element matching pattern
        methodName - Method name to call on the parent element
        See Also:
        SetNextRule

      • 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 corresonding Java wrapper class instead, such as java.lang.Boolean for a boolean parameter)
        See Also:
        SetNextRule

      • addSetRoot

        public void addSetRoot​(java.lang.String pattern,
                       java.lang.String methodName)
        Add SetRootRule with the specified parameters.
        Parameters:
        pattern - Element matching pattern
        methodName - Method name to call on the root object
        See Also:
        SetRootRule

      • addSetRoot

        public void addSetRoot​(java.lang.String pattern,
                       java.lang.String methodName,
                       java.lang.String paramType)
        Add SetRootRule with the specified parameters.
        Parameters:
        pattern - Element matching pattern
        methodName - Method name to call on the root object
        paramType - Java class name of the expected parameter type
        See Also:
        SetRootRule

      • 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

      • addSetProperty

        public void addSetProperty​(java.lang.String pattern,
                           java.lang.String name,
                           java.lang.String value)
        Add a "set property" rule for the specified parameters.
        Parameters:
        pattern - Element matching pattern
        name - Attribute name containing the property name to be set
        value - Attribute name containing the property value to set
        See Also:
        SetPropertyRule

      • addSetTop

        public void addSetTop​(java.lang.String pattern,
                      java.lang.String methodName)
        Add a "set top" rule for the specified parameters.
        Parameters:
        pattern - Element matching pattern
        methodName - Method name to call on the parent element
        See Also:
        SetTopRule

      • addSetTop

        public void addSetTop​(java.lang.String pattern,
                      java.lang.String methodName,
                      java.lang.String paramType)
        Add a "set top" 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 corresonding Java wrapper class instead, such as java.lang.Boolean for a boolean parameter)
        See Also:
        SetTopRule

      • clear

        public void clear()
        Clear the current contents of the default object stack, the param stack, all named stacks, and other internal variables.

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

        Note that this method is called automatically after a document has been successfully parsed by a Digester instance. However it is not invoked automatically when a parse fails, so when reusing a Digester instance (which is not recommended) this method must be called manually after a parse failure.

      • peek

        public <T> T peek()
        Return the top object on the stack without removing it. If there are no objects on the stack, return null.
        Type Parameters:
        T - the type used to auto-cast the returned object to the assigned variable type
        Returns:
        the top object on the stack without removing it.

      • peek

        public <T> T 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.
        Type Parameters:
        T - the type used to auto-cast the returned object to the assigned variable type
        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 n'th object down the stack

      • pop

        public <T> T pop()
        Pop the top object off of the stack, and return it. If there are no objects on the stack, return null.
        Type Parameters:
        T - the type used to auto-cast the returned object to the assigned variable type
        Returns:
        the top object popped off of the stack

      • push

        public <T> void push​(T object)
        Push a new object onto the top of the object stack.
        Type Parameters:
        T - any type of the pushed object
        Parameters:
        object - The new object

      • push

        public <T> void push​(java.lang.String stackName,
                     T value)
        Pushes the given object onto the stack with the given name. If no stack already exists with the given name then one will be created.
        Type Parameters:
        T - any type of the pushed object
        Parameters:
        stackName - the name of the stack onto which the object should be pushed
        value - the Object to be pushed onto the named stack.
        Since:
        1.6

      • pop

        public <T> T pop​(java.lang.String stackName)

        Pops (gets and removes) the top object from the stack with the given name.

        Note: a stack is considered empty if no objects have been pushed onto it yet.

        Type Parameters:
        T - the type used to auto-cast the returned object to the assigned variable type
        Parameters:
        stackName - the name of the stack from which the top value is to be popped.
        Returns:
        the top Object on the stack or or null if the stack is either empty or has not been created yet
        Since:
        1.6

      • peek

        public <T> T peek​(java.lang.String stackName)

        Gets the top object from the stack with the given name. This method does not remove the object from the stack.

        Note: a stack is considered empty if no objects have been pushed onto it yet.

        Type Parameters:
        T - the type used to auto-cast the returned object to the assigned variable type
        Parameters:
        stackName - the name of the stack to be peeked
        Returns:
        the top Object on the stack or null if the stack is either empty or has not been created yet
        Since:
        1.6

      • peek

        public <T> T peek​(java.lang.String stackName,
                  int n)

        Gets the top object from the stack with the given name. This method does not remove the object from the stack.

        Note: a stack is considered empty if no objects have been pushed onto it yet.

        Type Parameters:
        T - the type used to auto-cast the returned object to the assigned variable type
        Parameters:
        stackName - the name of the stack to be peeked
        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 on the stack.
        Since:
        1.6

      • isEmpty

        public boolean isEmpty​(java.lang.String stackName)

        Is the stack with the given name empty?

        Note: a stack is considered empty if no objects have been pushed onto it yet.

        Parameters:
        stackName - the name of the stack whose emptiness should be evaluated
        Returns:
        true if the given stack if empty
        Since:
        1.6

      • getRoot

        public <T> T getRoot()
        Returns the root element of the tree of objects created as a result of applying the rule objects to the input XML.

        If the digester stack was "primed" by explicitly pushing a root object onto the stack before parsing started, then that root object is returned here.

        Alternatively, if a Rule which creates an object (eg ObjectCreateRule) matched the root element of the xml, then the object created will be returned here.

        In other cases, the object most recently pushed onto an empty digester stack is returned. This would be a most unusual use of digester, however; one of the previous configurations is much more likely.

        Note that when using one of the Digester.parse methods, the return value from the parse method is exactly the same as the return value from this method. However when the Digester is being used as a SAXContentHandler, no such return value is available; in this case, this method allows you to access the root object that has been created after parsing has completed.

        Type Parameters:
        T - the type used to auto-cast the returned object to the assigned variable type
        Returns:
        the root object that has been created after parsing or null if the digester has not parsed any XML yet.

      • resetRoot

        public void resetRoot()
        This method allows the "root" variable to be reset to null.

        It is not considered safe for a digester instance to be reused to parse multiple xml documents. However if you are determined to do so, then you should call both clear() and resetRoot() before each parse.

        Since:
        1.7

      • cleanup

        protected void cleanup()

        Clean up allocated resources after parsing is complete. The default method closes input streams that have been created by Digester itself. If you override this method in a subclass, be sure to call super.cleanup() to invoke this logic.

        Since:
        1.8

      • 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. Once only initialization code should be placed in initialize() or the code should take responsibility by checking and setting the configured flag.

      • isConfigured

        public boolean isConfigured()
        Checks the Digester instance has been configured.
        Returns:
        true, if the Digester instance has been configured, false otherwise
        Since:
        3.0

      • initialize

        protected void initialize()

        Provides a hook for lazy initialization of this Digester instance. The default implementation does nothing, but subclasses can override as needed. Digester (by default) only calls this method once.

        Note This method will be called by configure() only when the configured flag is false. Subclasses that override configure or who set configured may find that this method may be called more than once.

        Since:
        1.6

      • 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 without removing it.

      • peekParams

        public java.lang.Object[] peekParams​(int n)

        Return the n'th object down the parameters stack, where 0 is the top element and [getCount()-1] is the bottom element. If the specified index is out of range, return null.

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

        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 n'th object down 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 popped off of 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 custom SAX exception message
        e - the exception cause
        Returns:
        the new SAX 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 exception cause
        Returns:
        the new SAX 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 custom SAX exception message
        Returns:
        the new SAX exception