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.
The Building Controller
Components chapter covered writing the <form-bean> and
<action-mapping> 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.
These "static" configuration elements are:
The <controller> element allows you to configure
the ActionServlet.
Many of the controller parameters were previously defined by servlet
initialization parameters in your web.xml file but have been
moved to this section of struts-config.xml in order to allow
different modules in the same web application to be configured differently.
For full details on available parameters see the
struts-config_1_2.dtd or the list below.
<forward> element is mapped to a
context-relative URL when it starts with a slash (and when the
contextRelative property is false).
This value may consist of any combination of the following:
<forward> element.
true if you want the
input attribute of <action> elements
to be the name of a local or global ActionForward, which
will then be used to calculate the ultimate URL.
Set to false to treat the input parameter of
<action> elements as a module-relative path to
the resource to be used as the input form.
[false] (optional)
true if you want a
Locale object stored in the user's session if not already
present.
[true] (optional)
true if you want the controller
to add HTTP headers for defeating caching to every response from
this module.
[false] (optional)
page 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:
<forward> element.
RequestProcessor subclass to be used with this module.
[org.apache.struts.action.RequestProcessor] (optional)
This example uses the default values for several controller parameters. If you only want default behavior you can omit the controller section altogether.
;
]]>
Struts has built in support for internationalization (I18N).
You can define one or more <message-resources> 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.
false to display missing resource
keys in your application like '???keyname???' instead of
null.
[true] (optional)
Example configuration:
]]>
This would set up a message resource bundle provided in the file
MyWebAppResources.properties under the default key.
Missing resource keys would be displayed as '???keyname???'.
Struts PlugIns are configured using the <plug-in>
element within the Struts configuration file.
This element has only one valid attribute, 'className', which is the fully
qualified name of the Java class which implements the
org.apache.struts.action.PlugIn interface.
For PlugIns that require configuration themselves, the nested
<set-property> element is available.
This is an example using the Tiles plugin:
Besides the objects related to defining ActionMappings, the Struts configuration may contain elements that create other useful objects.
The <data-sources> 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 data-sources element.
Since DataSource implementations vary in what properties need to be
set, unlike other Struts configuration elements, the
<data-source> element does not pre-define a slate of
properties.
Instead, the generic <set-property> feature is used to set
whatever properties your implementation may require.
Typically, these settings would include:
And other sundry properties.
]]>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.
For examples of specifying a <data-sources> element and using the
DataSource with an Action, see the
Accessing a Database HowTo.
Very little is required in order to start taking advantage of the Struts module feature. Just go through the following steps:
Back in Struts 1.0, a few "boot-strap" options were placed in the web.xml
file, and the bulk of the configuration was done in a single
struts-config.xml file.
Obviously, this wasn't ideal for a team environment, since multiple users
had to share the same configuration file.
Since Struts 1.1, you have two options: you can list multiple struts-config files as a comma-delimited list, or you can subdivide a larger application into modules.
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.
Since Struts 1.0, you listed your configuration file as an initialization
parameter to the action servlet in web.xml.
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/module", where module is
the name of your module (this gets used when determining which URIs fall
under a given module, so choose something meaningful!).
For example:
config
/WEB-INF/conf/struts-default.xml
config/module1
/WEB-INF/conf/struts-module1.xml
...
]]>
Here we have two modules.
One happens to be the "default" module, which has no "/module" in its
name, and the other one named "module1" (config/module1).
The controller is configured to find the respective configuration files
under /WEB-INF/conf/ (which is the recommended place to put all configuration files).
Pretty simple!
(The struts-default.xml would be equivalent to what most folks call
struts-config.xml.
I just like the symmetry of having all my Struts module configuration files being
named struts-modulename.xml)
If you'd like to vary where the pages for each module are stored, see the forwardPattern setting for the Controller.
There are three approaches for switching from one module to another.
You can use the built-in org.apache.struts.actions.SwitchAction,
you can use a <forward> (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).
You can use org.apache.struts.actions.SwitchAction like so:
Now, to change to ModuleB, we would use a URI like this:
http://localhost:8080/toModule.do?prefix=/moduleB&page=/index.do
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:
http://localhost:8080/toModule.do?prefix=&page=/index.do
Here's an example of a global forward:
You could do the same thing with a local forward declared in an ActionMapping:
...
]]>
Or, you can use
org.apache.struts.actions.SwitchAction:
Now, to change to ModuleB, we would use a URI like this:
http://localhost:8080/toModule.do?prefix=/moduleB&page=/index.do
Using the module parameter with a hyperlink tag is even simplier:
]]>That's all there is to it! Happy module-switching!
The final step in setting up the application is to configure the
application deployment descriptor (stored in file
WEB-INF/web.xml) 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.
Add an entry defining the action servlet itself, along with the appropriate initialization parameters. Such an entry might look like this:
action
org.apache.struts.action.ActionServlet
config
/WEB-INF/struts-config.xml
1
]]>The initialization parameters supported by the action servlet are described below. (You can also find these details in the Javadocs for the ActionServlet class.) Square brackets describe the default values that are assumed if you do not provide a value for that initialization parameter.
java.lang.Integer) will default to null (rather than 0).
(Since Struts 1.1) [false]
org.apache.commons.digester.RuleSet instances that
should be added to the Digester that will be processing
struts-config.xml files.
By default, only the RuleSet for the standard
configuration elements is loaded. (Since Struts 1.1)
WARNING - Struts will not
operate correctly if you define more than one
<servlet> element for a controller
servlet, or a subclass of the standard controller servlet class.
The controller servlet MUST be a web application
wide singleton.
Note: 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.
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.
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:
action
/do/*
]]>
which means that a request URI to match the /logon path
described earlier might look like this:
http://www.mycompany.com/myapplication/do/logon
where /myapplication is the context path under which your
application is deployed.
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 *.jsp pattern so that it is called to process
every JSP page that is requested.
To use the *.do extension (which implies "do something"),
the mapping entry would look like this:
action
*.do
]]>
and a request URI to match the /logon path described
earlier might look like this:
http://www.mycompany.com/myapplication/logon.do
WARNING - Struts will not
operate correctly if you define more than one
<servlet-mapping> element for the controller
servlet.
WARNING - If you are using the new module support since Struts 1.1, you should be aware that only extension mapping is supported.
Next, you must add an entry defining the Struts tag libraries.
The struts-bean taglib contains tags useful in accessing beans and their properties, as well as defining new beans (based on these accesses) that are accessible to the remainder of the page via scripting variables and page scope attributes. Convenient mechanisms to create new beans based on the value of request cookies, headers, and parameters are also provided.
The struts-html taglib contains tags used to create Struts input forms, as well as other tags generally useful in the creation of HTML-based user interfaces.
The struts-logic taglib contains tags that are useful in managing conditional generation of output text, looping over object collections for repetitive generation of output text, and application flow management.
The struts-tiles taglib contains tags used for combining various view components, called "tiles", into a final composite view.
The struts-nested taglib is an extension of other struts taglibs that allows the use of nested beans.
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:
http://struts.apache.org/tags-bean
/WEB-INF/struts-bean.tld
http://struts.apache.org/tags-html
/WEB-INF/struts-html.tld
http://struts.apache.org/tags-logic
/WEB-INF/struts-logic.tld
http://struts.apache.org/tags-tiles
/WEB-INF/struts-tiles.tld
http://struts.apache.org/tags-nested
/WEB-INF/struts-nested.tld
]]>
This tells the JSP system where to find the tag library descriptor
for this library (in your application's WEB-INF directory, instead of
out on the Internet somewhere).
Servlet 2.3 users only: The Servlet 2.3 specification simplifies the deployment and configuration of tag libraries. The instructions above will work on older containers as well as 2.3 containers (Struts only requires a servlet 2.2 container); however, if you're using a 2.3 container such as Tomcat 4.x, you can take advantage of a simplified deployment.
All that's required to install the Struts tag libraries is to copy
struts.jar into your /WEB-INF/lib directory and reference the tags in
your code like this:
<%@ taglib
uri="http://struts.apache.org/tags-html"
prefix="html" %>
Note that you must use the full uri defined in the various
tlds (see the example configuration for reference)
so that the container knows where to find the tag's class files.
You don't have to alter your web.xml file or copy tlds into any
application directories.
To use Struts, you must copy the .tld files that you require into
your WEB-INF directory, and copy struts.jar
(and all of the commons-*.jar files) into your
WEB-INF/lib directory.
Servlet 2.3 Users: See section 4.5.3.1 for how to avoid copying the tlds into your application.
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 $CATALINA_HOME/shared/lib or
$CATALINA_HOME/common/lib 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
/WEB-INF/lib 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.
If you have multiple Struts-based web applications, it is tempting
to consider taking advantage of this container feature, and placing
struts.jar and the various commons-*.jar
files in the shared directory, rather than in each web application.
However, there are several potential, and actual, problems with
this approach:
In spite of these difficulties, it is possible that sharing the Struts and Commons JAR files might appear to work for you. However, this is NOT a supported configuration.
If you file a bug report for ClassNotFoundException or
NoClassDefFoundError exceptions, or similar situations
where it appears that the wrong version of a class is being loaded,
the bug report will NOT be processed unless the
problem exists with the JAR files in their recommended location,
in the /WEB-INF/lib subdirectory of your webapp.
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 ServletContext.log()
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
Commons Logging,
which can be used as a wrapper around any logging implementation. The most
common implementations used are simple logging to System.err,
the Apache Log4J package,
or the built-in logging capabilities of JDK 1.4 or later in the
java.util.logging package.
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 Javadocs.
Commons Logging provides fine-grained control over the logging messages
created by a Log instance. By convention, the Log
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 RequestProcessor class are, naturally
enough, directed to a logger named
org.apache.struts.action.RequestProcessor.
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
hierarchies 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 RequestProcessor,
the logging system will look for explicit settings of the following loggers,
in this order, until it finds one:
org.apache.struts.action.RequestProcessororg.apache.struts.actionorg.apache.strutsorg.apacheorg
In a similar manner, the detail level for messages from
PropertyUtils (from the Commons BeanUtils library) is set by
a search for configuration settings for:
org.apache.commons.beanutils.PropertyUtilsorg.apache.commons.beanutilsorg.apache.commonsorg.apacheorgYou 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 Section 4.10. 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.
For more about putting it all together, see the Building Applications HowTo.
Next: Release Notes