digester

External Dependencies

The Digester component is dependent upon implementations of the following standard libraries:

• XML Parser compatible with the JAXP/1.1 specification. Examples compatible implementations include:
  • JAXP/1.1 Reference Implementation
  • Xerces (Version 1.3.1 or later)

It is also dependent on a compatible set of Apache Commons library components. The recommended dependency set is:

Recommended Dependency Set
Digester	+Logging 1.1.x	+BeanUtils 1.7

Other compatible dependency sets include:

Compatible Dependency Sets
Digester	+Logging 1.1.x	+BeanUtils 1.x	+Collections 2.x
Digester	+Logging 1.1.x	+BeanUtils 1.x	+Collections 3.x

It is also possible to use Logging 1.0.x instead.

Introduction

In many application environments that deal with XML-formatted data, it is useful to be able to process an XML document in an "event driven" manner, where particular Java objects are created (or methods of existing objects are invoked) when particular patterns of nested XML elements have been recognized. Developers familiar with the Simple API for XML Parsing (SAX) approach to processing XML documents will recognize that the Digester provides a higher level, more developer-friendly interface to SAX events, because most of the details of navigating the XML element hierarchy are hidden -- allowing the developer to focus on the processing to be performed.

In order to use a Digester, the following basic steps are required:

• Create a new instance of the org.apache.commons.digester.Digester class. Previously created Digester instances may be safely reused, as long as you have completed any previously requested parse, and you do not try to utilize a particular Digester instance from more than one thread at a time.
• Set any desired configuration properties that will customize the operation of the Digester when you next initiate a parse operation.
• Optionally, push any desired initial object(s) onto the Digester's object stack.
• Register all of the element matching patterns for which you wish to have processing rules fired when this pattern is recognized in an input document. You may register as many rules as you like for any particular pattern. If there is more than one rule for a given pattern, the rules will be executed in the order that they were listed.
• Call the digester.parse() method, passing a reference to the XML document to be parsed in one of a variety of forms. See the Digester.parse() documentation for details. Note that you will need to be prepared to catch any IOException or SAXException that is thrown by the parser, or any runtime expression that is thrown by one of the processing rules.

Alternatively a Digester may be used as a sax event hander, as follows:

• Create an instance of a sax parser (using the JAXP APIs or otherwise).
• Set any desired configuration properties on that parser object.
• Create an instance of org.apache.commons.digester.Digester.
• Optionally, push any desired initial object(s) onto the Digester's object stack.
• Register patterns and rules with the digester instance.
• Call parser.parse(inputSource, digester).

For example code, see the usage examples, and the FAQ .

Digester Configuration Properties

A org.apache.commons.digester.Digester instance contains several configuration properties that can be used to customize its operation. These properties must be configured before you call one of the parse() variants, in order for them to take effect on that parse.

Property	Description
classLoader	You can optionally specify the class loader that will be used to load classes when required by the ObjectCreateRule and FactoryCreateRule rules. If not specified, application classes will be loaded from the thread's context class loader (if the useContextClassLoader property is set to true) or the same class loader that was used to load the Digester class itself.
errorHandler	You can optionally specify a SAX ErrorHandler that is notified when parsing errors occur. By default, any parsing errors that are encountered are logged, but Digester will continue processing as well.
namespaceAware	A boolean that is set to true to perform parsing in a manner that is aware of XML namespaces. Among other things, this setting affects how elements are matched to processing rules. See Namespace Aware Parsing for more information.
ruleNamespaceURI	The public URI of the namespace for which all subsequently added rules are associated, or null for adding rules that are not associated with any namespace. See Namespace Aware Parsing for more information.
rules	The Rules component that actually performs matching of Rule instances against the current element nesting pattern is pluggable. By default, Digester includes a Rules implementation that behaves as described in this document. See Pluggable Rules Processing for more information.
useContextClassLoader	A boolean that is set to true if you want application classes required by FactoryCreateRule and ObjectCreateRule to be loaded from the context class loader of the current thread. By default, classes will be loaded from the class loader that loaded this Digester class. NOTE - This property is ignored if you set a value for the classLoader property; that class loader will be used unconditionally.
validating	A boolean that is set to true if you wish to validate the XML document against a Document Type Definition (DTD) that is specified in its DOCTYPE declaration. The default value of false requests a parse that only detects "well formed" XML documents, rather than "valid" ones.

In addition to the scalar properties defined above, you can also register a local copy of a Document Type Definition (DTD) that is referenced in a DOCTYPE declaration. Such a registration tells the XML parser that, whenever it encounters a DOCTYPE declaration with the specified public identifier, it should utilize the actual DTD content at the registered system identifier (a URL), rather than the one in the DOCTYPE declaration.

For example, the Struts framework controller servlet uses the following registration in order to tell Struts to use a local copy of the DTD for the Struts configuration file. This allows usage of Struts in environments that are not connected to the Internet, and speeds up processing even at Internet connected sites (because it avoids the need to go across the network).

    URL url = new URL("/org/apache/struts/resources/struts-config_1_0.dtd");
    digester.register
      ("-//Apache Software Foundation//DTD Struts Configuration 1.0//EN",
       url.toString());

As a side note, the system identifier used in this example is the path that would be passed to java.lang.ClassLoader.getResource() or java.lang.ClassLoader.getResourceAsStream(). The actual DTD resource is loaded through the same class loader that loads all of the Struts classes -- typically from the struts.jar file.

The Object Stack

One very common use of org.apache.commons.digester.Digester technology is to dynamically construct a tree of Java objects, whose internal organization, as well as the details of property settings on these objects, are configured based on the contents of the XML document. In fact, the primary reason that the Digester package was created (it was originally part of Struts, and then moved to the Commons project because it was recognized as being generally useful) was to facilitate the way that the Struts controller servlet configures itself based on the contents of your application's struts-config.xml file.

To facilitate this usage, the Digester exposes a stack that can be manipulated by processing rules that are fired when element matching patterns are satisfied. The usual stack-related operations are made available, including the following:

• clear() - Clear the current contents of the object stack.
• peek() - Return a reference to the top object on the stack, without removing it.
• pop() - Remove the top object from the stack and return it.
• push() - Push a new object onto the top of the stack.

A typical design pattern, then, is to fire a rule that creates a new object and pushes it on the stack when the beginning of a particular XML element is encountered. The object will remain there while the nested content of this element is processed, and it will be popped off when the end of the element is encountered. As we will see, the standard "object create" processing rule supports exactly this functionalility in a very convenient way.

Several potential issues with this design pattern are addressed by other features of the Digester functionality:

• How do I relate the objects being created to each other? - The Digester supports standard processing rules that pass the top object on the stack as an argument to a named method on the next-to-top object on the stack (or vice versa). This rule makes it easy to establish parent-child relationships between these objects. One-to-one and one-to-many relationships are both easy to construct.
• How do I retain a reference to the first object that was created? As you review the description of what the "object create" processing rule does, it would appear that the first object you create (i.e. the object created by the outermost XML element you process) will disappear from the stack by the time that XML parsing is completed, because the end of the element would have been encountered. However, Digester will maintain a reference to the very first object ever pushed onto the object stack, and will return it to you as the return value from the parse() call. Alternatively, you can push a reference to some application object onto the stack before calling parse(), and arrange that a parent-child relationship be created (by appropriate processing rules) between this manually pushed object and the ones that are dynamically created. In this way, the pushed object will retain a reference to the dynamically created objects (and therefore all of their children), and will be returned to you after the parse finishes as well.

Element Matching Patterns

A primary feature of the org.apache.commons.digester.Digester parser is that the Digester automatically navigates the element hierarchy of the XML document you are parsing for you, without requiring any developer attention to this process. Instead, you focus on deciding what functions you would like to have performed whenver a certain arrangement of nested elements is encountered in the XML document being parsed. The mechanism for specifying such arrangements are called element matching patterns.

The Digester can be configured to use different pattern-matching algorithms via the Digester.setRules method. However for the vast majority of cases, the default matching algorithm works fine. The default pattern matching behaviour is described below.

A very simple element matching pattern is a simple string like "a". This pattern is matched whenever an <a> top-level element is encountered in the XML document, no matter how many times it occurs. Note that nested <a> elements will not match this pattern -- we will describe means to support this kind of matching later.

The next step up in matching pattern complexity is "a/b". This pattern will be matched when a <b> element is found nested inside a top-level <a> element. Again, this match can occur as many times as desired, depending on the content of the XML document being parsed. You can use multiple slashes to define a hierarchy of any desired depth that will be matched appropriately.

For example, assume you have registered processing rules that match patterns "a", "a/b", and "a/b/c". For an input XML document with the following contents, the indicated patterns will be matched when the corresponding element is parsed:

  <a>         -- Matches pattern "a"
    <b>       -- Matches pattern "a/b"
      <c/>    -- Matches pattern "a/b/c"
      <c/>    -- Matches pattern "a/b/c"
    </b>
    <b>       -- Matches pattern "a/b"
      <c/>    -- Matches pattern "a/b/c"
      <c/>    -- Matches pattern "a/b/c"
      <c/>    -- Matches pattern "a/b/c"
    </b>
  </a>

It is also possible to match a particular XML element, no matter how it is nested (or not nested) in the XML document, by using the "*" wildcard character in your matching pattern strings. For example, an element matching pattern of "*/a" will match an <a> element at any nesting position within the document.

It is quite possible that, when a particular XML element is being parsed, the pattern for more than one registered processing rule will be matched because you registered more than one processing rule with the exact same matching pattern.

When this occurs, the corresponding processing rules will all be fired in order. Rule methods begin (and body) are executed in the order that the Rules were initially registered with the Digester, whilst end method calls are executed in reverse order. In other words - the order is first in, last out.

Note that wildcard patterns are ignored if an explicit match can be found (and when multiple wildcard patterns match, only the longest, ie most explicit, pattern is considered a match). The result is that rules can be added for "an <a> tag anywhere", but then for that behaviour to be explicitly overridden for specific cases, eg "but not an <a> that is a direct child of an <x>". Therefore if you have rules A and B registered for pattern "*/a" then want to add an additional rule C for pattern "x/a" only, then what you need to do is add *three* rules for "x/a": A, B and C. Note that by using:

  Rule ruleA = new ObjectCreateRule();
  Rule ruleB = new SetNextRule();
  Rule ruleC = new SetPropertiesRule();

  digester.addRule("*/a", ruleA);
  digester.addRule("*/a", ruleB);
  digester.addRule("x/a", ruleA);
  digester.addRule("x/a", ruleB);
  digester.addRule("x/a", ruleC);

Processing Rules

The previous section documented how you identify when you wish to have certain actions take place. The purpose of processing rules is to define what should happen when the patterns are matched.

Formally, a processing rule is a Java class that subclasses the org.apache.commons.digester.Rule interface. Each Rule implements one or more of the following event methods that are called at well-defined times when the matching patterns corresponding to this rule trigger it:

• begin() - Called when the beginning of the matched XML element is encountered. A data structure containing all of the attributes corresponding to this element are passed as well.
• body() - Called when nested content (that is not itself XML elements) of the matched element is encountered. Any leading or trailing whitespace will have been removed as part of the parsing process.
• end() - Called when the ending of the matched XML element is encountered. If nested XML elements that matched other processing rules was included in the body of this element, the appropriate processing rules for the matched rules will have already been completed before this method is called.
• finish() - Called when the parse has been completed, to give each rule a chance to clean up any temporary data they might have created and cached.

As you are configuring your digester, you can call the addRule() method to register a specific element matching pattern, along with an instance of a Rule class that will have its event handling methods called at the appropriate times, as described above. This mechanism allows you to create Rule implementation classes dynamically, to implement any desired application specific functionality.

In addition, a set of processing rule implementation classes are provided, which deal with many common programming scenarios. These classes include the following:

• ObjectCreateRule - When the begin() method is called, this rule instantiates a new instance of a specified Java class, and pushes it on the stack. The class name to be used is defaulted according to a parameter passed to this rule's constructor, but can optionally be overridden by a classname passed via the specified attribute to the XML element being processed. When the end() method is called, the top object on the stack (presumably, the one we added in the begin() method) will be popped, and any reference to it (within the Digester) will be discarded.
• FactoryCreateRule - A variation of ObjectCreateRule that is useful when the Java class with which you wish to create an object instance does not have a no-arguments constructor, or where you wish to perform other setup processing before the object is handed over to the Digester.
• SetPropertiesRule - When the begin() method is called, the digester uses the standard Java Reflection API to identify any JavaBeans property setter methods (on the object at the top of the digester's stack) who have property names that match the attributes specified on this XML element, and then call them individually, passing the corresponding attribute values. These natural mappings can be overridden. This allows (for example) a class attribute to be mapped correctly. It is recommended that this feature should not be overused - in most cases, it's better to use the standard BeanInfo mechanism. A very common idiom is to define an object create rule, followed by a set properties rule, with the same element matching pattern. This causes the creation of a new Java object, followed by "configuration" of that object's properties based on the attributes of the same XML element that created this object.
• SetPropertyRule - When the begin() method is called, the digester calls a specified property setter (where the property itself is named by an attribute) with a specified value (where the value is named by another attribute), on the object at the top of the digester's stack. This is useful when your XML file conforms to a particular DTD, and you wish to configure a particular property that does not have a corresponding attribute in the DTD.
• SetNextRule - When the end() method is called, the digester analyzes the next-to-top element on the stack, looking for a property setter method for a specified property. It then calls this method, passing the object at the top of the stack as an argument. This rule is commonly used to establish one-to-many relationships between the two objects, with the method name commonly being something like "addChild".
• SetTopRule - When the end() method is called, the digester analyzes the top element on the stack, looking for a property setter method for a specified property. It then calls this method, passing the next-to-top object on the stack as an argument. This rule would be used as an alternative to a SetNextRule, with a typical method name "setParent", if the API supported by your object classes prefers this approach.
• CallMethodRule - This rule sets up a method call to a named method of the top object on the digester's stack, which will actually take place when the end() method is called. You configure this rule by specifying the name of the method to be called, the number of arguments it takes, and (optionally) the Java class name(s) defining the type(s) of the method's arguments. The actual parameter values, if any, will typically be accumulated from the body content of nested elements within the element that triggered this rule, using the CallParamRule discussed next.
• CallParamRule - This rule identifies the source of a particular numbered (zero-relative) parameter for a CallMethodRule within which we are nested. You can specify that the parameter value be taken from a particular named attribute, or from the nested body content of this element.
• NodeCreateRule - A specialized rule that converts part of the tree into a DOM Node and then pushes it onto the stack.

You can create instances of the standard Rule classes and register them by calling digester.addRule(), as described above. However, because their usage is so common, shorthand registration methods are defined for each of the standard rules, directly on the Digester class. For example, the following code sequence:

    Rule rule = new SetNextRule(digester, "addChild",
                                "com.mycompany.mypackage.MyChildClass");
    digester.addRule("a/b/c", rule);

can be replaced by:

    digester.addSetNext("a/b/c", "addChild",
                        "com.mycompany.mypackage.MyChildClass");

Logging

Logging is a vital tool for debugging Digester rulesets. Digester can log copious amounts of debugging information. So, you need to know how logging works before you start using Digester seriously.

Digester uses Apache Commons Logging. This component is not really a logging framework - rather an extensible, configurable bridge. It can be configured to swallow all log messages, to provide very basic logging by itself or to pass logging messages on to more sophisticated logging frameworks. Commons-Logging comes with connectors for many popular logging frameworks. Consult the commons-logging documentation for more information.

Two main logs are used by Digester:

• SAX-related messages are logged to org.apache.commons.digester.Digester.sax. This log gives information about the basic SAX events received by Digester.
• org.apache.commons.digester.Digester is used for everything else. You'll probably want to have this log turned up during debugging but turned down during production due to the high message volume.

Complete documentation of how to configure Commons-Logging can be found in the Commons Logging package documentation. However, as a simple example, let's assume that you want to use the SimpleLog implementation that is included in Commons-Logging, and set up Digester to log events from the Digester logger at the DEBUG level, while you want to log events from the Digester.log logger at the INFO level. You can accomplish this by creating a commons-logging.properties file in your classpath (or setting corresponding system properties on the command line that starts your application) with the following contents:

  org.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog
  org.apache.commons.logging.simplelog.log.org.apache.commons.digester.Digester=debug
  org.apache.commons.logging.simplelog.log.org.apache.commons.digester.Digester.sax=info

Usage Examples

Creating a Simple Object Tree

Let's assume that you have two simple JavaBeans, Foo and Bar, with the following method signatures:

  package mypackage;
  public class Foo {
    public void addBar(Bar bar);
    public Bar findBar(int id);
    public Iterator getBars();
    public String getName();
    public void setName(String name);
  }

  package mypackage;
  public class Bar {
    public int getId();
    public void setId(int id);
    public String getTitle();
    public void setTitle(String title);
  }

and you wish to use Digester to parse the following XML document:

  <foo name="The Parent">
    <bar id="123" title="The First Child"/>
    <bar id="456" title="The Second Child"/>
  </foo>

A simple approach will be to use the following Digester in the following way to set up the parsing rules, and then process an input file containing this document:

  Digester digester = new Digester();
  digester.setValidating(false);
  digester.addObjectCreate("foo", "mypackage.Foo");
  digester.addSetProperties("foo");
  digester.addObjectCreate("foo/bar", "mypackage.Bar");
  digester.addSetProperties("foo/bar");
  digester.addSetNext("foo/bar", "addBar", "mypackage.Bar");
  Foo foo = (Foo) digester.parse();

In order, these rules do the following tasks:

1. When the outermost <foo> element is encountered, create a new instance of mypackage.Foo and push it on to the object stack. At the end of the <foo> element, this object will be popped off of the stack.
2. Cause properties of the top object on the stack (i.e. the Foo object that was just created and pushed) to be set based on the values of the attributes of this XML element.
3. When a nested <bar> element is encountered, create a new instance of mypackage.Bar and push it on to the object stack. At the end of the <bar> element, this object will be popped off of the stack (i.e. after the remaining rules matching foo/bar are processed).
4. Cause properties of the top object on the stack (i.e. the Bar object that was just created and pushed) to be set based on the values of the attributes of this XML element. Note that type conversions are automatically performed (such as String to int for the id property), for all converters registered with the ConvertUtils class from commons-beanutils package.
5. Cause the addBar method of the next-to-top element on the object stack (which is why this is called the "set next" rule) to be called, passing the element that is on the top of the stack, which must be of type mypackage.Bar. This is the rule that causes the parent/child relationship to be created.

Once the parse is completed, the first object that was ever pushed on to the stack (the Foo object in this case) is returned to you. It will have had its properties set, and all of its child Bar objects created for you.

Processing A Struts Configuration File

As stated earlier, the primary reason that the Digester package was created is because the Struts controller servlet itself needed a robust, flexible, easy to extend mechanism for processing the contents of the struts-config.xml configuration that describes nearly every aspect of a Struts-based application. Because of this, the controller servlet contains a comprehensive, real world, example of how the Digester can be employed for this type of a use case. See the initDigester() method of class org.apache.struts.action.ActionServlet for the code that creates and configures the Digester to be used, and the initMapping() method for where the parsing actually takes place.

(Struts binary and source distributions can be acquired at http://struts.apache.org.)

The following discussion highlights a few of the matching patterns and processing rules that are configured, to illustrate the use of some of the Digester features. First, let's look at how the Digester instance is created and initialized:

    Digester digester = new Digester();
    digester.push(this); // Push controller servlet onto the stack
    digester.setValidating(true);

We see that a new Digester instance is created, and is configured to use a validating parser. Validation will occur against the struts-config_1_0.dtd DTD that is included with Struts (as discussed earlier). In order to provide a means of tracking the configured objects, the controller servlet instance itself will be added to the digester's stack.

    digester.addObjectCreate("struts-config/global-forwards/forward",
                             forwardClass, "className");
    digester.addSetProperties("struts-config/global-forwards/forward");
    digester.addSetNext("struts-config/global-forwards/forward",
                        "addForward",
                        "org.apache.struts.action.ActionForward");
    digester.addSetProperty
      ("struts-config/global-forwards/forward/set-property",
       "property", "value");

The rules created by these lines are used to process the global forward declarations. When a <forward> element is encountered, the following actions take place:

• A new object instance is created -- the ActionForward instance that will represent this definition. The Java class name defaults to that specified as an initialization parameter (which we have stored in the String variable forwardClass), but can be overridden by using the "className" attribute (if it is present in the XML element we are currently parsing). The new ActionForward instance is pushed onto the stack.
• The properties of the ActionForward instance (at the top of the stack) are configured based on the attributes of the <forward> element.
• Nested occurrences of the <set-property> element cause calls to additional property setter methods to occur. This is required only if you have provided a custom implementation of the ActionForward class with additional properties that are not included in the DTD.
• The addForward() method of the next-to-top object on the stack (i.e. the controller servlet itself) will be called, passing the object at the top of the stack (i.e. the ActionForward instance) as an argument. This causes the global forward to be registered, and as a result of this it will be remembered even after the stack is popped.
• At the end of the <forward> element, the top element (i.e. the ActionForward instance) will be popped off the stack.

Later on, the digester is actually executed as follows:

    InputStream input =
      getServletContext().getResourceAsStream(config);
    ...
    try {
        digester.parse(input);
        input.close();
    } catch (SAXException e) {
        ... deal with the problem ...
    }

As a result of the call to parse(), all of the configuration information that was defined in the struts-config.xml file is now represented as collections of objects cached within the Struts controller servlet, as well as being exposed as servlet context attributes.

Parsing Body Text In XML Files

The Digester module also allows you to process the nested body text in an XML file, not just the elements and attributes that are encountered. The following example is based on an assumed need to parse the web application deployment descriptor (/WEB-INF/web.xml) for the current web application, and record the configuration information for a particular servlet. To record this information, assume the existence of a bean class with the following method signatures (among others):

  package com.mycompany;
  public class ServletBean {
    public void setServletName(String servletName);
    public void setServletClass(String servletClass);
    public void addInitParam(String name, String value);
  }

We are going to process the web.xml file that declares the controller servlet in a typical Struts-based application (abridged for brevity in this example):

  <web-app>
    ...
    <servlet>
      <servlet-name>action</servlet-name>
      <servlet-class>org.apache.struts.action.ActionServlet<servlet-class>
      <init-param>
        <param-name>application</param-name>
        <param-value>org.apache.struts.example.ApplicationResources<param-value>
      </init-param>
      <init-param>
        <param-name>config</param-name>
        <param-value>/WEB-INF/struts-config.xml<param-value>
      </init-param>
    </servlet>
    ...
  </web-app>

Next, lets define some Digester processing rules for this input file:

  digester.addObjectCreate("web-app/servlet",
                           "com.mycompany.ServletBean");
  digester.addCallMethod("web-app/servlet/servlet-name", "setServletName", 0);
  digester.addCallMethod("web-app/servlet/servlet-class",
                         "setServletClass", 0);
  digester.addCallMethod("web-app/servlet/init-param",
                         "addInitParam", 2);
  digester.addCallParam("web-app/servlet/init-param/param-name", 0);
  digester.addCallParam("web-app/servlet/init-param/param-value", 1);

Now, as elements are parsed, the following processing occurs:

• <servlet> - A new com.mycompany.ServletBean object is created, and pushed on to the object stack.
• <servlet-name> - The setServletName() method of the top object on the stack (our ServletBean) is called, passing the body content of this element as a single parameter.
• <servlet-class> - The setServletClass() method of the top object on the stack (our ServletBean) is called, passing the body content of this element as a single parameter.
• <init-param> - A call to the addInitParam method of the top object on the stack (our ServletBean) is set up, but it is not called yet. The call will be expecting two String parameters, which must be set up by subsequent call parameter rules.
• <param-name> - The body content of this element is assigned as the first (zero-relative) argument to the call we are setting up.
• <param-value> - The body content of this element is assigned as the second (zero-relative) argument to the call we are setting up.
• </init-param> - The call to addInitParam() that we have set up is now executed, which will cause a new name-value combination to be recorded in our bean.
• <init-param> - The same set of processing rules are fired again, causing a second call to addInitParam() with the second parameter's name and value.
• </servlet> - The element on the top of the object stack (which should be the ServletBean we pushed earlier) is popped off the object stack.

Namespace Aware Parsing

For digesting XML documents that do not use XML namespaces, the default behavior of Digester, as described above, is generally sufficient. However, if the document you are processing uses namespaces, it is often convenient to have sets of Rule instances that are only matched on elements that use the prefix of a particular namespace. This approach, for example, makes it possible to deal with element names that are the same in different namespaces, but where you want to perform different processing for each namespace.

Digester does not provide full support for namespaces, but does provide sufficient to accomplish most tasks. Enabling digester's namespace support is done by following these steps:

1. Tell Digester that you will be doing namespace aware parsing, by adding this statement in your initalization of the Digester's properties:

       digester.setNamespaceAware(true);
       

2. Declare the public namespace URI of the namespace with which following rules will be associated. Note that you do not make any assumptions about the prefix - the XML document author is free to pick whatever prefix they want:

       digester.setRuleNamespaceURI("http://www.mycompany.com/MyNamespace");
       

3. Add the rules that correspond to this namespace, in the usual way, by calling methods like addObjectCreate() or addSetProperties(). In the matching patterns you specify, use only the local name portion of the elements (i.e. the part after the prefix and associated colon (":") character:

       digester.addObjectCreate("foo/bar", "com.mycompany.MyFoo");
       digester.addSetProperties("foo/bar");
       

4. Repeat the previous two steps for each additional public namespace URI that should be recognized on this Digester run.

Now, consider that you might wish to digest the following document, using the rules that were set up in the steps above:

<m:foo
   xmlns:m="http://www.mycompany.com/MyNamespace"
   xmlns:y="http://www.yourcompany.com/YourNamespace">

  <m:bar name="My Name" value="My Value"/>

  <y:bar id="123" product="Product Description"/>L

</x:foo>

Note that your object create and set properties rules will be fired for the first occurrence of the bar element, but not the second one. This is because we declared that our rules only matched for the particular namespace we are interested in. Any elements in the document that are associated with other namespaces (or no namespaces at all) will not be processed. In this way, you can easily create rules that digest only the portions of a compound document that they understand, without placing any restrictions on what other content is present in the document.

You might also want to look at Encapsulated Rule Sets if you wish to reuse a particular set of rules, associated with a particular namespace, in more than one application context.

Using Namespace Prefixes In Pattern Matching

Using rules with namespaces is very useful when you have orthogonal rulesets. One ruleset applies to a namespace and is independent of other rulesets applying to other namespaces. However, if your rule logic requires mixed namespaces, then matching namespace prefix patterns might be a better strategy.

When you set the NamespaceAware property to false, digester uses the qualified element name (which includes the namespace prefix) rather than the local name as the patten component for the element. This means that your pattern matches can include namespace prefixes as well as element names. So, rather than create namespace-aware rules, create pattern matches including the namespace prefixes.

For example, (with NamespaceAware false), the pattern 'foo:bar' will match a top level element named 'bar' in the namespace with (local) prefix 'foo'.

Limitations of Digester Namespace support

Digester does not provide general "xpath-compliant" matching; only the namespace attached to the last element in the match path is involved in the matching process. Namespaces attached to parent elements are ignored for matching purposes.

Pluggable Rules Processing

By default, Digester selects the rules that match a particular pattern of nested elements as described under Element Matching Patterns. If you prefer to use different selection policies, however, you can create your own implementation of the org.apache.commons.digester.Rules interface, or subclass the corresponding convenience base class org.apache.commons.digester.RulesBase. Your implementation of the match() method will be called when the processing for a particular element is started or ended, and you must return a List of the rules that are relevant for the current nesting pattern. The order of the rules you return is significant, and should match the order in which rules were initally added.

Your policy for rule selection should generally be sensitive to whether Namespace Aware Parsing is taking place. In general, if namespaceAware is true, you should select only rules that:

• Are registered for the public namespace URI that corresponds to the prefix being used on this element.
• Match on the "local name" portion of the element (so that the document creator can use any prefix that they like).

ExtendedBaseRules

ExtendedBaseRules, adds some additional expression syntax for pattern matching to the default mechanism, but it also executes more slowly. See the JavaDocs for more details on the new pattern matching syntax, and suggestions on when this implementation should be used. To use it, simply do the following as part of your Digester initialization:

  Digester digester = ...
  ...
  digester.setRules(new ExtendedBaseRules());
  ...

RegexRules

RegexRules is an advanced Rules implementation which does not build on the default pattern matching rules. It uses a pluggable RegexMatcher implementation to test if a path matches the pattern for a Rule. All matching rules are returned (note that this behaviour differs from longest matching rule of the default pattern matching rules). See the Java Docs for more details.

Example usage:

  Digester digester = ...
  ...
  digester.setRules(new RegexRules(new SimpleRegexMatcher()));
  ...

RegexMatchers

Digester ships only with one RegexMatcher implementation: SimpleRegexMatcher. This implementation is unsophisticated and lacks many good features lacking in more power Regex libraries. There are some good reasons why this approach was adopted. The first is that SimpleRegexMatcher is simple, it is easy to write and runs quickly. The second has to do with the way that RegexRules is intended to be used.

There are many good regex libraries available. (For example Jakarta ORO, Jakarta Regex, GNU Regex and Java 1.4 Regex) Not only do different people have different personal tastes when it comes to regular expression matching but these products all offer different functionality and different strengths.

The pluggable RegexMatcher is a thin bridge designed to adapt other Regex systems. This allows any Regex library the user desires to be plugged in and used just by creating one class. Digester does not (currently) ship with bridges to the major regex (to allow the dependencies required by Digester to be kept to a minimum).

WithDefaultsRulesWrapper

WithDefaultsRulesWrapper allows default Rule instances to be added to any existing Rules implementation. These default Rule instances will be returned for any match for which the wrapped implementation does not return any matches.

For example,

    Rule alpha;
    ...
    WithDefaultsRulesWrapper rules = new WithDefaultsRulesWrapper(new BaseRules());
    rules.addDefault(alpha);
    ...
    digester.setRules(rules);
    ...

WithDefaultsRulesWrapper follows the Decorator pattern.

Encapsulated Rule Sets

All of the examples above have described a scenario where the rules to be processed are registered with a Digester instance immediately after it is created. However, this approach makes it difficult to reuse the same set of rules in more than one application environment. Ideally, one could package a set of rules into a single class, which could be easily loaded and registered with a Digester instance in one easy step.

The RuleSet interface (and the convenience base class RuleSetBase) make it possible to do this. In addition, the rule instances registered with a particular RuleSet can optionally be associated with a particular namespace, as described under Namespace Aware Processing.

An example of creating a RuleSet might be something like this:

public class MyRuleSet extends RuleSetBase {

  public MyRuleSet() {
    this("");
  }

  public MyRuleSet(String prefix) {
    super();
    this.prefix = prefix;
    this.namespaceURI = "http://www.mycompany.com/MyNamespace";
  }

  protected String prefix = null;

  public void addRuleInstances(Digester digester) {
    digester.addObjectCreate(prefix + "foo/bar",
      "com.mycompany.MyFoo");
    digester.addSetProperties(prefix + "foo/bar");
  }

}

You might use this RuleSet as follow to initialize a Digester instance:

  Digester digester = new Digester();
  ... configure Digester properties ...
  digester.addRuleSet(new MyRuleSet("baz/"));

A couple of interesting notes about this approach:

• The application that is using these rules does not need to know anything about the fact that the RuleSet being used is associated with a particular namespace URI. That knowledge is emedded inside the RuleSet class itself.
• If desired, you could make a set of rules work for more than one namespace URI by providing constructors on the RuleSet to allow this to be specified dynamically.
• The MyRuleSet example above illustrates another technique that increases reusability -- you can specify (as an argument to the constructor) the leading portion of the matching pattern to be used. In this way, you can construct a Digester that recognizes the same set of nested elements at different nesting levels within an XML document.

Using Named Stacks For Inter-Rule Communication

Digester is based on Rule instances working together to process xml. For anything other than the most trival processing, communication between Rule instances is necessary. Since Rule instances are processed in sequence, this usually means storing an Object somewhere where later instances can retrieve it.

Digester is based on SAX. The most natural data structure to use with SAX based xml processing is the stack. This allows more powerful processes to be specified more simply since the pushing and popping of objects can mimic the nested structure of the xml.

Digester uses two basic stacks: one for the main beans and the other for parameters for method calls. These are inadequate for complex processing where many different Rule instances need to communicate through different channels.

In this case, it is recommended that named stacks are used. In addition to the two basic stacks, Digester allows rules to use an unlimited number of other stacks referred to by an identifying string (the name). (That's where the term named stack comes from.) These stacks are accessed through calls to:

• void push(String stackName, Object value)
• Object pop(String stackName)
• Object peek(String stackName)

Note: all stack names beginning with org.apache.commons.digester are reserved for future use by the Digester component. It is also recommended that users choose stack names prefixed by the name of their own domain to avoid conflicts with other Rule implementations.

Registering DTDs

Brief (But Still Too Long) Introduction To System and Public Identifiers

A definition for an external entity comes in one of two forms:

1. SYSTEM system-identifier
2. PUBLIC public-identifier system-identifier

The system-identifier is an URI from which the resource can be obtained (either directly or indirectly). Many valid URIs may identify the same resource. The public-identifier is an additional free identifier which may be used (by the parser) to locate the resource.

In practice, the weakness with a system-identifier is that most parsers will attempt to interprete this URI as an URL, try to download the resource directly from the URL and stop the parsing if this download fails. So, this means that almost always the URI will have to be an URL from which the declaration can be downloaded.

URLs may be local or remote but if the URL is chosen to be local, it is likely only to function correctly on a small number of machines (which are configured precisely to allow the xml to be parsed). This is usually unsatisfactory and so a universally accessable URL is preferred. This usually means an internet URL.

To recap, in practice the system-identifier will (most likely) be an internet URL. Unfortunately downloading from an internet URL is not only slow but unreliable (since successfully downloading a document from the internet relies on the client being connect to the internet and the server being able to satisfy the request).

The public-identifier is a freely defined name but (in practice) it is strongly recommended that a unique, readable and open format is used (for reasons that should become clear later). A Formal Public Identifier (FPI) is a very common choice. This public identifier is often used to provide a unique and location independent key which can be used to subsistute local resources for remote ones (hint: this is why ;).

By using the second (PUBLIC) form combined with some form of local catalog (which matches public-identifiers to local resources) and where the public-identifier is a unique name and the system-identifier is an internet URL, the practical disadvantages of specifying just a system-identifier can be avoided. Those external entities which have been store locally (on the machine parsing the document) can be identified and used. Only when no local copy exists is it necessary to download the document from the internet URL. This naming scheme is recommended when using Digester.

External Entity Resolution Using Digester

SAX factors out the resolution of external entities into an EntityResolver. Digester supports the use of custom EntityResolver but ships with a simple internal implementation. This implementation allows local URLs to be easily associated with public-identifiers.

For example:

    digester.register("-//Example Dot Com //DTD Sample Example//EN", "assets/sample.dtd");

will make digester return the relative file path assets/sample.dtd whenever an external entity with public id -//Example Dot Com //DTD Sample Example//EN is needed.

Note: This is a simple (but useful) implementation. Greater sophistication requires a custom EntityResolver.

Troubleshooting

Debugging Exceptions

Digester is based on SAX. Digestion throws two kinds of Exception:

• java.io.IOException
• org.xml.sax.SAXException

The first is rarely thrown and indicates the kind of fundemental IO exception that developers know all about. The second is thrown by SAX parsers when the processing of the XML cannot be completed. So, to diagnose the cause a certain familiarity with the way that SAX error handling works is very useful.

Diagnosing SAX Exceptions

This is a short, potted guide to SAX error handling strategies. It's not intended as a proper guide to error handling in SAX.

When a SAX parser encounters a problem with the xml (well, ok - sometime after it encounters a problem) it will throw a SAXParseException. This is a subclass of SAXException and contains a bit of extra information about what exactly when wrong - and more importantly, where it went wrong. If you catch an exception of this sort, you can be sure that the problem is with the XML and not Digester or your rules. It is usually a good idea to catch this exception and log the extra information to help with diagnosing the reason for the failure.

General SAXException instances may wrap a causal exception. When exceptions are throw by Digester each of these will be wrapped into a SAXException and rethrown. So, catch these and examine the wrapped exception to diagnose what went wrong.

Frequently Asked Questions

• Why do I get warnings when using a JAXP 1.1 parser?

  If you're using a JAXP 1.1 parser, you might see the following warning (in your log):

  [WARN] Digester - -Error: JAXP SAXParser property not recognized: http://java.sun.com/xml/jaxp/properties/schemaLanguage
  

  This property is needed for JAXP 1.2 (XML Schema support) as required for the Servlet Spec. 2.4 but is not recognized by JAXP 1.1 parsers. This warning is harmless.

• Why Doesn't Schema Validation Work With Parser XXX Out Of The Box?

  Schema location and language settings are often need for validation using schemas. Unfortunately, there isn't a single standard approach to how these properties are configured on a parser. Digester tries to guess the parser being used and configure it appropriately but it's not infallible. You might need to grab an instance, configure it and pass it to Digester.

  If you want to support more than one parser in a portable manner, then you'll probably want to take a look at the org.apache.commons.digester.parsers package and add a new class to support the particular parser that's causing problems.

• Help! I'm Validating Against Schema But Digester Ignores Errors!

  Digester is based on SAX. The convention for SAX parsers is that all errors are reported (to any registered ErrorHandler) but processing continues. Digester (by default) registers its own ErrorHandler implementation. This logs details but does not stop the processing (following the usual convention for SAX based processors).

  This means that the errors reported by the validation of the schema will appear in the Digester logs but the processing will continue. To change this behaviour, call digester.setErrorHandler with a more suitable implementation.

• Where Can I Find Example Code?

  Digester ships with a sample application: a mapping for the Rich Site Summary format used by many newsfeeds. Download the source distribution to see how it works.

  Digester also ships with a set of examples demonstrating most of the features described in this document. See the "src/examples" subdirectory of the source distribution.

• When Are You Going To Support Rich Site Summary Version x.y.z?

  The Rich Site Summary application is intended to be a sample application. It works but we have no plans to add support for other versions of the format.

  We would consider donations of standard digester applications but it's unlikely that these would ever be shipped with the base digester distribution. If you want to discuss this, please post to commons dev mailing list

Extensions

Three extension packages are included within the Digester distribution. These provide extra functionality extending the core Digester concepts. Detailed descriptions are contained within their own package documentation.

• plugins provides a framework for the easy dynamic addition of rules during a Digestion. Rules can trigger the dynamic addition of other rules in an intuitive fashion.
• substitution provides for manipulation of attributes and element body text before it is processed by the rules.
• xmlrules package contains a system allowing digester rule configurations to be specifed through an xml file.

Known Limitations

Accessing Public Methods In A Default Access Superclass

There is an issue when invoking public methods contained in a default access superclass. Reflection locates these methods fine and correctly assigns them as public. However, an IllegalAccessException is thrown if the method is invoked.

MethodUtils contains a workaround for this situation. It will attempt to call setAccessible on this method. If this call succeeds, then the method can be invoked as normal. This call will only succeed when the application has sufficient security privilages. If this call fails then a warning will be logged and the method may fail.

Digester uses MethodUtils and so there may be an issue accessing methods of this kind from a high security environment. If you think that you might be experiencing this problem, please ask on the mailing list.

Digester aims to support the widest range possible of parsers. Unfortunately, there are a few parser settings which have not been standardized. In most cases, the best practice is for the user to configure the parser themselves and pass it to Digester to use.

There are a few reasonable exceptions which Digester makes to this general rule. There are a small number of common use cases where insisting that the user configure the parser may reduce the portability of applications using Digester. These are outlined below.

Validating With Schema

When validating using schemas (rather than DTDs), settings for schema language and schema location are commonly needed. Unfortunately, there is a lack of standardization for these settings. In particular, for older versions of Xerces, these are set differently from newer versions.

In order to aid portability for this common use case, Digester uses the classes in this package (together with ParserFeatureSetterFactory) to guess the parser and set these properties appropriately. The aim is for Digester to automagically recognize and configure each parser. Help would be gratefully appreciated to maintain and improve the support in this area.

Provides an easy mechanism whereby new digestion rules can be added dynamically during a digestion.

Introduction.

• Apache log4j allows user-provided "Appender" classes to be specified in its configuration file
• Apache Avalon allows "components" of a user-specified class
• Apache Ant allows custom tasks to be defined

An Example

Given the following digester rules in the main "parsing" application:

        Digester digester = new Digester();
        PluginRules rc = new PluginRules();
        digester.setRules(rc);
        
        digester.addObjectCreate("pipeline", Pipeline.class);
        
        digester.addCallMethod("pipeline/source", "setSource", 1);
        digester.addCallParam("pipeline/source", 0, "file");
        
        PluginCreateRule pcr = new PluginCreateRule(Transform.class);
        digester.addRule("pipeline/transform", pcr);
        digester.addSetNext("pipeline/transform", "setTransform");
        
        digester.addCallMethod("pipeline/destination", "setDest", 1);
        digester.addCallParam("pipeline/destination", 0, "file");

        digester.parse(filename);

the following input can be processed:

    <pipeline>
      <source file="input.txt"/>
      <transform plugin-class="SubstituteTransform">
        <from>changeme</from>
        <to>changed</to>
      </transform>
      <destination file="output.txt"/>
    </pipeline>

Note that the "SubstituteTransform" class is not hard-wired into the application, and also that this class is configuring itself from the same configuration file.

The user can specify any class they like here, and (provided that class follows the plugins conventions) it can use any Digester functionality to process the configuration data within the transform tag and its subtags.

The original application simply defined a "plugin point" of "pipeline/transform" at which user classes could be plugged in. However it did not specify what classes were permitted, other than that they must implement the Transform interface. It is the input file which has defined exactly which class should be instantiated when the transform element is encountered, and furthermore the "plugin" class itself has dynamically added rules for parsing elements nested within itself.

A class used as a plugin may dynamically add its own rules to the digester, in order to process its attributes and any subtags in any manner it wishes. This may be done by several mechanisms, including:

• declaring a method public static void addRules(Digester d, String pattern) on the class being "plugged in", or
• providing a separate "rule info" class, somewhat in the spirit of "BeanInfo" classes for java beans, or
• providing an xmlrules file which defines the associated parsing rules.

In the example above, an end user may create their own classes which implement the required Transform interface, then cause these custom classes to be used instead of, or in addition to, classes distributed with the application.

Plugin Declarations

The plugin class can be declared once:

  <plugin id="widget" class="com.acme.Widget"/>

  <sometag plugin-id="widget" ... >

Suggested Applications

Note also that plugged-in classes can themselves allow user-defined classes to be plugged in within their configuration. This allows a very simple framework to be extended almost without limit by the end user.

Terminology

The term "plugin point" refers to a pattern associated with a PluginCreateRule. An xml element matching that pattern is expected to have a plugin-id attribute (but see note on "default plugins" elsewhere in this document).

Limitations

An instance of "PluginRules" must be used as the Rules implementation for the Digester (see example). However a PluginRules can use any other Rules implementation as its rule-matching engine, so this is not a significant issue. Plugged-in classes may only use the default RulesBase matching for the rules they add dynamically.

For technical reasons, a single instance of PluginCreateRule cannot currently be associated with multiple patterns; multiple instances are required. This is not expected to be a problem.

Performance

Processing elements which match patterns added dynamically by plugin classes does have a performance impact, but not excessively so.

Alternatives

• With xmlrules, the full set of parsing rules for the whole configuration file is exposed. This is good for developers, but in most cases both too complex and too dangerous to require end users to edit directly.
• Using xmlrules requires a fair level of knowledge of the Apache Digester. How an end user (not a plugin developer) can use plugins can be explained in about 3 paragraphs.

How to write plugin classes

Well, if the class has a no-argument constuctor, and only simple configuration needs that can be met by a SetPropertiesRule, then no changes need to be made at all.

In other circumstances, you may either define an "addRules" method on the class which adds any necessary rules to the digester, a separate class containing that information, or write an xmlrules-format file defining the necessary rules. In the "separate rule info class" approach, the class containing the rule info may have any name of your choice, but the original class + "RuleInfo" is recommended.

Here is the addRules method on class SubstituteTransform, from the example:

    public static void addRules(Digester d, String pathPrefix) {
        d.addCallMethod(pathPrefix+"/from", "setFrom", 0);
        d.addCallMethod(pathPrefix+"/to", "setTo", 0);
    }

If a plugin class does not define an "addRules" method, and the plugin declaration does not associate a rule info class with it, then the plugins module will define a "SetPropertiesRule" by default. However if any custom rules are defined for the plugin class, then that implementation is required to define a SetPropertiesRule for itself if it desires one.

Note that when adding any rules, the pattern passed to the digester must start with the pathPrefix provided. A plugin cannot define rules with absolute paths. And as defined in the limitations, the pattern should not include any wildcard characters.

Other features

In situations where a user might want to specify a custom class, but will often want "default" behaviour, a PluginCreateRule can specify a default class. If the user then omits the "plugin-id" attribute on the matching xml element, an instance of the default class will be created.

This package contains "rule-finding" strategy classes, and their associated "helper" loader classes.

Note that you do not need to understand or deal with any of the classes in this package in order to use the plugins functionality. If you wish to use plugins functionality in non-english languages and therefore want to change the attribute names used on plugin declaration tags ("id", "file", etc) then you will need some familiarity with this package. Otherwise, this package is only relevant to people really wishing to tweak plugins in unexpected ways. If this is the case, come and talk to us on the digester email lists as we would be interested in knowing about your requirements.

When the plugins module is being used and the input xml indicates that a specific plugin class is to be instantiated, that class may then wish to configure itself from the xml attributes on that tag or xml attributes and elements nested within that tag.

The question is: how is the digester going to figure out where the plugin keeps its custom rules which are to be applied to the xml within that plugin tag?

Well, the answer is that there is a list of "rule finding strategies", generally containing an instance of each of the Finder classes in this package in a specific order. The strategies provided here should satisfy just about everyone, but if they don't you can add extra strategies if desired.

A RuleFinder is essentially a "strategy" or "algorithm" for finding the dynamic rules associated with a plugin class. When a plugin declaration is encountered in the input xml, the PluginContext object is asked for the list of RuleFinder objects, then each RuleFinder instance in turn is passed the declaration parameters, and asked "are you able to locate custom parsing rules for this declaration?". When one can, it returns a RuleLoader instance which is remembered. When the input xml indicates that an instance of the declared plugin class is to be created, that RuleLoader is invoked to temporarily add the relevant custom rules to the Digester in order to map xml attributes/elements/etc into the instantiated plugin object. Once the end of the plugin tag is encountered, those temporary rules are removed. This repeats each time the input xml indicates that an instance of a plugin class is to be instantiated.

If the plugin is declared "inline", using the "plugin-class" attribute instead of using "plugin-id" to reference a previous declaration then the process is exactly the same, except that the RuleFinder objects don't have any user-provided attribute "hints" to tell them where the custom rules are.

The RuleFinder list is carefully ordered; classes which look at the user-provided data in the declaration come first, and classes which look in "well-known places" come later so that users can override default behaviour by providing the appropriate tags on the plugin declaration.

See the javadoc on the different Finder classes for information on what each does, and what attribute (if any) it looks for in the declaration.

Example usage of Digester to parse XML documents compatible with the Rich Site Summary format used by many newsfeeds.

The class org.apache.commons.digester.Substitutor defines an abstract interface for mechanisms which manipulate xml attributes and body text. The Digester method setSubstitutor can be used to define a concrete substitutor that will be applied to the data before it is passed to the matching rules.

This package provides some useful concrete implementations of the abstract Substitutor class. In particular, it provides an implementation that allows the application to define "variables" which the input data can reference using a syntax such as "${user.name}".

Here's an example of setting up the VariableSubstitutor:

  // set up the variables the input xml can reference
  Map vars = new HashMap();
  vars.put("user.name", "me");
  vars.put("os", "Linux");
  
  // map ${varname} to the entries in the var map
  MultiVariableExpander expander = new MultiVariableExpander();
  expander.addSource("$", vars);

  // allow expansion in both xml attributes and element text
  Substitutor substitutor = new VariableSubstitutor(expander);

  Digester digester = new Digester();
  digester.setSubstitutor(substitutor);

The xmlrules package provides for XML-based definition of rules for Digester. This improves maintainability of Java code, as rules are now defined in XML and read into Digester at run-time.

Introduction

This is a brief overview of the digester-rules-in-XML feature. Briefly, this feature lets you define Digester rules in XML, instead of creating and initializing the Rules objects programmatically, which can become tedious. In addition, it allows for including of one XML rules file within another, inclusion of programmatically created rule sets within an XML file (via reflection), and recursively nested matching pattern specifications.

Overview of digester-rules.dtd

A DTD, named digester-rules.dtd has been defined to help in the understanding of how the loader operates.

The DTD is distributed in the commons-digester.jar. It can be found at org/apache/commons/digester/xmlrules/digester-rules.dtd. It is not available for download from the Apache website since users are best advised to use a copy stored on their local system.

Digester input documents wishing to cite this DTD should include the following DOCTYPE declaration:

  <!DOCTYPE digester-rules PUBLIC
   "-//Jakarta Apache //DTD digester-rules XML V1.0//EN"
   "digester-rules.dtd">

Rule elements:

The DTD defines an element type corresponding to each predefined Digester rule. Each rule element type includes attributes for values needed to initialize the rule, and an optional pattern attribute specifying the pattern to associate with the rule.

The DigesterLoader adds the rules to the digester in the order in which they occur in the XML.

The use of each rule element type should be self-explanatory, if you compare them to the API documentation for the Digester rules classes.

Defining matching patterns:

The matching pattern is a simple, xpath-like string which the Digester uses to determine which elements to apply each rule to. See the Digester documentation for more details.
There are two methods for associating patterns to rules in the XML file. One is for each rule element to directly define its pattern in a pattern attribute. An example would like something like:

      <digester-rules>
        <object-create-rule pattern="*/foo" classname="Foo"/>
        <set-properties-rule pattern="*/foo"/>
      </digester-rules>

       <digester-rules>
         <pattern value="*/foo">
           <object-create-rule classname="Foo"/>
           <set-properties-rule/>
         </pattern>
       </digester-rules>

       <digester-rules>
         <pattern value="*/foo">
           <pattern value="bar">
             <object-create-rule classname="Foobar"/>
             <set-properties-rule/>
           </pattern>
         </pattern>
       </digester-rules>

       <digester-rules>
         <pattern value="*/foo">
           <object-create-rule pattern="bar" classname="Foobar"/>
           <set-properties-rule pattern="bar"/>
         </pattern>
       </digester-rules>

Including rules XML files within other rules XML files:

The <include> element lets you include one rules file within another. With respect to pattern concatenation, the DigesterLoader behaves as if the include file was 'macro-expanded'. Example:

      File rules1.xml:
         <?xml version="1.0"?>
         <!DOCTYPE digester-rules SYSTEM "digester-rules.dtd">

         <digester-rules>
           <pattern value="root/foo">
             <object-create-rule classname="Foo"/>

             <include path="rules2.xml"/>
           </pattern>
         </digester-rules>


      File rules2.xml:
         <?xml version="1.0"?>
         <!DOCTYPE digester-rules SYSTEM "digester-rules.dtd">

         <digester-rules>
           <pattern value="bar">
             <object-create-rule classname="Bar"/>
           </pattern>
         </digester-rules>

Including programmatically-created rules:

Sometimes rules cannot be easily defined via XML. Rule sets that are created programmatically can still be included within a digester-rules XML file. This is done by using an <include> element with a class attribute, containing the name of a class that implements org.apache.commons.digester.xmlrules.DigesterRulesSource. This interface defines one method, getRules(Digester), which creates rules and adds them to the supplied Digester. The pattern concatenation works exactly as if the rules had been included from an XML file. Example:

      File rules3.xml:
         <?xml version="1.0"?>
         <!DOCTYPE digester-rules SYSTEM "digester-rules.dtd">

         <digester-rules>
           <pattern value="root/foo">
             <object-create-rule classname="Foo"/>

             <include class="BarRuleCreator"/>
           </pattern>
         </digester-rules>

          public class BarRuleCreator implements DigesterRulesSource {
              public void getRules(Digester digester) {
                  digester.addObjectCreate("bar", "Bar");
              }
          }

Creating a digester from XML:

FromXmlRuleSet is a RuleSet implementation that initializes its Digester from rules defined in an XML file. The path to the XML file is passed to constructor.

Alternatively, the convenience class DigesterLoader defines a static method, Digester createDigester(String rulesXml) throws DigesterLoaderException". When passing the name of the file that contains your digester rules, this method returns a Digester instance initialized with the rules.

To add your own rules, you need to:

• Update the DTD
  You should add an element type for your rule. The element should have an attribute corresponding to each of the rule's initialization parameters.
• Define an ObjectCreationFactory
• Extend DigesterRuleParser
DigesterRuleParser is a RuleSet for parsing a rules XML file. You should extend this, and override the addRuleInstances() method to add the rules for parsing your new element. Look in DigesterRuleParser.java to see how its done.