|Home > Guides > Core Developers Guide > Configuration Elements > Action Configuration|
The action mappings are the basic "unit-of-work" in the framework. Essentially, the action maps an identifier to a handler class. When a request matches the action's name, the framework uses the mapping to determine how to process the request.
The action mapping can specify a set of result types, a set of exception handlers, and an interceptor stack. Only the
name attribute is required. The other attributes can also be provided at package scope.
When using Convention Plugin the action mapping can be configured with annotations:
In a web application, the
name attribute is matched as part of the location requested by a browser (or other HTTP client). The framework will drop the host and application name and the extension and match what's in the middle: the action name. So, a request for
http://www.planetstruts.org/struts2-mailreader/Welcome.action will map to the
Within an application a link to an action is usually generated by a Struts Tag. The tag can specify the action by name, and the framework will render the default extension and anything else that is needed. Forms may also submit directly to a Struts Action name (rather than a "raw" URI).
Action Names With Slashes
If your action names have slashes in them (for example,
<action name="admin/home" class="tutorial.Admin"/>) you need to specifically allow slashes in your action names via a constant in the
struts.xml file by specifying
<constant name="struts.enable.SlashesInActionNames" value="true"/>. See JIRA Issue WW-1383 for discussion as there are side effects to setting this property to
Action Names with Dots and Dashes
Although action naming is pretty flexible, one should pay attention when using dots (eg.
create.user) and/or dashes (eg.
createUser) or underscores (eg.
The default entry method to the handler class is defined by the Action interface.
Implementing the Action interface is optional. If Action is not implemented, the framework will use reflection to look for an
Sometimes, developers like to create more than one entry point to an Action. For example, in the case of a data-access Action, a developer might want separate entry-points for
delete. A different entry point can be specified by the
If there is no
execute method and no other method specified in the configuration the framework will throw an exception.
Convention Plugin allows that by annotating methods:
Many times, a set of action mappings will share a common pattern. For example, all your
edit actions might start with the word "edit", and call the
edit method on the Action class. The
delete actions might use the same pattern, but call the
delete method instead.
Rather than code a separate mapping for each action class that uses this pattern, you can write it once as a wildcard mapping.
Here, a reference to "editCrud" will call the
edit method on an instance of the Crud Action class. Likewise, a reference to "deleteCrud" will call the
delete method instead.
Another common approach is to postfix the method name and set it off with an exclamation point (aka "bang"), underscore, or other special character.
To use a postfix wildcard, just move the asterisk and add an underscore.
From the framework's perspective, a wildcard mapping creates a new "virtual" mapping with all the same attributes as a conventional, static mapping. As a result, you can use the expanded wildcard name as the name of validation, type conversion, and message resource files, just as if it were an Action name (which it is!).
If Wildcard Method mapping uses a "!" in the action name, the Wildcard Method will overlap with another flexible approach to mapping, Dynamic Method Invocation. To use action names that include the "!" character, set
FALSE in the application configuration.
There's a feature embedded in WebWork 2 that lets the "!" (bang) character invoke a method other than
execute. In WebWork, it doesn't really have a name. During the S2 discussions, we coined the term "dynamic method invocation" to describe how WW/S2 use the bang notation.
Dynamic Method Invocation (DMI) will use the string following a "!" character in an action name as the name of a method to invoke (instead of
execute). A reference to "
Category!create.action", says to use the "Category" action mapping, but call the
create method instead.
Another way to use DMI is to provide HTTP parameters prefixed with "
method:". For example in the URL it could be "
Category.action?method:create=foo", the parameter value is ignored. In POST-Requests that can be used e.g. with a hidden parameter (
<s:hidden name="method:create" value="foo" />) or along with a button (
<s:submit method="create" />).
For Struts 2, we added a switch to disable DMI for two reasons. First, DMI can cause security issues if POJO actions are used. Second, DMI overlaps with the Wildcard Method feature that we brought over from Struts 1 (and from Cocoon before that). If you have security concerns, or would like to use the "!" character with Wildcard Method actions, then set
FALSE in the application configuration.
The framework does support DMI, just like WebWork 2, but there are problems with way DMI is implemented. Essentially, the code scans the action name for a "!" character, and finding one, tricks the framework into invoking the other method instead of
execute. The other method is invoked, but it uses the same configuration as the
execute method, including validations. The framework "believes" it is invoking the
Category action with the
The Wildcard Method feature is implemented differently. When a Wildcard Method action is invoked, the framework acts as if the matching action had been hardcoded in the configuration. The framework "believes" it's executing the action
Category!create and "knows" it is executing the
create method of the corresponding Action class. Accordingly, we can add for a Wildcard Method action mapping its own validations, message resources, and type converters, just like a conventional action mapping. For this reason, the Wildcard Method is preferred.
In Struts 2.3, an option was added to restrict the methods that DMI can invoke. First, set the attribute
strict-method-invocation="true" on your
<package> element. This tells Struts to reject any method that is not explicitly allowed via either the
method attribute (including wildcards) or the
<allowed-methods> tag. Then specify
<allowed-methods> as a comma-separated list of method names in your
<action>. (If you specify a
method attribute for your action, you do not need to list it in
Note that you can specify
<allowed-methods> even without
strict-method-invocation. This restricts access only for the specific actions that have
Strict DMI doesn't work with the Convention Plugin yet!
If the class attribute in an action mapping is left blank, the
com.opensymphony.xwork2.ActionSupport class is used as a default.
The ActionSupport class has an
execute method that returns "success" and an
input method that returns "input".
To specify a different class as the default Action class, set the
default-class-ref package attribute.
For more about using wildcards, see Wildcard Mappings.
A good practice is to link to actions rather than pages. Linking to actions encapsulates which server page renders, and ensures that an Action class can fire before a page renders.
Another common workflow stategy is to first render a page using an alternate method, like
input and then have it submit back to the default
Using these two strategies together creates an opportunity to use a "post-back" form that doesn't specify an action. The form simply submits back to the action that created it.
Usually, if an action is requested, and the framework can't map the request to an action name, the result will be the usual "404 - Page not found" error. But, if you would prefer that an omnibus action handle any unmatched requests, you can specify a default action. If no other action matches, the default action is used instead.
There are no special requirements for the default action. Each package can have its own default action, but there should only be one default action per namespace.
One to a Namespace
The default action features should be set up so that there is only one default action per namespace. If you have multiple packages declaring a default action with the same namespace, there is no guarantee which action will be the default.
Using wildcards is another approach to default actions. A wildcard action at the end of the configuration can be used to catch unmatched references.
When a new action is needed, just add a stub page.
It's important to put a "catchall" wildcard mapping like this at the end of your configuration so it won't attempt to map every request!