Spring json error response

If there is empty message text in json when you encounter exception, you can be hit by changed behavior in spring boot 2.3.0. If this is the case, just change your server.error.include-message property to always.

Following answer is totally derived from Andy Wilkinson’s answer (which uses web.reactive classes)
— It includes web.servlet based classes.
— Spring boot 2.2.4.RELEASE

ExceptionHandlerConfig.java

package com.example.sample.core.exception;

import java.util.LinkedHashMap;
import java.util.Map;

import org.springframework.boot.web.servlet.error.DefaultErrorAttributes;
import org.springframework.boot.web.servlet.error.ErrorAttributes;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.WebRequest;

@Configuration
public class ExceptionHandlerConfig {

    //private static final String DEFAULT_KEY_TIMESTAMP = "timestamp";
    private static final String DEFAULT_KEY_STATUS = "status";
    private static final String DEFAULT_KEY_ERROR = "error";
    private static final String DEFAULT_KEY_ERRORS = "errors";
    private static final String DEFAULT_KEY_MESSAGE = "message";
    //private static final String DEFAULT_KEY_PATH = "path";

    public static final String KEY_STATUS = "status";
    public static final String KEY_ERROR = "error";
    public static final String KEY_MESSAGE = "message";
    public static final String KEY_TIMESTAMP = "timestamp";
    public static final String KEY_ERRORS = "errors";

    //

    @Bean
    public ErrorAttributes errorAttributes() {
        return new DefaultErrorAttributes() {

            @Override
            public Map<String ,Object> getErrorAttributes(
                WebRequest webRequest
                ,boolean includeStackTrace
            ) {
                Map<String ,Object> defaultMap
                    = super.getErrorAttributes( webRequest ,includeStackTrace );

                Map<String ,Object> errorAttributes = new LinkedHashMap<>();
                // Customize.
                // For eg: Only add the keys you want.
                errorAttributes.put( KEY_STATUS, defaultMap.get( DEFAULT_KEY_STATUS ) );                    
                errorAttributes.put( KEY_MESSAGE ,defaultMap.get( DEFAULT_KEY_MESSAGE ) );

                return errorAttributes;
            }
        };
    }
}

answered Mar 10, 2020 at 11:53

public class MyWebApplicationInitializer implements WebApplicationInitializer {

    @Override
    public void onStartup(ServletContext servletContext) {

        // Load Spring web application configuration
        AnnotationConfigWebApplicationContext context = new AnnotationConfigWebApplicationContext();
        context.register(AppConfig.class);

        // Create and register the DispatcherServlet
        DispatcherServlet servlet = new DispatcherServlet(context);
        ServletRegistration.Dynamic registration = servletContext.addServlet("app", servlet);
        registration.setLoadOnStartup(1);
        registration.addMapping("/app/*");
    }
}

class MyWebApplicationInitializer : WebApplicationInitializer {

    override fun onStartup(servletContext: ServletContext) {

        // Load Spring web application configuration
        val context = AnnotationConfigWebApplicationContext()
        context.register(AppConfig::class.java)

        // Create and register the DispatcherServlet
        val servlet = DispatcherServlet(context)
        val registration = servletContext.addServlet("app", servlet)
        registration.setLoadOnStartup(1)
        registration.addMapping("/app/*")
    }
}

Java

public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {

    @Override
    protected Class<?>[] getRootConfigClasses() {
        return new Class<?>[] { RootConfig.class };
    }

    @Override
    protected Class<?>[] getServletConfigClasses() {
        return new Class<?>[] { App1Config.class };
    }

    @Override
    protected String[] getServletMappings() {
        return new String[] { "/app1/*" };
    }
}

Kotlin

class MyWebAppInitializer : AbstractAnnotationConfigDispatcherServletInitializer() {

    override fun getRootConfigClasses(): Array<Class<*>> {
        return arrayOf(RootConfig::class.java)
    }

    override fun getServletConfigClasses(): Array<Class<*>> {
        return arrayOf(App1Config::class.java)
    }

    override fun getServletMappings(): Array<String> {
        return arrayOf("/app1/*")
    }
}

<web-app>

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>/WEB-INF/root-context.xml</param-value>
    </context-param>

    <servlet>
        <servlet-name>app1</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>/WEB-INF/app1-context.xml</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>app1</servlet-name>
        <url-pattern>/app1/*</url-pattern>
    </servlet-mapping>

</web-app>

Java

import org.springframework.web.WebApplicationInitializer;

public class MyWebApplicationInitializer implements WebApplicationInitializer {

    @Override
    public void onStartup(ServletContext container) {
        XmlWebApplicationContext appContext = new XmlWebApplicationContext();
        appContext.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml");

        ServletRegistration.Dynamic registration = container.addServlet("dispatcher", new DispatcherServlet(appContext));
        registration.setLoadOnStartup(1);
        registration.addMapping("/");
    }
}

Kotlin

import org.springframework.web.WebApplicationInitializer

class MyWebApplicationInitializer : WebApplicationInitializer {

    override fun onStartup(container: ServletContext) {
        val appContext = XmlWebApplicationContext()
        appContext.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml")

        val registration = container.addServlet("dispatcher", DispatcherServlet(appContext))
        registration.setLoadOnStartup(1)
        registration.addMapping("/")
    }
}

Java

public class MyWebAppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {

    @Override
    protected Class<?>[] getRootConfigClasses() {
        return null;
    }

    @Override
    protected Class<?>[] getServletConfigClasses() {
        return new Class<?>[] { MyWebConfig.class };
    }

    @Override
    protected String[] getServletMappings() {
        return new String[] { "/" };
    }
}

Kotlin

class MyWebAppInitializer : AbstractAnnotationConfigDispatcherServletInitializer() {

    override fun getRootConfigClasses(): Array<Class<*>>? {
        return null
    }

    override fun getServletConfigClasses(): Array<Class<*>>? {
        return arrayOf(MyWebConfig::class.java)
    }

    override fun getServletMappings(): Array<String> {
        return arrayOf("/")
    }
}

Java

public class MyWebAppInitializer extends AbstractDispatcherServletInitializer {

    @Override
    protected WebApplicationContext createRootApplicationContext() {
        return null;
    }

    @Override
    protected WebApplicationContext createServletApplicationContext() {
        XmlWebApplicationContext cxt = new XmlWebApplicationContext();
        cxt.setConfigLocation("/WEB-INF/spring/dispatcher-config.xml");
        return cxt;
    }

    @Override
    protected String[] getServletMappings() {
        return new String[] { "/" };
    }
}

Kotlin

class MyWebAppInitializer : AbstractDispatcherServletInitializer() {

    override fun createRootApplicationContext(): WebApplicationContext? {
        return null
    }

    override fun createServletApplicationContext(): WebApplicationContext {
        return XmlWebApplicationContext().apply {
            setConfigLocation("/WEB-INF/spring/dispatcher-config.xml")
        }
    }

    override fun getServletMappings(): Array<String> {
        return arrayOf("/")
    }
}

Java

public class MyWebAppInitializer extends AbstractDispatcherServletInitializer {

    // ...

    @Override
    protected Filter[] getServletFilters() {
        return new Filter[] {
            new HiddenHttpMethodFilter(), new CharacterEncodingFilter() };
    }
}

Kotlin

class MyWebAppInitializer : AbstractDispatcherServletInitializer() {

    // ...

    override fun getServletFilters(): Array<Filter> {
        return arrayOf(HiddenHttpMethodFilter(), CharacterEncodingFilter())
    }
}

• The WebApplicationContext is searched for and bound in the request as an attribute
  that the controller and other elements in the process can use. It is bound by default
  under the DispatcherServlet.WEB_APPLICATION_CONTEXT_ATTRIBUTE key.

• The locale resolver is bound to the request to let elements in the process
  resolve the locale to use when processing the request (rendering the view, preparing
  data, and so on). If you do not need locale resolving, you do not need the locale resolver.

• The theme resolver is bound to the request to let elements such as views determine
  which theme to use. If you do not use themes, you can ignore it.

• If you specify a multipart file resolver, the request is inspected for multiparts. If
  multiparts are found, the request is wrapped in a MultipartHttpServletRequest for
  further processing by other elements in the process. See Multipart Resolver for further
  information about multipart handling.

• An appropriate handler is searched for. If a handler is found, the execution chain
  associated with the handler (preprocessors, postprocessors, and controllers) is
  run to prepare a model for rendering. Alternatively, for annotated
  controllers, the response can be rendered (within the HandlerAdapter) instead of
  returning a view.

• If a model is returned, the view is rendered. If no model is returned (maybe due to
  a preprocessor or postprocessor intercepting the request, perhaps for security
  reasons), no view is rendered, because the request could already have been fulfilled.

• preHandle(..): Before the actual handler is run

• postHandle(..): After the handler is run

• afterCompletion(..): After the complete request has finished

Chain of Resolvers

You can form an exception resolver chain by declaring multiple HandlerExceptionResolver
beans in your Spring configuration and setting their order properties as needed.
The higher the order property, the later the exception resolver is positioned.

The contract of HandlerExceptionResolver specifies that it can return:

The MVC Config automatically declares built-in resolvers for default Spring MVC
exceptions, for @ResponseStatus annotated exceptions, and for support of
@ExceptionHandler methods. You can customize that list or replace it.

Container Error Page

If an exception remains unresolved by any HandlerExceptionResolver and is, therefore,
left to propagate or if the response status is set to an error status (that is, 4xx, 5xx),
Servlet containers can render a default error page in HTML. To customize the default
error page of the container, you can declare an error page mapping in web.xml.
The following example shows how to do so:

<error-page>
    <location>/error</location>
</error-page>

Given the preceding example, when an exception bubbles up or the response has an error status, the
Servlet container makes an ERROR dispatch within the container to the configured URL
(for example, /error). This is then processed by the DispatcherServlet, possibly mapping it
to a @Controller, which could be implemented to return an error view name with a model
or to render a JSON response, as the following example shows:

@RestController
public class ErrorController {

    @RequestMapping(path = "/error")
    public Map<String, Object> handle(HttpServletRequest request) {
        Map<String, Object> map = new HashMap<String, Object>();
        map.put("status", request.getAttribute("jakarta.servlet.error.status_code"));
        map.put("reason", request.getAttribute("jakarta.servlet.error.message"));
        return map;
    }
}

@RestController
class ErrorController {

    @RequestMapping(path = ["/error"])
    fun handle(request: HttpServletRequest): Map<String, Any> {
        val map = HashMap<String, Any>()
        map["status"] = request.getAttribute("jakarta.servlet.error.status_code")
        map["reason"] = request.getAttribute("jakarta.servlet.error.message")
        return map
    }
}

Handling

You can chain view resolvers by declaring more than one resolver bean and, if necessary, by
setting the order property to specify ordering. Remember, the higher the order property,
the later the view resolver is positioned in the chain.

The contract of a ViewResolver specifies that it can return null to indicate that the
view could not be found. However, in the case of JSPs and InternalResourceViewResolver,
the only way to figure out if a JSP exists is to perform a dispatch through
RequestDispatcher. Therefore, you must always configure an InternalResourceViewResolver
to be last in the overall order of view resolvers.

Configuring view resolution is as simple as adding ViewResolver beans to your Spring
configuration. The MVC Config provides a dedicated configuration API for
View Resolvers and for adding logic-less
View Controllers which are useful for HTML template
rendering without controller logic.

Redirecting

The special redirect: prefix in a view name lets you perform a redirect. The
UrlBasedViewResolver (and its subclasses) recognize this as an instruction that a
redirect is needed. The rest of the view name is the redirect URL.

The net effect is the same as if the controller had returned a RedirectView, but now
the controller itself can operate in terms of logical view names. A logical view
name (such as redirect:/myapp/some/resource) redirects relative to the current
Servlet context, while a name such as redirect:https://myhost.com/some/arbitrary/path
redirects to an absolute URL.

Note that, if a controller method is annotated with the @ResponseStatus, the annotation
value takes precedence over the response status set by RedirectView.

Forwarding

You can also use a special forward: prefix for view names that are
ultimately resolved by UrlBasedViewResolver and subclasses. This creates an
InternalResourceView, which does a RequestDispatcher.forward().
Therefore, this prefix is not useful with InternalResourceViewResolver and
InternalResourceView (for JSPs), but it can be helpful if you use another view
technology but still want to force a forward of a resource to be handled by the
Servlet/JSP engine. Note that you may also chain multiple view resolvers, instead.

Content Negotiation

ContentNegotiatingViewResolver
does not resolve views itself but rather delegates
to other view resolvers and selects the view that resembles the representation requested
by the client. The representation can be determined from the Accept header or from a
query parameter (for example, "/path?format=pdf").

The ContentNegotiatingViewResolver selects an appropriate View to handle the request
by comparing the request media types with the media type (also known as
Content-Type) supported by the View associated with each of its ViewResolvers. The
first View in the list that has a compatible Content-Type returns the representation
to the client. If a compatible view cannot be supplied by the ViewResolver chain,
the list of views specified through the DefaultViews property is consulted. This
latter option is appropriate for singleton Views that can render an appropriate
representation of the current resource regardless of the logical view name. The Accept
header can include wildcards (for example text/*), in which case a View whose
Content-Type is text/xml is a compatible match.

See View Resolvers under MVC Config for configuration details.

• Time Zone

• Header Resolver

• Cookie Resolver

• Session Resolver

• Locale Interceptor

Time Zone

In addition to obtaining the client’s locale, it is often useful to know its time zone.
The LocaleContextResolver interface offers an extension to LocaleResolver that lets
resolvers provide a richer LocaleContext, which may include time zone information.

When available, the user’s TimeZone can be obtained by using the
RequestContext.getTimeZone() method. Time zone information is automatically used
by any Date/Time Converter and Formatter objects that are registered with Spring’s
ConversionService.

This locale resolver inspects the accept-language header in the request that was sent
by the client (for example, a web browser). Usually, this header field contains the locale of
the client’s operating system. Note that this resolver does not support time zone
information.

Cookie Resolver

This locale resolver inspects a Cookie that might exist on the client to see if a
Locale or TimeZone is specified. If so, it uses the specified details. By using the
properties of this locale resolver, you can specify the name of the cookie as well as the
maximum age. The following example defines a CookieLocaleResolver:

<bean id="localeResolver" class="org.springframework.web.servlet.i18n.CookieLocaleResolver">

    <property name="cookieName" value="clientlanguage"/>

    <!-- in seconds. If set to -1, the cookie is not persisted (deleted when browser shuts down) -->
    <property name="cookieMaxAge" value="100000"/>

</bean>

The following table describes the properties CookieLocaleResolver:

Session Resolver

The SessionLocaleResolver lets you retrieve Locale and TimeZone from the
session that might be associated with the user’s request. In contrast to
CookieLocaleResolver, this strategy stores locally chosen locale settings in the
Servlet container’s HttpSession. As a consequence, those settings are temporary
for each session and are, therefore, lost when each session ends.

Note that there is no direct relationship with external session management mechanisms,
such as the Spring Session project. This SessionLocaleResolver evaluates and
modifies the corresponding HttpSession attributes against the current HttpServletRequest.

Locale Interceptor

You can enable changing of locales by adding the LocaleChangeInterceptor to one of the
HandlerMapping definitions. It detects a parameter in the request and changes the locale
accordingly, calling the setLocale method on the LocaleResolver in the dispatcher’s
application context. The next example shows that calls to all *.view resources
that contain a parameter named siteLanguage now changes the locale. So, for example,
a request for the URL, https://www.sf.net/home.view?siteLanguage=nl, changes the site
language to Dutch. The following example shows how to intercept the locale:

<bean id="localeChangeInterceptor"
        class="org.springframework.web.servlet.i18n.LocaleChangeInterceptor">
    <property name="paramName" value="siteLanguage"/>
</bean>

<bean id="localeResolver"
        class="org.springframework.web.servlet.i18n.CookieLocaleResolver"/>

<bean id="urlMapping"
        class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
    <property name="interceptors">
        <list>
            <ref bean="localeChangeInterceptor"/>
        </list>
    </property>
    <property name="mappings">
        <value>/**/*.view=someController</value>
    </property>
</bean>

Defining a theme

To use themes in your web application, you must set up an implementation of the
org.springframework.ui.context.ThemeSource interface. The WebApplicationContext
interface extends ThemeSource but delegates its responsibilities to a dedicated
implementation. By default, the delegate is an
org.springframework.ui.context.support.ResourceBundleThemeSource implementation that
loads properties files from the root of the classpath. To use a custom ThemeSource
implementation or to configure the base name prefix of the ResourceBundleThemeSource,
you can register a bean in the application context with the reserved name, themeSource.
The web application context automatically detects a bean with that name and uses it.

When you use the ResourceBundleThemeSource, a theme is defined in a simple properties
file. The properties file lists the resources that make up the theme, as the following example shows:

styleSheet=/themes/cool/style.css
background=/themes/cool/img/coolBg.jpg

The keys of the properties are the names that refer to the themed elements from view
code. For a JSP, you typically do this using the spring:theme custom tag, which is
very similar to the spring:message tag. The following JSP fragment uses the theme
defined in the previous example to customize the look and feel:

<%@ taglib prefix="spring" uri="http://www.springframework.org/tags"%>
<html>
    <head>
        <link rel="stylesheet" href="<spring:theme code='styleSheet'/>" type="text/css"/>
    </head>
    <body style="background=<spring:theme code='background'/>">
        ...
    </body>
</html>

By default, the ResourceBundleThemeSource uses an empty base name prefix. As a result,
the properties files are loaded from the root of the classpath. Thus, you would put the
cool.properties theme definition in a directory at the root of the classpath (for
example, in /WEB-INF/classes). The ResourceBundleThemeSource uses the standard Java
resource bundle loading mechanism, allowing for full internationalization of themes. For
example, we could have a /WEB-INF/classes/cool_nl.properties that references a special
background image with Dutch text on it.

Resolving Themes

After you define themes, as described in the preceding section,
you decide which theme to use. The DispatcherServlet looks for a bean named themeResolver
to find out which ThemeResolver implementation to use. A theme resolver works in much the same
way as a LocaleResolver. It detects the theme to use for a particular request and can also
alter the request’s theme. The following table describes the theme resolvers provided by Spring:

Spring also provides a ThemeChangeInterceptor that lets theme changes on every
request with a simple request parameter.

Servlet Multipart Parsing

Servlet multipart parsing needs to be enabled through Servlet container configuration.
To do so:

The following example shows how to set a MultipartConfigElement on the Servlet registration:

public class AppInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {

    // ...

    @Override
    protected void customizeRegistration(ServletRegistration.Dynamic registration) {

        // Optionally also set maxFileSize, maxRequestSize, fileSizeThreshold
        registration.setMultipartConfig(new MultipartConfigElement("/tmp"));
    }

}

class AppInitializer : AbstractAnnotationConfigDispatcherServletInitializer() {

    // ...

    override fun customizeRegistration(registration: ServletRegistration.Dynamic) {

        // Optionally also set maxFileSize, maxRequestSize, fileSizeThreshold
        registration.setMultipartConfig(MultipartConfigElement("/tmp"))
    }

}

Once the Servlet multipart configuration is in place, you can add a bean of type
StandardServletMultipartResolver with a name of multipartResolver.

Sensitive Data

DEBUG and TRACE logging may log sensitive information. This is why request parameters and
headers are masked by default and their logging in full must be enabled explicitly
through the enableLoggingRequestDetails property on DispatcherServlet.

The following example shows how to do so by using Java configuration:

public class MyInitializer
        extends AbstractAnnotationConfigDispatcherServletInitializer {

    @Override
    protected Class<?>[] getRootConfigClasses() {
        return ... ;
    }

    @Override
    protected Class<?>[] getServletConfigClasses() {
        return ... ;
    }

    @Override
    protected String[] getServletMappings() {
        return ... ;
    }

    @Override
    protected void customizeRegistration(ServletRegistration.Dynamic registration) {
        registration.setInitParameter("enableLoggingRequestDetails", "true");
    }

}

class MyInitializer : AbstractAnnotationConfigDispatcherServletInitializer() {

    override fun getRootConfigClasses(): Array<Class<*>>? {
        return ...
    }

    override fun getServletConfigClasses(): Array<Class<*>>? {
        return ...
    }

    override fun getServletMappings(): Array<String> {
        return ...
    }

    override fun customizeRegistration(registration: ServletRegistration.Dynamic) {
        registration.setInitParameter("enableLoggingRequestDetails", "true")
    }
}

@Controller
public class HelloController {

    @GetMapping("/hello")
    public String handle(Model model) {
        model.addAttribute("message", "Hello World!");
        return "index";
    }
}

import org.springframework.ui.set

@Controller
class HelloController {

    @GetMapping("/hello")
    fun handle(model: Model): String {
        model["message"] = "Hello World!"
        return "index"
    }
}

Java

@Configuration
@ComponentScan("org.example.web")
public class WebConfig {

    // ...
}

Kotlin

@Configuration
@ComponentScan("org.example.web")
class WebConfig {

    // ...
}

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:p="http://www.springframework.org/schema/p"
    xmlns:context="http://www.springframework.org/schema/context"
    xsi:schemaLocation="
        http://www.springframework.org/schema/beans
        https://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/context
        https://www.springframework.org/schema/context/spring-context.xsd">

    <context:component-scan base-package="org.example.web"/>

    <!-- ... -->

</beans>

AOP Proxies

In some cases, you may need to decorate a controller with an AOP proxy at runtime.
One example is if you choose to have @Transactional annotations directly on the
controller. When this is the case, for controllers specifically, we recommend
using class-based proxying. This is automatically the case with such annotations
directly on the controller.

If the controller implements an interface, and needs AOP proxying, you may need to
explicitly configure class-based proxying. For example, with @EnableTransactionManagement
you can change to @EnableTransactionManagement(proxyTargetClass = true), and with
<tx:annotation-driven/> you can change to <tx:annotation-driven proxy-target-class="true"/>.

• @GetMapping

• @PostMapping

• @PutMapping

• @DeleteMapping

• @PatchMapping

Java

@RestController
@RequestMapping("/persons")
class PersonController {

    @GetMapping("/{id}")
    public Person getPerson(@PathVariable Long id) {
        // ...
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public void add(@RequestBody Person person) {
        // ...
    }
}

Kotlin

@RestController
@RequestMapping("/persons")
class PersonController {

    @GetMapping("/{id}")
    fun getPerson(@PathVariable id: Long): Person {
        // ...
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    fun add(@RequestBody person: Person) {
        // ...
    }
}

URI patterns

@RequestMapping methods can be mapped using URL patterns. There are two alternatives:

PathPattern is the recommended solution for web applications and it is the only choice in
Spring WebFlux. It was enabled for use in Spring MVC from version 5.3 and is enabled by
default from version 6.0. See MVC config for
customizations of path matching options.

PathPattern supports the same pattern syntax as AntPathMatcher. In addition, it also
supports the capturing pattern, e.g. {*spring}, for matching 0 or more path segments
at the end of a path. PathPattern also restricts the use of ** for matching multiple
path segments such that it’s only allowed at the end of a pattern. This eliminates many
cases of ambiguity when choosing the best matching pattern for a given request.
For full pattern syntax please refer to
PathPattern and
AntPathMatcher.

Some example patterns:

Captured URI variables can be accessed with @PathVariable. For example:

@GetMapping("/owners/{ownerId}/pets/{petId}")
public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {
    // ...
}

@GetMapping("/owners/{ownerId}/pets/{petId}")
fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet {
    // ...
}

You can declare URI variables at the class and method levels, as the following example shows:

@Controller
@RequestMapping("/owners/{ownerId}")
public class OwnerController {

    @GetMapping("/pets/{petId}")
    public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {
        // ...
    }
}

@Controller
@RequestMapping("/owners/{ownerId}")
class OwnerController {

    @GetMapping("/pets/{petId}")
    fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet {
        // ...
    }
}

URI variables are automatically converted to the appropriate type, or TypeMismatchException
is raised. Simple types (int, long, Date, and so on) are supported by default and you can
register support for any other data type.
See Type Conversion and DataBinder.

You can explicitly name URI variables (for example, @PathVariable("customId")), but you can
leave that detail out if the names are the same and your code is compiled with the -parameters
compiler flag.

The syntax {varName:regex} declares a URI variable with a regular expression that has
syntax of {varName:regex}. For example, given URL "/spring-web-3.0.5.jar", the following method
extracts the name, version, and file extension:

@GetMapping("/{name:[a-z-]+}-{version:\d\.\d\.\d}{ext:\.[a-z]+}")
public void handle(@PathVariable String name, @PathVariable String version, @PathVariable String ext) {
    // ...
}

@GetMapping("/{name:[a-z-]+}-{version:\d\.\d\.\d}{ext:\.[a-z]+}")
fun handle(@PathVariable name: String, @PathVariable version: String, @PathVariable ext: String) {
    // ...
}

URI path patterns can also have embedded ${…​} placeholders that are resolved on startup
by using PropertySourcesPlaceholderConfigurer against local, system, environment, and
other property sources. You can use this, for example, to parameterize a base URL based on
some external configuration.

Pattern Comparison

When multiple patterns match a URL, the best match must be selected. This is done with
one of the following depending on whether use of parsed PathPattern is enabled for use or not:

Both help to sort patterns with more specific ones on top. A pattern is less specific if
it has a lower count of URI variables (counted as 1), single wildcards (counted as 1),
and double wildcards (counted as 2). Given an equal score, the longer pattern is chosen.
Given the same score and length, the pattern with more URI variables than wildcards is
chosen.

The default mapping pattern (/**) is excluded from scoring and always
sorted last. Also, prefix patterns (such as /public/**) are considered less
specific than other pattern that do not have double wildcards.

For the full details, follow the above links to the pattern Comparators.

Suffix Match

Starting in 5.3, by default Spring MVC no longer performs .* suffix pattern
matching where a controller mapped to /person is also implicitly mapped to
/person.*. As a consequence path extensions are no longer used to interpret
the requested content type for the response — for example, /person.pdf, /person.xml,
and so on.

Using file extensions in this way was necessary when browsers used to send Accept headers
that were hard to interpret consistently. At present, that is no longer a necessity and
using the Accept header should be the preferred choice.

Over time, the use of file name extensions has proven problematic in a variety of ways.
It can cause ambiguity when overlain with the use of URI variables, path parameters, and
URI encoding. Reasoning about URL-based authorization
and security (see next section for more details) also becomes more difficult.

To completely disable the use of path extensions in versions prior to 5.3, set the following:

Having a way to request content types other than through the "Accept" header can still
be useful, e.g. when typing a URL in a browser. A safe alternative to path extensions is
to use the query parameter strategy. If you must use file extensions, consider restricting
them to a list of explicitly registered extensions through the mediaTypes property of
ContentNegotiationConfigurer.

Suffix Match and RFD

A reflected file download (RFD) attack is similar to XSS in that it relies on request input
(for example, a query parameter and a URI variable) being reflected in the response. However, instead of
inserting JavaScript into HTML, an RFD attack relies on the browser switching to perform a
download and treating the response as an executable script when double-clicked later.

In Spring MVC, @ResponseBody and ResponseEntity methods are at risk, because
they can render different content types, which clients can request through URL path extensions.
Disabling suffix pattern matching and using path extensions for content negotiation
lower the risk but are not sufficient to prevent RFD attacks.

To prevent RFD attacks, prior to rendering the response body, Spring MVC adds a
Content-Disposition:inline;filename=f.txt header to suggest a fixed and safe download
file. This is done only if the URL path contains a file extension that is neither
allowed as safe nor explicitly registered for content negotiation. However, it can
potentially have side effects when URLs are typed directly into a browser.

Many common path extensions are allowed as safe by default. Applications with custom
HttpMessageConverter implementations can explicitly register file extensions for content
negotiation to avoid having a Content-Disposition header added for those extensions.
See Content Types.

See CVE-2015-5211 for additional
recommendations related to RFD.

Consumable Media Types

You can narrow the request mapping based on the Content-Type of the request,
as the following example shows:

@PostMapping(path = "/pets", consumes = "application/json") (1)
public void addPet(@RequestBody Pet pet) {
    // ...
}

@PostMapping("/pets", consumes = ["application/json"]) (1)
fun addPet(@RequestBody pet: Pet) {
    // ...
}

The consumes attribute also supports negation expressions — for example, !text/plain means any
content type other than text/plain.

You can declare a shared consumes attribute at the class level. Unlike most other
request-mapping attributes, however, when used at the class level, a method-level consumes attribute
overrides rather than extends the class-level declaration.

Producible Media Types

You can narrow the request mapping based on the Accept request header and the list of
content types that a controller method produces, as the following example shows:

@GetMapping(path = "/pets/{petId}", produces = "application/json") (1)
@ResponseBody
public Pet getPet(@PathVariable String petId) {
    // ...
}

@GetMapping("/pets/{petId}", produces = ["application/json"]) (1)
@ResponseBody
fun getPet(@PathVariable petId: String): Pet {
    // ...
}

The media type can specify a character set. Negated expressions are supported — for example,
!text/plain means any content type other than «text/plain».

You can declare a shared produces attribute at the class level. Unlike most other
request-mapping attributes, however, when used at the class level, a method-level produces attribute
overrides rather than extends the class-level declaration.

Parameters, headers

You can narrow request mappings based on request parameter conditions. You can test for the
presence of a request parameter (myParam), for the absence of one (!myParam), or for a
specific value (myParam=myValue). The following example shows how to test for a specific value:

@GetMapping(path = "/pets/{petId}", params = "myParam=myValue") (1)
public void findPet(@PathVariable String petId) {
    // ...
}

@GetMapping("/pets/{petId}", params = ["myParam=myValue"]) (1)
fun findPet(@PathVariable petId: String) {
    // ...
}

You can also use the same with request header conditions, as the following example shows:

@GetMapping(path = "/pets", headers = "myHeader=myValue") (1)
public void findPet(@PathVariable String petId) {
    // ...
}

@GetMapping("/pets", headers = ["myHeader=myValue"]) (1)
fun findPet(@PathVariable petId: String) {
    // ...
}

HTTP HEAD, OPTIONS

@GetMapping (and @RequestMapping(method=HttpMethod.GET)) support HTTP HEAD
transparently for request mapping. Controller methods do not need to change.
A response wrapper, applied in jakarta.servlet.http.HttpServlet, ensures a Content-Length
header is set to the number of bytes written (without actually writing to the response).

@GetMapping (and @RequestMapping(method=HttpMethod.GET)) are implicitly mapped to
and support HTTP HEAD. An HTTP HEAD request is processed as if it were HTTP GET except
that, instead of writing the body, the number of bytes are counted and the Content-Length
header is set.

By default, HTTP OPTIONS is handled by setting the Allow response header to the list of HTTP
methods listed in all @RequestMapping methods that have matching URL patterns.

For a @RequestMapping without HTTP method declarations, the Allow header is set to
GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS. Controller methods should always declare the
supported HTTP methods (for example, by using the HTTP method specific variants:
@GetMapping, @PostMapping, and others).

You can explicitly map the @RequestMapping method to HTTP HEAD and HTTP OPTIONS, but that
is not necessary in the common case.

Custom Annotations

Spring MVC supports the use of composed annotations
for request mapping. Those are annotations that are themselves meta-annotated with
@RequestMapping and composed to redeclare a subset (or all) of the @RequestMapping
attributes with a narrower, more specific purpose.

@GetMapping, @PostMapping, @PutMapping, @DeleteMapping, and @PatchMapping are
examples of composed annotations. They are provided because, arguably, most
controller methods should be mapped to a specific HTTP method versus using @RequestMapping,
which, by default, matches to all HTTP methods. If you need an example of composed
annotations, look at how those are declared.

Spring MVC also supports custom request-mapping attributes with custom request-matching
logic. This is a more advanced option that requires subclassing
RequestMappingHandlerMapping and overriding the getCustomMethodCondition method, where
you can check the custom attribute and return your own RequestCondition.

Explicit Registrations

You can programmatically register handler methods, which you can use for dynamic
registrations or for advanced cases, such as different instances of the same handler
under different URLs. The following example registers a handler method:

@Configuration
public class MyConfig {

    @Autowired
    public void setHandlerMapping(RequestMappingHandlerMapping mapping, UserHandler handler) (1)
            throws NoSuchMethodException {

        RequestMappingInfo info = RequestMappingInfo
                .paths("/user/{id}").methods(RequestMethod.GET).build(); (2)

        Method method = UserHandler.class.getMethod("getUser", Long.class); (3)

        mapping.registerMapping(info, handler, method); (4)
    }
}

@Configuration
class MyConfig {

    @Autowired
    fun setHandlerMapping(mapping: RequestMappingHandlerMapping, handler: UserHandler) { (1)
        val info = RequestMappingInfo.paths("/user/{id}").methods(RequestMethod.GET).build() (2)
        val method = UserHandler::class.java.getMethod("getUser", Long::class.java) (3)
        mapping.registerMapping(info, handler, method) (4)
    }
}

Method Arguments

The next table describes the supported controller method arguments. Reactive types are not supported
for any arguments.

JDK 8’s java.util.Optional is supported as a method argument in combination with
annotations that have a required attribute (for example, @RequestParam, @RequestHeader,
and others) and is equivalent to required=false.

Return Values

The next table describes the supported controller method return values. Reactive types are
supported for all return values.

Type Conversion

Some annotated controller method arguments that represent String-based request input (such as
@RequestParam, @RequestHeader, @PathVariable, @MatrixVariable, and @CookieValue)
can require type conversion if the argument is declared as something other than String.

For such cases, type conversion is automatically applied based on the configured converters.
By default, simple types (int, long, Date, and others) are supported. You can customize
type conversion through a WebDataBinder (see DataBinder) or by registering
Formatters with the FormattingConversionService.
See Spring Field Formatting.

A practical issue in type conversion is the treatment of an empty String source value.
Such a value is treated as missing if it becomes null as a result of type conversion.
This can be the case for Long, UUID, and other target types. If you want to allow null
to be injected, either use the required flag on the argument annotation, or declare the
argument as @Nullable.

Matrix Variables

RFC 3986 discusses name-value pairs in
path segments. In Spring MVC, we refer to those as “matrix variables” based on an
“old post” by Tim Berners-Lee, but they
can be also be referred to as URI path parameters.

Matrix variables can appear in any path segment, with each variable separated by a semicolon and
multiple values separated by comma (for example, /cars;color=red,green;year=2012). Multiple
values can also be specified through repeated variable names (for example,
color=red;color=green;color=blue).

If a URL is expected to contain matrix variables, the request mapping for a controller
method must use a URI variable to mask that variable content and ensure the request can
be matched successfully independent of matrix variable order and presence.
The following example uses a matrix variable:

// GET /pets/42;q=11;r=22

@GetMapping("/pets/{petId}")
public void findPet(@PathVariable String petId, @MatrixVariable int q) {

    // petId == 42
    // q == 11
}

// GET /pets/42;q=11;r=22

@GetMapping("/pets/{petId}")
fun findPet(@PathVariable petId: String, @MatrixVariable q: Int) {

    // petId == 42
    // q == 11
}

Given that all path segments may contain matrix variables, you may sometimes need to
disambiguate which path variable the matrix variable is expected to be in.
The following example shows how to do so:

// GET /owners/42;q=11/pets/21;q=22

@GetMapping("/owners/{ownerId}/pets/{petId}")
public void findPet(
        @MatrixVariable(name="q", pathVar="ownerId") int q1,
        @MatrixVariable(name="q", pathVar="petId") int q2) {

    // q1 == 11
    // q2 == 22
}

// GET /owners/42;q=11/pets/21;q=22

@GetMapping("/owners/{ownerId}/pets/{petId}")
fun findPet(
        @MatrixVariable(name = "q", pathVar = "ownerId") q1: Int,
        @MatrixVariable(name = "q", pathVar = "petId") q2: Int) {

    // q1 == 11
    // q2 == 22
}

A matrix variable may be defined as optional and a default value specified, as the
following example shows:

// GET /pets/42

@GetMapping("/pets/{petId}")
public void findPet(@MatrixVariable(required=false, defaultValue="1") int q) {

    // q == 1
}

// GET /pets/42

@GetMapping("/pets/{petId}")
fun findPet(@MatrixVariable(required = false, defaultValue = "1") q: Int) {

    // q == 1
}

To get all matrix variables, you can use a MultiValueMap, as the following example shows:

// GET /owners/42;q=11;r=12/pets/21;q=22;s=23

@GetMapping("/owners/{ownerId}/pets/{petId}")
public void findPet(
        @MatrixVariable MultiValueMap<String, String> matrixVars,
        @MatrixVariable(pathVar="petId") MultiValueMap<String, String> petMatrixVars) {

    // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23]
    // petMatrixVars: ["q" : 22, "s" : 23]
}

// GET /owners/42;q=11;r=12/pets/21;q=22;s=23

@GetMapping("/owners/{ownerId}/pets/{petId}")
fun findPet(
        @MatrixVariable matrixVars: MultiValueMap<String, String>,
        @MatrixVariable(pathVar="petId") petMatrixVars: MultiValueMap<String, String>) {

    // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23]
    // petMatrixVars: ["q" : 22, "s" : 23]
}

Note that you need to enable the use of matrix variables. In the MVC Java configuration,
you need to set a UrlPathHelper with removeSemicolonContent=false through
Path Matching. In the MVC XML namespace, you can set
<mvc:annotation-driven enable-matrix-variables="true"/>.

@RequestParam

You can use the @RequestParam annotation to bind Servlet request parameters (that is,
query parameters or form data) to a method argument in a controller.

The following example shows how to do so:

@Controller
@RequestMapping("/pets")
public class EditPetForm {

    // ...

    @GetMapping
    public String setupForm(@RequestParam("petId") int petId, Model model) { (1)
        Pet pet = this.clinic.loadPet(petId);
        model.addAttribute("pet", pet);
        return "petForm";
    }

    // ...

}

import org.springframework.ui.set

@Controller
@RequestMapping("/pets")
class EditPetForm {

    // ...

    @GetMapping
    fun setupForm(@RequestParam("petId") petId: Int, model: Model): String { (1)
        val pet = this.clinic.loadPet(petId);
        model["pet"] = pet
        return "petForm"
    }

    // ...

}

By default, method parameters that use this annotation are required, but you can specify that
a method parameter is optional by setting the @RequestParam annotation’s required flag to
false or by declaring the argument with an java.util.Optional wrapper.

Type conversion is automatically applied if the target method parameter type is not
String. See Type Conversion.

Declaring the argument type as an array or list allows for resolving multiple parameter
values for the same parameter name.

When an @RequestParam annotation is declared as a Map<String, String> or
MultiValueMap<String, String>, without a parameter name specified in the annotation,
then the map is populated with the request parameter values for each given parameter name.

Note that use of @RequestParam is optional (for example, to set its attributes).
By default, any argument that is a simple value type (as determined by
BeanUtils#isSimpleProperty)
and is not resolved by any other argument resolver, is treated as if it were annotated
with @RequestParam.

You can use the @RequestHeader annotation to bind a request header to a method argument in a
controller.

Consider the following request, with headers:

Host                    localhost:8080
Accept                  text/html,application/xhtml+xml,application/xml;q=0.9
Accept-Language         fr,en-gb;q=0.7,en;q=0.3
Accept-Encoding         gzip,deflate
Accept-Charset          ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive              300

The following example gets the value of the Accept-Encoding and Keep-Alive headers:

@GetMapping("/demo")
public void handle(
        @RequestHeader("Accept-Encoding") String encoding, (1)
        @RequestHeader("Keep-Alive") long keepAlive) { (2)
    //...
}

@GetMapping("/demo")
fun handle(
        @RequestHeader("Accept-Encoding") encoding: String, (1)
        @RequestHeader("Keep-Alive") keepAlive: Long) { (2)
    //...
}

If the target method parameter type is not
String, type conversion is automatically applied. See Type Conversion.

When an @RequestHeader annotation is used on a Map<String, String>,
MultiValueMap<String, String>, or HttpHeaders argument, the map is populated
with all header values.

@CookieValue

You can use the @CookieValue annotation to bind the value of an HTTP cookie to a method argument
in a controller.

Consider a request with the following cookie:

JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84

The following example shows how to get the cookie value:

@GetMapping("/demo")
public void handle(@CookieValue("JSESSIONID") String cookie) { (1)
    //...
}

@GetMapping("/demo")
fun handle(@CookieValue("JSESSIONID") cookie: String) { (1)
    //...
}

If the target method parameter type is not String, type conversion is applied automatically.
See Type Conversion.

@ModelAttribute

You can use the @ModelAttribute annotation on a method argument to access an attribute from
the model or have it be instantiated if not present. The model attribute is also overlain with
values from HTTP Servlet request parameters whose names match to field names. This is referred
to as data binding, and it saves you from having to deal with parsing and converting individual
query parameters and form fields. The following example shows how to do so:

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute Pet pet) { (1)
    // method logic...
}

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@ModelAttribute pet: Pet): String { (1)
    // method logic...
}

The Pet instance above is sourced in one of the following ways:

One alternative to using a @ModelAttribute method to
supply it or relying on the framework to create the model attribute, is to have a
Converter<String, T> to provide the instance. This is applied when the model attribute
name matches to the name of a request value such as a path variable or a request
parameter, and there is a Converter from String to the model attribute type.
In the following example, the model attribute name is account which matches the URI
path variable account, and there is a registered Converter<String, Account> which
could load the Account from a data store:

@PutMapping("/accounts/{account}")
public String save(@ModelAttribute("account") Account account) { (1)
    // ...
}

@PutMapping("/accounts/{account}")
fun save(@ModelAttribute("account") account: Account): String { (1)
    // ...
}

After the model attribute instance is obtained, data binding is applied. The
WebDataBinder class matches Servlet request parameter names (query parameters and form
fields) to field names on the target Object. Matching fields are populated after type
conversion is applied, where necessary. For more on data binding (and validation), see
Validation. For more on customizing data binding, see
DataBinder.

Data binding can result in errors. By default, a BindException is raised. However, to check
for such errors in the controller method, you can add a BindingResult argument immediately next
to the @ModelAttribute, as the following example shows:

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { (1)
    if (result.hasErrors()) {
        return "petForm";
    }
    // ...
}

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@ModelAttribute("pet") pet: Pet, result: BindingResult): String { (1)
    if (result.hasErrors()) {
        return "petForm"
    }
    // ...
}

In some cases, you may want access to a model attribute without data binding. For such
cases, you can inject the Model into the controller and access it directly or,
alternatively, set @ModelAttribute(binding=false), as the following example shows:

@ModelAttribute
public AccountForm setUpForm() {
    return new AccountForm();
}

@ModelAttribute
public Account findAccount(@PathVariable String accountId) {
    return accountRepository.findOne(accountId);
}

@PostMapping("update")
public String update(@Valid AccountForm form, BindingResult result,
        @ModelAttribute(binding=false) Account account) { (1)
    // ...
}

@ModelAttribute
fun setUpForm(): AccountForm {
    return AccountForm()
}

@ModelAttribute
fun findAccount(@PathVariable accountId: String): Account {
    return accountRepository.findOne(accountId)
}

@PostMapping("update")
fun update(@Valid form: AccountForm, result: BindingResult,
           @ModelAttribute(binding = false) account: Account): String { (1)
    // ...
}

You can automatically apply validation after data binding by adding the
jakarta.validation.Valid annotation or Spring’s @Validated annotation
(Bean Validation and
Spring validation). The following example shows how to do so:

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
public String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { (1)
    if (result.hasErrors()) {
        return "petForm";
    }
    // ...
}

@PostMapping("/owners/{ownerId}/pets/{petId}/edit")
fun processSubmit(@Valid @ModelAttribute("pet") pet: Pet, result: BindingResult): String { (1)
    if (result.hasErrors()) {
        return "petForm"
    }
    // ...
}

Note that using @ModelAttribute is optional (for example, to set its attributes).
By default, any argument that is not a simple value type (as determined by
BeanUtils#isSimpleProperty)
and is not resolved by any other argument resolver is treated as if it were annotated
with @ModelAttribute.

@SessionAttributes

@SessionAttributes is used to store model attributes in the HTTP Servlet session between
requests. It is a type-level annotation that declares the session attributes used by a
specific controller. This typically lists the names of model attributes or types of
model attributes that should be transparently stored in the session for subsequent
requests to access.

The following example uses the @SessionAttributes annotation:

@Controller
@SessionAttributes("pet") (1)
public class EditPetForm {
    // ...
}

@Controller
@SessionAttributes("pet") (1)
class EditPetForm {
    // ...
}

On the first request, when a model attribute with the name, pet, is added to the model,
it is automatically promoted to and saved in the HTTP Servlet session. It remains there
until another controller method uses a SessionStatus method argument to clear the
storage, as the following example shows:

@Controller
@SessionAttributes("pet") (1)
public class EditPetForm {

    // ...

    @PostMapping("/pets/{id}")
    public String handle(Pet pet, BindingResult errors, SessionStatus status) {
        if (errors.hasErrors) {
            // ...
        }
        status.setComplete(); (2)
        // ...
    }
}

@Controller
@SessionAttributes("pet") (1)
class EditPetForm {

    // ...

    @PostMapping("/pets/{id}")
    fun handle(pet: Pet, errors: BindingResult, status: SessionStatus): String {
        if (errors.hasErrors()) {
            // ...
        }
        status.setComplete() (2)
        // ...
    }
}

@SessionAttribute

If you need access to pre-existing session attributes that are managed globally
(that is, outside the controller — for example, by a filter) and may or may not be present,
you can use the @SessionAttribute annotation on a method parameter,
as the following example shows:

@RequestMapping("/")
public String handle(@SessionAttribute User user) { (1)
    // ...
}

@RequestMapping("/")
fun handle(@SessionAttribute user: User): String { (1)
    // ...
}

For use cases that require adding or removing session attributes, consider injecting
org.springframework.web.context.request.WebRequest or
jakarta.servlet.http.HttpSession into the controller method.

For temporary storage of model attributes in the session as part of a controller
workflow, consider using @SessionAttributes as described in
@SessionAttributes.

@RequestAttribute

Similar to @SessionAttribute, you can use the @RequestAttribute annotations to
access pre-existing request attributes created earlier (for example, by a Servlet Filter
or HandlerInterceptor):

@GetMapping("/")
public String handle(@RequestAttribute Client client) { (1)
    // ...
}

@GetMapping("/")
fun handle(@RequestAttribute client: Client): String { (1)
    // ...
}

Redirect Attributes

By default, all model attributes are considered to be exposed as URI template variables in
the redirect URL. Of the remaining attributes, those that are primitive types or
collections or arrays of primitive types are automatically appended as query parameters.

Appending primitive type attributes as query parameters can be the desired result if a
model instance was prepared specifically for the redirect. However, in annotated
controllers, the model can contain additional attributes added for rendering purposes (for example,
drop-down field values). To avoid the possibility of having such attributes appear in the
URL, a @RequestMapping method can declare an argument of type RedirectAttributes and
use it to specify the exact attributes to make available to RedirectView. If the method
does redirect, the content of RedirectAttributes is used. Otherwise, the content of the
model is used.

The RequestMappingHandlerAdapter provides a flag called
ignoreDefaultModelOnRedirect, which you can use to indicate that the content of the default
Model should never be used if a controller method redirects. Instead, the controller
method should declare an attribute of type RedirectAttributes or, if it does not do so,
no attributes should be passed on to RedirectView. Both the MVC namespace and the MVC
Java configuration keep this flag set to false, to maintain backwards compatibility.
However, for new applications, we recommend setting it to true.

Note that URI template variables from the present request are automatically made
available when expanding a redirect URL, and you don’t need to explicitly add them
through Model or RedirectAttributes. The following example shows how to define a redirect:

@PostMapping("/files/{path}")
public String upload(...) {
    // ...
    return "redirect:files/{path}";
}

@PostMapping("/files/{path}")
fun upload(...): String {
    // ...
    return "redirect:files/{path}"
}

Another way of passing data to the redirect target is by using flash attributes. Unlike
other redirect attributes, flash attributes are saved in the HTTP session (and, hence, do
not appear in the URL). See Flash Attributes for more information.

Flash Attributes

Flash attributes provide a way for one request to store attributes that are intended for use in
another. This is most commonly needed when redirecting — for example, the
Post-Redirect-Get pattern. Flash attributes are saved temporarily before the
redirect (typically in the session) to be made available to the request after the
redirect and are removed immediately.

Spring MVC has two main abstractions in support of flash attributes. FlashMap is used
to hold flash attributes, while FlashMapManager is used to store, retrieve, and manage
FlashMap instances.

Flash attribute support is always “on” and does not need to be enabled explicitly.
However, if not used, it never causes HTTP session creation. On each request, there is an
“input” FlashMap with attributes passed from a previous request (if any) and an
“output” FlashMap with attributes to save for a subsequent request. Both FlashMap
instances are accessible from anywhere in Spring MVC through static methods in
RequestContextUtils.

Annotated controllers typically do not need to work with FlashMap directly. Instead, a
@RequestMapping method can accept an argument of type RedirectAttributes and use it
to add flash attributes for a redirect scenario. Flash attributes added through
RedirectAttributes are automatically propagated to the “output” FlashMap. Similarly,
after the redirect, attributes from the “input” FlashMap are automatically added to the
Model of the controller that serves the target URL.

Multipart

After a MultipartResolver has been enabled, the content of POST
requests with multipart/form-data is parsed and accessible as regular request
parameters. The following example accesses one regular form field and one uploaded
file:

@Controller
public class FileUploadController {

    @PostMapping("/form")
    public String handleFormUpload(@RequestParam("name") String name,
            @RequestParam("file") MultipartFile file) {

        if (!file.isEmpty()) {
            byte[] bytes = file.getBytes();
            // store the bytes somewhere
            return "redirect:uploadSuccess";
        }
        return "redirect:uploadFailure";
    }
}

@Controller
class FileUploadController {

    @PostMapping("/form")
    fun handleFormUpload(@RequestParam("name") name: String,
                        @RequestParam("file") file: MultipartFile): String {

        if (!file.isEmpty) {
            val bytes = file.bytes
            // store the bytes somewhere
            return "redirect:uploadSuccess"
        }
        return "redirect:uploadFailure"
    }
}

Declaring the argument type as a List<MultipartFile> allows for resolving multiple
files for the same parameter name.

When the @RequestParam annotation is declared as a Map<String, MultipartFile> or
MultiValueMap<String, MultipartFile>, without a parameter name specified in the annotation,
then the map is populated with the multipart files for each given parameter name.

You can also use multipart content as part of data binding to a
command object. For example, the form field
and file from the preceding example could be fields on a form object,
as the following example shows:

class MyForm {

    private String name;

    private MultipartFile file;

    // ...
}

@Controller
public class FileUploadController {

    @PostMapping("/form")
    public String handleFormUpload(MyForm form, BindingResult errors) {
        if (!form.getFile().isEmpty()) {
            byte[] bytes = form.getFile().getBytes();
            // store the bytes somewhere
            return "redirect:uploadSuccess";
        }
        return "redirect:uploadFailure";
    }
}

class MyForm(val name: String, val file: MultipartFile, ...)

@Controller
class FileUploadController {

    @PostMapping("/form")
    fun handleFormUpload(form: MyForm, errors: BindingResult): String {
        if (!form.file.isEmpty) {
            val bytes = form.file.bytes
            // store the bytes somewhere
            return "redirect:uploadSuccess"
        }
        return "redirect:uploadFailure"
    }
}

Multipart requests can also be submitted from non-browser clients in a RESTful service
scenario. The following example shows a file with JSON:

POST /someUrl
Content-Type: multipart/mixed

--edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp
Content-Disposition: form-data; name="meta-data"
Content-Type: application/json; charset=UTF-8
Content-Transfer-Encoding: 8bit

{
    "name": "value"
}
--edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp
Content-Disposition: form-data; name="file-data"; filename="file.properties"
Content-Type: text/xml
Content-Transfer-Encoding: 8bit
... File Data ...

You can access the «meta-data» part with @RequestParam as a String but you’ll
probably want it deserialized from JSON (similar to @RequestBody). Use the
@RequestPart annotation to access a multipart after converting it with an
HttpMessageConverter:

@PostMapping("/")
public String handle(@RequestPart("meta-data") MetaData metadata,
        @RequestPart("file-data") MultipartFile file) {
    // ...
}

@PostMapping("/")
fun handle(@RequestPart("meta-data") metadata: MetaData,
        @RequestPart("file-data") file: MultipartFile): String {
    // ...
}

You can use @RequestPart in combination with jakarta.validation.Valid or use Spring’s
@Validated annotation, both of which cause Standard Bean Validation to be applied.
By default, validation errors cause a MethodArgumentNotValidException, which is turned
into a 400 (BAD_REQUEST) response. Alternatively, you can handle validation errors locally
within the controller through an Errors or BindingResult argument,
as the following example shows:

@PostMapping("/")
public String handle(@Valid @RequestPart("meta-data") MetaData metadata,
        BindingResult result) {
    // ...
}

@PostMapping("/")
fun handle(@Valid @RequestPart("meta-data") metadata: MetaData,
        result: BindingResult): String {
    // ...
}

@RequestBody

You can use the @RequestBody annotation to have the request body read and deserialized into an
Object through an HttpMessageConverter.
The following example uses a @RequestBody argument:

@PostMapping("/accounts")
public void handle(@RequestBody Account account) {
    // ...
}

@PostMapping("/accounts")
fun handle(@RequestBody account: Account) {
    // ...
}

You can use the Message Converters option of the MVC Config to
configure or customize message conversion.

You can use @RequestBody in combination with jakarta.validation.Valid or Spring’s
@Validated annotation, both of which cause Standard Bean Validation to be applied.
By default, validation errors cause a MethodArgumentNotValidException, which is turned
into a 400 (BAD_REQUEST) response. Alternatively, you can handle validation errors locally
within the controller through an Errors or BindingResult argument,
as the following example shows:

@PostMapping("/accounts")
public void handle(@Valid @RequestBody Account account, BindingResult result) {
    // ...
}

@PostMapping("/accounts")
fun handle(@Valid @RequestBody account: Account, result: BindingResult) {
    // ...
}

HttpEntity

HttpEntity is more or less identical to using @RequestBody but is based on a
container object that exposes request headers and body. The following listing shows an example:

@PostMapping("/accounts")
public void handle(HttpEntity<Account> entity) {
    // ...
}

@PostMapping("/accounts")
fun handle(entity: HttpEntity<Account>) {
    // ...
}

@ResponseBody

You can use the @ResponseBody annotation on a method to have the return serialized
to the response body through an
HttpMessageConverter.
The following listing shows an example:

@GetMapping("/accounts/{id}")
@ResponseBody
public Account handle() {
    // ...
}

@GetMapping("/accounts/{id}")
@ResponseBody
fun handle(): Account {
    // ...
}

@ResponseBody is also supported at the class level, in which case it is inherited by
all controller methods. This is the effect of @RestController, which is nothing more
than a meta-annotation marked with @Controller and @ResponseBody.

You can use @ResponseBody with reactive types.
See Asynchronous Requests and Reactive Types for more details.

You can use the Message Converters option of the MVC Config to
configure or customize message conversion.

You can combine @ResponseBody methods with JSON serialization views.
See Jackson JSON for details.

ResponseEntity

ResponseEntity is like @ResponseBody but with status and headers. For example:

@GetMapping("/something")
public ResponseEntity<String> handle() {
    String body = ... ;
    String etag = ... ;
    return ResponseEntity.ok().eTag(etag).body(body);
}

@GetMapping("/something")
fun handle(): ResponseEntity<String> {
    val body = ...
    val etag = ...
    return ResponseEntity.ok().eTag(etag).build(body)
}

Spring MVC supports using a single value reactive type
to produce the ResponseEntity asynchronously, and/or single and multi-value reactive
types for the body. This allows the following types of async responses:

Jackson JSON

Spring offers support for the Jackson JSON library.

@RestController
public class UserController {

    @GetMapping("/user")
    @JsonView(User.WithoutPasswordView.class)
    public User getUser() {
        return new User("eric", "7!jd#h23");
    }
}

public class User {

    public interface WithoutPasswordView {};
    public interface WithPasswordView extends WithoutPasswordView {};

    private String username;
    private String password;

    public User() {
    }

    public User(String username, String password) {
        this.username = username;
        this.password = password;
    }

    @JsonView(WithoutPasswordView.class)
    public String getUsername() {
        return this.username;
    }

    @JsonView(WithPasswordView.class)
    public String getPassword() {
        return this.password;
    }
}

@RestController
class UserController {

    @GetMapping("/user")
    @JsonView(User.WithoutPasswordView::class)
    fun getUser() = User("eric", "7!jd#h23")
}

class User(
        @JsonView(WithoutPasswordView::class) val username: String,
        @JsonView(WithPasswordView::class) val password: String) {

    interface WithoutPasswordView
    interface WithPasswordView : WithoutPasswordView
}

@RestController
public class UserController {

    @GetMapping("/user")
    public MappingJacksonValue getUser() {
        User user = new User("eric", "7!jd#h23");
        MappingJacksonValue value = new MappingJacksonValue(user);
        value.setSerializationView(User.WithoutPasswordView.class);
        return value;
    }
}

@RestController
class UserController {

    @GetMapping("/user")
    fun getUser(): MappingJacksonValue {
        val value = MappingJacksonValue(User("eric", "7!jd#h23"))
        value.serializationView = User.WithoutPasswordView::class.java
        return value
    }
}

@Controller
public class UserController extends AbstractController {

    @GetMapping("/user")
    public String getUser(Model model) {
        model.addAttribute("user", new User("eric", "7!jd#h23"));
        model.addAttribute(JsonView.class.getName(), User.WithoutPasswordView.class);
        return "userView";
    }
}

@Controller
class UserController : AbstractController() {

    @GetMapping("/user")
    fun getUser(model: Model): String {
        model["user"] = User("eric", "7!jd#h23")
        model[JsonView::class.qualifiedName] = User.WithoutPasswordView::class.java
        return "userView"
    }
}

• On a method argument in @RequestMapping methods
  to create or access an Object from the model and to bind it to the request through a
  WebDataBinder.

• As a method-level annotation in @Controller or @ControllerAdvice classes that help
  to initialize the model prior to any @RequestMapping method invocation.

• On a @RequestMapping method to mark its return value is a model attribute.

Java

@ModelAttribute
public void populateModel(@RequestParam String number, Model model) {
    model.addAttribute(accountRepository.findAccount(number));
    // add more ...
}

Kotlin

@ModelAttribute
fun populateModel(@RequestParam number: String, model: Model) {
    model.addAttribute(accountRepository.findAccount(number))
    // add more ...
}

Java

@ModelAttribute
public Account addAccount(@RequestParam String number) {
    return accountRepository.findAccount(number);
}

Kotlin

@ModelAttribute
fun addAccount(@RequestParam number: String): Account {
    return accountRepository.findAccount(number)
}

Java

@GetMapping("/accounts/{id}")
@ModelAttribute("myAccount")
public Account handle() {
    // ...
    return account;
}

Kotlin

@GetMapping("/accounts/{id}")
@ModelAttribute("myAccount")
fun handle(): Account {
    // ...
    return account
}

• Bind request parameters (that is, form or query data) to a model object.

• Convert String-based request values (such as request parameters, path variables,
  headers, cookies, and others) to the target type of controller method arguments.

• Format model object values as String values when rendering HTML forms.

Java

@Controller
public class FormController {

    @InitBinder (1)
    public void initBinder(WebDataBinder binder) {
        SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
        dateFormat.setLenient(false);
        binder.registerCustomEditor(Date.class, new CustomDateEditor(dateFormat, false));
    }

    // ...
}

Kotlin

@Controller
class FormController {

    @InitBinder (1)
    fun initBinder(binder: WebDataBinder) {
        val dateFormat = SimpleDateFormat("yyyy-MM-dd")
        dateFormat.isLenient = false
        binder.registerCustomEditor(Date::class.java, CustomDateEditor(dateFormat, false))
    }

    // ...
}

Java

@Controller
public class FormController {

    @InitBinder (1)
    protected void initBinder(WebDataBinder binder) {
        binder.addCustomFormatter(new DateFormatter("yyyy-MM-dd"));
    }

    // ...
}

Kotlin

@Controller
class FormController {

    @InitBinder (1)
    protected fun initBinder(binder: WebDataBinder) {
        binder.addCustomFormatter(DateFormatter("yyyy-MM-dd"))
    }

    // ...
}

Model Design

In the context of web applications, data binding involves the binding of HTTP request
parameters (that is, form data or query parameters) to properties in a model object and
its nested objects.

Only public properties following the
JavaBeans naming conventions
are exposed for data binding — for example, public String getFirstName() and
public void setFirstName(String) methods for a firstName property.

By default, Spring permits binding to all public properties in the model object graph.
This means you need to carefully consider what public properties the model has, since a
client could target any public property path, even some that are not expected to be
targeted for a given use case.

For example, given an HTTP form data endpoint, a malicious client could supply values for
properties that exist in the model object graph but are not part of the HTML form
presented in the browser. This could lead to data being set on the model object and any
of its nested objects, that is not expected to be updated.

The recommended approach is to use a dedicated model object that exposes only
properties that are relevant for the form submission. For example, on a form for changing
a user’s email address, the model object should declare a minimum set of properties such
as in the following ChangeEmailForm.

public class ChangeEmailForm {

    private String oldEmailAddress;
    private String newEmailAddress;

    public void setOldEmailAddress(String oldEmailAddress) {
        this.oldEmailAddress = oldEmailAddress;
    }

    public String getOldEmailAddress() {
        return this.oldEmailAddress;
    }

    public void setNewEmailAddress(String newEmailAddress) {
        this.newEmailAddress = newEmailAddress;
    }

    public String getNewEmailAddress() {
        return this.newEmailAddress;
    }

}

If you cannot or do not want to use a dedicated model object for each data
binding use case, you must limit the properties that are allowed for data binding.
Ideally, you can achieve this by registering allowed field patterns via the
setAllowedFields() method on WebDataBinder.

For example, to register allowed field patterns in your application, you can implement an
@InitBinder method in a @Controller or @ControllerAdvice component as shown below:

@Controller
public class ChangeEmailController {

    @InitBinder
    void initBinder(WebDataBinder binder) {
        binder.setAllowedFields("oldEmailAddress", "newEmailAddress");
    }

    // @RequestMapping methods, etc.

}

In addition to registering allowed patterns, it is also possible to register disallowed
field patterns via the setDisallowedFields() method in DataBinder and its subclasses.
Please note, however, that an «allow list» is safer than a «deny list». Consequently,
setAllowedFields() should be favored over setDisallowedFields().

Note that matching against allowed field patterns is case-sensitive; whereas, matching
against disallowed field patterns is case-insensitive. In addition, a field matching a
disallowed pattern will not be accepted even if it also happens to match a pattern in the
allowed list.

Java

@Controller
public class SimpleController {

    // ...

    @ExceptionHandler
    public ResponseEntity<String> handle(IOException ex) {
        // ...
    }
}

Kotlin

@Controller
class SimpleController {

    // ...

    @ExceptionHandler
    fun handle(ex: IOException): ResponseEntity<String> {
        // ...
    }
}

Java

@ExceptionHandler({FileSystemException.class, RemoteException.class})
public ResponseEntity<String> handle(IOException ex) {
    // ...
}

Kotlin

@ExceptionHandler(FileSystemException::class, RemoteException::class)
fun handle(ex: IOException): ResponseEntity<String> {
    // ...
}

Java

@ExceptionHandler({FileSystemException.class, RemoteException.class})
public ResponseEntity<String> handle(Exception ex) {
    // ...
}

Kotlin

@ExceptionHandler(FileSystemException::class, RemoteException::class)
fun handle(ex: Exception): ResponseEntity<String> {
    // ...
}

Method Arguments

@ExceptionHandler methods support the following arguments:

Return Values

@ExceptionHandler methods support the following return values:

Java

// Target all Controllers annotated with @RestController
@ControllerAdvice(annotations = RestController.class)
public class ExampleAdvice1 {}

// Target all Controllers within specific packages
@ControllerAdvice("org.example.controllers")
public class ExampleAdvice2 {}

// Target all Controllers assignable to specific classes
@ControllerAdvice(assignableTypes = {ControllerInterface.class, AbstractController.class})
public class ExampleAdvice3 {}

Kotlin

// Target all Controllers annotated with @RestController
@ControllerAdvice(annotations = [RestController::class])
class ExampleAdvice1

// Target all Controllers within specific packages
@ControllerAdvice("org.example.controllers")
class ExampleAdvice2

// Target all Controllers assignable to specific classes
@ControllerAdvice(assignableTypes = [ControllerInterface::class, AbstractController::class])
class ExampleAdvice3

Java

import static org.springframework.http.MediaType.APPLICATION_JSON;
import static org.springframework.web.servlet.function.RequestPredicates.*;
import static org.springframework.web.servlet.function.RouterFunctions.route;

PersonRepository repository = ...
PersonHandler handler = new PersonHandler(repository);

RouterFunction<ServerResponse> route = route() (1)
    .GET("/person/{id}", accept(APPLICATION_JSON), handler::getPerson)
    .GET("/person", accept(APPLICATION_JSON), handler::listPeople)
    .POST("/person", handler::createPerson)
    .build();


public class PersonHandler {

    // ...

    public ServerResponse listPeople(ServerRequest request) {
        // ...
    }

    public ServerResponse createPerson(ServerRequest request) {
        // ...
    }

    public ServerResponse getPerson(ServerRequest request) {
        // ...
    }
}

Kotlin

import org.springframework.web.servlet.function.router

val repository: PersonRepository = ...
val handler = PersonHandler(repository)

val route = router { (1)
    accept(APPLICATION_JSON).nest {
        GET("/person/{id}", handler::getPerson)
        GET("/person", handler::listPeople)
    }
    POST("/person", handler::createPerson)
}


class PersonHandler(private val repository: PersonRepository) {

    // ...

    fun listPeople(request: ServerRequest): ServerResponse {
        // ...
    }

    fun createPerson(request: ServerRequest): ServerResponse {
        // ...
    }

    fun getPerson(request: ServerRequest): ServerResponse {
        // ...
    }
}

ServerRequest

ServerRequest provides access to the HTTP method, URI, headers, and query parameters,
while access to the body is provided through the body methods.

The following example extracts the request body to a String:

String string = request.body(String.class);

val string = request.body<String>()

The following example extracts the body to a List<Person>,
where Person objects are decoded from a serialized form, such as JSON or XML:

List<Person> people = request.body(new ParameterizedTypeReference<List<Person>>() {});

val people = request.body<Person>()

The following example shows how to access parameters:

MultiValueMap<String, String> params = request.params();

val map = request.params()

ServerResponse

ServerResponse provides access to the HTTP response and, since it is immutable, you can use
a build method to create it. You can use the builder to set the response status, to add response
headers, or to provide a body. The following example creates a 200 (OK) response with JSON
content:

Person person = ...
ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person);

val person: Person = ...
ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person)

The following example shows how to build a 201 (CREATED) response with a Location header and no body:

URI location = ...
ServerResponse.created(location).build();

val location: URI = ...
ServerResponse.created(location).build()

You can also use an asynchronous result as the body, in the form of a CompletableFuture,
Publisher, or any other type supported by the ReactiveAdapterRegistry. For instance:

Mono<Person> person = webClient.get().retrieve().bodyToMono(Person.class);
ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person);

val person = webClient.get().retrieve().awaitBody<Person>()
ServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person)

If not just the body, but also the status or headers are based on an asynchronous type,
you can use the static async method on ServerResponse, which
accepts CompletableFuture<ServerResponse>, Publisher<ServerResponse>, or
any other asynchronous type supported by the ReactiveAdapterRegistry. For instance:

Mono<ServerResponse> asyncResponse = webClient.get().retrieve().bodyToMono(Person.class)
  .map(p -> ServerResponse.ok().header("Name", p.name()).body(p));
ServerResponse.async(asyncResponse);

Server-Sent Events can be provided via the
static sse method on ServerResponse. The builder provided by that method
allows you to send Strings, or other objects as JSON. For example:

public RouterFunction<ServerResponse> sse() {
    return route(GET("/sse"), request -> ServerResponse.sse(sseBuilder -> {
                // Save the sseBuilder object somewhere..
            }));
}

// In some other thread, sending a String
sseBuilder.send("Hello world");

// Or an object, which will be transformed into JSON
Person person = ...
sseBuilder.send(person);

// Customize the event by using the other methods
sseBuilder.id("42")
        .event("sse event")
        .data(person);

// and done at some point
sseBuilder.complete();

fun sse(): RouterFunction<ServerResponse> = router {
    GET("/sse") { request -> ServerResponse.sse { sseBuilder ->
        // Save the sseBuilder object somewhere..
    }
}

// In some other thread, sending a String
sseBuilder.send("Hello world")

// Or an object, which will be transformed into JSON
val person = ...
sseBuilder.send(person)

// Customize the event by using the other methods
sseBuilder.id("42")
        .event("sse event")
        .data(person)

// and done at some point
sseBuilder.complete()

Handler Classes

We can write a handler function as a lambda, as the following example shows:

HandlerFunction<ServerResponse> helloWorld =
  request -> ServerResponse.ok().body("Hello World");

val helloWorld: (ServerRequest) -> ServerResponse =
  { ServerResponse.ok().body("Hello World") }

That is convenient, but in an application we need multiple functions, and multiple inline
lambda’s can get messy.
Therefore, it is useful to group related handler functions together into a handler class, which
has a similar role as @Controller in an annotation-based application.
For example, the following class exposes a reactive Person repository:

import static org.springframework.http.MediaType.APPLICATION_JSON;
import static org.springframework.web.reactive.function.server.ServerResponse.ok;

public class PersonHandler {

    private final PersonRepository repository;

    public PersonHandler(PersonRepository repository) {
        this.repository = repository;
    }

    public ServerResponse listPeople(ServerRequest request) { (1)
        List<Person> people = repository.allPeople();
        return ok().contentType(APPLICATION_JSON).body(people);
    }

    public ServerResponse createPerson(ServerRequest request) throws Exception { (2)
        Person person = request.body(Person.class);
        repository.savePerson(person);
        return ok().build();
    }

    public ServerResponse getPerson(ServerRequest request) { (3)
        int personId = Integer.parseInt(request.pathVariable("id"));
        Person person = repository.getPerson(personId);
        if (person != null) {
            return ok().contentType(APPLICATION_JSON).body(person);
        }
        else {
            return ServerResponse.notFound().build();
        }
    }

}

class PersonHandler(private val repository: PersonRepository) {

    fun listPeople(request: ServerRequest): ServerResponse { (1)
        val people: List<Person> = repository.allPeople()
        return ok().contentType(APPLICATION_JSON).body(people);
    }

    fun createPerson(request: ServerRequest): ServerResponse { (2)
        val person = request.body<Person>()
        repository.savePerson(person)
        return ok().build()
    }

    fun getPerson(request: ServerRequest): ServerResponse { (3)
        val personId = request.pathVariable("id").toInt()
        return repository.getPerson(personId)?.let { ok().contentType(APPLICATION_JSON).body(it) }
                ?: ServerResponse.notFound().build()

    }
}

Validation

A functional endpoint can use Spring’s validation facilities to
apply validation to the request body. For example, given a custom Spring
Validator implementation for a Person:

public class PersonHandler {

    private final Validator validator = new PersonValidator(); (1)

    // ...

    public ServerResponse createPerson(ServerRequest request) {
        Person person = request.body(Person.class);
        validate(person); (2)
        repository.savePerson(person);
        return ok().build();
    }

    private void validate(Person person) {
        Errors errors = new BeanPropertyBindingResult(person, "person");
        validator.validate(person, errors);
        if (errors.hasErrors()) {
            throw new ServerWebInputException(errors.toString()); (3)
        }
    }
}

class PersonHandler(private val repository: PersonRepository) {

    private val validator = PersonValidator() (1)

    // ...

    fun createPerson(request: ServerRequest): ServerResponse {
        val person = request.body<Person>()
        validate(person) (2)
        repository.savePerson(person)
        return ok().build()
    }

    private fun validate(person: Person) {
        val errors: Errors = BeanPropertyBindingResult(person, "person")
        validator.validate(person, errors)
        if (errors.hasErrors()) {
            throw ServerWebInputException(errors.toString()) (3)
        }
    }
}

Handlers can also use the standard bean validation API (JSR-303) by creating and injecting
a global Validator instance based on LocalValidatorFactoryBean.
See Spring Validation.

Predicates

You can write your own RequestPredicate, but the RequestPredicates utility class
offers commonly used implementations, based on the request path, HTTP method, content-type,
and so on.
The following example uses a request predicate to create a constraint based on the Accept
header:

RouterFunction<ServerResponse> route = RouterFunctions.route()
    .GET("/hello-world", accept(MediaType.TEXT_PLAIN),
        request -> ServerResponse.ok().body("Hello World")).build();

import org.springframework.web.servlet.function.router

val route = router {
    GET("/hello-world", accept(TEXT_PLAIN)) {
        ServerResponse.ok().body("Hello World")
    }
}

You can compose multiple request predicates together by using:

Many of the predicates from RequestPredicates are composed.
For example, RequestPredicates.GET(String) is composed from RequestPredicates.method(HttpMethod)
and RequestPredicates.path(String).
The example shown above also uses two request predicates, as the builder uses
RequestPredicates.GET internally, and composes that with the accept predicate.

Routes

Router functions are evaluated in order: if the first route does not match, the
second is evaluated, and so on.
Therefore, it makes sense to declare more specific routes before general ones.
This is also important when registering router functions as Spring beans, as will
be described later.
Note that this behavior is different from the annotation-based programming model, where the
«most specific» controller method is picked automatically.

When using the router function builder, all defined routes are composed into one
RouterFunction that is returned from build().
There are also other ways to compose multiple router functions together:

The following example shows the composition of four routes:

import static org.springframework.http.MediaType.APPLICATION_JSON;
import static org.springframework.web.servlet.function.RequestPredicates.*;

PersonRepository repository = ...
PersonHandler handler = new PersonHandler(repository);

RouterFunction<ServerResponse> otherRoute = ...

RouterFunction<ServerResponse> route = route()
    .GET("/person/{id}", accept(APPLICATION_JSON), handler::getPerson) (1)
    .GET("/person", accept(APPLICATION_JSON), handler::listPeople) (2)
    .POST("/person", handler::createPerson) (3)
    .add(otherRoute) (4)
    .build();

import org.springframework.http.MediaType.APPLICATION_JSON
import org.springframework.web.servlet.function.router

val repository: PersonRepository = ...
val handler = PersonHandler(repository);

val otherRoute = router {  }

val route = router {
    GET("/person/{id}", accept(APPLICATION_JSON), handler::getPerson) (1)
    GET("/person", accept(APPLICATION_JSON), handler::listPeople) (2)
    POST("/person", handler::createPerson) (3)
}.and(otherRoute) (4)

Nested Routes

It is common for a group of router functions to have a shared predicate, for instance a shared
path.
In the example above, the shared predicate would be a path predicate that matches /person,
used by three of the routes.
When using annotations, you would remove this duplication by using a type-level @RequestMapping
annotation that maps to /person.
In WebMvc.fn, path predicates can be shared through the path method on the router function builder.
For instance, the last few lines of the example above can be improved in the following way by using nested routes:

RouterFunction<ServerResponse> route = route()
    .path("/person", builder -> builder (1)
        .GET("/{id}", accept(APPLICATION_JSON), handler::getPerson)
        .GET(accept(APPLICATION_JSON), handler::listPeople)
        .POST(handler::createPerson))
    .build();

import org.springframework.web.servlet.function.router

val route = router {
    "/person".nest { (1)
        GET("/{id}", accept(APPLICATION_JSON), handler::getPerson)
        GET(accept(APPLICATION_JSON), handler::listPeople)
        POST(handler::createPerson)
    }
}

Though path-based nesting is the most common, you can nest on any kind of predicate by using
the nest method on the builder.
The above still contains some duplication in the form of the shared Accept-header predicate.
We can further improve by using the nest method together with accept:

RouterFunction<ServerResponse> route = route()
    .path("/person", b1 -> b1
        .nest(accept(APPLICATION_JSON), b2 -> b2
            .GET("/{id}", handler::getPerson)
            .GET(handler::listPeople))
        .POST(handler::createPerson))
    .build();

import org.springframework.web.servlet.function.router

val route = router {
    "/person".nest {
        accept(APPLICATION_JSON).nest {
            GET("/{id}", handler::getPerson)
            GET("", handler::listPeople)
            POST(handler::createPerson)
        }
    }
}

• RouterFunctionMapping: Detects one or more RouterFunction<?> beans in the Spring
  configuration, orders them, combines them through
  RouterFunction.andOther, and routes requests to the resulting composed RouterFunction.

• HandlerFunctionAdapter: Simple adapter that lets DispatcherHandler invoke
  a HandlerFunction that was mapped to a request.

Java

@Configuration
@EnableMvc
public class WebConfig implements WebMvcConfigurer {

    @Bean
    public RouterFunction<?> routerFunctionA() {
        // ...
    }

    @Bean
    public RouterFunction<?> routerFunctionB() {
        // ...
    }

    // ...

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        // configure message conversion...
    }

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        // configure CORS...
    }

    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        // configure view resolution for HTML rendering...
    }
}

Kotlin

@Configuration
@EnableMvc
class WebConfig : WebMvcConfigurer {

    @Bean
    fun routerFunctionA(): RouterFunction<*> {
        // ...
    }

    @Bean
    fun routerFunctionB(): RouterFunction<*> {
        // ...
    }

    // ...

    override fun configureMessageConverters(converters: List<HttpMessageConverter<*>>) {
        // configure message conversion...
    }

    override fun addCorsMappings(registry: CorsRegistry) {
        // configure CORS...
    }

    override fun configureViewResolvers(registry: ViewResolverRegistry) {
        // configure view resolution for HTML rendering...
    }
}

Java

RouterFunction<ServerResponse> route = route()
    .path("/person", b1 -> b1
        .nest(accept(APPLICATION_JSON), b2 -> b2
            .GET("/{id}", handler::getPerson)
            .GET(handler::listPeople)
            .before(request -> ServerRequest.from(request) (1)
                .header("X-RequestHeader", "Value")
                .build()))
        .POST(handler::createPerson))
    .after((request, response) -> logResponse(response)) (2)
    .build();

Kotlin

import org.springframework.web.servlet.function.router

val route = router {
    "/person".nest {
        GET("/{id}", handler::getPerson)
        GET(handler::listPeople)
        before { (1)
            ServerRequest.from(it)
                    .header("X-RequestHeader", "Value").build()
        }
    }
    POST(handler::createPerson)
    after { _, response -> (2)
        logResponse(response)
    }
}

Java

SecurityManager securityManager = ...

RouterFunction<ServerResponse> route = route()
    .path("/person", b1 -> b1
        .nest(accept(APPLICATION_JSON), b2 -> b2
            .GET("/{id}", handler::getPerson)
            .GET(handler::listPeople))
        .POST(handler::createPerson))
    .filter((request, next) -> {
        if (securityManager.allowAccessTo(request.path())) {
            return next.handle(request);
        }
        else {
            return ServerResponse.status(UNAUTHORIZED).build();
        }
    })
    .build();

Kotlin

import org.springframework.web.servlet.function.router

val securityManager: SecurityManager = ...

val route = router {
    ("/person" and accept(APPLICATION_JSON)).nest {
        GET("/{id}", handler::getPerson)
        GET("", handler::listPeople)
        POST(handler::createPerson)
        filter { request, next ->
            if (securityManager.allowAccessTo(request.path())) {
                next(request)
            }
            else {
                status(UNAUTHORIZED).build();
            }
        }
    }
}

Java

UriComponents uriComponents = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}") (1)
        .queryParam("q", "{q}") (2)
        .encode() (3)
        .build(); (4)

URI uri = uriComponents.expand("Westin", "123").toUri(); (5)

Kotlin

val uriComponents = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}") (1)
        .queryParam("q", "{q}") (2)
        .encode() (3)
        .build() (4)

val uri = uriComponents.expand("Westin", "123").toUri() (5)

Java

URI uri = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}")
        .queryParam("q", "{q}")
        .encode()
        .buildAndExpand("Westin", "123")
        .toUri();

Kotlin

val uri = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}")
        .queryParam("q", "{q}")
        .encode()
        .buildAndExpand("Westin", "123")
        .toUri()

Java

URI uri = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}")
        .queryParam("q", "{q}")
        .build("Westin", "123");

Kotlin

val uri = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}")
        .queryParam("q", "{q}")
        .build("Westin", "123")

Java

URI uri = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}?q={q}")
        .build("Westin", "123");

Kotlin

val uri = UriComponentsBuilder
        .fromUriString("https://example.com/hotels/{hotel}?q={q}")
        .build("Westin", "123")

Java

// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;

String baseUrl = "https://example.org";
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);

RestTemplate restTemplate = new RestTemplate();
restTemplate.setUriTemplateHandler(factory);

Kotlin

// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode

val baseUrl = "https://example.org"
val factory = DefaultUriBuilderFactory(baseUrl)
factory.encodingMode = EncodingMode.TEMPLATE_AND_VALUES

val restTemplate = RestTemplate()
restTemplate.uriTemplateHandler = factory

Java

// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;

String baseUrl = "https://example.org";
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);

WebClient client = WebClient.builder().uriBuilderFactory(factory).build();

Kotlin

// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode

val baseUrl = "https://example.org"
val factory = DefaultUriBuilderFactory(baseUrl)
factory.encodingMode = EncodingMode.TEMPLATE_AND_VALUES

val client = WebClient.builder().uriBuilderFactory(factory).build()

Java

String baseUrl = "https://example.com";
DefaultUriBuilderFactory uriBuilderFactory = new DefaultUriBuilderFactory(baseUrl);

URI uri = uriBuilderFactory.uriString("/hotels/{hotel}")
        .queryParam("q", "{q}")
        .build("Westin", "123");

Kotlin

val baseUrl = "https://example.com"
val uriBuilderFactory = DefaultUriBuilderFactory(baseUrl)

val uri = uriBuilderFactory.uriString("/hotels/{hotel}")
        .queryParam("q", "{q}")
        .build("Westin", "123")

• UriComponentsBuilder#encode():
  Pre-encodes the URI template first and then strictly encodes URI variables when expanded.

• UriComponents#encode():
  Encodes URI components after URI variables are expanded.

Java

URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
        .queryParam("q", "{q}")
        .encode()
        .buildAndExpand("New York", "foo+bar")
        .toUri();

// Result is "/hotel%20list/New%20York?q=foo%2Bbar"

Kotlin

val uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
        .queryParam("q", "{q}")
        .encode()
        .buildAndExpand("New York", "foo+bar")
        .toUri()

// Result is "/hotel%20list/New%20York?q=foo%2Bbar"

Java

URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
        .queryParam("q", "{q}")
        .build("New York", "foo+bar");

Kotlin

val uri = UriComponentsBuilder.fromPath("/hotel list/{city}")
        .queryParam("q", "{q}")
        .build("New York", "foo+bar")

Java

URI uri = UriComponentsBuilder.fromUriString("/hotel list/{city}?q={q}")
        .build("New York", "foo+bar");

Kotlin

val uri = UriComponentsBuilder.fromUriString("/hotel list/{city}?q={q}")
        .build("New York", "foo+bar")

Java

String baseUrl = "https://example.com";
DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl)
factory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);

// Customize the RestTemplate..
RestTemplate restTemplate = new RestTemplate();
restTemplate.setUriTemplateHandler(factory);

// Customize the WebClient..
WebClient client = WebClient.builder().uriBuilderFactory(factory).build();

Kotlin

val baseUrl = "https://example.com"
val factory = DefaultUriBuilderFactory(baseUrl).apply {
    encodingMode = EncodingMode.TEMPLATE_AND_VALUES
}

// Customize the RestTemplate..
val restTemplate = RestTemplate().apply {
    uriTemplateHandler = factory
}

// Customize the WebClient..
val client = WebClient.builder().uriBuilderFactory(factory).build()

• TEMPLATE_AND_VALUES: Uses UriComponentsBuilder#encode(), corresponding to
  the first option in the earlier list, to pre-encode the URI template and strictly encode URI variables when
  expanded.

• VALUES_ONLY: Does not encode the URI template and, instead, applies strict encoding
  to URI variables through UriUtils#encodeUriVariables prior to expanding them into the
  template.

• URI_COMPONENT: Uses UriComponents#encode(), corresponding to the second option in the earlier list, to
  encode URI component value after URI variables are expanded.

• NONE: No encoding is applied.

Java

HttpServletRequest request = ...

// Re-uses scheme, host, port, path, and query string...

URI uri = ServletUriComponentsBuilder.fromRequest(request)
        .replaceQueryParam("accountId", "{id}")
        .build("123");

Kotlin

val request: HttpServletRequest = ...

// Re-uses scheme, host, port, path, and query string...

val uri = ServletUriComponentsBuilder.fromRequest(request)
        .replaceQueryParam("accountId", "{id}")
        .build("123")

Java

HttpServletRequest request = ...

// Re-uses scheme, host, port, and context path...

URI uri = ServletUriComponentsBuilder.fromContextPath(request)
        .path("/accounts")
        .build()
        .toUri();

Kotlin

val request: HttpServletRequest = ...

// Re-uses scheme, host, port, and context path...

val uri = ServletUriComponentsBuilder.fromContextPath(request)
        .path("/accounts")
        .build()
        .toUri()

Java

HttpServletRequest request = ...

// Re-uses scheme, host, port, context path, and Servlet mapping prefix...

URI uri = ServletUriComponentsBuilder.fromServletMapping(request)
        .path("/accounts")
        .build()
        .toUri();

Kotlin

val request: HttpServletRequest = ...

// Re-uses scheme, host, port, context path, and Servlet mapping prefix...

val uri = ServletUriComponentsBuilder.fromServletMapping(request)
        .path("/accounts")
        .build()
        .toUri()

Java

@Controller
@RequestMapping("/hotels/{hotel}")
public class BookingController {

    @GetMapping("/bookings/{booking}")
    public ModelAndView getBooking(@PathVariable Long booking) {
        // ...
    }
}

Kotlin

@Controller
@RequestMapping("/hotels/{hotel}")
class BookingController {

    @GetMapping("/bookings/{booking}")
    fun getBooking(@PathVariable booking: Long): ModelAndView {
        // ...
    }
}

Java

UriComponents uriComponents = MvcUriComponentsBuilder
    .fromMethodName(BookingController.class, "getBooking", 21).buildAndExpand(42);

URI uri = uriComponents.encode().toUri();

Kotlin

val uriComponents = MvcUriComponentsBuilder
    .fromMethodName(BookingController::class.java, "getBooking", 21).buildAndExpand(42)

val uri = uriComponents.encode().toUri()

Java

UriComponents uriComponents = MvcUriComponentsBuilder
    .fromMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42);

URI uri = uriComponents.encode().toUri();

Kotlin

val uriComponents = MvcUriComponentsBuilder
    .fromMethodCall(on(BookingController::class.java).getBooking(21)).buildAndExpand(42)

val uri = uriComponents.encode().toUri()

Java

UriComponentsBuilder base = ServletUriComponentsBuilder.fromCurrentContextPath().path("/en");
MvcUriComponentsBuilder builder = MvcUriComponentsBuilder.relativeTo(base);
builder.withMethodCall(on(BookingController.class).getBooking(21)).buildAndExpand(42);

URI uri = uriComponents.encode().toUri();

Kotlin

val base = ServletUriComponentsBuilder.fromCurrentContextPath().path("/en")
val builder = MvcUriComponentsBuilder.relativeTo(base)
builder.withMethodCall(on(BookingController::class.java).getBooking(21)).buildAndExpand(42)

val uri = uriComponents.encode().toUri()

Java

@RequestMapping("/people/{id}/addresses")
public class PersonAddressController {

    @RequestMapping("/{country}")
    public HttpEntity<PersonAddress> getAddress(@PathVariable String country) { ... }
}

Kotlin

@RequestMapping("/people/{id}/addresses")
class PersonAddressController {

    @RequestMapping("/{country}")
    fun getAddress(@PathVariable country: String): HttpEntity<PersonAddress> { ... }
}

<%@ taglib uri="http://www.springframework.org/tags" prefix="s" %>
...
<a href="${s:mvcUrl('PAC#getAddress').arg(0,'US').buildAndExpand('123')}">Get Address</a>

Java

@GetMapping("/quotes")
@ResponseBody
public DeferredResult<String> quotes() {
    DeferredResult<String> deferredResult = new DeferredResult<String>();
    // Save the deferredResult somewhere..
    return deferredResult;
}

// From some other thread...
deferredResult.setResult(result);

Kotlin

@GetMapping("/quotes")
@ResponseBody
fun quotes(): DeferredResult<String> {
    val deferredResult = DeferredResult<String>()
    // Save the deferredResult somewhere..
    return deferredResult
}

// From some other thread...
deferredResult.setResult(result)

Java

@PostMapping
public Callable<String> processUpload(final MultipartFile file) {
    return () -> "someView";
}

Kotlin

@PostMapping
fun processUpload(file: MultipartFile) = Callable<String> {
    // ...
    "someView"
}

• A ServletRequest can be put in asynchronous mode by calling request.startAsync().
  The main effect of doing so is that the Servlet (as well as any filters) can exit, but
  the response remains open to let processing complete later.

• The call to request.startAsync() returns AsyncContext, which you can use for
  further control over asynchronous processing. For example, it provides the dispatch method,
  which is similar to a forward from the Servlet API, except that it lets an
  application resume request processing on a Servlet container thread.

• The ServletRequest provides access to the current DispatcherType, which you can
  use to distinguish between processing the initial request, an asynchronous
  dispatch, a forward, and other dispatcher types.

• The controller returns a DeferredResult and saves it in some in-memory
  queue or list where it can be accessed.

• Spring MVC calls request.startAsync().

• Meanwhile, the DispatcherServlet and all configured filters exit the request
  processing thread, but the response remains open.

• The application sets the DeferredResult from some thread, and Spring MVC
  dispatches the request back to the Servlet container.

• The DispatcherServlet is invoked again, and processing resumes with the
  asynchronously produced return value.

• The controller returns a Callable.

• Spring MVC calls request.startAsync() and submits the Callable to
  a TaskExecutor for processing in a separate thread.

• Meanwhile, the DispatcherServlet and all filters exit the Servlet container thread,
  but the response remains open.

• Eventually the Callable produces a result, and Spring MVC dispatches the request back
  to the Servlet container to complete processing.

• The DispatcherServlet is invoked again, and processing resumes with the
  asynchronously produced return value from the Callable.

Exception Handling

When you use a DeferredResult, you can choose whether to call setResult or
setErrorResult with an exception. In both cases, Spring MVC dispatches the request back
to the Servlet container to complete processing. It is then treated either as if the
controller method returned the given value or as if it produced the given exception.
The exception then goes through the regular exception handling mechanism (for example, invoking
@ExceptionHandler methods).

When you use Callable, similar processing logic occurs, the main difference being that
the result is returned from the Callable or an exception is raised by it.

Interception

HandlerInterceptor instances can be of type AsyncHandlerInterceptor, to receive the
afterConcurrentHandlingStarted callback on the initial request that starts asynchronous
processing (instead of postHandle and afterCompletion).

HandlerInterceptor implementations can also register a CallableProcessingInterceptor
or a DeferredResultProcessingInterceptor, to integrate more deeply with the
lifecycle of an asynchronous request (for example, to handle a timeout event). See
AsyncHandlerInterceptor
for more details.

DeferredResult provides onTimeout(Runnable) and onCompletion(Runnable) callbacks.
See the javadoc of DeferredResult
for more details. Callable can be substituted for WebAsyncTask that exposes additional
methods for timeout and completion callbacks.

Async Spring MVC compared to WebFlux

The Servlet API was originally built for making a single pass through the Filter-Servlet
chain. Asynchronous request processing lets applications exit the Filter-Servlet chain
but leave the response open for further processing. The Spring MVC asynchronous support
is built around that mechanism. When a controller returns a DeferredResult, the
Filter-Servlet chain is exited, and the Servlet container thread is released. Later, when
the DeferredResult is set, an ASYNC dispatch (to the same URL) is made, during which the
controller is mapped again but, rather than invoking it, the DeferredResult value is used
(as if the controller returned it) to resume processing.

By contrast, Spring WebFlux is neither built on the Servlet API, nor does it need such an
asynchronous request processing feature, because it is asynchronous by design. Asynchronous
handling is built into all framework contracts and is intrinsically supported through all
stages of request processing.

From a programming model perspective, both Spring MVC and Spring WebFlux support
asynchronous and Reactive Types as return values in controller methods.
Spring MVC even supports streaming, including reactive back pressure. However, individual
writes to the response remain blocking (and are performed on a separate thread), unlike WebFlux,
which relies on non-blocking I/O and does not need an extra thread for each write.

Another fundamental difference is that Spring MVC does not support asynchronous or reactive
types in controller method arguments (for example, @RequestBody, @RequestPart, and others),
nor does it have any explicit support for asynchronous and reactive types as model attributes.
Spring WebFlux does support all that.

Finally, from a configuration perspective the asynchronous request processing feature must be
enabled at the Servlet container level.

Objects

You can use the ResponseBodyEmitter return value to produce a stream of objects, where
each object is serialized with an
HttpMessageConverter and written to the
response, as the following example shows:

@GetMapping("/events")
public ResponseBodyEmitter handle() {
    ResponseBodyEmitter emitter = new ResponseBodyEmitter();
    // Save the emitter somewhere..
    return emitter;
}

// In some other thread
emitter.send("Hello once");

// and again later on
emitter.send("Hello again");

// and done at some point
emitter.complete();

@GetMapping("/events")
fun handle() = ResponseBodyEmitter().apply {
    // Save the emitter somewhere..
}

// In some other thread
emitter.send("Hello once")

// and again later on
emitter.send("Hello again")

// and done at some point
emitter.complete()

You can also use ResponseBodyEmitter as the body in a ResponseEntity, letting you
customize the status and headers of the response.

When an emitter throws an IOException (for example, if the remote client went away), applications
are not responsible for cleaning up the connection and should not invoke emitter.complete
or emitter.completeWithError. Instead, the servlet container automatically initiates an
AsyncListener error notification, in which Spring MVC makes a completeWithError call.
This call, in turn, performs one final ASYNC dispatch to the application, during which Spring MVC
invokes the configured exception resolvers and completes the request.

SSE

SseEmitter (a subclass of ResponseBodyEmitter) provides support for
Server-Sent Events, where events sent from the server
are formatted according to the W3C SSE specification. To produce an SSE
stream from a controller, return SseEmitter, as the following example shows:

@GetMapping(path="/events", produces=MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter handle() {
    SseEmitter emitter = new SseEmitter();
    // Save the emitter somewhere..
    return emitter;
}

// In some other thread
emitter.send("Hello once");

// and again later on
emitter.send("Hello again");

// and done at some point
emitter.complete();

@GetMapping("/events", produces = [MediaType.TEXT_EVENT_STREAM_VALUE])
fun handle() = SseEmitter().apply {
    // Save the emitter somewhere..
}

// In some other thread
emitter.send("Hello once")

// and again later on
emitter.send("Hello again")

// and done at some point
emitter.complete()

While SSE is the main option for streaming into browsers, note that Internet Explorer
does not support Server-Sent Events. Consider using Spring’s
WebSocket messaging with
SockJS fallback transports (including SSE) that target
a wide range of browsers.

See also previous section for notes on exception handling.

Raw Data

Sometimes, it is useful to bypass message conversion and stream directly to the response
OutputStream (for example, for a file download). You can use the StreamingResponseBody
return value type to do so, as the following example shows:

@GetMapping("/download")
public StreamingResponseBody handle() {
    return new StreamingResponseBody() {
        @Override
        public void writeTo(OutputStream outputStream) throws IOException {
            // write...
        }
    };
}

@GetMapping("/download")
fun handle() = StreamingResponseBody {
    // write...
}

You can use StreamingResponseBody as the body in a ResponseEntity to
customize the status and headers of the response.

• A single-value promise is adapted to, similar to using DeferredResult. Examples
  include Mono (Reactor) or Single (RxJava).

• A multi-value stream with a streaming media type (such as application/x-ndjson
  or text/event-stream) is adapted to, similar to using ResponseBodyEmitter or
  SseEmitter. Examples include Flux (Reactor) or Observable (RxJava).
  Applications can also return Flux<ServerSentEvent> or Observable<ServerSentEvent>.

• A multi-value stream with any other media type (such as application/json) is adapted
  to, similar to using DeferredResult<List<?>>.

Java

// Capture ThreadLocal values from the main thread ...
ContextSnapshot snapshot = ContextSnapshot.captureAll();

// On a different thread: restore ThreadLocal values
try (ContextSnapshot.Scope scoped = snapshot.setThreadLocals()) {
    // ...
}

Servlet Container

Filter and Servlet declarations have an asyncSupported flag that needs to be set to true
to enable asynchronous request processing. In addition, Filter mappings should be
declared to handle the ASYNC jakarta.servlet.DispatchType.

In Java configuration, when you use AbstractAnnotationConfigDispatcherServletInitializer
to initialize the Servlet container, this is done automatically.

In web.xml configuration, you can add <async-supported>true</async-supported> to the
DispatcherServlet and to Filter declarations and add
<dispatcher>ASYNC</dispatcher> to filter mappings.

Spring MVC

The MVC configuration exposes the following options related to asynchronous request processing:

You can configure the following:

Note that you can also set the default timeout value on a DeferredResult,
a ResponseBodyEmitter, and an SseEmitter. For a Callable, you can use
WebAsyncTask to provide a timeout value.

Java

@RestController
@RequestMapping("/account")
public class AccountController {

    @CrossOrigin
    @GetMapping("/{id}")
    public Account retrieve(@PathVariable Long id) {
        // ...
    }

    @DeleteMapping("/{id}")
    public void remove(@PathVariable Long id) {
        // ...
    }
}

Kotlin

@RestController
@RequestMapping("/account")
class AccountController {

    @CrossOrigin
    @GetMapping("/{id}")
    fun retrieve(@PathVariable id: Long): Account {
        // ...
    }

    @DeleteMapping("/{id}")
    fun remove(@PathVariable id: Long) {
        // ...
    }
}

• All origins.

• All headers.

• All HTTP methods to which the controller method is mapped.

Java

@CrossOrigin(origins = "https://domain2.com", maxAge = 3600)
@RestController
@RequestMapping("/account")
public class AccountController {

    @GetMapping("/{id}")
    public Account retrieve(@PathVariable Long id) {
        // ...
    }

    @DeleteMapping("/{id}")
    public void remove(@PathVariable Long id) {
        // ...
    }
}

Kotlin

@CrossOrigin(origins = ["https://domain2.com"], maxAge = 3600)
@RestController
@RequestMapping("/account")
class AccountController {

    @GetMapping("/{id}")
    fun retrieve(@PathVariable id: Long): Account {
        // ...
    }

    @DeleteMapping("/{id}")
    fun remove(@PathVariable id: Long) {
        // ...
    }

Java

@CrossOrigin(maxAge = 3600)
@RestController
@RequestMapping("/account")
public class AccountController {

    @CrossOrigin("https://domain2.com")
    @GetMapping("/{id}")
    public Account retrieve(@PathVariable Long id) {
        // ...
    }

    @DeleteMapping("/{id}")
    public void remove(@PathVariable Long id) {
        // ...
    }
}

Kotlin

@CrossOrigin(maxAge = 3600)
@RestController
@RequestMapping("/account")
class AccountController {

    @CrossOrigin("https://domain2.com")
    @GetMapping("/{id}")
    fun retrieve(@PathVariable id: Long): Account {
        // ...
    }

    @DeleteMapping("/{id}")
    fun remove(@PathVariable id: Long) {
        // ...
    }
}

• All origins.

• All headers.

• GET, HEAD, and POST methods.

Java Configuration

To enable CORS in the MVC Java config, you can use the CorsRegistry callback,
as the following example shows:

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {

        registry.addMapping("/api/**")
            .allowedOrigins("https://domain2.com")
            .allowedMethods("PUT", "DELETE")
            .allowedHeaders("header1", "header2", "header3")
            .exposedHeaders("header1", "header2")
            .allowCredentials(true).maxAge(3600);

        // Add more mappings...
    }
}

@Configuration
@EnableWebMvc
class WebConfig : WebMvcConfigurer {

    override fun addCorsMappings(registry: CorsRegistry) {

        registry.addMapping("/api/**")
                .allowedOrigins("https://domain2.com")
                .allowedMethods("PUT", "DELETE")
                .allowedHeaders("header1", "header2", "header3")
                .exposedHeaders("header1", "header2")
                .allowCredentials(true).maxAge(3600)

        // Add more mappings...
    }
}

XML Configuration

To enable CORS in the XML namespace, you can use the <mvc:cors> element,
as the following example shows:

<mvc:cors>

    <mvc:mapping path="/api/**"
        allowed-origins="https://domain1.com, https://domain2.com"
        allowed-methods="GET, PUT"
        allowed-headers="header1, header2, header3"
        exposed-headers="header1, header2" allow-credentials="true"
        max-age="123" />

    <mvc:mapping path="/resources/**"
        allowed-origins="https://domain1.com" />

</mvc:cors>

Java

CorsConfiguration config = new CorsConfiguration();

// Possibly...
// config.applyPermitDefaultValues()

config.setAllowCredentials(true);
config.addAllowedOrigin("https://domain1.com");
config.addAllowedHeader("*");
config.addAllowedMethod("*");

UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
source.registerCorsConfiguration("/**", config);

CorsFilter filter = new CorsFilter(source);

Kotlin

val config = CorsConfiguration()

// Possibly...
// config.applyPermitDefaultValues()

config.allowCredentials = true
config.addAllowedOrigin("https://domain1.com")
config.addAllowedHeader("*")
config.addAllowedMethod("*")

val source = UrlBasedCorsConfigurationSource()
source.registerCorsConfiguration("/**", config)

val filter = CorsFilter(source)

• The status property of ProblemDetail determines the HTTP status.

• The instance property of ProblemDetail is set from the current URL path, if not
  already set.

• For content negotiation, the Jackson HttpMessageConverter prefers
  «application/problem+json» over «application/json» when rendering a ProblemDetail,
  and also falls back on it if no compatible media type is found.

• Each ErrorResponse exposes a message code and arguments to resolve the «detail» field
  through a MessageSource.
  The actual message code value is parameterized with placeholders, e.g.
  "HTTP method {0} not supported" to be expanded from the arguments.

• Each ErrorResponse also exposes a message code to resolve the «title» field.

• ResponseEntityExceptionHandler uses the message code and arguments to resolve the
  «detail» and the «title» fields.

• WebContentInterceptor

• WebContentGenerator

• Controllers

• Static Resources

Java

// Cache for an hour - "Cache-Control: max-age=3600"
CacheControl ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS);

// Prevent caching - "Cache-Control: no-store"
CacheControl ccNoStore = CacheControl.noStore();

// Cache for ten days in public and private caches,
// public caches should not transform the response
// "Cache-Control: max-age=864000, public, no-transform"
CacheControl ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic();

Kotlin

// Cache for an hour - "Cache-Control: max-age=3600"
val ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS)

// Prevent caching - "Cache-Control: no-store"
val ccNoStore = CacheControl.noStore()

// Cache for ten days in public and private caches,
// public caches should not transform the response
// "Cache-Control: max-age=864000, public, no-transform"
val ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic()

• A -1 value does not generate a Cache-Control response header.

• A 0 value prevents caching by using the 'Cache-Control: no-store' directive.

• An n > 0 value caches the given response for n seconds by using the
  'Cache-Control: max-age=n' directive.

View Configuration

The following example shows how to configure FreeMarker as a view technology:

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        registry.freeMarker();
    }

    // Configure FreeMarker...

    @Bean
    public FreeMarkerConfigurer freeMarkerConfigurer() {
        FreeMarkerConfigurer configurer = new FreeMarkerConfigurer();
        configurer.setTemplateLoaderPath("/WEB-INF/freemarker");
        return configurer;
    }
}

@Configuration
@EnableWebMvc
class WebConfig : WebMvcConfigurer {

    override fun configureViewResolvers(registry: ViewResolverRegistry) {
        registry.freeMarker()
    }

    // Configure FreeMarker...

    @Bean
    fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply {
        setTemplateLoaderPath("/WEB-INF/freemarker")
    }
}

The following example shows how to configure the same in XML:

<mvc:annotation-driven/>

<mvc:view-resolvers>
    <mvc:freemarker/>
</mvc:view-resolvers>

<!-- Configure FreeMarker... -->
<mvc:freemarker-configurer>
    <mvc:template-loader-path location="/WEB-INF/freemarker"/>
</mvc:freemarker-configurer>

Alternatively, you can also declare the FreeMarkerConfigurer bean for full control over all
properties, as the following example shows:

<bean id="freemarkerConfig" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer">
    <property name="templateLoaderPath" value="/WEB-INF/freemarker/"/>
</bean>

Your templates need to be stored in the directory specified by the FreeMarkerConfigurer
shown in the preceding example. Given the preceding configuration, if your controller
returns a view name of welcome, the resolver looks for the
/WEB-INF/freemarker/welcome.ftl template.

FreeMarker Configuration

You can pass FreeMarker ‘Settings’ and ‘SharedVariables’ directly to the FreeMarker
Configuration object (which is managed by Spring) by setting the appropriate bean
properties on the FreeMarkerConfigurer bean. The freemarkerSettings property requires
a java.util.Properties object, and the freemarkerVariables property requires a
java.util.Map. The following example shows how to use a FreeMarkerConfigurer:

<bean id="freemarkerConfig" class="org.springframework.web.servlet.view.freemarker.FreeMarkerConfigurer">
    <property name="templateLoaderPath" value="/WEB-INF/freemarker/"/>
    <property name="freemarkerVariables">
        <map>
            <entry key="xml_escape" value-ref="fmXmlEscape"/>
        </map>
    </property>
</bean>

<bean id="fmXmlEscape" class="freemarker.template.utility.XmlEscape"/>

See the FreeMarker documentation for details of settings and variables as they apply to
the Configuration object.

Form Handling

Spring provides a tag library for use in JSPs that contains, among others, a
<spring:bind/> element. This element primarily lets forms display values from
form-backing objects and show the results of failed validations from a Validator in the
web or business tier. Spring also has support for the same functionality in FreeMarker,
with additional convenience macros for generating form input elements themselves.

<!-- FreeMarker macros have to be imported into a namespace.
    We strongly recommend sticking to 'spring'. -->
<#import "/spring.ftl" as spring/>
<html>
    ...
    <form action="" method="POST">
        Name:
        <@spring.bind "personForm.name"/>
        <input type="text"
            name="${spring.status.expression}"
            value="${spring.status.value?html}"/><br />
        <#list spring.status.errorMessages as error> <b>${error}</b> <br /> </#list>
        <br />
        ...
        <input type="submit" value="submit"/>
    </form>
    ...
</html>

<@spring.formInput "command.name"/>
<@spring.showErrors "<br>"/>

Name:
<input type="text" name="name" value="">
<br>
    <b>required</b>
<br>
<br>

...
Town:
<@spring.formRadioButtons "command.address.town", cityMap, ""/><br><br>

Town:
<input type="radio" name="address.town" value="London">London</input>
<input type="radio" name="address.town" value="Paris" checked="checked">Paris</input>
<input type="radio" name="address.town" value="New York">New York</input>

protected Map<String, ?> referenceData(HttpServletRequest request) throws Exception {
    Map<String, String> cityMap = new LinkedHashMap<>();
    cityMap.put("LDN", "London");
    cityMap.put("PRS", "Paris");
    cityMap.put("NYC", "New York");

    Map<String, Object> model = new HashMap<>();
    model.put("cityMap", cityMap);
    return model;
}

protected fun referenceData(request: HttpServletRequest): Map<String, *> {
    val cityMap = linkedMapOf(
            "LDN" to "London",
            "PRS" to "Paris",
            "NYC" to "New York"
    )
    return hashMapOf("cityMap" to cityMap)
}

Town:
<input type="radio" name="address.town" value="LDN">London</input>
<input type="radio" name="address.town" value="PRS" checked="checked">Paris</input>
<input type="radio" name="address.town" value="NYC">New York</input>

<#-- for FreeMarker -->
<#assign xhtmlCompliant = true>

<#-- until this point, default HTML escaping is used -->

<#assign htmlEscape = true>
<#-- next field will use HTML escaping -->
<@spring.formInput "command.name"/>

<#assign htmlEscape = false in spring>
<#-- all future fields will be bound with HTML escaping off -->

Configuration

The following example shows how to configure the Groovy Markup Template Engine:

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        registry.groovy();
    }

    // Configure the Groovy Markup Template Engine...

    @Bean
    public GroovyMarkupConfigurer groovyMarkupConfigurer() {
        GroovyMarkupConfigurer configurer = new GroovyMarkupConfigurer();
        configurer.setResourceLoaderPath("/WEB-INF/");
        return configurer;
    }
}

@Configuration
@EnableWebMvc
class WebConfig : WebMvcConfigurer {

    override fun configureViewResolvers(registry: ViewResolverRegistry) {
        registry.groovy()
    }

    // Configure the Groovy Markup Template Engine...

    @Bean
    fun groovyMarkupConfigurer() = GroovyMarkupConfigurer().apply {
        resourceLoaderPath = "/WEB-INF/"
    }
}

The following example shows how to configure the same in XML:

<mvc:annotation-driven/>

<mvc:view-resolvers>
    <mvc:groovy/>
</mvc:view-resolvers>

<!-- Configure the Groovy Markup Template Engine... -->
<mvc:groovy-configurer resource-loader-path="/WEB-INF/"/>

Example

Unlike traditional template engines, Groovy Markup relies on a DSL that uses a builder
syntax. The following example shows a sample template for an HTML page:

yieldUnescaped '<!DOCTYPE html>'
html(lang:'en') {
    head {
        meta('http-equiv':'"Content-Type" content="text/html; charset=utf-8"')
        title('My page')
    }
    body {
        p('This is an example of HTML contents')
    }
}

Requirements

You need to have the script engine on your classpath, the details of which vary by script engine:

You need to have the script templating library. One way to do that for JavaScript is
through WebJars.

Script Templates

You can declare a ScriptTemplateConfigurer bean to specify the script engine to use,
the script files to load, what function to call to render templates, and so on.
The following example uses Mustache templates and the Nashorn JavaScript engine:

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        registry.scriptTemplate();
    }

    @Bean
    public ScriptTemplateConfigurer configurer() {
        ScriptTemplateConfigurer configurer = new ScriptTemplateConfigurer();
        configurer.setEngineName("nashorn");
        configurer.setScripts("mustache.js");
        configurer.setRenderObject("Mustache");
        configurer.setRenderFunction("render");
        return configurer;
    }
}

@Configuration
@EnableWebMvc
class WebConfig : WebMvcConfigurer {

    override fun configureViewResolvers(registry: ViewResolverRegistry) {
        registry.scriptTemplate()
    }

    @Bean
    fun configurer() = ScriptTemplateConfigurer().apply {
        engineName = "nashorn"
        setScripts("mustache.js")
        renderObject = "Mustache"
        renderFunction = "render"
    }
}

The following example shows the same arrangement in XML:

<mvc:annotation-driven/>

<mvc:view-resolvers>
    <mvc:script-template/>
</mvc:view-resolvers>

<mvc:script-template-configurer engine-name="nashorn" render-object="Mustache" render-function="render">
    <mvc:script location="mustache.js"/>
</mvc:script-template-configurer>

The controller would look no different for the Java and XML configurations, as the following example shows:

@Controller
public class SampleController {

    @GetMapping("/sample")
    public String test(Model model) {
        model.addAttribute("title", "Sample title");
        model.addAttribute("body", "Sample body");
        return "template";
    }
}

@Controller
class SampleController {

    @GetMapping("/sample")
    fun test(model: Model): String {
        model["title"] = "Sample title"
        model["body"] = "Sample body"
        return "template"
    }
}

The following example shows the Mustache template:

<html>
    <head>
        <title>{{title}}</title>
    </head>
    <body>
        <p>{{body}}</p>
    </body>
</html>

The render function is called with the following parameters:

Mustache.render() is natively compatible with this signature, so you can call it directly.

If your templating technology requires some customization, you can provide a script that
implements a custom render function. For example, Handlerbars
needs to compile templates before using them and requires a
polyfill to emulate some
browser facilities that are not available in the server-side script engine.

The following example shows how to do so:

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        registry.scriptTemplate();
    }

    @Bean
    public ScriptTemplateConfigurer configurer() {
        ScriptTemplateConfigurer configurer = new ScriptTemplateConfigurer();
        configurer.setEngineName("nashorn");
        configurer.setScripts("polyfill.js", "handlebars.js", "render.js");
        configurer.setRenderFunction("render");
        configurer.setSharedEngine(false);
        return configurer;
    }
}

@Configuration
@EnableWebMvc
class WebConfig : WebMvcConfigurer {

    override fun configureViewResolvers(registry: ViewResolverRegistry) {
        registry.scriptTemplate()
    }

    @Bean
    fun configurer() = ScriptTemplateConfigurer().apply {
        engineName = "nashorn"
        setScripts("polyfill.js", "handlebars.js", "render.js")
        renderFunction = "render"
        isSharedEngine = false
    }
}

polyfill.js defines only the window object needed by Handlebars to run properly, as follows:

This basic render.js implementation compiles the template before using it. A production-ready
implementation should also store any reused cached templates or pre-compiled templates.
You can do so on the script side (and handle any customization you need — managing
template engine configuration, for example). The following example shows how to do so:

function render(template, model) {
    var compiledTemplate = Handlebars.compile(template);
    return compiledTemplate(model);
}

Check out the Spring Framework unit tests,
Java, and
resources,
for more configuration examples.

View Resolvers

When developing with JSPs, you typically declare an InternalResourceViewResolver bean.

InternalResourceViewResolver can be used for dispatching to any Servlet resource but in
particular for JSPs. As a best practice, we strongly encourage placing your JSP files in
a directory under the 'WEB-INF' directory so there can be no direct access by clients.

<bean id="viewResolver" class="org.springframework.web.servlet.view.InternalResourceViewResolver">
    <property name="viewClass" value="org.springframework.web.servlet.view.JstlView"/>
    <property name="prefix" value="/WEB-INF/jsp/"/>
    <property name="suffix" value=".jsp"/>
</bean>

JSPs versus JSTL

When using the JSP Standard Tag Library (JSTL) you must use a special view class, the
JstlView, as JSTL needs some preparation before things such as the I18N features can
work.

Spring’s JSP Tag Library

Spring provides data binding of request parameters to command objects, as described in
earlier chapters. To facilitate the development of JSP pages in combination with those
data binding features, Spring provides a few tags that make things even easier. All
Spring tags have HTML escaping features to enable or disable escaping of characters.

The spring.tld tag library descriptor (TLD) is included in the spring-webmvc.jar.
For a comprehensive reference on individual tags, browse the
API reference
or see the tag library description.

Spring’s form tag library

As of version 2.0, Spring provides a comprehensive set of data binding-aware tags for
handling form elements when using JSP and Spring Web MVC. Each tag provides support for
the set of attributes of its corresponding HTML tag counterpart, making the tags
familiar and intuitive to use. The tag-generated HTML is HTML 4.01/XHTML 1.0 compliant.

Unlike other form/input tag libraries, Spring’s form tag library is integrated with
Spring Web MVC, giving the tags access to the command object and reference data your
controller deals with. As we show in the following examples, the form tags make
JSPs easier to develop, read, and maintain.

We go through the form tags and look at an example of how each tag is used. We have
included generated HTML snippets where certain tags require further commentary.

<%@ taglib prefix="form" uri="http://www.springframework.org/tags/form" %>

<form:form>
    <table>
        <tr>
            <td>First Name:</td>
            <td><form:input path="firstName"/></td>
        </tr>
        <tr>
            <td>Last Name:</td>
            <td><form:input path="lastName"/></td>
        </tr>
        <tr>
            <td colspan="2">
                <input type="submit" value="Save Changes"/>
            </td>
        </tr>
    </table>
</form:form>

<form method="POST">
    <table>
        <tr>
            <td>First Name:</td>
            <td><input name="firstName" type="text" value="Harry"/></td>
        </tr>
        <tr>
            <td>Last Name:</td>
            <td><input name="lastName" type="text" value="Potter"/></td>
        </tr>
        <tr>
            <td colspan="2">
                <input type="submit" value="Save Changes"/>
            </td>
        </tr>
    </table>
</form>

<form:form modelAttribute="user">
    <table>
        <tr>
            <td>First Name:</td>
            <td><form:input path="firstName"/></td>
        </tr>
        <tr>
            <td>Last Name:</td>
            <td><form:input path="lastName"/></td>
        </tr>
        <tr>
            <td colspan="2">
                <input type="submit" value="Save Changes"/>
            </td>
        </tr>
    </table>
</form:form>

public class Preferences {

    private boolean receiveNewsletter;
    private String[] interests;
    private String favouriteWord;

    public boolean isReceiveNewsletter() {
        return receiveNewsletter;
    }

    public void setReceiveNewsletter(boolean receiveNewsletter) {
        this.receiveNewsletter = receiveNewsletter;
    }

    public String[] getInterests() {
        return interests;
    }

    public void setInterests(String[] interests) {
        this.interests = interests;
    }

    public String getFavouriteWord() {
        return favouriteWord;
    }

    public void setFavouriteWord(String favouriteWord) {
        this.favouriteWord = favouriteWord;
    }
}

class Preferences(
        var receiveNewsletter: Boolean,
        var interests: StringArray,
        var favouriteWord: String
)

<form:form>
    <table>
        <tr>
            <td>Subscribe to newsletter?:</td>
            <%-- Approach 1: Property is of type java.lang.Boolean --%>
            <td><form:checkbox path="preferences.receiveNewsletter"/></td>
        </tr>

        <tr>
            <td>Interests:</td>
            <%-- Approach 2: Property is of an array or of type java.util.Collection --%>
            <td>
                Quidditch: <form:checkbox path="preferences.interests" value="Quidditch"/>
                Herbology: <form:checkbox path="preferences.interests" value="Herbology"/>
                Defence Against the Dark Arts: <form:checkbox path="preferences.interests" value="Defence Against the Dark Arts"/>
            </td>
        </tr>

        <tr>
            <td>Favourite Word:</td>
            <%-- Approach 3: Property is of type java.lang.Object --%>
            <td>
                Magic: <form:checkbox path="preferences.favouriteWord" value="Magic"/>
            </td>
        </tr>
    </table>
</form:form>