The struts.xml File

The struts.xml file is an XML file with a struts root element. You define all the actions in your Struts application in this file. Here is the skeleton of a struts.xml file.

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

...

</struts>

The more important elements that can appear between <struts> and </struts> are discussed below.

The package Element

Since Struts has been designed with modularity in mind, actions are grouped into packages. Think packages as modules. A typical struts.xml file can have one or many packages:

<struts>

 <package name="package-1" namespace="namespace-1" extends="struts-default">

<action name="..."/> <action name="..."/>

...

</package>

<package name="package-2" namespace="namespace-2"> extends="struts-default">

<action name="..."/> <action name="..."/>

 ...

</package>

...

<package name="package-n" namespace="namespace-n"> extends="struts-default">

<action name="..."/> <action name="..."/>

...

 </package>

</struts>

A package element must have a name attribute. The namespace attribute is optional and if it is not present, the default value "/" is assumed.

 If the namespace attribute has a non-default value, the namespace must be added to the URI that invokes the actions in the package.

For example, the URI for invoking an action in a package with a default namespace is this: /context/actionName.action

To invoke an action in a package with a non-default namespace, you need this URI: /context/namespace/actionName.action

A package element almost always extends the struts-default package defined in struts-default.xml. By doing so, all actions in the package can use the result types and interceptors registered in struts-default.xml.

The include Element

A large application may have many packages. In order to make the struts.xml file easier to manage for a large application, it is advisable to divide it into smaller files and use include elements to reference the files. Each file would ideally include a package or related packages. A struts.xml file with multiple include elements would look like this.

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

 <include file="module-l.xml" />

 <include file="module-2.xml" />

...

<include file="module-n.xml" />

</struts>

The action Element

An action element is nested within a package element and represents an action. An action must have a name and you may choose any name for it. A good name reflects what the action does. For instance, an action that displays a form for entering a product's details may be called displayAddProductForm. By convention, you are encouraged to use the combination of a noun and a verb. For example, instead of calling an action displayAddProductForm, name it Product_input. However, it is totally up to you.

An action may or may not specify an action class. Therefore, an action element may be as simple as this.

<action name="MyAction">

An action that does not specify an action class will be given an instance of the default action class. The ActionSupport class is the default action class.

If an action has a non-default action class, however, you must specify the fully class name using the class attribute. In addition, you must also specify the name of the action method, which is the method in the action class that will be executed when the action is invoked.

 Here is an example.

<action name="Address_save" class="app.Address" method="save">

If the class attribute is present but the method attribute is not, execute is assumed for the method name. In other words, the following action elements mean the same thing.

<action name="Employee_save" class="app.Employee" method="execute"> <action name="Employee_save" class="app.Employee">

The result Element

<result> is a subelement of <action> and tells Struts where you want the action to be forwarded to. A result element corresponds to the return value of an action method. Because an action method may return different values for different situations, an action element may have several result elements, each of which corresponds to a possible return value of the action method. This is to say, if a method may return "success" and "input," you must have two result elements. The name attribute of the result element maps a result with a method return value.

If a method returns a value without a matching result element, Struts will try to find a matching result under the global-results element (See the discussion of this element below). If no corresponding result element is found under global-results, an exception will be thrown. For example, the following action element contains two result elements.

 <action name="Product_save" class="app.Product" method="save"> <result name="success" type="dispatcher"> /jsp/Confirm.jsp </result>

<result name="input" type="dispatcher"> /jsp/Product.jsp </result>

</action>

The first result will be executed if the action method save returns "success," in which case the Confirm.jsp page will be displayed. The second result will be executed if the method returns "input," in which case the Product.jsp page will be sent to the browser.

By the way, the type attribute of a result element specifies the result type. The value of the type attribute must be a result type that is registered in the containing package or a parent package extended by the containing package. Assuming that the action Product_save is in a package that extends struts-default, it is safe to use a Dispatcher result for this action because the Dispatcher result type is defined in struts-default. If you omit the name attribute in a result element, "success" is implied. In addition, if the type attribute is not present, the default result type Dispatcher is assumed. Therefore, these two result elements are the same.

<result name="success" type="dispatcher">/jsp/Confirm.jsp</result> <result>/jsp/Confirm.jsp</result>

 An alternative syntax that employs the param element exists for the Dispatcher result element. In this case, the parameter name to be used with the param element is location. In other words, this result element

<result>/test.jsp</result>

is the same as this:

 <result> <param name="location">/test.jsp</param> </result>

The global-results Element

A package element may contain a global-results element that contains results that act as general results. If an action cannot find a matching result under its action declaration, it will search the global-results element, if any.

Here is an example of the global-results element.

<global-results>

 <result name="error">/jsp/GenericErrorPage.jsp</result>

<result name="login" type="redirect-action">Login</result> </global-results>

The Interceptor-related Elements

There are five interceptor-related elements that may appear in a struts.xml file: interceptors, interceptor, interceptor-ref, interceptor-stack, and default-interceptor-ref. They are explained in this section.

An action element must contain a list of interceptors that will process the action object. Before you can use an interceptor, however, you have to register it using an interceptor element under <interceptors>. Interceptors defined in a package can be used by all actions in the package. For example, the following package element registers two interceptors, validation and logger.

<package name="main" extends="struts-default">

<interceptors>

<interceptor name="validation" class="..."/>

<interceptor name="logger" class="..."/>

</interceptors>

 </package>

To apply an interceptor to an action, use the interceptor-ref element under the action element of that action. For instance, the following configuration registers four interceptors and apply them to the Product_delete and Product_save actions.

 <package name="main" extends="struts-default">

 <interceptors>

 <interceptor name="alias" class="..."/>

<interceptor name="i18n" class="..."/>

<interceptor name="validation" class="..."/>

<interceptor name="logger" class="..."/>

</interceptors>

 <action name="Product_delete" class="...">

<interceptor-ref name="alias"/>

<interceptor-ref name="i18n"/>

<interceptor-ref name="validation"/>

<interceptor-ref name="logger"/>

 <result>/jsp/main.jsp</result>

</action> <action name="Product_save" class="...">

<interceptor-ref name="alias"/>

<interceptor-ref name="i18n"/>

<interceptor-ref name="validation"/>

 <interceptor-ref name="logger"/>

 <result name="input">/jsp/Product.jsp</result> <result>/jsp/ProductDetails.jsp</result>

 </action>

 </package>

With these settings every time the Product_delete or Product_save actions are invoked, the four interceptors will be given a chance to process the actions. Note that the order of appearance of the interceptor-ref element is important as it determines the order of invocation of registered interceptors for that action. In this example, the alias interceptor will be invoked first, followed by the i18n interceptor, the validation interceptor, and the logger interceptor.

With most Struts application having multiple action elements, repeating the list of interceptors for each action can be a daunting task. In order to alleviate this problem, Struts allows you to create interceptor stacks that group required interceptors. Instead of referencing interceptors from within each action element, you can reference the interceptor stack instead.

For instance, six interceptors are often used in the following orders: exception, servletConfig, prepare, checkbox, params, and conversionError. Rather than referencing them again and again in your action declarations, you can create an interceptor stack like this:

 <interceptor-stack name="basicStack">

<interceptor-ref name="exception"/>

<interceptor-ref name="servlet-config"/>

<interceptor-ref name="prepare"/>

<interceptor-ref name="checkbox"/>

<interceptor-ref name="params"/>

 <interceptor-ref name="conversionError"/>

</interceptor-stack>

To use these interceptors, you just need to reference the stack:

<action name="..." class="...">

 <interceptor-ref name="basicStack"/>

 <result name="input">/jsp/Product.jsp</result> <result>/jsp/ProductDetails.jsp</result>

 </action>

The struts-default package defines several stacks. In addition, it defines a default-interceptor-ref element that specifies the default interceptor or interceptor stack to use if no interceptor is defined for an action:

 <default-interceptor-ref name="defaultStack"/>

If an action needs a combination of other interceptors and the default stack, you must redefine the default stack as the default-interceptor-ref element will be ignored if an interceptor element can be found within an action element.

The param Element

The param element can be nested within another element such as action, result-type, and interceptor to pass a value to the enclosing object.

The param element has a name attribute that specifies the name of the parameter. The format is as follows:

<param name="property">value</param>

Used within an action element, param can be used to set an action property. For example, the following param element sets the siteId property of the action.

<action name="customer" class="...">

<param name="siteId">california01</param>

</action>

And the following param element sets the excludeMethod of the validation interceptor-ref:

 <interceptor-ref name="validation">

 <param name="excludeMethods">input,back,cancel</param> </interceptor-ref>

The excludeMethods parameter is used to exclude certain methods from invoking the enclosing interceptor.

The constant Element

In addition to the struts.xml file, you can have a struts.properties file. You create the latter if you need to override one or more key/value pairs defined in the default.properties file, which is included in the struts2-core-VERSION.jar file. Most of the time you won't need a struts.properties file as the default.properties file is good enough. Besides, you can override a setting in the default.properties file using the constant element in the struts.xml file.

The constant element has a name attribute and a value attribute. For example, the struts.devMode setting determines whether or not the Struts application is in development mode. By default, the value is false, meaning the application is not in development mode. The following constant element sets struts.devMode to true.

<struts>

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

</struts>

 

Posted in: Struts 2