blob: 7b25f08cc65e60acb04990f35092ddfb832e963a [file] [log] [blame]
<?xml version="1.0"?>
<document url="configuration.html">
<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>
<author>Tim O'Brien</author>
</properties>
<body>
<chapter name="5. Configuring Applications" href="config_apps">
<section name="5.1 Overview" href="config-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 Struts application.
These include components in the Struts configuration file
and in the Web Application Deployment Descriptor.
</p>
</section>
<section name="5.2 The Struts configuration file" href="struts-config">
<p>
The <a href="building_controller.html#config">Building Controller
Components</a> chapter covered writing the <code>&lt;form-bean&gt;</code> and
<code>&lt;action-mapping&gt;</code> portions of the Struts 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>
&lt;controller&gt;
</li>
<li>
&lt;message-resources&gt;
</li>
<li>
&lt;plug-in&gt;
</li>
<li>
&lt;data-sources&gt;
</li>
</ul>
</section>
<section name="5.2.1 Controller Configuration" href="controller_config">
<p>
The <code>&lt;controller&gt;</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_2.dtd">
struts-config_1_2.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>className</strong> - Classname of configuration bean.
[org.apache.struts.config.ControllerConfig] (optional)
</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>&lt;forward&gt;</code> element is mapped to a
context-relative URL when it starts with a slash (and when the
<code>contextRelative</code> property is <code>false</code>).
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>&lt;forward&gt;</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>&lt;action&gt;</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>&lt;action&gt;</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>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>&lt;forward&gt;</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.action.RequestProcessor] (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>
<pre><code><![CDATA[
<controller
processorClass="org.apache.struts.action.RequestProcessor"
contentType="text/html"/>;
]]></code></pre>
</section>
<section name="5.2.2 Message Resources Configuration" href="resources_config">
<p>
Struts has built in support for internationalization (I18N).
You can define one or more <code>&lt;message-resources&gt;</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>
<p>Example configuration:</p>
<pre><code><![CDATA[
<message-resources
parameter="MyWebAppResources"
null="false" />
]]></code></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 '<em>???keyname???</em>'.
</p>
</section>
<section name="5.2.3 PlugIn Configuration" href="plugin_config">
<p>
Struts PlugIns are configured using the <code>&lt;plug-in&gt;</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>&lt;set-property&gt;</code> element is available.
</p>
<p>
This is an example using the Tiles plugin:
</p>
<pre><code><![CDATA[
<plug-in className="org.apache.struts.tiles.TilesPlugin">
<set-property
property="definitions-config"
value="/WEB-INF/tiles-defs.xml"/>
</plug-in>
]]></code></pre>
</section>
<section name="5.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>&lt;data-sources></code> section can be used to specify
a collection of DataSources [javax.sql.DataSource] for the use of your
application.
Typically, a DataSource represents a connection pool to a database
or other persistent store.
As a convenience, the Struts DataSource manager can be used to
instantiate whatever standard pool your application may need.
Of course, if your persistence layer provides for its own connections,
then you do not need to specify a <code>data-sources</code> element.
</p>
<p>
Since DataSource implementations vary in what properties need to be
set, unlike other Struts configuration elements, the
<code>&lt;data-source&gt;</code> element does not pre-define a slate of
properties.
Instead, the generic <code>&lt;set-property&gt;</code> feature is used to set
whatever properties your implementation may require.
Typically, these settings would include:
</p>
<ul>
<li>
A driver class name
</li>
<li>
A url to access the driver
</li>
<li>
A description
</li>
</ul>
<p>
And other sundry properties.
</p>
<pre><code><![CDATA[
<data-source type="org.apache.commons.dbcp.BasicDataSource">
<!-- ... set-property elements ... -->
</data-source>
]]></code></pre>
<p>
Since Struts 1.2.0, the GenericDataSource has been removed, and it is
recommended that you use the Commons BasicDataSource or other DataSource
implementations instead. In practice, if you need to use the DataSource
manager, you should use whatever DataSource implementation works best
with your container or database.
</p>
<p>
For examples of specifying a <code>&lt;data-sources&gt;</code> element and using the
DataSource with an Action, see the
<a href="../faqs/database.html">Accessing a Database HowTo</a>.
</p>
</section>
<section
name="5.3 Configuring your application for modules"
href="dd_config_modules">
<p>
Very little is required in order to start taking advantage of the Struts
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>
</section>
<section name="5.3.1 Module Configuration Files" href="module_config-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="#dd_config_servlet">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>
</section>
<section
name="5.3.2 Informing the Controller"
href="module_config-inform_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 Struts 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>
<pre><code><![CDATA[
...
<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>
...
]]></code></pre>
<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 Struts 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="#controller_config">forwardPattern</a> setting for the
Controller.
</p>
</section>
<section name="5.3.3 Switching Modules" href="module_config-switching">
<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>&lt;forward&gt;</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 hyperlink tags (Include, Img, Link, Rewrite, or Forward).
</p>
<p>
You can use <code>org.apache.struts.actions.SwitchAction</code> like so:
</p>
<pre><code><![CDATA[
...
<action-mappings>
<action path="/toModule"
type="org.apache.struts.actions.SwitchAction"/>
...
</action-mappings>
...
]]></code></pre>
<p>
Now, to change to ModuleB, we would use a URI like this:
</p>
<pre><code>
http://localhost:8080/toModule.do?prefix=/moduleB&amp;page=/index.do
</code></pre>
<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>
<pre><code>
http://localhost:8080/toModule.do?prefix=&amp;page=/index.do
</code></pre>
<p>
Here's an example of a global forward:
</p>
<pre><code><![CDATA[
<global-forwards>
<forward name="toModuleB"
contextRelative="true"
path="/moduleB/index.do"
redirect="true"/>
...
</global-forwards>
]]></code></pre>
<p>
You could do the same thing with a local forward declared in an
ActionMapping:
</p>
<pre><code><![CDATA[
<action-mappings>
<action ... >
<forward name="success"
contextRelative="true"
path="/moduleB/index.do"
redirect="true"/>
</action>
...
</action-mappings>
]]></code></pre>
<p>
Or, you can use
<code>org.apache.struts.actions.SwitchAction</code>:
</p>
<pre><code><![CDATA[
<action-mappings>
<action path="/toModule"
type="org.apache.struts.actions.SwitchAction"/>
...
</action-mappings>
]]></code></pre>
<p>
Now, to change to ModuleB, we would use a URI like this:
</p>
<pre><code>
http://localhost:8080/toModule.do?prefix=/moduleB&amp;page=/index.do
</code></pre>
<p>
Using the module parameter with a hyperlink tag is even simpler:
</p>
<pre><code><![CDATA[
<html:link module="/moduleB" path="/index.do"/>
]]></code></pre>
<p>
That's all there is to it! Happy module-switching!
</p>
</section>
<section name="5.4 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="5.4.1 Configure the ActionServlet 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><code><![CDATA[
<servlet>
<servlet-name>action</servlet-name>
<servlet-class>
org.apache.struts.action.ActionServlet
</servlet-class>
<init-param>
<param-name>config</param-name>
<param-value>
/WEB-INF/struts-config.xml
</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
]]></code></pre>
<p>
The initialization parameters supported by the action 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.
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>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>
<li>
<strong>configFactory</strong> - The Java class name of the
<code>ModuleConfigFactory</code> used to create the implementation of the
<code>ModuleConfig</code> interface.
[org.apache.struts.config.impl.DefaultModuleConfigFactory]
</li>
</ul>
<p>
<strong>WARNING</strong> - Struts will not
operate correctly if you define more than one
<code>&lt;servlet&gt;</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>
</section>
<section
name="5.4.2 Configure the ActionServlet 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><code><![CDATA[
<servlet-mapping>
<servlet-name>action</servlet-name>
<url-pattern>/do/*</url-pattern>
</servlet-mapping>
]]></code></pre>
<p>
which means that a request URI to match the <code>/logon</code> path
described earlier might look like this:
</p>
<pre><code>http://www.mycompany.com/myapplication/do/logon</code></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><code><![CDATA[
<servlet-mapping>
<servlet-name>action</servlet-name>
<url-pattern>*.do</url-pattern>
</servlet-mapping>
]]></code></pre>
<p>
and a request URI to match the <code>/logon</code> path described
earlier might look like this:
</p>
<pre><code>http://www.mycompany.com/myapplication/logon.do</code></pre>
<p>
<strong>WARNING</strong> - Struts will not
operate correctly if you define more than one
<code>&lt;servlet-mapping&gt;</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>
</section>
<section
name="5.4.3 Configure the Struts Tag Libraries"
href="dd_config_taglib">
<p>
Next, you must add an entry defining the Struts tag libraries.
</p>
<p>
The <a href="dev_bean.html">struts-bean</a> 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 <a href="dev_html.html">struts-html</a> 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 <a href="dev_logic.html">struts-logic</a> 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 <a href="dev_tiles.html">struts-tiles</a> taglib contains tags used for combining various view
components, called "tiles", into a final composite view.
</p>
<p>
The <a href="dev_nested.html">struts-nested</a> taglib is an extension of other struts taglibs that
allows the use of nested beans.
</p>
<p>
Below is how you would define all Struts taglibs for use within your
application.
In practice, you would only specify the taglibs that your application
uses:
</p>
<pre><code><![CDATA[
<taglib>
<taglib-uri>
http://struts.apache.org/tags-bean
</taglib-uri>
<taglib-location>
/WEB-INF/struts-bean.tld
</taglib-location>
</taglib>
<taglib>
<taglib-uri>
http://struts.apache.org/tags-html
</taglib-uri>
<taglib-location>
/WEB-INF/struts-html.tld
</taglib-location>
</taglib>
<taglib>
<taglib-uri>
http://struts.apache.org/tags-logic
</taglib-uri>
<taglib-location>
/WEB-INF/struts-logic.tld
</taglib-location>
</taglib>
<taglib>
<taglib-uri>
http://struts.apache.org/tags-tiles
</taglib-uri>
<taglib-location>
/WEB-INF/struts-tiles.tld
</taglib-location>
</taglib>
<taglib>
<taglib-uri>
http://struts.apache.org/tags-nested
</taglib-uri>
<taglib-location>
/WEB-INF/struts-nested.tld
</taglib-location>
</taglib>
]]></code></pre>
<p>
This tells the JSP system where to find the tag library descriptor
for this library (in your application's <code>WEB-INF</code> directory, instead of
out on the Internet somewhere).
</p>
</section>
<section
name="5.4.3.1 Configure the Struts Tag Libraries (Servlet 2.3/2.4)"
href="dd_config_taglib_23">
<p>
<strong>Servlet 2.3/2.4 users only:</strong> The Servlet 2.3 and 2.4 specifications simplify
the deployment and configuration of tag libraries.
The instructions above will work on older containers as well as 2.3 and 2.4
containers (Struts only requires a servlet 2.2 container);
however, if you're using a 2.3/2.4 container such as Tomcat 4.x/5.x,
you can take advantage of a simplified deployment.
</p>
<p>
All that's required to install the Struts tag libraries is to copy
<code>struts.jar</code> into your <code>/WEB-INF/lib</code> directory and reference the tags in
your code like this:
</p>
<pre><code>
&lt;%@ taglib
uri="http://struts.apache.org/tags-html"
prefix="html" %&gt;
</code></pre>
<p>
Note that you <strong>must use the full uri</strong> defined in the various
tlds (see the <a href="#dd_config_taglib">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>
</section>
<section
name="5.5 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>
<strong>Servlet 2.3/2.4 Users:</strong> See
<a href="#dd_config_taglib_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, Struts dynamically loads your action and form bean
classes, and normally would not be able to find those classes.
Struts 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
Struts 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 Struts, and the Commons libraries it
relies on, use static variables to maintain information that is
presumed to be visible only within a single web applicaiton.
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>
</section>
<section
name="5.6 Logging in Struts Based Applications"
href="config_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 Struts itself, 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 a Struts based environment. 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/api/org/apache/commons/logging/package-summary.html#package_description">
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 Struts (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 Struts and the Commons libraries use, by
following the instructions in
<a href="building_controller.html#logging">Section 4.10</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>
</section>
<section>
<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>
</section>
</chapter>
</body>
</document>