You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by ms...@apache.org on 2001/01/08 20:35:40 UTC

cvs commit: jakarta-struts/src/doc/userGuide resources.xml building_controller.xml building_model.xml building_view.xml introduction.xml

mschachter    01/01/08 11:35:39

  Modified:    src/doc  project.xml
               src/doc/userGuide building_controller.xml building_model.xml
                        building_view.xml introduction.xml
  Added:       src/doc/userGuide resources.xml
  Log:
  Updates to the user guide and project.xml pointing to the location of the
  new user guide
  
  Revision  Changes    Path
  1.16      +7 -0      jakarta-struts/src/doc/project.xml
  
  Index: project.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-struts/src/doc/project.xml,v
  retrieving revision 1.15
  retrieving revision 1.16
  diff -u -r1.15 -r1.16
  --- project.xml	2001/01/06 22:30:54	1.15
  +++ project.xml	2001/01/08 19:35:32	1.16
  @@ -8,6 +8,7 @@
       <menu name="Documentation">
           <item name="Home"                href="index.html"/>
           <item name="Installation"        href="installation.html"/>
  +	<item name="User Guide (1.0)"    href="introduction.html"/>
           <item name="Javadoc"             href="api/index.html"/>
           <item name="Release Notes (1.0)" href="release.html"/>
           <item name="TODO List (1.0)"     href="todo-1.0.html"/>
  @@ -39,3 +40,9 @@
       </menu>
   
   </project>
  +
  +
  +
  +
  +
  +
  
  
  
  1.4       +590 -587  jakarta-struts/src/doc/userGuide/building_controller.xml
  
  Index: building_controller.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-struts/src/doc/userGuide/building_controller.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- building_controller.xml	2001/01/08 03:44:58	1.3
  +++ building_controller.xml	2001/01/08 19:35:35	1.4
  @@ -1,587 +1,590 @@
  -<?xml version="1.0"?>
  -<document url="./building_controller.xml">
  -
  -  <properties>
  -    <author>Craig R. McClanahan</author>
  -    <author>Mike Schachter</author>
  -    <title>The Struts Framework Project</title>
  -  </properties>
  -  
  -  <body>  
  -  <chapter name="Building Controller Components" href="building_controller">
  -  
  -  		<section name="4.1 Overview" href="building_controller_overview">
  -  			
  -  			<p>
  -  				Now that we understand how to construct the Model and View components
  -				of your application, it is time to focus on the <code>Controller</code>
  -				components.  Struts includes a servlet that implements the primary function
  -				of mapping a request URI to an <code>Action</code> class.  Therefore, your
  -				primary responsibilities related to the Controller are:
  -			</p>
  -			
  -			<ul>
  -				<li>Write an <code>Action</code> class (that is, an extension of the
  -				    <code>Action</code> class) for each logical request
  -				    that may be received.</li>
  -				<li>Write an <code>ActionMapping</code> class (that is, an extension
  -				    of the <code>ActionMapping</code> class) that defines the class
  -				    names and other information associated with each possible
  -				    mapping.</li>
  -				<li>Write the action mapping configuration file (in XML) that is used
  -				    to configure the controller servlet.</li>
  -				<li>Update the web application deployment descriptor file (in XML)
  -				    for your application to include the necessary Struts components.</li>
  -				<li>Add the appropriate Struts components to your application.</li>
  -			</ul>
  -		</section>
  -		
  -		<section name="4.2 Action Classes" href="building_controller_action_classes">
  -			
  -			<p>The <code>Action</code> class defines two methods that could be
  -				executed depending on your servlet environment:
  -				<pre>
  -				    public ActionForward perform(ActionMapping mapping,
  -				 											ActionForm form,
  -				 											HttpServletRequest request,
  -															HttpServletResponse response)
  -						throws IOException, ServletException
  -						
  -					 public ActionForward perform(ActionMapping mapping,
  -				 											ActionForm form,
  -				 											ServletRequest request,
  -															ServletResponse response)
  -						throws IOException, ServletException
  -				</pre>
  -			</p>
  -				
  -			<p>
  -				The goal of an <code>Action</code> class is to process this request,
  -				and then to return an <code>ActionForward</code> object that identifies
  -				the JSP page (if any) to which control should be forwarded to generate
  -				the corresponding response.  In the <i>Model-1</i> design pattern,
  -				a typical <code>Action</code> class will implement the following
  -				logic in its <code>perform()</code> method:
  -			</p>
  -			<ul>
  -				<li>Validate the current state of the user's session (for example, checking
  -				    that the user has successfully logged on).  If the <code>Action</code>
  -				    class finds that no logon exists, the request should be forwarded to
  -				    the JSP page that displays the username and password prompts for
  -				    logging on.  This could occur because a user tried to enter your
  -				    application "in the middle" (say, from a bookmark), or because the
  -				    session has timed out, and the servlet container created a new one.</li>
  -				<li>If validation has not yet occurred,
  -				    validate the form bean properties as necessary.  If a problem is found,
  -				    store the appropriate error message keys as a request attribute, and
  -				    forward control back to the input form so that the errors can be
  -				    corrected.</li>
  -				<li>Perform the processing required to deal with this request (such as
  -				    saving a row into a database).  This can be done by code embedded within
  -				    the <code>Action</code> class itself, but should generally be performed
  -				    by calling an appropriate method of a business logic bean.</li>
  -				<li>Update the server-side objects that will be used to create the next
  -				    page of the user interface (typically request scope or session scope
  -				    beans, depending on how long you need to keep these items available).</li>
  -				<li>Return an appropriate <code>ActionForward</code> object that identifies
  -				    the JSP page to be used to generate this response, based on the newly
  -				    updated beans.  Typically, you will acquire a reference to such an
  -				    object by calling <code>findForward()</code> on either the
  -				    <code>ActionMapping</code> object you received (if you are using a
  -				    logical name local to this mapping), or on the controller servlet
  -				    itself (if you are using a logical name global to the application).</li>
  -			</ul>
  -				
  -			<p>
  -				Design issues to remember when coding <code>Action</code> classes
  -				include the following:
  -			</p>
  -			
  -			<ul>
  -				<li>The controller servlet creates only one instance of your
  -				    <code>Action</code> class, and uses it for all requests.  Thus,
  -				    you need to code your <code>Action</code> class so that it operates
  -				    correctly in a multi-threaded environment, just as you must code a
  -				    servlet's <code>service()</code> method safely.</li>
  -				<li>The most important principle that aids in thread-safe coding is to
  -				    use only local variables, not instance variables, in your
  -				    <code>Action</code> class.  Local variables are created on a
  -				    stack that is assigned (by your JVM) to each request thread, so
  -				    there is no need to worry about sharing them.</li>
  -				<li>The beans that represent the Model of your system may throw exceptions
  -				    due to problems accessing databases or other resources.
  -				    You should trap all such exceptions
  -				    in the logic of your <code>perform()</code> method, and log them to the
  -				    application logfile (along with the corresponding stack trace) by
  -				    calling:
  -				    <pre>
  -					servlet.log("Error message text", exception);
  -				    </pre></li>
  -				<li>As a general rule, allocating scarce resources and keeping them across
  -				    requests from the same user (in the user's session) can cause
  -				    scalability problems.  You should strive to release such resources
  -				    (such as database connections) prior to forwarding control to the
  -				    appropriate View component -- even if a bean method you have called
  -				    throws an exception.</li>
  -			</ul>
  -				
  -			<p>
  -				In addition, you will want to guard against <code>Action</code> classes
  -				that are too large.  The easiest way for this to happen is to embed your
  -				functional logic in the <code>Action</code> class itself, rather than
  -				coding it in separate business logic beans.  Besides making the
  -				<code>Action</code> class itself hard to understand and maintain, this
  -				approach also makes it harder to re-use the business logic code, because
  -				it is embedded inside a component (the <code>Action</code> class) that
  -				is tied to being executed in a web application environment.
  -			</p>
  -				
  -			<p>
  -				The example application included with Struts stretches this design
  -				principle somewhat, because the business logic itself is embedded in the
  -				<code>Action</code> classes.  This should be considered something of a
  -				bug in the design of the sample application, rather than an intrinsic
  -				feature of the Struts architecture, or an approach to be emulated.
  -			</p>
  -		</section>
  -				
  -		<section name="4.3 The ActionMapping Implementation" href="building_controller_actionmapping">
  -			
  -			<p>
  -				In order to operate successfully, the Struts controller servlet needs
  -				to know several things about how each request URI should be mapped to an
  -				appropriate <code>Action</code> class.  The required knowledge has been
  -				encapsulated in a Java interface named <code>ActionMapping</code>, the most
  -				important properties are as follows:
  -			</p>
  -			
  -			<ul>
  -				<li><b>type</b> - Fully qualified Java class name of the
  -					<code>Action</code> implementation class used by this mapping.</li>
  -				<li><b>name</b> - The name of the form bean defined in the config file
  -					that this action will use</li>
  -				<li><b>path</b> - The request URI path that is matched to select this
  -				    mapping.  See below for examples of how matching works.</li>
  -				    
  -				<li><b>unknown</b> - Set to <code>true</code> if this action
  -					should be configured as the default for this application, to handle
  -					all requests not handled by another action.  Only one action can be
  - 					defined as a default within a single application.</li>
  -				<li><b>validate</b> - Set to <code>true</code> if the
  -					<code>validate()</code> method of the action associated
  -					with this mapping should be called.</li>
  -			</ul>
  -				
  -				
  -			<p>
  -				In the example application included with Struts, this feature is used to
  -				define two additional properties:
  -			</p>
  -			
  -			<ul>
  -				<li><b>failure</b> - The context-relative URI to which control should be
  -				    forwarded if the Action class detects some sort of problem with the
  -				    input fields it received.  This will typically be the name of the
  -				    JSP page from which the request was sent, which will cause the form
  -				    to be redisplayed (with the error messages set by the Action Class
  -				    and the most recent input values from the ActionForm bean).</li>
  -				<li><b>success</b> - The context-relative URI to which control should be
  -				    forwarded if the Action class successfully performs the required
  -				    function.  This will typically be the name of a JSP page that prepares
  -				    the next page of the conversation flow for this application.</li>
  -			</ul>
  -				
  -			<p>
  -				Using these two extra properties, the <code>Action</code> classes in the
  -				example application are almost totally independent of the actual names of
  -				the JSP pages that are used by the page designers.  The pages can be renamed
  -				(for example) during a redesign, with negligible impact on the
  -				<code>Action</code> classes themselves.  If the names of the "next" JSP
  -				pages were hard coded into the <code>Action</code> classes, all of these
  -				classes would also need to be modified.
  -			</p>
  -		</section>
  -		
  -		<section name="4.4 The Action Mappings Configuration File" href="building_controller_config">
  -			
  -			<p>
  -				How does the controller servlet learn about the mappings you want?  It
  -				would be possible (but tedious) to write a small Java class that simply
  -				instantiated new <code>ActionMapping</code> instances, and called all of
  -				the appropriate setter methods.  To make this process easier, Struts includes
  -				a Digester module that is capable of reading an XML-based description of
  -				the desired mappings, creating the appropriate objects along the way.
  -				See the <a href="api/index.html">API documentation</a> for more information
  -				about Digester.
  -			</p>
  -				
  -			<p>
  -				The developer's responsibility is to create an XML file named
  -				<code>struts-config.xml</code>, and place it in the WEB-INF directory of your
  -				application. This format of this document is constrained by it's definition in 
  -				"struts-config_1_0.dtd".  The outermost XML element must be <code>&lt;struts-config&gt;</code>.				
  -			</p>
  -			
  -			<p>
  -				Inside of the &lt;struts-config&gt; element, there two important elements that use
  -				to describe your actions:
  -				
  -				<blockquote>
  -					<b>&lt;form-beans&gt;</b><br />
  -						This section contains your form bean definitions.  You use a &gt;form-bean&lt; element
  -						for each form bean, which has the following important attributes:
  -						<ul>
  -							<li>
  -								<b>name</b>: The name of the request or session level attribute that this form
  -								bean will be stored as
  -							</li>
  -							<li>
  -								<b>type</b>: The fully-qualified Java classname of your form bean
  -							</li>
  -						</ul>
  -				</blockquote>
  -				<blockquote>
  -					<b>&lt;action-mappings&gt;</b><br />
  -						This section contains your action definitions.  You use an &gt;action&lt; element
  -						for each of your actions you would like to define.  Each action element has requires
  -						the follwing attributes to be defined:
  -						
  -						<ul>
  -							<li>
  -								<b>path</b>: The application context-relative path to the action
  -							</li>
  -							<li>
  -								<b>type</b>: The fully qualified java classname of your Action class
  -							</li>
  -							<li>
  -								<b>name</b>: The name of your &lt;form-bean&gt; element to use with this action
  -							</li>
  -						</ul>
  -				</blockquote>
  -			</p>
  -				
  -			<p>
  -				The <code>struts-config.xml</code> file from the example application includes
  -				the following mapping entry for the "log on" function, which we will use
  -				to illustrate the requirements.  Note that the entries for all the other actions
  -				are left out:
  -			</p>
  -				<pre>
  -				  &lt;struts-config>
  -				  		&lt;form-beans>
  -				  			&lt;form-bean name="logonForm"
  -				  						  type="org.apache.struts.example.LogonForm">
  -				  		&lt;/form-beans>
  -				  		
  -				  		&lt;global-forwards type="org.apache.struts.action.ActionForward">
  - 							&lt;forward name="logon" path="/logon.jsp" redirect="false" /> 
  - 						&lt;/global-forwards>
  -				  		
  -					  &lt;action-mappings&gt;
  -					   
  -  						&lt;action path="/logon" 
  -  									  type="org.apache.struts.example.LogonAction"
  -  									  name="logonForm"
  -  									  scope="request"
  -  									  input="/logon.jsp"
  -  									  unknown="false"
  -  									  validate="true" /> 					
  -					  &lt;/action-mappings&gt;
  -				 &lt;/struts-config>
  -				</pre>
  -			
  -			<p>
  -				First the form bean is defined.  A basic bean of class "org.apache.struts.example.LogonForm"
  -				is mapped to the logical name "logonForm".  This name is used as a session or request attribute
  -				name for the form bean.
  -			</p>
  -			<p>
  -				The "global-forwards" section is used to create logical name mappings between commonly used
  -				jsp pages.  Each of these forwards is available through a call to your action mapping instance,
  -				i.e. actionMappingInstace.findForward("logicalName")
  -			</p>
  -			<p>
  -				As you can see, this mapping matches the path <code>/logon</code> (actually,
  -				because the example application uses extension mapping, the request URI you
  -				specify in a JSP page would end in <code>/logon.do</code>).  When a request
  -				that matches this path is received, an instance of the <code>LogonAction</code>
  -				class will be created (the first time only) and used.  The controller servlet
  -				will look for a session scoped bean under key <code>logonForm</code>, creating
  -				and saving a bean of the specified class if needed.
  -			</p>
  -				
  -			<p>
  -				One more section of good use is the <code>&lt;data-source></code> section, which 
  -				specifies data sources that your application can use.This is how you would specify a basic data source for your application inside
  -				of struts-config.xml:
  -			</p>
  -			<p>
  -				<pre>
  -					&lt;struts-config>
  -						&lt;data-source autoCommit="false"
  -											 description="Example Data Source Description"
  -											 driverClass="org.postgresql.Driver"
  -									       maxCount="4"
  -									       minCount="2"
  -									       password="mypassword"
  -									       url="jdbc:postgresql://localhost/mydatabase"
  -									       user="myusername"/>
  -					&lt;/struts-config>
  -				</pre>
  -			</p>  
  -			<p>
  -				For information on how to retrieve the data source, see the 
  -				<a href="#building_model_databases">Accessing Relational Databases</a> section.  
  -			</p>
  -		</section>
  -		
  -		<section name="4.5 The Web Application Deployment Descriptor" href="building_controller_dd_config">
  -			
  -			<p>
  -				The final step in setting up the application is to configure the application
  -				deployment descriptor (stored in file <code>WEB-INF/web.xml</code>) to include
  -				all the Struts components that are required.  Using the deployment descriptor
  -				for the example application as a guide, we see that the following entries need
  -				to be created or modified.
  -			</p>
  -			
  -			<section name="4.5.1 Configure the Action Servlet Instance" href="building_controller_dd_config_servlet">
  -				
  -				<p>
  -					Add an entry defining the action servlet itself, along with the appropriate
  -					initialization parameters.  Such an entry might look like this:
  -					<pre>
  -					    &lt;servlet&gt;
  -					      &lt;servlet-name&gt;action&lt;/servlet-name&gt;
  -					      &lt;servlet-class&gt;org.apache.struts.action.ActionServlet&lt;/servlet-class&gt;
  -					      &lt;init-param&gt;
  -					        &lt;param-name&gt;application&lt;/param-name&gt;
  -					        &lt;param-value&gt;org.apache.struts.example.ApplicationResources&lt;/param-value&gt;
  -					      &lt;/init-param&gt;
  -					      &lt;init-param&gt;
  -					        &lt;param-name&gt;config&lt;/param-name&gt;
  -					        &lt;param-value&gt;/WEB-INF/struts-config.xml&lt;/param-value&gt;
  -					      &lt;/init-param&gt;
  -					      &lt;init-param&gt;
  -					        &lt;param-name&gt;debug&lt;/param-name&gt;
  -					        &lt;param-value&gt;2&lt;/param-value&gt;
  -					      &lt;/init-param&gt;
  -					      &lt;init-param&gt;
  -					        &lt;param-name&gt;mapping&lt;/param-name&gt;
  -					        &lt;param-value&gt;org.apache.struts.example.ApplicationMapping&lt;/param-value&gt;
  -					      &lt;/init-param&gt;
  -					      &lt;load-on-startup&gt;2&lt;/load-on-startup&gt;
  -					    &lt;/servlet&gt;
  -					</pre>
  -				</p>
  -				
  -				<p>
  -					The initialization parameters supported by the controller servlet are
  -					described below, which is copied from the <a href="api/index.html">Javadocs</a>
  -					for the <code>ActionServlet</code> class.  Square brackets describe the
  -					default values that are assumed if you do not provide a value for that
  -					initialization parameter.
  -				</p>
  -				<ul>
  -	
  -					<li><strong>application</strong> - Java class name of the application
  -					     resources bundle base class.  [NONE]</li>
  -					<li><strong>bufferSize</strong> - The size of the input buffer used when
  -					     processing file uploads.  [4096]</li>
  -					<li><strong>config</strong> - Context-relative path to the XML resource
  -					    containing our configuration information.
  -					    [/WEB-INF/struts-config.xml]</li>
  -					<li><strong>content</strong> - Default content type and character encoding
  -					    to be set on each response; may be overridden by a forwarded-to
  -					    servlet or JSP page.  [text/html]</li>
  -					<li><strong>debug</strong> - The debugging detail level for this
  -					    servlet, which controls how much information is logged.  [0]</li>
  -					<li><strong>detail</strong> - The debugging detail level for the Digester
  -					    we utilize in <code>initMapping()</code>, which logs to System.out
  -					    instead of the servlet log.  [0]</li>
  -					<li><strong>factory</strong> - The Java class name of the
  -					    <code>MessageResourcesFactory</code> used to create the application
  -					    <code>MessageResources</code> object.</li>
  -					<li><strong>formBean</strong> - The Java class name of the ActionFormBean
  -					    implementation to use [org.apache.struts.action.ActionFormBean].</li>
  -					<li><strong>forward</strong> - The Java class name of the ActionForward
  -					    implementation to use [org.apache.struts.action.ActionForward].
  -					    Two convenient classes you may wish to use are:
  -					    <ul>
  -					    <li><em>org.apache.struts.action.ForwardingActionForward</em> -
  -					        Subclass of <code>org.apache.struts.action.ActionForward</code>
  -					        that defaults the <code>redirect</code> property to
  -					        <code>false</code> (same as the ActionForward default value).</li>
  -					    <li><em>org.apache.struts.action.RedirectingActionForward</em> -
  -					        Subclass of <code>org.apache.struts.action.ActionForward</code>
  -					        that defaults the <code>redirect</code> property to
  -					        <code>true</code>.</li>
  -					    </ul></li>
  -					<li><strong>locale</strong> - If set to <code>true</code>, and there is a
  -					    user session, identify and store an appropriate
  -					    <code>java.util.Locale</code> object (under the standard key
  -					    identified by <code>Action.LOCALE_KEY</code>) in the user's session
  -					    if there is not a Locale object there already.</li>
  -					<li><strong>mapping</strong> - The Java class name of the ActionMapping
  -					    implementation to use [org.apache.struts.action.ActionMapping].
  -					    Two convenient classes you may wish to use are:
  -					    <ul>
  -					    <li><em>org.apache.struts.action.RequestActionMapping</em> - Subclass
  -					        of <code>org.apache.struts.action.ActionMapping</code> that
  -					        defaults the <code>scope</code> property to "request".</li>
  -					    <li><em>org.apache.struts.action.SessionActionMapping</em> - Subclass
  -					        of <code>org.apache.struts.action.ActionMapping</code> that
  -					        defaults the <code>scope</code> property to "session".  (Same
  -					        as the ActionMapping default value).</li>
  -					    </ul></li>
  -					<li><strong>maxFileSize</strong> - The maximum size (in bytes) of a file
  -					    to be accepted as a file upload.  Can be expressed as a number followed
  -					    by a "K" "M", or "G", which are interpreted to mean kilobytes,
  -					    megabytes, or gigabytes, respectively.  [250M]</li>
  -					<li><strong>multipartClass</strong> - The fully qualified name of the
  -					    MultiplartRequestHandler implementation class to be used for processing
  -					    file uploads.  [org.apache.struts.upload.DiskMultipartRequestHandler]
  -					    </li>
  -					<li><strong>nocache</strong> - If set to <code>true</code>, add HTTP headers
  -					    to every response intended to defeat browser caching of any response we
  -					    generate or forward to.  [false]</li>
  -					<li><strong>null</strong> - If set to <code>true</code>, set our application
  -					    resources to return <code>null</code> if an unknown message key is used.
  -					    Otherwise, an error message including the offending message key will
  -					    be returned.  [true]</li>
  -					<li><strong>tempDir</strong> - The temporary working directory to use when
  -					    processing file uploads.  [The working directory provided to this web
  -					    application as a servlet context attribute]</li>
  -					<li><strong>validate</strong> - Are we using the new configuration file
  -					    format?  [true]</li>	
  -				</ul>
  -			</section>
  -			
  -			<section name="4.5.2 Configure the Action Servlet Mapping" href="building_controller_dd_config_mapping">
  -			
  -				<p>
  -					There are two common approaches to defining the URLs that will
  -					be processed by the controller servlet -- prefix matching and extension
  -					matching.  An appropriate mapping entry for each approach will be
  -					described below.
  -				</p>
  -					
  -				<p>
  -					Prefix matching means that you want all URLs that start (after the context
  -					path part) with a particular value to be passed to this servlet.  Such an
  -					entry might look like this:
  -				</p>
  -					<pre>
  -					    &lt;servlet-mapping&gt;
  -					      &lt;servlet-name&gt;action&lt;/servlet-name&gt;
  -					      &lt;url-pattern&gt;/execute/*&lt;/url-pattern&gt;
  -					    &lt;/servlet-mapping&gt;
  -					</pre>
  -				
  -				<p>
  -					which means that a request URI to match the <code>/logon</code> path
  -					described earlier might look like this:
  -					<pre>
  -					    http://www.mycompany.com/myapplication/execute/logon
  -					</pre>
  -				</p>
  -				
  -				<p>
  -					where <code>/myapplication</code> is the context path under which your
  -					application is deployed.
  -				</p>
  -					
  -				<p>
  -					Extension mapping, on the other hand, matches request URIs to the action
  -					servlet based on the fact that the URI ends with a period followed by a
  -					defined set of characters.  For example, the JSP processing servlet is mapped
  -					to the <code>*.jsp</code> pattern so that it is called to process every
  -					JSP page that is requested.  To use the <code>*.do</code> extension (which
  -					implies "do something"), the mapping entry would look like this:
  -					<pre>
  -					    &lt;servlet-mapping&gt;
  -					      &lt;servlet-name&gt;action&lt;/servlet-name&gt;
  -					      &lt;url-pattern&gt;*.do&lt;/url-pattern&gt;
  -					    &lt;/servlet-mapping&gt;
  -					</pre>
  -				</p>
  -				
  -				<p>
  -					and a request URI to match the <code>/logon</code> path described
  -					earlier might look like this:
  -					<pre>
  -					    http://www.mycompany.com/myapplication/logon.do
  -					</pre>
  -				</p>
  -			</section>
  -			
  -			<section name="4.5.3 Configure the Struts Tag Library" href="building_controller_dd_config_taglib">
  -				
  -				<p>
  -					Next, you must add an entry defining the Struts tag library.  There are currently four
  -					taglibs that struts is packaged with.
  -				</p>
  -				<p>
  -					The struts-bean taglib contains tags useful in accessing
  -					beans and their properties, as well as defining new beans (based on these accesses) that are
  -					accessible to the remainder of the page via scripting variables and page scope attributes.
  -					Convenient mechanisms to create new beans based on the value of request cookies, headers, 
  -					and parameters are also provided.
  -				</p>
  -				<p>
  -					The struts-html taglib contains tags used to create struts input forms, as well as other
  -					tags generally useful in the creation of HTML-based user interfaces.
  -				</p>
  -				<p>
  -					The struts-logic taglib contains tags that are useful in managing conditional generation
  -					of output text, looping over object collections for repetitive generation of output text,
  -					and application flow management.
  -				</p>
  -				<p>
  -					The struts-template taglib contains tags that define a template mechanism.
  -				</p>
  -				
  -				<p>
  -					Below is how you would define all taglibs for use within your application,
  -					in reality you would only specify the taglib's that your application will use:
  -					
  -					<pre>
  -					  &lt;taglib&gt;
  -					    &lt;taglib-uri&gt;/WEB-INF/struts-bean.tld&lt;/taglib-uri&gt;
  -					    &lt;taglib-location&gt;/WEB-INF/struts-bean.tld&lt;/taglib-location&gt;
  -					  &lt;/taglib&gt;
  -					  &lt;taglib&gt;
  -					    &lt;taglib-uri&gt;/WEB-INF/struts-html.tld&lt;/taglib-uri&gt;
  -					    &lt;taglib-location&gt;/WEB-INF/struts-html.tld&lt;/taglib-location&gt;
  -					  &lt;/taglib&gt;
  -					  &lt;taglib&gt;
  -					    &lt;taglib-uri&gt;/WEB-INF/struts-logic.tld&lt;/taglib-uri&gt;
  -					    &lt;taglib-location&gt;/WEB-INF/struts-logic.tld&lt;/taglib-location&gt;
  -					  &lt;/taglib&gt;
  -					  &lt;taglib&gt;
  -					    &lt;taglib-uri&gt;/WEB-INF/struts-template.tld&lt;/taglib-uri&gt;
  -					    &lt;taglib-location&gt;/WEB-INF/struts-template.tld&lt;/taglib-location&gt;
  -					  &lt;/taglib&gt;
  -					</pre>
  -				</p>
  -					
  -				<p>
  -					This tells the JSP system where to find the tag library descriptor
  -					for this library (in your application's WEB-INF directory, instead of
  -					out on the Internet somewhere).
  -				</p>
  -			</section>
  -			
  -			<section name="4.5.4 Add Struts Components To Your Application" href="building_controller_dd_config_add">
  -				
  -				<p>
  -					To use struts, you must copy the .tld files that you require into your
  -					WEB-INF directory, and copy struts.jar into your WEB-INF/lib directory.
  -				</p>
  -			</section>
  -		</section>
  -	</chapter>
  -	</body>
  -</document>
  -					
  -										
  +<?xml version="1.0"?>
  +<document url="./building_controller.xml">
  +
  +  <properties>
  +    <author>Craig R. McClanahan</author>
  +    <author>Mike Schachter</author>
  +    <title>The Struts Framework Project</title>
  +  </properties>
  +  
  +  <body>  
  +  <chapter name="Building Controller Components" href="building_controller">
  +  
  +  		<section name="4.1 Overview" href="overview">
  +  			
  +  			<p>
  +  				Now that we understand how to construct the Model and View components
  +				of your application, it is time to focus on the <code>Controller</code>
  +				components.  Struts includes a servlet that implements the primary function
  +				of mapping a request URI to an <code>Action</code> class.  Therefore, your
  +				primary responsibilities related to the Controller are:
  +			</p>
  +			
  +			<ul>
  +				<li>Write an <code>Action</code> class (that is, an extension of the
  +				    <code>Action</code> class) for each logical request
  +				    that may be received.</li>
  +				<li>Write an <code>ActionMapping</code> class (that is, an extension
  +				    of the <code>ActionMapping</code> class) that defines the class
  +				    names and other information associated with each possible
  +				    mapping.</li>
  +				<li>Write the action mapping configuration file (in XML) that is used
  +				    to configure the controller servlet.</li>
  +				<li>Update the web application deployment descriptor file (in XML)
  +				    for your application to include the necessary Struts components.</li>
  +				<li>Add the appropriate Struts components to your application.</li>
  +			</ul>
  +		</section>
  +		
  +		<section name="4.2 Action Classes" href="action_classes">
  +			
  +			<p>The <code>Action</code> class defines two methods that could be
  +				executed depending on your servlet environment:
  +				<pre>
  +				    public ActionForward perform(ActionMapping mapping,
  +				 											ActionForm form,
  +				 											HttpServletRequest request,
  +															HttpServletResponse response)
  +						throws IOException, ServletException
  +						
  +					 public ActionForward perform(ActionMapping mapping,
  +				 											ActionForm form,
  +				 											ServletRequest request,
  +															ServletResponse response)
  +						throws IOException, ServletException
  +				</pre>
  +			</p>
  +				
  +			<p>
  +				The goal of an <code>Action</code> class is to process this request,
  +				and then to return an <code>ActionForward</code> object that identifies
  +				the JSP page (if any) to which control should be forwarded to generate
  +				the corresponding response.  In the <i>Model-1</i> design pattern,
  +				a typical <code>Action</code> class will implement the following
  +				logic in its <code>perform()</code> method:
  +			</p>
  +			<ul>
  +				<li>Validate the current state of the user's session (for example, checking
  +				    that the user has successfully logged on).  If the <code>Action</code>
  +				    class finds that no logon exists, the request should be forwarded to
  +				    the JSP page that displays the username and password prompts for
  +				    logging on.  This could occur because a user tried to enter your
  +				    application "in the middle" (say, from a bookmark), or because the
  +				    session has timed out, and the servlet container created a new one.</li>
  +				<li>If validation has not yet occurred,
  +				    validate the form bean properties as necessary.  If a problem is found,
  +				    store the appropriate error message keys as a request attribute, and
  +				    forward control back to the input form so that the errors can be
  +				    corrected.</li>
  +				<li>Perform the processing required to deal with this request (such as
  +				    saving a row into a database).  This can be done by code embedded within
  +				    the <code>Action</code> class itself, but should generally be performed
  +				    by calling an appropriate method of a business logic bean.</li>
  +				<li>Update the server-side objects that will be used to create the next
  +				    page of the user interface (typically request scope or session scope
  +				    beans, depending on how long you need to keep these items available).</li>
  +				<li>Return an appropriate <code>ActionForward</code> object that identifies
  +				    the JSP page to be used to generate this response, based on the newly
  +				    updated beans.  Typically, you will acquire a reference to such an
  +				    object by calling <code>findForward()</code> on either the
  +				    <code>ActionMapping</code> object you received (if you are using a
  +				    logical name local to this mapping), or on the controller servlet
  +				    itself (if you are using a logical name global to the application).</li>
  +			</ul>
  +				
  +			<p>
  +				Design issues to remember when coding <code>Action</code> classes
  +				include the following:
  +			</p>
  +			
  +			<ul>
  +				<li>The controller servlet creates only one instance of your
  +				    <code>Action</code> class, and uses it for all requests.  Thus,
  +				    you need to code your <code>Action</code> class so that it operates
  +				    correctly in a multi-threaded environment, just as you must code a
  +				    servlet's <code>service()</code> method safely.</li>
  +				<li>The most important principle that aids in thread-safe coding is to
  +				    use only local variables, not instance variables, in your
  +				    <code>Action</code> class.  Local variables are created on a
  +				    stack that is assigned (by your JVM) to each request thread, so
  +				    there is no need to worry about sharing them.</li>
  +				<li>The beans that represent the Model of your system may throw exceptions
  +				    due to problems accessing databases or other resources.
  +				    You should trap all such exceptions
  +				    in the logic of your <code>perform()</code> method, and log them to the
  +				    application logfile (along with the corresponding stack trace) by
  +				    calling:
  +				    <pre>
  +					servlet.log("Error message text", exception);
  +				    </pre></li>
  +				<li>As a general rule, allocating scarce resources and keeping them across
  +				    requests from the same user (in the user's session) can cause
  +				    scalability problems.  You should strive to release such resources
  +				    (such as database connections) prior to forwarding control to the
  +				    appropriate View component -- even if a bean method you have called
  +				    throws an exception.</li>
  +			</ul>
  +				
  +			<p>
  +				In addition, you will want to guard against <code>Action</code> classes
  +				that are too large.  The easiest way for this to happen is to embed your
  +				functional logic in the <code>Action</code> class itself, rather than
  +				coding it in separate business logic beans.  Besides making the
  +				<code>Action</code> class itself hard to understand and maintain, this
  +				approach also makes it harder to re-use the business logic code, because
  +				it is embedded inside a component (the <code>Action</code> class) that
  +				is tied to being executed in a web application environment.
  +			</p>
  +				
  +			<p>
  +				The example application included with Struts stretches this design
  +				principle somewhat, because the business logic itself is embedded in the
  +				<code>Action</code> classes.  This should be considered something of a
  +				bug in the design of the sample application, rather than an intrinsic
  +				feature of the Struts architecture, or an approach to be emulated.
  +			</p>
  +		</section>
  +				
  +		<section name="4.3 The ActionMapping Implementation" href="actionmapping">
  +			
  +			<p>
  +				In order to operate successfully, the Struts controller servlet needs
  +				to know several things about how each request URI should be mapped to an
  +				appropriate <code>Action</code> class.  The required knowledge has been
  +				encapsulated in a Java interface named <code>ActionMapping</code>, the most
  +				important properties are as follows:
  +			</p>
  +			
  +			<ul>
  +				<li><b>type</b> - Fully qualified Java class name of the
  +					<code>Action</code> implementation class used by this mapping.</li>
  +				<li><b>name</b> - The name of the form bean defined in the config file
  +					that this action will use</li>
  +				<li><b>path</b> - The request URI path that is matched to select this
  +				    mapping.  See below for examples of how matching works.</li>
  +				    
  +				<li><b>unknown</b> - Set to <code>true</code> if this action
  +					should be configured as the default for this application, to handle
  +					all requests not handled by another action.  Only one action can be
  + 					defined as a default within a single application.</li>
  +				<li><b>validate</b> - Set to <code>true</code> if the
  +					<code>validate()</code> method of the action associated
  +					with this mapping should be called.</li>
  +			</ul>
  +				
  +				
  +			<p>
  +				In the example application included with Struts, this feature is used to
  +				define two additional properties:
  +			</p>
  +			
  +			<ul>
  +				<li><b>failure</b> - The context-relative URI to which control should be
  +				    forwarded if the Action class detects some sort of problem with the
  +				    input fields it received.  This will typically be the name of the
  +				    JSP page from which the request was sent, which will cause the form
  +				    to be redisplayed (with the error messages set by the Action Class
  +				    and the most recent input values from the ActionForm bean).</li>
  +				<li><b>success</b> - The context-relative URI to which control should be
  +				    forwarded if the Action class successfully performs the required
  +				    function.  This will typically be the name of a JSP page that prepares
  +				    the next page of the conversation flow for this application.</li>
  +			</ul>
  +				
  +			<p>
  +				Using these two extra properties, the <code>Action</code> classes in the
  +				example application are almost totally independent of the actual names of
  +				the JSP pages that are used by the page designers.  The pages can be renamed
  +				(for example) during a redesign, with negligible impact on the
  +				<code>Action</code> classes themselves.  If the names of the "next" JSP
  +				pages were hard coded into the <code>Action</code> classes, all of these
  +				classes would also need to be modified.
  +			</p>
  +		</section>
  +		
  +		<section name="4.4 The Action Mappings Configuration File" href="config">
  +			
  +			<p>
  +				How does the controller servlet learn about the mappings you want?  It
  +				would be possible (but tedious) to write a small Java class that simply
  +				instantiated new <code>ActionMapping</code> instances, and called all of
  +				the appropriate setter methods.  To make this process easier, Struts includes
  +				a Digester module that is capable of reading an XML-based description of
  +				the desired mappings, creating the appropriate objects along the way.
  +				See the <a href="api/index.html">API documentation</a> for more information
  +				about Digester.
  +			</p>
  +				
  +			<p>
  +				The developer's responsibility is to create an XML file named
  +				<code>struts-config.xml</code>, and place it in the WEB-INF directory of your
  +				application. This format of this document is constrained by it's definition in 
  +				"struts-config_1_0.dtd".  The outermost XML element must be <code>&lt;struts-config&gt;</code>.				
  +			</p>
  +			
  +			<p>
  +				Inside of the &lt;struts-config&gt; element, there two important elements that use
  +				to describe your actions:
  +				
  +				<blockquote>
  +					<b>&lt;form-beans&gt;</b><br />
  +						This section contains your form bean definitions.  You use a &gt;form-bean&lt; element
  +						for each form bean, which has the following important attributes:
  +						<ul>
  +							<li>
  +								<b>name</b>: The name of the request or session level attribute that this form
  +								bean will be stored as
  +							</li>
  +							<li>
  +								<b>type</b>: The fully-qualified Java classname of your form bean
  +							</li>
  +						</ul>
  +				</blockquote>
  +				<blockquote>
  +					<b>&lt;action-mappings&gt;</b><br />
  +						This section contains your action definitions.  You use an &gt;action&lt; element
  +						for each of your actions you would like to define.  Each action element has requires
  +						the follwing attributes to be defined:
  +						
  +						<ul>
  +							<li>
  +								<b>path</b>: The application context-relative path to the action
  +							</li>
  +							<li>
  +								<b>type</b>: The fully qualified java classname of your Action class
  +							</li>
  +							<li>
  +								<b>name</b>: The name of your &lt;form-bean&gt; element to use with this action
  +							</li>
  +						</ul>
  +				</blockquote>
  +			</p>
  +				
  +			<p>
  +				The <code>struts-config.xml</code> file from the example application includes
  +				the following mapping entry for the "log on" function, which we will use
  +				to illustrate the requirements.  Note that the entries for all the other actions
  +				are left out:
  +			</p>
  +				<pre>
  +				  &lt;struts-config>
  +				  		&lt;form-beans>
  +				  			&lt;form-bean name="logonForm"
  +				  						  type="org.apache.struts.example.LogonForm">
  +				  		&lt;/form-beans>
  +				  		
  +				  		&lt;global-forwards type="org.apache.struts.action.ActionForward">
  + 							&lt;forward name="logon" path="/logon.jsp" redirect="false" /> 
  + 						&lt;/global-forwards>
  +				  		
  +					  &lt;action-mappings&gt;
  +					   
  +  						&lt;action path="/logon" 
  +  									  type="org.apache.struts.example.LogonAction"
  +  									  name="logonForm"
  +  									  scope="request"
  +  									  input="/logon.jsp"
  +  									  unknown="false"
  +  									  validate="true" /> 					
  +					  &lt;/action-mappings&gt;
  +				 &lt;/struts-config>
  +				</pre>
  +			
  +			<p>
  +				First the form bean is defined.  A basic bean of class "org.apache.struts.example.LogonForm"
  +				is mapped to the logical name "logonForm".  This name is used as a session or request attribute
  +				name for the form bean.
  +			</p>
  +			<p>
  +				The "global-forwards" section is used to create logical name mappings between commonly used
  +				jsp pages.  Each of these forwards is available through a call to your action mapping instance,
  +				i.e. actionMappingInstace.findForward("logicalName")
  +			</p>
  +			<p>
  +				As you can see, this mapping matches the path <code>/logon</code> (actually,
  +				because the example application uses extension mapping, the request URI you
  +				specify in a JSP page would end in <code>/logon.do</code>).  When a request
  +				that matches this path is received, an instance of the <code>LogonAction</code>
  +				class will be created (the first time only) and used.  The controller servlet
  +				will look for a session scoped bean under key <code>logonForm</code>, creating
  +				and saving a bean of the specified class if needed.
  +			</p>
  +				
  +			<p>
  +				One more section of good use is the <code>&lt;data-source></code> section, which 
  +				specifies data sources that your application can use.This is how you would specify a basic data source for your application inside
  +				of struts-config.xml:
  +			</p>
  +			<p>
  +				<pre>
  +					&lt;struts-config>
  +						&lt;data-source autoCommit="false"
  +											 description="Example Data Source Description"
  +											 driverClass="org.postgresql.Driver"
  +									       maxCount="4"
  +									       minCount="2"
  +									       password="mypassword"
  +									       url="jdbc:postgresql://localhost/mydatabase"
  +									       user="myusername"/>
  +					&lt;/struts-config>
  +				</pre>
  +			</p>  
  +			<p>
  +				For information on how to retrieve the data source, see the 
  +				<a href="building_model.html#databases">Accessing Relational Databases</a> section.  
  +			</p>
  +		</section>
  +		
  +		<section name="4.5 The Web Application Deployment Descriptor" href="dd_config">
  +			
  +			<p>
  +				The final step in setting up the application is to configure the application
  +				deployment descriptor (stored in file <code>WEB-INF/web.xml</code>) to include
  +				all the Struts components that are required.  Using the deployment descriptor
  +				for the example application as a guide, we see that the following entries need
  +				to be created or modified.
  +			</p>
  +			
  +			<section name="4.5.1 Configure the Action Servlet Instance" href="dd_config_servlet">
  +				
  +				<p>
  +					Add an entry defining the action servlet itself, along with the appropriate
  +					initialization parameters.  Such an entry might look like this:
  +					<pre>
  +					    &lt;servlet&gt;
  +					      &lt;servlet-name&gt;action&lt;/servlet-name&gt;
  +					      &lt;servlet-class&gt;org.apache.struts.action.ActionServlet&lt;/servlet-class&gt;
  +					      &lt;init-param&gt;
  +					        &lt;param-name&gt;application&lt;/param-name&gt;
  +					        &lt;param-value&gt;org.apache.struts.example.ApplicationResources&lt;/param-value&gt;
  +					      &lt;/init-param&gt;
  +					      &lt;init-param&gt;
  +					        &lt;param-name&gt;config&lt;/param-name&gt;
  +					        &lt;param-value&gt;/WEB-INF/struts-config.xml&lt;/param-value&gt;
  +					      &lt;/init-param&gt;
  +					      &lt;init-param&gt;
  +					        &lt;param-name&gt;debug&lt;/param-name&gt;
  +					        &lt;param-value&gt;2&lt;/param-value&gt;
  +					      &lt;/init-param&gt;
  +					      &lt;init-param&gt;
  +					        &lt;param-name&gt;mapping&lt;/param-name&gt;
  +					        &lt;param-value&gt;org.apache.struts.example.ApplicationMapping&lt;/param-value&gt;
  +					      &lt;/init-param&gt;
  +					      &lt;load-on-startup&gt;2&lt;/load-on-startup&gt;
  +					    &lt;/servlet&gt;
  +					</pre>
  +				</p>
  +				
  +				<p>
  +					The initialization parameters supported by the controller servlet are
  +					described below, which is copied from the <a href="api/index.html">Javadocs</a>
  +					for the <code>ActionServlet</code> class.  Square brackets describe the
  +					default values that are assumed if you do not provide a value for that
  +					initialization parameter.
  +				</p>
  +				<ul>
  +	
  +					<li><strong>application</strong> - Java class name of the application
  +					     resources bundle base class.  [NONE]</li>
  +					<li><strong>bufferSize</strong> - The size of the input buffer used when
  +					     processing file uploads.  [4096]</li>
  +					<li><strong>config</strong> - Context-relative path to the XML resource
  +					    containing our configuration information.
  +					    [/WEB-INF/struts-config.xml]</li>
  +					<li><strong>content</strong> - Default content type and character encoding
  +					    to be set on each response; may be overridden by a forwarded-to
  +					    servlet or JSP page.  [text/html]</li>
  +					<li><strong>debug</strong> - The debugging detail level for this
  +					    servlet, which controls how much information is logged.  [0]</li>
  +					<li><strong>detail</strong> - The debugging detail level for the Digester
  +					    we utilize in <code>initMapping()</code>, which logs to System.out
  +					    instead of the servlet log.  [0]</li>
  +					<li><strong>factory</strong> - The Java class name of the
  +					    <code>MessageResourcesFactory</code> used to create the application
  +					    <code>MessageResources</code> object.</li>
  +					<li><strong>formBean</strong> - The Java class name of the ActionFormBean
  +					    implementation to use [org.apache.struts.action.ActionFormBean].</li>
  +					<li><strong>forward</strong> - The Java class name of the ActionForward
  +					    implementation to use [org.apache.struts.action.ActionForward].
  +					    Two convenient classes you may wish to use are:
  +					    <ul>
  +					    <li><em>org.apache.struts.action.ForwardingActionForward</em> -
  +					        Subclass of <code>org.apache.struts.action.ActionForward</code>
  +					        that defaults the <code>redirect</code> property to
  +					        <code>false</code> (same as the ActionForward default value).</li>
  +					    <li><em>org.apache.struts.action.RedirectingActionForward</em> -
  +					        Subclass of <code>org.apache.struts.action.ActionForward</code>
  +					        that defaults the <code>redirect</code> property to
  +					        <code>true</code>.</li>
  +					    </ul></li>
  +					<li><strong>locale</strong> - If set to <code>true</code>, and there is a
  +					    user session, identify and store an appropriate
  +					    <code>java.util.Locale</code> object (under the standard key
  +					    identified by <code>Action.LOCALE_KEY</code>) in the user's session
  +					    if there is not a Locale object there already.</li>
  +					<li><strong>mapping</strong> - The Java class name of the ActionMapping
  +					    implementation to use [org.apache.struts.action.ActionMapping].
  +					    Two convenient classes you may wish to use are:
  +					    <ul>
  +					    <li><em>org.apache.struts.action.RequestActionMapping</em> - Subclass
  +					        of <code>org.apache.struts.action.ActionMapping</code> that
  +					        defaults the <code>scope</code> property to "request".</li>
  +					    <li><em>org.apache.struts.action.SessionActionMapping</em> - Subclass
  +					        of <code>org.apache.struts.action.ActionMapping</code> that
  +					        defaults the <code>scope</code> property to "session".  (Same
  +					        as the ActionMapping default value).</li>
  +					    </ul></li>
  +					<li><strong>maxFileSize</strong> - The maximum size (in bytes) of a file
  +					    to be accepted as a file upload.  Can be expressed as a number followed
  +					    by a "K" "M", or "G", which are interpreted to mean kilobytes,
  +					    megabytes, or gigabytes, respectively.  [250M]</li>
  +					<li><strong>multipartClass</strong> - The fully qualified name of the
  +					    MultiplartRequestHandler implementation class to be used for processing
  +					    file uploads.  [org.apache.struts.upload.DiskMultipartRequestHandler]
  +					    </li>
  +					<li><strong>nocache</strong> - If set to <code>true</code>, add HTTP headers
  +					    to every response intended to defeat browser caching of any response we
  +					    generate or forward to.  [false]</li>
  +					<li><strong>null</strong> - If set to <code>true</code>, set our application
  +					    resources to return <code>null</code> if an unknown message key is used.
  +					    Otherwise, an error message including the offending message key will
  +					    be returned.  [true]</li>
  +					<li><strong>tempDir</strong> - The temporary working directory to use when
  +					    processing file uploads.  [The working directory provided to this web
  +					    application as a servlet context attribute]</li>
  +					<li><strong>validate</strong> - Are we using the new configuration file
  +					    format?  [true]</li>	
  +				</ul>
  +			</section>
  +			
  +			<section name="4.5.2 Configure the Action Servlet Mapping" href="dd_config_mapping">
  +			
  +				<p>
  +					There are two common approaches to defining the URLs that will
  +					be processed by the controller servlet -- prefix matching and extension
  +					matching.  An appropriate mapping entry for each approach will be
  +					described below.
  +				</p>
  +					
  +				<p>
  +					Prefix matching means that you want all URLs that start (after the context
  +					path part) with a particular value to be passed to this servlet.  Such an
  +					entry might look like this:
  +				</p>
  +					<pre>
  +					    &lt;servlet-mapping&gt;
  +					      &lt;servlet-name&gt;action&lt;/servlet-name&gt;
  +					      &lt;url-pattern&gt;/execute/*&lt;/url-pattern&gt;
  +					    &lt;/servlet-mapping&gt;
  +					</pre>
  +				
  +				<p>
  +					which means that a request URI to match the <code>/logon</code> path
  +					described earlier might look like this:
  +					<pre>
  +					    http://www.mycompany.com/myapplication/execute/logon
  +					</pre>
  +				</p>
  +				
  +				<p>
  +					where <code>/myapplication</code> is the context path under which your
  +					application is deployed.
  +				</p>
  +					
  +				<p>
  +					Extension mapping, on the other hand, matches request URIs to the action
  +					servlet based on the fact that the URI ends with a period followed by a
  +					defined set of characters.  For example, the JSP processing servlet is mapped
  +					to the <code>*.jsp</code> pattern so that it is called to process every
  +					JSP page that is requested.  To use the <code>*.do</code> extension (which
  +					implies "do something"), the mapping entry would look like this:
  +					<pre>
  +					    &lt;servlet-mapping&gt;
  +					      &lt;servlet-name&gt;action&lt;/servlet-name&gt;
  +					      &lt;url-pattern&gt;*.do&lt;/url-pattern&gt;
  +					    &lt;/servlet-mapping&gt;
  +					</pre>
  +				</p>
  +				
  +				<p>
  +					and a request URI to match the <code>/logon</code> path described
  +					earlier might look like this:
  +					<pre>
  +					    http://www.mycompany.com/myapplication/logon.do
  +					</pre>
  +				</p>
  +			</section>
  +			
  +			<section name="4.5.3 Configure the Struts Tag Library" href="dd_config_taglib">
  +				
  +				<p>
  +					Next, you must add an entry defining the Struts tag library.  There are currently four
  +					taglibs that struts is packaged with.
  +				</p>
  +				<p>
  +					The struts-bean taglib contains tags useful in accessing
  +					beans and their properties, as well as defining new beans (based on these accesses) that are
  +					accessible to the remainder of the page via scripting variables and page scope attributes.
  +					Convenient mechanisms to create new beans based on the value of request cookies, headers, 
  +					and parameters are also provided.
  +				</p>
  +				<p>
  +					The struts-html taglib contains tags used to create struts input forms, as well as other
  +					tags generally useful in the creation of HTML-based user interfaces.
  +				</p>
  +				<p>
  +					The struts-logic taglib contains tags that are useful in managing conditional generation
  +					of output text, looping over object collections for repetitive generation of output text,
  +					and application flow management.
  +				</p>
  +				<p>
  +					The struts-template taglib contains tags that define a template mechanism.
  +				</p>
  +				
  +				<p>
  +					Below is how you would define all taglibs for use within your application,
  +					in reality you would only specify the taglib's that your application will use:
  +					
  +					<pre>
  +					  &lt;taglib&gt;
  +					    &lt;taglib-uri&gt;/WEB-INF/struts-bean.tld&lt;/taglib-uri&gt;
  +					    &lt;taglib-location&gt;/WEB-INF/struts-bean.tld&lt;/taglib-location&gt;
  +					  &lt;/taglib&gt;
  +					  &lt;taglib&gt;
  +					    &lt;taglib-uri&gt;/WEB-INF/struts-html.tld&lt;/taglib-uri&gt;
  +					    &lt;taglib-location&gt;/WEB-INF/struts-html.tld&lt;/taglib-location&gt;
  +					  &lt;/taglib&gt;
  +					  &lt;taglib&gt;
  +					    &lt;taglib-uri&gt;/WEB-INF/struts-logic.tld&lt;/taglib-uri&gt;
  +					    &lt;taglib-location&gt;/WEB-INF/struts-logic.tld&lt;/taglib-location&gt;
  +					  &lt;/taglib&gt;
  +					  &lt;taglib&gt;
  +					    &lt;taglib-uri&gt;/WEB-INF/struts-template.tld&lt;/taglib-uri&gt;
  +					    &lt;taglib-location&gt;/WEB-INF/struts-template.tld&lt;/taglib-location&gt;
  +					  &lt;/taglib&gt;
  +					</pre>
  +				</p>
  +					
  +				<p>
  +					This tells the JSP system where to find the tag library descriptor
  +					for this library (in your application's WEB-INF directory, instead of
  +					out on the Internet somewhere).
  +				</p>
  +			</section>
  +			
  +			<section name="4.5.4 Add Struts Components To Your Application" href="config_add">
  +				
  +				<p>
  +					To use struts, you must copy the .tld files that you require into your
  +					WEB-INF directory, and copy struts.jar into your WEB-INF/lib directory.
  +				</p>
  +                                <p>
  +                                        Next: <a href="resources.html">Struts Resources</a>
  +                                </p>
  +			</section>
  +		</section>
  +	</chapter>
  +	</body>
  +</document>
  +					
  +										
  
  
  
  1.4       +11 -7     jakarta-struts/src/doc/userGuide/building_model.xml
  
  Index: building_model.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-struts/src/doc/userGuide/building_model.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- building_model.xml	2001/01/08 03:44:58	1.3
  +++ building_model.xml	2001/01/08 19:35:36	1.4
  @@ -10,7 +10,7 @@
     <body>  
     <chapter name="Building Model Components" href="building_model">
     
  -  		<section name="2.1 Overview" href="building_model_overview">
  +  		<section name="2.1 Overview" href="overview">
     			
     			<p>
     				The application requirements document that you are using will likely
  @@ -26,7 +26,7 @@
   			</p>
   		</section>
   		
  -		<section name="2.2 JavaBeans and Scope" href="building_model_javabeans">
  +		<section name="2.2 JavaBeans and Scope" href="javabeans">
   		
   			<p>
   				Within a web-based application, JavaBeans can be stored in (and accessed
  @@ -75,7 +75,7 @@
   			</pre>
   		</section>
   		
  -		<section name="2.3 ActionForm Beans" href="building_model_actionform">
  +		<section name="2.3 ActionForm Beans" href="actionform">
   			
   			<p>
   				Note: ActionForm beans are actually closer to the <i>View</i>
  @@ -148,7 +148,7 @@
   			</p>
   		</section>
   		
  -		<section name="2.4 System State Beans" href="building_model_system_state">
  +		<section name="2.4 System State Beans" href="system_state">
   			
   			<p>
   				The actual state of a system is normally represented as a set of one or
  @@ -174,7 +174,7 @@
   			</p>
   		</section>
   		
  -		<section name="2.5 Business Logic Beans" href="building_model_business_logic">
  +		<section name="2.5 Business Logic Beans" href="business_logic">
   			
   			<p>
   				You should encapsulate the functional logic of your application as
  @@ -208,11 +208,11 @@
   			</p>
   		</section>
   		
  -		<section name="2.6 Accessing Relational Databases" href="building_model_databases">
  +		<section name="2.6 Accessing Relational Databases" href="databases">
   			
   			<p>
   				Struts contains in it's mapping config file the ability to specify data sources.
  -				See <a href="#building_controller_config">The Action Mappings Configuration File</a>
  +				See <a href="building_controller.html#config">The Action Mappings Configuration File</a>
   				for information on how to set up a datasource.  Do that first.
   			</p>
   			
  @@ -244,6 +244,10 @@
   						}
   					}
   				</pre>
  +			</p>
  +			
  +			<p align="center">
  +				Next: <a href="building_view.html">Building View Components</a>
   			</p>
   		</section>
   	</chapter>
  
  
  
  1.4       +16 -12    jakarta-struts/src/doc/userGuide/building_view.xml
  
  Index: building_view.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-struts/src/doc/userGuide/building_view.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- building_view.xml	2001/01/08 03:44:58	1.3
  +++ building_view.xml	2001/01/08 19:35:36	1.4
  @@ -10,7 +10,7 @@
     <body>  
     <chapter name="Building View Components" href="building_view">
     
  -  		<section name="3.1 Overview" href="building_view_overview">
  +  		<section name="3.1 Overview" href="overview">
     			
     			<p>
     				This chapter focuses on the task of building the <i>View</i> components
  @@ -22,7 +22,7 @@
   			
   		</section>
   		
  -		<section name="3.2 Internationalized Messages" href="building_view_i18n">
  +		<section name="3.2 Internationalized Messages" href="i18n">
   			
   			<p>
   				A few years ago, application developers could count on having to support
  @@ -118,7 +118,7 @@
   			</p>
   		</section>
   
  -		<section name="3.3 Forms and FormBean Interactions" href="building_view_form_beans">
  +		<section name="3.3 Forms and FormBean Interactions" href="form_beans">
   		
   			<p>
   				At one time or another, most web developers have built forms using
  @@ -161,7 +161,7 @@
   				in a way identical to building normal forms.
   			</p>
   		
  -			<section name="3.3.1 Building Forms With Struts" href="building_view_forms">
  +			<section name="3.3.1 Building Forms With Struts" href="forms">
   				
   				<p>
   					A complete example of a login form will illustrate how Struts
  @@ -344,7 +344,7 @@
   							
   			</section>
   			
  -			<section name="3.3.2 Input Field Types Supported" href="building_view_form_input">
  +			<section name="3.3.2 Input Field Types Supported" href="form_input">
   				
   				<p>
   					Struts defines tags for all of the following types of input fields,
  @@ -371,7 +371,7 @@
   				</p>
   			</section>
   			
  -			<section name="3.3.3 Other Useful Presentation Tags" href="building_view_presentation_tags">
  +			<section name="3.3.3 Other Useful Presentation Tags" href="presentation_tags">
   				
   				<p>
   					There are several tags useful for creating presentations, consult the documentation
  @@ -409,7 +409,7 @@
   				</ul>
   			</section>
   			
  -			<section name="3.3.4 Automatic Form Validation" href="building_view_form_validation">
  +			<section name="3.3.4 Automatic Form Validation" href="form_validation">
   			
   				<p>
   					In addition to the form and bean interactions described above, Struts
  @@ -454,7 +454,7 @@
   			</section>
   		</section>
   		
  -		<section name="3.4 Other Presentation Techniques" href="building_view_other_presentations">
  +		<section name="3.4 Other Presentation Techniques" href="other_presentations">
   		
   			<p>
   				Although the look and feel of your application can be completely constructed
  @@ -464,7 +464,7 @@
   				are discussed in the following sections.
   			</p>
   			
  -			<section name="3.4.1 Application-Specific Custom Tags" href="building_view_custom_tags">
  +			<section name="3.4.1 Application-Specific Custom Tags" href="custom_tags">
   			
   				<p>
   					Beyond using the custom tags provided by the Struts library, it is easy
  @@ -496,7 +496,7 @@
   				</p>
   			</section>
   			
  -			<section name="3.4.2 Page Composition With Includes" href="building_view_includes">
  +			<section name="3.4.2 Page Composition With Includes" href="includes">
   				
   				<p>
   					Creating the entire presentation of a page in one JSP file (with custom
  @@ -539,7 +539,7 @@
   					    flush="true" /&gt;</code>) is processed at request time, and is handled
   					    transparently by the server.  Among other things, that means you
   					    can conditionally perform the include by nesting it within a tag
  -					    like <a href="tags.html#ifParameterEquals">ifParameterEquals</a>.</li>
  +					    like <a href="struts-logic.html#ifParameterEquals">ifParameterEquals</a>.</li>
   					<li>The <a href="struts-bean.html#include">bean:include</a> tag takes either a
   						 an argument "forward" representing a logical name mapped to the jsp to include,
   						 or the "id" argument, which represents a page context String variable to print
  @@ -547,7 +547,7 @@
   				</ul>
   			</section>
   
  -			<section name="3.4.3 Image Rendering Components" href="building_view_image_rendering">
  +			<section name="3.4.3 Image Rendering Components" href="image_rendering">
   			
   				<p>
   					Some applications require dynamically generated images, like the price
  @@ -567,6 +567,10 @@
   					    can have the applet make its own connection to the server to receive
   					    these parameters.</li>
   				</ul>
  +			
  +				<p align="center">
  +					Next: <a href="building_controller.html">Building Controller Components</a>
  +				</p>
   			</section>
   		</section>
   	</chapter>
  
  
  
  1.5       +122 -10   jakarta-struts/src/doc/userGuide/introduction.xml
  
  Index: introduction.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-struts/src/doc/userGuide/introduction.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- introduction.xml	2001/01/08 16:24:53	1.4
  +++ introduction.xml	2001/01/08 19:35:37	1.5
  @@ -5,13 +5,14 @@
       <author>Craig R. McClanahan</author>
       <author>Mike Schachter</author>
       <author>Larry McCay</author>
  +    <author>Ted Husted</author>
       <title>The Struts Framework Project</title>
     </properties>
   
     <body>
   
     <chapter name="Introduction" href="introduction">
  -  	
  +  
     		<section name="The Model-View-Controller ('MVC') Design Pattern" href="mvc">
     		
     			<p>
  @@ -24,15 +25,10 @@
   	  			a loose coupling of the View and Model within the application.	 The MVC implementation in Struts
   	  			is sometimes also called "Model-2". 		
   	  		</p>	  		
  -	  		<p>
  -	  			See the "<a href="#resources">resources</a>" section at the end of this guide for links to the
  -	  			Model-View-Controller desgin pattern.
  -	  		</p>
   	  		
  -  			
     		</section>
     		
  -  		<section name="Mapping MVC Concepts to Struts Components" href="introduction_mvcConcepts">
  +  		<section name="Mapping MVC Concepts to Struts Components" href="mvcConcepts">
     		
     			<p>
     				The Struts architecture implements the concepts of the
  @@ -48,8 +44,118 @@
     				Each major component of this architecture will be discussed in more detail below.
     			</p>
     		</section>
  +  		
  +  		<section name="Overview" href="overview">
  +  			<p>
  +  				Struts uses a switchboard, or controller, servlet to route requests to other
  +				Struts objects. When initialized, the controller parses a configuration resource
  +				file. The configuration resource defines (among other things) the action
  +				mappings for the application. The controller uses these mappings to turn HTTP
  +				requests into application actions.
  +			</p>
  +			
  +			<p>
  +				At a minimum, a mapping must specify (1) a request path and (2) the object
  +				type to act upon the request. The action object can handle the request and respond to the client (usually a
  +				Web browser), or
  +				indicate that control should be forwarded to another action. For example, if a
  +				login succeeds, the loginAction object may wish to forward control to the
  +				mainMenu action.
  +			</p>
  +		
  +			<p>
  +				Action objects are linked to the application's controller, and so have access
  +				to that servlet's methods. When forwarding control, an object can indirectly
  +				forward one or more shared objects, including JavaBeans, by placing them in one
  +				of the standard collections shared by Java servlets.
  +			</p>
  +			
  +			<p>
  +				One action object can create a shopping cart bean, add an item to the
  +				cart, place the bean in the session collection, and then forward control to
  +				another action -- that may use a JSP to display the contents of the user's cart.
  +				Since each client has their own session, they will each also have their own
  +				shopping cart. In a Struts application, most of the business logic is
  +				represented using JavaBeans.
  +			</p>
  +			
  +			<p>
  +				JavaBeans can also be used to manage input forms. A key problem in designing
  +				Web applications is retaining and validating what a user has entered between
  +				requests. With Struts, you can easily store the data for a input form in a form
  +				bean. The bean is saved in one of the standard, shared context collections, so that it can
  +				be used by other objects.
  +			</p>
  +			
  +			<p>
  +				The form bean can be used by a JSP to collect data from the user ... by an
  +				action object to validate the user entered ... and then by the JSP again to
  +				re-populate the form fields. In the case of validation errors, Struts has a
  +				shared mechanism for raising and displaying error messages.
  +			</p>
  +			
  +			<p>
  +				A Struts form bean is defined in the configuration resource and linked to an action
  +				mapping using a common name. When a request calls for an action that uses a form
  +				bean, the controller servlet either retrieves or creates the form bean, and
  +				passes it to the action object. The action object can then check the contents of
  +				the form bean before its input form is displayed, and also queue messages to be
  +				handled by the form. When ready, the action object can return control with a
  +				forwarding to its input form, usually a JSP. The controller can then respond to
  +				the HTTP request and direct the client to the Java Server Page.
  +			</p>
  +			
  +			<p>
  +				The Struts framework includes custom tags that can automatically populate
  +				fields from a form bean. The only thing most JavaServer Pages need to know
  +				about the rest of the framework is the proper field names and where to submit
  +				the form. Components like the messages set by the action object can be output
  +				using a single custom tag. Other application-specific tags can also be defined
  +				to hide implementation details from the JSPs.
  +			</p>
  +			
  +			<p>
  +				The custom tags in the Struts framework are designed to use the
  +				internationalization features built into the Java platform. All the field labels
  +				and messages can be retrieved from a message resource, and Java can
  +				automatically provide the correct resource for a client's country and language.
  +				To provide messages for another language, simply add another resource file.
  +			</p>
  +			
  +			<p>
  +				Other benefits to this approach are consistent labeling between forms, and
  +				the ability to review all labels and messages from a central location.
  +			</p>
  +			
  +			<p>
  +				For the simplest applications, an action object can handle the business logic
  +				associated with a request. However, in most cases, an action object should pass
  +				the request to another object, usually a JavaBean. To allow resuse on other
  +				platforms, business-logic JavaBeans should not refer to any Web application
  +				objects. The action object should translate needed details from the HTTP request
  +				and pass those along to the business-logic beans as regular Java variables.
  +			</p>
  +				
  +			<p>
  +				In a database application, the business-logic beans might connect to and
  +				query the database and return the result set back to the action's servlet ... to
  +				be stored in a form bean ... and then displayed by the JSP. Neither the action's
  +				servlet nor the JSP need to know (or care) where the result set comes from.
  +			</p>
  +			
  +			<p>
  +				The Struts framework is compliant with the classic Model-View-Controller
  +				paradigm, which is the architecture recommended by Sun and most other vendors.
  +			</p>
  +			
  +			<p>
  +				In Struts, the ActionServlet object (described above) is the MVC controller,
  +				the view is handled by JSP or directly by an Action object, and the model is
  +				handled with business-logic beans, or directly by an Action object.
  +			</p>
  +		</section>
   
  -		<section name="The Model: System State and Business Logic JavaBeans" href="introduction_modelConcepts">
  +		<section name="The Model: System State and Business Logic JavaBeans" href="modelConcepts">
   			
   			<p>
   				The <i>Model</i> portion of an MVC-based system can be subdivided into
  @@ -94,7 +200,7 @@
   			</p>
   		</section>
   
  -		<section name="1.4 The View: JSP Pages and Presentation Components" href="introduction_presentationConcepts">
  +		<section name="1.4 The View: JSP Pages and Presentation Components" href="presentationConcepts">
   			
   			<p>
   				The <i>View</i> portion of a Struts-based application is generally
  @@ -126,7 +232,7 @@
   			</p>
   		</section>
   		
  -		<section name="1.5 The Controller: ActionServlet and ActionMapping" href="introduction_controllerConcepts">
  +		<section name="1.5 The Controller: ActionServlet and ActionMapping" href="controllerConcepts">
   			
   			<p>
   				The <i>Controller</i> portion of the application is focused on receiving
  @@ -156,7 +262,13 @@
   				the control logic (what do I do next) with the view logic (what is the name
   				of the corresponding page).
   			</p>
  +			
  +			<p align="center">
  +				Next: <a href="building_model.html">Building Model Components</a>
  +			</p>
     		</section>
  +  		
  +  		
     	</chapter>
     	</body>
   </document>
  
  
  
  1.1                  jakarta-struts/src/doc/userGuide/resources.xml
  
  Index: resources.xml
  ===================================================================
  <?xml version="1.0"?>
  <document url="./resources.xml">
  
    <properties>
      <author>Mike Schachter</author>
      <title>The Struts Framework Project</title>
    </properties>
  
    <body>
    
  	<chapter name="Struts Resources" href="resources">
  		
  		<section name="Struts Tutorials" href="tutorials">
  		
  			<p>
  				<u>Welcome to the Struts Framework</u>, <a href="http://www.bluestone.com">Bluestone Software</a><br />
  				<a href="http://developer.bluestone.com/scripts/SaISAPI.dll/Gallery.class/demos/trailMaps/index.jsp">http://developer.bluestone.com/scripts/SaISAPI.dll/Gallery.class/demos/trailMaps/index.jsp</a>
  			</p>
  	
  			<p>
  				<u>A Walking Tour of the Struts Example Application</u>, <a href="mailto:news.ted@husted.com">Ted Husted</a><br />
  				<a href="http://www.husted.com/about/struts/tour.htm">http://www.husted.com/about/struts/tour.htm</a>
  			</p>
  			
  			<p>
  				<u>Struts with a Fruit Glaze</u>, <a href="mailto:news.ted@husted.com">Ted Husted</a><br />
  				<a href="http://www.husted.com/about/struts/husted-coreservlets-jdbc.zip">http://www.husted.com/about/struts/husted-coreservlets-jdbc.zip</a>
  			</p>
  			
  			<p>
  				<u>About Struts - Husted dot Com</u>, <a href="mailto:news.ted@husted.com">Ted Husted</a><br />
  				<a href="http://www.husted.com/about/struts/">Struts Resources</a>
  			</p>		
  		</section>
  		
  		<section name="Struts Articles" href="articles">
  		
  			<p>
  				<u>Strut Your Stuff With JSP Tags</u>, <a href="Thor.Kristmundsson@javaworld.com">Thor Kristmundsson</a><br />
  				<a href="http://www.javaworld.com/javaworld/jw-12-2000/jw-1201-struts.html">http://www.javaworld.com/javaworld/jw-12-2000/jw-1201-struts.html</a>
  			</p>
  			
  			<p>
  				<u>Using the Struts Framework to Develop a Message Board</u>, Maneesh Sahu<br />
  				<a href="http://informit.com/books/authors/author_template/index.asp?authorid={A08A00B0-71BB-42DB-9B29-08879A9A7ABE}&amp;t={94AE5B48-1D7D-462A-A4A6-83CE19EC0705}&amp;n={4641FAF9-E21F-4902-8F6E-0C8FAF114C62}">Author Page (article requires registration with informit.com)</a>
  			</p>
  				
  			
  		
  		
  		</section>
  		
  		<section name="Struts Mailing List Archives" href="archives">
  			
  			<p>
  				<u>covalent.net</u>, <a href="http://archive.covalent.net/">http://archive.covalent.net</a>
  			</p>
  		</section>
  		
  	
  	</chapter>
  	
  	
    </body>
  </document>