husted 01/02/11 13:39:21
Modified: src/doc/userGuide introduction.xml building_model.xml
building_view.xml building_controller.xml
Log:
(Submitted by Ted Husted). Minor corrections and stylistic changes.
Revision Changes Path
1.10 +3 -2 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.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- introduction.xml 2001/01/21 12:57:51 1.9
+++ introduction.xml 2001/02/11 21:39:20 1.10
@@ -77,8 +77,9 @@
<p>
True to the Model-View-Controller design pattern, Struts applications
have three
- major components: a servlet controller, JavaServer pages, and the
application's
- business logic (or the "model"). Let's step through how this all fits
together.</p>
+ major components: a servlet controller, JavaServer pages (the "view"),
and the
+ application's business logic (or the "model"). Let's step through how
this all
+ fits together.</p>
<p>
The controller bundles and routes HTTP requests to other objects in the
framework,
including JavaServer Pages. When initialized, the controller parses a
configuration
1.12 +15 -40 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.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- building_model.xml 2001/01/23 05:06:49 1.11
+++ building_model.xml 2001/02/11 21:39:20 1.12
@@ -4,6 +4,7 @@
<properties>
<author>Craig R. McClanahan</author>
<author>Mike Schachter</author>
+ <author>Ted Husted</author>
<title>The Struts User's Guide - Building Model Components</title>
</properties>
@@ -119,15 +120,10 @@
<li>The ActionForm object also offers a standard validation mechanism.
If you override a "stub" method, and provide error messages in the
standard application resource, Struts will automatically validate the
- input from the form (using your method). If validation fails, Struts
- can automatically return the user to the input form, re-populate
- the form from the form bean, and display your error messages (via a
- custom tag), all before the Action object is ever called. This is a
- quick and easy way to get simple validation out of the way, but you
- might also want to provide further "business logic" validation as
- part of your Action object. (See "Action Form Validation" for details.)
- Of course, you can also ignore the ActionForm validation and provide
- your own in the Action object.</li>
+ input from the form (using your method). See "<a
+ href="./building_view.html#form_validation">Action Form Validation</a>"
+ for details. Of course, you can also ignore the ActionForm validation
+ and provide your own in the Action object.</li>
<li>Define a property (with associated <code>getXxx()</code> and
<code>setXxx()</code> methods) for each field that is present
in the form. The field name and property name must match according
@@ -137,9 +133,9 @@
<li>You may also place a bean instance on your form, and use nested
property
references. For example, you might have a "customer" bean on your
Action
Form, and then refer to the property "customer.name" in your JSP view.
- This would correspond to the methods customer.getName() and
- customer.setName(string Name) on your customer bean. See the Tag
Library
- Developer Guides for more about nested syntax.</li>
+ This would correspond to the methods <code>customer.getName()</code>
and
+ <code>customer.setName(string Name)</code> on your customer bean. See
the
+ Tag Library Developer Guides for more about nested syntax.</li>
</ul>
<p>
@@ -152,8 +148,8 @@
properties for all of the fields, no matter which page the field is
actually
displayed on. Likewise, the various pages of the same form should all be
submitted to the same Action Class. If you follow these suggestions, the
- page designers can rearrange the fields among the various pages, with no
- changes required to the processing logic in most cases.
+ page designers can rearrange the fields among the various pages, pftem
without
+ requiring changes to the processing logic.
</p>
</section>
@@ -176,7 +172,7 @@
for a long period of time, a set of system state beans may contain all the
knowledge that the system ever has of these particular details. Or, as is
often the case, the system state beans will represent information that is
- stored permanently in some external database (such as a CustomerBean object
+ stored permanently in some external database (such as a
<code>CustomerBean</code> object
that corresponds to a particular row in the CUSTOMERS table), and are
created or removed from the server's memory as needed. Entity Enterprise
JavaBeans are also used for this purpose in large scale applications.
@@ -230,31 +226,10 @@
from within a Action perform method.
</p>
<pre>
-public ActionForward
- perform(ActionMapping mapping,
- ActionForm form,
- HttpServletRequest request,
- HttpServletResponse response)
-{
- try {
- javax.sql.DataSource dataSource =
- servlet.findDataSource(null);
- java.sql.Connection myConnection =
- dataSource.getConnection();
- //do what you wish with myConnection
- } catch (SQLException sqle) {
- getServlet().log("Connection.process", sqle);
- } finally {
- //enclose this in a finally block to make
- //sure the connection is closed
- try {
- myConnection.close();
- } catch (SQLException e) {
- getServlet().log("Connection.close", e);
- }
- }
-}
-</pre>
+public ActionForward<br/> perform(ActionMapping mapping,<br/>
ActionForm form,<br/> HttpServletRequest request,<br/>
HttpServletResponse response)<br/>{<br/>
+ try {<br/> javax.sql.DataSource dataSource =<br/>
servlet.findDataSource(null);<br/> java.sql.Connection myConnection =<br/>
dataSource.getConnection();<br/>
+ //do what you wish with myConnection<br/> } catch (SQLException sqle) {<br/>
getServlet().log("Connection.process", sqle);<br/> } finally {<br/>
+ //enclose this in a finally block to make<br/> //sure the connection is
closed<br/> try {<br/> myConnection.close();<br/> } catch (SQLException e)
{<br/> getServlet().log("Connection.close", e);<br/> }<br/>
}<br/>}<br/></pre>
<p align="center">
Next: <a href="building_view.html">Building View Components</a>
1.15 +69 -117 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.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- building_view.xml 2001/02/06 19:54:00 1.14
+++ building_view.xml 2001/02/11 21:39:20 1.15
@@ -4,6 +4,7 @@
<properties>
<author>Craig R. McClanahan</author>
<author>Mike Schachter</author>
+ <author>Ted Husted</author>
<title>The Struts User's Guide - Building View Components</title>
</properties>
@@ -69,7 +70,7 @@
the first runtime argument, <code>{1}</code> is replaced by the second
argument, and so on.</li>
<li><b>MessageResources</b> - The Struts class
- <code>org.apache.struts.util.MessageResources</code> lets you treat
+ <code><a
href="api/org/apache/struts/util/MessageResources.html">org.apache.struts.util.MessageResources</a></code>
lets you treat
a set of resource bundles like a database, and allows you to request
a particular message string for a particular Locale (normally one
associated with the current user) instead of for the default Locale
@@ -80,7 +81,7 @@
For an internationalized application, follow the steps described in
the Internationalization document in the JDK documentation bundle for your
platform to create a properties file containing the messages for each
- language. An example will illustrate this further.
+ language. An example will illustrate this further:
</p>
<p>
@@ -110,8 +111,18 @@
deployment descriptor, one of the things you will need to define in
an initialization parameter is the base name of the resource bundle
for the application. In the case described above, it would be
- <code>com.mycompany.mypackage.MyResources</code>.
+ <code>com.mycompany.mypackage.MyResources</code>.
</p>
+<pre>
+<servlet><br/> <servlet-name>action</servlet-name><br/>
<servlet-class>org.apache.struts.action.ActionServlet</servlet-class><br/>
<init-param><br/> <param-name>application</param-name><br/>
<param-value>com.mycompany.mypackage.MyResources</param-value><br/>
</init-param><br/> <.../><br/></servlet></pre>
+
+ <p>
+ The important thing is for the resource bundle to be found on the
+ class path for your application. Another approach is to store
+ the <code>MyResources.properties</code> file in your application's
+ class folder. You can then simply specify "myResources" as the
+ application value.
+ </p>
</section>
<section name="3.3 Forms and FormBean Interactions" href="form_beans">
@@ -133,9 +144,7 @@
</p>
<pre>
-<input type="text" name="username"
- value="<%= loginBean.getUsername() %>"/>
-</pre>
+<input type="text" name="username"<br/> value="<%=
loginBean.getUsername() %>"/></pre>
<p>
which is difficult to type correctly, confuses HTML developers who are
@@ -145,9 +154,8 @@
The case above would be rendered like this using Struts:
</p>
-<pre>
-<html:text property="username"/>
-</pre>
+<pre>
+<html:text property="username"/></pre>
<p>
with no need to explicitly refer to the JavaBean from which the initial
@@ -170,58 +178,18 @@
and standard JSP facilities. Consider the following page (based on the
example application included with Struts) named <code>logon.jsp</code>:
</p>
-
+<hr/>
<pre>
-<%@ page language="java" %>
-<%@ taglib uri="/WEB-INF/struts-html.tld"
- prefix="html" %>
-<%@ taglib uri="/WEB-INF/struts-bean.tld"
- prefix="bean" %>
-<html:html>
-<head>
-<title>
- <bean:message key="logon.title"/>
-</title>
-<body bgcolor="white">
-<html:errors/>
-<html:form name="logonForm" action="logon.do">
-<table border="0" width="100%">
- <tr>
- <th align="right">
- <html:message key="prompt.username"/>
- </th>
- <td align="left">
- <html:text property="username"
- size="16"/>
- </td>
- </tr>
- <tr>
- <th align="right">
- <html:message key="prompt.password"/>
- </th>
- <td align="left">
- <html:password property="password"
- size="16"/>
- </td>
- </tr>
- <tr>
- <td align="right">
- <struts:submit>
- <bean:message key="button.submit"/>
- </struts:submit>
- </td>
- <td align="right">
- <html:reset>
- <bean:message key="button.reset"/>
- </html:reset>
- </td>
- </tr>
-</table>
-</html:form>
-</body>
-</html:html>
-</pre>
-
+<%@ page language="java" %><br/><%@ taglib
uri="/WEB-INF/struts-html.tld"<br/> prefix="html" %><br/><%@ taglib
uri="/WEB-INF/struts-bean.tld"<br/> prefix="bean" %>
+<html:html><br/><head><br/><title><br/> <bean:message
key="logon.title"/><br/></title><br/>
+<body bgcolor="white"><br/><html:errors/><br/>
+<html:form name="logonForm" action="logon.do"<br/>
type="org.apache.struts.example.LogonForm"><br/><table border="0"
width="100%"><br/>
+ <tr><br/> <th align="right"><br/> <html:message
key="prompt.username"/><br/> </th><br/> <td align="left"><br/>
<html:text property="username"<br/> size="16"/><br/>
</td><br/> </tr>
+ <tr><br/> <th align="right"><br/> <html:message
key="prompt.password"/><br/> </th><br/> <td align="left"><br/>
<html:password property="password"<br/>
size="16"/><br/> </td><br/> </tr>
+ <tr><br/>
+ <td align="right"><br/> <struts:submit><br/>
<bean:message key="button.submit"/><br/> </struts:submit><br/>
</td><br/> <td align="right"><br/> <html:reset><br/>
<bean:message key="button.reset"/><br/> </html:reset><br/>
</td><br/> </tr><br/></table><br/></html:form>
+</body><br/></html:html></pre>
+<hr/>
<p>
The following items illustrate the key features of form handling in
Struts,
based on this example:
@@ -262,10 +230,12 @@
This bean is used to provide initial values for all of the input
fields that have names matching the property names of the bean.
If an appropriate bean is not found, a new one will be created
- automatically, using the specified Java class name. (The form bean
name
- can also be specified in the Struts configuration file, and then
omitted
+ automatically, using the specified Java class name.
+ <li>The form bean can also be specified in the Struts configuration
file,
+ in which case the Name and Type can be omitted
here. See "<a href="building_controller.html#config">The Action
Mappings
Configuration File</a>" for details.)</li>
+ </li>
<li>The text tag renders an HTML
<code><input></code> element of type "text". In this case,
the number of character positions to occupy on the browser's screen
@@ -288,48 +258,25 @@
creating a multipart form is to utilize the struts-html taglib to create
the presentation
page:
</p>
-
-<pre>
-<%@page language="java">
-<%@taglib uri="/WEB-INF/struts-html.tld"
- prefix="html">
-<html:form action="uploadAction.do">
- Please Input Text:
- <html:text property="myText"><br/>
- Please Input The File You Wish to Upload:<br/>
- <html:file property="myFile"><br />
- <html:submit />
-</html:form>
-</pre>
+<hr/>
+<pre>
+<%@page language="java"><br/><%@taglib uri="/WEB-INF/struts-html.tld"<br/>
prefix="html"><br/>
+<html:form action="uploadAction.do"><br/> Please Input Text:<br/>
<html:text property="myText"><br/><br/> Please Input The File You Wish to
Upload:<br/><br/> <html:file property="myFile"><br /><br/> <html:submit
/><br/></html:form></pre>
+<hr/>
<p>
The next step is to create your ActionForm bean:
</p>
+<hr/>
<pre>
-import javax.servlet.http.HttpServletRequest;
-import javax.servlet.http.HttpServletResponse;
-import org.apache.struts.action.ActionForm;
-import org.apache.struts.action.ActionMapping;
-import org.apache.struts.upload.FormFile;
-public class UploadForm extends ActionForm {
- protected String myText;
- protected FormFile myFile;
- public void setMyText(String text) {
- myText = text;
- }
- public String getMyText() {
- return myText;
- }
- public void setMyFile(FormFile file) {
- myFile = file;
- }
- public FormFile getMyFile() {
- return myFile;
- }
-}
-</pre>
-
+import javax.servlet.http.HttpServletRequest;<br/>import
javax.servlet.http.HttpServletResponse;<br/>import
org.apache.struts.action.ActionForm;<br/>import
org.apache.struts.action.ActionMapping;<br/>import org.apache.struts.upload.FormFile;
+public class UploadForm extends ActionForm {<br/> protected String myText;<br/>
protected FormFile myFile;
+ public void setMyText(String text) {<br/> myText = text;<br/> }
+ public String getMyText() {<br/> return myText;<br/> }
+ public void setMyFile(FormFile file) {<br/> myFile = file;<br/> }
+ public FormFile getMyFile() {<br/> return myFile;<br/> }<br/>}</pre>
+<hr/>
<p>
Look at the <a href="../api/index.html">javadocs</a> for FormFile to see
the
methods it exposes to manipulate files in file uploading. Also look at
the
@@ -344,7 +291,7 @@
<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,
+ Struts defines HTML tags for all of the following types of input fields,
with hyperlinks to the corresponding reference information.
</p>
@@ -378,10 +325,10 @@
<ul>
- <li><a href="../struts-logic.html#iterate">iterate</a> repeats its tag
body once
+ <li>[logic] <a href="../struts-logic.html#iterate">iterate</a> repeats
its tag body once
for each element of a specified collection (which can be an
Enumeration,
a Hashtable, a Vector, or an array of objects).</li>
- <li><a href="../struts-logic.html#present">present</a> depending on which
attribute
+ <li>[logic] <a href="../struts-logic.html#present">present</a> depending
on which attribute
is specified, this tag checks the current request, and evaluates the
nested
body content of this tag only if the specified value is present. Only
one of
the attributes may be used in one occurrence of this tag, unless you
use the
@@ -389,22 +336,26 @@
attributes include cookie, header, name, parameter, property, role,
scope,
and user.
</li>
- <li><a href="../struts-logic.html#notPresent">notPresent</a> the
companion tag to
+ <li>[logic] <a href="../struts-logic.html#notPresent">notPresent</a> the
companion tag to
present, notPresent provides the same functionality when the
specified attribute
is not present.</li>
- <li><a href="../struts-html.html#link">link</a> generates a HTML
<a> element
+ <li>[html] <a href="../struts-html.html#link">link</a> generates a HTML
<a> element
as an anchor definition or a hyperlink to the specified URL, and
automatically
applies URL encoding to maintain session state in the absence of
cookie support.</li>
- <li><a href="../struts-bean.html#parameter">parameter</a> retrieves the
value of the
+ <li>[html] <a href="../struts-html.html#img">img</a> generates a HTML
<img> element
+ with the ability to dynamically modify the URLs specified by the
"src" and
+ "lowsrc" attributes in the same manner that <html:link> can.
+ </li>
+ <li>[bean] <a href="../struts-bean.html#parameter">parameter</a>
retrieves the value of the
specified request parameter, and defines the result as a page scope
attribute of
type String or String[].</li>
</ul>
</section>
- <section name="3.3.4 Automatic Form Validation" href="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
offers an additional facility to validate the input fields it has
received.
@@ -412,11 +363,7 @@
class:
</p>
-<pre>
-public ActionErrors
- validate(ActionMapping mapping,
- HttpServletRequest request);
-</pre>
+<pre>public ActionErrors<br/> validate(ActionMapping mapping,<br/>
HttpServletRequest request);</pre>
<p>
The validate() method is called by the controller servlet after the bean
@@ -427,9 +374,9 @@
<ul>
<li>Perform the appropriate validations and find no problems -- Return
either
- <code>null</code> or a zero-length ActionErrors instance, and the
controller servlet
- will proceed to call the <code>perform()</code> method of the
appropriate
- <code>Action</code> class.</li>
+ <code>null</code> or a zero-length ActionErrors instance, and the
controller
+ servlet will proceed to call the <code>perform()</code> method of the
+ appropriate <code>Action</code> class.</li>
<li>Perform the appropriate validations and find problems -- Return an
ActionErrors
instance containing <code>ActionError</code>'s, which are classes
that contain
the error message keys (into the application's
@@ -445,6 +392,11 @@
of the validate() method returns <code>null</code>, and the controller
servlet
will assume that any required validation is done by the action class.
</p>
+ <p>
+ One common approach is to perform simple validations using the validate()
method, and
+ also provide further "business logic" validation as part of your Action
object.
+ </p>
+
</section>
</section>
@@ -469,16 +421,16 @@
</p>
<ul>
- <li><code>checkLogon</code> - Checks for the existence of a particular
session
+ <li><b>checkLogon</b> - Checks for the existence of a particular session
object, and forwards control to the logon page if it is missing.
This is
used to catch cases where a user has bookmarked a page in the middle
of
your application and tries to bypass logging on, or if the user's
session
has been timed out.</li>
- <li><code>linkSubscription</code> - Generates a hyperlink to a details
page
+ <li><b>linkSubscription</b> - Generates a hyperlink to a details page
for a Subscription, which passes the required primary key values as
request attributes. This is used when listing the subscriptions
associated
with a user, and providing links to edit or delete them.</li>
- <li><code>linkUser</code> - Generates a hyperlink to a details page
+ <li><b>linkUser</b> - Generates a hyperlink to a details page
for a User, which passes the required primary key values as
request attributes.</li>
</ul>
1.10 +38 -39 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.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- building_controller.xml 2001/01/23 05:06:49 1.9
+++ building_controller.xml 2001/02/11 21:39:20 1.10
@@ -4,6 +4,7 @@
<properties>
<author>Craig R. McClanahan</author>
<author>Mike Schachter</author>
+ <author>Ted Husted</author>
<title>The Struts User's Guide - Building Controller Components</title>
</properties>
@@ -172,35 +173,7 @@
<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">
@@ -245,7 +218,7 @@
<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:
+ the following attributes to be defined:
<ul>
<li>
@@ -258,7 +231,8 @@
<b>name</b>: The name of your <form-bean> element to use with
this action
</li>
</ul>
- </blockquote>
+ </blockquote>
+
</p>
<p>
@@ -294,14 +268,14 @@
</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
+ First the form bean is defined. A basic bean of class
"<code>org.apache.struts.example.LogonForm</code>"
+ is mapped to the logical name "<code>logonForm</code>". 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
+ The "<code>global-forwards</code>" 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")
+ i.e. <code>actionMappingInstace.findForward("logicalName")</code>.
</p>
<p>
As you can see, this mapping matches the path <code>/logon</code> (actually,
@@ -312,6 +286,31 @@
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>
+ An optional but very useful section is the local "<local>forwards</code>".
In the example
+ application, many actions include a local "success" and/or "failure"
forward as
+ part of an Action mapping.
+ </p>
+<pre>
+<!-- Edit mail subscription -->
+<action path="/editSubscription"
+ type="org.apache.struts.example.EditSubscriptionAction"
+ name="subscriptionForm"
+ scope="request"
+ validate="false">
+ <forward name="failure" path="/mainMenu.jsp"/>
+ <forward name="success" path="/subscription.jsp"/>
+ </action>
+</pre>
+
+ <p>Using just 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. Of course,
you can define
+ whatever local forward properties makes sense for your own application.
+ </p>
<p>
One more section of good use is the <code><data-sources></code> section,
which
@@ -498,9 +497,9 @@
which means that a request URI to match the <code>/logon</code> path
described earlier might look like this:</p>
-<pre><font size="-1">
+<pre>
http://www.mycompany.com/myapplication/execute/logon
-</font></pre>
+</pre>
<p>
where <code>/myapplication</code> is the context path under which your
@@ -528,9 +527,9 @@
earlier might look like this:
</p>
-<pre><font size="-1">
+<pre>
http://www.mycompany.com/myapplication/logon.do
-</font></pre>
+</pre>
</section>
<section name="4.5.3 Configure the Struts Tag Library"
href="dd_config_taglib">
