| <?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 xmlns="http://maven.apache.org/XDOC/2.0" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd"> |
| |
| <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 -> |
| 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.</p> |
| |
| |
| </section> |
| |
| |
| <section name="Documentation"> |
| |
| <p>User documentation is available in the website, you can start reading the |
| <a href="http://commons.apache.org/digester/commons-digester-3.0/core.html">Core APIs</a>.</p> |
| |
| <p>The <a href="http://commons.apache.org/digester/commons-digester-3.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 3.0 Release (Still in sandbox, not released yet)"> |
| <p> |
| The Digester 3.0 is an almost complete rewrite of the original Digester implementation, which offers: |
| </p> |
| <ul> |
| <li> |
| A universal loader: core features and extensions became not so easy to maintain, since every contribution was created |
| with a different approach; a fresh new architecture is able to load modules that allow users write and include easily |
| their own extensions; |
| </li> |
| <li> |
| Reusability of Digester configurations: what was missing is a way to |
| <i>describe</i> |
| how the Digester instances have to be built and not how to set rules given an existing instance; |
| </li> |
| <li> |
| Rules are now expressed via EDSL: the key feature of Digester3 is expressing rule bindings using a fluent APIs |
| collection, that speak more in English rather than in a programming language; |
| </li> |
| <li> |
| Improved errors reporting: rules binding debug operations have made easier, a detailed errors list of wrong binding is |
| reported just when the loader attempts to create a new Digester instance, and not when running it. |
| </li> |
| </ul> |
| <p><em>Acknowledgements</em>: The Digester 3 has been inspired by special people:</p> |
| <ul> |
| <li>Rahul Akolkar, for mentoring;</li> |
| <li> |
| James Carman, who had the initial idea of building a Digester with fluent APIs; |
| </li> |
| <li>Matt Benson, for having influenced on DSL;</li> |
| <li> |
| Daniele Testa [mrwolfgraphics AT gmail DOT com], who provided the Digester3 logo. |
| </li> |
| </ul> |
| </subsection> |
| |
| |
| <subsection name="Digester 2.1 Release (September 2010)"> |
| <p> |
| Digester 2.1 is a minor release with new features, a new <code>annotations</code> package |
| adds facilities to configure the Digester using the Java5 language meta-data annotations, |
| allowing Digester instances creation introspecting the target POJOs, using a provided set |
| of annotations. New projects are encouraged to use this release of digester. |
| <br/> |
| There are breaking changes from Digester 2.0, see release notes in detail before choosing |
| to upgrade. |
| <br/> |
| There is no urgency for existing projects to upgrade; Digester 2.0 has proven to be a |
| stable release. |
| </p> |
| <p> |
| Digester 2.1 <b>requires a minimum of JDK 1.5</b>. |
| </p> |
| <p> |
| The recommended dependency set for Digester 2.1 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.3</td> |
| </tr> |
| </table> |
| <p> |
| It is also possible to use Logging 1.0.x or BeanUtils 1.8.0 instead. |
| </p> |
| </subsection> |
| |
| <subsection name='Digester 2.0 Release (January 2009)'> |
| <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 2009)'> |
| <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 1.x versions had 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 include the stable collections ArrayStack class |
| necessary). |
| </p> |
| <p> |
| The recommended dependency set for Digester 1.8.1 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.1 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/digester/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/digester/download_digester.cgi"> |
| the regular download page</a>.</li> |
| <li>Much 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'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 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> |