General Information

ASF

Documentation for org.apache.commons.digester3.xmlrules

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-digester3-3.0.jar. It can be found at
org/apache/commons/digester3/xmlrules/digester-rules.dtd.

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

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 Digesterdocumentation 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:

In the above example, an ObjectCreateRule is created and
associated with the pattern "*/foo"; then a SetPropertiesRule is
created and associated with the pattern "*/foo".

The other method is to nest rules elements inside a
<pattern> element. In this way, the same pattern can be
defined for a group of rules. The following example has the same effect as the
previous example:

Note that the url attribute accepts any valid URL, plus the the meta classpath URL,
that points to a any valid resource present in the ClassPath; the ClassLoader used to load the resources
is the same users set to resolve classes during the parse-time.

Parsing rule1.xml would result in a Digester initialized with these
pattern/rule pairs:

Note that the pattern for the bar rule has been prepended with the root/foo
pattern. If rule2.xml was parsed by itself, it would yield a Digester
initialized with this pattern/rule:

bar -> ObjectCreateRule(Bar)

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.digester3.binder.RulesModule.
The pattern concatenation works exactly as if the rules had been included from an XML file,
i.e.:

Apache Commons, Apache Apache Commons Digester, Apache, the Apache feather logo, and the Apache Commons project logos are trademarks of The Apache Software Foundation.
All other marks mentioned may be trademarks or registered trademarks of their respective owners.