husted 2002/06/29 07:12:01
Modified: doc/userGuide release-notes.xml project.xml index.xml
dev_validator.xml building_view.xml
building_model.xml building_controller.xml
Added: doc/userGuide dev_util.xml
Log:
Add "TODO" markers where 1.1 documentation can be added.
Add a Developers Guide portal page to link to package description,
API, and any other resources.
Revision Changes Path
1.3 +2 -0 jakarta-struts/doc/userGuide/release-notes.xml
Index: release-notes.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/release-notes.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- release-notes.xml 26 Jun 2002 23:36:11 -0000 1.2
+++ release-notes.xml 29 Jun 2002 14:12:01 -0000 1.3
@@ -242,6 +242,8 @@
<p>The following new features have been added to the Struts Documentation
application (and corresponding contents on the Struts web site):</p>
<ul>
+ <li>Added "cover page" to Develper Guides. These then link to the Package
Descriptions and the API guides.
+ Removed separate links to taglib documentation, since these are now in the
Developer Guide.</li>
<li>Move Tag Library documentation into User's Guide.</li>
<li>Added Kickstart FAQ.</li>
<li>Added Reference copy of 1.0 JavaDoc.</li>
1.13 +1 -1 jakarta-struts/doc/userGuide/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/project.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- project.xml 29 Jun 2002 03:21:02 -0000 1.12
+++ project.xml 29 Jun 2002 14:12:01 -0000 1.13
@@ -28,7 +28,7 @@
<item name="Tiles Tags"
href="dev_tiles.html"/>
<item name="Utilities"
- href="dev_utils.html"/>
+ href="dev_util.html"/>
<item name="Validator"
href="dev_validator.html"/>
</menu>
1.10 +10 -2 jakarta-struts/doc/userGuide/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/index.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- index.xml 29 Jun 2002 03:21:02 -0000 1.9
+++ index.xml 29 Jun 2002 14:12:01 -0000 1.10
@@ -57,6 +57,7 @@
<li><a href="building_view.html#form_input">3.3.2 Input Field
Types Supported</a></li>
<li><a href="building_view.html#presentation_tags">3.3.3 Other
Useful Presentation Tags</a></li>
<li><a href="building_view.html#form_validation">3.3.4
Automatic Form Validation</a></li>
+ <li><a href="building_view.html#struts_validator">3.3.5 Struts
Validator</a></li>
</ul></li>
<li><a href="building_view.html#other_presentations">3.4 Other
Presentation Techniques</a>
<ul>
@@ -70,8 +71,15 @@
<li><a href="building_controller.html">4. Building Controller
Components</a>
<ul>
<li><a href="building_controller.html#overview">4.1
Overview</a></li>
- <li><a href="building_controller.html#action_classes">4.2 Action
Classes</a></li>
- <li><a href="building_controller.html#actionmapping">4.3 The
ActionMapping Implementation</a></li>
+ <li><a href="building_controller.html#action_form_classes">4.2
ActionForm Classes</a></li>
+ <li><a
href="building_controller.html#dyna_action_form_classes">4.2.1 DynaActionForm
Classes</a></li>
+ <li><a
href="building_controller.html#map_action_form_classes">4.2.2 Map-backed ActionForm
Classes</a></li>
+ <li><a href="building_controller.html#action_classes">4.3 Action
Classes</a></li>
+ <li><a href="building_controller.html#plugin_classes">4.3.x Plugin
Classes</a></li>
+ <li><a href="building_controller.html#action_servlet">4.4 The
ActionServlet</a></li>
+ <li><a href="building_controller.html#request_controller">4.4.1
Request Processor</a></li>
+ <li><a href="building_controller.html#exception_handler">4.4.2
Exception Handler</a></li>
+ <li><a href="building_controller.html#actionmapping">4.5 The
ActionMapping Implementation</a></li>
<li><a href="building_controller.html#config">4.4 The Struts
Configuration File</a></li>
<li><a href="building_controller.html#dd_config">4.5 The Web
Application Deployment Descriptor</a>
<ul>
1.2 +2 -2 jakarta-struts/doc/userGuide/dev_validator.xml
Index: dev_validator.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/dev_validator.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- dev_validator.xml 29 Jun 2002 03:21:02 -0000 1.1
+++ dev_validator.xml 29 Jun 2002 14:12:01 -0000 1.2
@@ -3,10 +3,10 @@
<properties>
<author>Ted Husted</author>
<author>David Winterfeldt</author>
-<title>The Struts User's Guide - Validator Developer Guide</title>
+<title>The Struts User's Guide - Validator Guide</title>
</properties>
<body>
-<chapter name="Struts Validator Developer Guide">
+<chapter name="Struts Validator Guide">
<section href="validator" name="Struts Validator">
<p>
1.14 +31 -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.13
retrieving revision 1.14
diff -u -r1.13 -r1.14
--- building_view.xml 29 Jun 2002 03:21:02 -0000 1.13
+++ building_view.xml 29 Jun 2002 14:12:01 -0000 1.14
@@ -104,16 +104,16 @@
<code>com.mycompany.mypackage</code>, so it is stored in a directory
(relative to your source directory) named
<code>com/mycompany/mypackage</code>. To create a resource bundle called
- <code>com.mycompany.mypackage.MyResources</code>, you would create the
+ <code>com.mycompany.mypackage.MyApplication</code>, you would create the
following files in the <code>com/mycompany/mypackage</code> directory:
</p>
<ul>
- <li><b>MyResources.properties</b> - Contains the messages in the default
+ <li><b>MyApplication.properties</b> - Contains the messages in the default
language for your server. If your default language is English, you
might have an entry like this:
<code>prompt.hello=Hello</code></li>
- <li><b>MyResources_xx.properties</b> - Contains the same messages in the
+ <li><b>MyApplication_xx.properties</b> - Contains the same messages in the
language whose ISO language code is "xx" (See the
<a
href="http://java.sun.com/j2se/1.4.1/docs/api/java/util/ResourceBundle.html";>ResourceBundle
Javadoc</a>
page for a link to the current list). For a French version
@@ -127,7 +127,7 @@
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.MyApplication</code>.
</p>
<pre>
<servlet>
@@ -295,7 +295,7 @@
tags from the struts-bean library, and "html" as the prefix that
identifies
tags from the struts-html library. Any desired prefix can be
used.</li>
<li>This page uses several occurrences of the
- message tag to look up internationalized
+ <b>message</b> tag to look up internationalized
message strings from a <code>MessageResources</code> object containing
all the resources for this application. For this page to work, the
following message keys must be defined in these resources:
@@ -312,37 +312,43 @@
implement giving the user an option to switch languages -- simply
change
the stored <code>Locale</code> object, and all messages are switched
automatically.</li>
- <li>The errors tag displays any error
+ <li>The <b>errors</b> tag displays any error
messages that have been stored by a business logic component, or
nothing
if no errors have been stored. This tag will be described further
below.</li>
- <li>The form tag renders an HTML
+ <li>The <b>form</b> tag renders an HTML
<code><form></code> element, based on the specified attributes.
- It also associates all of the fields within this form with a session
- scoped FormBean that is stored under the key <code>logonForm</code>.
- The Struts developer provides the Java implementation of this form
+ It also associates all of the fields within this form with a
+ <code>ActionForm</code> bean
[<code>org.apache.struts.action.ActionForm</code>].
+ The tag looks up the <code>/logon</code> action mapping in the Struts
+ configuration.
+ The <code>logon</code> mapping tells the tag that the form bean is
stored
+ in the session context under the key <code>logonForm</code>.
+ The Struts developer provides the Java implementation of the
ActionForm
bean, subclassing the Struts class <code>ActionForm</code>
- (see <a href="building_controller">Building Controller</a>
components).
+ (see <a href="building_controller.html#action_form_classes">Building
+ Controller</a> components).
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.
- <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 Struts
- Configuration File</a>" for details.)</li>
+ automatically, using the Java class name specified through the action
+ mapping.</li>
+ <li>The form bean can also be specified in the tag by providing
+ <code>name</code> and <code>type</code> attributes. But most often,
+ everything is specified in the
+ <a href="building_controller.html#config">Struts Configuration
File</a>.
</li>
- <li>The text tag renders an HTML
+ <li>The <b>text</b> 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
- has been specified as well. When this page is executed, the current
+ has been specified as well. When this page is executed, the current
value of the <code>username</code> property of the corresponding bean
(that is, the value returned by <code>getUsername</code>).</li>
- <li>The password tag is used similarly.
+ <li>The <b>password</b> tag is used similarly.
The difference is that the browser will echo asterisk characters,
instead of the input value, as the user types their password.</li>.
- <li>The submit and
- reset tags generate the corresponding
+ <li>The <b>submit</b> and
+ <b>reset</b> tags generate the corresponding
buttons at the bottom of the form. The text labels for each button
are created using message tags,
as with the prompts, so that these values are internationalized.</li>
@@ -530,6 +536,10 @@
</p>
</section>
+ <section name="3.3.5 The Struts Validator" href="validator">
+ <p>[:TODO:]</p>
+ </section>
+
<section name="3.4 Other Presentation Techniques" href="other_presentations">
<p>
1.10 +22 -51 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.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- building_model.xml 28 Jun 2002 20:59:59 -0000 1.9
+++ building_model.xml 29 Jun 2002 14:12:01 -0000 1.10
@@ -114,69 +114,40 @@
JSP action <code><jsp:setProperty></code> when you use the
asterisk wildcard to select all properties.</li>
<li>The updated <code>ActionForm</code> bean will be passed to the
- Action Class <code>execute</code> method when it is called,
- making these values immediately available.</li>
+ <code>execute</code> method of an <code>Action</code> class
+ [<code>org.apache.struts.Action</code>], so that the values can
+ be made available to your system state and business logic beans.</li>
</ul>
<p>
- When you code your <code>ActionForm</code> beans, keep the following
- principles in mind:
+ For more about coding <code>Actions</code> and <code>ActionForm</code>
+ beans, see the "<a href="building_controller.html">Building
+ Controller Components</a>" chapter.
</p>
-
- <ul>
- <li>The <code>ActionForm</code> class itself requires no specific
- methods to be implemented. It is used to identify the role these
- particular beans play in the overall architecture. Typically, an
- <code>ActionForm</code> bean will have only property getter and
- property setter methods, with no business logic.</li>
- <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). 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
- 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>Buttons and other controls on your form can also be defined as
properties.
- This can help determine which button or control was selected when the
- form was submitted. Remember, the ActionForm is meant to represent your
- data-entry form, not just the data beans.</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>
You should note that a "form", in the sense discussed here, does not
necessarily correspond to a single JSP page in the user interface. It is
common in many applications to have a "form" (from the user's perspective)
- that extends over multiple pages. Think, for example, of the wizard style
+ that extends over multiple pages. Think, for example, of the wizard style
user interface that is commonly used when installing new applications.
Struts
encourages you to define a single <code>ActionForm</code> bean that contains
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
+ 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, often
without
requiring changes to the processing logic.
</p>
+
+ <p>
+ Smaller applications may only need a single ActionForm to service all of
+ its input forms. Others applications might use a single ActionForm for each
+ major subsystem of the application. Some teams might prefer to have a
+ separate ActionForm class for each distinct input form or workflow. How
many
+ or how few ActionForms to use is entirely up to you. The framework doesn't
+ care.
+ </p>
+
</section>
<section name="2.4 System State Beans" href="system_state">
@@ -264,8 +235,8 @@
that works well with the datasource manager. If another component
is not specified, the Generic DataSource pool is used by default.
See <a href="building_controller.html#config">The Struts
- Configuration File</a> section and the Utilities Developer Guide for
- more detail.
+ Configuration File</a> section and the <a href="dev_utils">Utilities
+ Developer Guide</a> for more detail.
</p>
<p>
After the datasource is defined, here is an example of using the
@@ -302,7 +273,7 @@
</pre>
<p>
- Note that the Struts connection pool
[org.apache.struts.util.GenericDataSource]
+ Note that the Struts connection pool
[<code>org.apache.struts.util.GenericDataSource</code>]
has <b>not</b> been optimized for performance. Many Struts applications use
other connection
pools, especially with high-volume production systems. If your DBMS or
container
provides a connection pool of its own, that may be a better choice.
1.19 +65 -12 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.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- building_controller.xml 29 Jun 2002 03:21:02 -0000 1.18
+++ building_controller.xml 29 Jun 2002 14:12:01 -0000 1.19
@@ -39,7 +39,54 @@
</section>
<section name="4.2 ActionForm Classes" href="action_form_classes">
- <p>[:TODO:]</p>
+
+ <p>[:TODO: introduction paragraph ]</p>
+
+ <p>
+ When you code your <code>ActionForm</code> beans, keep the following
+ principles in mind:
+ </p>
+
+ <ul>
+ <li>The <code>ActionForm</code> class itself requires no specific
+ methods to be implemented. It is used to identify the role these
+ particular beans play in the overall architecture. Typically, an
+ <code>ActionForm</code> bean will have only property getter and
+ property setter methods, with no business logic.</li>
+ <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). 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
+ 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>Buttons and other controls on your form can also be defined as
properties.
+ This can help determine which button or control was selected when the
+ form was submitted. Remember, the ActionForm is meant to represent your
+ data-entry form, not just the data beans.</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>
</section>
<section name="4.2.1 DynaActionForm Classes" href="dyna_action_form_classes">
@@ -185,7 +232,11 @@
<p>[:TODO:]</p>
</section>
- <section name="4.4.x Exception Handler" href="exception_handler">
+ <section name="4.4.1 Request Processor" href="request_processor">
+ <p>[:TODO:]</p>
+ </section>
+
+ <section name="4.4.2 Exception Handler" href="exception_handler">
<p>[:TODO:]</p>
</section>
@@ -218,7 +269,7 @@
a <b>type</b> property. </li>
</ul>
-
+
</section>
<section name="4.6 The Struts Configuration File" href="config">
@@ -435,7 +486,9 @@
Add an entry defining the action servlet itself, along with the
appropriate
initialization parameters. Such an entry might look like this:
</p>
-
+ <p>
+ [:TODO: Conform with MailReader example application]
+ </p>
<pre>
<servlet>
<servlet-name>action</servlet-name>
@@ -578,7 +631,7 @@
<pre>
<servlet-mapping>
<servlet-name>action</servlet-name>
- <url-pattern>/execute/*</url-pattern>
+ <url-pattern>/do/*</url-pattern>
</servlet-mapping>
</pre>
@@ -658,14 +711,14 @@
</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:
+ Below is how you would define all taglibs for use within your application.
+ In practice, you would only specify the taglibs that your application
uses:
</p>
<pre>
<taglib>
<taglib-uri>
- /WEB-INF/struts-bean.tld
+ /tags/struts-bean
</taglib-uri>
<taglib-location>
/WEB-INF/struts-bean.tld
@@ -673,7 +726,7 @@
</taglib>
<taglib>
<taglib-uri>
- /WEB-INF/struts-html.tld
+ /tags/struts-html
</taglib-uri>
<taglib-location>
/WEB-INF/struts-html.tld
@@ -681,7 +734,7 @@
</taglib>
<taglib>
<taglib-uri>
- /WEB-INF/struts-logic.tld
+ /tags/struts-logic
</taglib-uri>
<taglib-location>
/WEB-INF/struts-logic.tld
@@ -689,10 +742,10 @@
</taglib>
<taglib>
<taglib-uri>
- /WEB-INF/struts-template.tld
+ /tags/struts-tiles
</taglib-uri>
<taglib-location>
- /WEB-INF/struts-template.tld
+ /WEB-INF/struts-tiles.tld
</taglib-location>
</taglib>
</pre>
1.1 jakarta-struts/doc/userGuide/dev_util.xml
Index: dev_util.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1"?>
<document url="./resources.xml">
<properties>
<author>Ted Husted</author>
<title>The Struts User's Guide - Utilities Guide</title>
</properties>
<body>
<chapter name="Utilities Guide">
<section href="utils" name="The Utilities Package">
<p>
The Utilities package provides a variety of families of classes, to solve problems
that are commonly
encountered in building web applications.
</p>
</section>
<section href="resources" name="Utilities Resources">
<ul>
<li><a
href="../api/org/apache/struts/util/package-summary.html#package_description">Utilities
Package Description</a></li>
</ul>
</section>
</chapter></body></document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
