Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.digester3
Class Rule

    java.lang.Object
      org.apache.commons.digester3.Rule

Direct Known Subclasses:
  AbstractMethodRule, BeanPropertySetterRule, CallMethodRule, CallParamRule, FactoryCreateRule, NodeCreateRule, ObjectCreateRule, ObjectParamRule, PathCallParamRule, PluginCreateRule, PluginDeclarationRule, SetNestedPropertiesRule, SetPropertiesRule, SetPropertyRule

    public abstract class Rule

extends 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.

Constructor Summary
`Rule()`

Method Summary
`void` | `begin(String namespace, String name, Attributes attributes)` This method is called when the beginning of a matching XML element is encountered.
`void` | `body(String namespace, String name, String text)` This method is called when the body of a matching XML element is encountered.
`void` | `end(String namespace, 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.
`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(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`

Constructor Detail

### Rule

    public Rule()

Method Detail

### getDigester

    public Digester getDigester()

  Return the Digester with which this Rule is associated.

  Returns:
    the Digester with which this Rule is associated

### setDigester

    public void setDigester(Digester digester)

  Set the `Digester` with which this `Rule` is associated.

  Parameters:
    `digester` - the `Digester` with which this `Rule` is associated

### getNamespaceURI

    public String getNamespaceURI()

  Return the namespace URI for which this Rule is relevant, if any.

  Returns:
    the namespace URI for which this Rule is relevant, if any

### setNamespaceURI

    public void setNamespaceURI(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

    public void begin(String namespace,
                      String name,
                      Attributes attributes)
               throws Exception

  This method is called when the beginning of a matching XML element is encountered.

  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:
    `Exception` - if any error occurs
  Since:
    Digester 1.4

### body

    public void body(String namespace,
                     String name,
                     String text)
              throws 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.

  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:
    `Exception` - if any error occurs
  Since:
    Digester 1.4

### end

    public void end(String namespace,
                    String name)
             throws Exception

  This method is called when the end of a matching XML element is encountered.

  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:
    `Exception` - if any error occurs
  Since:
    Digester 1.4

### finish

    public void finish()
                throws Exception

  This method is called after all parsing methods have been called, to allow Rules to remove temporary data.

  Throws:
    `Exception` - if any error occurs

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2011 The Apache Software Foundation. All Rights Reserved.