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 2006/01/21 01:21:00 UTC
svn commit: r370938 [32/50] - in /struts: action/trunk/
action/trunk/conf/java/ action/trunk/src/java/org/apache/struts/
action/trunk/src/java/org/apache/struts/action/
action/trunk/src/java/org/apache/struts/chain/
action/trunk/src/java/org/apache/str...
Modified: struts/action/trunk/xdocs/userGuide/configuration.xml
URL: http://svn.apache.org/viewcvs/struts/action/trunk/xdocs/userGuide/configuration.xml?rev=370938&r1=370937&r2=370938&view=diff
==============================================================================
--- struts/action/trunk/xdocs/userGuide/configuration.xml (original)
+++ struts/action/trunk/xdocs/userGuide/configuration.xml Fri Jan 20 16:19:02 2006
@@ -18,334 +18,447 @@
-->
<document>
-<properties>
- <title>Configuring Applications</title>
-</properties>
-
-<body>
-<section name="5. Configuring Applications">
-
-<a name="config-overview"/>
-<subsection name="5.1 Overview">
-
- <p>
- Before you can build an application, you need to lay a solid foundation.
- There are several setup tasks you need to perform before deploying
- your application.
- These include components in the configuration file
- and in the Web Application Deployment Descriptor.
- </p>
-
- </subsection>
-
- <a name="struts-config"/>
- <subsection name="5.2 The configuration file">
-
- <p>
- The <a href="building_controller.html#4_8_Writing_Action_Mappings">Writing Action
- Mappings</a> section covered writing the <code><form-bean></code> and
- <code><action-mapping></code> portions of the configuration file.
- These elements usually play an important role in the development of an
- application.
- The other elements in a configuration file tend to be static:
- you set them once and leave them alone.
- </p>
-
- <p>
- These "static" configuration elements are:
- </p>
-
- <ul>
-
- <li>
- <controller>
- </li>
-
- <li>
- <message-resources>
- </li>
-
- <li>
- <plug-in>
- </li>
-
- </ul>
-
- </subsection>
-
- <a name="controller_config"/>
- <subsection name="5.2.1 Controller Configuration">
-
- <p>
- The <code><controller></code> element allows you to configure
- the ActionServlet.
- Many of the controller parameters were previously defined by servlet
- initialization parameters in your <code>web.xml</code> file but have been
- moved to this section of <code>struts-config.xml</code> in order to allow
- different modules in the same web application to be configured differently.
- For full details on available parameters see the
- <a href="http://struts.apache.org/dtds/struts-config_1_3.dtd">
- struts-config_1_3.dtd</a> or the list below.
- </p>
-
-
-
- <ul>
-
- <li>
- <strong>bufferSize</strong> - The size (in bytes) of the input buffer
- used when processing file uploads.
- [4096] (optional)
- </li>
-
- <li>
- <strong>catalog</strong> - Name of the catalog to use when processing requests
- for this module.
- [struts]
- </li>
-
- <li>
- <strong>className</strong> - Classname of configuration bean.
- [org.apache.struts.config.ControllerConfig] (optional)
- </li>
-
- <li>
- <strong>command</strong> - Name of the command to execute to process a request.
- [servlet-standard]
- </li>
-
- <li>
- <strong>contentType</strong> - Default content type (and optional character
- encoding) to be set on each response.
- May be overridden by the Action, JSP, or other resource to which
- the request is forwarded.
- [text/html] (optional)
- </li>
-
- <li>
- <strong>forwardPattern</strong> - Replacement pattern defining how the "path"
- attribute of a <code><forward></code> element is mapped to a
- context-relative URL when it starts with a slash.
- This value may consist of any combination of the following:
-
- <ul>
-
- <li>
- <em>$M</em> - Replaced by the module prefix of this module.
- </li>
-
- <li>
- <em>$P</em> - Replaced by the "path" attribute of the selected
- <code><forward></code> element.
- </li>
-
- <li>
- <em>$$</em> - Causes a literal dollar sign to be rendered.
- </li>
-
- <li>
- <em>$x</em> - (Where "x" is any character not defined above)
- Silently swallowed, reserved for future use.
- </li>
-
- </ul>
-
- If not specified, the default forwardPattern is consistent with the
- previous behavior of forwards.
- [$M$P] (optional)
- </li>
-
- <li>
- <strong>inputForward</strong> - Set to <code>true</code> if you want the
- <code>input</code> attribute of <code><action></code> elements
- to be the name of a local or global <code>ActionForward</code>, which
- will then be used to calculate the ultimate URL.
- Set to <code>false</code> to treat the <code>input</code> parameter of
- <code><action></code> elements as a module-relative path to
- the resource to be used as the input form.
- [false] (optional)
- </li>
-
- <li>
- <strong>locale</strong> - Set to <code>true</code> if you want a
- <code>Locale</code> object stored in the user's session if not already
- present.
- [true] (optional)
- </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] (optional)
- </li>
-
- <li>
- <strong>memFileSize</strong> - The maximum size (in bytes) of a file whose contents will
- be retained in memory after uploading. Files larger than
- this threshold will be written to some alternative storage
- medium, typically a hard disk. Can be expressed as a number
- followed by a "K", "M", or "G", which are interpreted to
- mean kilobytes, megabytes, or gigabytes, respectively.
- ["256K"]
- </li>
-
- <li>
- <strong>multipartClass</strong> - The fully qualified Java class name of the
- multipart request handler class to be used with this module.
- [org.apache.struts.upload.CommonsMultipartRequestHandler] (optional)
- </li>
-
- <li>
- <strong>nocache</strong> - Set to <code>true</code> if you want the controller
- to add HTTP headers for defeating caching to every response from
- this module.
- [false] (optional)
- </li>
-
- <li>
- <strong>pagePattern</strong> - Replacement pattern defining how the
- <code>page</code> attribute of custom tags using it is mapped to a
- context-relative URL of the corresponding resource.
- This value may consist of any combination of the following:
-
- <ul>
-
- <li>
- <em>$M</em> - Replaced by the module prefix of this module.
- </li>
-
- <li>
- <em>$P</em> - Replaced by the "path" attribute of the selected
- <code><forward></code> element.
-
- </li>
- <li>
- <em>$$</em> - Causes a literal dollar sign to be rendered.
- </li>
-
- <li>
- <em>$x</em> - (Where "x" is any character not defined above)
- Silently swallowed, reserved for future use.
- </li>
-
- </ul>
-
- If not specified, the default pagePattern is consistent with the
- previous behavior of URL calculation.
- [$M$P] (optional)
- </li>
- <li>
-
- <strong>processorClass</strong> - The fully qualified Java class name of the
- <code>RequestProcessor</code> subclass to be used with this module.
- [org.apache.struts.chain.ComposableRequestProcessor] (optional)
- </li>
-
- <li>
- <strong>tempDir</strong> - Temporary working directory to use when processing
- file uploads.
- [{the directory provided by the servlet container}]
- </li>
-
- </ul>
-
- <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>
+ <properties>
+ <title>Configuring Applications</title>
+ </properties>
+
+ <body>
+ <section name="5. Configuring Applications">
+
+ <a name="config-overview"/>
+ <subsection name="5.1 Overview">
+
+ <p>
+ Before you can build an application, you need to lay a
+ solid foundation.
+ There are several setup tasks you need to perform before
+ deploying
+ your application.
+ These include components in the configuration file
+ and in the Web Application Deployment Descriptor.
+ </p>
+
+ </subsection>
+
+ <a name="struts-config"/>
+ <subsection name="5.2 The configuration file">
+
+ <p>
+ The
+ <a href="building_controller.html#4_8_Writing_Action_Mappings">
+ Writing Action
+ Mappings</a>
+ section covered writing the
+ <code><form-bean></code>
+ and
+ <code><action-mapping></code>
+ portions of the configuration file.
+ These elements usually play an important role in the
+ development of an
+ application.
+ The other elements in a configuration file tend to be
+ static:
+ you set them once and leave them alone.
+ </p>
+
+ <p>
+ These "static" configuration elements are:
+ </p>
+
+ <ul>
+
+ <li>
+ <controller>
+ </li>
+
+ <li>
+ <message-resources>
+ </li>
+
+ <li>
+ <plug-in>
+ </li>
+
+ </ul>
+
+ </subsection>
+
+ <a name="controller_config"/>
+ <subsection name="5.2.1 Controller Configuration">
+
+ <p>
+ The
+ <code><controller></code>
+ element allows you to configure
+ the ActionServlet.
+ Many of the controller parameters were previously defined
+ by servlet
+ initialization parameters in your
+ <code>web.xml</code>
+ file but have been
+ moved to this section of
+ <code>struts-config.xml</code>
+ in order to allow
+ different modules in the same web application to be
+ configured differently.
+ For full details on available parameters see the
+ <a href="http://struts.apache.org/dtds/struts-config_1_3.dtd">
+ struts-config_1_3.dtd</a>
+ or the list below.
+ </p>
+
+
+ <ul>
+
+ <li>
+ <strong>bufferSize</strong>
+ - The size (in bytes) of the input buffer
+ used when processing file uploads.
+ [4096] (optional)
+ </li>
+
+ <li>
+ <strong>catalog</strong>
+ - Name of the catalog to use when processing requests
+ for this module.
+ [struts]
+ </li>
+
+ <li>
+ <strong>className</strong>
+ - Classname of configuration bean.
+ [org.apache.struts.config.ControllerConfig] (optional)
+ </li>
+
+ <li>
+ <strong>command</strong>
+ - Name of the command to execute to process a request.
+ [servlet-standard]
+ </li>
+
+ <li>
+ <strong>contentType</strong>
+ - Default content type (and optional character
+ encoding) to be set on each response.
+ May be overridden by the Action, JSP, or other
+ resource to which
+ the request is forwarded.
+ [text/html] (optional)
+ </li>
+
+ <li>
+ <strong>forwardPattern</strong>
+ - Replacement pattern defining how the "path"
+ attribute of a
+ <code><forward></code>
+ element is mapped to a
+ context-relative URL when it starts with a slash.
+ This value may consist of any combination of the
+ following:
+
+ <ul>
+
+ <li>
+ <em>$M</em>
+ - Replaced by the module prefix of this
+ module.
+ </li>
+
+ <li>
+ <em>$P</em>
+ - Replaced by the "path" attribute of the
+ selected
+ <code><forward></code>
+ element.
+ </li>
+
+ <li>
+ <em>$$</em>
+ - Causes a literal dollar sign to be rendered.
+ </li>
+
+ <li>
+ <em>$x</em>
+ - (Where "x" is any character not defined
+ above)
+ Silently swallowed, reserved for future use.
+ </li>
+
+ </ul>
+
+ If not specified, the default forwardPattern is
+ consistent with the
+ previous behavior of forwards.
+ [$M$P] (optional)
+ </li>
+
+ <li>
+ <strong>inputForward</strong>
+ - Set to
+ <code>true</code>
+ if you want the
+ <code>input</code>
+ attribute of
+ <code><action></code>
+ elements
+ to be the name of a local or global
+ <code>ActionForward</code>
+ , which
+ will then be used to calculate the ultimate URL.
+ Set to
+ <code>false</code>
+ to treat the
+ <code>input</code>
+ parameter of
+ <code><action></code>
+ elements as a module-relative path to
+ the resource to be used as the input form.
+ [false] (optional)
+ </li>
+
+ <li>
+ <strong>locale</strong>
+ - Set to
+ <code>true</code>
+ if you want a
+ <code>Locale</code>
+ object stored in the user's session if not already
+ present.
+ [true] (optional)
+ </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] (optional)
+ </li>
+
+ <li>
+ <strong>memFileSize</strong>
+ - The maximum size (in bytes) of a file whose contents
+ will
+ be retained in memory after uploading. Files larger
+ than
+ this threshold will be written to some alternative
+ storage
+ medium, typically a hard disk. Can be expressed as a
+ number
+ followed by a "K", "M", or "G", which are interpreted
+ to
+ mean kilobytes, megabytes, or gigabytes, respectively.
+ ["256K"]
+ </li>
+
+ <li>
+ <strong>multipartClass</strong>
+ - The fully qualified Java class name of the
+ multipart request handler class to be used with this
+ module.
+ [org.apache.struts.upload.CommonsMultipartRequestHandler]
+ (optional)
+ </li>
+
+ <li>
+ <strong>nocache</strong>
+ - Set to
+ <code>true</code>
+ if you want the controller
+ to add HTTP headers for defeating caching to every
+ response from
+ this module.
+ [false] (optional)
+ </li>
+
+ <li>
+ <strong>pagePattern</strong>
+ - Replacement pattern defining how the
+ <code>page</code>
+ attribute of custom tags using it is mapped to a
+ context-relative URL of the corresponding resource.
+ This value may consist of any combination of the
+ following:
+
+ <ul>
+
+ <li>
+ <em>$M</em>
+ - Replaced by the module prefix of this
+ module.
+ </li>
+
+ <li>
+ <em>$P</em>
+ - Replaced by the "path" attribute of the
+ selected
+ <code><forward></code>
+ element.
+
+ </li>
+ <li>
+ <em>$$</em>
+ - Causes a literal dollar sign to be rendered.
+ </li>
+
+ <li>
+ <em>$x</em>
+ - (Where "x" is any character not defined
+ above)
+ Silently swallowed, reserved for future use.
+ </li>
+
+ </ul>
+
+ If not specified, the default pagePattern is
+ consistent with the
+ previous behavior of URL calculation.
+ [$M$P] (optional)
+ </li>
+ <li>
+
+ <strong>processorClass</strong>
+ - The fully qualified Java class name of the
+ <code>RequestProcessor</code>
+ subclass to be used with this module.
+ [org.apache.struts.chain.ComposableRequestProcessor]
+ (optional)
+ </li>
+
+ <li>
+ <strong>tempDir</strong>
+ - Temporary working directory to use when processing
+ file uploads.
+ [{the directory provided by the servlet container}]
+ </li>
+
+ </ul>
+
+ <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>
-<source><![CDATA[
+ <source><![CDATA[
<controller
processorClass="org.apache.struts.action.RequestProcessor"
contentType="text/html"/>;
]]></source>
-</subsection>
+ </subsection>
-<a name="resources_config"/>
-<subsection name="5.2.2 Message Resources Configuration">
+ <a name="resources_config"/>
+ <subsection name="5.2.2 Message Resources Configuration">
- <p>
- The framework has built in 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>
+ <p>
+ The framework has built in 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>
+
+ <ul>
+
+ <li>
+ <strong>className</strong>
+ - Classname of configuration bean.
+ [org.apache.struts.config.MessageResourcesConfig]
+ (optional)
+ </li>
+
+ <li>
+ <strong>factory</strong>
+ - Classname of MessageResourcesFactory.
+ [org.apache.struts.util.PropertyMessageResourcesFactory]
+ (optional)
+ </li>
+
+ <li>
+ <strong>key</strong>
+ - ServletContext attribute key to store this bundle.
+ [org.apache.struts.action.MESSAGE] (optional)
+ </li>
+
+ <li>
+ <strong>null</strong>
+ - Set to
+ <code>false</code>
+ to display missing resource
+ keys in your application like '
+ <em>???keyname???</em>
+ ' instead of
+ <code>null</code>
+ .
+ [true] (optional)
+ </li>
+
+ <li>
+ <strong>parameter</strong>
+ - Name of the resource bundle. (required)
+ </li>
- <ul>
+ </ul>
- <li>
- <strong>className</strong> - Classname of configuration bean.
- [org.apache.struts.config.MessageResourcesConfig] (optional)
- </li>
- <li>
- <strong>factory</strong> - Classname of MessageResourcesFactory.
- [org.apache.struts.util.PropertyMessageResourcesFactory] (optional)
- </li>
+ <p>Example configuration:</p>
- <li>
- <strong>key</strong> - ServletContext attribute key to store this bundle.
- [org.apache.struts.action.MESSAGE] (optional)
- </li>
-
- <li>
- <strong>null</strong> - Set to <code>false</code> to display missing resource
- keys in your application like '<em>???keyname???</em>' instead of
- <code>null</code>.
- [true] (optional)
- </li>
-
- <li>
- <strong>parameter</strong> - Name of the resource bundle. (required)
- </li>
-
- </ul>
-
-
-
- <p>Example configuration:</p>
-
-<source><![CDATA[
+ <source><![CDATA[
<message-resources
parameter="MyWebAppResources"
null="false" />
]]></source>
- <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 '<em>???keyname???</em>'.
- </p>
-
-</subsection>
-
-<a name="plugin_config"/>
-<subsection name="5.2.3 PlugIn Configuration">
-
- <p>
- Struts PlugIns are configured using the <code><plug-in></code>
- element within the 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>
+ <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 '
+ <em>???keyname???</em>
+ '.
+ </p>
+
+ </subsection>
+
+ <a name="plugin_config"/>
+ <subsection name="5.2.3 PlugIn Configuration">
+
+ <p>
+ Struts PlugIns are configured using the
+ <code><plug-in></code>
+ element within the 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>
-<source><![CDATA[
+ <source><![CDATA[
<plug-in className="org.apache.struts.tiles.TilesPlugin">
<set-property
property="definitions-config"
@@ -353,80 +466,104 @@
</plug-in>
]]></source>
-</subsection>
+ </subsection>
-<a name="dd_config_modules"/>
-<subsection name="5.3 Configuring Your Application for Modules">
+ <a name="dd_config_modules"/>
+ <subsection name="5.3 Configuring Your Application for Modules">
- <p>
- Very little is required in order to start taking advantage of the
- module feature.
- Just go through the following steps:
- </p>
-
- <ol>
-
- <li>
- Prepare a configuration file for each module.
- </li>
-
- <li>
- Inform the controller of your module.
- </li>
-
- <li>
- Use Actions to refer to your pages.
- </li>
-
- </ol>
-
-</subsection>
-
-<a name="module_config-files"/>
-<subsection name="5.3.1 Module Configuration Files">
-
- <p>
- Back in Struts 1.0, a few "boot-strap" options were placed in the <code>web.xml</code>
- file, and the bulk of the configuration was done in a single
- <code>struts-config.xml</code> file.
- Obviously, this wasn't ideal for a team environment, since multiple users
- had to share the same configuration file.
- </p>
-
- <p>
- Since Struts 1.1, you have two options: you can list
- <a href="#5_4_1_Configure_the_ActionServlet_Instance">multiple struts-config files</a> as a
- comma-delimited list, or you can subdivide a larger application into
- modules.
- </p>
-
- <p>
- With the advent of modules, a given module has its 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>
-
-</subsection>
-
-<a name="module_config-inform_controller"/>
-<subsection name="5.3.2 Informing the Controller">
-
- <p>
- Since Struts 1.0, you listed your configuration file as an initialization
- parameter to the action servlet in <code>web.xml</code>.
- This is still done since Struts 1.1, but the parameter can be extended.
- In order to tell the framework machinery about your different modules, you
- specify multiple 'config' initialization parameters, with a slight twist.
- You'll still use 'config' to tell the ActionServlet about your "default"
- module, however, for each additional module, you will
- list an initialization parameter named "config<em>/module</em>", where <em>/module</em> is
- the prefix for your module (this gets used when determining which URIs fall
- under a given module, so choose something meaningful!).
- For example:
- </p>
+ <p>
+ Very little is required in order to start taking advantage
+ of the
+ module feature.
+ Just go through the following steps:
+ </p>
+
+ <ol>
+
+ <li>
+ Prepare a configuration file for each module.
+ </li>
+
+ <li>
+ Inform the controller of your module.
+ </li>
+
+ <li>
+ Use Actions to refer to your pages.
+ </li>
+
+ </ol>
+
+ </subsection>
+
+ <a name="module_config-files"/>
+ <subsection name="5.3.1 Module Configuration Files">
+
+ <p>
+ Back in Struts 1.0, a few "boot-strap" options were placed
+ in the
+ <code>web.xml</code>
+ file, and the bulk of the configuration was done in a
+ single
+ <code>struts-config.xml</code>
+ file.
+ Obviously, this wasn't ideal for a team environment, since
+ multiple users
+ had to share the same configuration file.
+ </p>
+
+ <p>
+ Since Struts 1.1, you have two options: you can list
+ <a href="#5_4_1_Configure_the_ActionServlet_Instance">
+ multiple struts-config files</a>
+ as a
+ comma-delimited list, or you can subdivide a larger
+ application into
+ modules.
+ </p>
+
+ <p>
+ With the advent of modules, a given module has its 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>
+
+ </subsection>
+
+ <a name="module_config-inform_controller"/>
+ <subsection name="5.3.2 Informing the Controller">
+
+ <p>
+ Since Struts 1.0, you listed your configuration file as an
+ initialization
+ parameter to the action servlet in
+ <code>web.xml</code>
+ .
+ This is still done since Struts 1.1, but the parameter can
+ be extended.
+ In order to tell the framework machinery about your
+ different modules, you
+ specify multiple 'config' initialization parameters, with
+ a slight twist.
+ You'll still use 'config' to tell the ActionServlet about
+ your "default"
+ module, however, for each additional module, you will
+ list an initialization parameter named "config
+ <em>/module</em>
+ ", where
+ <em>/module</em>
+ is
+ the prefix for your module (this gets used when
+ determining which URIs fall
+ under a given module, so choose something meaningful!).
+ For example:
+ </p>
-<source><![CDATA[
+ <source><![CDATA[
...
<init-param>
<param-name>config</param-name>
@@ -439,47 +576,76 @@
...
]]></source>
- <p>
- Here we have two modules.
- One happens to be the "default" module, identified by the param-name of
- "config", and the other will be using the module prefix "/module1" based
- on the param-name it was given ("config/module1").
- The controller is configured to find the respective configuration files
- under <code>/WEB-INF/conf/</code> (which is the recommended place to put all configuration files).
- Pretty simple!
- </p>
-
- <p>
- (The <code>struts-default.xml</code> would be equivalent to what most folks call
- <code>struts-config.xml</code>.
- I just like the symmetry of having all my module configuration files being
- named <code>struts-<em>module</em>.xml</code>)
- </p>
-
- <p>
- If you'd like to vary where the pages for each module are stored,
- see the <a href="#5_2_1_Controller_Configuration">forwardPattern</a> setting for the
- Controller.
- </p>
-
-</subsection>
-
-
-<a name="module_config-switching"/>
-<subsection name="5.3.3 Switching Modules">
-
- <p>
- There are three approaches for switching from one module to another.
- You can use the built-in <code>org.apache.struts.actions.SwitchAction</code>,
- you can use a <code><forward></code> (global or local) and specify the contextRelative attribute with a value of true,
- or you can specify the "module" parameter as part of any of the Struts JSP hyperlink tags (Include, Img, Link, Rewrite, or Forward).
- </p>
-
- <p>
- You can use <code>org.apache.struts.actions.SwitchAction</code> like so:
- </p>
+ <p>
+ Here we have two modules.
+ One happens to be the "default" module, identified by the
+ param-name of
+ "config", and the other will be using the module prefix
+ "/module1" based
+ on the param-name it was given ("config/module1").
+ The controller is configured to find the respective
+ configuration files
+ under
+ <code>/WEB-INF/conf/</code>
+ (which is the recommended place to put all configuration
+ files).
+ Pretty simple!
+ </p>
+
+ <p>
+ (The
+ <code>struts-default.xml</code>
+ would be equivalent to what most folks call
+ <code>struts-config.xml</code>
+ .
+ I just like the symmetry of having all my module
+ configuration files being
+ named
+ <code>struts-
+ <em>module</em>
+ .xml
+ </code>
+ )
+ </p>
+
+ <p>
+ If you'd like to vary where the pages for each module are
+ stored,
+ see the
+ <a href="#5_2_1_Controller_Configuration">
+ forwardPattern</a>
+ setting for the
+ Controller.
+ </p>
+
+ </subsection>
+
+
+ <a name="module_config-switching"/>
+ <subsection name="5.3.3 Switching Modules">
+
+ <p>
+ There are three approaches for switching from one module
+ to another.
+ You can use the built-in
+ <code>org.apache.struts.actions.SwitchAction</code>
+ ,
+ you can use a
+ <code><forward></code>
+ (global or local) and specify the contextRelative
+ attribute with a value of true,
+ or you can specify the "module" parameter as part of any
+ of the Struts JSP hyperlink tags (Include, Img, Link,
+ Rewrite, or Forward).
+ </p>
+
+ <p>
+ You can use
+ <code>org.apache.struts.actions.SwitchAction</code>
+ like so:
+ </p>
-<source><![CDATA[
+ <source><![CDATA[
...
<action-mappings>
<action path="/toModule"
@@ -489,28 +655,30 @@
...
]]></source>
- <p>
- Now, to change to ModuleB, we would use a URI like this:
- </p>
-
- <source>
- http://localhost:8080/toModule.do?prefix=/moduleB&page=/index.do
- </source>
-
- <p>
- If you are using the "default" module as well as "named" modules (like "/moduleB"),
- you can switch back to the "default" module with a URI like this:
- </p>
-
- <source>
- http://localhost:8080/toModule.do?prefix=&page=/index.do
- </source>
-
- <p>
- Here's an example of a global forward:
- </p>
+ <p>
+ Now, to change to ModuleB, we would use a URI like this:
+ </p>
+
+ <source>
+ http://localhost:8080/toModule.do?prefix=/moduleB&page=/index.do
+ </source>
+
+ <p>
+ If you are using the "default" module as well as "named"
+ modules (like "/moduleB"),
+ you can switch back to the "default" module with a URI
+ like this:
+ </p>
+
+ <source>
+ http://localhost:8080/toModule.do?prefix=&page=/index.do
+ </source>
+
+ <p>
+ Here's an example of a global forward:
+ </p>
-<source><![CDATA[
+ <source><![CDATA[
<global-forwards>
<forward name="toModuleB"
contextRelative="true"
@@ -520,12 +688,13 @@
</global-forwards>
]]></source>
- <p>
- You could do the same thing with a local forward declared in an
- ActionMapping:
- </p>
+ <p>
+ You could do the same thing with a local forward declared
+ in an
+ ActionMapping:
+ </p>
-<source><![CDATA[
+ <source><![CDATA[
<action-mappings>
<action ... >
<forward name="success"
@@ -537,12 +706,13 @@
</action-mappings>
]]></source>
- <p>
- Or, you can use
- <code>org.apache.struts.actions.SwitchAction</code>:
- </p>
+ <p>
+ Or, you can use
+ <code>org.apache.struts.actions.SwitchAction</code>
+ :
+ </p>
- <source><![CDATA[
+ <source><![CDATA[
<action-mappings>
<action path="/toModule"
type="org.apache.struts.actions.SwitchAction"/>
@@ -550,52 +720,58 @@
</action-mappings>
]]></source>
- <p>
- Now, to change to ModuleB, we would use a URI like this:
- </p>
-
- <source>
- http://localhost:8080/toModule.do?prefix=/moduleB&page=/index.do
- </source>
-
- <p>
- Using the module parameter with a hyperlink tag is even simpler:
- </p>
+ <p>
+ Now, to change to ModuleB, we would use a URI like this:
+ </p>
+
+ <source>
+ http://localhost:8080/toModule.do?prefix=/moduleB&page=/index.do
+ </source>
+
+ <p>
+ Using the module parameter with a hyperlink tag is even
+ simpler:
+ </p>
- <source><![CDATA[
+ <source><![CDATA[
<html:link module="/moduleB" path="/index.do"/>
]]></source>
- <p>
- That's all there is to it! Happy module-switching!
- </p>
-
-</subsection>
-
-<a name="dd_config"/>
-<subsection name="5.4 The Web Application Deployment Descriptor">
-
- <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 framework or Taglib 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>
-
-</subsection>
-
-<a name="dd_config_servlet"/>
-<subsection name="5.4.1 Configure the ActionServlet Instance">
-
- <p>
- Add an entry defining the action servlet itself, along with the
- appropriate initialization parameters.
- Such an entry might look like this:
- </p>
+ <p>
+ That's all there is to it! Happy module-switching!
+ </p>
+
+ </subsection>
+
+ <a name="dd_config"/>
+ <subsection name="5.4 The Web Application Deployment Descriptor">
+
+ <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 framework or Taglib 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>
+
+ </subsection>
+
+ <a name="dd_config_servlet"/>
+ <subsection name="5.4.1 Configure the ActionServlet Instance">
+
+ <p>
+ Add an entry defining the action servlet itself, along
+ with the
+ appropriate initialization parameters.
+ Such an entry might look like this:
+ </p>
-<source><![CDATA[
+ <source><![CDATA[
<servlet>
<servlet-name>action</servlet-name>
<servlet-class>
@@ -611,408 +787,621 @@
</servlet>
]]></source>
- <p>
- The initialization parameters supported by the action servlet are
- described below.
- (You can also find these details in the
- <a href="../apidocs/org/apache/struts/action/ActionServlet.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>chainConfig</strong> - Comma-separated list of either
- context-relative or classloader path(s) to load commons-chain catalog
- definitions from. If none specified, the default catalog that is
- provided with the framework will be used. (Since version 1.3)
- </li>
-
- <li>
- <strong>config</strong> - Context-relative path to the XML resource
- containing the configuration information for the default module.
- This may also be a comma-delimited list of configuration files.
- Each file is loaded in turn, and its objects are appended to the
- internal data structure. [/WEB-INF/struts-config.xml].<br/>
- <strong>WARNING</strong> - If you define
- an object of the same name in more than one configuration file,
- the last one loaded quietly wins.
- </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>configFactory</strong> - The Java class name of the
- ModuleConfigFactory used to create the implementation of the
- ModuleConfig interface. (Since version 1.3)
- [org.apache.struts.config.impl.DefaultModuleConfigFactory]
- </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>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>
- <strong>WARNING</strong> - The framework will not
- operate correctly if you define more than one
- <code><servlet></code> element for a controller
- servlet, or a subclass of the standard controller servlet class.
- The controller servlet <strong>MUST</strong> be a web application
- wide singleton.
- </p>
-
-</subsection>
-
-<a name="dd_config_mapping"/>
-<subsection name="5.4.2 Configure the ActionServlet Mapping">
-
- <p>
- <strong>Note:</strong> The material in this section is not specific to
- Struts Action Framework.
- The configuration of servlet mappings is defined in the Java Servlet
- Specification.
- This section describes the most common means of configuring a
- 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>
+ <p>
+ The initialization parameters supported by the action
+ servlet are
+ described below.
+ (You can also find these details in the
+ <a href="../apidocs/org/apache/struts/action/ActionServlet.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>chainConfig</strong>
+ - Comma-separated list of either
+ context-relative or classloader path(s) to load
+ commons-chain catalog
+ definitions from. If none specified, the default
+ catalog that is
+ provided with the framework will be used. (Since
+ version 1.3)
+ </li>
+
+ <li>
+ <strong>config</strong>
+ - Context-relative path to the XML resource
+ containing the configuration information for the
+ default module.
+ This may also be a comma-delimited list of
+ configuration files.
+ Each file is loaded in turn, and its objects are
+ appended to the
+ internal data structure. [/WEB-INF/struts-config.xml].
+ <br/>
+ <strong>WARNING</strong>
+ - If you define
+ an object of the same name in more than one
+ configuration file,
+ the last one loaded quietly wins.
+ </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>configFactory</strong>
+ - The Java class name of the
+ ModuleConfigFactory used to create the implementation
+ of the
+ ModuleConfig interface. (Since version 1.3)
+ [org.apache.struts.config.impl.DefaultModuleConfigFactory]
+ </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>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>
+ <strong>WARNING</strong>
+ - The framework will not
+ operate correctly if you define more than one
+ <code><servlet></code>
+ element for a controller
+ servlet, or a subclass of the standard controller servlet
+ class.
+ The controller servlet
+ <strong>MUST</strong>
+ be a web application
+ wide singleton.
+ </p>
+
+ </subsection>
+
+ <a name="dd_config_mapping"/>
+ <subsection name="5.4.2 Configure the ActionServlet Mapping">
+
+ <p>
+ <strong>Note:</strong>
+ The material in this section is not specific to
+ Struts Action Framework.
+ The configuration of servlet mappings is defined in the
+ Java Servlet
+ Specification.
+ This section describes the most common means of
+ configuring a
+ 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>
-<source><![CDATA[
+ <source><![CDATA[
<servlet-mapping>
<servlet-name>action</servlet-name>
<url-pattern>/do/*</url-pattern>
</servlet-mapping>
]]></source>
- <p>
- which means that a request URI to match the <code>/logon</code> path
- described earlier might look like this:
- </p>
-
-<source>http://www.mycompany.com/myapplication/do/logon</source>
-
- <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>
+ <p>
+ which means that a request URI to match the
+ <code>/logon</code>
+ path
+ described earlier might look like this:
+ </p>
+
+ <source>
+ http://www.mycompany.com/myapplication/do/logon</source>
+
+ <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>
-<source><![CDATA[
+ <source><![CDATA[
<servlet-mapping>
<servlet-name>action</servlet-name>
<url-pattern>*.do</url-pattern>
</servlet-mapping>
]]></source>
- <p>
- and a request URI to match the <code>/logon</code> path described
- earlier might look like this:
- </p>
-
-<source>http://www.mycompany.com/myapplication/logon.do</source>
-
- <p>
- <strong>WARNING</strong> - The framework will not
- operate correctly if you define more than one
- <code><servlet-mapping></code> element for the controller
- servlet.
- </p>
-
- <p>
- <strong>WARNING</strong> - If you are using
- the new module support since Struts 1.1, you should be aware
- that <strong>only</strong> extension mapping is supported.
- </p>
-
-</subsection>
-
-<a name="dd_config_taglib_uri"/>
-<subsection name="5.4.3.1 Configure the Struts JSP Tag Libraries (Servlet 2.3/2.4)">
-
- <p>
- The Servlet 2.3 and 2.4 specifications simplify the deployment and configuration of tag libraries.
- All that's now required to install the Struts tag libraries is to copy
- <code>struts-taglib.jar</code> into your <code>/WEB-INF/lib</code> directory and reference the tags in
- your code like this:
- </p>
-
- <source>
- <%@ taglib
- uri="http://struts.apache.org/tags-html"
- prefix="html" %>
- </source>
-
- <p>
- Note that you <strong>must use the full uri</strong> defined in the various
- tlds (see the <a href="5_4_3_Configure_the_Struts_Tag_Libraries">
- example configuration</a> for reference)
- so that the container knows where to find the tag's class files.
- You don't have to alter your <code>web.xml</code> file or copy tlds into any
- application directories.
- </p>
-
- <p>
- Of course, the configuration techniques use for older containers do still work.
- </p>
-
-</subsection>
-
-<a name="config_add"/>
-<subsection name="5.5 Add Struts Components To Your Application">
-
- <p>
- To use the framework, you must copy <code>struts.jar</code>
- (and all of the <code>commons-*.jar</code> files) into your
- <code>WEB-INF/lib</code> directory. To use Struts Taglib,
- you must also copy the .tld files that you require into
- your <code>WEB-INF</code> directory and the struts-taglib.jar.
- </p>
-
- <p>
- <strong>Servlet 2.3/2.4 Users:</strong> See
- <a href="5_4_3_Configure_the_Struts_Tag_Libraries_23">section 4.5.3.1</a>
- for how to avoid copying the tlds into your application.
- </p>
-
- <div class="notice">
- <h4 class="center">
- Sidebar: Sharing JAR Files Across Web Applications
- </h4>
-
- <p>
- Many servlet containers and application servers provide facilities
- for sharing JAR files across multiple web applications that depend
- on them. For example, Tomcat 4.1 allows you to put JAR files into
- the <code>$CATALINA_HOME/shared/lib</code> or
- <code>$CATALINA_HOME/common/lib</code> directories, and the classes
- in those JAR files will be available in all applications, without
- the need to place them in every web application's
- <code>/WEB-INF/lib</code> directory. Usually, the sharing is
- accomplished by creating a separate class loader that is the parent
- of the class loader (created by your container) for each individual
- web application.
- </p>
-
- <p>
- If you have multiple Struts-based web applications, it is tempting
- to consider taking advantage of this container feature, and placing
- <code>struts.jar</code> and the various <code>commons-*.jar</code>
- files in the shared directory, rather than in each web application.
- However, there are several potential, and actual, problems with
- this approach:
- </p>
-
- <ul>
- <li>
- Classes loaded from the shared class loader cannot see classes
- in the web application's class loader, unless they are specifically
- programmed to use the Thread context class loader.
-
- For example, the framework dynamically loads your action and form bean
- classes, and normally would not be able to find those classes.
- The framework has been programmed to deal with this in <em>most</em>
- scenarios, but it has not been thoroughly audited to ensure that
- it works in <em>all</em> scenarios. The Commons libraries that
- the framework uses have <strong>NOT</strong> been audited to catch all
- possible scenarios where this might become a problem.
-
- </li>
- <li>
- When a class is loaded from a shared class loader, static variables
- used within that class become global as well. This can cause
- inter-webapp conflicts when the underlying code assumes that the
- statics are global only within a particular web applicaiton (which
- would be true if the class was loaded from the webapp class loader).
-
- There are many cases where the framework, and the Commons libraries it
- relies on, use static variables to maintain information that is
- presumed to be visible only within a single web application.
- Sharing these JAR files can cause unwanted interactions, and
- probably cause incorrect behavior.
-
- </li>
- <li>
- When JAR files are shared like this, it is not possible to update
- the JAR file versions employed by a single web application without
- updating all of them. In addition, because updating a Struts version
- normally requires recompilation of the applications that use it,
- you will have to recompile all of your applications as well, instead
- of being able to manage them independently.
- </li>
- </ul>
-
- <p>
- In spite of these difficulties, it is possible that sharing the
- Struts and Commons JAR files <em>might</em> appear to work for you.
- However, this is <strong>NOT</strong> a supported configuration.
- </p>
-
- <p>
- If you file a bug report for <code>ClassNotFoundException</code> or
- <code>NoClassDefFoundError</code> exceptions, or similar situations
- where it appears that the wrong version of a class is being loaded,
- the bug report will <strong>NOT</strong> be processed unless the
- problem exists with the JAR files in their recommended location,
- in the <code>/WEB-INF/lib</code> subdirectory of your webapp.
- </p>
- </div>
-
-</subsection>
-<a name="config_logging"/>
-<subsection name="5.6 Logging">
-
- <p>
- Since Struts 1.0, the logging functionality was fairly limited. You could
- set a debugging detail level with a servlet initialization parameter, and
- all log messages were written to wherever <code>ServletContext.log()</code>
- output is sent by your servlet container. With Struts 1.1, however, all
- logging messages written by the framework, as well as the commons libraries
- that it utilizes, flow through an abstract wrapper called
- <a href="http://jakarta.apache.org/commons/logging">Commons Logging</a>,
- which can be used as a wrapper around any logging implementation. The most
- common implementations used are simple logging to <code>System.err</code>,
- the <a href="http://jakarta.apache.org/log4j/">Apache Log4J</a> package,
- or the built-in logging capabilities of JDK 1.4 or later in the
- <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html">
- java.util.logging</a> package.
- </p>
-
- <p>
- This section does not attempt to fully explain how Commons Logging is
- configured and used. Instead, it focuses on pertinent details of using
- Commons Logging in connection with the Struts Action Framework. For complete documentation
- on using Commons Logging, consult the documentation for the logging system
- you are using, plus the Commons Logging
- <a href="http://jakarta.apache.org/commons/logging/commons-logging-1.0.3/docs/api/">
- Javadocs</a>.
- </p>
-
- <p>
- Commons Logging provides fine-grained control over the logging messages
- created by a <code>Log</code> instance. By convention, the <code>Log</code>
- instances for the framework (and the Commons packages in general) are named the
- fully qualified class name of the class whose messages are being logged.
- Therefore, log messages created by the <code>RequestProcessor</code> class are, naturally
- enough, directed to a logger named
- <code>org.apache.struts.action.RequestProcessor</code>.
- </p>
-
- <p>
- The advantage of this approach is that you can configure the level of detail
- in the output you want from each class, individually. However, it would be
- a burden to be required to maintain such settings for every possible class,
- so the logging environment supports the notion of logging
- <em>hierarchies</em> as well. If a detail level configuration for a
- particular class has not been set, the logging system looks up the hierarchy
- until it finds a configuration setting to use, or else uses the default
- detail level if no configuration for any level of the hierarchy has been
- explicitly set. In the case of our messages from <code>RequestProcessor</code>,
- the logging system will look for explicit settings of the following loggers,
- in this order, until it finds one:
- </p>
-
- <ul>
- <li><code>org.apache.struts.action.RequestProcessor</code></li>
- <li><code>org.apache.struts.action</code></li>
- <li><code>org.apache.struts</code></li>
- <li><code>org.apache</code></li>
- <li><code>org</code></li>
- <li>The default logging detail level for your log implementation.</li>
- </ul>
-
- <p>
- In a similar manner, the detail level for messages from
- <code>PropertyUtils</code> (from the Commons BeanUtils library) is set by
- a search for configuration settings for:
- </p>
-
- <ul>
- <li><code>org.apache.commons.beanutils.PropertyUtils</code></li>
- <li><code>org.apache.commons.beanutils</code></li>
- <li><code>org.apache.commons</code></li>
- <li><code>org.apache</code></li>
- <li><code>org</code></li>
- <li>The default logging detail level for your log implementation.</li>
- </ul>
-
- <p>
- You can seamlessly integrate logging from your own components into the same
- logging implementation that the framework and the Commons libraries use, by
- following the instructions in
- <a href="building_controller.html#4_11_Commons_Logging_Interface">
- Section 4.11</a>. If you do
- this, you are strongly encouraged to follow the same naming convention for
- loggers (based on the class name of the messages being logged) for
- maximum configuration flexibility.
- </p>
-
-</subsection>
-
-
-<subsection>
-
- <p>
- For more about putting it all together, see the <a href="../faqs/apps.html">
- Building Applications HowTo</a>.
- </p>
-
- <p class="right">
- Next: <a href="./release-notes.html">Release Notes</a>
- </p>
+ <p>
+ and a request URI to match the
+ <code>/logon</code>
+ path described
+ earlier might look like this:
+ </p>
+
+ <source>
+ http://www.mycompany.com/myapplication/logon.do</source>
+
+ <p>
+ <strong>WARNING</strong>
+ - The framework will not
+ operate correctly if you define more than one
+ <code><servlet-mapping></code>
+ element for the controller
+ servlet.
+ </p>
+
+ <p>
+ <strong>WARNING</strong>
+ - If you are using
+ the new module support since Struts 1.1, you should be
+ aware
+ that
+ <strong>only</strong>
+ extension mapping is supported.
+ </p>
+
+ </subsection>
+
+ <a name="dd_config_taglib_uri"/>
+ <subsection
+ name="5.4.3.1 Configure the Struts JSP Tag Libraries (Servlet 2.3/2.4)">
+
+ <p>
+ The Servlet 2.3 and 2.4 specifications simplify the
+ deployment and configuration of tag libraries.
+ All that's now required to install the Struts tag
+ libraries is to copy
+ <code>struts-taglib.jar</code>
+ into your
+ <code>/WEB-INF/lib</code>
+ directory and reference the tags in
+ your code like this:
+ </p>
+
+ <source>
+ <%@ taglib
+ uri="http://struts.apache.org/tags-html"
+ prefix="html" %>
+ </source>
+
+ <p>
+ Note that you
+ <strong>must use the full uri</strong>
+ defined in the various
+ tlds (see the
+ <a href="5_4_3_Configure_the_Struts_Tag_Libraries">
+ example configuration</a>
+ for reference)
+ so that the container knows where to find the tag's class
+ files.
+ You don't have to alter your
+ <code>web.xml</code>
+ file or copy tlds into any
+ application directories.
+ </p>
+
+ <p>
+ Of course, the configuration techniques use for older
+ containers do still work.
+ </p>
+
+ </subsection>
+
+ <a name="config_add"/>
+ <subsection name="5.5 Add Struts Components To Your Application">
+
+ <p>
+ To use the framework, you must copy
+ <code>struts.jar</code>
+ (and all of the
+ <code>commons-*.jar</code>
+ files) into your
+ <code>WEB-INF/lib</code>
+ directory. To use Struts Taglib,
+ you must also copy the .tld files that you require into
+ your
+ <code>WEB-INF</code>
+ directory and the struts-taglib.jar.
+ </p>
+
+ <p>
+ <strong>Servlet 2.3/2.4 Users:</strong>
+ See
+ <a href="5_4_3_Configure_the_Struts_Tag_Libraries_23">
+ section 4.5.3.1</a>
+ for how to avoid copying the tlds into your application.
+ </p>
+
+ <div class="notice">
+ <h4 class="center">
+ Sidebar: Sharing JAR Files Across Web Applications
+ </h4>
+
+ <p>
+ Many servlet containers and application servers
+ provide facilities
+ for sharing JAR files across multiple web applications
+ that depend
+ on them. For example, Tomcat 4.1 allows you to put JAR
+ files into
+ the
+ <code>$CATALINA_HOME/shared/lib</code>
+ or
+ <code>$CATALINA_HOME/common/lib</code>
+ directories, and the classes
+ in those JAR files will be available in all
+ applications, without
+ the need to place them in every web application's
+ <code>/WEB-INF/lib</code>
+ directory. Usually, the sharing is
+ accomplished by creating a separate class loader that
+ is the parent
+ of the class loader (created by your container) for
+ each individual
+ web application.
+ </p>
+
+ <p>
+ If you have multiple Struts-based web applications, it
+ is tempting
+ to consider taking advantage of this container
+ feature, and placing
+ <code>struts.jar</code>
+ and the various
+ <code>commons-*.jar</code>
+ files in the shared directory, rather than in each web
+ application.
+ However, there are several potential, and actual,
+ problems with
+ this approach:
+ </p>
+
+ <ul>
+ <li>
+ Classes loaded from the shared class loader cannot
+ see classes
+ in the web application's class loader, unless they
+ are specifically
+ programmed to use the Thread context class loader.
+
+ For example, the framework dynamically loads your
+ action and form bean
+ classes, and normally would not be able to find
+ those classes.
+ The framework has been programmed to deal with
+ this in
+ <em>most</em>
+ scenarios, but it has not been thoroughly audited
+ to ensure that
+ it works in
+ <em>all</em>
+ scenarios. The Commons libraries that
+ the framework uses have
+ <strong>NOT</strong>
+ been audited to catch all
+ possible scenarios where this might become a
+ problem.
+
+ </li>
+ <li>
+ When a class is loaded from a shared class loader,
+ static variables
+ used within that class become global as well. This
+ can cause
+ inter-webapp conflicts when the underlying code
+ assumes that the
+ statics are global only within a particular web
+ applicaiton (which
+ would be true if the class was loaded from the
+ webapp class loader).
+
+ There are many cases where the framework, and the
+ Commons libraries it
+ relies on, use static variables to maintain
+ information that is
+ presumed to be visible only within a single web
+ application.
+ Sharing these JAR files can cause unwanted
+ interactions, and
+ probably cause incorrect behavior.
+
+ </li>
+ <li>
+ When JAR files are shared like this, it is not
+ possible to update
+ the JAR file versions employed by a single web
+ application without
+ updating all of them. In addition, because
+ updating a Struts version
+ normally requires recompilation of the
+ applications that use it,
+ you will have to recompile all of your
+ applications as well, instead
+ of being able to manage them independently.
+ </li>
+ </ul>
+
+ <p>
+ In spite of these difficulties, it is possible that
+ sharing the
+ Struts and Commons JAR files
+ <em>might</em>
+ appear to work for you.
+ However, this is
+ <strong>NOT</strong>
+ a supported configuration.
+ </p>
+
+ <p>
+ If you file a bug report for
+ <code>ClassNotFoundException</code>
+ or
+ <code>NoClassDefFoundError</code>
+ exceptions, or similar situations
+ where it appears that the wrong version of a class is
+ being loaded,
+ the bug report will
+ <strong>NOT</strong>
+ be processed unless the
+ problem exists with the JAR files in their recommended
+ location,
+ in the
+ <code>/WEB-INF/lib</code>
+ subdirectory of your webapp.
+ </p>
+ </div>
+
+ </subsection>
+ <a name="config_logging"/>
+ <subsection name="5.6 Logging">
+
+ <p>
+ Since Struts 1.0, the logging functionality was fairly
+ limited. You could
+ set a debugging detail level with a servlet initialization
+ parameter, and
+ all log messages were written to wherever
+ <code>ServletContext.log()</code>
+ output is sent by your servlet container. With Struts 1.1,
+ however, all
+ logging messages written by the framework, as well as the
+ commons libraries
+ that it utilizes, flow through an abstract wrapper called
+ <a href="http://jakarta.apache.org/commons/logging">
+ Commons Logging</a>
+ ,
+ which can be used as a wrapper around any logging
+ implementation. The most
+ common implementations used are simple logging to
+ <code>System.err</code>
+ ,
+ the
+ <a href="http://jakarta.apache.org/log4j/">Apache
+ Log4J</a>
+ package,
+ or the built-in logging capabilities of JDK 1.4 or later
+ in the
+ <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html">
+ java.util.logging</a>
+ package.
+ </p>
+
+ <p>
+ This section does not attempt to fully explain how Commons
+ Logging is
+ configured and used. Instead, it focuses on pertinent
+ details of using
+ Commons Logging in connection with the Struts Action
+ Framework. For complete documentation
+ on using Commons Logging, consult the documentation for
+ the logging system
+ you are using, plus the Commons Logging
+ <a href="http://jakarta.apache.org/commons/logging/commons-logging-1.0.3/docs/api/">
+ Javadocs</a>
+ .
+ </p>
+
+ <p>
+ Commons Logging provides fine-grained control over the
+ logging messages
+ created by a
+ <code>Log</code>
+ instance. By convention, the
+ <code>Log</code>
+ instances for the framework (and the Commons packages in
+ general) are named the
+ fully qualified class name of the class whose messages are
+ being logged.
+ Therefore, log messages created by the
+ <code>RequestProcessor</code>
+ class are, naturally
+ enough, directed to a logger named
+ <code>org.apache.struts.action.RequestProcessor</code>
+ .
+ </p>
+
+ <p>
+ The advantage of this approach is that you can configure
+ the level of detail
+ in the output you want from each class, individually.
+ However, it would be
+ a burden to be required to maintain such settings for
+ every possible class,
+ so the logging environment supports the notion of logging
+ <em>hierarchies</em>
+ as well. If a detail level configuration for a
+ particular class has not been set, the logging system
+ looks up the hierarchy
+ until it finds a configuration setting to use, or else
+ uses the default
+ detail level if no configuration for any level of the
+ hierarchy has been
+ explicitly set. In the case of our messages from
+ <code>RequestProcessor</code>
+ ,
+ the logging system will look for explicit settings of the
+ following loggers,
+ in this order, until it finds one:
+ </p>
+
+ <ul>
+ <li>
+ <code>org.apache.struts.action.RequestProcessor</code>
+ </li>
+ <li>
+ <code>org.apache.struts.action</code>
+ </li>
+ <li>
+ <code>org.apache.struts</code>
+ </li>
+ <li>
+ <code>org.apache</code>
+ </li>
+ <li>
+ <code>org</code>
+ </li>
+ <li>The default logging detail level for your log
+ implementation.</li>
+ </ul>
+
+ <p>
+ In a similar manner, the detail level for messages from
+ <code>PropertyUtils</code>
+ (from the Commons BeanUtils library) is set by
+ a search for configuration settings for:
+ </p>
+
+ <ul>
+ <li>
+ <code>
+ org.apache.commons.beanutils.PropertyUtils</code>
+ </li>
+ <li>
+ <code>org.apache.commons.beanutils</code>
+ </li>
+ <li>
+ <code>org.apache.commons</code>
+ </li>
+ <li>
+ <code>org.apache</code>
+ </li>
+ <li>
+ <code>org</code>
+ </li>
+ <li>The default logging detail level for your log
+ implementation.</li>
+ </ul>
+
+ <p>
+ You can seamlessly integrate logging from your own
+ components into the same
+ logging implementation that the framework and the Commons
+ libraries use, by
+ following the instructions in
+ <a href="building_controller.html#4_11_Commons_Logging_Interface">
+ Section 4.11</a>
+ . If you do
+ this, you are strongly encouraged to follow the same
+ naming convention for
+ loggers (based on the class name of the messages being
+ logged) for
+ maximum configuration flexibility.
+ </p>
+
+ </subsection>
+
+
+ <subsection>
+
+ <p>
+ For more about putting it all together, see the
+ <a href="../faqs/apps.html">
+ Building Applications HowTo</a>
+ .
+ </p>
+
+ <p class="right">
+ Next:
+ <a href="./release-notes.html">Release Notes</a>
+ </p>
-</subsection>
+ </subsection>
- </section>
- </body>
+ </section>
+ </body>
</document>
Modified: struts/action/trunk/xdocs/userGuide/dev_util.xml
URL: http://svn.apache.org/viewcvs/struts/action/trunk/xdocs/userGuide/dev_util.xml?rev=370938&r1=370937&r2=370938&view=diff
==============================================================================
--- struts/action/trunk/xdocs/userGuide/dev_util.xml (original)
+++ struts/action/trunk/xdocs/userGuide/dev_util.xml Fri Jan 20 16:19:02 2006
@@ -18,26 +18,32 @@
-->
<document>
-<properties>
- <title>Utilities Guide</title>
-</properties>
-<body>
-<section name="Utilities Guide">
-
-<subsection href="utils" name="The Utilities Package">
-
-<p>
-The Utilities package provides a variety of families of classes, to solve problems that are commonly
-encountered in building web applications.
-</p>
-
-</subsection>
-
-<subsection href="resources" name="Utilities Resources">
-
-<ul>
-<li><a href="../struts-action/apidocs/org/apache/struts/util/package-summary.html#package_description">Utilities Package Description</a></li>
-</ul>
-</subsection>
-
-</section></body></document>
+ <properties>
+ <title>Utilities Guide</title>
+ </properties>
+ <body>
+ <section name="Utilities Guide">
+
+ <subsection href="utils" name="The Utilities Package">
+
+ <p>
+ The Utilities package provides a variety of families of
+ classes, to solve problems that are commonly
+ encountered in building web applications.
+ </p>
+
+ </subsection>
+
+ <subsection href="resources" name="Utilities Resources">
+
+ <ul>
+ <li>
+ <a href="../struts-action/apidocs/org/apache/struts/util/package-summary.html#package_description">
+ Utilities Package Description</a>
+ </li>
+ </ul>
+ </subsection>
+
+ </section>
+ </body>
+</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org