Struts2: Struts Configuration file

In this section we will introduce you to the struts.xml file. This section explains you how best you can use the struts.xml file for you big projects.

The struts.xml File

The Struts 2 Framework uses a configuration file (struts.xml) to initialize its own resources. These resources include:

* Interceptors that can preprocess and postprocess a request
* Action classes that can call business logic and data access code
* Results that can prepare views using JavaServer Pages, Velocity and FreeMarker templates

At runtime, there is a single configuration for an application. Prior to runtime, the configuration is defined through one or more XML documents, including the default struts.xml document. There are several elements that can be configured, including packages, namespaces, includes, actions, results, interceptors, and exceptions.

The struts.xml file is the core configuration file for the framework and it should be present in the class path of your web application. Features of struts 2 configuration file:

* The struts.xml file allows to break big struts.xml file into small files and configuration files to be included as needed. Here is the example:

* You can even place struts-plugin.xml file in the JAR, and it will be automatically plugged into the application. This helps the programmers to develop self-configured components.

* If you want to use the frameworks such as Freemaker and Velocity modules, then the templates can also be loaded from classpath. This enables the developer to package entire module just in single JAR file.

Structure of the struts.xml file

In the last section we developed and tested the Hello World application. Here is the sample struts.xml file from the last example.

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE struts PUBLIC "-//Apache Software Foundation//DTD Struts Configuration
2.0//EN" "http://struts.apache.org/dtds/struts-2.0.dtd">

<struts>

<constant name="struts.enable.DynamicMethodInvocation"
value="false" />

<constant name="struts.devMode" value="true" />

<package name="jitendra" namespace="/jitendra" extends="struts-default">

<action name="HelloWorld" class="net.jitendra.Struts2HelloWorld">

<result>/pages/HelloWorld.jsp</result>

</action>



</package>



</struts>

The struts.xml file must confirm to the Struts 2 Document Type Definition (DTD)

The DTD provides information about the structure and the elements that the struts.xml file should have.
Here is the Struts 2.0 DTD :

<!ELEMENT struts (package|include|bean|constant)*>

<!ELEMENT package (result-types?, interceptors?,
default-interceptor-ref?, default-action-ref?, global-results?,
global-exception-mappings?, action*)>

<!ATTLIST package name CDATA #REQUIRED
extends CDATA #IMPLIED
namespace CDATA #IMPLIED
abstract CDATA #IMPLIED
externalReferenceResolver NMTOKEN #IMPLIED>

<!ELEMENT result-types (result-type+)>

<!ELEMENT result-type (param*)>

<!ATTLIST result-type name CDATA #REQUIRED
class CDATA #REQUIRED
default (true|false) "false">

<!ELEMENT interceptors (interceptor|interceptor-stack)+>

<!ELEMENT interceptor (param*)>

<!ATTLIST interceptor name CDATA #REQUIRED
class CDATA #REQUIRED>

<!ELEMENT interceptor-stack (interceptor-ref+)>

<!ATTLIST interceptor-stack name CDATA #REQUIRED>

<!ELEMENT interceptor-ref (param*)>

<!ATTLIST interceptor-ref name CDATA #REQUIRED>

<!ELEMENT default-interceptor-ref (param*)>

<!ATTLIST default-interceptor-ref name CDATA #REQUIRED>

<!ELEMENT default-action-ref (param*)>

<!ATTLIST default-action-ref name CDATA #REQUIRED>

<!ELEMENT global-results (result+)>

<!ELEMENT global-exception-mappings (exception-mapping+)>

<!ELEMENT action (param|result|interceptor-ref|exception-mapping)*>

<!ATTLIST action name CDATA #REQUIRED class CDATA #IMPLIED
method CDATA #IMPLIED
converter CDATA #IMPLIED>

<!ELEMENT param (#PCDATA)>

<!ATTLIST param name CDATA #REQUIRED>

<!ELEMENT result (#PCDATA|param)*>

<!ATTLIST result name CDATA #IMPLIED
type CDATA #IMPLIED>

<!ELEMENT exception-mapping (#PCDATA|param)*>

<!ATTLIST exception-mapping name CDATA #IMPLIED
exception CDATA #REQUIRED
result CDATA #REQUIRED>

<!ELEMENT include (#PCDATA)>

<!ATTLIST include file CDATA #REQUIRED>

<!ELEMENT bean (#PCDATA)>

<!ATTLIST bean type CDATA #IMPLIED name CDATA #IMPLIED
class CDATA #REQUIRED scope CDATA #IMPLIED
static CDATA #IMPLIED
optional CDATA #IMPLIED
>

<!ELEMENT constant (#PCDATA)>

<!ATTLIST constant name CDATA #REQUIRED value CDATA #REQUIRED >

It is possible to remove the “struts.xml” file from your application completely if the functionality of your application does not depends on it. There are few configurations that can be handled alternatively such as annotations, “web.xml” startup parameters, and alternate URL mapping schemes. Still, there are few configurations that always need the “struts.xml” file like the global results, exception handling, and the custom interceptor stacks.

Exploring struts.xml

The tag is the root tag for the struts.xml. It may contain the following tags : package, include, bean and constant.

1. The Package Tag :

Packages are a way to group actions, results, result types, interceptors, and interceptor-stacks into a logical configuration unit. Conceptually, packages are similar to objects in that they can be extended and have individual parts that can be overridden by "sub" packages.

The tag is used to group together configurations that share common attributes such as interceptor stacks or URL namespaces. It may also be useful to organizationally separate functions, which may be further separated into different configuration files.

The package element has one required attribute, name, which acts as the key for later reference to the package. The extends attribute is optional and allows one package to inherit the configuration of one or more previous packages - including all interceptor, interceptor-stack, and action configurations.

Note that the configuration file is processed sequentially down the document, so the package referenced by an "extends" should be defined above the package which extends it.

The optional abstract attribute creates a base package that can omit the action configuration.

Attribute	Required	Description
name	yes	key for other packages to reference
extends	no	inherits package behavior of the package it extends
namespace	no	provides a mapping from the URL to the package.
abstract	no	declares package to be abstract (no action configurations required in package)

1. name – unique name is given for a package.
2. extends – the name of a package that this package will extend; all configuration information (including action configurations) from the extended package will be available in the new package, under the new namespace.
3. namespace – the namespace provides a mapping from the URL to the package. i.e. for two different packages, with namespace attributes defined as “pack1” and “pack2”, the URLs would be something like “/webApp/pack1/my.action” and “/webApp/pack2/my.action”
4. abstract – if this attribute value is “true” the package is truly a configuration grouping and actions configured will not be accessible via the package name. It is important to make sure you are extending the correct parent package so that the necessary pre-configured features will be available to you.

2. The Include Tag:

The tag is used to modularize a Struts2 application that needs to include other configuration files. It contains only one attribute “file” that provides the name of the xml file to be included. This file has exactly the same structure as the “struts.xml” configuration file. For example, to break a configuration file of a finance application, you might choose to group together the invoices, admin, report configurations etc into separate files:

While including files, order is important. The information from the included file will be available from the point that the include tag is placed in the file.

There are some files that are included implicitly. These are the “strutsdefault.xml” and the “struts-plugin.xml” files. Both contains default configurations for result types, interceptors, interceptor stacks, packages as well as configuration information for the web application execution environment (which can also configured in the “struts.properties” file). The difference is that “struts-default.xml” provides the core configuration for Struts2, where “struts-plugin.xml” provides configurations for a particular plug-in. Each plug-in JAR file should contain a “struts-plugin.xml” file, all of which are loaded during startup.

3. The Bean Tag

Most applications won't need to extend the Bean Configuration. The bean element requires the class attribute which specifies the Java class to be created or manipulated. A bean can either

1. be created by the framework's container and injected into internal framework objects, or

2. have values injected to its static methods

The first use, object injection, is generally accompanied by the type attribute, which tells the container that which interface this object implements.

The second use, value injection, is good for allowing objects not created by the container to receive framework constants. Objects using value inject must define the the static attribute.

Attribute	Required	Description
class	yes	the name of the bean class
type	no	the primary Java interface this class implements
name	no	the unique name of this bean; must be unique among other beans that specify the same `type`
scope	no	the scope of the bean; must be either `default`, `singleton`, `request`, `session`, `thread`
static	no	whether to inject static methods or not; shouldn't be `true` when the `type` is specified
optional	no	whether the bean is optional or not

Bean Example (struts.xml)

4. The Constant Tag

There are two key roles for constants.

1. They are used to override settings like the maximum file upload size or whether the Struts framework should be in devMode(= development mode) or not.

2. They specify which Bean should be chosen, among multiple implementations of a given type.

Constants can be declared in multiple files. By default, constants are searched for in the following order, allowing for subsequent files to override by the previous ones:

* struts-default.xml

* struts-plugin.xml

* struts.xml

* struts.properties

* web.xml

The struts.properties file is provided for backward-compatiblity with WebWork. In the struts.properties file, each entry is treated as a constant. In the web.xml file, any FilterDispatcher initialization parameters are loaded as constants.

In the various XML variants, the constant element has two required attributes : name and value.