husted 2002/10/09 20:15:16
Modified: doc/userGuide building_model.xml building_controller.xml
Added: doc/userGuide building_apps.xml
Log:
Add "building applications" document per #11996 (Dan Walker)
Revision Changes Path
1.12 +4 -3 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.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- building_model.xml 9 Jul 2002 22:49:30 -0000 1.11
+++ building_model.xml 10 Oct 2002 03:15:16 -0000 1.12
@@ -222,7 +222,8 @@
</p>
<p>
The Struts datasource manager is configured as an element in the
- Struts configuration file (struts-config.xml). The manager can
+ <a href="building_controller.html#other_config">Struts configuration
file</a>
+ (struts-config.xml). The manager can
used to deploy any connection pool that implements the
<code>javax.sql.DataSource</code> interface and is configurable totally
from JavaBean properties. If your DBMS or container provides a
@@ -234,7 +235,7 @@
[org.apache.commons.dbcp.BasicDataSource] also works well with the
datasource manager, if a native component is not available. The Struts
distribution includes a Generic DataSource class in its util
- package, but this is now only a wraper around the BasicDataSource. The
+ package, but this is now only a wrapper around the BasicDataSource. The
GenericDataSource class is deprecated as of Struts 1.1 and replaced by
direct use of the BasicDataSource.
</p>
@@ -253,7 +254,7 @@
java.sql.Connection myConnection;
try {
- dataSource = servlet.findDataSource(null);
+ dataSource = getDataSource(request);
myConnection = dataSource.getConnection();
//do what you wish with myConnection
1.27 +156 -94 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.26
retrieving revision 1.27
diff -u -r1.26 -r1.27
--- building_controller.xml 18 Sep 2002 00:38:52 -0000 1.26
+++ building_controller.xml 10 Oct 2002 03:15:16 -0000 1.27
@@ -7,6 +7,9 @@
<author>Ted Husted</author>
<author>Martin Cooper</author>
<author>Ed Burns</author>
+ <author>Eddie Bush</author>
+ <author>Yann Cebron </author>
+ <author>David Graham</author>
<title>The Struts User's Guide - Building Controller Components</title>
</properties>
@@ -87,6 +90,7 @@
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">
<p>[:TODO:]</p>
@@ -96,8 +100,6 @@
<p>[:TODO:]</p>
</section>
- </section>
-
<section name="4.3 Action Classes" href="action_classes">
<p>The <code>Action</code> class defines two methods that could be
@@ -231,6 +233,7 @@
<section name="4.4 The ActionServlet" href="action_servlet">
<p>[:TODO:]</p>
+ </section>
<section name="4.4.1 Request Processor" href="request_processor">
<p>[:TODO:]</p>
@@ -255,7 +258,6 @@
PlugIn Configuration</a> for details.
</p>
</section>
- </section>
<section name="4.5 The ActionMapping Implementation" href="actionmapping">
@@ -340,7 +342,23 @@
</ul>
</blockquote>
<blockquote>
- [:TODO: ActionForwards]
+ <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.
+ You use a <forward> element for each forward definition, which has
the following important attributes:
+ <ul>
+ <li>
+ <b>name</b>: The logical name for this forward. This is used in your
ActionForm's execute
+ method to forward to the next appropriate resource. Example: homepage
+ </li>
+ <li>
+ <b>path</b>: The context relative path to the resource. Example:
/index.jsp or /index.do
+ </li>
+ <li>
+ <b>redirect</b>: True or false (default). Should the ActionServlet
redirect to the resource instead of forward?
+ </li>
+ </ul>
</blockquote>
<blockquote>
<b><action-mappings></b><br />
@@ -378,7 +396,8 @@
</blockquote>
</p>
-
+ </section>
+
<section name="4.6.1 ActionMapping Example" href="action_mapping_example">
<p>
@@ -466,89 +485,64 @@
</p>
</section>
- <section name="4.6.3 Message Resources Configuration" href="resources_config">
- <p>
- Very little is required in order to start taking advantage of the Struts
- sub-application feature. Just go through the following steps:
- </p>
- <ol>
- <li>Prepare a config file for each sub-application.</li>
- <li>Inform the controller of your sub-applications.</li>
- <li>Use actions to refer to your pages.</li>
- </ol>
- </section>
- <section name="4.6.3.1 Sub-Application Configuration Files"
href="module_config-files">
- <p>
- Back in Struts 1.0, a few "boot-strap" options were placed in the web.xml
file,
- and the bulk of the configuration was done in a single struts-config.xml
file.
- Obviously, this wasn't ideal for a team environment, since multiple users
had
- to share the same configuration file. Sub-applications to the rescue!
- </p>
- <p>
- With the advent of sub-applications, a given module (sub-application) has
it's
- own configuration file. This means each team (each module would
presumably be
- developed by a single team) has their own configuration file, and there
should
- be a lot less contention when trying to modify it.
- </p>
- </section>
- <section name="4.6.3.2 Informing the Controller"
href="module_config-inform_conroller">
- <p>
- In struts 1.0, you listed your configuration file as an initialization
parameter
- to the action servlet in web.xml. This is still done in 1.1, but it's
augmented
- a little. In order to tell the Struts machinery about your different
- sub-applications, you specify multiple config initialization parameters,
with a
- slight twist. You'll still use "config" to tell the action servlet about
your
- "default" sub-application, however, for each additional sub-application,
you will
- list an initialization parameter named "config/module", where module is
the name
- of your sub-application (this gets used when determining which URIs fall
under a
- given sub-application, so choose something meaningful!). For example:
- </p>
- <pre>
- ...
- <init-param>
- <param-name>config</param-name>
-
<param-value>/WEB-INF/conf/struts-default.xml</param-value>
- </init-param>
- <init-param>
- <param-name>config/module1</param-name>
-
<param-value>/WEB-INF/conf/struts-module1.xml</param-value>
- </init-param>
- ...
- </pre>
- <p>
- This says I have two sub-applications. One happens to be the "default"
sub-application,
- which has no "/module" in it's name, and one named "module1"
(config/module1). I've told
- the controller it can find their respective configurations under
/WEB-INF/conf (which is
- where I put all my configuration files). Pretty simple!
- </p>
- <p>
- (My struts-default.xml would be equivalent to what most folks call
struts-config.xml. I just
- like the symmety of having all my Struts module files being named
struts-<module>.xml)
- </p>
- </section>
- <section name="4.6.3.3 Using Actions for Pages"
href="module_config-use_actions">
- <p>
- Fronting your pages with actions is <i>essential</i> when using
sub-applications,
- since doing so is the only way you involve the controller in the request
-- and
- you want to! The controller puts the application configuration in the
request,
- which makes available all of your sub-application-specific configuration
data (including
- which plug-ins you are using, message resources, datasources, etc).
+ <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.
</p>
- </section>
-
- <section name="4.6.4 PlugIn Configuration" href="plugin_config">
- <p>
- Struts PlugIns are configured using the <plug-in> 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>PlugIn</code> interface.
- </p>
- <p>
- For PlugIns that require configuration themselves, the nested
- <set-property> element is available.
- </p>
- </section>
-
+ </section>
+
<section name="4.6.5 Other Configuration Objects" href="other_config">
<p>
@@ -612,10 +606,7 @@
</section>
- </section>
-
<section name="4.7 The Web Application Deployment Descriptor" href="dd_config">
-
<p>
The final step in setting up the application is to configure the application
deployment descriptor (stored in file <code>WEB-INF/web.xml</code>) to
include
@@ -623,6 +614,7 @@
for the example application as a guide, we see that the following entries
need
to be created or modified.
</p>
+ </section>
<section name="4.7.1 Configure the Action Servlet Instance"
href="dd_config_servlet">
@@ -902,13 +894,83 @@
</section>
<section name="4.7.4 Configuring your application for modules"
href="dd_config_modules">
+ <p>
+ Very little is required in order to start taking advantage of the Struts
+ application module feature. Just go through the following steps:
+ </p>
+ <ol>
+ <li>Prepare a config file for each module.</li>
+ <li>Inform the controller of your module.</li>
+ <li>Use actions to refer to your pages.</li>
+ </ol>
+ </section>
- <p>
- [:TODO:]
- </p>
+ <section name="4.7.4.1 Module Configuration Files" href="module_config-files">
+ <p>
+ Back in Struts 1.0, a few "boot-strap" options were placed in the web.xml
file,
+ and the bulk of the configuration was done in a single struts-config.xml
file.
+ Obviously, this wasn't ideal for a team environment, since multiple users
had
+ to share the same configuration file. Sub-applications to the rescue!
+ </p>
+ <p>
+ With the advent of modules, a given module has it's
+ own configuration file. This means each team (each module would
presumably be
+ developed by a single team) has their own configuration file, and there
should
+ be a lot less contention when trying to modify it.
+ </p>
</section>
- </section>
+ <section name="4.7.4.2 Informing the Controller"
href="module_config-inform_conroller">
+ <p>
+ In struts 1.0, you listed your configuration file as an initialization
parameter
+ to the action servlet in web.xml. This is still done in 1.1, but it's
augmented
+ a little. In order to tell the Struts machinery about your different
+ sub-applications, you specify multiple config initialization parameters,
with a
+ slight twist. You'll still use "config" to tell the action servlet about
your
+ "default" sub-application, however, for each additional sub-application,
you will
+ list an initialization parameter named "config/module", where module is
the name
+ of your sub-application (this gets used when determining which URIs fall
under a
+ given sub-application, so choose something meaningful!). For example:
+ </p>
+ <pre>
+ ...
+ <init-param>
+ <param-name>config</param-name>
+
<param-value>/WEB-INF/conf/struts-default.xml</param-value>
+ </init-param>
+ <init-param>
+ <param-name>config/module1</param-name>
+
<param-value>/WEB-INF/conf/struts-module1.xml</param-value>
+ </init-param>
+ ...
+ </pre>
+ <p>
+ This says I have two modules. One happens to be the "default" module,
+ which has no "/module" in it's name, and one named "module1"
(config/module1). I've told
+ the controller it can find their respective configurations under
/WEB-INF/conf (which is
+ where I put all my configuration files). Pretty simple!
+ </p>
+ <p>
+ (My struts-default.xml would be equivalent to what most folks call
struts-config.xml. I just
+ 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,
+ since doing so is the only way you involve the controller in the request
-- and
+ you want to! The controller puts the application configuration in the
request,
+ which makes available all of your sub-application-specific configuration
data (including
+ 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:
+ </p>
+ <pre>
+ <action path="/view" forward="/view.jsp"/>
+ </pre>
+ </section>
<section name="4.8 Add Struts Components To Your Application"
href="config_add">
1.1 jakarta-struts/doc/userGuide/building_apps.xml
Index: building_apps.xml
===================================================================
<?xml version="1.0"?>
<document url="./building_apps.xml">
<properties>
<author>Dan Walker</author>
<author>Ted Husted</author>
<title>Building Applications</title>
</properties>
<body>
<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
elsewhere and is referenced by "(more...)" links where possible.
</p>
</section>
<section href="caveats" name="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 material was written for Struts 1.1 (beta 2).</li>
</ol>
</section>
<section href="overview" name="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
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
<code>ActionServlet</code>, taglibs used by Struts.</li>
<li>Parallel Tasks</li>
<ol>
<li>Building</li>
<li>Unit Testing</li>
<li>Deployment</li>
</ol>
</ol>
</section>
<section href="details" name="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
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
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
displayed. <a href="preface.html#resources">(more...) </a></li>
</ol>
<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
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
not need to do this.</li>
</ol>
<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
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).
<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
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
actions. The file minimally needs:</li>
<ol>
<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
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
<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
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
that need to be copied, compiled, etc. </li>
</ol>
<li>Unit Testing</li>
<ol>
<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
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.
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>
<li>Deployment</li>
<ol>
<li>Build script should create a war file containing the files developed
above, along with files that make up the Struts framework. [:TODO: describe this
further, look for doc to link to]</li>
</ol>
</ol>
</ol>
</section>
</chapter>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
