craigmcc 01/02/10 12:32:46
Modified: src/share/org/apache/struts/digester package.html
Log:
Add a second extensive example of using Digester to process a web application
deployment descriptor (web.xml) file. In particular, illustrate how the
nested body content of XML elements can be processed just as easily as elements
and attributes can.
Suggested by: Jens Rehpohler <[EMAIL PROTECTED]>
Revision Changes Path
1.2 +86 -1 jakarta-struts/src/share/org/apache/struts/digester/package.html
Index: package.html
===================================================================
RCS file:
/home/cvs/jakarta-struts/src/share/org/apache/struts/digester/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 2000/11/29 06:47:15 1.1
+++ package.html 2001/02/10 20:32:46 1.2
@@ -349,8 +349,10 @@
</pre>
<a name="doc.Usage"></a>
-<h3>Usage Example</h3>
+<h3>Usage Examples</h3>
+<h5>Processing The Struts Configuration File</h5>
+
<p>As stated earlier, the primary reason that the
<code>org.apache.struts.digester.Digester</code> package exists is because the
Struts controller servlet itself needed a robust, flexible, easy to extend
@@ -435,6 +437,89 @@
information that was defined in the <code>struts-config.xml</code> file is
now represented as collections of objects cached within the Struts controller
servlet, as well as being exposed as servlet context attributes.</p>
+
+<h5>Parsing Body Text In XML Files</h5>
+
+<p>The Digester module also allows you to process the nested body text in an
+XML file, not just the elements and attributes that are encountered. The
+following example is based on an assumed need to parse the web application
+deployment descriptor (<code>/WEB-INF/web.xml</code>) for the current web
+application, and record the configuration information for a particular
+servlet. To record this information, assume the existence of a bean class
+with the following method signatures (among others):</p>
+<pre>
+ package com.mycompany;
+ public class ServletBean {
+ public void setServletName(String servletName);
+ public void setServletClass(String servletClass);
+ public void addInitParam(String name, String value);
+ }
+</pre>
+
+<p>We are going to process the <code>web.xml</code> file that declares the
+controller servlet in a typical Struts-based application (abridged for
+brevity in this example):</p>
+<pre>
+ <web-app>
+ ...
+ <servlet>
+ <servlet-name>action</servlet-name>
+
<servlet-class>org.apache.struts.action.ActionServlet<servlet-class>
+ <init-param>
+ <param-name>application</param-name>
+
<param-value>org.apache.struts.example.ApplicationResources<param-value>
+ </init-param>
+ <init-param>
+ <param-name>config</param-name>
+ <param-value>/WEB-INF/struts-config.xml<param-value>
+ </init-param>
+ </servlet>
+ ...
+ </web-app>
+</pre>
+
+<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",
+ "addInitParam", 2);
+ digester.addCallParam("web-app/servlet/init-param/param-name", 0);
+ digester.addCallParam("web-app/servlet/init-param/param-value", 1);
+</pre>
+
+<p>Now, as elements are parsed, the following processing occurs:</p>
+<ul>
+<li><em><servlet></em> - A new <code>com.mycompany.ServletBean</code>
+ object is created, and pushed on to the object stack.</li>
+<li><em><servlet-name></em> - The <code>setServletName()</code> method
+ of the top object on the stack (our <code>ServletBean</code>) is called,
+ passing the body content of this element as a single parameter.</li>
+<li><em><servlet-class></em> - The <code>setServletClass()</code> method
+ of the top object on the stack (our <code>ServletBean</code>) is called,
+ passing the body content of this element as a single parameter.</li>
+<li><em><init-param></em> - A call to the <code>addInitParam</code>
+ method of the top object on the stack (our <code>ServletBean</code>) is
+ set up, but it is <strong>not</strong> called yet. The call will be
+ expecting two <code>String</code> parameters, which must be set up by
+ subsequent call parameter rules.</li>
+<li><em><param-name></em> - The body content of this element is assigned
+ as the first (zero-relative) argument to the call we are setting up.</li>
+<li><em><param-value></em> - The body content of this element is assigned
+ as the second (zero-relative) argument to the call we are setting up.</li>
+<li><em></init-param></em> - The call to <code>addInitParam()</code>
+ that we have set up is now executed, which will cause a new name-value
+ combination to be recorded in our bean.</li>
+<li><em><init-param></em> - The same set of processing rules are fired
+ again, causing a second call to <code>addInitParam()</code> with the
+ second parameter's name and value.</li>
+<li><em></servlet></em> - The element on the top of the object stack
+ (which should be the <code>ServletBean</code> we pushed earlier) is
+ popped off the object stack.</li>
+</ul>
</body>
</html>
