husted 2002/10/09 20:42:45
Modified: doc/userGuide release-notes.xml project.xml installation.xml
index.xml building_controller.xml building_apps.xml
Log:
Add "building applications" document per #11996 (Dan Walker)
Revision Changes Path
1.13 +1 -1 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.12
retrieving revision 1.13
diff -u -r1.12 -r1.13
--- release-notes.xml 31 Aug 2002 13:15:02 -0000 1.12
+++ release-notes.xml 10 Oct 2002 03:42:44 -0000 1.13
@@ -11,7 +11,7 @@
<body>
- <chapter name="5.1 Release Notes" href="release_notoes">
+ <chapter name="6.1 Release Notes" href="release_notoes">
<section name="Beta Notes" href="beta">
<p>This section contains the release notes for
1.15 +5 -4 jakarta-struts/doc/userGuide/project.xml
Index: project.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/project.xml,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- project.xml 29 Jun 2002 23:58:38 -0000 1.14
+++ project.xml 10 Oct 2002 03:42:44 -0000 1.15
@@ -12,6 +12,7 @@
<item name="Model Components" href="building_model.html"/>
<item name="View Components" href="building_view.html"/>
<item name="Controller Components" href="building_controller.html"/>
+ <item name="Applications" href="building_apps.html"/>
</menu>
<menu name="Developer Guides">
@@ -34,18 +35,18 @@
</menu>
<menu name="Getting Started">
- <item name="Release Notes"
+ <item name="Release Notes"
href="release-notes.html"/>
- <item name="Installation"
+ <item name="Installation"
href="installation.html"/>
- <item name="Newbie FAQ"
+ <item name="Newbie FAQ"
href="../newbie.html"/>
</menu>
<menu name="Welcome">
<item name="Home" href="../index.html"/>
<item name="News & Status" href="../news.html"/>
- <item name="Kickstart FAQ" href="../kickstart.html"/>
+ <item name="Kickstart FAQ" href="../kickstart.html"/>
<item name="Resources" href="../resources/index.html"/>
<item name="Who We Are" href="../volunteers.html"/>
</menu>
1.8 +1 -1 jakarta-struts/doc/userGuide/installation.xml
Index: installation.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/installation.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- installation.xml 10 Sep 2002 19:06:28 -0000 1.7
+++ installation.xml 10 Oct 2002 03:42:44 -0000 1.8
@@ -20,7 +20,7 @@
</properties>
<body>
- <chapter name="5.2 Installation" href="installation">
+ <chapter name="6.2 Installation" href="installation">
<section name="Prerequisite Software" href="Prerequisites">
<p>The Struts binary distribution needs three other software packages installed to
1.16 +13 -3 jakarta-struts/doc/userGuide/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/index.xml,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- index.xml 14 Sep 2002 05:53:38 -0000 1.15
+++ index.xml 10 Oct 2002 03:42:44 -0000 1.16
@@ -26,6 +26,10 @@
<author>Robert Leland</author>
<author>Stanley Santiago</author>
<author>Wong Kok Kai</author>
+ <author>Dan Walker</author>
+ <author>Eddie Bush</author>
+ <author>Yann Cebron </author>
+ <author>David Graham</author>
<title>The Struts User's Guide - Table of Contents</title>
</properties>
@@ -126,9 +130,15 @@
<li><a href="building_controller.html#config_add">4.8 Add Struts
Components To Your Application</a></li>
<li><a href="building_controller.html#logging">4.9 Using The
Commons Logging Interface</a></li>
</ul></li>
- <li>5. Getting Started</li>
+ <li><a href="building_apps.html">5. Building Applications</a>
+ <ul>
+ <li><a href="building_apps.html#caveats">5.1 Caveats</a></li>
+ <li><a href="building_apps.html#overview">5.2 Overview</a></li>
+ <li><a href="building_apps.html#details">5.3 Details</a></li>
+ </ul></li>
+ <li>6. Getting Started</li>
<ul>
- <li><a href="release-notes.html">5.1 Release Notes</a></li>
+ <li><a href="release-notes.html">6.1 Release Notes</a></li>
<ul>
<li><a href="release-notes-1.1-b2.html">Release Notes
1.1-b2</a></li>
<li><a href="release-notes-1.1-b1.html">Release Notes
1.1-b1</a></li>
@@ -139,7 +149,7 @@
<li><a href="release-notes-1.0-b2.html">Release Notes
1.0-b2</a></li>
<li><a href="release-notes-1.0-b1.html">Release Notes
1.0-b1</a></li>
</ul>
- <li><a href="installation.html">5.2 Installation</a></li>
+ <li><a href="installation.html">6.2 Installation</a></li>
<ul>
<li><a href="installation-ip.html">iPlanet</a></li>
<li><a href="installation-ipas.html">Portal Application
Server</a></li>
1.28 +210 -210 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.27
retrieving revision 1.28
diff -u -r1.27 -r1.28
--- building_controller.xml 10 Oct 2002 03:15:16 -0000 1.27
+++ building_controller.xml 10 Oct 2002 03:42:44 -0000 1.28
@@ -12,12 +12,12 @@
<author>David Graham</author>
<title>The Struts User's Guide - Building Controller Components</title>
</properties>
-
- <body>
+
+ <body>
<chapter name="4. 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>
@@ -25,14 +25,14 @@
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>ActionForm</code> class to mediate between the Model
- and the View, as described in <a href="building_model.html">Building
+ <li>Write an <code>ActionForm</code> class to mediate between the Model
+ and the View, as described in <a href="building_model.html">Building
Model Components</a>.</li>
- <li>Write an <code>Action</code> class for each logical request that may
+ <li>Write an <code>Action</code> class for each logical request that may
be received (extend <code>org.apache.struts.action.Action</code>).</li>
- <li>Configure a ActionMapping (in XML) for each logical request that may
+ <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)
@@ -40,7 +40,7 @@
<li>Add the appropriate Struts components to your application.</li>
</ul>
</section>
-
+
<section name="4.2 ActionForm Classes" href="action_form_classes">
<p>[:TODO: introduction paragraph ]</p>
@@ -49,47 +49,47 @@
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>
+ 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
+ <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
+ <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
+ <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>
+ <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">
@@ -101,7 +101,7 @@
</section>
<section name="4.3 Action Classes" href="action_classes">
-
+
<p>The <code>Action</code> class defines two methods that could be
executed depending on your servlet environment:
</p>
@@ -119,14 +119,14 @@
HttpServletResponse response)
throws Exception;
</pre>
-
+
<p>
- Most projects 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 a request, via
- its <code>execute()</code> method, and return an <code>ActionForward</code>
object
- that identifies where control should be forwarded (e.g. a JSP) to provide
+ The goal of an <code>Action</code> class is to process a request, via
+ its <code>execute()</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>execute()</code> method:
@@ -136,7 +136,7 @@
that the user has successfully logged on). If the <code>Action</code>
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 an
+ 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 is not complete,
@@ -159,12 +159,12 @@
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,
@@ -190,7 +190,7 @@
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
@@ -203,11 +203,11 @@
</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.
+ 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
principle somewhat, because the business logic itself is embedded in the
@@ -217,20 +217,20 @@
</p>
<p>
- In Struts 1.0, Actions called a <code>perform</code> method instead of the
now
- preferred <code>execute</code> method. These methods use the same
parameters and
- differ only in which exceptions they throw. The elder <code>perform</code>
method
- throws <code>SerlvetException</code> and <code>IOException</code>. The new
<code>execute</code> method
- simply throws <code>Exception</code>. The change was to facilitate the
Declarative
+ In Struts 1.0, Actions called a <code>perform</code> method instead of the
now
+ preferred <code>execute</code> method. These methods use the same
parameters and
+ differ only in which exceptions they throw. The elder <code>perform</code>
method
+ throws <code>SerlvetException</code> and <code>IOException</code>. The new
<code>execute</code> method
+ simply throws <code>Exception</code>. The change was to facilitate the
Declarative
Exception handling feature introduced in Struts 1.1.
</p>
<p>
- The <code>perform</code> method may still be used in Struts 1.1 but is
deprecated.
- The Struts 1.1 method simply calls the new <code>execute</code> method and
wraps
- any <code>Exception</code> thrown as a <code>ServletException</code>.
+ The <code>perform</code> method may still be used in Struts 1.1 but is
deprecated.
+ The Struts 1.1 method simply calls the new <code>execute</code> method and
wraps
+ any <code>Exception</code> thrown as a <code>ServletException</code>.
</p>
</section>
-
+
<section name="4.4 The ActionServlet" href="action_servlet">
<p>[:TODO:]</p>
</section>
@@ -260,7 +260,7 @@
</section>
<section name="4.5 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
@@ -268,7 +268,7 @@
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>
@@ -283,50 +283,50 @@
<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
+ <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>
-
+
<section name="4.6 The Struts 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 uses
the
+ the appropriate setter methods. To make this process easier, Struts uses
the
Jakarta-Digester component to parse an XML-based description of
- the desired mappings and create the appropriate objects initialized to the
- appropriate default values.
- See the <a href="http://jakarta.apache.org/commons";>Jakarta Commons web
site</a>
+ the desired mappings and create the appropriate objects initialized to the
+ appropriate default values.
+ See the <a href="http://jakarta.apache.org/commons";>Jakarta Commons web
site</a>
for more information about the 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 described by the Document Type
Definition (DTD)
- maintained at
- <a
href="http://jakarta.apache.org/struts/dtds/struts-config_1_1.dtd";>http://jakarta.apache.org/struts/dtds/struts-config_1_1.dtd</a>.
- The User Guide touches on the most important elements and attributes
available to the
+ maintained at
+ <a
href="http://jakarta.apache.org/struts/dtds/struts-config_1_1.dtd";>http://jakarta.apache.org/struts/dtds/struts-config_1_1.dtd</a>.
+ The User Guide touches on the most important elements and attributes
available to the
Struts configuration file, but developers are referred to the DTD for more
detail.
</p>
<p>
The controller uses an internal copy of this document to parse the
configuration;
an Internet connection is not required for operation.
</p>
-
+
<p>
- The outermost XML element must be <code><struts-config></code>.
Inside of
- the <struts-config> element, there are three important elements that
are
+ The outermost XML element must be <code><struts-config></code>.
Inside of
+ the <struts-config> element, there are three important elements that
are
used to describe your actions:
-
+
<blockquote>
<b><form-beans></b><br />
- This section contains your form bean definitions. Form beans are
descriptors that
+ This section contains your form bean definitions. Form beans are
descriptors that
are used to create ActionForm instances at runtime. You use a
<form-bean> element
for each form bean, which has the following important attributes:
<ul>
@@ -344,8 +344,8 @@
<blockquote>
<b><global-forwards></b><br />
This section contains your global forward definitions. Forwards are
instances of the ActionForward
- class returned from an ActionForm's execute method. These map logical
names to specific resources (typically
- JSPs), allowing you to change the resource without changing references to
it throughout your application.
+ class returned from an ActionForm's execute method. These map logical
names to specific resources (typically
+ JSPs), allowing you to change the resource without changing references to
it throughout your application.
You use a <forward> element for each forward definition, which has
the following important attributes:
<ul>
<li>
@@ -363,9 +363,9 @@
<blockquote>
<b><action-mappings></b><br />
This section contains your action definitions. You use an
<action> element
- for each of the mappings you would like to define. Most action
elements will
+ for each of the mappings you would like to define. Most action
elements will
define at least the following attributes:
-
+
<ul>
<li>
<b>path</b>: The application context-relative path to the action
@@ -389,16 +389,16 @@
</li>
</ul>
- <p>For a complete description of the elements that can be used with the
action element, see the
- <a
href="http://jakarta.apache.org/struts/dtds/struts-config_1_1.dtd";>Struts
Configuration DTD</a> and the
+ <p>For a complete description of the elements that can be used with the
action element, see the
+ <a
href="http://jakarta.apache.org/struts/dtds/struts-config_1_1.dtd";>Struts
Configuration DTD</a> and the
<a
href="../api/org/apache/struts/action/ActionMapping.html">ActionMapping
documentation</a>.</p>
</blockquote>
-
+
</p>
</section>
-
- <section name="4.6.1 ActionMapping Example" href="action_mapping_example">
+
+ <section name="4.6.1 ActionMapping Example" href="action_mapping_example">
<p>
The <code>struts-config.xml</code> file from the example application
includes
@@ -413,24 +413,24 @@
<form-bean
name="logonForm"
type="org.apache.struts.example.LogonForm" />
- </form-beans>
+ </form-beans>
<global-forwards
type="org.apache.struts.action.ActionForward" />
<forward name="logon" path="/logon.jsp"
- redirect="false" />
- </global-forwards>
- <action-mappings>
+ redirect="false" />
+ </global-forwards>
+ <action-mappings>
<action
- path="/logon"
+ path="/logon"
type="org.apache.struts.example.LogonAction"
name="logonForm"
scope="request"
input="/logon.jsp"
unknown="false"
- validate="true" />
+ validate="true" />
</action-mappings>
</struts-config>
-</pre>
+</pre>
<p>
First the form bean is defined. A basic bean of class
"<code>org.apache.struts.example.LogonForm</code>"
@@ -452,9 +452,9 @@
and saving a bean of the specified class if needed.
</p>
<p>
- Optional but very useful are the local "<code>forward</code>" elements. In
the example
- application, many actions include a local "success" and/or "failure"
forward as
- part of an Action mapping.
+ Optional but very useful are the local "<code>forward</code>" elements. 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 -->
@@ -466,17 +466,17 @@
<forward name="failure" path="/mainMenu.jsp"/>
<forward name="success" path="/subscription.jsp"/>
</action>
-</pre>
+</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>
+ <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>
-
+
</section>
<section name="4.6.2 Controller Configuration" href="controller_config">
@@ -485,81 +485,81 @@
</p>
</section>
- <section name="4.6.3 Message Resources Configuration"
href="resources_config">
- <p>
- Struts has builtin support for internationalization (I18N).
- You can define one or more <code><message-resources></code> elements
- for your webapp; sub-applications can define their own resource bundles.
- Different bundles can be used simultaneously in your application, the
- 'key' attribute is used to specify the desired bundle.
- </p>
- <blockquote>
- <ul>
- <li>
- <b>className</b> - Classname of configuration bean.
- [org.apache.struts.config.MessageResourcesConfig] (optional)
- </li>
- <li>
- <b>factory</b> - Classname of MessageResourcesFactory.
- [org.apache.struts.util.PropertyMessageResourcesFactory] (optional)
- </li>
- <li>
- <b>key</b> - ServletContext attribute key to store this bundle.
- [org.apache.struts.action.MESSAGE] (optional)
- </li>
- <li>
- <b>null</b> - Set to <code>false</code> to display missing resource keys
- in your application like '<i>???keyname???</i>' instead of <code>null</code>.
- [true] (optional)
- </li>
- <li>
- <b>parameter</b> - Name of the resource bundle. (required)
- </li>
- </ul>
- </blockquote>
- <p>Example configuration:</p>
- <pre>
- <message-resources
- parameter="MyWebAppResources"
- null="false" />
- </pre>
- <p>
- This would set up a message resource bundle provided in the file
- <code>MyWebAppResources.properties</code> under the default key.
- Missing resource keys would be displayed as '<i>???keyname???</i>'.
- </p>
- </section>
-
- <section name="4.6.4 PlugIn Configuration" href="plugin_config">
- <p>
- Struts PlugIns are configured using the <code><plug-in></code> element
within
- the Struts configuration file. This element has only one valid attribute,
- 'className', which is the fully qualified name of the Java class which
- implements the <code>org.apache.struts.action.PlugIn</code> interface.
- </p>
- <p>
- For PlugIns that require configuration themselves, the nested
- <code><set-property></code> element is available.
+ <section name="4.6.3 Message Resources Configuration"
href="resources_config">
+ <p>
+ Struts has builtin support for internationalization (I18N).
+ You can define one or more <code><message-resources></code> elements
+ for your webapp; sub-applications can define their own resource bundles.
+ Different bundles can be used simultaneously in your application, the
+ 'key' attribute is used to specify the desired bundle.
+ </p>
+ <blockquote>
+ <ul>
+ <li>
+ <b>className</b> - Classname of configuration bean.
+ [org.apache.struts.config.MessageResourcesConfig] (optional)
+ </li>
+ <li>
+ <b>factory</b> - Classname of MessageResourcesFactory.
+ [org.apache.struts.util.PropertyMessageResourcesFactory] (optional)
+ </li>
+ <li>
+ <b>key</b> - ServletContext attribute key to store this bundle.
+ [org.apache.struts.action.MESSAGE] (optional)
+ </li>
+ <li>
+ <b>null</b> - Set to <code>false</code> to display missing resource keys
+ in your application like '<i>???keyname???</i>' instead of <code>null</code>.
+ [true] (optional)
+ </li>
+ <li>
+ <b>parameter</b> - Name of the resource bundle. (required)
+ </li>
+ </ul>
+ </blockquote>
+ <p>Example configuration:</p>
+ <pre>
+ <message-resources
+ parameter="MyWebAppResources"
+ null="false" />
+ </pre>
+ <p>
+ This would set up a message resource bundle provided in the file
+ <code>MyWebAppResources.properties</code> under the default key.
+ Missing resource keys would be displayed as '<i>???keyname???</i>'.
+ </p>
+ </section>
+
+ <section name="4.6.4 PlugIn Configuration" href="plugin_config">
+ <p>
+ Struts PlugIns are configured using the <code><plug-in></code> element
within
+ the Struts configuration file. This element has only one valid attribute,
+ 'className', which is the fully qualified name of the Java class which
+ implements the <code>org.apache.struts.action.PlugIn</code> interface.
</p>
- </section>
+ <p>
+ For PlugIns that require configuration themselves, the nested
+ <code><set-property></code> element is available.
+ </p>
+ </section>
<section name="4.6.5 Other Configuration Objects" href="other_config">
-
- <p>
- Besides the objects related to defining ActionMappings, the Struts
configuration may
+
+ <p>
+ Besides the objects related to defining ActionMappings, the Struts
configuration may
contain elements that create other useful objects.
- </p>
-
- <p>
- The <code><data-sources></code> section, which
+ </p>
+
+ <p>
+ The <code><data-sources></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>
-
- <pre>
+ </p>
+
+ <pre>
<struts-config>
<data-sources>
- <!-- configuration for GenericDataSource wrapper -->
+ <!-- configuration for GenericDataSource wrapper -->
<data-source>
<set-property property="autoCommit"
value="false"/>
@@ -578,30 +578,30 @@
<set-property property="user"
value="myusername"/>
</data-source>
-
+
<!-- configuration for commons BasicDataSource -->
<data-source type="org.apache.commons.dbcp.BasicDataSource">
- <set-property property="driverClassName"
- value="org.postgresql.Driver" />
- <set-property property="url"
- value="jdbc:postgresql://localhost/mydatabase"
/>
- <set-property property="maxActive"
- value="10" />
- <set-property property="maxWait"
- value="5000" />
- <set-property property="defaultAutoCommit"
- value="false" />
- <set-property property="defaultReadOnly"
- value="false" />
-
+ <set-property property="driverClassName"
+ value="org.postgresql.Driver" />
+ <set-property property="url"
+ value="jdbc:postgresql://localhost/mydatabase" />
+ <set-property property="maxActive"
+ value="10" />
+ <set-property property="maxWait"
+ value="5000" />
+ <set-property property="defaultAutoCommit"
+ value="false" />
+ <set-property property="defaultReadOnly"
+ value="false" />
+
</data-source>
</data-sources>
</struts-config>
</pre>
<p>
- For information on how to retrieve the data source, see the
- <a href="building_model.html#databases">Accessing Relational Databases</a>
section.
+ For information on how to retrieve the data source, see the
+ <a href="building_model.html#databases">Accessing Relational Databases</a>
section.
</p>
</section>
@@ -617,7 +617,7 @@
</section>
<section name="4.7.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:
@@ -656,19 +656,19 @@
<load-on-startup>2</load-on-startup>
</servlet>
</pre>
-
+
<p>
The initialization parameters supported by the controller servlet are
- described below. (You can also find these details in the <a
- href="../api/index.html">Javadocs</a> for the ActionServlet class.)
Square brackets
- describe the default values that are assumed if you do not provide a
value for
+ described below. (You can also find these details in the <a
+ href="../api/index.html">Javadocs</a> for the ActionServlet class.)
Square brackets
+ describe the default values that are assumed if you do not provide a
value for
that initialization parameter.
</p>
<p>
[:TODO: Conform with JavaDoc as to nominal and deprecated params]
</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
@@ -739,12 +739,12 @@
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>
+ format? [true]</li>
</ul>
</section>
-
+
<section name="4.7.2 Configure the Action Servlet Mapping"
href="dd_config_mapping">
-
+
<p>
<strong>Note:</strong> The material in this section is not specific to
Struts. The configuration of servlet mappings is defined in the Java
@@ -757,7 +757,7 @@
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
@@ -770,7 +770,7 @@
<url-pattern>/do/*</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:</p>
@@ -783,7 +783,7 @@
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
@@ -799,7 +799,7 @@
<url-pattern>*.do</url-pattern>
</servlet-mapping>
</pre>
-
+
<p>
and a request URI to match the <code>/logon</code> path described
earlier might look like this:
@@ -819,9 +819,9 @@
that <strong>only</strong> extension mapping is supported.</p>
</section>
-
+
<section name="4.7.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.
@@ -830,7 +830,7 @@
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,
+ Convenient mechanisms to create new beans based on the value of request
cookies, headers,
and parameters are also provided.
</p>
<p>
@@ -845,7 +845,7 @@
<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 practice, you would only specify the taglibs that your application
uses:
@@ -955,7 +955,7 @@
like the symmety of having all my Struts module files being named
struts-<module>.xml)
</p>
</section>
-
+
<section name="4.7.4.3 Using Actions for Pages"
href="module_config-use_actions">
<p>
Fronting your pages with actions is <i>essential</i> when using modules,
@@ -965,7 +965,7 @@
which plug-ins you are using, message resources, datasources, etc).
</p>
<p>
- The simplest way to do this is to use the <code>forward</code> property
of the ActionMapping:
+ The simplest way to do this is to use the <code>forward</code> property
of the ActionMapping:
</p>
<pre>
<action path="/view" forward="/view.jsp"/>
@@ -973,7 +973,7 @@
</section>
<section name="4.8 Add Struts Components To Your Application"
href="config_add">
-
+
<p>
To use Struts, you must copy the .tld files that you require into
your <code>WEB-INF</code> directory, and copy <code>struts.jar</code>
@@ -982,14 +982,14 @@
</p>
</section>
-
+
<section name="4.9 Commons Logging Interface" href="logging">
<p>
[:TODO:]
</p>
<p>
- Next: <a href="release-notes.html">Release Notes</a>
+ Next: <a href="building_apps.html">Building Applications</a>
</p>
</section>
1.2 +40 -37 jakarta-struts/doc/userGuide/building_apps.xml
Index: building_apps.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/building_apps.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- building_apps.xml 10 Oct 2002 03:15:16 -0000 1.1
+++ building_apps.xml 10 Oct 2002 03:42:45 -0000 1.2
@@ -9,36 +9,36 @@
<chapter name="5. Building Applications" href="building_apps">
<section href="intro" name="About This Document">
<p>
-This document outlines one possible sequence of development steps that can be
followed to create a
-Struts application. It is not intended as a complete description of each
-referenced development activity. More detailed documentation is available
+This document outlines one possible sequence of development steps that can be
followed to create a
+Struts application. It is not intended as a complete description of each
+referenced development activity. More detailed documentation is available
elsewhere and is referenced by "(more...)" links where possible.
</p>
</section>
-<section href="caveats" name="Caveats">
+<section href="caveats" name="5.1 Caveats">
<ol>
<li>Requirements development and design are outside of the scope of this
document.</li>
<li>For help installing Struts, see the <a href="installation.html">Getting
Started</a> chapter.</li>
<li>There are many other ways to approach Struts development and there are many
other features available besides the ones discussed below. This document
outlines only one way to get started.</li>
-<li>This document focuses on form/data centric applications, but may also work with
- other tyeps of appilications.</li>
+<li>This document focuses on form/data centric applications, but may also work with
+ other tyeps of appilications.</li>
<li>This material was written for Struts 1.1 (beta 2).</li>
</ol>
</section>
-<section href="overview" name="Overview">
+<section href="overview" name="5.2 Overview">
<ol>
<li>Implement data entry forms as JSP files.</li>
<li>Implement one or more <code>ActionForm</code> descendents to buffer data
between JSPs and Actions.</li>
-<li>Create an XML document that defines the validation rules for your
+<li>Create an XML document that defines the validation rules for your
application.</li>
<li>Implement one or more <code>Action</code> descendents to respond form
submissions.</li>
-<li>Create <code>struts-config.xml</code> to associate forms with
- actions.</li>
-<li>Create or update <code>web.xml</code> to reference
+<li>Create <code>struts-config.xml</code> to associate forms with
+ actions.</li>
+<li>Create or update <code>web.xml</code> to reference
<code>ActionServlet</code>, taglibs used by Struts.</li>
<li>Parallel Tasks</li>
<ol>
@@ -48,83 +48,83 @@
</ol>
</ol>
</section>
-<section href="details" name="Details">
+<section href="details" name="5.3 Details">
<ol>
<li>Implement data entry forms as JSP files.</li>
<ol>
-<li>Use elements from the <code>html</code> taglib to define the form
+<li>Use elements from the <code>html</code> taglib to define the form
elements. <a href="struts-html.html">(more...)</a></li>
-<li>Use <code>message</code> and other elements from the
- <code>bean</code> taglib to define the labels and other static text
+<li>Use <code>message</code> and other elements from the
+ <code>bean</code> taglib to define the labels and other static text
of the form. <a href="struts-bean.html">(more...)</a></li> <ol>
-<li>Create and maintain a properties file of the text elements to be
+<li>Create and maintain a properties file of the text elements to be
displayed. <a href="preface.html#resources">(more...) </a></li>
</ol>
-<li>Use <code>property</code> attributes to link form fields to
+<li>Use <code>property</code> attributes to link form fields to
<code>ActionForm</code> instance variables.</li>
</ol>
<li>Implement one or more <code>ActionForm</code> descendents to buffer data
between JSPs and Actions.</li>
<ol>
-<li>Create get/set pairs that correspond to the property names in your
+<li>Create get/set pairs that correspond to the property names in your
related JSP form. Example:
<pre><html:text property="city" /></pre>
needs:
<pre>getCity() and setCity(String c)</pre></li>
-<li>When needed, create a <code>reset</code> method that sets the fields of the
- <code>ActionForm</code> to their default values. Most ActionForms do
+<li>When needed, create a <code>reset</code> method that sets the fields of the
+ <code>ActionForm</code> to their default values. Most ActionForms do
not need to do this.</li>
</ol>
-<li>Create an XML document that defines the validation rules for your
+<li>Create an XML document that defines the validation rules for your
application.</li>
-<li>Implement one or more <code>Action</code> descendents to respond to form
+<li>Implement one or more <code>Action</code> descendents to respond to form
submissions.</li>
<ol>
-<li>Descend from DispatchAction or LookupDispatchAction if you want one class
- to handle more than one kind of event (example: one Action to handle
- 'insert', 'update' and 'delete' events, using a different "surrogate"
- execute method for each).
+<li>Descend from DispatchAction or LookupDispatchAction if you want one class
+ to handle more than one kind of event (example: one Action to handle
+ 'insert', 'update' and 'delete' events, using a different "surrogate"
+ execute method for each).
<a href="http://husted.com/struts/tips/002.html";>(more...)</a></li>
-<li>Use the <code>execute</code> method (or its surrogates) of your
- Action class to interface with objects in your application responsible
+<li>Use the <code>execute</code> method (or its surrogates) of your
+ Action class to interface with objects in your application responsible
for database interaction, such as EJBs, etc. [:TODO: find good doc to link
to]</li>
<li>Use the return value of the <code>execute</code> method (or its surrogates)
direct the user interface to the appropriate next page. [:TODO: find good doc
to link to]</li>
</ol>
-<li>Create <code>struts-config.xml</code> to associate forms with
+<li>Create <code>struts-config.xml</code> to associate forms with
actions. The file minimally needs:</li>
<ol>
-<li><code><form-beans></code> section to relate form-beans with ActionForms
+<li><code><form-beans></code> section to relate form-beans with ActionForms
<a href="building_controller.html#config">(more...)</a></li>
<li><code><action-mappings></code> section to relate <code><html:form>
</code> actions with Action classes <a
href="building_controller.html#action_classes">(more...)</a> </li>
-<li><code><message-resources></code> to make your ApplicationResources
+<li><code><message-resources></code> to make your ApplicationResources
available to the rest of the app</li>
<li><code><plug-in></code> section to link in the Struts validator and other
extensions<a href="building_controller.html#plugin_classes">
(more...)</a> </li>
-</ol> <li>Create or update <code>web.xml</code> to reference
+</ol> <li>Create or update <code>web.xml</code> to reference
<code>ActionServlet</code>, taglibs used by Struts. <a
href="building_controller.html#dd_config">
(more...)</a></li>
<li>Parallel Tasks</li>
<ol>
<li>Building</li>
<ol>
-<li>Use Ant. It can compile, create WAR file, perform XSLT
+<li>Use Ant. It can compile, create WAR file, perform XSLT
transformations, run unit tests, interact with version control
systems, clean up, etc. <a href="http://jakarta.apache.org/ant";>
(more...)</a></li>
-<li>Create and use build script incrementally, as you create files
+<li>Create and use build script incrementally, as you create files
that need to be copied, compiled, etc. </li>
</ol>
<li>Unit Testing</li>
<ol>
-<li>Unit test normal java beans with JUnit.
+<li>Unit test normal java beans with JUnit.
<a href="http://www.junit.org";> (more...)</a></li>
-<li>Unit test JSP, taglibs and conventional servlet components with
+<li>Unit test JSP, taglibs and conventional servlet components with
Cactus. <a href="http://jakarta.apache.org/cactus";> (more...)</a></li>
<li>Unit test Action servlets with StrutsTestCase.
<a href="http://strutstestcase.sourceforge.net";> (more...)</a></li>
-<li>Add all unit tests to the build script as a separate target.
+<li>Add all unit tests to the build script as a separate target.
This target should use the <code>junit</code> tag to launch each
TestCase descendent. <a
href="http://jakarta.apache.org/ant/manual/OptionalTasks/junit.html";>
(more...)</a></li>
</ol>
@@ -136,6 +136,9 @@
</ol>
</ol>
</ol>
+ <p>
+ Next: <a href="release-notes.html">Release Notes</a>
+ </p>
</section>
</chapter>
</body>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
