THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
The default Interceptor stack is designed to serve the needs of most applications. Most applications will not need to add Interceptors or change the Interceptor stack.
Many Actions share common concerns. Some Actions need input validated. Other Actions may need a file upload to be pre-processed. Another Action might need protection from a double submit. Many Actions need drop-down lists and other controls pre-populated before the page displays.
The framework makes it easy to share solutions to these concerns using an "Interceptor" strategy. When you request a resource that maps to an "action"
[Interceptors can execute code before and after an Action is invoked. Most of the framework's core features are implemented as Interceptors. Object population and type conversion, validation, file uploads, double-submit guards, component setup, and more, are all implemented with Interceptors.
Interceptors can be configured on a per-action basis. Custom Interceptors can be mixed-and-matched with the Interceptors bundled with the framework. Interceptors "set the stage" for the Action classes, doing much of the "heavy lifting" before the Action executes. The Interceptor strategy promotes reusability and simplicity.
When you access request an "action" URI, the framework invokes the Action object. But, before the Action is executed, the invocation can be intercepted by another object. (Hence the name. ) After the Action executes, the invocation can could be intercepted again.
Action Lifecyle |
|---|
|
Interceptors can interrupt the request processing, so that the Action never executes. Interceptors can also change the state of an Action before it executes. The Interceptors are defined in a stack that specifies the execution order. In some cases, the order of the Interceptors on the stack can be very important.
Configuring Interceptors
...
Unsurprisingly, we call these objects "Interceptors."
2
Understanding Interceptors
Interceptors can execute code before and after an Action is invoked. Most of the framework's core functionality is implemented as Interceptors. Features like double-submit guards, type conversion, object population, validation, file upload, page preparation, and more, are all implemented with the help of Interceptors. Each and every Interceptor is pluggable, so you can decide exactly which features an Action needs to support.
Interceptors can be configured on a per-action basis. Your own custom Interceptors can be mixed-and-matched with the Interceptors bundled with the framework. Interceptors "set the stage" for the Action classes, doing much of the "heavy lifting" before the Action executes.
Action Lifecyle |
|---|
|
In some cases, an Interceptor might keep an Action from firing, because of a double-submit or because validation failed. Interceptors can also change the state of an Action before it executes.
The Interceptors are defined in a stack that specifies the execution order. In some cases, the order of the Interceptors on the stack can be very important.
Configuring Interceptors
...
Stacking Interceptors
With most web applications, you'll we find yourself ourselves wanting to apply the same set of interceptors Interceptors over and over again. Rather than declare interceptor-refs for each action, you reiterate the same list of Interceptors, we can bundle these interceptors Interceptors together using an interceptor stackInterceptor Stack.
...
Looking inside actionstruts-default.xml, we can see how it's done,
...
.
...
...
<!DOCTYPE xwork PUBLIC "-//OpenSymphony Group//XWork 1.0//EN" "http://www.opensymphony.com/xwork/xwork-1.1.dtd">
<!-- // START SNIPPET: webwork-default -->
<xwork>
<package name="action-default">
<result-types>
<result-type name="chain" class="com.opensymphony.xwork.ActionChainResult"/>
<result-type name="dispatcher" class="org.apache.struts.action2.dispatcher.ServletDispatcherResult"
default="true"/>
<result-type name="freemarker" class="org.apache.struts.action2.views.freemarker.FreemarkerResult"/>
<result-type name="httpheader" class="org.apache.struts.action2.dispatcher.HttpHeaderResult"/>
<result-type name="jasper" class="org.apache.struts.action2.views.jasperreports.JasperReportsResult"/>
<result-type name="redirect" class="org.apache.struts.action2.dispatcher.ServletRedirectResult"/>
<result-type name="redirect-action"
class="org.apache.struts.action2.dispatcher.ServletActionRedirectResult"/>
<result-type name="stream" class="org.apache.struts.action2.dispatcher.StreamResult"/>
<result-type name="velocity" class="org.apache.struts.action2.dispatcher.VelocityResult"/>
<result-type name="xslt" class="org.apache.struts.action2.views.xslt.XSLTResult"/>
</result-types>
<interceptors>
<interceptor name="alias" class="com.opensymphony.xwork.interceptor.AliasInterceptor"/>
<interceptor name="autowiring"
class="com.opensymphony.xwork.spring.interceptor.ActionAutowiringInterceptor"/>
<interceptor name="chain" class="com.opensymphony.xwork.interceptor.ChainingInterceptor"/>
<interceptor name="component" class="com.opensymphony.xwork.interceptor.component.ComponentInterceptor"/>
<interceptor name="conversionError"
class="org.apache.struts.action2.interceptor.WebWorkConversionErrorInterceptor"/>
<interceptor name="external-ref" class="com.opensymphony.xwork.interceptor.ExternalReferencesInterceptor"/>
<interceptor name="execAndWait" class="corg.apache.struts.action2.interceptor.ExecuteAndWaitInterceptor"/>
<interceptor name="exception" class="com.opensymphony.xwork.interceptor.ExceptionMappingInterceptor"/>
<interceptor name="fileUpload" class="com.opensymphony.webwork.interceptor.FileUploadInterceptor"/>
<interceptor name="i18n" class="com.opensymphony.xwork.interceptor.I18nInterceptor"/>
<interceptor name="logger" class="com.opensymphony.xwork.interceptor.LoggingInterceptor"/>
<interceptor name="model-driven" class="com.opensymphony.xwork.interceptor.ModelDrivenInterceptor"/>
<interceptor name="params" class="com.opensymphony.xwork.interceptor.ParametersInterceptor"/>
<interceptor name="prepare" class="com.opensymphony.xwork.interceptor.PrepareInterceptor"/>
<interceptor name="static-params" class="com.opensymphony.xwork.interceptor.StaticParametersInterceptor"/>
<interceptor name="servlet-config" class="org.apache.struts.action2.interceptor.ServletConfigInterceptor"/>
<interceptor name="sessionAutowiring"
class="org.apache.struts.action2.spring.interceptor.SessionContextAutowiringInterceptor"/>
<interceptor name="timer" class="com.opensymphony.xwork.interceptor.TimerInterceptor"/>
<interceptor name="token" class="com.opensymphony.webwork.interceptor.TokenInterceptor"/>
<interceptor name="token-session"
class="com.opensymphony.webwork.interceptor.TokenSessionStoreInterceptor"/>
<interceptor name="validation" class="com.opensymphony.xwork.validator.ValidationInterceptor"/>
<interceptor name="workflow" class="com.opensymphony.xwork.interceptor.DefaultWorkflowInterceptor"/>
<!-- Basic stack -->
<interceptor-stack name="basicStack">
<interceptor-ref name="exception"/>
<interceptor-ref name="servlet-config"/>
<interceptor-ref name="prepare"/>
<interceptor-ref name="static-params"/>
<interceptor-ref name="params"/>
<interceptor-ref name="conversionError"/>
</interceptor-stack>
<!-- Sample validation and workflow stack -->
<interceptor-stack name="validationWorkflowStack">
<interceptor-ref name="basicStack"/>
<interceptor-ref name="validation"/>
<interceptor-ref name="workflow"/>
</interceptor-stack>
<!-- Sample file upload stack -->
<interceptor-stack name="fileUploadStack">
<interceptor-ref name="fileUpload"/>
<interceptor-ref name="basicStack"/>
</interceptor-stack>
<!-- Sample WebWork Inversion of Control stack
Note: WebWork's IoC is deprecated - please
look at alternatives such as Sprint -->
<interceptor-stack name="componentStack">
<interceptor-ref name="component"/>
<interceptor-ref name="basicStack"/>
</interceptor-stack>
<!-- Sample model-driven stack -->
<interceptor-stack name="modelDrivenStack">
<interceptor-ref name="model-driven"/>
<interceptor-ref name="basicStack"/>
</interceptor-stack>
<!-- Sample action chaining stack -->
<interceptor-stack name="chainStack">
<interceptor-ref name="chain"/>
<interceptor-ref name="basicStack"/>
</interceptor-stack>
<!-- Sample i18n stack -->
<interceptor-stack name="chainStack">
<interceptor-ref name="i18n"/>
<interceptor-ref name="basicStack"/>
</interceptor-stack>
<!-- Sample execute and wait stack.
Note: execAndWait should always be the *last* interceptor. -->
<interceptor-stack name="executeAndWaitStack">
<interceptor-ref name="basicStack"/>
<interceptor-ref name="execAndWait"/>
</interceptor-stack>
<!-- A complete stack with all the common interceptors in place.
Generally, this stack should be the one you use, though it
may process additional stuff you don't need, which could
lead to some performance problems. Also, the ordering can be
switched around (ex: if you wish to have your components
before prepare() is called, you'd need to move the component
interceptor up -->
<interceptor-stack name="defaultStack">
<interceptor-ref name="exception"/>
<interceptor-ref name="alias"/>
<interceptor-ref name="prepare"/>
<interceptor-ref name="servlet-config"/>
<interceptor-ref name="i18n"/>
<interceptor-ref name="chain"/>
<interceptor-ref name="model-driven"/>
<interceptor-ref name="fileUpload"/>
<interceptor-ref name="static-params"/>
<interceptor-ref name="params"/>
<interceptor-ref name="conversionError"/>
<interceptor-ref name="validation"/>
<interceptor-ref name="workflow"/>
</interceptor-stack>
<!-- The completeStack is here for backwards compatibility for
applications that still refer to the defaultStack by the
old name -->
<interceptor-stack name="completeStack">
<interceptor-ref name="defaultStack"/>
</interceptor-stack>
</interceptors>
<default-interceptor-ref name="defaultStack"/>
</package>
</xwork>
<!-- // END SNIPPET: webwork-default -->
Since we included action-default.xml in our action.xml, all the predefined interceptors and stacks are available for us to use in our actions.
timer | clocks how long the action (including nested interceptors and view) takes to execute |
logger | logs the action being executed |
chain | makes the previous action's properties available to the current action. Used to make action chaining (reference: Result Types) |
static-params: sets the parameters defined in | |
params | sets the request (POST and GET) parameters onto the action class. We have seen an example of this in TODO |
*model-driven | if the action implements |
component | enables and makes registered components available to the actions. (reference: IoC & Components) |
token | checks for valid token presence in action, prevents duplicate form submission |
token-session | same as above, but storing the submitted data in session when handed an invalid token; |
validation | performs validation using the validators defined in { |
workflow | calls the validate method in your action class. If action errors created then it returns the |
servlet-config | give access to |
prepare | allows you to programmatic access to your Action class before the parameters are set on it. |
conversionError | Adds field errors if any type-conversion errors occurred\ |
execAndWait | Spawns a separate thread to execute the action |
fileUpload | Sets uploaded files as action files (File objects) |
In addition to the prepackaged Interceptors, action-default.xml includes prepackaged
combinations in named Interceptor Stacks.
Building your own Interceptor
If none of the stock Interceptors meets your needs, you can implement your own Interceptor. Fortunately, this is an easy task to accomplish. Suppose we need an Interceptor that places a greeting in the session according to the time of the day (morning, afternoon or evening). Here's how we could implement it:
- Create an Interceptor class, which is a class that implements the
com.opensymphony.xwork.interceptor.Interceptorinterface (bundled inxwork-1.1.jar) - Declare the class in your XML configuration file
action.xml) using the element<interceptor />nested within<interceptors />; - Create stacks of Interceptors, using the
<interceptor-stack />element (optional); - Determine which Interceptors are used by which mapping, using
<interceptor-ref />or<default-interceptor-ref />. The former defines the interceptors to be used in a specific action, while the latter determines the default interceptor stack to be used by all actions that do not specify their own<interceptor-ref />.
GreetingInterceptor.java:
...
package lesson05;
import java.util.Calendar;
import com.opensymphony.xwork.interceptor.Interceptor;
import com.opensymphony.xwork.ActionInvocation;
public class GreetingInterceptor implements Interceptor {
public void init() { }
public void destroy() { }
public String intercept(ActionInvocation invocation) throws Exception {
Calendar calendar = Calendar.getInstance();
int hour = calendar.get(Calendar.HOUR_OF_DAY);
String greeting = (hour < 6) ? "Good evening" :
((hour < 12) ? "Good morning":
((hour < 18) ? "Good afternoon": "Good evening"));
invocation.getInvocationContext().getSession().put("greeting", greeting);
String result = invocation.invoke();
return result;
}
}
xwork.xml:
...
<!DOCTYPE xwork PUBLIC "-//OpenSymphony Group//XWork 1.0//EN"
"http://www.opensymphony.com/xwork/xwork-1.0.dtd">
<xwork>
<!-- Include webwork defaults (from WebWork JAR). -->
<include file="webwork-default.xml" />
<!-- Configuration for the default package. -->
<package name="default" extends="webwork-default">
<interceptors>
<interceptor name="greeting" class="section02.lesson05.GreetingInterceptor" />
</interceptors>
<!-- Action: Lesson 5: GreetingInterceptor. -->
<action name="greetingAction" class="lesson05.GreetingAction">
<result name="success" type="velocity">ex01-result.vm</result>
<interceptor-ref name="greeting" />
</action>
</package>
</xwork>
GreetingAction.java:
...
package lesson05;
import com.opensymphony.xwork.ActionSupport;
public class GreetingAction extends ActionSupport {
public String execute() throws Exception {
return SUCCESS;
}
}
The Default Configuration
struts-default.xml is included in the application's configuration by default, all of the predefined interceptors and stacks are available "out of the box".
Framework Interceptors
Interceptor classes are also defined using a key-value pair specified in the Struts configuration file. The names specified below come specified in struts-default.xml. If you extend the struts-default package, then you can use the names below. Otherwise, they must be defined in your package with a name-class pair specified in the <interceptors> tag.
Interceptor | Name | Description |
|---|---|---|
alias | Converts similar parameters that may be named differently between requests. | |
chain | Makes the previous Action's properties available to the current Action. Commonly used together with <result type="chain"> (in the previous Action). | |
checkbox | Adds automatic checkbox handling code that detect an unchecked checkbox and add it as a parameter with a default (usually 'false') value. Uses a specially named hidden field to detect unsubmitted checkboxes. The default unchecked value is overridable for non-boolean value'd checkboxes. | |
cookie | Inject cookie with a certain configurable name / value into action. (Since 2.0.7.) | |
cookieProvider | Transfer cookies from action to response (Since 2.3.15.) | |
conversionError | Adds conversion errors from the ActionContext to the Action's field errors | |
createSession | Create an HttpSession automatically, useful with certain Interceptors that require a HttpSession to work properly (like the TokenInterceptor) | |
debugging | Provides several different debugging screens to provide insight into the data behind the page. | |
execAndWait | Executes the Action in the background and then sends the user off to an intermediate waiting page. | |
exception | Maps exceptions to a result. | |
fileUpload | An Interceptor that adds easy access to file upload support. | |
i18n | Remembers the locale selected for a user's session. | |
logger | Outputs the name of the Action. | |
store | Store and retrieve action messages / errors / field errors for action that implements ValidationAware interface into session. | |
modelDriven | If the Action implements ModelDriven, pushes the | |
scopedModelDriven | If the Action implements ScopedModelDriven, the interceptor retrieves and stores the model from a scope and sets it on the action calling | |
params | Sets the request parameters onto the Action. | |
prepare | If the Action implements Preparable, calls its | |
scope | Simple mechanism for storing Action state in the session or application scope. | |
servletConfig | Provide access to Maps representing HttpServletRequest and HttpServletResponse. | |
staticParams | Sets the | |
roles | Action will only be executed if the user has the correct JAAS role. | |
timer | Outputs how long the Action takes to execute (including nested Interceptors and View) | |
token | Checks for valid token presence in Action, prevents duplicate form submission. | |
tokenSession | Same as Token Interceptor, but stores the submitted data in session when handed an invalid token | |
validation | Performs validation using the validators defined in action-validation.xml | |
workflow | Calls the | |
N/A | Removes parameters from the list of those available to Actions | |
profiling | Activate profiling through parameter | |
multiselect | Like the checkbox interceptor detects that no value was selected for a field with multiple values (like a select) and adds an empty parameter | |
| NoOp Interceptor | noop | Does nothing, just passes invocation further, used in empty stack |
...
Since 2.0.7, Interceptors and Results with hyphenated names were converted to camelCase. (The former model-driven is now modelDriven.) The original hyphenated names are retained as "aliases" until Struts 2.1.0. For clarity, the hyphenated versions are not listed here, but might be referenced in prior versions of the documentation.
Method Filtering
Interceptor Parameter Overriding
Interceptor's parameter could be overridden through the following ways :
Method 1:
...
Method 2:
...
In the first method, the whole default stack is copied and the parameter then changed accordingly.
In the second method, the interceptor-ref refers to an existing interceptor-stack, namely defaultStack in this example, and override the validator and workflow interceptor excludeMethods attribute. Note that in the param tag, the name attribute contains a dot (.) the word before the dot(.) specifies the interceptor name whose parameter is to be overridden and the word after the dot (.) specifies the parameter itself. The syntax is as follows:
...
Note also that in this case the interceptor-ref name attribute is used to indicate an interceptor stack which makes sense as if it is referring to the interceptor itself it would be just using Method 1 describe above.
Method 3:
...
Interceptor Parameter Overriding Inheritance
Parameters override are not inherited in interceptors, meaning that the last set of overridden parameters will be used. For example, if a stack overrides the parameter "defaultBlock" for the "postPrepareParameterFilter" interceptor as:
...
and an action overrides the "allowed" for "postPrepareParameterFilter":
...
Then, only "allowed" will be overridden for the "postPrepareParameterFilter" interceptor in that action, the other params will be null.
Lazy parameters
...
This functionality was added in Struts 2.5.9
It is possible to define an interceptor with parameters evaluated during action invocation. In such case the interceptor must be marked with WithLazyParams interface. This must be developer's decision as interceptor must be aware of having those parameters set during invocation and not when the interceptor is created as it happens in normal way.
Params are evaluated as any other expression starting with from action as a top object.
...
Please be aware that order of interceptors can matter when want to access parameters passed via request as those parameters are set by Parameters Interceptor.
Order of Interceptor Execution
Interceptors provide an excellent means to wrap before/after processing. The concept reduces code duplication (think AOP).
...
Note that some Interceptors will interrupt the stack/chain/flow ... so the order is very important.
Interceptors implementing com.opensymphony.xwork2.interceptor.PreResultListener will run after the Action executes but before the Result executes.
...
FAQ
- How do we configure an Interceptor to be used with every Action?
- How do we get access to the session?
- How can we access the HttpServletRequest?
- How can we access the HttpServletResponse?
- How can we access request parameters passed into an Action?
- How do we access static parameters from an Action?
- Can we access an Action's Result?
- How do I obtain security details (JAAS)?
- Why isn't our Prepare interceptor being executed?
- How do we upload files?
Next: Writing Interceptors
ex01-result.vm:
...
<html>
<head>
<title>WebWork Tutorial - Lesson 5 - Example 1</title>
</head>
<body>
#set ($ses = $req.getSession())
<p><b>${ses.getAttribute('greeting')}!</b></p>
</body>
</html>
Let's take a look at our interceptor class first. As explained before, the interceptor must implement com.opensymphony.xwork.interceptor.Interceptor's methods: init(), called during interceptor initialization, destroy(), called during destruction, and most importantly, intercept(ActionInvocation invocation), which is where we place the code that does the work.
Notice that our interceptor returns the result from invocation.invoke() which is the method responsible for executing the next interceptor in the stack or, if this is the last one, the action. This means that the interceptor has the power of short-circuiting the action invocation and return a result string without executing the action at all! Use this with caution, though.
One other thing that interceptors can do is execute code after the action has executed. To do that, just place code after the invocation.invoke() call. WebWork provides an abstract class that already implements this kind of behaviour: com.opensymphony.xwork.interceptor.AroundInterceptor. Just extend it and implement the methods before(ActionInvocation invocation) and after(ActionInvocation dispatcher, String result).
The xwork.xml configuration, the action class and the result page are pretty straightforward and require no further explanation.
...