| <?xml version="1.0"?> |
| |
| <document> |
| |
| <properties> |
| <title>Commons</title> |
| <author email="commons-dev@jakarta.apache.org">Commons Documentation Team</author> |
| </properties> |
| |
| <body> |
| |
| <section name="The Digester Component"> |
| |
| <p>Many Jakarta 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 -> |
| 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://jakarta.apache.org/commons/digester/current/docs/apidocs/index.html">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://jakarta.apache.org/commons/digester/current/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/viewcvs/jakarta/commons/proper/digester/trunk/src/examples/"> |
| the web-based repository browser</a> web site, or can use subversion to |
| download the files. |
| </p> |
| |
| </section> |
| |
| |
| <section name="Releases"> |
| <subsection name='Digester 1.7 Release (12 June 2005)'> |
| <p> |
| Digester 1.7 is a minor bugfix and maintenance release. A few small features have been added. |
| New projects are encouraged to use this release of digester, but there is no urgency |
| for existing projects to upgrade; Digester 1.6 has proven to be a stable release. See |
| the release notes for more details. |
| </p> |
| <p> |
| The dependencies for Digester 1.7 are identical to the dependencies for Digester 1.6. |
| </p> |
| <p> |
| Digester has a dependency on |
| <a href='http://jakarta.apache.org/commons/collections'>Commons Collections</a>. |
| This threatens to raise compatibility issues now that two incompatible series of releases exist. |
| Fortunately, this dependency is only upon a single mature class (ArrayStack) and the versions |
| of this class to be found in different versions of the library are binary compatible. |
| Therefore a release from the 2.x series or from the 3.x series of commons collections |
| will do equally well (even though these libraries are incompatible). The dependency can |
| alternatively be satisfied by including the latest BeanUtils release (1.7) |
| (which includes the class). |
| </p> |
| <p> |
| The dependencies neccessary for Digester 1.7 can be summarized as follows: |
| </p> |
| <table> |
| <tr> |
| <th colspan='4'>Compatible Dependency Sets</th> |
| </tr> |
| <tr> |
| <td>Digester</td> |
| <td>+Logging 1.0.x</td> |
| <td>+BeanUtils 1.x</td> |
| <td>+Collections 2.x</td> |
| </tr> |
| <tr> |
| <td>Digester</td> |
| <td>+Logging 1.0.x</td> |
| <td>+BeanUtils 1.x</td> |
| <td>+Collections 3.x</td> |
| </tr> |
| <tr> |
| <td>Digester</td> |
| <td>+Logging 1.0.x</td> |
| <td>+BeanUtils 1.7</td> |
| <td>-</td> |
| </tr> |
| </table> |
| </subsection> |
| <subsection name='Downloading'> |
| <ul> |
| <li>The most recent release is available from apache mirrors via |
| <a href="http://jakarta.apache.org/site/downloads/downloads_commons-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://jakarta.apache.org/site/downloads/downloads_commons-digester.cgi"> |
| the regular download page</a>.</li> |
| <li>Older releases can be found |
| <a href="http://archive.apache.org/dist/jakarta/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/jakarta-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'Reilly article</a> by Timothy M. O'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 Jakarta 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> |