You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by hu...@apache.org on 2002/12/02 14:09:07 UTC
cvs commit: jakarta-struts/doc/userGuide configuration.xml installation.xml index.xml building_controller.xml
husted 2002/12/02 05:09:07
Modified: doc/userGuide installation.xml index.xml
building_controller.xml
Added: doc/userGuide configuration.xml
Log:
Proof-reading / formatting / spell-check / organizational pass on building_controller. No significant content changes.
First blush on new configuration chapter. No new content here, just extracts from building_controller. Needs work, but wanted to get this back up.
Updated index with organization changes. Will probably move configuration later, but wanted to post the story so far.
Revision Changes Path
1.15 +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.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- installation.xml 29 Oct 2002 11:09:34 -0000 1.14
+++ installation.xml 2 Dec 2002 13:09:07 -0000 1.15
@@ -418,7 +418,7 @@
<section>
<p>
- Next: <a href="../faqs/index.html">FAQs and Howtos</a>
+ Next: <a href="configuration.html">Configuring Applications</a>
</p>
</section>
1.20 +47 -28 jakarta-struts/doc/userGuide/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-struts/doc/userGuide/index.xml,v
retrieving revision 1.19
retrieving revision 1.20
diff -u -r1.19 -r1.20
--- index.xml 30 Nov 2002 22:25:16 -0000 1.19
+++ index.xml 2 Dec 2002 13:09:07 -0000 1.20
@@ -96,44 +96,36 @@
<li><a href="building_view.html#includes">3.4.3 Page Composition With Tiles</a></li>
<li><a href="building_view.html#image_rendering">3.4.4 Image Rendering Components</a></li>
<li><a href="building_view.html#text_rendering">3.4.5 Rendering Text</a></li>
- <li><a href="building_view.html#struts-el">3.4.6 The
-Struts-EL Tag Library</a></li>
+ <li><a href="building_view.html#struts-el">3.4.6 The Struts-EL Tag Library</a></li>
</ul></li>
</ul></li>
+
<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_form_classes">4.2 ActionForm Classes</a></li>
+ <li><a href="building_controller.html#action_servlet">4.2 The ActionServlet</a></li>
<ul>
- <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#request_controller">4.2.1 Request Processor</a></li>
</ul>
- <li><a href="building_controller.html#action_classes">4.3 Action Classes</a></li>
- <li><a href="building_controller.html#action_servlet">4.4 The ActionServlet</a></li>
+
+ <li><a href="building_controller.html#action_form_classes">4.3 ActionForm Classes</a></li>
<ul>
- <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#plugin_classes">4.4.3 Plugin Classes</a></li>
+ <li><a href="building_controller.html#dyna_action_form_classes">4.3.1 DynaActionForm Classes</a></li>
+ <li><a href="building_controller.html#map_action_form_classes">4.3.2 Map-backed ActionForm Classes</a></li>
</ul>
- <li><a href="building_controller.html#actionmapping">4.5 The ActionMapping Implementation</a></li>
- <li><a href="building_controller.html#config">4.6 The Struts Configuration File</a>
- <ul>
- <li><a href="building_controller.html#action_mapping_example">4.6.1 ActionMapping Example</a></li>
- <li><a href="building_controller.html#controller_config">4.6.2 Controller Configuration</a></li>
- <li><a href="building_controller.html#resources_config">4.6.3 Message Resources Configuration</a></li>
- <li><a href="building_controller.html#plugin_config">4.6.4 PlugIn Configuration</a></li>
- <li><a href="building_controller.html#other_config">4.6.5 Other Configuration Objects</a></li>
- </ul></li>
- <li><a href="building_controller.html#dd_config">4.7 The Web Application Deployment Descriptor</a>
- <ul>
- <li><a href="building_controller.html#dd_config_servlet">4.7.1 Configure the Action Servlet Instance</a></li>
- <li><a href="building_controller.html#dd_config_mapping">4.7.2 Configure the Action Servlet Mapping</a></li>
- <li><a href="building_controller.html#dd_config_taglib">4.7.3 Configure the Struts Tag Library</a></li>
- <li><a href="building_controller.html#dd_config_modules">4.7.4 Configuring your application for modules</a></li>
- </ul></li>
- <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>
+ <li><a href="building_controller.html#action_classes">4.4 Action Classes</a></li>
+ <li><a href="building_controller.html#exception_handler">4.5 Exception Handler</a></li>
+ <li><a href="building_controller.html#plugin_classes">4.6 Plugin Classes</a></li>
+ <li><a href="building_controller.html#actionmapping">4.7 The ActionMapping Implementation</a></li>
+ <li><a href="building_controller.html#config">4.8 Writing ActionMappings</a>\
+ <ul>
+ <li><a href="building_controller.html#action_mapping_example">4.8.1 ActionMapping Example</a></li>
+ </ul>
+ </li>
+ <li><a href="building_controller.html#module_config-use_actions">4.9 Using ActionMappings for Pages</a></li>
+ <li><a href="building_controller.html#logging">4.10 Using The Commons Logging Interface</a></li>
</ul></li>
+
<li><a href="building_apps.html">5. Building Applications</a>
<ul>
<li><a href="building_apps.html#caveats">5.1 Caveats</a></li>
@@ -168,6 +160,33 @@
<li><a href="installation-wls5.html">Weblogic 5.1 sp8</a></li>
</ul>
</ul>
+
+ <li>7. Configuring Applications</li>
+ <ul>
+ <li><a href="">7.1 </a></li>
+ <li>
+ <a href="configuration.html#config">7.2 The Struts Configuration File</a>
+ <ul>
+ <li><a href="configuration.html#plugin_config">7.2.1 Controller Configurationn</a></li>
+ <li><a href="configuration.html#resources_config">7.2.2 Message Resources Configuration</a></li>
+ <li><a href="configuration.html#PlugIn_config">7.2.3 PlugIn Configuration</a></li>
+ <li><a href="configuration.html#data-source_config">7.2.4 Data Source Configuration</a></li>
+ <li><a href="configuration.html#dd_config_modules">7.2.5 Configuring your application for modules</a></li>
+ <li><a href="configuration.html#module_config-switching">7.2.6 Switching Modules</a></li>
+ </ul>
+ </li>
+ <li>
+ <a href="configuration.html#dd_config">7.3 The Web Application Deployment Descriptor</a>
+ <ul>
+ <li><a href="configuration.html#dd_config_servlet">7.3.1 Configure the Action Servlet Instance</a></li>
+ <li><a href="configuration.html#dd_config_mapping">7.3.2 Configure the Action Servlet Mapping</a></li>
+ <li><a href="configuration.html#dd_config_taglib">7.3.3 Configure the Struts Tag Library</a></li>
+ <li><a href="configuration.html#dd_config_taglib">7.3.3.1 Configure the Struts Tag Library (Servlet 2.3)</a></li>
+ </ul>
+ </li>
+ <li><a href="configuration.html#config_add">7.4 Add Struts Components To Your Application</a></li>
+ </ul>
+
</ul>
</section>
1.49 +1318 -858 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.48
retrieving revision 1.49
diff -u -r1.48 -r1.49
--- building_controller.xml 1 Dec 2002 20:22:41 -0000 1.48
+++ building_controller.xml 2 Dec 2002 13:09:07 -0000 1.49
@@ -1,7 +1,12 @@
<?xml version="1.0"?>
<document url="./building_controller.xml">
- <properties>
+<!--
+// ======================================================================== 78
+-->
+
+<properties>
+ <title>The Struts User Guide - Building Controller Components</title>
<author>Craig R. McClanahan</author>
<author>Mike Schachter</author>
<author>Ted Husted</author>
@@ -11,200 +16,631 @@
<author>Eddie Bush</author>
<author>Yann Cebron</author>
<author>David Graham</author>
- <title>The Struts User's Guide - Building Controller Components</title>
- </properties>
+</properties>
+
+<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>
+ components.
+ Struts includes a servlet that implements the primary function 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
+ Model Components</a>.
+ </li>
+
+ <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
+ be submitted.
+ The XML configuration file is usually named
+ <code>struts-config.xml</code>.
+ </li>
+
+ </ul>
+
+ <p>
+ To deploy your application, you will also need to:
+ </p>
+
+ <ul>
+
+ <li>
+ Update the web application deployment descriptor file (in XML)
+ for your application to include the necessary Struts components.
+ </li>
+
+ <li>
+ Add the appropriate Struts components to your application.
+ </li>
+
+ </ul>
+
+ <p>
+ The latter two items are covered in the
+ "<a href="configuring.html">Configuring Applications</a>" chapter.
+ </p>
+
+</section>
+
+<section name="4.2 The ActionServlet" href="action_servlet">
+
+ <p>
+ For those of you familiar with MVC architecture, the ActionServlet
+ represents the C - the controller.
+ The job of the controller is to:
+ </p>
+
+ <ul>
+
+ <li>
+ process user requests,
+ </li>
+
+ <li>
+ determine what the user is trying to achieve according to the request,
+ </li>
+
+ <li>
+ pull data from the model (if necessary) to be given to the appropriate
+ view, and
+ </li>
+
+ <li>
+ select the proper view to respond to the user.
+ </li>
+
+ </ul>
+
+ <p>
+ The Struts controller delegates most of this grunt work to Action classes.
+ </p>
+
+ <p>
+ In addition to being the controller for your application, the
+ ActionServlet instance also is responsible for initialization and
+ clean-up of resources.
+ When the controller initializes, it first loads the application config
+ corresponding to the "config" init-param.
+ It then goes through an enumeration of all <code>init-param</code>
+ elements, looking for those elements who's name starts with
+ <code>config/</code>.
+ For each of these elements, Struts loads the configuration file specified
+ by the value of that <code>init-param</code>, and assigns a "prefix"
+ value to that module's ApplicationConfig instance consisting of the piece
+ of the <code>init-param</code> name following "config/".
+ For example, the module prefix specified by the
+ <code>init-param config/foo</code> would be "foo".
+ This is important to know, since this is how the controller determines
+ which module will be given control of processing the request.
+ To access the module foo, you would use a URL like:
+ </p>
+
+ <pre>http://localhost:8080/myApp/foo/someAction.do</pre>
+
+ <p>
+ For each request made of the controller, the method
+ <code>process(HttpServletRequest, HttpServletResponse)</code> will be
+ called.
+ This method simply determines which module should service the request and
+ then invokes that module's RequestProcessor's process method, passing the
+ same request and response.
+ </p>
+
+</section>
+
+<section name="4.2.1 Request Processor" href="request_processor">
+
+ <p>
+ The RequestProcessor is where the majority of the core processing
+ occurs for each request.
+ Let's take a look at the helper functions the process method invokes
+ in-turn:
+ </p>
+
+ <table border="1">
+
+ <tr>
+ <td>
+ </td>
+ <td>
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <code>processPath</code>
+ </td>
+ <td>
+ Determine the path that invoked us.
+ This will be used later to retrieve an ActionMapping.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <code>processLocale</code>
+ </td>
+ <td>
+ Select a locale for this request, if one hasn't already been
+ selected, and place it in the request.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <code>processContent</code>
+ </td>
+ <td>
+ Set the default content type (with optional character encoding) for
+ all responses if requested.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <code>processNoCache</code>
+ </td>
+ <td>
+ If appropriate, set the following response headers: "Pragma",
+ "Cache-Control", and "Expires".
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <code>processPreprocess</code>
+ </td>
+ <td>
+ This is one of the "hooks" the RequestProcessor makes available for
+ subclasses to override.
+ The default implementation simply returns <code>true</code>.
+ If you subclass RequestProcessor and override processPreprocess you
+ should either return <code>true</code> (indicating process should
+ continue processing the request) or <code>false</code> (indicating
+ you have handled the request and the process should return)
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <code>processMapping</code>
+ </td>
+ <td>
+ Determine the ActionMapping associated with this path.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <code>processRoles</code>
+ </td>
+ <td>
+ If the mapping has a role associated with it, ensure the requesting
+ user is has the specified role.
+ If they do not, raise an error and stop processing of the request.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <code>processActionForm</code>
+ </td>
+ <td>
+ Instantiate (if necessary) the ActionForm associated with this
+ mapping (if any) and place it into the appropriate scope.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <code>processPopulate</code>
+ </td>
+ <td>
+ Populate the ActionForm associated with this request, if any.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <code>processValidate</code>
+ </td>
+ <td>
+ Perform validation (if requested) on the ActionForm associated with
+ this request (if any).
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <code>processForward</code>
+ </td>
+ <td>
+ If this mapping represents a forward, forward to the path specified
+ by the mapping.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <code>processInclude</code>
+ </td>
+ <td>
+ If this mapping represents an include, include the result of
+ invoking the path in this request.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <code>processActionCreate</code>
+ </td>
+ <td>
+ Instantiate an instance of the class specified by the current
+ ActionMapping (if necessary).
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <code>processActionPerform</code>
+ </td>
+ <td>
+ This is the point at which your action's <code>perform</code> or
+ <code>execute</code> method will be called.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
+ <code>processActionForward</code>
+ </td>
+ <td>
+ Finally, the process method of the RequestProcessor takes the
+ ActionForward returned by your Action class, and uses to select the
+ next resource (if any).
+ Most often the ActionForward leads to the presentation page that
+ renders the response.
+ </td>
+ </tr>
+
+ </table>
+
+</section>
- <body>
- <chapter name="4. Building Controller Components" href="building_controller">
+<section name="4.3 ActionForm Classes" href="action_form_classes">
- <section name="4.1 Overview" href="overview">
+ <p>
+ An ActionForm represents an HTML form that the user interacts with over
+ one or more pages.
+ You will provide properties to hold the state of the form with getters
+ and setters to access them.
+ ActionForms can be stored in either the session (default) or request
+ scopes.
+ If they're in the session it's important to implement the form's
+ <code>reset</code> method to initialize the form before each use.
+ Struts sets the ActionForm's properties from the request parameters and
+ sends the validated form to the appropriate Action's <code>execute</code>
+ method.
+ </p>
- <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>
- components. Struts includes a servlet that implements the primary function
- 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
- Model Components</a>.</li>
- <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
- 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>
- <li>Add the appropriate Struts components to your application.</li>
- </ul>
- </section>
-
- <section name="4.2 ActionForm Classes" href="action_form_classes">
-
- <p>
- An ActionForm represents an HTML form that the user interacts with over one
- or more pages. You will provide properties to hold the state of the form with
- getters and setters to access them. ActionForms can be stored in either the session (default)
- or request scopes. If they're in the session it's important to implement the form's reset
- method to initialize the form before each use. Struts sets the ActionForm's properties from
- the request parameters and sends the validated form to the appropriate Action's execute method.
- </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 (see the javadoc for the
- <code>java.beans.Introspector</code> class for a start on information
- about this). 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">
-
- <p>Maintaining a separate concrete ActionForm class for each form in your struts application is time-consuming. This can be alleviated through the use of DynaActionForm classes. Instead of creating a new ActionForm subclass and new get/set methods for each of your bean's properties, you can list its properties, type, and defaults in the struts configuration file.</p>
- <p>For example, add the following to struts-config.xml for a UserForm bean that stores a user's given and family names:</p>
-<pre>
-<![CDATA[
+ <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 (see the Javadoc for the
+ <code>java.beans.Introspector</code> class for a start on information
+ about this).
+ 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 <code>validate</code> 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 ActionForm, and
+ then refer to the property "customer.name" in your presentation page.
+ 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 using nested syntax
+ with the Struts JSP tags.
+ </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 beans that can affect the business state 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.3.1 DynaActionForm Classes" href="dyna_action_form_classes">
+
+ <p>
+ Maintaining a separate concrete ActionForm class for each form in your
+ Struts application is time-consuming.
+ This can be alleviated through the use of DynaActionForm classes.
+ Instead of creating a new ActionForm subclass and new get/set methods for
+ each of your bean's properties, you can list its properties, type, and
+ defaults in the Struts configuration file.
+ </p>
+
+ <p>
+ For example, add the following to struts-config.xml for a UserForm bean
+ that stores a user's given and family names:
+ </p>
+
+<pre><code><![CDATA[
<form-bean
- name="UserForm"
- type="org.apache.struts.action.DynaActionForm">
- <form-property
- name="givenName"
- type="java.lang.String"
- initial="John"/>
- <form-property
- name="familyName"
- type="java.lang.String"
- initial="Smith"/>
+ name="UserForm"
+ type="org.apache.struts.action.DynaActionForm">
+ <form-property
+ name="givenName"
+ type="java.lang.String"
+ initial="John"/>
+ <form-property
+ name="familyName"
+ type="java.lang.String"
+ initial="Smith"/>
</form-bean>
-]]>
-</pre>
- <p>The list of types supported by DynaActionForm beans includes:</p>
- <ul>
- <li>java.lang.BigDecimal</li>
- <li>java.lang.BigInteger</li>
- <li>boolean and java.lang.Boolean</li>
- <li>byte and java.lang.Byte</li>
- <li>char and java.lang.Character</li>
- <li>java.lang.Class</li>
- <li>double and java.lang.Double</li>
- <li>float and java.lang.Float</li>
- <li>int and java.lang.Integer</li>
- <li>long and java.lang.Long</li>
- <li>short and java.lang.Short</li>
- <li>java.lang.String</li>
- <li>java.sql.Date</li>
- <li>java.sql.Time</li>
- <li>java.sql.Timestamp</li>
- </ul>
- <p>If you do not supply an initial attribute, numbers will be initialized
- to 0 and objects to null.</p>
- <p>In JSP pages using Struts custom tags, attributes of
- <code>DynaActionForm</code> objects can be referenced just like ordinary
- <code>ActionForm</code> objects. However, when utilizing the JavaServer
- Pages Standard Tag Library, only properties of ordinary
- <code>ActionForm</code> objects can be directly accessed through the JSTL
- expression language syntax. However, <code>DynaActionForm</code>
- properties can be accessed through a slightly different syntax.</p>
- <p>In particular, whereas the JSTL EL syntax for referencing a property
- of an <code>ActionForm</code> would be something like:</p>
- <pre>
- ${formbean.prop}</pre>
- <p>The syntax for referencing a property of a <code>DynaActionForm</code>
- would be:</p>
- <pre>
- ${dynabean.map.prop}</pre>
- <p>The <code>map</code> property is a property of
- <code>DynaActionForm</code> which represents the <code>HashMap</code>
- containing the <code>DynaActionForm</code> properties.</p>
-
- </section>
-
- <section name="4.2.2 Map-backed ActionForms" href="map_action_form_classes">
- <p>The DynaActionForm classes offer the ability to create ActionForm beans at initialization time, based on a list of properties enumerated in the struts configuration file. However, many HTML forms are generated dynamically at request time. Since the properties of these forms' ActionForm beans are not all known ahead of time, we need a new approach.</p>
- <p>Struts allows you to make one or more of your ActionForm's properties' values a Map instead of a traditional atomic object. You can then store the data from your form's dynamic fields in that Map. Here is an example of a map-backed ActionForm class:</p>
-<pre>
-<![CDATA[
-public FooForm extends ActionForm {
+]]></code></pre>
- private final Map values = new HashMap();
+ <p>
+ The types supported by DynaActionForm include:
+ </p>
+
+ <ul>
+
+ <li>
+ java.lang.BigDecimal
+ </li>
- public void setValue(String key, Object value) {
- values.put(key, value);
- }
+ <li>
+ java.lang.BigInteger
+ </li>
- public Object getValue(String key) {
- return values.get(key);
- }
+ <li>
+ boolean and java.lang.Boolean
+ </li>
+
+ <li>
+ byte and java.lang.Byte
+ </li>
+
+ <li>
+ char and java.lang.Character
+ </li>
+
+ <li>
+ java.lang.Class
+ </li>
+
+ <li>
+ double and java.lang.Double
+ </li>
+
+ <li>
+ float and java.lang.Float
+ </li>
+
+ <li>
+ int and java.lang.Integer
+ </li>
+
+ <li>
+ long and java.lang.Long
+ </li>
+
+ <li>
+ short and java.lang.Short
+ </li>
+
+ <li>
+ java.lang.String
+ </li>
+
+ <li>
+ java.sql.Date
+ </li>
+
+ <li>
+ java.sql.Time
+ </li>
+
+ <li>
+ java.sql.Timestamp
+ </li>
+
+ </ul>
+
+ <p>
+ If you do not supply an initial attribute, numbers will be initialized to
+ 0 and objects to <code>null</code>.
+ </p>
+
+ <p>
+ In JSP pages using Struts custom tags, attributes of
+ <code>DynaActionForm</code> objects can be referenced just like ordinary
+ <code>ActionForm</code> objects.
+ However, when utilizing the JavaServer Pages Standard Tag Library, only
+ properties of ordinary <code>ActionForm</code> objects can be directly
+ accessed through the JSTL expression language syntax.
+ However, <code>DynaActionForm</code> properties can be accessed through a
+ slightly different syntax.
+ In particular, whereas the JSTL EL syntax for referencing a property
+ of an <code>ActionForm</code> would be something like:
+ </p>
+
+<pre><code>${formbean.prop}</code></pre>
+
+ <p>
+ The syntax for referencing a property of a <code>DynaActionForm</code>
+ would be:
+ </p>
+
+<pre><code>${dynabean.map.prop}</code></pre>
+
+ <p>
+ The <code>map</code> property is a property of
+ <code>DynaActionForm</code> which represents the <code>HashMap</code>
+ containing the <code>DynaActionForm</code> properties.
+ </p>
+
+</section>
+
+<section name="4.3.2 Map-backed ActionForms" href="map_action_form_classes">
+
+ <p>
+ The DynaActionForm classes offer the ability to create ActionForm beans
+ at initialization time, based on a list of properties enumerated in the
+ Struts configuration file.
+ However, many HTML forms are generated dynamically at request time.
+ Since the properties of these forms' ActionForm beans are not all known
+ ahead of time, we need a new approach.
+ </p>
+
+ <p>
+ Struts allows you to make one or more of your ActionForm's properties'
+ values a Map instead of a traditional atomic object.
+ You can then store the data from your form's dynamic fields in that Map.
+ Here is an example of a map-backed ActionForm class:
+ </p>
+
+<pre><code><![CDATA[public FooForm extends ActionForm {
+
+private final Map values = new HashMap();
+
+public void setValue(String key, Object value) {
+values.put(key, value);
+}
+
+public Object getValue(String key) {
+return values.get(key);
+}
}
-]]>
-</pre>
- <p>In its corresponding JSP page, you can access objects stored in the values map using a special notation: <i>mapname(keyname)</i>. The parentheses in the bean property name indicate that the bean property named <i>mapname</i> is indexed using Strings (probably backed by a Map) and that struts should look for get/set methods that take a String key parameter to find the correct sub-property value. Struts will, of course, use the <i>keyname</i> value from the parentheses when it calls the get/set methods.</p>
- <p>Here is a simple example:</p>
-<pre>
-<![CDATA[
-<html:text property="value(foo)"/>
-]]>
-</pre>
- <p>This will call the getValue() method on FooForm with a key value of "foo" to find the property value. To create a form with dynamic field names, you could do the following:</p>
-<pre>
-<![CDATA[
-<% for (int i=0; i<10; i++) {
- String name = "value(foo-" + i + ")";
- <html:text property="<%=name%>"/><br/>
+]]></code></pre>
+
+ <p>
+ In its corresponding JSP page, you can access objects stored in the
+ values map using a special notation: <code>mapname(keyname)</code>.
+ The parentheses in the bean property name indicate that:
+ </p>
+
+ <ul>
+
+ <li>
+ the bean property named <code>mapname</code> is indexed using Strings
+ (probably backed by a Map), and that
+ </li>
+
+ <li>
+ Struts should look for get/set methods that take a String key
+ parameter to find the correct sub-property value.
+ Struts will, of course, use the <code>keyname</code> value from the
+ parentheses when it calls the get/set methods.
+ </li>
+
+ </ul>
+
+ <p>
+ Here is a simple example:
+ </p>
+
+<pre><code><![CDATA[<html:text property="value(foo)"/>]]></code></pre>
+
+ <p>
+ This will call the <code>getValue</code> method on FooForm with a key
+ value of "<code>foo</code>" to find the property value.
+ To create a form with dynamic field names, you could do the following:
+ </p>
+
+<pre><code><![CDATA[<% for (int i=0; i<10; i++) {
+String name = "value(foo-" + i + ")";
+<html:text property="<%=name%>"/><br/>
%>
-]]>
-</pre>
- <p>Note that there is nothing special about the name <i>value</i>. Your map-backed property could instead be named <i>property</i>, <i>thingy</i>, or any other bean property name you prefer. You can even have multiple map-backed properties on the same bean.</p>
- <p>In addition to map-backed properties, you can also create list-backed properties. You do so by creating indexed get/set methods on your bean:</p>
-<pre>
-<![CDATA[
-public FooForm extends ActionForm {
+]]></code></pre>
+
+ <p>
+ Note that there is nothing special about the name <code>value</code>.
+ Your map-backed property could instead be named <code>property</code>,
+ <code>thingy</code>, or any other bean property name you prefer.
+ You can even have multiple map-backed properties on the same bean.
+ </p>
+
+ <p>
+ In addition to map-backed properties, you can also create list-backed
+ properties.
+ You do so by creating indexed get/set methods on your bean:
+ </p>
+
+<pre><code><![CDATA[public FooForm extends ActionForm {
private final List values = new ArrayList();
@@ -216,690 +652,714 @@
return values.get(key);
}
}
-]]>
-</pre>
- <p>In your JSP pages, you access individual entries in a list-backed property by using a different special notation: <i>listname[index]</i>. The braces in the bean property name indicate that the bean property named <i>listname</i> is indexed (probably backed by a List), and that struts should look for get/set methods that take an index parameter in order to find the correct sub-property value.</p>
+]]></code></pre>
+
+ <p>
+ In your presentation pages, you access individual entries in a list-backed
+ property by using a different special notation:
+ <code>listname[index]</code>.
+ The braces in the bean property name indicate that the bean property named
+ <code>listname</code> is indexed (probably backed by a List), and that
+ Struts should look for get/set methods that take an index parameter in
+ order to find the correct sub-property value.
+ </p>
+
</section>
- <section name="4.3 Action Classes" href="action_classes">
+<section name="4.4 Action Classes" href="action_classes">
- <p>The <code>Action</code> class defines two methods that could be
- executed depending on your servlet environment:
- </p>
+ <p>
+ The <code>Action</code> class defines two methods that could be
+ executed depending on your servlet environment:
+ </p>
-<pre>
-public ActionForward execute(ActionMapping mapping,
- ActionForm form,
- ServletRequest request,
- ServletResponse response)
- throw Exception;
+<pre><code>public ActionForward execute(ActionMapping mapping,
+ ActionForm form,
+ ServletRequest request,
+ ServletResponse response)
+throw Exception;
public ActionForward execute(ActionMapping mapping,
- ActionForm form,
- HttpServletRequest request,
- HttpServletResponse response)
- throws Exception;
-</pre>
-
- <p>
- 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 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:
- </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 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
- 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,
- 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 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
- page of the user interface (typically request scope or session scope
- beans, depending on how long you need to keep these items available).</li>
- <li>Return an appropriate <code>ActionForward</code> object that identifies
- the JSP page to be used to generate this response, based on the newly
- updated beans. Typically, you will acquire a reference to such an
- object by calling <code>findForward()</code> on either the
- <code>ActionMapping</code> object you received (if you are using a
- 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,
- you need to code your <code>Action</code> class so that it operates
- correctly in a multi-threaded environment, just as you must code a
- servlet's <code>service()</code> method safely.</li>
- <li>The most important principle that aids in thread-safe coding is to
- use only local variables, not instance variables, in your
- <code>Action</code> class. Local variables are created on a
- stack that is assigned (by your JVM) to each request thread, so
- there is no need to worry about sharing them.</li>
- <li>The beans that represent the Model of your system may throw exceptions
- due to problems accessing databases or other resources.
- You should trap all such exceptions
- in the logic of your <code>execute()</code> method, and record them in the
- application's log (along with the corresponding stack trace) by
- calling:<br />
- <code>servlet.log("Error message text", exception);</code></li>
- <li>As a general rule, allocating scarce resources and keeping them across
- requests from the same user (in the user's session) can cause
- scalability problems. You should strive to release such resources
- (such as database connections) prior to forwarding control to the
- 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
- functional logic in the <code>Action</code> class itself, rather than
- coding it in separate business logic beans. Besides making the
- <code>Action</code> class itself hard to understand and maintain, this
- approach also makes it harder to re-use the business logic code, because
- 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
- principle somewhat, because the business logic itself is embedded in the
- <code>Action</code> classes. This should be considered something of a
- bug in the design of the sample application, rather than an intrinsic
- feature of the Struts architecture, or an approach to be emulated.
- </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
- 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>.
- </p>
- </section>
-
- <section name="4.4 The ActionServlet" href="action_servlet">
- <p>
- For those of you familiar with MVC architecture, the ActionServlet
- represents the C - the controller. The job of the controller is to
- process user requests, determine what the user is trying to achieve
- according to the request, pull data from the model (if necessary) to
- be given to the appropriate view, and then select the proper view
- to respond to the user. The Struts controller delegates most of this
- grunt work to Action classes.
- </p>
- <p>
- In addition to being the controller for your application, the
- ActionServlet instance also is responsible for initialization and
- clean-up of resources. When the controller initializes, it first
- loads the application con fig corresponding to the "config" init-param.
- It then goes through an enumeration of all <code>init-param</code>
- elements, looking for those elements who's name starts with
- <code>config/</code>. For each of these elements, Struts loads the
- configuration file specified by the value of that
- <code>init-param</code>, and assigns a "prefix" value
- to that module's ApplicationConfig instance consisting of the piece of
- the <code>init-param</code> name following "config/". For example, the
- module prefix specified by the <code>init-param config/foo</code> would
- be "foo". This is important to know, since this is how the
- controller determines which module will be given control of processing
- the request. To access the module foo, you would use a URL like:
- </p>
- <p>
- <pre>http://localhost:8080/myApp/foo/someAction.do</pre>
- </p>
- <p>
- For each request made of the controller, the method
- <code>process(HttpServletRequest, HttpServletResponse)</code> will be
- called. This method simply determines which module should service
- the request and then invokes that module's RequestProcessor's
- process method, passing the same request and response.
- </p>
- </section>
-
- <section name="4.4.1 Request Processor" href="request_processor">
- <p>
- The RequestProcessor is where the majority of the core
- processing occurs for each request. Let's take a look at the
- helper functions the process method invokes in-turn:
- </p>
- <ul>
- <li><code>processPath</code> Determine the path that invoked us. This
- will be used later to retrieve an ActionMapping.</li>
- <li><code>processLocale</code> Select a locale for this request, if one
- hasn't already been selected, and place it in the request.</li>
- <li><code>processContent</code> Set the default content type (with optional
- character encoding) for all responses if requested.</li>
- <li><code>processNoCache</code> If appropriate, set the following response
- headers: "Pragma", "Cache-Control", and "Expires".</li>
- <li><code>processPreprocess</code> This is one of the "hooks" the
- RequestProcessor makes available for subclasses to override. The
- default implementation simply returns true. If you subclass
- RequestProcessor and override processPreprocess you should either
- return true (indicating process should continue
- processing the request) or false (indicating you have handled the
- request and the process should return).</li>
- <li><code>processMapping</code> Determine the ActionMapping associated with
- this path.</li>
- <li><code>processRoles</code> If the mapping has a role associated with it,
- ensure the requesting user is has the specified role. If they do
- not, raise an error and stop processing of the request.</li>
- <li><code>processActionForm</code> Instantiate (if necessary) the
- ActionForm associated with this mapping (if any) and place it
- into the appropriate scope.</li>
- <li><code>processPopulate</code> Populate the ActionForm associated with
- this request, if any.</li>
- <li><code>processValidate</code> Perform validation (if requested) on the
- ActionForm associated with this request (if any).</li>
- <li><code>processForward</code> If this mapping represents a forward,
- forward to the path specified by the mapping.</li>
- <li><code>processInclude</code> If this mapping represents an include,
- include the result of invoking the path in this request.</li>
- <li><code>processActionCreate</code> Instantiate an instance of the class
- specified by the current ActionMapping (if necessary).</li>
- <li><code>processActionPerform</code> This is the point at which your
- action's perform or execute method will be called.</li>
- <li><code>processActionForward</code> Finally, the process method of the
- RequestProcessor takes the ActionForward returned by your
- Action class, and uses to select the next resource (if any).
- Most often the ActionForward leads to the presentation page that
- renders the response. </li>
- </ul>
- </section>
-
- <section name="4.4.2 Exception Handler" href="exception_handler">
- <p>
- You can define an ExceptionHandler to execute when an Action's execute
- method throws an Exception. First, you need to subclass
- org.apache.struts.action.ExceptionHandler and override the execute method.
- Your execute method should process the Exception and return an ActionForward
- object to tell Struts where to forward to next. Then you configure your
- handler in struts-config.xml like this:<br/>
- <pre><![CDATA[
- <global-exceptions>
- <exception
- key="some.key"
- type="java.io.IOException"
- handler="com.yourcorp.ExceptionHandler">
- </global-exceptions>
- ]]></pre>
- <br/>
- That configuration says that com.yourcorp.ExceptionHandler.execute() will be called
- when any IOException is thrown by an Action. The key is a key from your message resources
- properties file that can be used to display an error message.
- </p>
- <p>
- You can override global exception handlers by defining a handler inside an action definition.
- </p>
- <p>
- A common use of ExceptionHandlers is to configure one for java.lang.Exception so it's called
- for any exception and log the exception to some data store.
- </p>
- </section>
-
- <section name="4.4.3 PlugIn Classes" href="plugin_classes">
- <p>
- The <code>PlugIn</code> interface allows applications to easily hook
- into the <code>ActionServlet</code> lifecycle. This interface defines
- two methods, <code>init()</code> and <code>destroy()</code>, which
- are called at application startup and shutdown, respectively. A common
- use of a plugin is to configure or load application-specific data as
- the web application is starting up.
- </p>
- <p>
- At runtime, any resource setup by <code>init</code> would be accessed by Actions
- or business tier classes. The PlugIn interface allows you to setup
- resources, but does not provide any special way to access them. Most
- often, the resource would be stored in application context, under
- a known key, where other components can find it.</p>
- <p>
- PlugIns are configured using <plug-in> elements within the
- Struts configuration file. See <a href="#plugin_config">
- PlugIn Configuration</a> for details.
- </p>
- </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
- appropriate <code>Action</code> class. The required knowledge has been
- 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>
- <li><b>name</b> - The name of the form bean defined in the config file
- 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
- defined as a default within a single application.</li>
- <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>
-
- <section name="4.6 Writing Action Mappings" 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
- 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>
- 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>.
- This chapter covers the configuration elements that you will typically
- write as part of developing your application.
- There are several other elements that can be placed in the
- struts-config file to customize your application.
- See chapter 7 for more about the other elements in the Struts
- configuration file.
- </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
- used to describe your actions:
-
- <blockquote>
- <b><form-beans></b><br />
- 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>
- <li>
- <b>name</b>: A unique identifier for this bean, which will be used
- to reference it in corresponding action mappings. Usually, this
- is also the name of the request or session attribute under which
- this form bean will be stored.
- </li>
- <li>
- <b>type</b>: The fully-qualified Java classname of the ActionForm subclass to use with this form bean.
- </li>
- </ul>
- </blockquote>
- <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.
- 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 />
- 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
- define at least the following attributes:
-
- <ul>
- <li>
- <b>path</b>: The application context-relative path to the action
- </li>
- <li>
- <b>type</b>: The fully qualified java classname of your Action class
- </li>
- <li>
- <b>name</b>: The name of your <form-bean> element to use with this action
- </li>
- </ul>
-
- <p>Other often-used attributes include:</p>
-
- <ul>
- <li>
- <b>parameter</b>: A general-purpose attribute often used by "standard" Actions to pass a required property.
- </li>
- <li>
- <b>roles</b>: A comma-delimited list of the user security roles that can access this mapping.
- </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
- <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">
-
- <p>
- The <code>struts-config.xml</code> file from the example application includes
- the following mapping entry for the "log on" function, which we will use
- to illustrate the requirements. Note that the entries for all the other actions
- are left out:
- </p>
-
-<pre><![CDATA[
-<struts-config>
- <form-beans>
- <form-bean
- name="logonForm"
- type="org.apache.struts.example.LogonForm" />
- </form-beans>
- <global-forwards
- type="org.apache.struts.action.ActionForward" />
- <forward
- name="logon"
- path="/logon.jsp"
- redirect="false" />
- </global-forwards>
- <action-mappings>
- <action
- path="/logon"
- type="org.apache.struts.example.LogonAction"
- name="logonForm"
- scope="request"
- input="/logon.jsp"
- unknown="false"
- validate="true" />
- </action-mappings>
+ ActionForm form,
+ HttpServletRequest request,
+ HttpServletResponse response)
+throws Exception;
+</code></pre>
+
+ <p>
+ 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 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:
+ </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 can be forwarded to the presentation page that displays the
+ username and password prompts for 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, 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 <i>can</i> be done by logic code embedded within the
+ <code>Action</code> class itself, <b>but</b> 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
+ page of the user interface (typically request scope or session scope
+ beans, depending on how long you need to keep these items available).
+ </li>
+
+ <li>
+ Return an appropriate <code>ActionForward</code> object that
+ identifies the presentation page to be used to generate this response,
+ based on the newly updated beans.
+ Typically, you will acquire a reference to such an object by calling
+ <code>findForward</code> on either the <code>ActionMapping</code>
+ object you received (if you are using a 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>
+ The 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, you need to code your <code>Action</code> class so that it
+ operates correctly in a multi-threaded environment, just as you must
+ code a servlet's <code>service</code> method safely.
+ </li>
+
+ <li>
+ The most important principle that aids in thread-safe coding is to
+ use only local variables, not instance variables, in your
+ <code>Action</code> class.
+ Local variables are created on a stack that is assigned (by your JVM)
+ to each request thread, so there is no need to worry about sharing
+ them.
+ </li>
+
+ <li>
+ The beans that represent the Model of your system may throw exceptions
+ due to problems accessing databases or other resources.
+ You should trap all such exceptions in the logic of your
+ <code>execute</code> method, and record them in the application's log
+ (along with the corresponding stack trace) by calling:<br />
+ <code>servlet.log("Error message text", exception);</code>
+ </li>
+
+ <li>
+ As a general rule, allocating scarce resources and keeping them across
+ requests from the same user (in the user's session) can cause
+ scalability problems.
+ You should strive to release such resources (such as database
+ connections) prior to forwarding control to the 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 functional logic in
+ the <code>Action</code> class itself, rather than coding it in separate
+ business logic beans.
+ Besides making the <code>Action</code> class itself hard to understand and
+ maintain, this approach also makes it harder to re-use the business logic
+ code, because 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
+ principle somewhat, because the business logic itself is embedded in the
+ <code>Action</code> classes. This should be considered something of a
+ bug in the design of the sample application, rather than an intrinsic
+ feature of the Struts architecture, or an approach to be emulated.
+ </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 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>.
+ </p>
+
+</section>
+
+<section name="4.5 Exception Handler" href="exception_handler">
+
+ <p>
+ You can define an ExceptionHandler to execute when an Action's
+ <code>execute</code> method throws an Exception.
+ First, you need to subclass
+ <code>org.apache.struts.action.ExceptionHandler</code> and override the
+ <code>execute</code> method.
+ Your <code>execute</code> method should process the Exception and return
+ an ActionForward object to tell Struts where to forward to next.
+ Then you configure your handler in struts-config.xml like this:
+ </p>
+
+<pre><code><![CDATA[<global-exceptions>
+ <exception
+ key="some.key"
+ type="java.io.IOException"
+ handler="com.yourcorp.ExceptionHandler">
+</global-exceptions>
+]]></code></pre>
+
+ <p>
+ This configuration element says that
+ <code>com.yourcorp.ExceptionHandler.execute</code> will be called when
+ any IOException is thrown by an Action.
+ The <code>key</code> is a key into your message resources properties file
+ that can be used to retrieve an error message.
+ </p>
+
+ <p>
+ You can override global exception handlers by defining a handler inside an
+ action definition.
+ </p>
+
+ <p>
+ A common use of ExceptionHandlers is to configure one for
+ <code>java.lang.Exception</code> so it's called for any exception and log
+ the exception to some data store.
+ </p>
+
+</section>
+
+<section name="4.6 PlugIn Classes" href="plugin_classes">
+
+ <p>
+ The <i>PlugIn</i> interface extends Action and so that applications can
+ easily hook into the ActionServlet lifecycle.
+ This interface defines two methods, <code>init()</code> and
+ <code>destroy()</code>, which are called at application startup and
+ shutdown, respectively.
+ A common use of a Plugin Action is to configure or load
+ application-specific data as the web application is starting up.
+ </p>
+
+ <p>
+ At runtime, any resource setup by <code>init</code> would be accessed by
+ Actions or business tier classes.
+ The PlugIn interface allows you to setup resources, but does not provide
+ any special way to access them.
+ Most often, the resource would be stored in application context, under
+ a known key, where other components can find it.
+ </p>
+
+ <p>
+ PlugIns are configured using <plug-in> elements within the
+ Struts configuration file.
+ See <a href="configuration.html#plugin_config"> PlugIn Configuration</a>
+ for details.
+ </p>
+
+</section>
+
+<section name="4.7 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
+ appropriate <code>Action</code> class.
+ The required knowledge has been encapsulated in a Java class named
+ <i>ActionMapping</i>, the most important properties are as follows:
+ </p>
+
+ <ul>
+
+ <li>
+ <code>type</code> - Fully qualified Java class name of the Action
+ implementation class used by this mapping.
+ </li>
+
+ <li>
+ <code>name</code> - The name of the form bean defined in the config file
+ that this action will use.
+ </li>
+
+ <li>
+ <code>path</code> - The request URI path that is matched to select this
+ mapping.
+ See below for examples of how matching works.
+ </li>
+
+ <li>
+ <code>unknown</code> - 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 defined as a default within a single application.
+ </li>
+
+ <li>
+ <code>validate</code> - Set to <code>true</code> if the
+ <code>validate</code> method of the action associated with this mapping
+ should be called.
+ </li>
+
+ <li>
+ <code>forward</code> - The request URI path to which control is passed
+ when this mapping is invoked.
+ This is an alternative to declaring a <code>type</code> property.
+ </li>
+
+ </ul>
+
+</section>
+
+<section name="4.8 Writing Action Mappings" 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 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
+ website</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>.
+ This chapter covers the configuration elements that you will typically
+ write as part of developing your application.
+ There are several other elements that can be placed in the
+ struts-config file to customize your application.
+ See "<a href="configuration.html">Configuring Applications</a>" for more
+ about the other elements in the Struts configuration file.
+ </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 used to describe your actions:
+ </p>
+
+ <ul>
+
+ <li>
+ <code><form-beans></code>
+ </li>
+
+ <li>
+ <code><global-forwards></code>
+ </li>
+
+ <li>
+ <code><action-mappings></code>
+ </li>
+
+ </ul>
+
+ <p>
+ <code><b><form-beans></b></code><br />
+ 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:
+ </p>
+
+ <ul>
+
+ <li>
+ <code>name</code>: A unique identifier for this bean, which will be
+ used to reference it in corresponding action mappings.
+ Usually, this is also the name of the request or session attribute
+ under which this form bean will be stored.
+ </li>
+
+ <li>
+ <code>type</code>: The fully-qualified Java classname of the
+ ActionForm subclass to use with this form bean.
+ </li>
+
+ </ul>
+
+ <p>
+ <b><global-forwards></b><br />
+ This section contains your global forward definitions.
+ Forwards are instances of the ActionForward class returned from an
+ ActionForm's <code>execute</code> 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 <code><forward></code> element for each forward
+ definition, which has the following important attributes:
+ </p>
+
+ <ul>
+
+ <li>
+ <code>name</code>: The logical name for this forward.
+ This is used in your ActionForm's <code>execute</code> method to
+ forward to the next appropriate resource.
+ Example: homepage
+ </li>
+
+ <li>
+ <code>path</code>: The context relative path to the resource.
+ Example: /index.jsp or /index.do
+ </li>
+
+ <li>
+ <code>redirect</code>: <code>True</code> or <code>false</code>
+ (default).
+ Should the ActionServlet redirect to the resource instead of forward?
+ </li>
+
+ </ul>
+
+ <p>
+ <code><b><action-mappings></b></code><br />
+ This section contains your action definitions.
+ You use an <code><action></code> element for each of the mappings
+ you would like to define.
+ Most action elements will define at least the following attributes:
+ </p>
+
+ <ul>
+
+ <li>
+ <code>path</code>: The application context-relative path to the
+ action.
+ </li>
+
+ <li>
+ <code>type</code>: The fully qualified java classname of your
+ Action class.
+ </li>
+
+ <li>
+ <code>name</code>: The name of your
+ <code><form-bean></code> element to use with this action
+ </li>
+
+ </ul>
+
+ <p>Other often-used attributes include:</p>
+
+ <ul>
+
+ <li>
+ <code>parameter</code>: A general-purpose attribute often used by
+ "standard" Actions to pass a required property.
+ </li>
+
+ <li>
+ <code>roles</code>: A comma-delimited list of the user security roles
+ that can access this mapping.
+ </li>
+
+ </ul>
+
+ <p>
+ For a complete description of the elements that can be used with the
+ <code>action</code> 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>
+
+</section>
+
+<section name="4.8.1 ActionMapping Example" href="action_mapping_example">
+
+ <p>
+ The <code>struts-config.xml</code> file from the MailReader example
+ application includes the following mapping entry for the "log on"
+ function, which we will use to illustrate the requirements.
+ Note that the entries for all the other actions are left out:
+ </p>
+
+<pre><code><![CDATA[<struts-config>
+ <form-beans>
+ <form-bean
+ name="logonForm"
+ type="org.apache.struts.example.LogonForm" />
+ </form-beans>
+ <global-forwards
+ type="org.apache.struts.action.ActionForward" />
+ <forward
+ name="logon"
+ path="/logon.jsp"
+ redirect="false" />
+ </global-forwards>
+ <action-mappings>
+ <action
+ path="/logon"
+ type="org.apache.struts.example.LogonAction"
+ name="logonForm"
+ scope="request"
+ input="/logon.jsp"
+ unknown="false"
+ validate="true" />
+ </action-mappings>
</struts-config>
-]]></pre>
+]]></code></pre>
+
+ <p>
+ First the form bean is defined.
+ A basic bean of class "<code>org.apache.struts.example.LogonForm</code>"
+ is mapped to the logical name "<code>logonForm</code>".
+ This name is used as a session or request attribute name for the form
+ bean.
+ </p>
- <p>
- First the form bean is defined. A basic bean of class "<code>org.apache.struts.example.LogonForm</code>"
- is mapped to the logical name "<code>logonForm</code>". This name is used as a session or request attribute
- name for the form bean.
- </p>
- <p>
- The "<code>global-forwards</code>" section is used to create logical name mappings for commonly used
- jsp pages. Each of these forwards is available through a call to your action mapping instance,
- i.e. <code>mapping.findForward("logicalName")</code>.
- </p>
- <p>
- As you can see, this mapping matches the path <code>/logon</code> (actually,
- because the example application uses extension mapping, the request URI you
- specify in a JSP page would end in <code>/logon.do</code>). When a request
- that matches this path is received, an instance of the <code>LogonAction</code>
- class will be created (the first time only) and used. The controller servlet
- will look for a session scoped bean under key <code>logonForm</code>, creating
- and saving a bean of the specified class if needed.
- </p>
- <p>
- 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><![CDATA[
-<!-- Edit mail subscription -->
+ <p>
+ The "<code>global-forwards</code>" section is used to create logical name
+ mappings for commonly used presentation pages.
+ Each of these forwards is available through a call to your action mapping
+ instance, i.e. <code>mapping.findForward("logicalName")</code>.
+ </p>
+
+ <p>
+ As you can see, this mapping matches the path <code>/logon</code>
+ (actually, because the MailReader example application uses extension
+ mapping, the request URI you specify in a JSP page would end in
+ <code>/logon.do</code>).
+ When a request that matches this path is received, an instance of the
+ <i>LogonAction</i> class will be created (the first time only) and used.
+ The controller servlet will look for a session scoped bean under key
+ <code>logonForm</code>, creating and saving a bean of the specified class
+ if needed.
+ </p>
+
+ <p>
+ Optional but very useful are the local "<code>forward</code>" elements.
+ In the MailReader example application, many actions include a local
+ "success" and/or "failure" forward as part of an action mapping.
+ </p>
+
+<pre><code><![CDATA[<!-- Edit mail subscription -->
<action
- path="/editSubscription"
- type="org.apache.struts.example.EditSubscriptionAction"
- name="subscriptionForm"
- scope="request"
- validate="false">
- <forward name="failure" path="/mainMenu.jsp"/>
- <forward name="success" path="/subscription.jsp"/>
- </action>
-]]></pre>
-
- <p>Using just these two extra properties, the <code>Action</code> classes in the example
- application are almost totally independent of the actual names of the JSP pages
- that are used by the page designers. The pages can be renamed (for example) during
- a redesign, with negligible impact on the <code>Action</code> classes themselves.
- If the names of the "next" JSP pages were hard coded into the <code>Action</code>
- classes, all of these classes would also need to be modified. Of course, you can define
- whatever local forward properties makes sense for your own application.
- </p>
-
- <p>
- The Struts configuration file includes several other elements that you
- can use to customize your application.
- See chapter 7 for details.
- </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 module-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.7.4.4 Switching Modules" href="module_config-switching">
- <p>
- There are two basic methods to switching from one module to another.
- You can either use a forward (global or local) and specify the
- contextRelative attribute with a value of true, or you can use
- the built-in <code>org.apache.struts.actions.SwitchAction</code>.
- </p>
- <p>
- Here's an example of a global forward:
- </p>
- <p>
-<pre>
- ...
- <struts-config>
- ...
- <global-forwards>
- <forward name="toModuleB"
- contextRelative="true"
- path="/moduleB/index.do"
- redirect="true"/>
- ...
- </global-forwards>
- ...
- </struts-config>
- </pre>
- </p>
- <p>
- You could do the same thing with a local forward declared in an
- ActionMapping:
- </p>
- <p>
-<pre>
- ...
- <struts-config>
- ...
- <action-mappings>
- ...
- <action ... >
- <forward name="success"
- contextRelative="true"
- path="/moduleB/index.do"
- redirect="true"/>
- </action>
- ...
- </action-mappingss>
- ...
- </struts-config>
- </pre>
- </p>
- <p>
- Finally, you could use <code>org.apache.struts.actions.SwitchAction
- </code>, like so:
- </p>
- <p>
- <pre>
-...
-<action-mappings>
-<action path="/toModule"
- type="org.apache.struts.actions.SwitchAction"/>
-...
-</action-mappingss>
+ path="/editSubscription"
+ type="org.apache.struts.example.EditSubscriptionAction"
+ name="subscriptionForm"
+ scope="request"
+ validate="false">
+ <forward
+ name="failure"
+ path="/mainMenu.jsp"/>
+ <forward
+ name="success"
+ path="/subscription.jsp"/>
+</action>
+]]></code></pre>
+
+ <p>
+ Using just these two extra properties, the Action classes are almost
+ totally independent of the actual names of the presentation pages.
+ The pages can be renamed (for example) during a redesign, with negligible
+ impact on the Action classes themselves.
+ If the names of the "next" pages were hard coded into the Action classes,
+ all of these classes would also need to be modified.
+ Of course, you can define whatever local <code>forward</code> properties
+ makes sense for your own application.
+ </p>
+
+ <p>
+ The Struts configuration file includes several other elements that you
+ can use to customize your application.
+ See "<a href="configuration.html">Configuring Applications</a>" for details.
+ </p>
+
+</section>
+
+<section name="4.9 Using ActionMappings for Pages" href="module_config-use_actions">
+
+ <p>
+ Fronting your pages with ActionMappings is <i>essential</i> when using
+ application 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 module-specific configuration data
+ (including which message resources you are using, request-processor,
+ datasources, and so forth).
+ </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.10 Commons Logging Interface" href="logging">
+ <p>
+ Struts doesn't configure logging itself -- it's all done by
+ <a href="http://jakarta.apache.org/commons/">commons-logging</a>
+ under the covers.
+ The default algorithm is a search:
+ </p>
+
+ <ul>
+
+ <li>
+ If Log4J is there, use it.
+ </li>
+
+ <li>
+ If JDK 1.4 is there, use it.
+ </li>
+
+ <li>
+ Otherwise, use SimpleLog.
+ </li>
+
+ </ul>
+
+ <p>
+ The commons-logging interface is an <i>ultra-thin</i> bridge to many
+ different logging implementations.
+ The intent is to remove compile- and run-time dependencies on any
+ single logging implementation.
+ For more information about the currently-supported implementations,
+ please refer to the
+ <a href="http://jakarta.apache.org/commons/logging/api/index.html">
+ the description for the <code>org.apache.commons.logging</code>
+ package</a>.
+ </p>
+
+ <p>
+ Because Struts uses commons-logging and, therefore, includes the necessary
+ JAR files for <b>you</b> to use commons-logging, you've probably had the
+ occasional fleeting thought, <i>"Should I use
+ commons-logging?"</i>
+ The answer (surprise!) depends on the requirements for your particular
+ project.
+ If one of your requirements is the ability to easily change logging
+ implementations with zero impact on your application, then commons-logging
+ is a very good option.
+ </p>
+
+ <p>
+ <i>"Great! What do I do to get started using commons-logging in my own
+ code?"</i>
+ </p>
+
+ <p>
+ Using commons-logging in your own code is very simple - all you need are
+ two imports and a declaration for a logger.
+ Let's take a look:
+ </p>
+
+<pre><code>package com.foo;
+// ...
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
...
-</pre>
- </p>
- <p>
- Now, to change to ModuleB, we would use a URI like this:
- </p>
- <p>
- <code>http://localhost:8080/toModule.do?prefix=moduleB&page=index.do</code>
- </p>
- <p>
- That's all there is to it! Happy module-switching!
- </p>
- </section>
-
- <section name="4.8 Commons Logging Interface" href="logging">
- <p>
- Struts doesn't configure logging itself -- it's all done by
- commons-logging under the covers. The default algorithm is a search:
- </p>
- <ul>
- <li>
- If Log4J is there, use it.
- </li>
- <li>
- If JDK 1.4 is there, use it.
- </li>
- <li>
- Otherwise, use SimpleLog.
- </li>
- </ul>
- <p>
- The commons-logging interface is an <i>ultra-thin</i> bridge to
- many different logging implementations. The intent is to remove
- compile- and run-time dependencies on any single logging
- implementation. For more information about the currently-supported
- implementations, please refer to the
- <a href="http://jakarta.apache.org/commons/logging/api/index.html">
- the description for the org.apache.commons.logging package</a>.
- </p>
- <p>
- Because Struts uses commons-logging and, therefore, includes the
- necessary JAR files for <b>you</b> to use commons-logging, you've
- probably had the occassional fleeting thought, <i>"Should I use
- commons-logging?"</i> The answer (surprise!) depends on the
- requirements for your particular project. If one of your requirements
- is the ability to easily change logging implementations with zero
- impact on your application, then commons-logging is a very good option.
- </p>
- <p>
- <i>"Great! What do I do to get started using commons-logging in
- my own code?"</i>
- </p>
- <p>
- Using commons-logging in your own code is very simple - all you need
- are two imports and a declaration for a logger. Let's take a look:
- </p>
- <p>
-<pre>
- package com.foo;
- ...
- import org.apache.commons.logging.Log;
- import org.apache.commons.logging.LogFactory;
- ...
- public class Foo {
- ...
+public class Foo {
+ // ...
private static Log log = LogFactory.getLog(Foo.class);
- ...
- public void setBar(Bar bar)
- {
- if (log.isTraceEnabled())
- log.trace("Setting bar to " + bar);
-
- this.bar = bar;
- }
- ...
- }
-</pre>
- </p>
- <p>
- The general idea is to instantiate a single logger per class and to
- use a name for the logger which reflects where it's being used. The
- example is constructed with the class itself. This gives the
- logger the name of com.foo.Foo. Doing things this way lets you
- easily see where the output is coming from, so you can quickly
- pin-point problem areas. In additon, you are able to enable/disable
- logging in a very fine-grained way.
- </p>
- <p>
- For examples of using logging in Struts classes, see the
- Action classes in the Struts MailReader example application.
- </p>
-
- <p>
- Next: <a href="building_apps.html">Building Applications</a>
- </p>
- </section>
+ // ...
+ public void setBar(Bar bar) {
+ if (log.isTraceEnabled()) {
+ log.trace("Setting bar to " + bar);
+ }
+ this.bar = bar;
+ }
+// ...
+}
+</code></pre>
+
+ <p>
+ The general idea is to instantiate a single logger per class and to
+ use a name for the logger which reflects where it's being used. The
+ example is constructed with the class itself. This gives the
+ logger the name of com.foo.Foo. Doing things this way lets you
+ easily see where the output is coming from, so you can quickly
+ pin-point problem areas. In addition, you are able to enable/disable
+ logging in a very fine-grained way.
+ </p>
+
+ <p>
+ For examples of using logging in Struts classes, see the
+ Action classes in the Struts MailReader example application.
+ </p>
+
+</section>
+
+<section>
+ <p>
+ Next: <a href="building_apps.html">Building Applications</a>
+ </p>
+</section>
- </chapter>
- </body>
+</chapter>
+</body>
</document>
1.1 jakarta-struts/doc/userGuide/configuration.xml
Index: configuration.xml
===================================================================
<?xml version="1.0"?>
<document url="./configuration.xml">
<properties>
<title>The Struts User's Guide - Configuring Applications</title>
<author>Craig R. McClanahan</author>
<author>Mike Schachter</author>
<author>Ted Husted</author>
<author>Martin Cooper</author>
<author>Ed Burns</author>
<author>Donald Ball</author>
<author>Eddie Bush</author>
<author>Yann Cebron</author>
<author>David Graham</author>
</properties>
<body>
<chapter name="7. Configuring Applications" href="config_apps">
<section name="7.1">
<p>
[:TODO:]
</p>
</section>
<section name="7.2 The Struts configuration file" href="struts-config">
<p>
The <a href="building_controller.html#config">Building Controller
Components</a> chapter covered writing the form-bean and action-mapping
portions of the Stgruts configuration file.
These elements usually play an important role in the development of a
Struts application.
The other elements in Struts configuration file tend to be static:
you set them once and leave them alone.
</p>
<p>
These "static" configuration elements are :
</p>
<ul>
<li>[:TODO:]</li>
</ul>
</section>
<section name="7.2.1 Controller Configuration" href="controller_config">
<p>
The <controller> element allows you to configure the ActionServlet.
Many of the controller parameters were previously defined by servlet init. parameters in your web.xml file but have been moved to this section of struts-config.xml.
For full details on available parameters see the
<a href="http://jakarta.apache.org/struts/dtds/struts-config_1_1.dtd">struts-config_1_1.dtd</a>.
</p>
<p>
This example uses the default values for several controller parameters.
If you only want default behavior you can omit the controller section altogether.
</p>
<pre><![CDATA[
<controller
processorClass="org.apache.struts.action.RequestProcessor"
debug="0"
contentType="text/html"/>;
]]></pre>
</section>
<section name="7.2.2 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;
modules 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="7.2.3 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>
<p>
This is an example using the Tiles plugin:
</p>
<pre>
<plug-in className="org.apache.struts.tiles.TilesPlugin" >
<set-property
property="definitions-config"
value="/WEB-INF/tiles-defs.xml"/>
</plug-in>
</pre>
</section>
<section name="7.2.4 Data Source Configuration" href="data-source_config">
<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 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><![CDATA[
<struts-config>
<data-sources>
<!-- configuration for GenericDataSource wrapper -->
<data-source>
<set-property
property="autoCommit"
value="false"/>
<set-property
property="description"
value="Example Data Source Configuration"/>
<set-property
property="driverClass"
value="org.postgresql.Driver"/>
<set-property
property="maxCount"
value="4"/>
<set-property
property="minCount"
value="2"/>
<set-property
property="password"
value="mypassword"/>
<set-property
property="url"
value="jdbc:postgresql://localhost/mydatabase"/>
<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" />
</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.
</p>
<p>
<i>Note: Since Struts is now using commons-dbcp for all it's
data-source needs, the query you provide for the pingQuery
attribute must return at least one row.</i>
</p>
<p>
<b>Example:</b> <code>SELECT COUNT(*) FROM VALIDTABLE</code>
</p>
<p>
Just be sure you to replace "VALIDTABLE" with the name of a valid table in your database.
</p>
</section>
<section name="7.2.5 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>
<section name="7.2.5.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. Modules 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 name="7.2.5.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
modules, you specify multiple config initialization parameters, with a
slight twist. You'll still use "config" to tell the action servlet about your
"default" module, however, for each additional module, you will
list an initialization parameter named "config/module", where module is the name
of your module (this gets used when determining which URIs fall under a
given module, 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="7.2.6 Switching Modules" href="module_config-switching">
<p>
There are two basic methods to switching from one module to another.
You can either use a forward (global or local) and specify the
contextRelative attribute with a value of true, or you can use
the built-in <code>org.apache.struts.actions.SwitchAction</code>.
</p>
<p>
Here's an example of a global forward:
</p>
<p>
<pre>
...
<struts-config>
...
<global-forwards>
<forward name="toModuleB"
contextRelative="true"
path="/moduleB/index.do"
redirect="true"/>
...
</global-forwards>
...
</struts-config>
</pre>
</p>
<p>
You could do the same thing with a local forward declared in an
ActionMapping:
</p>
<p>
<pre>
...
<struts-config>
...
<action-mappings>
...
<action ... >
<forward name="success"
contextRelative="true"
path="/moduleB/index.do"
redirect="true"/>
</action>
...
</action-mappingss>
...
</struts-config>
</pre>
</p>
<p>
Finally, you could use <code>org.apache.struts.actions.SwitchAction
</code>, like so:
</p>
<p>
<pre>
...
<action-mappings>
<action path="/toModule"
type="org.apache.struts.actions.SwitchAction"/>
...
</action-mappingss>
...
</pre>
</p>
<p>
Now, to change to ModuleB, we would use a URI like this:
</p>
<p>
<code>http://localhost:8080/toModule.do?prefix=moduleB&page=index.do</code>
</p>
<p>
That's all there is to it! Happy module-switching!
</p>
</section>
<section name="7.3 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
all the Struts components that are required. Using the deployment descriptor
for the example application as a guide, we see that the following entries need
to be created or modified.
</p>
</section>
<section name="7.3.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:
</p>
<pre><![CDATA[
<servlet>
<servlet-name>action</servlet-name>
<servlet-class>
org.apache.struts.action.ActionServlet
</servlet-class>
<init-param>
<param-name>application</param-name>
<param-value>
org.apache.struts.example.ApplicationResources
</param-value>
</init-param>
<init-param>
<param-name>config</param-name>
<param-value>
/WEB-INF/struts-config.xml
</param-value>
</init-param>
<init-param>
<param-name>debug</param-name>
<param-value>2</param-value>
</init-param>
<init-param>
<param-name>mapping</param-name>
<param-value>
org.apache.struts.example.ApplicationMapping
</param-value>
</init-param>
<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
that initialization parameter.
</p>
<ul>
<li><strong>config</strong> - Context-relative path to the XML resource
containing the configuration information for the default module.
[/WEB-INF/struts-config.xml].</li>
<li><strong>config/${module}</strong> - Context-relative path to the XML resource
containing the configuration information for the application module that
will use the specified prefix (/${module}). This can be repeated as many
times as required for multiple application modules. (Since Struts 1.1)</li>
<li><strong>convertNull</strong> - Force simulation of the Struts 1.0 behavior
when populating forms. If set to true, the numeric Java wrapper class types
(like <code>java.lang.Integer</code>) will default to null (rather than 0).
(Since Struts 1.1) [false] </li>
<li><strong>debug</strong> - TThe debugging detail level that controls how much
information is logged for this servlet. Accepts values 0 (off) and from
1 (least serious) through 6 (most serious). [0]</li>
<li><strong>detail</strong> - The debugging detail level for the Digester
we utilize to process the application module configuration files. Accepts
values 0 (off) and 1 (least serious) through 6 (most serious). [0]</li>
<li><strong>rulesets</strong> - Comma-delimited list of fully qualified
classnames of additional <code>org.apache.commons.digester.RuleSet</code>
instances that should be added to the <code>Digester</code> that will
be processing <code>struts-config.xml</code> files. By default, only
the <code>RuleSet</code> for the standard configuration elements is
loaded. (Since Struts 1.1)</li>
<li><strong>validating</strong> - Should we use a validating XML parser to
process the configuration file (strongly recommended)? [true]</li>
</ul>
<p>The following parameters may still be used with the Struts 1.1 release but
are <b>deprecated</b>.</p>
<ul>
<li><strong>application</strong> - Java class name of the application
resources bundle base class. [NONE]
<em>DEPRECATED - Configure this using the "parameter" attribute
of the <message-resources> element.</em></li>
<li><strong>bufferSize</strong> - The size of the input buffer used when
processing file uploads. [4096]
<em>DEPRECATED - Configure this using the "bufferSize" attribute
of the <controller> element.</em></li>
<li><strong>content</strong> - Default content type and character encoding
to be set on each response; may be overridden by a forwarded-to
servlet or JSP page. [text/html]
<em>DEPRECATED - Configure this using the "contentType" attribute
of the <controller> element.</em></li>
<li><strong>factory</strong> - The Java class name of the
<code>MessageResourcesFactory</code> used to create the application
<code>MessageResources</code> object.
[org.apache.struts.util.PropertyMessageResourcesFactory]
<em>DEPRECATED - Configure this using the "factory" attribute
of the <message-resources> element.</em></li>
<li><strong>formBean</strong> - The Java class name of the ActionFormBean
implementation to use [org.apache.struts.action.ActionFormBean].
<em>DEPRECATED - Configure this using the "className" attribute
of each <form-bean> element.</em></li>
<li><strong>forward</strong> - The Java class name of the ActionForward
implementation to use [org.apache.struts.action.ActionForward].
Two convenient classes you may wish to use are:
<ul>
<li><em>org.apache.struts.action.ForwardingActionForward</em> -
Subclass of <code>org.apache.struts.action.ActionForward</code>
that defaults the <code>redirect</code> property to
<code>false</code> (same as the ActionForward default value).</li>
<li><em>org.apache.struts.action.RedirectingActionForward</em> -
Subclass of <code>org.apache.struts.action.ActionForward</code>
that defaults the <code>redirect</code> property to
<code>true</code>.</li>
</ul>
<em>DEPRECATED - Configure this using the "className" attribute of
each <forward> element.</em></li>
<li><strong>locale</strong> - If set to <code>true</code>, and there is a
user session, identify and store an appropriate
<code>java.util.Locale</code> object (under the standard key
identified by <code>Action.LOCALE_KEY</code>) in the user's session
if there is not a Locale object there already. [true]
<em>DEPRECATED - Configure this using the "locale" attribute of
the <controller> element.</em></li>
<li><strong>mapping</strong> - The Java class name of the ActionMapping
implementation to use [org.apache.struts.action.ActionMapping].
Two convenient classes you may wish to use are:
<ul>
<li><em>org.apache.struts.action.RequestActionMapping</em> - Subclass
of <code>org.apache.struts.action.ActionMapping</code> that
defaults the <code>scope</code> property to "request".</li>
<li><em>org.apache.struts.action.SessionActionMapping</em> - Subclass
of <code>org.apache.struts.action.ActionMapping</code> that
defaults the <code>scope</code> property to "session". (Same
as the ActionMapping default value).</li>
</ul>
<em>DEPRECATED - Configure this using the "className" attribute of
each <action> element, or globally for a module by using the
"type" attribute of the <action-mappings> element.</em></li>
<li><strong>maxFileSize</strong> - The maximum size (in bytes) of a file
to be accepted as a file upload. Can be expressed as a number followed
by a "K" "M", or "G", which are interpreted to mean kilobytes,
megabytes, or gigabytes, respectively. [250M]
<em>DEPRECATED - Configure this using the "maxFileSize" attribute of
the <controller> element.</em></li>
<li><strong>multipartClass</strong> - The fully qualified name of the
MultipartRequestHandler implementation class to be used for processing
file uploads. If set to <code>none</code>, disables Struts multipart
request handling. [org.apache.struts.upload.CommonsMultipartRequestHandler]
<em>DEPRECATED - Configure this using the "multipartClass" attribute of
the <controller> element.</em></li>
<li><strong>nocache</strong> - If set to <code>true</code>, add HTTP headers
to every response intended to defeat browser caching of any response we
generate or forward to. [false]
<em>DEPRECATED - Configure this using the "nocache" attribute of
the <controller> element.</em></li>
<li><strong>null</strong> - If set to <code>true</code>, set our application
resources to return <code>null</code> if an unknown message key is used.
Otherwise, an error message including the offending message key will
be returned. [true]
<em>DEPRECATED - Configure this using the "null" attribute of
the <message-resources> element.</em></li>
<li><strong>tempDir</strong> - The temporary working directory to use when
processing file uploads. [The working directory provided to this web
application as a servlet context attribute]
<em>DEPRECATED - Configure this using the "tempDir" attribute of
the <controller> element.</em></li>
</ul>
</section>
<section name="7.3.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
Servlet Specification. This section describes the most common means
of configuring a Struts application.
</p>
<p>
There are two common approaches to defining the URLs that will
be processed by the controller servlet -- prefix matching and extension
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
entry might look like this:
</p>
<pre>
<servlet-mapping>
<servlet-name>action</servlet-name>
<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>
<pre>
http://www.mycompany.com/myapplication/do/logon
</pre>
<p>
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
defined set of characters. For example, the JSP processing servlet is mapped
to the <code>*.jsp</code> pattern so that it is called to process every
JSP page that is requested. To use the <code>*.do</code> extension (which
implies "do something"), the mapping entry would look like this:
</p>
<pre>
<servlet-mapping>
<servlet-name>action</servlet-name>
<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:
</p>
<pre>
http://www.mycompany.com/myapplication/logon.do
</pre>
<p><font color="red"><strong>WARNING</strong></font> - Struts will not
operate correctly if you define more than one
<code><servlet-mapping></code> element for the controller
servlet.</p>
<p><font color="red"><strong>WARNING</strong></font> - If you are using
the new module support in Struts 1.1, you should be aware
that <strong>only</strong> extension mapping is supported.</p>
</section>
<section name="7.3.3 Configure the Struts Tag Library" href="dd_config_taglib">
<p>
Next, you must add an entry defining the Struts tag library. There are six taglibs
included with the Struts distribution.
</p>
<p>
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,
and parameters are also provided.
</p>
<p>
The struts-html taglib contains tags used to create struts input forms, as well as other
tags generally useful in the creation of HTML-based user interfaces.
</p>
<p>
The struts-logic taglib contains tags that are useful in managing conditional generation
of output text, looping over object collections for repetitive generation of output text,
and application flow management.
</p>
<p>
The struts-template taglib contains tags that define a template mechanism.
</p>
<p>
The struts-tiles taglib contains tags used for combining various view components,
called "tiles", into a final composite view. This is similar to struts-template in that
it's used for view composition, but tiles is a more full featured set of tags.
</p>
<p>
The struts-nested taglib is an extension of other struts taglibs that allows the use
of nested beans.
</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:
</p>
<pre>
<taglib>
<taglib-uri>
/tags/struts-bean
</taglib-uri>
<taglib-location>
/WEB-INF/struts-bean.tld
</taglib-location>
</taglib>
<taglib>
<taglib-uri>
/tags/struts-html
</taglib-uri>
<taglib-location>
/WEB-INF/struts-html.tld
</taglib-location>
</taglib>
<taglib>
<taglib-uri>
/tags/struts-logic
</taglib-uri>
<taglib-location>
/WEB-INF/struts-logic.tld
</taglib-location>
</taglib>
<taglib>
<taglib-uri>
/tags/struts-tiles
</taglib-uri>
<taglib-location>
/WEB-INF/struts-tiles.tld
</taglib-location>
</taglib>
</pre>
<p>
This tells the JSP system where to find the tag library descriptor
for this library (in your application's WEB-INF directory, instead of
out on the Internet somewhere).
</p>
</section>
<section name="7.3.3.1 Configure the Struts Tag Library (Servlet 2.3)" href="dd_config_taglib_23">
<p>
<b>Servlet 2.3 Users only:</b> The Servlet 2.3 specification simplifies the
deployment and configuration of tag libraries. The instructions above will work
on older containers as well as 2.3 containers (Struts only requires a servlet 2.2 container);
however, if you're using a 2.3 container such as Tomcat 4.x, you can take advantage of
a simplified deployment.
</p>
<p>
All that's required to install the struts tag libraries is to copy struts.jar into
your /WEB-INF/lib directory and reference the tags in your code like this:
<br/>
<code><%@ taglib uri="http://jakarta.apache.org/struts/tags-html-1.0" prefix="html" %></code>
<br/>
Note that you <b>must use the full uri</b> defined in the various struts tlds so that the container
knows where to find the tag's class files. You don't have to alter your web.xml file or
copy tlds into any application directories.
</p>
</section>
<section name="7.4 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>
(and all of the <code>commons-*.jar</code> files) into your
<code>WEB-INF/lib</code> directory.
</p>
<p>
<b>Servlet 2.3 Users:</b> See <a href="#dd_config_taglib_23">section 4.7.3.1</a>
for how to avoid copying the tlds into your application.
</p>
</section>
<section>
<p>
Next: <a href="../faqs/index.html">FAQs and Howtos</a>
</p>
</section>
</chapter>
</body>
</document>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>