net.sourceforge.stripes.controller
Interface Interceptor

All Known Implementing Classes:

BeforeAfterMethodInterceptor, HttpCacheInterceptor, SpringInterceptor, SpringInterceptorSupport

public interface Interceptor

Interface for classes which wish to intercept the processing of a request at various stages in the Stripes lifecycle. To denote the LifecycleStage (or stages) at which an interceptor should run, the class should be marked with an Intercepts annotation declaring one or more lifecycle stages.

Interceptors execute around the intercepted lifecycle stage. Assuming for simplicity's sake that a single interceptor is configured, any code in the intercept(ExecutionContext) method prior to calling context.proceed() will be executed immediately prior to the lifecycle code. Any code after calling context.proceed() will be executed immediately after the lifecycle code. For example the following implementation would print out a message before and after validation and binding occur:

@Intercepts(LifecycleStage.BindingAndValidation)
public class NoisyInterceptor implements Interceptor {
    public Resolution intercept(ExecutionContext context) {
        System.out.println("Before validation and binding!");
        Resolution r = context.proceed();
        System.out.println("After validation and binding!");
        return r;
    }
}

Interceptors can, in addition to adding behaviour, divert the flow of execution. They do this by returning a Resolution. If an interceptor returns a Resolution Stripes will abort processing of the current request and immediately execute the Resolution.

Interceptor developers must be careful to ensure that interceptors are well behaved. To continue normal processing interceptors must invoke context.proceed(). Since a given interceptor may be part of a stack of interceptors, or the lifecycle code may return a resolution, the interceptor must return the Resolution produced by context.proceed() unless it explicitly wishes to alter the flow of execution.

Interceptors gain access to information about the current execution environment through the ExecutionContext. Through this they can access the ActionBean, the handler Method, the lifecycle stage etc. Care must be taken to ensure that information is available before using it. For example interceptors which execute around ActionBeanResolution will not have access to the current ActionBean until after calling context.proceed() and will not have access to the event name or handler method at all (HandlerResolution occurs after ActionBeanResolution).

Optionally, Interceptor classes may implement the ConfigurableComponent interface. If implemented, the Interceptor will have it's init(Configuration) method called after instantiation and before being placed into service.

Interceptors are located by Stripes through it's Configuration. To configure interceptors you can either implement your own Configuration (probably by subclassing RuntimeConfiguration), or more likely by listing out the interceptors desired in the web.xml as specified in the documentation for RuntimeConfiguration.initInterceptors().

Since:

Stripes 1.3

Author:

Tim Fennell

Method Summary

Resolution

intercept(ExecutionContext context) Invoked when intercepting the flow of execution.

Method Detail

intercept

Resolution intercept(ExecutionContext context)
                     throws Exception

Invoked when intercepting the flow of execution.

Parameters:

context - the ExecutionContext of the request currently being processed

Returns:

the result of calling context.proceed(), or if the interceptor wishes to change the flow of execution, a Resolution

Throws:

Exception - if any non-recoverable errors occur