<?xml version="1.0"?>
<!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
<document>

 <properties>
  <title>Commons</title>
  <author email="dev@commons.apache.org">Commons Documentation Team</author>
 </properties>

 <body>

<section name="The Digester Component">

<p>Many projects read XML configuration files to provide initialization
of various Java objects within the system.  There are several ways of doing
this, and the <em>Digester</em> component was designed to provide a common
implementation that can be used in many different projects.</p>

<p>Basically, the <em>Digester</em> package lets you configure an XML -&gt;
Java object mapping module, which triggers certain actions called
<em>rules</em> whenever a particular pattern of nested XML elements is
recognized.  A rich set of predefined <em>rules</em> is available for your
use, or you can also create your own.  Advanced features of <em>Digester</em>
include:</p>
<ul>
<li>Ability to plug in your own pattern matching engine, if the standard one
    is not sufficient for your requirements.</li>
<li>Optional namespace-aware processing, so that you can define rules that
    are relevant only to a particular XML namespace.</li>
<li>Encapsulation of <em>Rules</em> into <em>RuleSets</em> that can be
    easily and conveniently reused in more than one application that requires
    the same type of processing.</li>
</ul>


</section>


<section name="Documentation">

<p>User documentation is available as package descriptions within the 
<a href="http://commons.apache.org/digester/commons-digester-2.0/docs/api/">JavaDoc
API documents</a>.  In particular, you should read the package description for 
the <code>org.apache.commons.digester</code> package for detailed information 
on using the package.</p>

<p>The <a href="http://commons.apache.org/digester/commons-digester-2.0/RELEASE-NOTES.txt">
Release Notes</a> document the new features and bug fixes that have been
included in this release.</p>

<p>The "examples" directory in the source code repository contains code which 
demonstrates the basic functionality. In particular, you should read the 
AddressBook example in the "api" subdirectory. You can view the examples
directly from the Subversion repository via <a
href="http://svn.apache.org/viewvc/commons/proper/digester/trunk/src/examples/">
the web-based repository browser</a> web site, or can use subversion to 
download the files.
</p>

<p>For the FAQ and other digester-related information, see
 <a href="http://wiki.apache.org/commons/Digester">the Digester wiki page</a>.
</p>

</section>

<section name="Releases">
    <subsection name='Digester 2.0 Release (January 2008)'>
        <p>
Digester 2.0 is a major release. New projects are encouraged to use this release
of digester. There are breaking changes from Digester 1.8, see release notes
in detail before choosing to upgrade. There is no urgency for existing
projects to upgrade; Digester 1.8 has proven to be a stable release.
        </p>
        <p>
Digester 2.0 <b>requires a minimum of JDK 1.5</b> and no longer requires any
classes from Commons Collections (as Digester 1.8 did).
        </p>
        <p>
The recommended dependency set for Digester 2.0 is:
        </p>
<table>
<tr>
<th colspan='3'>Recommended Dependency Set</th>
</tr>
<tr>
<td>Digester</td>
<td>+Logging 1.1.1</td>
<td>+BeanUtils 1.8.0</td>
</tr>
</table>
        <p>
It is also possible to use Logging 1.0.x or BeanUtils 1.7.0 instead.
        </p>
    </subsection>

    <subsection name='Digester 1.8.1 Release (January 2008)'>
        <p>
Digester 1.8.1 is a minor bugfix and maintenance release. Existing projects
using Digester 1.8 are encouraged to upgrade to the 1.8.1 release. New projects
are encouraged to use Digester 2.0, which requires JDK 1.5. See the release
notes for more details.
        </p>
        <p>
The dependencies for Digester 1.8.1 are identical to the dependencies for Digester 1.8.
        </p>
        <p>
Digester has a dependency on
<a href='http://commons.apache.org/collections'>Commons Collections</a>.
The dependency can alternatively be satisfied by including the latest BeanUtils
releases (1.7.0 or above) (which includes the stable collections ArrayStack class
necessary).
        </p>
        <p>
The recommended dependency set for Digester 1.8 is:
        </p>
<table>
<tr>
<th colspan='3'>Recommended Dependency Set</th>
</tr>
<tr>
<td>Digester</td>
<td>+Logging 1.1.1</td>
<td>+BeanUtils 1.8.0</td>
</tr>
</table>
        <p>
Other compatible dependency sets for Digester 1.8 can be summarized as follows:
        </p>
<table>
<tr>
<th colspan='4'>Compatible Dependency Sets</th>
</tr>
<tr>
<td>Digester</td>
<td>+Logging 1.1.x</td>
<td>+BeanUtils 1.x</td>
<td>+Collections 2.x</td>
</tr>
<tr>
<td>Digester</td>
<td>+Logging 1.1.x</td>
<td>+BeanUtils 1.x</td>
<td>+Collections 3.x</td>
</tr>
</table>
        <p>
It is also possible to use Logging 1.0.x or BeanUtils 1.7.0 instead.
        </p>
    </subsection>
    <subsection name='Downloading'>
 <ul>
  <li>The most recent release is available from apache mirrors via
  <a href="http://commons.apache.org/downloads/download_digester.cgi">
  the regular download page</a>.</li>
  <li>Reasonably recent releases are also available from apache mirrors, via the
  "browse downloads" link at
  <a href="http://commons.apache.org/downloads/download_digester.cgi">
  the regular download page</a>.</li>
  <li>Older releases can be found 
  <a href="http://archive.apache.org/dist/commons/digester/old">
  on the archive site</a>.</li>
 </ul>
   <p>Please remember to verify the MD5 check sums.</p>
    </subsection>
</section>

<section name="Resources">
 <ul>
  <!-- newest first sounds like a reasonable rule -->
  <li>
   <a href="http://wiki.apache.org/commons/Digester">The Apache wiki page for the commons digester component</a>.
  </li>
  <li>
   Jan 6, 2005 - <a href="http://www.onjava.com/pub/a/onjava/2004/12/22/jakarta-gems-1.html">O&apos;Reilly article</a> by Timothy M. O&apos;Brien about jakarta commons in general, including info on Digester.
  </li>
  <li>
   Jun 2, 2003 - <a href="http://www-106.ibm.com/developerworks/java/library/j-lucene/">IBM developerWorks article</a> by Otis Gospodnetic about parsing, indexing and searching XML with Digester and Lucene.
  </li>
  <li>
   Oct 25, 2002 - <a href="http://www.javaworld.com">JavaWorld</a> has an 
   article on Digester entitled <a href="http://www.javaworld.com/javaworld/jw-10-2002/jw-1025-opensourceprofile.html">
   Simplify XML file processing with the Apache Commons Digester</a>.
  </li>
  <li>
   Oct 23, 2002 - <a href="http://www.onjava.com">OnJava</a> has an article 
   on Digester entitled 
   <a href="http://www.onjava.com/pub/a/onjava/2002/10/23/digester.html">
   Learning and using Jakarta Digester</a>.</li>
 </ul>
</section>

</body>
</document>
