001: /*
002: * Copyright (c) 2002-2006 by OpenSymphony
003: * All rights reserved.
004: */
005: package com.opensymphony.xwork.interceptor;
006:
007: import com.opensymphony.xwork.ActionInvocation;
008:
009: import java.io.Serializable;
010:
011: /**
012: * <!-- START SNIPPET: introduction -->
013: *
014: * An interceptor is a stateless class that follows the interceptor pattern, as
015: * found in {@link javax.servlet.Filter} and in AOP languages.
016: *
017: * <p/>
018: *
019: * Interceptors are objects that dynamically intercept Action invocations.
020: * They provide the developer with the opportunity to define code that can be executed
021: * before and/or after the execution of an action. They also have the ability
022: * to prevent an action from executing. Interceptors provide developers a way to
023: * encapulate common functionality in a re-usable form that can be applied to
024: * one or more Actions.
025: *
026: * <p/>
027: *
028: * Interceptors <b>must</b> be stateless and not assume that a new instance will be created for each request or Action.
029: * Interceptors may choose to either short-circuit the {@link ActionInvocation} execution and return a return code
030: * (such as {@link com.opensymphony.xwork.Action#SUCCESS}), or it may choose to do some processing before
031: * and/or after delegating the rest of the procesing using {@link ActionInvocation#invoke()}.
032: *
033: * <!-- END SNIPPET: introduction -->
034: *
035: * <p/>
036: *
037: * <!-- START SNIPPET: parameterOverriding -->
038: *
039: * Interceptor's parameter could be overriden through the following ways :-
040: *
041: * <p/>
042: *
043: * <b>Method 1:</b>
044: * <pre>
045: * <action name="myAction" class="myActionClass">
046: * <interceptor-ref name="exception"/>
047: * <interceptor-ref name="alias"/>
048: * <interceptor-ref name="params"/>
049: * <interceptor-ref name="servlet-config"/>
050: * <interceptor-ref name="prepare"/>
051: * <interceptor-ref name="i18n"/>
052: * <interceptor-ref name="chain"/>
053: * <interceptor-ref name="model-driven"/>
054: * <interceptor-ref name="fileUpload"/>
055: * <interceptor-ref name="static-params"/>
056: * <interceptor-ref name="params"/>
057: * <interceptor-ref name="conversionError"/>
058: * <interceptor-ref name="validation">
059: * <param name="excludeMethods">myValidationExcudeMethod</param>
060: * </interceptor-ref>
061: * <interceptor-ref name="workflow">
062: * <param name="excludeMethods">myWorkflowExcludeMethod</param>
063: * </interceptor-ref>
064: * </action>
065: * </pre>
066: *
067: * <b>Method 2:</b>
068: * <pre>
069: * <action name="myAction" class="myActionClass">
070: * <interceptor-ref name="defaultStack">
071: * <param name="validation.excludeMethods">myValidationExcludeMethod</param>
072: * <param name="workflow.excludeMethods">myWorkflowExcludeMethod</param>
073: * </interceptor-ref>
074: * </action>
075: * </pre>
076: *
077: * <p/>
078: *
079: * In the first method, the whole default stack is copied and the parameter then
080: * changed accordingly.
081: *
082: * <p/>
083: *
084: * In the second method, the <interceptor-ref .../> refer to an existing
085: * interceptor-stack, namely default-stack in this example, and override the validator
086: * and workflow interceptor excludeMethods typically in this case. Note that in the
087: * <param ... /> tag, the name attribute contains a dot (.) the word before the dot(.)
088: * specifies the interceptor name whose parameter is to be overriden and the word after
089: * the dot (.) specifies the parameter itself. Essetially it is as follows :-
090: *
091: * <pre>
092: * <interceptor-name>.<parameter-name>
093: * </pre>
094: *
095: * <b>Note</b> also that in this case the <interceptor-ref ... > name attribute
096: * is used to indicate an interceptor stack which makes sense as if it is refering
097: * to the interceptor itself it would be just using Method 1 describe above.
098: *
099: * <!-- END SNIPPET: parameterOverriding -->
100: *
101: * <p/>
102: * <b>Nested Interceptor param overriding</b>
103: * <p/>
104: * <!-- START SNIPPET: nestedParameterOverriding -->
105: *
106: * Interceptor stack parameter overriding could be nested into as many level as possible, though it would
107: * be advisable not to nest it too deep as to avoid confusion, For example,
108: * <pre>
109: * <interceptor name="interceptor1" class="foo.bar.Interceptor1" />
110: * <interceptor name="interceptor2" class="foo.bar.Interceptor2" />
111: * <interceptor name="interceptor3" class="foo.bar.Interceptor3" />
112: * <interceptor name="interceptor4" class="foo.bar.Interceptor4" />
113: * <interceptor-stack name="stack1">
114: * <interceptor-ref name="interceptor1" />
115: * </interceptor-stack>
116: * <interceptor-stack name="stack2">
117: * <interceptor-ref name="intercetor2" />
118: * <interceptor-ref name="stack1" />
119: * </interceptor-stack>
120: * <interceptor-stack name="stack3">
121: * <interceptor-ref name="interceptor3" />
122: * <interceptor-ref name="stack2" />
123: * </interceptor-stack>
124: * <interceptor-stack name="stack4">
125: * <interceptor-ref name="interceptor4" />
126: * <interceptor-ref name="stack3" />
127: * </interceptor-stack>
128: * </pre>
129: * Assuming the interceptor has the following properties
130: * <table border="1" width="100%">
131: * <tr>
132: * <td>Interceptor</td>
133: * <td>property</td>
134: * </tr>
135: * <tr>
136: * <td>Interceptor1</td>
137: * <td>param1</td>
138: * </tr>
139: * <tr>
140: * <td>Interceptor2</td>
141: * <td>param2</td>
142: * </tr>
143: * <tr>
144: * <td>Interceptor3</td>
145: * <td>param3</td>
146: * </tr>
147: * <tr>
148: * <td>Interceptor4</td>
149: * <td>param4</td>
150: * </tr>
151: * </table>
152: * We could override them as follows :-
153: * <pre>
154: * <action ... >
155: * <!-- to override parameters of interceptor located directly in the stack -->
156: * <interceptor-ref name="stack4">
157: * <param name="interceptor4.param4"> ... </param>
158: * </interceptor-ref>
159: * </action>
160: * <action ... >
161: * <!-- to override parameters of interceptor located under nested stack -->
162: * <interceptor-ref name="stack4">
163: * <param name="stack3.interceptor3.param3"> ... </param>
164: * <param name="stack3.stack2.interceptor2.param2"> ... </param>
165: * <param name="stack3.stack2.stack1.interceptor1.param1"> ... </param>
166: * </interceptor-ref>
167: * </action>
168: * </pre>
169: *
170: * <!-- END SNIPPET: nestedParameterOverriding -->
171: *
172: *
173: * @author Jason Carreira
174: * @author tmjee
175: * @version $Date: 2007-05-28 20:23:15 +0200 (Mon, 28 May 2007) $ $Id: Interceptor.java 1525 2007-05-28 18:23:15Z tm_jee $
176: */
177: public interface Interceptor extends Serializable {
178:
179: /**
180: * Called to let an interceptor clean up any resources it has allocated.
181: */
182: void destroy();
183:
184: /**
185: * Called after an interceptor is created, but before any requests are processed using
186: * {@link #intercept(com.opensymphony.xwork.ActionInvocation) intercept} , giving
187: * the Interceptor a chance to initialize any needed resources.
188: */
189: void init();
190:
191: /**
192: * Allows the Interceptor to do some processing on the request before and/or after the rest of the processing of the
193: * request by the {@link ActionInvocation} or to short-circuit the processing and just return a String return code.
194: *
195: * @return the return code, either returned from {@link ActionInvocation#invoke()}, or from the interceptor itself.
196: * @throws Exception any system-level error, as defined in {@link com.opensymphony.xwork.Action#execute()}.
197: */
198: String intercept(ActionInvocation invocation) throws Exception;
199: }
|