You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by sk...@apache.org on 2005/02/21 03:13:52 UTC
svn commit: r154605 -
jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/package.html
Author: skitching
Date: Sun Feb 20 18:13:52 2005
New Revision: 154605
URL: http://svn.apache.org/viewcvs?view=rev&rev=154605
Log:
Update to digester2.0 features/API.
Modified:
jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/package.html
Modified: jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/package.html
URL: http://svn.apache.org/viewcvs/jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/package.html?view=diff&r1=154604&r2=154605
==============================================================================
--- jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/package.html (original)
+++ jakarta/commons/proper/digester/branches/digester2/src/java/org/apache/commons/digester2/package.html Sun Feb 20 18:13:52 2005
@@ -19,9 +19,10 @@
<title>Package Documentation for org.apache.commons.digester Package</title>
</head>
<body bgcolor="white">
-The Digester package provides for rules-based processing of arbitrary
-XML documents.
-<br><br>
+
+<p>The Digester package provides for rules-based processing of arbitrary
+XML documents.</p>
+
<a name="doc.Description"></a>
<div align="center">
<a href="#doc.Depend">[Dependencies]</a>
@@ -29,13 +30,12 @@
<a href="#doc.Properties">[Configuration Properties]</a>
<a href="#doc.Stack">[The Object Stack]</a>
<a href="#doc.Patterns">[Element Matching Patterns]</a>
-<a href="#doc.Rules">[Processing Rules]</a>
+<a href="#doc.Actions">[Processing Actions]</a>
+<a href="#doc.ActionFactory">[The Action Factory]</a>
<a href="#doc.Logging">[Logging]</a>
<a href="#doc.Usage">[Usage Example]</a>
<a href="#doc.Namespace">[Namespace Aware Parsing]</a>
<a href="#doc.Pluggable">[Pluggable Rules Processing]</a>
-<a href="#doc.RuleSets">[Encapsulated Rule Sets]</a>
-<a href="#doc.NamedStacks">[Using Named Stacks For Inter-Rule Communication]</a>
<a href="#doc.RegisteringDTDs">[Registering DTDs]</a>
<a href="#doc.troubleshooting">[Troubleshooting]</a>
<a href="#doc.FAQ">[FAQ]</a>
@@ -46,8 +46,9 @@
<a name="doc.Depend"></a>
<h3>External Dependencies</h3>
-<p>The <em>Digester</em> component is dependent upon implementations of the following
-standard libraries:</p>
+<p>The <em>Digester</em> component is dependent upon implementations of the
+following standard libraries:</p>
+
<ul>
<li><strong>XML Parser</strong> compatible with the JAXP/1.1 specification.
Examples compatible implementations include:
@@ -56,18 +57,16 @@
<li><a href="http://xml.apache.org/xerces-j">Xerces</a> (Version 1.3.1 or later)</li>
</ul></li>
</ul>
-<p>
-It is also dependent on a compatible set of
-<a href='http://jakarta.apache.org/commons'>Jakarta Commons</a> library components:
-</p>
-<blockquote>
- <table border="1" cellspacing="2" cellpadding="3">
- <tr class="a"><th colspan="4">Compatible Dependency Sets</th></tr>
- <tr class="b"><td>Digester</td><td>+Logging 1.0.x</td><td>+BeanUtils 1.x</td><td>+Collections 2.x</td></tr>
- <tr class="a"><td>Digester</td><td>+Logging 1.0.x</td><td>+BeanUtils 1.x</td><td>+Collections 3.x</td></tr>
- <tr class="b"><td>Digester</td><td>+Logging 1.0.x</td><td>+BeanUtils 1.7</td><td>-</td></tr>
- </table>
-</blockquote>
+
+<p>It is also dependent on the following
+<a href='http://jakarta.apache.org/commons'>Jakarta Commons</a>
+library components:</p>
+
+<ul>
+<li>Commons-Logging 1.0.x</li>
+<li>Commons-BeanUtils 1.7</li>
+</ul>
+
<a name="doc.Intro"></a>
<h3>Introduction</h3>
@@ -82,6 +81,7 @@
the developer to focus on the processing to be performed.</p>
<p>In order to use a Digester, the following basic steps are required:</p>
+
<ul>
<li>Create a new instance of the
<code>org.apache.commons.digester.Digester</code> class. Previously
@@ -94,22 +94,22 @@
<li>Optionally, push any desired initial object(s) onto the Digester's
<a href="#doc.Stack">object stack</a>.</li>
<li>Register all of the <a href="#doc.Patterns">element matching patterns</a>
- for which you wish to have <a href="#doc.Rules">processing rules</a>
+ for which you wish to have <a href="#doc.Actions">processing actions</a>
fired when this pattern is recognized in an input document. You may
- register as many rules as you like for any particular pattern. If there
- is more than one rule for a given pattern, the rules will be executed in
- the order that they were listed.</li>
+ register as many actions as you like for any particular pattern. If there
+ is more than one action for a given pattern, the actions will be executed in
+ the order that they were added.</li>
<li>Call the <code>digester.parse()</code> method, passing a reference to the
XML document to be parsed in one of a variety of forms. See the
<a href="Digester.html#parse(java.io.File)">Digester.parse()</a>
documentation for details. Note that you will need to be prepared to
catch any <code>IOException</code> or <code>SAXException</code> that is
thrown by the parser, or any runtime expression that is thrown by one of
- the processing rules.</li>
+ the processing actions.</li>
</ul>
<p>For example code, see <a href="#doc.Usage"> the usage
-examples</a>, and <a href="#doc.FAQ.Examples"> the FAQ </a>. </p>
+examples</a>, and <a href="#doc.FAQ.Examples"> the FAQ </a>.</p>
<a name="doc.Properties"></a>
<h3>Digester Configuration Properties</h3>
@@ -129,56 +129,40 @@
<tr>
<td align="center">classLoader</td>
<td>You can optionally specify the class loader that will be used to
- load classes when required by the <code>ObjectCreateRule</code>
- and <code>FactoryCreateRule</code> rules. If not specified,
- application classes will be loaded from the thread's context
- class loader (if the <code>useContextClassLoader</code> property
- is set to <code>true</code>) or the same class loader that was
- used to load the <code>Digester</code> class itself.</td>
+ load classes when required by the <code>CreateObjectAction</code>
+ and <code>CreateObjectWithFactoryAction</code> actions. If not
+ specified, application classes will be loaded from the thread's
+ context class loader (unless the <code>useContextClassLoader</code>
+ property is set to <code>false</code>) or the same class loader that
+ was used to load the <code>Digester</code> class itself.</td>
</tr>
<tr>
<td align="center">errorHandler</td>
<td>You can optionally specify a SAX <code>ErrorHandler</code> that
is notified when parsing errors occur. By default, any parsing
- errors that are encountered are logged, but Digester will continue
- processing as well.</td>
- </tr>
- <tr>
- <td align="center">namespaceAware</td>
- <td>A boolean that is set to <code>true</code> to perform parsing in a
- manner that is aware of XML namespaces. Among other things, this
- setting affects how elements are matched to processing rules. See
- <a href="#doc.Namespace">Namespace Aware Parsing</a> for more
- information.</td>
- </tr>
- <tr>
- <td align="center">ruleNamespaceURI</td>
- <td>The public URI of the namespace for which all subsequently added
- rules are associated, or <code>null</code> for adding rules that
- are not associated with any namespace. See
- <a href="#doc.Namespace">Namespace Aware Parsing</a> for more
- information.</td>
+ errors that are encountered cause an exception to be thrown, thus
+ terminating any processing.</td>
</tr>
<tr>
- <td align="center">rules</td>
- <td>The <code>Rules</code> component that actually performs matching of
- <code>Rule</code> instances against the current element nesting
- pattern is pluggable. By default, Digester includes a
- <code>Rules</code> implementation that behaves as described in this
- document. See
- <a href="#doc.Pluggable">Pluggable Rules Processing</a> for
+ <td align="center">ruleManager</td>
+ <td>The <code>RuleManager</code> component that actually performs matching
+ of registered patterns against the current xml element path is
+ pluggable. By default, Digester uses the
+ <code>DefaultRuleManager</code> implementation that behaves as
+ described in this document. See
+ <a href="#doc.Pluggable">Pluggable Pattern Matching</a> for
more information.</td>
</tr>
<tr>
- <td align="center">useContextClassLoader</code>
- <td>A boolean that is set to <code>true</code> if you want application
- classes required by <code>FactoryCreateRule</code> and
- <code>ObjectCreateRule</code> to be loaded from the context class
- loader of the current thread. By default, classes will be loaded
- from the class loader that loaded this <code>Digester</code> class.
- <strong>NOTE</strong> - This property is ignored if you set a
- value for the <code>classLoader</code> property; that class loader
- will be used unconditionally.</td>
+ <td align="center">useContextClassLoader</code></td>
+ <td>A boolean that is set to <code>false</code> if you explicitly want
+ to ignore any context-classloader associated with the current thread
+ when application <code>CreateObjectWithFactoryAction</code> or
+ <code>CreateObjectAction</code> need to load classes. By default,
+ classes will be loaded from the classloader explicitly set by the
+ caller (if one exists), then the context-classloader (if one exists),
+ and from the class loader that loaded this <code>Digester</code> class
+ otherwise.
</tr>
<tr>
<td align="center">validating</td>
@@ -199,17 +183,16 @@
registered system identifier (a URL), rather than the one in the
<code>DOCTYPE</code> declaration.</p>
-<p>For example, the Struts framework controller servlet uses the following
+<p>For example, the Struts framework controller servlet could use the following
registration in order to tell Struts to use a local copy of the DTD for the
-Struts configuration file. This allows usage of Struts in environments that
-are not connected to the Internet, and speeds up processing even at Internet
+Struts configuration file. This would allow usage of Struts in environments that
+are not connected to the Internet, and speed up processing even at Internet
connected sites (because it avoids the need to go across the network).</p>
<pre>
- URL url = new URL("/org/apache/struts/resources/struts-config_1_0.dtd");
- digester.register
- ("-//Apache Software Foundation//DTD Struts Configuration 1.0//EN",
- url.toString());
+ digester.registerKnownEntity(
+ "-//Apache Software Foundation//DTD Struts Configuration 1.0//EN",
+ "/org/apache/struts/resources/struts-config_1_0.dtd");
</pre>
<p>As a side note, the system identifier used in this example is the path
@@ -232,12 +215,11 @@
of your application's <code>struts-config.xml</code> file.</p>
<p>To facilitate this usage, the Digester exposes a stack that can be
-manipulated by processing rules that are fired when element matching patterns
-are satisfied. The usual stack-related operations are made available,
-including the following:</p>
+manipulated by processing actions that are fired when the associated patterns
+match the current xml element. The usual stack-related operations are made
+available, including the following:</p>
+
<ul>
-<li><a href="Digester.html#clear()">clear()</a> - Clear the current contents
- of the object stack.</li>
<li><a href="Digester.html#peek()">peek()</a> - Return a reference to the top
object on the stack, without removing it.</li>
<li><a href="Digester.html#pop()">pop()</a> - Remove the top object from the
@@ -246,38 +228,38 @@
object onto the top of the stack.</li>
</ul>
-<p>A typical design pattern, then, is to fire a rule that creates a new object
-and pushes it on the stack when the beginning of a particular XML element is
-encountered. The object will remain there while the nested content of this
-element is processed, and it will be popped off when the end of the element
-is encountered. As we will see, the standard "object create" processing rule
+<p>A typical design pattern, then, is to trigger an action that creates a new
+object and pushes it on the stack when the beginning of a particular XML
+element is encountered. The object will remain there while the nested content
+of this element is processed, and it will be popped off when the end of the
+element is encountered. As we will see, the standard CreateObjectAction
supports exactly this functionalility in a very convenient way.</p>
<p>Several potential issues with this design pattern are addressed by other
features of the Digester functionality:</p>
+
<ul>
<li><em>How do I relate the objects being created to each other?</em> - The
- Digester supports standard processing rules that pass the top object on
+ Digester supports standard processing actions that pass the top object on
the stack as an argument to a named method on the next-to-top object on
- the stack (or vice versa). This rule makes it easy to establish
+ the stack (or vice versa). This action makes it easy to establish
parent-child relationships between these objects. One-to-one and
one-to-many relationships are both easy to construct.</li>
<li><em>How do I retain a reference to the first object that was created?</em>
- As you review the description of what the "object create" processing rule
+ As you review the description of what the CreateObjectAction class
does, it would appear that the first object you create (i.e. the object
created by the outermost XML element you process) will disappear from the
stack by the time that XML parsing is completed, because the end of the
element would have been encountered. However, Digester will maintain a
reference to the very first object ever pushed onto the object stack,
- and will return it to you
- as the return value from the <code>parse()</code> call. Alternatively,
- you can push a reference to some application object onto the stack before
- calling <code>parse()</code>, and arrange that a parent-child relationship
- be created (by appropriate processing rules) between this manually pushed
- object and the ones that are dynamically created. In this way,
- the pushed object will retain a reference to the dynamically created objects
- (and therefore all of their children), and will be returned to you after
- the parse finishes as well.</li>
+ and will return it to you as the return value from the <code>parse()</code>
+ call. Alternatively, you can push a reference to some application object
+ onto the stack before calling <code>parse()</code>, and arrange that a
+ parent-child relationship be created (by appropriate processing actions)
+ between this manually pushed object and the ones that are dynamically
+ created. In this way, the pushed object will retain a reference to the
+ dynamically created objects (and therefore all of their children), and will
+ be returned to you after the parse finishes as well.</li>
</ul>
<a name="doc.Patterns"></a>
@@ -286,194 +268,199 @@
<p>A primary feature of the <code>org.apache.commons.digester.Digester</code>
parser is that the Digester automatically navigates the element hierarchy of
the XML document you are parsing for you, without requiring any developer
-attention to this process. Instead, you focus on deciding what functions you
+attention to this process. Instead, you focus on deciding what actions you
would like to have performed whenver a certain arrangement of nested elements
is encountered in the XML document being parsed. The mechanism for specifying
-such arrangements are called <em>element matching patterns</em>.
+such arrangements are called <em>element matching patterns</em>.</p>
+
+<p>A (pattern, action) pair is referred to as a "rule".</p>
-<p>A very simple element matching pattern is a simple string like "a". This
-pattern is matched whenever an <code><a></code> top-level element is
-encountered in the XML document, no matter how many times it occurs. Note that
-nested <code><a></code> elements will <strong>not</strong> match this
-pattern -- we will describe means to support this kind of matching later.</li>
+<p>A very simple element matching pattern is a simple string like "/a". This
+pattern is matched if-and-only-if the document's root element is
+<code><a></code>.</p>
-<p>The next step up in matching pattern complexity is "a/b". This pattern will
+<p>The next step up in matching pattern complexity is "/a/b". This pattern will
be matched when a <code><b></code> element is found nested inside a
-top-level <code><a></code> element. Again, this match can occur as many
+top-level <code><a></code> element. This match can occur as many
times as desired, depending on the content of the XML document being parsed.
You can use multiple slashes to define a hierarchy of any desired depth that
will be matched appropriately.</p>
-<p>For example, assume you have registered processing rules that match patterns
-"a", "a/b", and "a/b/c". For an input XML document with the following
+<p>For example, assume you have registered processing rules for patterns
+"/a", "/a/b", and "/a/b/c". For an input XML document with the following
contents, the indicated patterns will be matched when the corresponding element
is parsed:</p>
<pre>
- <a> -- Matches pattern "a"
- <b> -- Matches pattern "a/b"
- <c/> -- Matches pattern "a/b/c"
- <c/> -- Matches pattern "a/b/c"
+ <a> -- Matches pattern "/a"
+ <b> -- Matches pattern "/a/b"
+ <c/> -- Matches pattern "/a/b/c"
+ <c/> -- Matches pattern "/a/b/c"
</b>
- <b> -- Matches pattern "a/b"
- <c/> -- Matches pattern "a/b/c"
- <c/> -- Matches pattern "a/b/c"
- <c/> -- Matches pattern "a/b/c"
+ <b> -- Matches pattern "/a/b"
+ <c/> -- Matches pattern "/a/b/c"
+ <c/> -- Matches pattern "/a/b/c"
+ <c/> -- Matches pattern "/a/b/c"
</b>
</a>
</pre>
<p>It is also possible to match a particular XML element, no matter how it is
-nested (or not nested) in the XML document, by using the "*" wildcard character
-in your matching pattern strings. For example, an element matching pattern
-of "*/a" will match an <code><a></code> element at any nesting position
-within the document.</p>
+nested (or not nested) in the XML document, by leaving off the leading slash
+character in your matching pattern strings. For example, an element matching
+pattern of "a" will match an <code><a></code> element at any nesting
+position within the document, and a pattern of "a/b" will match a
+<code><b></code> element which is a direct child of an
+<code><a></code> element anywhere in the document.</p>
<p>It is quite possible that, when a particular XML element is being parsed,
the pattern for more than one registered processing rule will be matched
- either because you registered more than one processing rule with the same
+either because you registered more than one processing rule with the same
matching pattern, or because one more more exact pattern matches and wildcard
pattern matches are satisfied by the same element.</p>
-<p>When this occurs, the corresponding processing rules will all be fired in order.
-<code>begin</code> (and <code>body</code>) method calls are executed in the
-order that the <code>Rules</code> where initially registered with the
-<code>Digester</code>, whilst <code>end</code> method calls are execute in
-reverse order. In other words - the order is first in, last out.</p>
+<p>When this occurs, the corresponding processing actions for the matching rules
+will all be fired in order. The <code>begin</code> (and <code>body</code>)
+method calls are executed in the order that the <code>Action</code> objects
+were initially registered with the <code>Digester</code>, whilst <code>end</code>
+method calls are execute in reverse order. In other words - the order is first
+in, last out.</p>
-<a name="doc.Rules"></a>
-<h3>Processing Rules</h3>
+<a name="doc.Actions"></a>
+<h3>Processing Actions</h3>
<p>The <a href="#doc.Patterns">previous section</a> documented how you identify
<strong>when</strong> you wish to have certain actions take place. The purpose
-of processing rules is to define <strong>what</strong> should happen when the
+of processing actions is to define <strong>what</strong> should happen when the
patterns are matched.</p>
-<p>Formally, a processing rule is a Java class that subclasses the
-<a href="Rule.html">org.apache.commons.digester.Rule</a> interface. Each Rule
-implements one or more of the following event methods that are called at
-well-defined times when the matching patterns corresponding to this rule
-trigger it:</p>
+<p>Formally, a processing action is a Java class that subclasses the
+<a href="Action.html">Action</a> interface. Each Action implements one or more
+of the following event methods that are called at well-defined times when the
+matching patterns corresponding to this action trigger it:</p>
<ul>
-<li><a href="Rule.html#begin(org.xml.sax.AttributeList)">begin()</a> -
+<li><a href="Action.html#begin">begin</a> -
Called when the beginning of the matched XML element is encountered. A
data structure containing all of the attributes corresponding to this
element are passed as well.</li>
-<li><a href="Rule.html#body(java.lang.String)">body()</a> -
+<li><a href="Action.html#body">body</a> -
Called when nested content (that is not itself XML elements) of the
- matched element is encountered. Any leading or trailing whitespace will
- have been removed as part of the parsing process.</li>
-<li><a href="Rule.html#end()">end()</a> - Called when the ending of the matched
+ matched element is encountered.</li>
+<li><a href="Action.html#end">end</a> - Called when the ending of the matched
XML element is encountered. If nested XML elements that matched other
- processing rules was included in the body of this element, the appropriate
- processing rules for the matched rules will have already been completed
+ processing actions was included in the body of this element, the appropriate
+ processing rules for the matched actions will have already been completed
before this method is called.</li>
-<li><a href="Rule.html#finish()">finish()</a> - Called when the parse has
- been completed, to give each rule a chance to clean up any temporary data
- they might have created and cached.</li>
+<li><a href="Action.html#startParse">startParse</a> - Called when parsing of
+ an input document is about to start, to give each action a chance to
+ perform any per-parse initialisation it wishes to do.</li>
+<li><a href="Action.html#finishParse">finishParse</a> - Called when the parse
+ has been completed, to give each action a chance to clean up any temporary
+ data it might have created and cached.</li>
</ul>
<p>As you are configuring your digester, you can call the
<code>addRule()</code> method to register a specific element matching pattern,
-along with an instance of a <code>Rule</code> class that will have its event
+along with an instance of an <code>Action</code> class that will have its event
handling methods called at the appropriate times, as described above. This
-mechanism allows you to create <code>Rule</code> implementation classes
+mechanism allows you to create <code>Action</code> implementation classes
dynamically, to implement any desired application specific functionality.</p>
-<p>In addition, a set of processing rule implementation classes are provided,
+<p>In addition, a set of processing action implementation classes are provided,
which deal with many common programming scenarios. These classes include the
following:</p>
<ul>
-<li><a href="ObjectCreateRule.html">ObjectCreateRule</a> - When the
- <code>begin()</code> method is called, this rule instantiates a new
+<li><a href="actions/CreateObjectAction.html">CreateObjectAction</a> - When the
+ <code>begin</code> method is called, this action creates a new
instance of a specified Java class, and pushes it on the stack. The
- class name to be used is defaulted according to a parameter passed to
- this rule's constructor, but can optionally be overridden by a classname
- passed via the specified attribute to the XML element being processed.
- When the <code>end()</code> method is called, the top object on the stack
- (presumably, the one we added in the <code>begin()</code> method) will
+ class name to be used is specified in a parameter passed to
+ this action's constructor, but the input xml can optionally override this
+ by using an xml attribute to specify an alternative classname.
+ When the <code>end</code> method is called, the top object on the stack
+ (presumably, the one we added in the <code>begin</code> method) will
be popped, and any reference to it (within the Digester) will be
discarded.</li>
-<li><a href="FactoryCreateRule.html">FactoryCreateRule</a> - A variation of
- <code>ObjectCreateRule</code> that is useful when the Java class with
+<li><a href="actions/CreateObjectWithFactoryAction.html">
+ CreateObjectWithFactoryAction</a> - A variation of
+ <code>CreateObjectAction</code> that is useful when the Java class with
which you wish to create an object instance does not have a no-arguments
constructor, or where you wish to perform other setup processing before
the object is handed over to the Digester.</li>
-<li><a href="SetPropertiesRule.html">SetPropertiesRule</a> - When the
- <code>begin()</code> method is called, the digester uses the standard
+<li><a href="actions/SetPropertiesAction.html">SetPropertiesAction</a> - When
+ the <code>begin</code> method is called, the digester uses the standard
Java Reflection API to identify any JavaBeans property setter methods
- (on the object at the top of the digester's stack)
- who have property names that match the attributes specified on this XML
- element, and then call them individually, passing the corresponding
- attribute values. These natural mappings can be overridden. This allows
- (for example) a <code>class</code> attribute to be mapped correctly.
- It is recommended that this feature should not be overused - in most cases,
- it's better to use the standard <code>BeanInfo</code> mechanism.
- A very common idiom is to define an object create
- rule, followed by a set properties rule, with the same element matching
- pattern. This causes the creation of a new Java object, followed by
- "configuration" of that object's properties based on the attributes
- of the same XML element that created this object.</li>
-<li><a href="SetPropertyRule.html">SetPropertyRule</a> - When the
- <code>begin()</code> method is called, the digester calls a specified
+ (on the object at the top of the digester's stack) which have property
+ names that match the attributes specified on this XML element, and then
+ call them individually, passing the corresponding attribute values. These
+ natural mappings can be overridden. This allows (for example) a
+ <code>class</code> attribute to be mapped correctly. It is recommended
+ that this override feature should not be overused - in most cases, it's
+ better to use the standard <code>BeanInfo</code> mechanism.
+ A very common idiom is to define a "create-object" action followed by a
+ "set-properties" action, with the same element matching pattern. This
+ causes the creation of a new Java object, followed by "configuration" of
+ that object's properties based on the attributes of the same XML element
+ that created this object.</li>
+<li><a href="actions/SetPropertyAction.html">SetPropertyAction</a> - When the
+ <code>begin</code> method is called, the digester calls a specified
property setter (where the property itself is named by an attribute)
with a specified value (where the value is named by another attribute),
on the object at the top of the digester's stack.
This is useful when your XML file conforms to a particular DTD, and
you wish to configure a particular property that does not have a
corresponding attribute in the DTD.</li>
-<li><a href="SetNextRule.html">SetNextRule</a> - When the
- <code>end()</code> method is called, the digester analyzes the
- next-to-top element on the stack, looking for a property setter method
- for a specified property. It then calls this method, passing the object
- at the top of the stack as an argument. This rule is commonly used to
- establish one-to-many relationships between the two objects, with the
- method name commonly being something like "addChild".</li>
-<li><a href="SetTopRule.html">SetTopRule</a> - When the
- <code>end()</code> method is called, the digester analyzes the
- top element on the stack, looking for a property setter method for a
- specified property. It then calls this method, passing the next-to-top
- object on the stack as an argument. This rule would be used as an
- alternative to a SetNextRule, with a typical method name "setParent",
- if the API supported by your object classes prefers this approach.</li>
-<li><a href="CallMethodRule.html">CallMethodRule</a> - This rule sets up a
- method call to a named method of the top object on the digester's stack,
- which will actually take place when the <code>end()</code> method is
- called. You configure this rule by specifying the name of the method
- to be called, the number of arguments it takes, and (optionally) the
- Java class name(s) defining the type(s) of the method's arguments.
- The actual parameter values, if any, will typically be accumulated from
- the body content of nested elements within the element that triggered
- this rule, using the CallParamRule discussed next.</li>
-<li><a href="CallParamRule.html">CallParamRule</a> - This rule identifies
- the source of a particular numbered (zero-relative) parameter for a
- CallMethodRule within which we are nested. You can specify that the
- parameter value be taken from a particular named attribute, or from the
- nested body content of this element.</li>
-<li><a href="NodeCreateRule.html">NodeCreateRule</a> - A specialized rule
- that converts part of the tree into a <code>DOM Node</code> and then
- pushes it onto the stack.</li>
+<li><a href="actions/LinkObjectsAction.html">LinkObjectsAction</a> - Allows
+ one object on the digester stack to be passed to some other object on the
+ digester stack. Presumably the recipient stores a reference to the parameter
+ object somewhere for later use. The most common use of this action is to
+ establish parent/child relationships between the (top-1) object on the
+ stack and the (top) object on the stack, with the method name commonly
+ being called something like "addChild".</li>
+<li><a href="actions/CallMethodAction.html">CallMethodAction</a> - This action
+ sets up a method call to a specified method on some object on the
+ digester's stack. The target object is usually the top object on the stack.
+ The call to the method will actually take place when the <code>end</code>
+ method of the action is called. You configure this action by specifying the
+ name of the method to be called, the number of arguments it takes, and
+ (optionally) the Java class name(s) defining the type(s) of the method's
+ arguments. The actual parameter values, if any, will typically be
+ accumulated from the body content of nested elements within the element
+ that triggered this action, using the CallParam..Action actions discussed
+ in the following section.</li>
+<li>CallParam Actions</a> - There is a set of actions with names of form
+ <code>CallParam....Action</code>, eg CallParamBodyAction. These actions are
+ all intended to be used together with a CallMethodAction to select values
+ for the method call defined by the CallMethod action. Flavours exist to
+ select data from an xml element's attributes, its body text, from the
+ digester object stack, and several other options.</li>
+<li><a href="actions/CreateNodeAction.html">CreateNodeAction</a> - A
+ specialized action that converts part of the xml input into a
+ <code>DOM Node</code> and then pushes it onto the stack.</li>
</ul>
-<p>You can create instances of the standard <code>Rule</code> classes and
+<a name="doc.ActionFactory"></a>
+<h3>The Action Factory</h3>
+
+<p>You can create instances of the standard <code>Action</code> classes and
register them by calling <code>digester.addRule()</code>, as described above.
-However, because their usage is so common, shorthand registration methods are
-defined for each of the standard rules, directly on the <code>Digester</code>
-class. For example, the following code sequence:</p>
+However, because their usage is so common, the ActionFactory class provides
+a set of shorthand registration methods. For example, the following code
+sequence:</p>
<pre>
- Rule rule = new SetNextRule(digester, "addChild",
+ Action action = new LinkObjectsAction("addChild",
"com.mycompany.mypackage.MyChildClass");
- digester.addRule("a/b/c", rule);
+ digester.addRule("/a/b/c", action);
</pre>
<p>can be replaced by:</p>
<pre>
- digester.addSetNext("a/b/c", "addChild",
+ ActionFactory factory = new ActionFactory(digester);
+ factory.addLinkObjects("/a/b/c", "addChild",
"com.mycompany.mypackage.MyChildClass");
</pre>
<a name="doc.Logging"></a>
<h3>Logging</h3>
-<p>Logging is a vital tool for debugging Digester rulesets. Digester can log
+<p>Logging is a vital tool for debugging Digester operation. Digester can log
copious amounts of debugging information. So, you need to know how logging
works before you start using Digester seriously.</p>
@@ -555,12 +542,12 @@
<pre>
Digester digester = new Digester();
- digester.setValidating(false);
- digester.addObjectCreate("foo", "mypackage.Foo");
- digester.addSetProperties("foo");
- digester.addObjectCreate("foo/bar", "mypackage.Bar");
- digester.addSetProperties("foo/bar");
- digester.addSetNext("foo/bar", "addBar", "mypackage.Bar");
+ ActionFactory factory = new ActionFactory(digester);
+ factory.addCreateObject("/foo", "mypackage.Foo");
+ factory.addSetProperties("/foo");
+ factory.addCreateObject("/foo/bar", "mypackage.Bar");
+ factory.addSetProperties("/foo/bar");
+ factory.addLinkObjects("/foo/bar", "addBar", "mypackage.Bar");
Foo foo = (Foo) digester.parse();
</pre>
@@ -577,7 +564,7 @@
create a new instance of <code>mypackage.Bar</code> and push it
on to the object stack. At the end of the <code><bar></code>
element, this object will be popped off of the stack (i.e. after the
- remaining rules matching <code>foo/bar</code> are processed).</li>
+ remaining rules matching <code>/foo/bar</code> are processed).</li>
<li>Cause properties of the top object on the stack (i.e. the <code>Bar</code>
object that was just created and pushed) to be set based on the values
of the attributes of this XML element. Note that type conversions
@@ -585,10 +572,9 @@
property), for all converters registered with the <code>ConvertUtils</code>
class from <code>commons-beanutils</code> package.</li>
<li>Cause the <code>addBar</code> method of the next-to-top element on the
- object stack (which is why this is called the "set <em>next</em>" rule)
- to be called, passing the element that is on the top of the stack, which
- must be of type <code>mypackage.Bar</code>. This is the rule that causes
- the parent/child relationship to be created.</li>
+ object stack to be called, passing the element that is on the top of the
+ stack, which must be of type <code>mypackage.Bar</code>. This is the rule
+ that causes the parent/child relationship to be created.</li>
</ol>
<p>Once the parse is completed, the first object that was ever pushed on to the
@@ -615,12 +601,12 @@
<a href="http://jakarta.apache.org/struts/">http://jakarta.apache.org/struts/</a>.)</p>
<p>The following discussion highlights a few of the matching patterns and
-processing rules that are configured, to illustrate the use of some of the
+processing actions that are configured, to illustrate the use of some of the
Digester features. First, let's look at how the Digester instance is
created and initialized:</p>
<pre>
Digester digester = new Digester();
- digester.push(this); // Push controller servlet onto the stack
+ digester.setInitialObject(this);
digester.setValidating(true);
</pre>
@@ -631,14 +617,15 @@
itself will be added to the digester's stack.</p>
<pre>
- digester.addObjectCreate("struts-config/global-forwards/forward",
+ ActionFactory factory = new ActionFactory(digester);
+ factory.addCreateObject("/struts-config/global-forwards/forward",
forwardClass, "className");
- digester.addSetProperties("struts-config/global-forwards/forward");
- digester.addSetNext("struts-config/global-forwards/forward",
+ factory.addSetProperties("/struts-config/global-forwards/forward");
+ factory.addLinkObjects("/struts-config/global-forwards/forward",
"addForward",
"org.apache.struts.action.ActionForward");
- digester.addSetProperty
- ("struts-config/global-forwards/forward/set-property",
+ factory.addSetProperty(
+ "/struts-config/global-forwards/forward/set-property",
"property", "value");
</pre>
@@ -733,15 +720,13 @@
<p>Next, lets define some Digester processing rules for this input file:</p>
<pre>
- digester.addObjectCreate("web-app/servlet",
- "com.mycompany.ServletBean");
- digester.addCallMethod("web-app/servlet/servlet-name", "setServletName", 0);
- digester.addCallMethod("web-app/servlet/servlet-class",
- "setServletClass", 0);
- digester.addCallMethod("web-app/servlet/init-param",
+ factory.addCreateObject("/web-app/servlet", "com.mycompany.ServletBean");
+ factory.addSetProperty("/web-app/servlet/servlet-name");
+ factory.addSetProperty("/web-app/servlet/servlet-class");
+ factory.addCallMethod("/web-app/servlet/init-param",
"addInitParam", 2);
- digester.addCallParam("web-app/servlet/init-param/param-name", 0);
- digester.addCallParam("web-app/servlet/init-param/param-value", 1);
+ factory.addCallParamBody("/web-app/servlet/init-param/param-name", 0);
+ factory.addCallParamBody("/web-app/servlet/init-param/param-value", 1);
</pre>
<p>Now, as elements are parsed, the following processing occurs:</p>
@@ -776,324 +761,62 @@
<a name="doc.Namespace"></a>
-<h3>Namespace Aware Parsing</h3>
+<h3>Handling documents that use xml namespaces</h3>
-<p>For digesting XML documents that do not use XML namespaces, the default
-behavior of <code>Digester</code>, as described above, is generally sufficient.
-However, if the document you are processing uses namespaces, it is often
-convenient to have sets of <code>Rule</code> instances that are <em>only</em>
-matched on elements that use the prefix of a particular namespace. This
-approach, for example, makes it possible to deal with element names that are
-the same in different namespaces, but where you want to perform different
-processing for each namespace. </p>
-
-<p>Digester does not provide full support for namespaces, but does provide
-sufficient to accomplish most tasks. Enabling digester's namespace support
-is done by following these steps:</p>
+<p>Digester 2.0 has full support for xml namespaces. Before adding rules,
+simply define a set of (prefix->namespace) mappings via the
+<code>Digester.addNamespace</code> method. The patterns that are then passed
+to the addRule method may then use any of the prefixes that have been defined.
+</p>
-<ol>
-<li>Tell <code>Digester</code> that you will be doing namespace
- aware parsing, by adding this statement in your initalization
- of the Digester's properties:
- <pre>
- digester.setNamespaceAware(true);
- </pre></li>
-<li>Declare the public namespace URI of the namespace with which
- following rules will be associated. Note that you do <em>not</em>
- make any assumptions about the prefix - the XML document author
- is free to pick whatever prefix they want:
- <pre>
- digester.setRuleNamespaceURI("http://www.mycompany.com/MyNamespace");
- </pre></li>
-<li>Add the rules that correspond to this namespace, in the usual way,
- by calling methods like <code>addObjectCreate()</code> or
- <code>addSetProperties()</code>. In the matching patterns you specify,
- use only the <em>local name</em> portion of the elements (i.e. the
- part after the prefix and associated colon (":") character:
- <pre>
- digester.addObjectCreate("foo/bar", "com.mycompany.MyFoo");
- digester.addSetProperties("foo/bar");
- </pre></li>
-<li>Repeat the previous two steps for each additional public namespace URI
- that should be recognized on this <code>Digester</code> run.</li>
-</ol>
+<p>Element names in a pattern which do not have a prefix will match only
+xml elements which are in no namespace.</p>
-<p>Now, consider that you might wish to digest the following document, using
-the rules that were set up in the steps above:</p>
+<p>As an example, consider what happens when the following document:
<pre>
<m:foo
xmlns:m="http://www.mycompany.com/MyNamespace"
xmlns:y="http://www.yourcompany.com/YourNamespace">
<m:bar name="My Name" value="My Value"/>
-
- <y:bar id="123" product="Product Description"/>L
+ <y:bar id="123" product="Product Description"/>
+ <bar id="123" product="Product Description"/>
</x:foo>
</pre>
+is parsed with these rules:
+<pre>
+ digester.addNamespace("mns", "http://www.mycompany.com/MyNamespace");
+ digester.addRule("/mns:foo/mns:bar", new CreateObjectAction());
+ digester.addRule("/mns:foo/mns:bar", new SetPropertiesAction());
+</pre>
+</p>
-<p>Note that your object create and set properties rules will be fired for the
+<p>The create-object and set-properties actions will be fired for the
<em>first</em> occurrence of the <code>bar</code> element, but not the
-<em>second</em> one. This is because we declared that our rules only matched
-for the particular namespace we are interested in. Any elements in the
-document that are associated with other namespaces (or no namespaces at all)
-will not be processed. In this way, you can easily create rules that digest
-only the portions of a compound document that they understand, without placing
-any restrictions on what other content is present in the document.</p>
-
-<p>You might also want to look at <a href="#doc.RuleSets">Encapsulated
-Rule Sets</a> if you wish to reuse a particular set of rules, associated
-with a particular namespace, in more than one application context.</p>
-
-<h4>Using Namespace Prefixes In Pattern Matching</h4>
-
-<p>Using rules with namespaces is very useful when you have orthogonal rulesets.
-One ruleset applies to a namespace and is independent of other rulesets applying
-to other namespaces. However, if your rule logic requires mixed namespaces, then
-matching namespace prefix patterns might be a better strategy.</p>
-
-<p>When you set the <code>NamespaceAware</code> property to false, digester uses
-the qualified element name (which includes the namespace prefix) rather than the
-local name as the patten component for the element. This means that your pattern
-matches can include namespace prefixes as well as element names. So, rather than
-create namespace-aware rules, create pattern matches including the namespace
-prefixes.</p>
-
-<p>For example, (with <code>NamespaceAware</code> false), the pattern <code>
-'foo:bar'</code> will match a top level element named <code>'bar'</code> in the
-namespace with (local) prefix <code>'foo'</code>.</p>
-
-<h4>Limitations of Digester Namespace support</h4>
-<p>Digester does not provide general "xpath-compliant" matching;
-only the namespace attached to the <i>last</i> element in the match path
-is involved in the matching process. Namespaces attached to parent
-elements are ignored for matching purposes.</p>
-
+<em>second</em> or <em>third</em> ones. This is because we declared that
+our rules only matched for the particular namespace we are interested in.
+Any elements in the document that are associated with other namespaces
+(or no namespaces at all) will not match these patterns.</p>
+
+<p>Note also that there is no need for the namespace prefixes used in the
+patterns to be identical to the namespace prefixes used in the input document.
+What is important is that the namespace URI referred to by the prefixes is the
+same. This is a normal (and important) feature of xml namespaces. However in
+most cases a namespace URI has a "traditional" prefix string, and it
+would be logical and convenient for your patterns to use the traditional
+prefixes in order to make the patterns more readable.</p>
<a name="doc.Pluggable"></a>
<h3>Pluggable Rules Processing</h3>
-<p>By default, <code>Digester</code> selects the rules that match a particular
+<p>By default, <code>Digester</code> selects the actions that match a particular
pattern of nested elements as described under
<a href="#doc.Patterns">Element Matching Patterns</a>. If you prefer to use
different selection policies, however, you can create your own implementation
-of the <a href="Rules.html">org.apache.commons.digester.Rules</a> interface,
-or subclass the corresponding convenience base class
-<a href="RulesBase.html">org.apache.commons.digester.RulesBase</a>.
-Your implementation of the <code>match()</code> method will be called when the
-processing for a particular element is started or ended, and you must return
-a <code>List</code> of the rules that are relevant for the current nesting
-pattern. The order of the rules you return <strong>is</strong> significant,
-and should match the order in which rules were initally added.</p>
-
-<p>Your policy for rule selection should generally be sensitive to whether
-<a href="#doc.Namespace">Namespace Aware Parsing</a> is taking place. In
-general, if <code>namespaceAware</code> is true, you should select only rules
-that:</p>
-<ul>
-<li>Are registered for the public namespace URI that corresponds to the
- prefix being used on this element.</li>
-<li>Match on the "local name" portion of the element (so that the document
- creator can use any prefix that they like).</li>
-</ul>
-
-<h4>ExtendedBaseRules</h4>
-<p><a href="ExtendedBaseRules.html">ExtendedBaseRules</a>,
-adds some additional expression syntax for pattern matching
-to the default mechanism, but it also executes more slowly. See the
-JavaDocs for more details on the new pattern matching syntax, and suggestions
-on when this implementation should be used. To use it, simply do the
-following as part of your Digester initialization:</p>
-
-<pre>
- Digester digester = ...
- ...
- digester.setRules(new ExtendedBaseRules());
- ...
-</pre>
-
-<h4>RegexRules</h4>
-<p><a href="RegexRules.html">RegexRules</a> is an advanced <code>Rules</code>
-implementation which does not build on the default pattern matching rules.
-It uses a pluggable <a href="RegexMatcher.html">RegexMatcher</a> implementation to test
-if a path matches the pattern for a Rule. All matching rules are returned
-(note that this behaviour differs from longest matching rule of the default
- pattern matching rules). See the Java Docs for more details.
-</p>
-<p>
-Example usage:
-</p>
-
-<pre>
- Digester digester = ...
- ...
- digester.setRules(new RegexRules(new SimpleRegexMatcher()));
- ...
-</pre>
-<h5>RegexMatchers</h5>
-<p>
-<code>Digester</code> ships only with one <code>RegexMatcher</code>
-implementation: <a href='SimpleRegexMatcher.html'>SimpleRegexMatcher</a>.
-This implementation is unsophisticated and lacks many good features
-lacking in more power Regex libraries. There are some good reasons
-why this approach was adopted. The first is that <code>SimpleRegexMatcher</code>
-is simple, it is easy to write and runs quickly. The second has to do with
-the way that <code>RegexRules</code> is intended to be used.
-</p>
-<p>
-There are many good regex libraries available. (For example
-<a href='http://jakarta.apache.org/oro/index.html'>Jakarta ORO</a>,
-<a href='http://jakarta.apache.org/regexp/index.html'>Jakarta Regex</a>,
-<a href='http://www.cacas.org/java/gnu/regexp/'>GNU Regex</a> and
-<a href='http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/package-summary.html'>
-Java 1.4 Regex</a>)
-Not only do different people have different personal tastes when it comes to
-regular expression matching but these products all offer different functionality
-and different strengths.
-</p>
-<p>
-The pluggable <code>RegexMatcher</code> is a thin bridge
-designed to adapt other Regex systems. This allows any Regex library the user
-desires to be plugged in and used just by creating one class.
-<code>Digester</code> does not (currently) ship with bridges to the major
-regex (to allow the dependencies required by <code>Digester</code>
-to be kept to a minimum).
-</p>
-
-<h4>WithDefaultsRulesWrapper</h4>
-<p>
-<a href="WithDefaultsRulesWrapper.html"> WithDefaultsRulesWrapper</a> allows
-default <code>Rule</code> instances to be added to any existing
-<code>Rules</code> implementation. These default <code>Rule</code> instances
-will be returned for any match for which the wrapped implementation does not
-return any matches.
-</p>
-<p>
-For example,
-<pre>
- Rule alpha;
- ...
- WithDefaultsRulesWrapper rules = new WithDefaultsRulesWrapper(new BaseRules());
- rules.addDefault(alpha);
- ...
- digester.setRules(rules);
- ...
-</pre>
-when a pattern does not match any other rule, then rule alpha will be called.
-</p>
-<p>
-<code>WithDefaultsRulesWrapper</code> follows the <em>Decorator</em> pattern.
-</p>
-
-<a name="doc.RuleSets"></a>
-<h3>Encapsulated Rule Sets</h3>
-
-<p>All of the examples above have described a scenario where the rules to be
-processed are registered with a <code>Digester</code> instance immediately
-after it is created. However, this approach makes it difficult to reuse the
-same set of rules in more than one application environment. Ideally, one
-could package a set of rules into a single class, which could be easily
-loaded and registered with a <code>Digester</code> instance in one easy step.
-</p>
-
-<p>The <a href="RuleSet.html">RuleSet</a> interface (and the convenience base
-class <a href="RuleSetBase.html">RuleSetBase</a>) make it possible to do this.
-In addition, the rule instances registered with a particular
-<code>RuleSet</code> can optionally be associated with a particular namespace,
-as described under <a href="#doc.Namespace">Namespace Aware Processing</a>.</p>
-
-<p>An example of creating a <code>RuleSet</code> might be something like this:
-</p>
-<pre>
-public class MyRuleSet extends RuleSetBase {
+of the <a href="RuleManager.html">RuleManager</a> interface, or subclass the
+AbstractRuleManager base class.</p>
- public MyRuleSet() {
- this("");
- }
-
- public MyRuleSet(String prefix) {
- super();
- this.prefix = prefix;
- this.namespaceURI = "http://www.mycompany.com/MyNamespace";
- }
-
- protected String prefix = null;
-
- public void addRuleInstances(Digester digester) {
- digester.addObjectCreate(prefix + "foo/bar",
- "com.mycompany.MyFoo");
- digester.addSetProperties(prefix + "foo/bar");
- }
-
-}
-</pre>
-
-<p>You might use this <code>RuleSet</code> as follow to initialize a
-<code>Digester</code> instance:</p>
-<pre>
- Digester digester = new Digester();
- ... configure Digester properties ...
- digester.addRuleSet(new MyRuleSet("baz/"));
-</pre>
-
-<p>A couple of interesting notes about this approach:</p>
-<ul>
-<li>The application that is using these rules does not need to know anything
- about the fact that the <code>RuleSet</code> being used is associated
- with a particular namespace URI. That knowledge is emedded inside the
- <code>RuleSet</code> class itself.</li>
-<li>If desired, you could make a set of rules work for more than one
- namespace URI by providing constructors on the <code>RuleSet</code> to
- allow this to be specified dynamically.</li>
-<li>The <code>MyRuleSet</code> example above illustrates another technique
- that increases reusability -- you can specify (as an argument to the
- constructor) the leading portion of the matching pattern to be used.
- In this way, you can construct a <code>Digester</code> that recognizes
- the same set of nested elements at different nesting levels within an
- XML document.</li>
-</ul>
-<a name="doc.NamedStacks"></a>
-<h3>Using Named Stacks For Inter-Rule Communication</h3>
-<p>
-<code>Digester</code> is based on <code>Rule</code> instances working together
-to process xml. For anything other than the most trival processing,
-communication between <code>Rule</code> instances is necessary. Since <code>Rule</code>
-instances are processed in sequence, this usually means storing an Object
-somewhere where later instances can retrieve it.
-</p>
-<p>
-<code>Digester</code> is based on SAX. The most natural data structure to use with
-SAX based xml processing is the stack. This allows more powerful processes to be
-specified more simply since the pushing and popping of objects can mimic the
-nested structure of the xml.
-</p>
-<p>
-<code>Digester</code> uses two basic stacks: one for the main beans and the other
-for parameters for method calls. These are inadequate for complex processing
-where many different <code>Rule</code> instances need to communicate through
-different channels.
-</p>
-<p>
-In this case, it is recommended that named stacks are used. In addition to the
-two basic stacks, <code>Digester</code> allows rules to use an unlimited number
-of other stacks referred to by an identifying string (the name). (That's where
-the term <em>named stack</em> comes from.) These stacks are
-accessed through calls to:
-</p>
-<ul>
- <li><a href='Digester.html#push(java.lang.String, java.lang.Object)'>
- void push(String stackName, Object value)</a></li>
- <li><a href='Digester.html#pop(java.lang.String)'>
- Object pop(String stackName)</a></li>
- <li><a href='Digester.html#peek(java.lang.String)'>
- Object peek(String stackName)</a></li>
-</ul>
-<p>
-<strong>Note:</strong> all stack names beginning with <code>org.apache.commons.digester</code>
-are reserved for future use by the <code>Digester</code> component. It is also recommended
-that users choose stack names prefixed by the name of their own domain to avoid conflicts
-with other <code>Rule</code> implementations.
-</p>
<a name="doc.RegisteringDTDs"></a>
<h3>Registering DTDs</h3>
@@ -1151,14 +874,17 @@
<h4>External Entity Resolution Using Digester</h4>
<p>
-SAX factors out the resolution of external entities into an <code>EntityResolver</code>.
-<code>Digester</code> supports the use of custom <code>EntityResolver</code>
-but ships with a simple internal implementation. This implementation allows local URLs
-to be easily associated with <code><em>public-identifiers</em></code>.
+SAX factors out the resolution of external entities into an
+<code>EntityResolver</code>. <code>Digester</code> supports the use of custom
+<code>EntityResolver</code> objects but ships with a simple internal
+implementation. This implementation allows local URLs to be easily
+associated with <code><em>public-identifiers</em></code>.
</p>
<p>For example:</p>
<code><pre>
- digester.register("-//Example Dot Com //DTD Sample Example//EN", "assets/sample.dtd");
+ digester.registerKnownEntity(
+ "-//Example Dot Com //DTD Sample Example//EN",
+ "assets/sample.dtd");
</pre></code>
<p>
will make digester return the relative file path <code>assets/sample.dtd</code>
@@ -1185,117 +911,91 @@
of the XML cannot be completed. So, to diagnose the cause a certain familiarity with
the way that SAX error handling works is very useful.
</p>
+
<h5>Diagnosing SAX Exceptions</h5>
-<p>
-This is a short, potted guide to SAX error handling strategies. It's not intended as a
-proper guide to error handling in SAX.
-</p>
-<p>
-When a SAX parser encounters a problem with the xml (well, ok - sometime after it
+<p>This is a short, potted guide to SAX error handling strategies. It's not intended as a
+proper guide to error handling in SAX.</p>
+
+<p>When a SAX parser encounters a problem with the xml (well, ok - sometime after it
encounters a problem) it will throw a
<a href='http://www.saxproject.org/apidoc/org/xml/sax/SAXParseException.html'>
SAXParseException</a>. This is a subclass of <code>SAXException</code> and contains
a bit of extra information about what exactly when wrong - and more importantly,
where it went wrong. If you catch an exception of this sort, you can be sure that
-the problem is with the XML and not <code>Digester</code> or your rules.
+the problem is with the XML and not <code>Digester</code> or your actions.
It is usually a good idea to catch this exception and log the extra information
-to help with diagnosing the reason for the failure.
-</p>
-<p>
-General <a href='http://www.saxproject.org/apidoc/org/xml/sax/SAXException.html'>
+to help with diagnosing the reason for the failure.</p>
+
+<p>General <a href='http://www.saxproject.org/apidoc/org/xml/sax/SAXException.html'>
SAXException</a> instances may wrap a causal exception. When exceptions are
throw by <code>Digester</code> each of these will be wrapped into a
<code>SAXException</code> and rethrown. So, catch these and examine the wrapped
-exception to diagnose what went wrong.
-</p>
+exception to diagnose what went wrong.</p>
+
<a name="doc.FAQ"></a>
<h3>Frequently Asked Questions</h3>
-<p><ul>
+
+<ul>
+
<li><strong>Why do I get warnings when using a JAXP 1.1 parser?</strong>
-<p>If you're using a JAXP 1.1 parser, you might see the following warning (in your log):
-<code><pre>
-[WARN] Digester - -Error: JAXP SAXParser property not recognized: http://java.sun.com/xml/jaxp/properties/schemaLanguage
-</pre></code>
-This property is needed for JAXP 1.2 (XML Schema support) as required
-for the Servlet Spec. 2.4 but is not recognized by JAXP 1.1 parsers.
-This warning is harmless.</p>
-<p>
+ <p>If you're using a JAXP 1.1 parser, you might see the following warning
+ (in your log):<code><pre>[WARN] Digester - -Error: JAXP SAXParser property
+ not recognized: http://java.sun.com/xml/jaxp/properties/schemaLanguage
+ </pre></code>
+ This property is needed for JAXP 1.2 (XML Schema support) as required
+ for the Servlet Spec. 2.4 but is not recognized by JAXP 1.1 parsers.
+ This warning is harmless.</p>
</li>
+
<li><strong>Why Doesn't Schema Validation Work With Parser XXX Out Of The Box?</strong>
-<p>
-Schema location and language settings are often need for validation using schemas.
-Unfortunately, there isn't a single standard approach to how these properties are
-configured on a parser.
-Digester tries to guess the parser being used and configure it appropriately
-but it's not infallible.
-You might need to grab an instance, configure it and pass it to Digester.
-</p>
-<p>
-If you want to support more than one parser in a portable manner,
-then you'll probably want to take a look at the
-<code>org.apache.commons.digester.parsers</code> package
-and add a new class to support the particular parser that's causing problems.
-</p>
+ <p>Schema location and language settings are often need for validation
+ using schemas. Unfortunately, there isn't a single standard approach to how
+ these properties are configured on a parser. Digester tries to guess the
+ parser being used and configure it appropriately but it's not infallible.
+ You might need to grab an instance, configure it and pass it to Digester.</p>
+
+ <p>If you want to support more than one parser in a portable manner, then
+ you'll probably want to take a look at the
+ <code>org.apache.commons.digester.parsers</code> package and add a new class
+ to support the particular parser that's causing problems.</p>
</li>
-<li><strong>Help!
-I'm Validating Against Schema But Digester Ignores Errors!</strong>
-<p>
-Digester is based on <a href='http://www.saxproject.org'>SAX</a>. The convention for
-SAX parsers is that all errors are reported (to any registered
-<code>ErrorHandler</code>) but processing continues. Digester (by default)
-registers its own <code>ErrorHandler</code> implementation. This logs details
-but does not stop the processing (following the usual convention for SAX
-based processors).
-</p>
-<p>
-This means that the errors reported by the validation of the schema will appear in the
-Digester logs but the processing will continue. To change this behaviour, call
-<code>digester.setErrorHandler</code> with a more suitable implementation.
-</p>
<li><strong>Where Can I Find Example Code?</strong>
-<a name="doc.FAQ.Examples">
-<p>Digester ships with a sample application: a mapping for the <em>Rich Site
-Summary</em> format used by many newsfeeds. Download the source distribution
-to see how it works.</p>
-<p>Digester also ships with a set of examples demonstrating most of the
-features described in this document. See the "src/examples" subdirectory
-of the source distribution.</p>
-</li>
-<li><strong>When Are You Going To Support <em>Rich Site Summary</em> Version x.y.z?</strong>
-<p>
-The <em>Rich Site Summary</em> application is intended to be a sample application.
-It works but we have no plans to add support for other versions of the format.
-</p>
-<p>
-We would consider donations of standard digester applications but it's unlikely that
-these would ever be shipped with the base digester distribution.
-If you want to discuss this, please post to <a href='http://jakarta.apache.org/site/mail.html'>
-common-dev mailing list</a>
-</p>
+ <a name="doc.FAQ.Examples">
+ <p>Digester source distributions include a set of examples demonstrating most
+ of the features described in this document. See the "src/examples" subdirectory
+ of the source distribution.</p>
</li>
+
</ul>
+
<a name="doc.extensions"></a>
<h3>Extensions</h3>
+
<p>
Three extension packages are included within the Digester distribution.
These provide extra functionality extending the core Digester concepts.
Detailed descriptions are contained within their own package documentation.
</p>
+
<ul>
- <li>
-<a href='plugins/package-summary.html'>plugins</a> provides a framework for the easy
-dynamic addition of rules during a Digestion. Rules can trigger the dynamic addition
-of other rules in an intuitive fashion.
- </li>
- <li>
-<a href='substitution/package-summary.html'>substitution</a> provides for
-manipulation of attributes and element body text before it is processed by the rules.
- </li>
- <li>
-<a href='xmlrules/package-summary.html'>xmlrules</a> package contains a
-system allowing digester rule configurations to be specifed through an xml file.
- </li>
+<li>
+ <a href='plugins/package-summary.html'>plugins</a> provides a framework for
+ the easy dynamic addition of rules during a Digestion. Rules can trigger the
+ dynamic addition of other rules in an intuitive fashion.
+</li>
+
+<li>
+ <a href='substitution/package-summary.html'>substitution</a> provides for
+ manipulation of attributes and element body text before it is processed by
+ the rules.
+</li>
+
+<li>
+ <a href='xmlrules/package-summary.html'>xmlrules</a> package contains a
+ system allowing digester rule configurations to be specifed through an xml
+ file.
+</li>
</ul>
<a name="doc.Limits"></a>
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org