Introduction to Spring MVC HandlerInterceptor

1. Overview

In this tutorial, we’ll focus on understanding the Spring MVC HandlerInterceptor and how to use it correctly.

2. Spring MVC Handler

In order to understand how a Spring interceptor works, let’s take a step back and look at the HandlerMapping.

The purpose of HandlerMapping is to map a handler method to a URL. That way, the DispatcherServlet will be able to invoke it when processing a request.

As a matter of fact, the DispatcherServlet uses the HandlerAdapter to actually invoke the method.

In short, interceptors intercept requests and process them. They help to avoid repetitive handler code such as logging and authorization checks.

Now that we understand the overall context, let’s see how to use a HandlerInterceptor to perform some pre- and post-processing actions.

3. Maven Dependencies

In order to use interceptors, we need to include the spring-web dependency in our pom.xml:

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-web</artifactId>
    <version>6.2.1</version>
</dependency>

4. Spring Handler Interceptor

Before version 5.3 of spring-web, we could create a Spring interceptor class by extending the HandlerInterceptorAdapter class or implementing the HandlerInterceptor interface.

It’s worth noting that the HandlerInterceptorAdapter class is deprecated as of version 5.3. Therefore, to create an interceptor, we should implement the HandlerInterceptor interface directly.

The HandlerInterceptor interface contains three main methods:

• prehandle() – called before the execution of the actual handler
• postHandle() – called after the handler is executed
• afterCompletion() – called after the complete request is finished and the view is generated

These three methods provide flexibility to do all kinds of pre- and post-processing.

A quick note before we go further: To skip the theory and jump straight to examples, skip right ahead to Section 5.

Here’s a simple preHandle() implementation:

@Override
public boolean preHandle(
  HttpServletRequest request,
  HttpServletResponse response, 
  Object handler) throws Exception {
    // your code
    return true;
}

Notice that the method returns a boolean value. It tells Spring to further process the request (true) or not (false).

Next, we have an implementation of postHandle():

@Override
public void postHandle(
  HttpServletRequest request, 
  HttpServletResponse response,
  Object handler, 
  ModelAndView modelAndView) throws Exception {
    // your code
}

The interceptor calls this method immediately after processing the request but before generating the view.

For example, we may use this method to add an avatar of a logged-in user into a model.

The final method we need to implement is afterCompletion():

@Override
public void afterCompletion(
  HttpServletRequest request, 
  HttpServletResponse response,
  Object handler, Exception ex) {
    // your code
}

This method allows us to execute custom logic after the completion of the request processing.

Moreover, it’s worth mentioning that we can register multiple custom interceptors. To do that, we can use DefaultAnnotationHandlerMapping.

5. Custom Logger Interceptor

In this example, we’ll focus on logging in our web application.

First, our class needs to implement HandlerInterceptor:

public class LoggerInterceptor implements HandlerInterceptor {
    ...
}

We also need to enable logging in our interceptor:

private static Logger log = LoggerFactory.getLogger(LoggerInterceptor.class);

This allows Log4J to display logs as well as indicate which class is currently logging information to the specified output.

Next, let’s focus on our custom interceptor implementations.

5.1. preHandle() Method

As the name implies, the interceptor invokes preHandle() before handling a request.

By default, this method returns true to send the request further to the handler method. However, we can tell Spring to stop the execution by returning false.

We can use the hook to log information about the request’s parameters, such as where the request comes from.

In our example, we’re logging this info using a simple Log4J logger:

@Override
public boolean preHandle(
  HttpServletRequest request,
  HttpServletResponse response, 
  Object handler) throws Exception {
    
    log.info("[preHandle][" + request + "]" + "[" + request.getMethod()
      + "]" + request.getRequestURI() + getParameters(request));
    
    return true;
}

As we can see, we’re logging some basic information about the request.

In case we run into a password here, we’ll need to make sure we don’t log that, of course. A simple option would be to replace passwords, and any other sensitive type of data, with stars.

Here’s a quick implementation of how to do this:

private String getParameters(HttpServletRequest request) {
    StringBuffer posted = new StringBuffer();
    Enumeration<?> e = request.getParameterNames();
    if (e != null) {
        posted.append("?");
    }
    while (e.hasMoreElements()) {
        if (posted.length() > 1) {
            posted.append("&");
        }
        String curr = (String) e.nextElement();
        posted.append(curr + "=");
        if (curr.contains("password") 
          || curr.contains("pass")
          || curr.contains("pwd")) {
            posted.append("*****");
        } else {
            posted.append(request.getParameter(curr));
        }
    }
    String ip = request.getHeader("X-FORWARDED-FOR");
    String ipAddr = (ip == null) ? getRemoteAddr(request) : ip;
    if (ipAddr!=null && !ipAddr.equals("")) {
        posted.append("&_psip=" + ipAddr); 
    }
    return posted.toString();
}

Finally, we’re aiming to get the source IP address of the HTTP request.

Here’s a simple implementation:

private String getRemoteAddr(HttpServletRequest request) {
    String ipFromHeader = request.getHeader("X-FORWARDED-FOR");
    if (ipFromHeader != null && ipFromHeader.length() > 0) {
        log.debug("ip from proxy - X-FORWARDED-FOR : " + ipFromHeader);
        return ipFromHeader;
    }
    return request.getRemoteAddr();
}

5.2. postHandle() Method

The interceptor calls this method after the handler execution but before the DispatcherServlet renders the view.

We can use it to add additional attributes to ModelAndView. Another use case would be to compute the request’s processing time.

In our case, we’ll simply log our request just before the DispatcherServlet renders a view:

@Override
public void postHandle(
  HttpServletRequest request, 
  HttpServletResponse response,
  Object handler, 
  ModelAndView modelAndView) throws Exception {
    
    log.info("[postHandle][" + request + "]");
}

5.3. afterCompletion() Method

We can use this method to obtain request and response data after the view is rendered:

@Override
public void afterCompletion(
  HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) 
  throws Exception {
    if (ex != null){
        ex.printStackTrace();
    }
    log.info("[afterCompletion][" + request + "][exception: " + ex + "]");
}

6. Configuration

Now that we’ve put all the pieces together, let’s add our custom interceptor.

To do that, we need to override the addInterceptors() method:

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(new LoggerInterceptor());
}

We may achieve the same configuration by editing our XML Spring configuration file:

<mvc:interceptors>
    <bean id="loggerInterceptor" class="com.baeldung.web.interceptor.LoggerInterceptor"/>
</mvc:interceptors>

With this configuration active, the interceptor will be active, and all requests in the application will be properly logged.

Please notice that if multiple Spring interceptors are configured, the preHandle() method is executed in the configuration order, whereas postHandle() and afterCompletion() methods are invoked in the reverse order.

Please bear in mind that we don’t need to annotate our configuration class with @EnableWebMvc if we’re using Spring Boot instead of vanilla Spring.

7. Conclusion

This article provided a quick introduction to intercepting HTTP requests using Spring MVC Handler Interceptors.