com.opensymphony.xwork2.interceptor.Interceptor Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of xwork Show documentation
XWork is an command-pattern framework that is used to power WebWork as well as other applications. XWork provides an Inversion of Control container, a powerful expression language, data type conversion, validation, and pluggable configuration.
There is a newer version: 2.1.3
Show newest version
/*
 * Copyright (c) 2002-2006 by OpenSymphony
 * All rights reserved.
 */
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 
 * encapulate 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 overriden 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  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
 *  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  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.
 * 
 * 
 * 
 * 
 * @author Jason Carreira
 * @version $Date: 2008-03-28 18:50:47 +0100 (Fri, 28 Mar 2008) $ $Id: Interceptor.java 1769 2008-03-28 17:50:47Z rainerh $
 */
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;

}