1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
<?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 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'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>
|
