5. Configuring Applications

5.1 Overview

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.

5.2 The Struts configuration file

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:

<message-resources>

<plug-in>

<data-sources>

5.2.1 Controller Configuration

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.

bufferSize - The size (in bytes) of the input buffer used when processing file uploads. [4096] (optional)

className - Classname of configuration bean. [org.apache.struts.config.ControllerConfig] (optional)

contentType - 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)

forwardPattern - Replacement pattern defining how the "path" attribute of a <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:

$M - Replaced by the module prefix of this module.

$P - Replaced by the "path" attribute of the selected <forward> element.

$$ - Causes a literal dollar sign to be rendered.

$x - (Where "x" is any character not defined above) Silently swallowed, reserved for future use. If not specified, the default forwardPattern is consistent with the previous behavior of forwards. [$M$P] (optional)

inputForward - Set to 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)

locale - Set to true if you want a Locale object stored in the user's session if not already present. [true] (optional)

maxFileSize - 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)

multipartClass - The fully qualified Java class name of the multipart request handler class to be used with this module. [org.apache.struts.upload.CommonsMultipartRequestHandler] (optional)

nocache - Set to true if you want the controller to add HTTP headers for defeating caching to every response from this module. [false] (optional)

pagePattern - Replacement pattern defining how the 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:

$M - Replaced by the module prefix of this module.

$P - Replaced by the "path" attribute of the selected <forward> element.

$$ - Causes a literal dollar sign to be rendered.

$x - (Where "x" is any character not defined above) Silently swallowed, reserved for future use. If not specified, the default pagePattern is consistent with the previous behavior of URL calculation. [$M$P] (optional)

processorClass - The fully qualified Java class name of the RequestProcessor subclass to be used with this module. [org.apache.struts.action.RequestProcessor] (optional)

tempDir - Temporary working Directory to use when processing file uploads. [{the directory provided by the servlet container}]

This example uses the default values for several controller parameters. If you only want default behavior you can omit the controller section altogether.

<controller

processorClass="org.apache.struts.action.RequestProcessor"

contentType="text/html"/>;

5.2.2 Message Resources Configuration

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.

className - Classname of configuration bean. [org.apache.struts.config.MessageResourcesConfig] (optional)

factory - Classname of MessageResourcesFactory. [org.apache.struts.util.PropertyMessageResourcesFactory] (optional)

key - ServletContext attribute key to store this bundle. [org.apache.struts.action.MESSAGE] (optional)

null - Set to false to display missing resource keys in your application like '???keyname???' instead of null. [true] (optional)

parameter - Name of the resource bundle. (required)

Example configuration:

<message-resources

parameter="MyWebAppResources"

null="false" />

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???'.

5.2.3 PlugIn Configuration

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:

<plug-in className="org.apache.struts.tiles.TilesPlugin">

<set-property

property="definitions-config"

value="/WEB-INF/tiles-defs.xml"/>

</plug-in>

5.2.4 Data Source Configuration

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:

A driver class name

A url to Access the driver

A description

And other sundry properties.

<data-source type="org.apache.commons.dbcp.BasicDataSource">

</data-source>

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.

5.3 Configuring your application for modules

Very little is required in order to start taking advantage of the Struts module feature. Just go through the following steps:

Prepare a configuration file for each module.

Inform the controller of your module.

Use Actions to refer to your pages.

5.3.1 Module Configuration Files

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.

5.3.2 Informing the Controller

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:

...

<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>

...

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.

5.3.3 Switching Modules

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:

...

<action-mappings>

<action path="/toModule"

type="org.apache.struts.actions.SwitchAction"/>

...

</action-mappings>

...

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:

<global-forwards>

<forward name="toModuleB"

contextRelative="true"

path="/moduleB/index.do"

redirect="true"/>

...

</global-forwards>

You could do the same thing with a local forward declared in an ActionMapping:

<action-mappings>

<forward name="sUCcess"

contextRelative="true"

path="/moduleB/index.do"

redirect="true"/>

</action>

...

</action-mappings>

Or, you can use org.apache.struts.actions.SwitchAction:

<action-mappings>

<action path="/toModule"

type="org.apache.struts.actions.SwitchAction"/>

...

</action-mappings>

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:

<html:link module="moduleB" path="/index.do"/>

That's all there is to it! Happy module-switching!

5.4 The Web Application Deployment Descriptor

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.

5.4.1 Configure the ActionServlet Instance

Add an entry defining the action servlet itself, along with the appropriate initialization parameters. Such an entry might look like this:

<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>

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.

config - 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].