com.opensymphony.xwork2.interceptor.Interceptor Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package com.opensymphony.xwork2.interceptor;
import com.opensymphony.xwork2.ActionInvocation;
import java.io.Serializable;
/**
*
*
*
* An interceptor is a stateless class that follows the interceptor pattern, as
* found in {@link javax.servlet.Filter} and in AOP languages.
*
*
*
* Interceptors are objects that dynamically intercept Action invocations.
* They provide the developer with the opportunity to define code that can be executed
* before and/or after the execution of an action. They also have the ability
* to prevent an action from executing. Interceptors provide developers a way to
* encapsulate common functionality in a re-usable form that can be applied to
* one or more Actions.
*
*
*
* Interceptors must be stateless and not assume that a new instance will be created for each request or Action.
* Interceptors may choose to either short-circuit the {@link ActionInvocation} execution and return a return code
* (such as {@link com.opensymphony.xwork2.Action#SUCCESS}), or it may choose to do some processing before
* and/or after delegating the rest of the procesing using {@link ActionInvocation#invoke()}.
*
*
*
*
*
* Interceptor's parameter could be overridden through the following ways :-
*
* Method 1:
*
* <action name="myAction" class="myActionClass">
* <interceptor-ref name="exception"/>
* <interceptor-ref name="alias"/>
* <interceptor-ref name="params"/>
* <interceptor-ref name="servletConfig"/>
* <interceptor-ref name="prepare"/>
* <interceptor-ref name="i18n"/>
* <interceptor-ref name="chain"/>
* <interceptor-ref name="modelDriven"/>
* <interceptor-ref name="fileUpload"/>
* <interceptor-ref name="staticParams"/>
* <interceptor-ref name="params"/>
* <interceptor-ref name="conversionError"/>
* <interceptor-ref name="validation">
* <param name="excludeMethods">myValidationExcudeMethod</param>
* </interceptor-ref>
* <interceptor-ref name="workflow">
* <param name="excludeMethods">myWorkflowExcludeMethod</param>
* </interceptor-ref>
* </action>
*
*
* Method 2:
*
* <action name="myAction" class="myActionClass">
* <interceptor-ref name="defaultStack">
* <param name="validation.excludeMethods">myValidationExcludeMethod</param>
* <param name="workflow.excludeMethods">myWorkflowExcludeMethod</param>
* </interceptor-ref>
* </action>
*
*
*
* In the first method, the whole default stack is copied and the parameter then
* changed accordingly.
*
*
*
* In the second method, the 'interceptor-ref' refer to an existing
* interceptor-stack, namely defaultStack in this example, and override the validator
* and workflow interceptor excludeMethods typically in this case. 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. Essetially it is as follows :-
*
*
*
* <interceptor-name>.<parameter-name>
*
*
* 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.
*
*
*
*
* Nested Interceptor param overriding
*
*
*
*
* Interceptor stack parameter overriding could be nested into as many level as possible, though it would
* be advisable not to nest it too deep as to avoid confusion, For example,
*
*
* <interceptor name="interceptor1" class="foo.bar.Interceptor1" />
* <interceptor name="interceptor2" class="foo.bar.Interceptor2" />
* <interceptor name="interceptor3" class="foo.bar.Interceptor3" />
* <interceptor name="interceptor4" class="foo.bar.Interceptor4" />
* <interceptor-stack name="stack1">
* <interceptor-ref name="interceptor1" />
* </interceptor-stack>
* <interceptor-stack name="stack2">
* <interceptor-ref name="intercetor2" />
* <interceptor-ref name="stack1" />
* </interceptor-stack>
* <interceptor-stack name="stack3">
* <interceptor-ref name="interceptor3" />
* <interceptor-ref name="stack2" />
* </interceptor-stack>
* <interceptor-stack name="stack4">
* <interceptor-ref name="interceptor4" />
* <interceptor-ref name="stack3" />
* </interceptor-stack>
*
*
*
* Assuming the interceptor has the following properties
*
*
*
*
* Interceptor
* property
*
*
* Interceptor1
* param1
*
*
* Interceptor2
* param2
*
*
* Interceptor3
* param3
*
*
* Interceptor4
* param4
*
*
*
*
* We could override them as follows :
*
*
*
* <action ... >
* <!-- to override parameters of interceptor located directly in the stack -->
* <interceptor-ref name="stack4">
* <param name="interceptor4.param4"> ... </param>
* </interceptor-ref>
* </action>
*
* <action ... >
* <!-- to override parameters of interceptor located under nested stack -->
* <interceptor-ref name="stack4">
* <param name="stack3.interceptor3.param3"> ... </param>
* <param name="stack3.stack2.interceptor2.param2"> ... </param>
* <param name="stack3.stack2.stack1.interceptor1.param1"> ... </param>
* </interceptor-ref>
* </action>
*
*
*
*
* @author Jason Carreira
* @author tmjee
*/
public interface Interceptor extends Serializable {
/**
* Called to let an interceptor clean up any resources it has allocated.
*/
void destroy();
/**
* Called after an interceptor is created, but before any requests are processed using
* {@link #intercept(com.opensymphony.xwork2.ActionInvocation) intercept} , giving
* the Interceptor a chance to initialize any needed resources.
*/
void init();
/**
* Allows the Interceptor to do some processing on the request before and/or after the rest of the processing of the
* request by the {@link ActionInvocation} or to short-circuit the processing and just return a String return code.
*
* @param invocation the action invocation
* @return the return code, either returned from {@link ActionInvocation#invoke()}, or from the interceptor itself.
* @throws Exception any system-level error, as defined in {@link com.opensymphony.xwork2.Action#execute()}.
*/
String intercept(ActionInvocation invocation) throws Exception;
}