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:
- 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.
<!DOCTYPE struts PUBLIC
"-//Apache Software Foundation//DTD Struts Configuration 2.0//EN"
<constant name="struts.enable.DynamicMethodInvocation" value="false" />
<constant name="struts.devMode" value="true" />
<package name="roseindia" namespace="/roseindia" extends="struts-default">
<action name="HelloWorld" class="net.roseindia.Struts2HelloWorld">
<!-- Add actions here -->
<!-- Add packages here -->
The struts.xml file must confirm to the Struts 2 Document Type Definition (DTD)
The DTD provides information about thestructure 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.
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
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.
|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)|
? 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:
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
- be created by the framework's container and injected into internal framework objects, or
- 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.
|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)
<bean type="roseindia.net.ObjectFactory" name="factory" class="roseindia.net.MyObjectFactory" />
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:
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.
|name||yes||the name of the constant|
|value||yes||the value of the constant|
Constant Example (struts.xml)
<constant name="struts.devMode" value="true" />
Constant Example (struts.properties)
struts.devMode = true