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><struts-config></code>.
- </p>
-
- <p>
- Inside of the <struts-config> element, there two important elements that use
- to describe your actions:
-
- <blockquote>
- <b><form-beans></b><br />
- This section contains your form bean definitions. You use a >form-bean< 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><action-mappings></b><br />
- This section contains your action definitions. You use an >action< 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 <form-bean> 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>
- <struts-config>
- <form-beans>
- <form-bean name="logonForm"
- type="org.apache.struts.example.LogonForm">
- </form-beans>
-
- <global-forwards type="org.apache.struts.action.ActionForward">
- <forward name="logon" path="/logon.jsp" redirect="false" />
- </global-forwards>
-
- <action-mappings>
-
- <action path="/logon"
- type="org.apache.struts.example.LogonAction"
- name="logonForm"
- scope="request"
- input="/logon.jsp"
- unknown="false"
- validate="true" />
- </action-mappings>
- </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><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>
- <struts-config>
- <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"/>
- </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>
- <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>
- <init-param>
- <param-name>debug</param-name>
- <param-value>2</param-value>
- </init-param>
- <init-param>
- <param-name>mapping</param-name>
- <param-value>org.apache.struts.example.ApplicationMapping</param-value>
- </init-param>
- <load-on-startup>2</load-on-startup>
- </servlet>
- </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>
- <servlet-mapping>
- <servlet-name>action</servlet-name>
- <url-pattern>/execute/*</url-pattern>
- </servlet-mapping>
- </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>
- <servlet-mapping>
- <servlet-name>action</servlet-name>
- <url-pattern>*.do</url-pattern>
- </servlet-mapping>
- </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>
- <taglib>
- <taglib-uri>/WEB-INF/struts-bean.tld</taglib-uri>
- <taglib-location>/WEB-INF/struts-bean.tld</taglib-location>
- </taglib>
- <taglib>
- <taglib-uri>/WEB-INF/struts-html.tld</taglib-uri>
- <taglib-location>/WEB-INF/struts-html.tld</taglib-location>
- </taglib>
- <taglib>
- <taglib-uri>/WEB-INF/struts-logic.tld</taglib-uri>
- <taglib-location>/WEB-INF/struts-logic.tld</taglib-location>
- </taglib>
- <taglib>
- <taglib-uri>/WEB-INF/struts-template.tld</taglib-uri>
- <taglib-location>/WEB-INF/struts-template.tld</taglib-location>
- </taglib>
- </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><struts-config></code>.
+ </p>
+
+ <p>
+ Inside of the <struts-config> element, there two important elements that use
+ to describe your actions:
+
+ <blockquote>
+ <b><form-beans></b><br />
+ This section contains your form bean definitions. You use a >form-bean< 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><action-mappings></b><br />
+ This section contains your action definitions. You use an >action< 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 <form-bean> 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>
+ <struts-config>
+ <form-beans>
+ <form-bean name="logonForm"
+ type="org.apache.struts.example.LogonForm">
+ </form-beans>
+
+ <global-forwards type="org.apache.struts.action.ActionForward">
+ <forward name="logon" path="/logon.jsp" redirect="false" />
+ </global-forwards>
+
+ <action-mappings>
+
+ <action path="/logon"
+ type="org.apache.struts.example.LogonAction"
+ name="logonForm"
+ scope="request"
+ input="/logon.jsp"
+ unknown="false"
+ validate="true" />
+ </action-mappings>
+ </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><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>
+ <struts-config>
+ <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"/>
+ </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>
+ <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>
+ <init-param>
+ <param-name>debug</param-name>
+ <param-value>2</param-value>
+ </init-param>
+ <init-param>
+ <param-name>mapping</param-name>
+ <param-value>org.apache.struts.example.ApplicationMapping</param-value>
+ </init-param>
+ <load-on-startup>2</load-on-startup>
+ </servlet>
+ </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>
+ <servlet-mapping>
+ <servlet-name>action</servlet-name>
+ <url-pattern>/execute/*</url-pattern>
+ </servlet-mapping>
+ </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>
+ <servlet-mapping>
+ <servlet-name>action</servlet-name>
+ <url-pattern>*.do</url-pattern>
+ </servlet-mapping>
+ </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>
+ <taglib>
+ <taglib-uri>/WEB-INF/struts-bean.tld</taglib-uri>
+ <taglib-location>/WEB-INF/struts-bean.tld</taglib-location>
+ </taglib>
+ <taglib>
+ <taglib-uri>/WEB-INF/struts-html.tld</taglib-uri>
+ <taglib-location>/WEB-INF/struts-html.tld</taglib-location>
+ </taglib>
+ <taglib>
+ <taglib-uri>/WEB-INF/struts-logic.tld</taglib-uri>
+ <taglib-location>/WEB-INF/struts-logic.tld</taglib-location>
+ </taglib>
+ <taglib>
+ <taglib-uri>/WEB-INF/struts-template.tld</taglib-uri>
+ <taglib-location>/WEB-INF/struts-template.tld</taglib-location>
+ </taglib>
+ </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" /></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}&t={94AE5B48-1D7D-462A-A4A6-83CE19EC0705}&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>