Struts Configuration file - struts.xml

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:
  <struts>
  .....
  ......
  <include file="file1.xml"/>
  <include file="file2.xml"/>
  .....
  .....
  </struts>
    
• 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.

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 :

<!--
   Struts configuration DTD.
   Use the following DOCTYPE
   
   <!DOCTYPE struts PUBLIC 
	"-//Apache Software Foundation//DTD Struts Configuration 2.0//EN"
	"http://struts.apache.org/dtds/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 <struts> 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 <package  /> 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.

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 <include  /> 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:

<struts>

<include file="invoices-config.xml" />
<include file="admin-config.xml" />
<include file="reports-config.xml" />

</struts>

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.

<struts>

  <bean type="roseindia.net.ObjectFactory" name="factory" class="roseindia.net.MyObjectFactory" />
  
  ... 

</struts>

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.

<struts>

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

  ... 

</struts>

struts.devMode = true