src/site/xdoc/index.xml - commons-digester - Git at Google

 <?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 -&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.</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.2 (December 2011)">
       <p>The Digester 3.2 release is a maintenance release that adds the most innovating feature ever, providing the
       objects <a href="./guide/constructor.html">Constructor</a> feature.</p>
       <p>Take a look at Digester 3.2 release <a href="./changes-report.html#a3.2">changes list</a> for more details.</p>
       <p>Digester 3.2 <b>requires a minimum of JDK 1.5</b>.</p>
       <p>The recommended dependency set for Digester 3.2 is:</p>
       <table>
         <tr>
           <th colspan="4">Recommended Dependency Set</th>
         </tr>
         <tr>
           <td><strong>Digester</strong></td>
           <td>+Logging 1.1.1</td>
           <td>+BeanUtils 1.8.3</td>
           <td>+CGLIB 2.2.2</td>
         </tr>
       </table>
       <p>Since dependencies increased by number, since 3.2 release, Digester is distributed also in a single artifact
       with shaded dependencies.</p>
       <p>Maven users that want to switch over shaded artifact, must use the <code>with-deps</code> classifier:</p>
       <source><![CDATA[<dependency>
   <groupId>org.apache.commons</groupId>
   <artifactId>commons-digester3</artifactId>
   <version>3.2</version>
   <classifier>with-deps</classifier>
 </dependency>]]></source>
     </subsection>

     <subsection name="Digester 3.1 Release (October 2011)">
       <p>The Digester 3.1 release is a maintenance release that adds the
       <a href="./guide/async.html">Asynchronous parser</a> feature.</p>
     </subsection>

     <subsection name="Digester 3.0 Release (July 2011)">
       <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>
 </section>

 <section name="Resources">
  <ul>
   <!-- newest first sounds like a reasonable rule -->
   <li>
     Jul 11, 2011 - The online magazine JaxEnter interviews Commons PMC Member Simone Tripodi asking
     <a href="http://jaxenter.com/what-s-new-in-apache-commons-digester-3-0-36817.html">What's New in Apache Commons Digester 3.0?</a>.
   </li>
   <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>
	<?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.2 (December 2011)">
	<p>The Digester 3.2 release is a maintenance release that adds the most innovating feature ever, providing the
	objects <a href="./guide/constructor.html">Constructor</a> feature.</p>
	<p>Take a look at Digester 3.2 release <a href="./changes-report.html#a3.2">changes list</a> for more details.</p>
	<p>Digester 3.2 <b>requires a minimum of JDK 1.5</b>.</p>
	<p>The recommended dependency set for Digester 3.2 is:</p>
	<table>
	<tr>
	<th colspan="4">Recommended Dependency Set</th>
	</tr>
	<tr>
	<td><strong>Digester</strong></td>
	<td>+Logging 1.1.1</td>
	<td>+BeanUtils 1.8.3</td>
	<td>+CGLIB 2.2.2</td>
	</tr>
	</table>
	<p>Since dependencies increased by number, since 3.2 release, Digester is distributed also in a single artifact
	with shaded dependencies.</p>
	<p>Maven users that want to switch over shaded artifact, must use the <code>with-deps</code> classifier:</p>
	<source><![CDATA[<dependency>
	<groupId>org.apache.commons</groupId>
	<artifactId>commons-digester3</artifactId>
	<version>3.2</version>
	<classifier>with-deps</classifier>
	</dependency>]]></source>
	</subsection>

	<subsection name="Digester 3.1 Release (October 2011)">
	<p>The Digester 3.1 release is a maintenance release that adds the
	<a href="./guide/async.html">Asynchronous parser</a> feature.</p>
	</subsection>

	<subsection name="Digester 3.0 Release (July 2011)">
	<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>
	</section>

	<section name="Resources">
	<ul>
	<!-- newest first sounds like a reasonable rule -->
	<li>
	Jul 11, 2011 - The online magazine JaxEnter interviews Commons PMC Member Simone Tripodi asking
	<a href="http://jaxenter.com/what-s-new-in-apache-commons-digester-3-0-36817.html">What's New in Apache Commons Digester 3.0?</a>.
	</li>
	<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>