husted 2002/12/01 12:22:41
Modified: doc/userGuide building_controller.xml
Log:
Move sections 4.6.2 through 4.7.4.2 and 4.8 to a new chapter ("Configuring
Applications") to be uploaded later.
Add references to new chapter, but no content changes.
Revision Changes Path
1.48 +12 -625 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.47
retrieving revision 1.48
diff -u -r1.47 -r1.48
--- building_controller.xml 30 Nov 2002 14:30:27 -0000 1.47
+++ building_controller.xml 1 Dec 2002 20:22:41 -0000 1.48
@@ -525,7 +525,7 @@
</section>
- <section name="4.6 The Struts Configuration File" href="config">
+ <section name="4.6 Writing Action Mappings" href="config">
<p>
How does the controller servlet learn about the mappings you want? It
@@ -545,8 +545,12 @@
application. This format of this document is described by the Document Type
Definition (DTD)
maintained at
<a
href="http://jakarta.apache.org/struts/dtds/struts-config_1_1.dtd";>http://jakarta.apache.org/struts/dtds/struts-config_1_1.dtd</a>.
- The User Guide touches on the most important elements and attributes
available to the
- Struts configuration file, but developers are referred to the DTD for more
detail.
+ 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;
@@ -713,614 +717,13 @@
classes, all of these classes would also need to be modified. Of course,
you can define
whatever local forward properties makes sense for your own application.
</p>
-
- </section>
-
- <section name="4.6.2 Controller Configuration" href="controller_config">
- <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
- struts-config_1_1.dtd.
- </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="4.6.3 Message Resources Configuration" href="resources_config">
-
- <p>
- Struts has builtin support for internationalization (I18N).
- You can define one or more <code><message-resources></code> elements
- for your webapp; 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="4.6.4 PlugIn Configuration" href="plugin_config">
-
- <p>
- Struts PlugIns are configured using the <code><plug-in></code> element
within
- the Struts configuration file. This element has only one valid attribute,
- 'className', which is the fully qualified name of the Java class which
- implements the <code>org.apache.struts.action.PlugIn</code> interface.
- </p>
-
- <p>
- For PlugIns that require configuration themselves, the nested
- <code><set-property></code> element is available.
- </p>
-
- <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="4.6.5 Other Configuration Objects" href="other_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:
+ The Struts configuration file includes several other elements that you
+ can use to customize your application.
+ See chapter 7 for details.
</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="4.7 The Web Application Deployment Descriptor" href="dd_config">
- <p>
- The final step in setting up the application is to configure the application
- deployment descriptor (stored in file <code>WEB-INF/web.xml</code>) to
include
- 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="4.7.1 Configure the Action Servlet Instance"
href="dd_config_servlet">
-
- <p>
- Add an entry defining the action servlet itself, along with the
appropriate
- initialization parameters. Such an entry might look like this:
- </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="4.7.2 Configure the Action Servlet Mapping"
href="dd_config_mapping">
-
- <p>
- <strong>Note:</strong> The material in this section is not specific to
- Struts. The configuration of servlet mappings is defined in the Java
- 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="4.7.3 Configure the Struts Tag Library"
href="dd_config_taglib">
- <p>
- Next, you must add an entry defining the Struts tag library. There are
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="4.7.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="4.7.4 Configuring your application for modules"
href="dd_config_modules">
- <p>
- Very little is required in order to start taking advantage of the Struts
- application module feature. Just go through the following steps:
- </p>
- <ol>
- <li>Prepare a config file for each module.</li>
- <li>Inform the controller of your module.</li>
- <li>Use actions to refer to your pages.</li>
- </ol>
- </section>
-
- <section name="4.7.4.1 Module Configuration Files" href="module_config-files">
- <p>
- Back in Struts 1.0, a few "boot-strap" options were placed in the web.xml
file,
- and the bulk of the configuration was done in a single struts-config.xml
file.
- Obviously, this wasn't ideal for a team environment, since multiple users
had
- to share the same configuration file. 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="4.7.4.2 Informing the Controller"
href="module_config-inform_conroller">
- <p>
- In struts 1.0, you listed your configuration file as an initialization
parameter
- to the action servlet in web.xml. This is still done in 1.1, but it's
augmented
- a little. In order to tell the Struts machinery about your different
- 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="4.7.4.3 Using Actions for Pages"
href="module_config-use_actions">
@@ -1414,23 +817,7 @@
</p>
</section>
- <section name="4.8 Add Struts Components To Your Application"
href="config_add">
-
- <p>
- To use Struts, you must copy the .tld files that you require into
- your <code>WEB-INF</code> directory, and copy <code>struts.jar</code>
- (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 name="4.9 Commons Logging Interface" href="logging">
+ <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:
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
