Class Rule

  • Direct Known Subclasses:
    BeanPropertySetterRule, CallMethodRule, CallParamRule, DigesterRuleParser.SetNestedPropertiesAliasRule, DigesterRuleParser.SetPropertiesAliasRule, FactoryCreateRule, NodeCreateRule, ObjectCreateRule, ObjectParamRule, PathCallParamRule, PluginCreateRule, PluginDeclarationRule, SetNestedPropertiesRule, SetNextRule, SetPropertiesRule, SetPropertyRule, SetRootRule, SetTopRule

    public abstract class Rule
    extends java.lang.Object
    Concrete implementations of this class implement actions to be taken when a corresponding nested pattern of XML elements has been matched.

    Writing a custom Rule is considered perfectly normal when using Digester, and is encouraged whenever the default set of Rule classes don't meet your requirements; the digester framework can help process xml even when the built-in rules aren't quite what is needed. Creating a custom Rule is just as easy as subclassing javax.servlet.http.HttpServlet for webapps, or javax.swing.Action for GUI applications.

    If a rule wishes to manipulate a digester stack (the default object stack, a named stack, or the parameter stack) then it should only ever push objects in the rule's begin method and always pop exactly the same number of objects off the stack during the rule's end method. Of course peeking at the objects on the stacks can be done from anywhere.

    Rule objects should be stateless, ie they should not update any instance member during the parsing process. A rule instance that changes state will encounter problems if invoked in a "nested" manner; this can happen if the same instance is added to digester multiple times or if a wildcard pattern is used which can match both an element and a child of the same element. The digester object stack and named stacks should be used to store any state that a rule requires, making the rule class safe under all possible uses.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected Digester digester
      The Digester with which this Rule is associated.
      protected java.lang.String namespaceURI
      The namespace URI for which this Rule is relevant, if any.
    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void begin​(java.lang.String namespace, java.lang.String name, org.xml.sax.Attributes attributes)
      This method is called when the beginning of a matching XML element is encountered.
      void begin​(org.xml.sax.Attributes attributes)
      Deprecated.
      Use the begin method with namespace and name parameters instead.
      void body​(java.lang.String text)
      Deprecated.
      Use the body method with namespace and name parameters instead.
      void body​(java.lang.String namespace, java.lang.String name, java.lang.String text)
      This method is called when the body of a matching XML element is encountered.
      void end()
      Deprecated.
      Use the end method with namespace and name parameters instead.
      void end​(java.lang.String namespace, java.lang.String name)
      This method is called when the end of a matching XML element is encountered.
      void finish()
      This method is called after all parsing methods have been called, to allow Rules to remove temporary data.
      Digester getDigester()
      Return the Digester with which this Rule is associated.
      java.lang.String getNamespaceURI()
      Return the namespace URI for which this Rule is relevant, if any.
      void setDigester​(Digester digester)
      Set the Digester with which this Rule is associated.
      void setNamespaceURI​(java.lang.String namespaceURI)
      Set the namespace URI for which this Rule is relevant, if any.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • digester

        protected Digester digester
        The Digester with which this Rule is associated.
      • namespaceURI

        protected java.lang.String namespaceURI
        The namespace URI for which this Rule is relevant, if any.
    • Method Detail

      • getDigester

        public Digester getDigester()
        Return the Digester with which this Rule is associated.
      • setDigester

        public void setDigester​(Digester digester)
        Set the Digester with which this Rule is associated.
      • getNamespaceURI

        public java.lang.String getNamespaceURI()
        Return the namespace URI for which this Rule is relevant, if any.
      • setNamespaceURI

        public void setNamespaceURI​(java.lang.String namespaceURI)
        Set the namespace URI for which this Rule is relevant, if any.
        Parameters:
        namespaceURI - Namespace URI for which this Rule is relevant, or null to match independent of namespace.
      • begin

        @Deprecated
        public void begin​(org.xml.sax.Attributes attributes)
                   throws java.lang.Exception
        Deprecated.
        Use the begin method with namespace and name parameters instead.
        This method is called when the beginning of a matching XML element is encountered.
        Parameters:
        attributes - The attribute list of this element
        Throws:
        java.lang.Exception
      • begin

        public void begin​(java.lang.String namespace,
                          java.lang.String name,
                          org.xml.sax.Attributes attributes)
                   throws java.lang.Exception
        This method is called when the beginning of a matching XML element is encountered. The default implementation delegates to the deprecated method begin without the namespace and name parameters, to retain backwards compatibility.
        Parameters:
        namespace - the namespace URI of the matching element, or an empty string if the parser is not namespace aware or the element has no namespace
        name - the local name if the parser is namespace aware, or just the element name otherwise
        attributes - The attribute list of this element
        Throws:
        java.lang.Exception
        Since:
        Digester 1.4
      • body

        @Deprecated
        public void body​(java.lang.String text)
                  throws java.lang.Exception
        Deprecated.
        Use the body method with namespace and name parameters instead.
        This method is called when the body of a matching XML element is encountered. If the element has no body, this method is called with an empty string as the body text.
        Parameters:
        text - The text of the body of this element
        Throws:
        java.lang.Exception
      • body

        public void body​(java.lang.String namespace,
                         java.lang.String name,
                         java.lang.String text)
                  throws java.lang.Exception
        This method is called when the body of a matching XML element is encountered. If the element has no body, this method is called with an empty string as the body text.

        The default implementation delegates to the deprecated method body without the namespace and name parameters, to retain backwards compatibility.

        Parameters:
        namespace - the namespace URI of the matching element, or an empty string if the parser is not namespace aware or the element has no namespace
        name - the local name if the parser is namespace aware, or just the element name otherwise
        text - The text of the body of this element
        Throws:
        java.lang.Exception
        Since:
        Digester 1.4
      • end

        @Deprecated
        public void end()
                 throws java.lang.Exception
        Deprecated.
        Use the end method with namespace and name parameters instead.
        This method is called when the end of a matching XML element is encountered.
        Throws:
        java.lang.Exception
      • end

        public void end​(java.lang.String namespace,
                        java.lang.String name)
                 throws java.lang.Exception
        This method is called when the end of a matching XML element is encountered. The default implementation delegates to the deprecated method end without the namespace and name parameters, to retain backwards compatibility.
        Parameters:
        namespace - the namespace URI of the matching element, or an empty string if the parser is not namespace aware or the element has no namespace
        name - the local name if the parser is namespace aware, or just the element name otherwise
        Throws:
        java.lang.Exception
        Since:
        Digester 1.4
      • finish

        public void finish()
                    throws java.lang.Exception
        This method is called after all parsing methods have been called, to allow Rules to remove temporary data.
        Throws:
        java.lang.Exception