xdocs/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>

  <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 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 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.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>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>
	<?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 ->
	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 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 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.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>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>