husted 01/11/03 19:07:34
Modified: doc/userGuide introduction.xml index.xml building_view.xml
building_model.xml building_controller.xml
Log:
Several stylistic changes. Add caution regarding using nested beans with
ActionForms. Add section regarding rendering text.
Revision Changes Path
1.8 +1 -1 jakarta-struts/doc/userGuide/introduction.xml
Index: introduction.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/introduction.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- introduction.xml 2001/11/03 12:24:25 1.7
+++ introduction.xml 2001/11/04 03:07:34 1.8
@@ -355,7 +355,7 @@
control should be forwarded so that an action method can ask for the
"Main Menu" page (for example), without knowing what the actual name of the
corresponding JSP page is. These features greatly assist you in separating
- the control logic (what to do) with the view logic (how it's done).
+ the control logic (what to do) with the view logic (how it's rendered).
</p>
<p align="center">
1.5 +1 -0 jakarta-struts/doc/userGuide/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/index.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- index.xml 2001/10/05 11:19:29 1.4
+++ index.xml 2001/11/04 03:07:34 1.5
@@ -50,6 +50,7 @@
<li><a href="building_view.html#custom_tags">3.4.1
Application-Specific Custom Tags</a></li>
<li><a href="building_view.html#includes">3.4.2 Page
Composition With Includes</a></li>
<li><a href="building_view.html#image_rendering">3.4.3 Image
Rendering Components</a></li>
+ <li><a href="building_view.html#text_rendering">3.4.4 Rendering
Text</a></li>
</ul></li>
</ul></li>
<li><a href="building_controller.html">4. Building Controller
Components</a>
1.6 +59 -21 jakarta-struts/doc/userGuide/building_view.xml
Index: building_view.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/building_view.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- building_view.xml 2001/10/19 05:51:09 1.5
+++ building_view.xml 2001/11/04 03:07:34 1.6
@@ -80,10 +80,11 @@
</ul>
<p>
- Please note that the i18n support in Struts is currently limited to the
- <b>presentation</b> of internationalized information to the user.
- Support for various Locale specific <b>input methods</b> is left up
- to the client device, which is usually a web browser.
+ Please note that the i18n support in a framework like Struts is limited to
the
+ <b>presentation</b> of internationalized text and images to the user.
+ Support for Locale specific <b>input methods</b> (used with languages
+ such as Japanese, Chinese, and Korean) is left up to the client device,
which
+ is usually a web browser.
</p>
<p>
@@ -138,13 +139,24 @@
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.
+ <code>classes</code> folder. You can then simply specify "myResources" as
the
+ application value. Just be careful it is not deleted if your
+ build script deletes classes as part of a "clean" target.
</p>
+ <p>
+ If it does, here is an Ant task to run when compiling your application
+ that copies the contents of a <code>src/conf</code>
+ directory to the <code>classes</code> directory:
+ </p>
+ <pre>
+ <!-- Copy any configuration files -->
+ <copy todir="classes">
+ <fileset dir="src/conf"/>
+ </copy>
+ </pre>
</section>
- <section name="3.3 Forms and FormBean Interactions" href="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
the standard capabilities of HTML, such as the <code><input></code>
@@ -189,8 +201,9 @@
files. Struts handles these "multipart" forms in a way identical to
building normal forms. In the next section, we will cover using Struts to
create a simple login form, and also a simple mulitpart form.
- </p>
-
+ </p>
+ </section>
+
<section name="3.3.1 Building Forms With Struts" href="forms">
<p>
@@ -366,9 +379,9 @@
</pre>
<hr/>
<p>
- Look at the <a href="../api/index.html">javadocs</a> for FormFile to see
the
+ 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
- javadocs for ActionServlet and ActionMapping for the various parameters
+ Javadocs for ActionServlet and ActionMapping for the various parameters
you can specify to change how files are uploaded. Basically in your
peform() method in your action class you would call <code>((UploadForm)
form).getMyFile()</code>
to retrieve the FormFile and do what you want with it.
@@ -440,7 +453,6 @@
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">
@@ -485,12 +497,16 @@
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.
+ One common approach is to perform simple, prima facia validations using
the
+ ActionForm validate() method, and then handle the "business logic"
validation
+ from the Action.
</p>
-
+ <p>
+ An optional package for performing ActionForm validations is available in
the
+ Nightly Build and from <a href="http://home.earthlink.net/~dwinterfeldt/";>
+ David Winterfeldt's Web site</a>.
+ </p>
</section>
- </section>
<section name="3.4 Other Presentation Techniques" href="other_presentations">
@@ -501,6 +517,7 @@
reuse, reduce maintenance efforts, and/or reduce errors. Several options
are discussed in the following sections.
</p>
+ </section>
<section name="3.4.1 Application-Specific Custom Tags" href="custom_tags">
@@ -569,9 +586,9 @@
<ul>
<li>An <code><%@ include file="xxxxx" %></code> directive can
include a file that contains
- java code or jsp tags. The code in the included file can even reference
+ Java code or JSP tags. The code in the included file can even reference
variables declared earlier in the outer jsp page. The code is inlined into
- the other jsp before it is compiled so it can definately contain more than
+ the other JavaServer Page before it is compiled so it can definately
contain more than
just HTML.</li>
<li>The include <i>action</i> (<code><jsp:include page="xxxxx"
flush="true" /></code>) is processed at request time, and is
handled
@@ -588,6 +605,12 @@
Another approach to this would be to use the Struts Template Tag library.
See the
Developer's Guide for details.
</p>
+ <p>
+ Tiles is an alternative to the original Template Tag library, offering
several
+ enhancements and new capabilities. Tiles is available in the
+ Nightly Build, and from <a href="http://www.lifl.fr/~dumoulin/tiles/";>
+ Cedric Dumoulin's Web site</a>.
+ </p>
</section>
<section name="3.4.3 Image Rendering Components" href="image_rendering">
@@ -610,12 +633,27 @@
can have the applet make its own connection to the server to receive
these parameters.</li>
</ul>
-
+ </section>
+
+ <section name="3.4.4 Rendering Text" href="text_rendering">
+
+ <p>
+ Some applications require dynamically generated text or markup,
+ such as XML. If a complete page is being rendered, and can be output
+ using a PrintWriter, this is very easy to do from an Action:
+ </p>
+ <pre>
+ response.setContentType("text/plain"); // or text/xml
+ PrintWriter writer = response.getWriter();
+ // use writer to render text
+ return(null);
+ </pre>
+
<p align="center">
Next: <a href="building_controller.html">Building Controller
Components</a>
</p>
</section>
- </section>
+
</chapter>
</body>
</document>
1.4 +17 -2 jakarta-struts/doc/userGuide/building_model.xml
Index: building_model.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/building_model.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- building_model.xml 2001/10/19 05:51:09 1.3
+++ building_model.xml 2001/11/04 03:07:34 1.4
@@ -85,7 +85,7 @@
than the <i>Model</i>.
</p>
<p>
- The Struts framework generally assumes that you have created an
+ The Struts framework generally assumes that you have defined an
<code>ActionForm</code> bean (that is, a Java class extending the
<code>ActionForm</code> class) for each input form required in your
application. <code>ActionForm</code> beans are sometimes just called
@@ -135,12 +135,22 @@
to the usual JavaBeans conventions. For example, an input field named
<code>username</code> will cause the <code>setUsername()</code> method
to be called.</li>
+ <li>Think of your ActionForm beans as a firewall between HTTP and the
Action.
+ Use the validate method to ensure all required properties are present,
and
+ that they contain reasonable values. An ActionForm that fails
validation
+ will not even be presented to the Action for handling.</li>
<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 <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>
+ <li><i>Caution:</i> If you nest an existing bean instance on your form,
think
+ about the properties it exposes. Any public property on an ActionForm
that
+ accepts a single String value can be set with a query string. It may be
+ useful to place such beans inside a thin "wrapper" that exposes only
the
+ properties required. This wrapper can also provide a filter to be
+ sure runtime properties are not set to inappropriate values.</li>
</ul>
<p>
@@ -222,7 +232,7 @@
<p>
Struts can define the datasources for an application from within its
standard
- configuration file. A simple JDBC connection pool is also provided. See <a
+ configuration file. A <b>simple</b> JDBC connection pool is also provided.
See <a
href="building_controller.html#config">The Action Mappings Configuration
File</a>
section and the Utilities Developer Guide for details.
</p>
@@ -259,6 +269,11 @@
}
</pre>
+ <p>
+ Note that the Struts generic connection pool is an <b>optional</b>
component. Many
+ Struts applications use other connection pools for better performance,
+ especially with high-volume production systems.
+ </p>
<p align="center">
Next: <a href="building_view.html">Building View Components</a>
</p>
1.7 +27 -22 jakarta-struts/doc/userGuide/building_controller.xml
Index: building_controller.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/building_controller.xml,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- building_controller.xml 2001/10/19 05:51:09 1.6
+++ building_controller.xml 2001/11/04 03:07:34 1.7
@@ -24,14 +24,10 @@
</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>[Optionally] 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. This file is usually named
+ <li>Write an <code>Action</code> class for each logical request that may
+ be received (extend <code>org.apache.action.Action</code>).</li>
+ <li>Configure a ActionMapping (in XML) for each logical request that may
+ be submitted. The XML configuration file is usually named
<code>struts-config.xml</code>.</li>
<li>Update the web application deployment descriptor file (in XML)
for your application to include the necessary Struts components.</li>
@@ -60,31 +56,31 @@
</pre>
<p>
- Most people would only use the "HttpServletRequest" version.
+ Most projects would only use the "HttpServletRequest" version.
</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>MVC/Model 2</i> design pattern,
- a typical <code>Action</code> class will implement the following
- logic in its <code>perform()</code> method:
+ The goal of an <code>Action</code> class is to process a request, via
+ its <code>perform()</code> method, and return an <code>ActionForward</code>
object
+ that identifies where control should be forwarded (e.g. a JSP) to provide
+ the appropriate response. In the <i>MVC/Model 2</i> design pattern,
+ a typical <code>Action</code> class will often implement logic like the
following
+ 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
+ class finds that no logon exists, the request can 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
+ logging on. This could occur because a user tried to enter an
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,
+ <li>If validation is not complete,
+ validate the form bean properties as needed. 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
+ saving a row into a database). This can be done by logic 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
@@ -140,6 +136,12 @@
it is embedded inside a component (the <code>Action</code> class) that
is tied to being executed in a web application environment.
</p>
+
+ <p>
+ An <code>Action</code> can be factored into several local methods, so long
as all
+ properties needed are passed in the method signatures. The JVM
+ handles such properties using the stack, and so they are thread-safe.
+ </p>
<p>
The example application included with Struts stretches this design
@@ -167,7 +169,6 @@
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
@@ -175,6 +176,10 @@
<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>
+ <li><b>forward</b> - The request URI path to which control is passed
+ when his mapping is invoked. This is an alternative to declaring
+ a <b>type</b> property. </li>
+
</ul>
</section>
@@ -557,7 +562,7 @@
<p>
Next, you must add an entry defining the Struts tag library. There are
currently four
- taglibs that struts is packaged with.
+ taglibs that Struts is packaged with.
</p>
<p>
The struts-bean taglib contains tags useful in accessing
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
