1 /*
2 * Copyright (c) 2002-2006 by OpenSymphony
3 * All rights reserved.
4 */
5 package com.opensymphony.xwork2.interceptor;
6
7 import com.opensymphony.xwork2.ActionInvocation;
8
9 import java.io.Serializable;
10
11
12 /**
13 * <!-- START SNIPPET: introduction -->
14 * <p/>
15 * An interceptor is a stateless class that follows the interceptor pattern, as
16 * found in {@link javax.servlet.Filter} and in AOP languages.
17 * <p/>
18 * <p/>
19 * <p/>
20 * Interceptors are objects that dynamically intercept Action invocations.
21 * They provide the developer with the opportunity to define code that can be executed
22 * before and/or after the execution of an action. They also have the ability
23 * to prevent an action from executing. Interceptors provide developers a way to
24 * encapulate common functionality in a re-usable form that can be applied to
25 * one or more Actions.
26 * <p/>
27 * <p/>
28 * <p/>
29 * Interceptors <b>must</b> be stateless and not assume that a new instance will be created for each request or Action.
30 * Interceptors may choose to either short-circuit the {@link ActionInvocation} execution and return a return code
31 * (such as {@link com.opensymphony.xwork2.Action#SUCCESS}), or it may choose to do some processing before
32 * and/or after delegating the rest of the procesing using {@link ActionInvocation#invoke()}.
33 * <p/>
34 * <!-- END SNIPPET: introduction -->
35 * <p/>
36 * <p/>
37 * <p/>
38 * <!-- START SNIPPET: parameterOverriding -->
39 * <p/>
40 * Interceptor's parameter could be overriden through the following ways :-
41 * <p/>
42 * <p/>
43 * <p/>
44 * <b>Method 1:</b>
45 * <pre>
46 * <action name="myAction" class="myActionClass">
47 * <interceptor-ref name="exception"/>
48 * <interceptor-ref name="alias"/>
49 * <interceptor-ref name="params"/>
50 * <interceptor-ref name="servletConfig"/>
51 * <interceptor-ref name="prepare"/>
52 * <interceptor-ref name="i18n"/>
53 * <interceptor-ref name="chain"/>
54 * <interceptor-ref name="modelDriven"/>
55 * <interceptor-ref name="fileUpload"/>
56 * <interceptor-ref name="staticParams"/>
57 * <interceptor-ref name="params"/>
58 * <interceptor-ref name="conversionError"/>
59 * <interceptor-ref name="validation">
60 * <param name="excludeMethods">myValidationExcudeMethod</param>
61 * </interceptor-ref>
62 * <interceptor-ref name="workflow">
63 * <param name="excludeMethods">myWorkflowExcludeMethod</param>
64 * </interceptor-ref>
65 * </action>
66 * </pre>
67 * <p/>
68 * <b>Method 2:</b>
69 * <pre>
70 * <action name="myAction" class="myActionClass">
71 * <interceptor-ref name="defaultStack">
72 * <param name="validation.excludeMethods">myValidationExcludeMethod</param>
73 * <param name="workflow.excludeMethods">myWorkflowExcludeMethod</param>
74 * </interceptor-ref>
75 * </action>
76 * </pre>
77 * <p/>
78 * <p/>
79 * <p/>
80 * In the first method, the whole default stack is copied and the parameter then
81 * changed accordingly.
82 * <p/>
83 * <p/>
84 * <p/>
85 * In the second method, the 'interceptor-ref' refer to an existing
86 * interceptor-stack, namely defaultStack in this example, and override the validator
87 * and workflow interceptor excludeMethods typically in this case. Note that in the
88 * 'param' tag, the name attribute contains a dot (.) the word before the dot(.)
89 * specifies the interceptor name whose parameter is to be overridden and the word after
90 * the dot (.) specifies the parameter itself. Essetially it is as follows :-
91 * <p/>
92 * <pre>
93 * <interceptor-name>.<parameter-name>
94 * </pre>
95 * <p/>
96 * <b>Note</b> also that in this case the 'interceptor-ref' name attribute
97 * is used to indicate an interceptor stack which makes sense as if it is referring
98 * to the interceptor itself it would be just using Method 1 describe above.
99 * <p/>
100 * <!-- END SNIPPET: parameterOverriding -->
101 * <p/>
102 * <p/>
103 * <b>Nested Interceptor param overriding</b>
104 * <p/>
105 * <!-- START SNIPPET: nestedParameterOverriding -->
106 * <p/>
107 * Interceptor stack parameter overriding could be nested into as many level as possible, though it would
108 * be advisable not to nest it too deep as to avoid confusion, For example,
109 * <pre>
110 * <interceptor name="interceptor1" class="foo.bar.Interceptor1" />
111 * <interceptor name="interceptor2" class="foo.bar.Interceptor2" />
112 * <interceptor name="interceptor3" class="foo.bar.Interceptor3" />
113 * <interceptor name="interceptor4" class="foo.bar.Interceptor4" />
114 * <interceptor-stack name="stack1">
115 * <interceptor-ref name="interceptor1" />
116 * </interceptor-stack>
117 * <interceptor-stack name="stack2">
118 * <interceptor-ref name="intercetor2" />
119 * <interceptor-ref name="stack1" />
120 * </interceptor-stack>
121 * <interceptor-stack name="stack3">
122 * <interceptor-ref name="interceptor3" />
123 * <interceptor-ref name="stack2" />
124 * </interceptor-stack>
125 * <interceptor-stack name="stack4">
126 * <interceptor-ref name="interceptor4" />
127 * <interceptor-ref name="stack3" />
128 * </interceptor-stack>
129 * </pre>
130 * Assuming the interceptor has the following properties
131 * <table border="1" width="100%">
132 * <tr>
133 * <td>Interceptor</td>
134 * <td>property</td>
135 * </tr>
136 * <tr>
137 * <td>Interceptor1</td>
138 * <td>param1</td>
139 * </tr>
140 * <tr>
141 * <td>Interceptor2</td>
142 * <td>param2</td>
143 * </tr>
144 * <tr>
145 * <td>Interceptor3</td>
146 * <td>param3</td>
147 * </tr>
148 * <tr>
149 * <td>Interceptor4</td>
150 * <td>param4</td>
151 * </tr>
152 * </table>
153 * We could override them as follows :-
154 * <pre>
155 * <action ... >
156 * <!-- to override parameters of interceptor located directly in the stack -->
157 * <interceptor-ref name="stack4">
158 * <param name="interceptor4.param4"> ... </param>
159 * </interceptor-ref>
160 * </action>
161 * <p/>
162 * <action ... >
163 * <!-- to override parameters of interceptor located under nested stack -->
164 * <interceptor-ref name="stack4">
165 * <param name="stack3.interceptor3.param3"> ... </param>
166 * <param name="stack3.stack2.interceptor2.param2"> ... </param>
167 * <param name="stack3.stack2.stack1.interceptor1.param1"> ... </param>
168 * </interceptor-ref>
169 * </action>
170 * </pre>
171 * <p/>
172 * <!-- END SNIPPET: nestedParameterOverriding -->
173 *
174 * @author Jason Carreira
175 * @author tmjee
176 * @version $Date: 2008-06-21 15:36:59 +0200 (Sa, 21 Jun 2008) $ $Id: Interceptor.java 1837 2008-06-21 13:36:59Z musachy $
177 */
178 public interface Interceptor extends Serializable {
179
180 /**
181 * Called to let an interceptor clean up any resources it has allocated.
182 */
183 void destroy();
184
185 /**
186 * Called after an interceptor is created, but before any requests are processed using
187 * {@link #intercept(com.opensymphony.xwork2.ActionInvocation) intercept} , giving
188 * the Interceptor a chance to initialize any needed resources.
189 */
190 void init();
191
192 /**
193 * Allows the Interceptor to do some processing on the request before and/or after the rest of the processing of the
194 * request by the {@link ActionInvocation} or to short-circuit the processing and just return a String return code.
195 *
196 * @param invocation the action invocation
197 * @return the return code, either returned from {@link ActionInvocation#invoke()}, or from the interceptor itself.
198 * @throws Exception any system-level error, as defined in {@link com.opensymphony.xwork2.Action#execute()}.
199 */
200 String intercept(ActionInvocation invocation) throws Exception;
201
202 }