Simplify XML file processing with the Jakarta Commons Digester

How to use Digester to parse XML configuration files

By Erik Swenson, JavaWorld.com, 10/25/02

The Apache Jakarta site is home to many well-known Java open source projects, including Tomcat, Ant, and log4j. A lesser-known subproject of Jakarta is Jakarta Commons, a repository of reusable Java components. These components, such as Commons BeanUtils, Commons DBCP, and Commons Logging, alleviate the pain of some standard programming tasks. This article will focus on the Jakarta Commons Digester, a utility that maps XML files to Java objects.

Note: To use Digester, you must have the following libraries in your classpath: Digester, BeanUtils, Collections, Logging, and an XML parser conforming to SAX (Simple API for XML) 2.0 or JAXP (Java API for XML Parsing) 1.1. Links to all Jakarta Commons components, along with two suitable parsers, Crimson and Xerces, can be found in Resources.

XML parsing overview

Two basic methods parse XML documents. One is the Document Object Model (DOM) method. When parsing an XML document with DOM, the parser reads the entire document and creates a tree-like representation of it. The second method uses SAX and parses XML documents with events. The DOM method, while sometimes easier to implement, is slower and more resource-intensive than SAX. Digester simplifies SAX parsing by providing a higher-level interface to SAX events. This interface hides much of the complexity involved in XML document navigation, allowing developers to concentrate on processing XML data instead of parsing it.

Digester concepts

Digester introduces three important concepts: element matching patterns, processing rules, and the object stack.

Element matching patterns associate XML elements with processing rules. The following example shows the element matching patterns for an XML hierarchy:

<datasources>          'datasources'
  <datasource>         'datasources/datasource'
    <name/>            'datasources/datasource/name'
    <driver/>          'datasources/datasource/driver'  
  </datasource>
  <datasource>         'datasources/datasource'
    <name/>            'datasources/datasource/name'
    <driver/>          'datasources/datasource/driver'  
  </datasource>
</datasources>

Each time a pattern is matched, an associated rule is fired. In the above example, a rule associated with 'datasources/datasource' executes twice.

Processing rules define what happens when Digester matches a pattern. Digester includes predefined processing rules. Custom rules can also be created by subclassing org.apache.commons.digester.Rule.

The object stack makes objects available for manipulation by processing rules. Objects can be added or removed (pushed or popped) from the stack either manually or through processing rules.

Using Digester

Digester is often used to parse XML configuration files. In the following examples, we have an XML configuration file that contains information used to build a DataSources pool. The DataSource is a hypothetical class that has an empty constructor and many get and set methods that take in and return strings.

<?xml version="1.0"?>
<datasources>
  <datasource>
    <name>HsqlDataSource</name>
    <driver>org.hsqldb.jdbcDriver</driver>
    <url>jdbc:hsqldb:hsql://localhost</url>
    <username>sa</username>
    <password></password>
  </datasource>
  <datasource>
    <name>OracleDataSource</name>
    <driver>oracle.jdbc.driver.OracleDriver</driver>
    <url>jdbc:oracle:thin:@localhost:1521:orcl</url>
    <username>scott</username>
    <password>tiger</password>
  </datasource>
</datasources>

To use Digester you must create an instance of the Digester class, push any required objects to the Digester's object stack, add a set of processing rules, and finally parse the file. Here is an example: