How to Configure Struts 2 Actions Results and Interceptors
Configure packages, namespaces, actions, results and interceptor stacks in struts.xml, and use wildcards without opening dangerous method calls.

The configuration file is where a Struts 2 application keeps most of its complexity, and a large struts.xml is the part new team members dread. It reads easily once you know the four building blocks: packages, actions, results and interceptors. This post shows each with an example, covers the settings that matter for security, and ends with the one mistake that costs the most. The request path that connects them is explained in what Struts 2 is.
Packages and namespaces
<struts>
<package name="shop" namespace="/shop" extends="struts-default">
<!-- actions here are served under /shop/ -->
</package>
</struts>extends="struts-default" inherits the standard result types and the default interceptor stack from the framework. Without it, your package has no result types at all, and every action fails with a confusing error about an unknown result type. The namespace is part of the URL: an action named list in this package answers at /shop/list.action. A request whose namespace does not match any package falls back to the root namespace, and a mismatch there is the usual reason for "There is no Action mapped for namespace".
Actions and methods
<action name="list" class="dev.javahacks.web.ProductAction" method="list">
<result>/products.jsp</result>
</action>
<action name="save" class="dev.javahacks.web.ProductAction" method="save">
<result type="redirectAction">list</result>
<result name="input">/product-form.jsp</result>
</action>The method attribute names the method to call, and defaults to execute. A <result> without a name is the success result. Several actions may share one class and call different methods, which keeps related code together at the cost of a bigger class. The input result in the second action is what validation errors produce, so the form is shown again with its messages. That mechanism is covered in validating input.
Result types
| Type | Use |
|---|---|
dispatcher (the default) | Forward to a JSP or template |
redirect | HTTP redirect to a URL |
redirectAction | Redirect to another action, avoiding resubmission |
chain | Run another action within the same request |
stream | Send an input stream, for downloads |
json | JSON output, with the JSON plugin |
Use redirectAction after a successful save, so a browser refresh does not repeat the form post. That is the Post/Redirect/Get pattern, and skipping it is how customers end up with duplicate orders. A result name that the action returns and the configuration does not define raises the no-result error.
Global results and exceptions
<global-results>
<result name="login" type="redirectAction">login</result>
<result name="error">/error.jsp</result>
</global-results>
<global-exception-mappings>
<exception-mapping exception="java.lang.Exception" result="error" />
</global-exception-mappings>An exception mapping converts any exception thrown from an action into the error result, which keeps stack traces away from users. Be sure the exception is logged before it is mapped; the exception interceptor has a logEnabled parameter for that. Global results are looked up after the action's own, so a local result with the same name wins. That lets one action override the shared login redirect, which is occasionally what you want and occasionally a bug.
Interceptor stacks
Interceptors wrap the action, and the default stack covers parameter binding, validation, file upload and workflow. To add your own for a group of actions:
<package name="secure" extends="struts-default">
<interceptors>
<interceptor name="auth" class="dev.javahacks.web.AuthInterceptor" />
<interceptor-stack name="secureStack">
<interceptor-ref name="auth" />
<interceptor-ref name="defaultStack" />
</interceptor-stack>
</interceptors>
<default-interceptor-ref name="secureStack" />
</package>Order is behaviour. Here auth runs first, so an unauthenticated user never reaches parameter binding, and the framework never writes request values into an action that the user may not call. Placing your interceptor after defaultStack would reverse that. The built-in interceptors are described in the Struts interceptors documentation.
Wildcards
<action name="*-product" class="dev.javahacks.web.ProductAction" method="{1}">
<result>/product-{1}.jsp</result>
</action>edit-product calls edit(), and delete-product calls delete(). That is concise, and it makes every public method of the class callable from the outside by name. The method name is part of the URL, so a method added to the class next year, say purge(), becomes reachable the day it is written. Restrict the names:
<action name="*-product" class="dev.javahacks.web.ProductAction" method="{1}"
allowed-methods="edit,delete,save">Keep allowed-methods whenever {1} is used in method. Also leave dynamic method invocation off, which is the default in current versions; the constant struts.enable.DynamicMethodInvocation should stay false. The history of attacks that used these doors is in hardening Struts 2.
Splitting a large file
One file with hundreds of actions is a merge-conflict machine. Split by feature and include the parts:
<struts>
<include file="struts-shop.xml" />
<include file="struts-admin.xml" />
</struts>Each included file is a complete <struts> document with its own packages. Give each feature its own package and namespace, and the URL layout mirrors the file layout.
Reading the errors the configuration produces
Most configuration mistakes announce themselves with one of a few messages, and each points at a specific part of the file.
| Message | What it usually means |
|---|---|
| There is no Action mapped for namespace [/shop] and action name [list] | The package namespace or the action name does not match the URL |
| No result defined for action and result input | The action returned input and no <result name="input"> exists |
| Unable to load configuration | The XML is malformed, or a class named in it is missing |
| Dispatcher: Could not find action or result | A package does not extend struts-default, so the result type is unknown |
| The requested method is not allowed | A wildcard method is not listed in allowed-methods |
Turn on development mode while you work, with <constant name="struts.devMode" value="true" />. It reloads the configuration on change and prints much more detail in errors. Turn it off for production: it exposes internals in error pages and slows every request.
When an action does not behave as expected, look at which interceptors ran before reading its code. The order in the stack explains most surprises: a value that arrives empty was usually not bound because an earlier interceptor stopped the request, and a validation message that never shows up usually means the workflow interceptor is missing from a custom stack. If you build a custom stack by listing interceptors one by one, you will forget one. Start from defaultStack and add yours around it, as the example above does.
A last habit pays for itself. Keep the file readable by grouping actions by feature, with a short comment above each package saying which part of the application it serves. A configuration file is read far more often than it is written, and the next developer arrives with a stack trace and no context.
Annotations instead of XML
The Convention plugin derives actions from class names and package layout, so a class ProductAction in a package ending in .action is reachable without any XML. It removes the boilerplate and spreads the URL space across the code base. A project with hundreds of actions benefits from picking one style and enforcing it; mixing the two makes it hard to answer where a URL is defined. The struts.xml reference lists every element and attribute.


