Spring Boot and Web MVC, part 3

Template engines

In addition to REST web services, you can also use Spring MVC to handle dynamic HTML content. Spring MVC supports various templating technologies, including Thymeleaf, FreeMarker, and JSP. In addition, many other templating engines provide their own integrations with Spring MVC.

Spring Boot provides autoconfiguration support for the following templating engines:

• FreeMarker

• Groovy

• Thymeleaf

• Mustache

If one of these template engines is used with the default configuration, then templates are automatically selected from src/main/ resources/templates.

Error Handling

By default, Spring Boot displays /error that handles all errors appropriately, and it is logged as a "global" error page in the servlet container. For machine clients, it generates a JSON response with a detailed description of the error, an HTTP status code, and an exception message. For browser clients, there is a "whitelabel" error view that renders the same data in HTML (to customize this, add a View that allows error).

There are a number of server.error properties that you can set if you want to customize the default error logic.

To completely replace the default logic, you can implement a ErrorController and register a bean definition of that type, or add a bean of type ErrorAttributes to use the existing mechanism but replace the content.

In addition, you can define a class annotated with @ControllerAdvice to customize the returned JSON document for a specific controller and/or exception type, as shown in the following example:

import javax.servlet.RequestDispatcher;
import javax.servlet.http.HttpServletRequest;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;
@ControllerAdvice(basePackageClasses = SomeController.class)
public class MyControllerAdvice extends ResponseEntityExceptionHandler {
    @ResponseBody
    @ExceptionHandler(MyException.class)
    public ResponseEntity<?> handleControllerException(HttpServletRequest request, Throwable ex) {
        HttpStatus status = getStatus(request);
        return new ResponseEntity<>(new MyErrorBody(status.value(), ex.getMessage()), status);
    }
    private HttpStatus getStatus(HttpServletRequest request) {
        Integer code = (Integer) request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
        HttpStatus status = HttpStatus.resolve(code);
        return (status != null) ? status : HttpStatus.INTERNAL_SERVER_ERROR;
    }
}

import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.ControllerAdvice
import org.springframework.web.bind.annotation.ExceptionHandler
import org.springframework.web.bind.annotation.ResponseBody
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler
import javax.servlet.RequestDispatcher
import javax.servlet.http.HttpServletRequest
@ControllerAdvice(basePackageClasses = [SomeController::class])
class MyControllerAdvice : ResponseEntityExceptionHandler() {
    @ResponseBody
    @ExceptionHandler(MyException::class)
    fun handleControllerException(request: HttpServletRequest, ex: Throwable): ResponseEntity<*> {
        val status = getStatus(request)
        return ResponseEntity(MyErrorBody(status.value(), ex.message), status)
    }
    private fun getStatus(request: HttpServletRequest): HttpStatus {
        val code = request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE) as Int
        val status = HttpStatus.resolve(code)
        return status ?: HttpStatus.INTERNAL_SERVER_ERROR
    }
}

In the previous example, if MyException is thrown by a controller defined in the same package as SomeController, instead of the ErrorAttributes view, the JSON representation of the POJO object MyErrorBody is used .

In some cases, errors handled at the controller level are not captured by the metrics framework. Applications can ensure that such exceptions are recorded in request metrics by configuring the handled exception as a request attribute:

import javax.servlet.http.HttpServletRequest;
import org.springframework.boot.web.servlet.error.ErrorAttributes;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.ExceptionHandler;
@Controller
public class MyController {
    @ExceptionHandler(CustomException.class)
    String handleCustomException(HttpServletRequest request, CustomException ex) {
        request.setAttribute(ErrorAttributes.ERROR_ATTRIBUTE, ex);
        return "errorView";
    }
}

import org.springframework.boot.web.servlet.error.ErrorAttributes
import org.springframework.stereotype.Controller
import org.springframework.web.bind.annotation.ExceptionHandler
import javax.servlet.http.HttpServletRequest
@Controller
class MyController {
    @ExceptionHandler(CustomException::class)
    fun handleCustomException(request: HttpServletRequest, ex: CustomException?): String {
        request.setAttribute(ErrorAttributes.ERROR_ATTRIBUTE, ex)
        return "errorView"
    }
}

Custom error pages

If you want to display a custom HTML error page for a given status code, you can add the file to the /error directory. Error pages can be either static HTML (that is, added to any of the static resource directories) or built using templates. The file name must be the exact status code or series mask.

For example, to display a 404 with a static HTML file, the directory structure should look like this:

src/
 +- main/
     +- java/
     |   + <source code>
     +- resources/
         +- public/
             +- error/
             |   +- 404.html
             +- <other public assets>

To display all 5xx errors using the FreeMarker template, the directory structure should be as follows :

src/
 +- main/
     +- java/
     |   + <source code>
     +- resources/
         +- templates/
             +- error/
             |   +- 5xx.ftlh
             +- <other templates>

For more complex displays, you can also add beans that implement the ErrorViewResolver interface, as shown in following example:

import java.util.Map;
import javax.servlet.http.HttpServletRequest;
import org.springframework.boot.autoconfigure.web.servlet.error.ErrorViewResolver;
import org.springframework.http.HttpStatus;
import org.springframework.web.servlet.ModelAndView;
public class MyErrorViewResolver implements ErrorViewResolver {
    @Override
    public ModelAndView resolveErrorView(HttpServletRequest request, HttpStatus status, Map<String, Object> model) {
         // Use the request or status to desire to return ModelAndView
        if (status == HttpStatus.INSUFFICIENT_STORAGE) {
            // Here we can add custom model values
            new ModelAndView("myview");
        }
        return null;
    }
}

import org.springframework.boot.autoconfigure.web.servlet.error.ErrorViewResolver
import org.springframework.http.HttpStatus
import org.springframework.web.servlet.ModelAndView
import javax.servlet.http.HttpServletRequest
class MyErrorViewResolver : ErrorViewResolver {
    override fun resolveErrorView(request: HttpServletRequest, status: HttpStatus,
            model: Map<String, Any>): ModelAndView? {
        // Use the request or status to desire to return ModelAndView
        if (status == HttpStatus.INSUFFICIENT_STORAGE) {
            // Here we can add custom model values
            return ModelAndView("myview")
        }
        return null
    }
}

You can also use regular Spring MVC features, such as methods marked with the @ExceptionHandler annotation and the @ControllerAdvice. ErrorController then catches any unhandled exceptions.

Displaying error pages outside of Spring MVC

For applications not using Spring MVC, you can use the ErrorPageRegistrar interface for direct registration of ErrorPages. This abstraction works directly with the underlying built-in servlet container and works well even if you don't have DispatcherServlet for Spring MVC.

import org.springframework.boot.web.server.ErrorPage;
import org.springframework.boot.web.server.ErrorPageRegistrar;
import org.springframework.boot.web.server.ErrorPageRegistry;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpStatus;
@Configuration(proxyBeanMethods = false)
public class MyErrorPagesConfiguration {
    @Bean
    public ErrorPageRegistrar errorPageRegistrar() {
        return this::registerErrorPages;
    }
    private void registerErrorPages(ErrorPageRegistry registry) {
        registry.addErrorPages(new ErrorPage(HttpStatus.BAD_REQUEST, "/400"));
    }
}

import org.springframework.boot.web.server.ErrorPage
import org.springframework.boot.web.server.ErrorPageRegistrar
import org.springframework.boot.web.server.ErrorPageRegistry
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.http.HttpStatus
@Configuration(proxyBeanMethods = false)
class MyErrorPagesConfiguration {
    @Bean
    fun errorPageRegistrar(): ErrorPageRegistrar {
        return ErrorPageRegistrar { registry: ErrorPageRegistry -> registerErrorPages(registry) }
    }
    private fun registerErrorPages(registry: ErrorPageRegistry) {
        registry.addErrorPages(ErrorPage(HttpStatus.BAD_REQUEST, "/400"))
    }
}

import java.util.EnumSet;
import javax.servlet.DispatcherType;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@Configuration(proxyBeanMethods = false)
public class MyFilterConfiguration {
    @Bean
    public FilterRegistrationBean<MyFilter> myFilter() {
        FilterRegistrationBean<MyFilter> registration = new FilterRegistrationBean<>(new MyFilter());
        // ...
        registration.setDispatcherTypes(EnumSet.allOf(DispatcherType.class));
        return registration;
    }
}

import org.springframework.boot.web.servlet.FilterRegistrationBean
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import java.util.EnumSet
import javax.servlet.DispatcherType
@Configuration(proxyBeanMethods = false)
class MyFilterConfiguration {
    @Bean
    fun myFilter(): FilterRegistrationBean<MyFilter> {
        val registration = FilterRegistrationBean(MyFilter())
        // ...
        registration.setDispatcherTypes(EnumSet.allOf(DispatcherType::class.java))
        return registration
    }
}

Note that the FilterRegistrationBean does not contain the ERROR manager type by default.

Error handling during WAR deployment

When deployed to a servlet container, Spring Boot uses its error page filter to redirect a request with an error code to the appropriate error page. This is necessary because the servlet specification does not provide an API for logging error pages. Depending on the container you deploy your war file to and the technologies your application uses, additional configuration may be required.

The error page filter will only be able to redirect the request to the correct error page if the answer has not yet been recorded. By default, WebSphere Application Server 8.0 and later captures the response after the servlet service method completes successfully. You should disable this logic by setting the com.ibm.ws.webcontainer.invokeFlushAfterService parameter to false.

If you are using Spring Security and want to get accessing the principal on the error page, you need to configure the Spring Security filter to be called when errors are sent. To do this, set the spring.security.filter.dispatcher-types property to async, error, forward, request.

CORS support

Cross-Origin Resource Sharing (CORS) is a W3C specification implemented by most browsers, which allows flexibility in determining what types of cross-domain requests will be authorized, and is intended to replace some less secure and less efficient approaches , such as IFRAME or JSONP.

Since version 4.2, Spring MVC supports CORS. Using a controller method for CORS configuration with @CrossOrigin annotations in a Spring Boot application does not require any special configuration. The global CORS configuration can only be defined by registering a WebMvcConfigurer bean with the addCorsMappings(CorsRegistry) method configured, as shown in the following example:

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration(proxyBeanMethods = false)
public class MyCorsConfiguration {
    @Bean
    public WebMvcConfigurer corsConfigurer() {
        return new WebMvcConfigurer() {
            @Override
            public void addCorsMappings(CorsRegistry registry) {
                registry.addMapping("/api/**");
            }
        };
    }
}

import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.web.servlet.config.annotation.CorsRegistry
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer
@Configuration(proxyBeanMethods = false)
class MyCorsConfiguration {
    @Bean
    fun corsConfigurer(): WebMvcConfigurer {
        return object : WebMvcConfigurer {
            override fun addCorsMappings(registry: CorsRegistry) {
                registry.addMapping("/api/**")
            }
        }
    }
}