Set Up a Spring MVC Application

Next, you need to create a Spring MVC application layout. In general, a web application developed with Spring MVC is set up in the same way as a standard Java web application, except that you have to add a couple of configuration files and required libraries specific to Spring MVC .

The Java EE specification defines the valid directory structure of a Java web application made up of a web archive (WAR file). For example, you have to provide a web deployment descriptor (i.e., web.xml) in the WEB-INF root or one or more classes implementing ServletContainerInitializer. The class files and JAR files for this web application should be put in the WEB-INF/classes and WEB-INF/lib directories, respectively.

For your court reservation system, you create the following directory structure. Note that the highlighted files are Spring-specific configuration files.

<dependency>                    
    <groupId>org.springframework</groupId>                
    <artifactId>spring-webmvc</artifactId>                
    <version>${spring.version}</version>                
</dependency>                    

dependencies {
    compile "org.springframework:spring-webmvc:$springVersion"
}

The files outside the WEB-INF directory are directly accessible to users via URLs, so the CSS files and image files must be put there. When using Spring MVC, the JSP files act as templates. They are read by the framework for generating dynamic content, so the JSP files should be put inside the WEB-INF directory to prevent direct access to them. However, some application servers don’t allow the files inside WEB-INF to be read by a web application internally. In that case, you can only put them outside the WEB-INF directory.

Create the Configuration Files

The web deployment descriptor (web.xml or ServletContainerInitializer is the essential configuration file for a Java web application). In this file, you define the servlets for your application and how web requests are mapped to them. For a Spring MVC application, you have to define only a single DispatcherServlet instance that acts as the front controller for Spring MVC, although you are allowed to define more than one if required.

In large applications, it can be convenient to use multiple DispatcherServlet instances. This allows DispatcherServlet instances to be designated to specific URLs, making code management easier and letting individual team members work on an application’s logic without getting in each other’s way.

package com.apress.springrecipes.court.web;

import com.apress.springrecipes.court.config.CourtConfiguration;
import org.springframework.web.context.support.AnnotationConfigWebApplicationContext;
import org.springframework.web.servlet.DispatcherServlet;

import javax.servlet.ServletContainerInitializer;
import javax.servlet.ServletContext;
import javax.servlet.ServletException;
import javax.servlet.ServletRegistration;
import java.util.Set;

public class CourtServletContainerInitializer implements ServletContainerInitializer {

    @Override
    public void onStartup(Set<Class<?>> c, ServletContext ctx) throws ServletException {

        AnnotationConfigWebApplicationContext applicationContext =            new AnnotationConfigWebApplicationContext();
        applicationContext.register(CourtConfiguration.class);

        DispatcherServlet dispatcherServlet = new DispatcherServlet(applicationContext);

        ServletRegistration.Dynamic courtRegistration =            ctx.addServlet("court", dispatcherServlet);
        courtRegistration.setLoadOnStartup(1);
        courtRegistration.addMapping("/");
    }
}

In this CourtServletContainerInitializer , you define a servlet of type DispatcherServlet. This is the core servlet class in Spring MVC that receives web requests and dispatches them to appropriate handlers. You set this servlet’s name to court and map all URLs using a slash (/), with the slash representing the root directory. Note that the URL pattern can be set to more granular patterns. In larger applications, it can make more sense to delegate patterns among various servlets, but for simplicity, all URLs in the application are delegated to the single court servlet .

To have the CourtServletContainerInitializer detected, you also have to add a file named javax.servlet.ServletContainerInitializer into the META-INF/services directory. The content of the file should be the full name of the CourtServletContainerInitializer. This file is loaded by the servlet container and used to bootstrap the application.

com.apress.springrecipes.court.web.CourtServletContainerInitializer

Finally, add the CourtConfiguration class, which is a simple @Configuration class.

package com.apress.springrecipes.court.config;

import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;

@Configuration
@ComponentScan("com.apress.springrecipes.court")
public class CourtConfiguration {}

This defines an @ComponentScan annotation, which will scan the com.apress.springrecipes.court package (and subpackages) and register all the detected beans (in this case, the ReservationServiceImpl and the yet to be created @Controller annotated classes).

Create Spring MVC Controllers

An annotation-based controller class can be an arbitrary class that doesn’t implement a particular interface or extend a particular base class. You can annotate it with the @Controller annotation. There can be one or more handler methods defined in a controller to handle single or multiple actions. The signature of the handler methods is flexible enough to accept a range of arguments.

The @RequestMapping annotation can be applied to the class level or the method level. The first mapping strategy is to map a particular URL pattern to a controller class and then a particular HTTP method to each handler method .

package com.apress.springrecipes.court.web;

import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;

import java.util.Date;

@Controller
@RequestMapping("/welcome")
public class WelcomeController {

    @RequestMapping(method = RequestMethod.GET)
    public String welcome(Model model) {

        Date today = new Date();
        model.addAttribute("today", today);
        return "welcome";
    }
}

This controller creates a java.util.Date object to retrieve the current date and then adds it to the input Model object as an attribute so the target view can display it.

Since you’ve already activated annotation scanning on the com.apress.springrecipes.court package, the annotations for the controller class are detected upon deployment.

The @Controller annotation defines the class as a Spring MVC controller. The @RequestMapping annotation is more interesting since it contains properties and can be declared at the class or handler method level. The first value used in this class— ("/welcome")—is used to specify the URL on which the controller is actionable, meaning any request received on the /welcome URL is attended by the WelcomeController class.

Once a request is attended by the controller class, it delegates the call to the default HTTP GET handler method declared in the controller. The reason for this behavior is that every initial request made on a URL is of the HTTP GET kind. So, when the controller attends a request on the /welcome URL, it subsequently delegates to the default HTTP GET handler method for processing.

The annotation @RequestMapping(method = RequestMethod.GET) is used to decorate the welcome method as the controller’s default HTTP GET handler method. It’s worth mentioning that if no default HTTP GET handler method is declared, a ServletException is thrown. Hence, it’s important for a Spring MVC controller to have at a minimum a URL route and default HTTP GET handler method .

Another variation to this approach can be declaring both values—URL route and default HTTP GET handler method—in the @RequestMapping annotation used at the method level. This declaration is illustrated next:

@Controller
public class WelcomeController {

    @RequestMapping(value = "/welcome", method=RequestMethod.GET)
    public String welcome(Model model) { ... }

}

This declaration is equivalent to the earlier one. The value attribute indicates the URL to which the handler method is mapped, and the method attribute defines the handler method as the controller’s default HTTP GET method. Finally, there are also some convenient annotations such as @GetMapping, @PostMapping, and so on, to minimize the configuration. The following mapping will do the same as the earlier mentioned declarations:

@Controller
public class WelcomeController {

    @GetMapping("/welcome")
    public String welcome(Model model) { ... }

}

The @GetMapping annotation makes the class a bit shorter and maybe easier to read.

This last controller illustrates the basic principles of Spring MVC. However, a typical controller may invoke back-end services for business processing. For example, you can create a controller for querying reservations of a particular court as follows:

package com.apress.springrecipes.court.web;

import com.apress.springrecipes.court.domain.Reservation;
import com.apress.springrecipes.court.service.ReservationService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;

import java.util.List;

@Controller
@RequestMapping("/reservationQuery")
public class ReservationQueryController {

    private final ReservationService reservationService;

    public ReservationQueryController(ReservationService reservationService) {
        this.reservationService = reservationService;
    }

    @GetMapping
    public void setupForm() {}

    @PostMapping
    public String sumbitForm(@RequestParam("courtName") String courtName, Model model) {

        List<Reservation> reservations = java.util.Collections.emptyList();
        if (courtName != null) {
            reservations = reservationService.query(courtName);
        }
            model.addAttribute("reservations", reservations);
        return "reservationQuery";
    }
}

As outlined earlier, the controller then looks for a default HTTP GET handler method . Since the public void setupForm() method is assigned the necessary @RequestMapping annotation for this purpose, it’s called next.

Unlike the previous default HTTP GET handler method, notice that this method has no input parameters, has no logic, and has a void return value. This means two things. By having no input parameters and no logic, a view only displays data hard-coded in the implementation template (e.g., JSP) since no data is being added by the controller. By having a void return value, a default view name based on the request URL is used; therefore, since the requesting URL is /reservationQuery, a return view named reservationQuery is assumed.

The remaining handler method is decorated with the @PostMapping annotation. At first sight, having two handler methods with only the class-level /reservationQuery URL statement can be confusing, but it’s really simple. One method is invoked when HTTP GET requests are made on the /reservationQuery URL; the other is invoked when HTTP POST requests are made on the same URL.

The majority of requests in web applications are of the HTTP GET kind, whereas requests of the HTTP POST kind are generally made when a user submits an HTML form . So, revealing more of the application’s view (which we will describe shortly), one method is called when the HTML form is initially loaded (i.e., HTTP GET), whereas the other is called when the HTML form is submitted (i.e., HTTP POST).

Looking closer at the HTTP POST default handler method, notice the two input parameters. First notice the @RequestParam("courtName") String courtName declaration, used to extract a request parameter named courtName. In this case, the HTTP POST request comes in the form /reservationQuery?courtName=<value>; this declaration makes said value available in the method under the variable named courtName. Second, notice the Model declaration, which is used to define an object in which to pass data onto the returning view .

The logic executed by the handler method consists of using the controller’s reservationService to perform a query using the courtName variable. The results obtained from this query are assigned to the Model object, which will later become available to the returning view for display.

Finally, note that the method returns a view named reservationQuery. This method could have also returned void, just like the default HTTP GET, and have been assigned to the same reservationQuery default view on account of the requesting URL. Both approaches are identical.

Now that you are aware of how Spring MVC controllers are constituted, it’s time to explore the views to which a controller’s handler methods delegate their results.

Create JSP Views

Spring MVC supports many types of views for different presentation technologies. These include JSPs, HTML, PDF, Excel worksheets (XLS), XML, JSON, Atom and RSS feeds, JasperReports, and other third-party view implementations.

In a Spring MVC application, views are most commonly JSP templates written with JSTL. When the DispatcherServlet—defined in an application’s web.xml file—receives a view name returned from a handler, it resolves the logical view name into a view implementation for rendering. For example, you can configure the InternalResourceViewResolver bean, in this case in the CourtConfiguration, of a web application’s context to resolve view names into JSP files in the /WEB-INF/jsp/ directory.

@Bean
public InternalResourceViewResolver internalResourceViewResolver() {

    InternalResourceViewResolver viewResolver = new InternalResourceViewResolver();
    viewResolver.setPrefix("/WEB-INF/jsp/");
    viewResolver.setSuffix(".jsp");
    return viewResolver;
}

By using this last configuration, a logical view named reservationQuery is delegated to a view implementation located at /WEB-INF/jsp/reservationQuery.jsp. Knowing this, you can create the following JSP template for the welcome controller, naming it welcome.jsp and putting it in the /WEB-INF/jsp/ directory :

<%@ taglib prefix="fmt" uri="http://java.sun.com/jsp/jstl/fmt" %>

<html>                    
<head>                    
    <title>Welcome</title>                
</head>                    

<body>                    
<h2>Welcome to Court Reservation System</h2>                
Today is <fmt:formatDate value="${today}" pattern="yyyy-MM-dd" />.
</body>                    
</html>                    

In this JSP template, you make use of the fmt tag library in JSTL to format the today model attribute into the pattern yyyy-MM-dd. Don’t forget to include the fmt tag library definition at the top of this JSP template.

Next, you can create another JSP template for the reservation query controller and name it reservationQuery.jsp to match the view name.

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="fmt" uri="http://java.sun.com/jsp/jstl/fmt" %>

<html>                    
<head>                    
<title>Reservation Query</title>                
</head>                    

<body>                    
<form method="post">                
Court Name
<input type="text" name="courtName" value="${courtName}" />                
<input type="submit" value="Query" />                
</form>                    

<table border="1">                
    <tr>                
        <th>Court Name</th>                
        <th>Date</th>                
        <th>Hour</th>                
        <th>Player</th>                
    </tr>                
    <c:forEach items="${reservations}" var="reservation">                
    <tr>                
        <td>${reservation.courtName}</td>                
        <td><fmt:formatDate value="${reservation.date}" pattern="yyyy-MM-dd" /></td>                
        <td>${reservation.hour}</td>                
        <td>${reservation.player.name}</td>                
    </tr>                
    </c:forEach>                
</table>                    
</body>                    
</html>                    

In this JSP template, you include a form for users to input the court name they want to query and then use the <c:forEach> tag to loop the reservation’s model attribute to generate the result table.

Deploy the Web Application

In a web application’s development process, we strongly recommend installing a local Java EE application server that comes with a web container for testing and debugging purposes. For the sake of easy configuration and deployment, we have chosen Apache Tomcat 8.5.x as the web container.

The deployment directory for this web container is located in the webapps directory. By default, Tomcat listens on port 8080 and deploys applications onto a context by the same name of an application WAR. Therefore, if you package the application in a WAR named court.war, the welcome controller and the reservation query controller can be accessed through the following URLs:

http://localhost:8080/court/welcome
http://localhost:8080/court/reservationQuery

Bootstrap the Application Using a WebApplicationInitializer

In the previous section, you created a CourtServletContainerInitializer together with a file in META-INF/services to bootstrap the application.

Instead of implementing your own, you are now going to leverage the convenient Spring implementation the SpringServletContainerInitializer. This class is an implementation of the ServletContainerInitializer interface and scans the classpath for implementations of a WebApplicationInitializer interface. Luckily, Spring provides some convenience implementations of this interface, which you can leverage for the application; one of them is the AbstractAnnotationConfigDispatcherServletInitializer.

package com.apress.springrecipes.court.web;

import com.apress.springrecipes.court.config.CourtConfiguration;
import org.springframework.web.servlet.support.AbstractAnnotationConfigDispatcherServletInitializer;

public class CourtWebApplicationInitializer extends AbstractAnnotationConfigDispatcherServletInitializer {

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

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

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

The newly introduced CourtWebApplicationInitializer already creates a DispatcherServlet, so the only thing you need to do is to configure the mappings in the getServletMappings method and the configuration classes you want to load in the getServletConfigClasses. Next to the servlet there is also another component being created, optionally, which is the ContextLoaderListener. This is a ServletContextListener, which also creates an ApplicationContext, which will be used as a parent ApplicationContext for the DispatcherServlet. This is convenient if you have multiple servlets needing access to the same beans (services, data sources, etc.).

Map Requests by Method

The simplest strategy for using @RequestMapping annotations is to decorate the handler methods directly. For this strategy to work, you have to declare each handler method with the @RequestMapping annotation containing a URL pattern. If a handler’s @RequestMapping annotation matches a request’s URL, DispatcherServlet dispatches the request to this handler for it to handle the request.

package com.apress.springrecipes.court.web;

import com.apress.springrecipes.court.domain.Member;
import com.apress.springrecipes.court.service.MemberService;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;

@Controller
public class MemberController {

    private MemberService memberService;

    public MemberController(MemberService memberService) {
        this.memberService = memberService;
    }

    @RequestMapping("/member/add")
    public String addMember(Model model) {

        model.addAttribute("member", new Member());
        model.addAttribute("guests", memberService.list());
        return "memberList";
    }

    @RequestMapping(value = {"/member/remove", "/member/delete"}, method = RequestMethod.GET)
    public String removeMember(@RequestParam("memberName")String memberName) {
        memberService.remove(memberName);
        return "redirect:";
    }
}

This code illustrates how each handler method is mapped to a particular URL using the @RequestMapping annotation. The second handler method illustrates the assignment of multiple URLs, so both /member/remove and /member/delete trigger the execution of the handler method. By default, it’s assumed all incoming requests to URLs are of the HTTP GET kind.

Map Requests by Class

The @RequestMapping annotation can also be used to decorate a controller class. This allows handler methods to either forgo the use of @RequestMapping annotations, as illustrated in the ReservationQueryController controller in recipe 4-1, or use finer-grained URLs with their own @RequestMapping annotation. For broader URL matching, the @RequestMapping annotation also supports the use of wildcards (i.e., *).

The following code illustrates the use of URL wildcards in an @RequestMapping annotation, as well as finer-grained URL matching on @RequestMapping annotations for handler methods:

package com.apress.springrecipes.court.web;

import com.apress.springrecipes.court.domain.Member;
import com.apress.springrecipes.court.service.MemberService;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;

@Controller
@RequestMapping("/member/*")
public class MemberController {

    private final MemberService memberService;

    public MemberController(MemberService memberService) {
        this.memberService = memberService;
    }

    @RequestMapping("add")
    public String addMember(Model model) {

        model.addAttribute("member", new Member());
        model.addAttribute("guests", memberService.list());
        return "memberList";
    }

    @RequestMapping(value={"remove","delete"}, method=RequestMethod.GET)
    public String removeMember(@RequestParam("memberName") String memberName) {
        memberService.remove(memberName);
        return "redirect:";
    }

    @RequestMapping("display/{member}")
    public String displayMember(@PathVariable("member") String member, Model model) {
        model.addAttribute("member", memberService.find(member).orElse(null));
        return "member";
    }

    @RequestMapping
    public void memberList() {}

    public void memberLogic(String memberName) {}

}

Note the class-level @RequestMapping annotation uses a URL wildcard: /member/* . This in turn delegates all requests under the /member/ URL to the controller’s handler methods.

The first two handler methods make use of the @RequestMapping annotation. The addMember() method is invoked when an HTTP GET request is made on the /member/add URL, whereas the removeMember() method is invoked when an HTTP GET request is made on either the /member/remove or /member/delete URL.

The third handler method uses the special notation {path_variable} to specify its @RequestMapping value. By doing so, a value present in the URL can be passed as input to the handler method. Notice the handler method declares @PathVariable("user") String user. In this manner, if a request is received in the form member/display/jdoe, the handler method has access to the member variable with a jdoe value. This is mainly a facility that allows you to avoid tinkering with a handler’s request object and an approach that is especially helpful when you design RESTful web services.

The fourth handler method also uses the @RequestMapping annotation, but in this case it lacks a URL value. Since the class level uses the /member/* URL wildcard, this handler method is executed as a catchall. So, any URL request (e.g., /member/abcdefg or /member/randomroute) triggers this method. Note the void return value, which in turn makes the handler method default to a view by its name (i.e., memberList).

The last method—memberLogic—lacks any @RequestMapping annotations , which means the method is a utility for the class and has no influence on Spring MVC.

Map Requests by HTTP Request Type

By default, @RequestMapping annotations handle all types of incoming requests. However, in most cases, you do not want the same method to be executed for both a GET request and a POST request. To differentiate on HTTP requests, it’s necessary to specify the type explicitly in the @RequestMapping annotation as follows:

@RequestMapping(value= "processUser", method =  RequestMethod.POST)
public String submitForm(@ModelAttribute("member") Member member, BindingResult result, Model model) {

}

The extent to which you require specifying a handler method’s HTTP type depends on how and what is interacting with a controller. For the most part, web browsers perform the bulk of their operations using HTTP GET and HTTP POST requests. However, other devices or applications (e.g., RESTful web services) may require support for other HTTP request types. In all, there are nine different HTTP request types: HEAD, GET, POST, PUT, DELETE, PATCH, TRACE, OPTIONS, and CONNECT. However, support for handling all these request types goes beyond the scope of an MVC controller, since a web server, as well as the requesting party, needs to support such HTTP request types. Considering the majority of HTTP requests are of the GET or POST kind, you will rarely if ever need to implement support for these additional HTTP request types.

For the most commonly used request methods, Spring MVC provides specialized annotations, as shown in Table 3-1.

These convenience annotations are all specialized @RequestMapping annotations and make writing request-handling methods a bit more compact.

@PostMapping("processUser")
public String submitForm(@ModelAttribute("member") Member member, BindingResult result, Model model) {

}

You might have noticed that in all the URLs specified in @RequestMapping annotations, there was no trace of a file extension like .html or .jsp. This is good practice in accordance with MVC design, even though it’s not widely adopted.

A controller should not be tied to any type of extension that is indicative of a view technology, such as HTML or JSP. This is why controllers return logical views and also why matching URLs should be declared without extensions.

In an age where it’s common to have applications serve the same content in different formats, such as XML, JSON, PDF, or XLS (Excel), it should be left to a view resolver to inspect the extension provided in a request—if any—and determine which view technology to use.

In this short introduction, you’ve seen how a resolver is configured in an MVC’s configuration class to map logical views to JSP files, all without every using a URL file extension like .jsp.

In later recipes, you will learn how Spring MVC uses this same nonextension URL approach to serve content using different view technologies .

Resolve Locales by an HTTP Request Header

The default locale resolver used by Spring is AcceptHeaderLocaleResolver. It resolves locales by inspecting the accept-language header of an HTTP request . This header is set by a user’s web browser according to the locale setting of the underlying operating system. Note that this locale resolver cannot change a user’s locale because it is unable to modify the locale setting of the user’s operating system.

Resolve Locales by a Session Attribute

Another option of resolving locales is by SessionLocaleResolver. It resolves locales by inspecting a predefined attribute in a user’s session. If the session attribute doesn’t exist, this locale resolver determines the default locale from the accept-language HTTP header.

@Bean
public LocaleResolver localeResolver () {
    SessionLocaleResolver localeResolver = new SessionLocaleResolver();
    localeResolver.setDefaultLocale(new Locale("en"));
    return localeResolver;
}

You can set the defaultLocale property for this resolver in case the session attribute doesn’t exist. Note that this locale resolver is able to change a user’s locale by altering the session attribute that stores the locale.

Resolve Locales by a Cookie

You can also use CookieLocaleResolver to resolve locales by inspecting a cookie in a user’s browser. If the cookie doesn’t exist, this locale resolver determines the default locale from the accept-language HTTP header.

@Bean
public LocaleResolver localeResolver() {
    return new CookieLocaleResolver();
}

The cookie used by this locale resolver can be customized by setting the cookieName and cookieMaxAge properties. The cookieMaxAge property indicates how many seconds this cookie should be persisted. The value -1 indicates that this cookie will be invalid after the browser is closed.

@Bean
public LocaleResolver localeResolver() {
    CookieLocaleResolver cookieLocaleResolver = new CookieLocaleResolver();
    cookieLocaleResolver.setCookieName("language");
    cookieLocaleResolver.setCookieMaxAge(3600);
    cookieLocaleResolver.setDefaultLocale(new Locale("en"));
    return cookieLocaleResolver;
}

You can also set the defaultLocale property for this resolver in case the cookie doesn’t exist in a user’s browser. This locale resolver is able to change a user’s locale by altering the cookie that stores the locale .

Resolve Views Based on a Template’s Name and Location

The basic strategy of resolving views is to map them to a template’s name and location directly. The view resolver InternalResourceViewResolver maps each view name to an application’s directory by means of a prefix and a suffix declaration. To register InternalResourceViewResolver, you can declare a bean of this type in the web application context.

@Bean
public InternalResourceViewResolver viewResolver() {
    InternalResourceViewResolver viewResolver = new InternalResourceViewResolver();
    viewResolver.setPrefix("/WEB-INF/jsp/");
    viewResolver.setSuffix(".jsp");
    return viewResolver;
}

For example, InternalResourceViewResolver resolves the view names welcome and reservationQuery in the following way:

welcome --> /WEB-INF/jsp/welcome.jsp
reservationQuery --> /WEB-INF/jsp/reservationQuery.jsp

The type of the resolved views can be specified by the viewClass property. By default, InternalResourceViewResolver resolves view names into view objects of type JstlView if the JSTL library (i.e., jstl.jar) is present in the classpath. So, you can omit the viewClass property if your views are JSP templates with JSTL tags.

InternalResourceViewResolver is simple, but it can only resolve internal resource views that can be forwarded by the Servlet API’s RequestDispatcher (e.g., an internal JSP file or a servlet). As for other view types supported by Spring MVC, you have to resolve them using other strategies.

Resolve Views from an XML Configuration File

Another strategy for resolving views is to declare them as Spring beans and resolve them by their bean names. You can declare the view beans in the same configuration file as the web application context, but it’s better to isolate them in a separate configuration file. By default, XmlViewResolver loads view beans from /WEB-INF/views.xml, but this location can be overridden through the location property .

Configuration
public class ViewResolverConfiguration implements WebMvcConfigurer, ResourceLoaderAware {

    private ResourceLoader resourceLoader;

    @Bean
    public ViewResolver viewResolver() {
        XmlViewResolver viewResolver = new XmlViewResolver();
        viewResolver.setLocation(resourceLoader.getResource("/WEB-INF/court-views.nl"));
        return viewResolver;
    }

    @Override
    public void setResourceLoader(ResourceLoader resourceLoader) {
        this.resourceLoader=resourceLoader;
    }
}

Note in the implementation of the ResourceLoaderAware interface, you need to load resources as the location property takes an argument of the type Resource. In a Spring XML file, the conversion from String to Resource is handled for you; however, when using a Java-based configuration, you have to do some additional work. In the court-views.xml configuration file, you can declare each view as a normal Spring bean by setting the class name and properties. In this way, you can declare any types of views (e.g., RedirectView and even custom view types).

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd">                

    <bean id="welcome"
        class="org.springframework.web.servlet.view.JstlView">                
        <property name="url" value="/WEB-INF/jsp/welcome.jsp" />                
    </bean>                

    <bean id="reservationQuery"
        class="org.springframework.web.servlet.view.JstlView">                
        <property name="url" value="/WEB-INF/jsp/reservationQuery.jsp" />                
    </bean>                

    <bean id="welcomeRedirect"
        class="org.springframework.web.servlet.view.RedirectView">                
        <property name="url" value="welcome" />                
    </bean>                
</beans>                    

Resolve Views from a Resource Bundle

In addition to an XML configuration file, you can declare view beans in a resource bundle. ResourceBundleViewResolver loads view beans from a resource bundle in the classpath root. Note that ResourceBundleViewResolver can also take advantage of the resource bundle capability to load view beans from different resource bundles for different locales.

@Bean
public ResourceBundleViewResolver viewResolver() {
    ResourceBundleViewResolver viewResolver = new ResourceBundleViewResolver();
    viewResolver.setBasename("court-views");
    return viewResolver;
}

As you specify court-views as the base name of ResourceBundleViewResolver, the resource bundle is court-views.properties. In this resource bundle, you can declare view beans in the format of properties. This type of declaration is equivalent to the XML bean declaration.

welcome.(class)=org.springframework.web.servlet.view.JstlView welcome.url=/WEB-INF/jsp/welcome.jsp reservationQuery.(class)=org.springframework.web.servlet.view.JstlView reservationQuery.url=/WEB-INF/jsp/reservationQuery.jsp welcomeRedirect.(class)=org.springframework.web.servlet.view.RedirectView welcomeRedirect.url=welcome

Resolve Views with Multiple Resolvers

If you have a lot of views in your web application, it is often insufficient to choose only one view-resolving strategy. Typically, InternalResourceViewResolver can resolve most of the internal JSP views, but there are usually other types of views that have to be resolved by ResourceBundleViewResolver. In this case, you have to combine both strategies for view resolution.

@Bean
public ResourceBundleViewResolver viewResolver() {
    ResourceBundleViewResolver viewResolver = new ResourceBundleViewResolver();
    viewResolver.setOrder(0);
    viewResolver.setBasename("court-views");
    return viewResolver;
}

@Bean
public InternalResourceViewResolver internalResourceViewResolver() {
    InternalResourceViewResolver viewResolver = new InternalResourceViewResolver();
    viewResolver.setOrder(1);
    viewResolver.setPrefix("/WEB-INF/jsp/");
    viewResolver.setSuffix(".jsp");
    return viewResolver;
}

When choosing more than one strategy at the same time, it’s important to specify the resolving priority. You can set the order properties of the view resolver beans for this purpose. The lower-order value represents the higher priority. Note that you should assign the lowest priority to InternalResourceViewResolver because it always resolves a view no matter whether it exists. So, other resolvers will have no chance to resolve a view if they have lower priorities. Now the resource bundle court-views.properties should only contain the views that can’t be resolved by InternalResourceViewResolver (e.g., the redirect views).

welcomeRedirect.(class)=org.springframework.web.servlet.view.RedirectView welcomeRedirect.url=welcome

Use the Redirect Prefix

If you have InternalResourceViewResolver configured in your web application context, it can resolve redirect views by using the redirect: prefix in the view name. Then the rest of the view name is treated as the redirect URL. For example, the view name redirect:welcome triggers a redirect to the relative URL welcome. You can also specify an absolute URL in the view name.

Map Exceptions Using @ExceptionHandler

Instead of configuring a HandlerExceptionResolver, you can annotate a method with @ExceptionHandler. It works in a similar way as the @RequestMapping annotation.

@Controller
@RequestMapping("/reservationForm")
@SessionAttributes("reservation")
public class ReservationFormController {
    @ExceptionHandler(ReservationNotAvailableException.class)
    public String handle(ReservationNotAvailableException ex) {
        return "reservationNotAvailable";
    }

    @ExceptionHandler
    public String handleDefault(Exception e) {
        return "error";
    }
    ...
}

You have here two methods annotated as @ExceptionHandler. The first is for handling the specific ReservationNotAvailableException; the second is the general (catchall) exception-handling method. You also don’t have to specify a HandlerExceptionResolver in the WebConfiguration anymore.

Methods annotated with @ExceptionHandler can have a variety of return types (like the @RequestMapping methods); here you just return the name of the view that needs to be rendered, but you could also have returned a ModelAndView, a View, and so on.

Although using @ExceptionHandler annotated methods is very powerful and flexible, there is a drawback when you put them in controllers. Those methods will work only for the controller they are defined in, so if you have an exception occurring in another controller (for instance, the WelcomeController), these methods won’t be called. Generic exception-handling methods have to be moved to a separate class, and that class has to be annotated with @ControllerAdvice.

@ControllerAdvice
public class ExceptionHandlingAdvice {

    @ExceptionHandler(ReservationNotAvailableException.class)
    public String handle(ReservationNotAvailableException ex) {
        return "reservationNotAvailable";
    }

    @ExceptionHandler
    public String handleDefault(Exception e) {
        return "error";
    }
}

This class will apply to all controllers in the application context, which is why it’s called @ControllerAdvice.

Create a Form’s Views

Let’s create the form view reservationForm. jsp. The form relies on Spring’s form tag library, as this simplifies a form’s data binding, display of error messages, and the redisplay of original values entered by the user in case of errors.

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

<html>                    
<head>                    
<title>Reservation Form</title>                
<style>                    
.error {
    color: #ff0000;
    font-weight: bold;
}
</style>                    
</head>                    

<body>                    
<form:form method="post" modelAttribute="reservation">                
<form:errors path="*" cssClass="error" />                
<table>                    
    <tr>                
        <td>Court Name</td>                
        <td><form:input path="courtName" /></td>                
        <td><form:errors path="courtName" cssClass="error" /></td>                
    </tr>                
    <tr>                
        <td>Date</td>                
        <td><form:input path="date" /></td>                
        <td><form:errors path="date" cssClass="error" /></td>                
    </tr>                
    <tr>                
        <td>Hour</td>                
        <td><form:input path="hour" /></td>                
        <td><form:errors path="hour" cssClass="error" /></td>                
    </tr>                
    <tr>                
        <td colspan="3"><input type="submit" /></td>                
    </tr>                
</table>                    
</form:form>                    
</body>                    
</html>                    

The Spring <form:form> declares two attributes. The method="post" attribute indicates that a form performs an HTTP POST request upon submission. The modelAttribute="reservation" attribute indicates that the form data is bound to a model named reservation. The first attribute should be familiar to you since it’s used on most HTML forms. The second attribute will become clearer once we describe the controller that handles the form.

Bear in mind the <form:form> tag is rendered into standard HTML before it’s sent to a user, so it’s not that modelAttribute="reservation" is of use to a browser; the attribute is used as a facility to generate the actual HTML form .

Next, you can find the <form:errors> tag, used to define a location in which to place errors in case a form does not meet the rules set forth by a controller. The attribute path="*" is used to indicate the display of all errors—given the wildcard *—whereas the attribute cssClass="error" is used to indicate a CSS formatting class to display the errors.

Next, you can find the form’s various <form:input> tags accompanied by another set of corresponding <form:errors> tags. These tags make use of the attribute path to indicate the form’s fields, which in this case are courtName, date, and hour.

The <form:input> tags are bound to properties corresponding to modelAttribute by using the path attribute. They show the user the original value of the field, which will be either the bound property value or the value rejected because of a binding error. They must be used inside the <form:form> tag, which defines a form that binds to modelAttribute by its name.

Finally, you can find the standard HTML tag <input type="submit" /> that generates a Submit button and trigger the sending of data to the server, followed by the </form:form> tag that closes out the form. If the form and its data are processed correctly, you need to create a success view to notify the user of a successful reservation . The reservationSuccess.jsp illustrated next serves this purpose:

<html>                    
<head>                    
<title>Reservation Success</title>                
</head>                    

<body>                    
Your reservation has been made successfully.
</body>                    
</html>                    

It’s also possible for errors to occur because of invalid values being submitted in a form. For example, if the date is not in a valid format or an alphabetic character is presented for hour, the controller is designed to reject such field values. The controller will then generate a list of selective error codes for each error to be returned to the form view, and the values are placed inside the <form:errors> tag.

For example, for an invalid value input in the date field, the following error codes are generated by a controller:

typeMismatch.command.date
typeMismatch.date
typeMismatch.java.time.LocalDate
typeMismatch

If you have a ResourceBundleMessageSource defined, you can include the following error messages in your resource bundle for the appropriate locale (e.g., messages.properties for the default locale):

typeMismatch.date=Invalid date format
typeMismatch.hour=Invalid hour format

The corresponding error codes and their values are returned to a user if a failure occurs when processing form data.

Now that you know the structure of the views involved with a form, as well as the data handled by it, let’s take a look at the logic that handles the submitted data (i.e., the reservation) in a form.

Create a Form’s Service Processing

This is not the controller but rather the service used by the controller to process the form’s data reservation. First define a make() method in the ReservationService interface.

package com.apress.springrecipes.court.service;
...
public interface ReservationService {
    ...
    void make(Reservation reservation)
        throws ReservationNotAvailableException;
}

Then you implement this make() method by adding a Reservation item to the list that stores the reservations. You throw a ReservationNotAvailableException in case of a duplicate reservation.

package com.apress.springrecipes.court.service;
...
public class ReservationServiceImpl implements ReservationService {
    ...
    @Override
    public void make(Reservation reservation) throws ReservationNotAvailableException {
        long cnt = reservations.stream()
            .filter(made -> Objects.equals(made.getCourtName(), reservation.getCourtName()))
            .filter(made -> Objects.equals(made.getDate(), reservation.getDate()))
            .filter(made -> made.getHour() == reservation.getHour())                 .count();

        if (cnt > 0) {
            throw new ReservationNotAvailableException(reservation
                .getCourtName(), reservation.getDate(), reservation
                .getHour());
        } else {
            reservations.add(reservation);
        }
    }
}

Now that you have a better understanding of the two elements that interact with a controller—a form’s views and the reservation service class—let’s create a controller to handle the court reservation form .

Create a Form’s Controller

A controller used to handle forms makes use of practically the same annotations you’ve already used in the previous recipes. So let’s get right to the code.

package com.apress.springrecipes.court.web;
...

@Controller
@RequestMapping("/reservationForm")
@SessionAttributes("reservation")
public class ReservationFormController {

    private final ReservationService reservationService;

    @Autowired
    public ReservationFormController(ReservationService reservationService) {
        this.reservationService = reservationService;
    }

    @RequestMapping(method = RequestMethod.GET)
    public String setupForm(Model model) {
        Reservation reservation = new Reservation();
        model.addAttribute("reservation", reservation);
        return "reservationForm";
    }

    @RequestMapping(method = RequestMethod.POST)
    public String submitForm(
        @ModelAttribute("reservation") Reservation reservation,
        BindingResult result, SessionStatus status) {
            reservationService.make(reservation);
            return "redirect:reservationSuccess";
    }
}

The controller starts by using the standard @Controller annotation, as well as the @RequestMapping annotation that allows access to the controller through the following URL:

http://localhost:8080/court/reservationForm

When you enter this URL in your browser, it will send an HTTP GET request to your web application. This in turn triggers the execution of the setupForm method, which is designated to handle this type of request based on its @RequestMapping annotation.

The setupForm method defines a Model object as an input parameter, which serves to send model data to the view (i.e., the form). Inside the handler method, an empty Reservation object is created that is added as an attribute to the controller’s Model object. Then the controller returns the execution flow to the reservationForm view, which in this case is resolved to reservationForm.jsp (i.e., the form).

The most important aspect of this last method is the addition of an empty Reservation object . If you analyze the form reservationForm.jsp, you will notice the <form:form> tag declares the attribute modelAttribute="reservation". This means that upon rendering the view, the form expects an object named reservation to be available, which is achieved by placing it inside the handler method’s Model. In fact, further inspection reveals that the path values for each <form:input> tag correspond to the field names belonging to the Reservation object. Since the form is being loaded for the first time, it should be evident that an empty Reservation object is expected.

Another aspect that is vital to describe prior to analyzing the other controller handler method is the @SessionAttributes("reservation") annotation —declared at the top of the controller class. Since it’s possible for a form to contain errors, it can be an inconvenience to lose whatever valid data was already provided by a user on every subsequent submission. To solve this problem, the @SessionAttributes annotation is used to save a reservation field to a user’s session so that any future reference to the reservation field is in fact made on the same reference, whether a form is submitted twice or more times. This is also the reason why only a single Reservation object is created and assigned to the reservation field in the entire controller. Once the empty Reservation object is created—inside the HTTP GET handler method—all actions are made on the same object, since it’s assigned to a user’s session.

Now let’s turn our attention to submitting the form for the first time. After you have filled in the form fields, submitting the form triggers an HTTP POST request, which in turn invokes the submitForm method —on account of this method’s @RequestMapping value. The input fields declared for the submitForm method are three. The @ModelAttribute("reservation") Reservation reservation is used to reference the reservation object. The BindingResult object contains newly submitted data by the user. The SessionStatus object is used so that it is possible to mark the processing as completed, after which the Reservation object will be removed from the HttpSession.

At this juncture, the handler method doesn’t incorporate validation or perform access to a user’s session, which is the purpose of the BindingResult object and SessionStatus object—we will describe and incorporate them shortly.

The only operation performed by the handler method is reservationService.make(reservation);. This operation invokes the reservation service using the current state of the reservation object. Generally, controller objects are first validated prior to performing this type of operation on them. Finally, note the handler method returns a view named redirect:reservationSuccess. The actual name of the view in this case is reservationSuccess, which is resolved to the reservationSuccess.jsp page you created earlier.

The redirect: prefix in the view name is used to avoid a problem known as duplicate form submission .

When you refresh the web page in the form success view, the form you just submitted is resubmitted. To avoid this problem, you can apply the post/redirect/get design pattern, which recommends redirecting to another URL after a form submission is handled successfully, instead of returning an HTML page directly. This is the purpose of prefixing a view name with redirect:.

Initialize a Model Attribute Object and Prepopulate a Form with Values

The form is designed to let users make reservations. However, if you analyze the Reservation domain class, you will note the form is still missing two fields to create a complete reservation object. One of these fields is the player field, which corresponds to a Player object. Per the Player class definition, a Player object has both a name field and a phone field.

So, can the player field be incorporated into a form view and controller? Let’s analyze the form view first.

<html>                  
<head>                  
<title>Reservation Form</title>              
</head>                  
<body>                  
<form method="post" modelAttribute="reservation">              
<table>                  
    ...
    <tr>              
        <td>Player Name</td>              
        <td><form:input path="player.name" /></td>              
        <td><form:errors path="player.name" cssClass="error" /></td>              
    </tr>              
    <tr>              
        <td>Player Phone</td>              
        <td><form:input path="player.phone" /></td>              
        <td><form:errors path="player.phone" cssClass="error" /></td>              
    </tr>              
    <tr>              
        <td colspan="3"><input type="submit" /></td>              
    </tr>              
</table>                  
</form>                  
</body>                  
</html>                  

Using a straightforward approach, you add two additional <form:input> tags to represent the Player object’s fields . Though these form declarations are simple, you also need to perform modifications to the controller. Recall that by using <form:input> tags, a view expects to have access to model objects passed by the controller that match the path value for <form:input> tags.

Though the controller’s HTTP GET handler method returns an empty reservation named Reservation to this last view, the player property is null, so it causes an exception when rendering the form. To solve this problem, you have to initialize an empty Player object and assign it to the Reservation object returned to the view.

@RequestMapping(method = RequestMethod.GET)
public String setupForm(
@RequestParam(required = false, value = "username") String username, Model model) {
    Reservation reservation = new Reservation();
    reservation.setPlayer(new Player(username, null));
    model.addAttribute("reservation", reservation);
    return "reservationForm";
}

In this case, after creating the empty Reservation object, the setPlayer method is used to assign it an empty Player object. Further note that the creation of the Person object relies on the username value. This particular value is obtained from the @RequestParam input value, which was also added to the handler method. By doing so, the Player object can be created with a specific username value passed in as a request parameter, resulting in the username form field being prepopulated with this value.

So, for example, if a request to the form is made in the following manner:

http://localhost:8080/court/reservationForm?username=Roger

this allows the handler method to extract the username parameter to create the Player object , in turn prepopulating the form’s username form field with a Roger value. It’s worth noting that the @RequestParam annotation for the username parameter uses the property required=false; this allows a form request to be processed even if such a request parameter is not present.

Provide Form Reference Data

When a form controller is requested to render the form view, it may have some types of reference data to provide to the form (e.g., the items to display in an HTML selection). Now suppose you want to allow a user to select the sport type when reserving a court—which is the final unaccounted field for the Reservation class.

<html>                  
<head>                  
<title>Reservation Form</title>              
</head>                  
<body>                  
<form method="post" modelAttribute="reservation">              
<table>                  
    ...
    <tr>              
        <td>Sport Type</td>              
        <td><form:select path="sportType" items="${sportTypes}"            itemValue="id" itemLabel="name" /></td>              
        <td><form:errors path="sportType" cssClass="error" /></td>              
    </tr>              
    <tr>              
<tdcolspan="3"><input type="submit" /></td>              
    /<tr>              
</table>                  
</form>                  
</body>                  
</html>                  

The <form:select> tag provides a way to generate a drop-down list of values passed to the view by the controller. Thus, the form represents the sportType field as a set of HTML <select> elements, instead of the previous open-ended fields—<input>—that require a user to introduce text values.

Next, let’s take a look at how the controller assigns the sportType field as a model attribute; the process is a little different from the previous fields.

First let’s define the getAllSportTypes() method in the ReservationService interface for retrieving all available sport types.

package com.apress.springrecipes.court.service;
...
public interface ReservationService {
    ...
    public List<SportType> getAllSportTypes();
}

Then you can implement this method by returning a hard-coded list.

package com.apress.springrecipes.court.service;
...
public class ReservationServiceImpl implements ReservationService {
    ...
    public static final SportType TENNIS = new SportType(1, "Tennis");
    public static final SportType SOCCER = new SportType(2, "Soccer");

    public List<SportType> getAllSportTypes() {
        return Arrays.asList(TENNIS, SOCCER);
    }
}

Now that you have an implementation that returns a hard-coded list of SportType objects , let’s take a look at how the controller associates this list for it to be returned to the form view.

package com.apress.springrecipes.court.service;
.....
    @ModelAttribute("sportTypes")
    public List<SportType> populateSportTypes() {
        return reservationService.getAllSportTypes();
    }

    @RequestMapping(method = RequestMethod.GET)
    public String setupForm(
    @RequestParam(required = false, value = "username") String username, Model model) {
        Reservation reservation = new Reservation();
        reservation.setPlayer(new Player(username, null));
        model.addAttribute("reservation", reservation);
        return "reservationForm";
    }

Notice that the setupForm handler method charged with returning the empty Reservation object to the form view remains unchanged.

The new addition and what is responsible for passing a SportType list as a model attribute to the form view is the method decorated with the @ModelAttribute("sportTypes") annotation. The @ModelAttribute annotation is used to define global model attributes, available to any returning view used in handler methods. In the same way, a handler method declares a Model object as an input parameter and assigns attributes that can be accessed in the returning view.

Since the method decorated with the @ModelAttribute("sportTypes") annotation has a return type of List<SportType> and makes a call to reservationService.getAllSportTypes(), the hard-coded TENNIS and SOCCER SportType objects are assigned to the model attribute named sportTypes. This last model attribute is used in the form view to populate a drop-down list (i.e., <form:select> tag).

Bind Properties of Custom Types

When a form is submitted, a controller binds the form field values to the model object’s properties of the same name, in this case a Reservation object. However, for properties of custom types, a controller is not able to convert them unless you specify the corresponding property editors for them.

For example, the sport type selection field only submits the selected sport type ID—as this is the way HTML <select> fields operate. Therefore, you have to convert this ID into a SportType object with a property editor. First, you require the getSportType() method in ReservationService to retrieve a SportType object by its ID.

package com.apress.springrecipes.court.service;
...
public interface ReservationService {
    ...
    public SportType getSportType(int sportTypeId);
}

For testing purposes, you can implement this method with a switch/case statement.

package com.apress.springrecipes.court.service;
...
public class ReservationServiceImpl implements ReservationService {
    ...
    public SportType getSportType(int sportTypeId) {
        switch (sportTypeId) {
        case 1:
            return TENNIS;
        case 2:
            return SOCCER;
        default:
            return null;
        }
    }
}

Then you create the SportTypeConverter class to convert a sport type ID into a SportType object. This converter requires ReservationService to perform the lookup.

package com.apress.springrecipes.court.domain;

import com.apress.springrecipes.court.service.ReservationService;
import org.springframework.core.convert.converter.Converter;

public class SportTypeConverter implements Converter<String, SportType> {

    private ReservationService reservationService;

    public SportTypeConverter(ReservationService reservationService) {
        this.reservationService = reservationService;
    }

    @Override
    public SportType convert(String source) {
        int sportTypeId = Integer.parseInt(source);
        SportType sportType = reservationService.getSportType(sportTypeId);
        return sportType;
    }
}

Now that you have the supporting SportTypeConverter class required to bind form properties to a custom class like SportType, you need to associate it with the controller. For this purpose, you can use the addFormatters method from the WebMvcConfigurer.

By overriding this method in your configuration class, custom types can be associated with a controller. This includes the SportTypeConverter class and other custom types like Date. Though we didn’t mention the date field earlier, it suffers from the same problem as the sport type selection field. A user introduces date fields as text values. For the controller to assign these text values to the Reservation object’s date field, this requires the date fields to be associated with a Date object. Given that the Date class is part of the Java language, it won’t be necessary to create a special class like SportTypeConverter. For this purpose, the Spring Framework already includes a custom class.

Knowing you need to bind both the SportTypeConverter class and a Date class to the underlying controller, the following code illustrates the modifications to the configuration class:

package com.apress.springrecipes.court.web.config;
...
import com.apress.springrecipes.court.domain.SportTypeConverter;
import com.apress.springrecipes.court.service.ReservationService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.format.FormatterRegistry;
import org.springframework.format.datetime.DateFormatter;

@Configuration
@EnableWebMvc
@ComponentScan("com.apress.springrecipes.court.web")
public class WebConfiguration implements WebMvcConfigurer {

    @Autowired
    private ReservationService reservationService;

    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addConverter(new SportTypeConverter(reservationService));
    }
 }

The only field for this last class corresponds to reservationService, used to access the application’s ReservationService bean. Note the use of the @Autowired annotation that enables the injection of the bean. Next, you can find the addFormatters method used to bind the Date and SportTypeConverter classes . You can then find two calls to register the converter and formatter. These methods belong to the FormatterRegistry object, which is passed as an input parameter to the addFormatters method.

The first call is used to bind a Date class to the DateFormatter class. The DateFormatter class is provided by the Spring Framework and offers functionality to parse and print Date objects.

The second call is used to register the SportTypeConverter class. Since you created the SportTypeConverter class, you should know that its only input parameter is a ReservationService bean. By using this approach, every annotation-based controller (i.e., classes using the @Controller annotation) can have access to the same custom converters and formatters in their handler methods.

Validate Form Data

When a form is submitted, it’s standard practice to validate the data provided by a user before a submission is successful. Spring MVC supports validation by means of a validator object that implements the Validator interface. You can write the following validator to check whether the required form fields are filled and whether the reservation hour is valid on holidays and weekdays:

package com.apress.springrecipes.court.domain;

import org.springframework.stereotype.Component;
import org.springframework.validation.Errors;
import org.springframework.validation.ValidationUtils;
import org.springframework.validation.Validator;

import java.time.DayOfWeek;
import java.time.LocalDate;

@Component
public class ReservationValidator implements Validator {

    public boolean supports(Class<?> clazz) {
        return Reservation.class.isAssignableFrom(clazz);
    }

    public void validate(Object target, Errors errors) {
        ValidationUtils.rejectIfEmptyOrWhitespace(errors, "courtName",
            "required.courtName", "Court name is required.");
        ValidationUtils.rejectIfEmpty(errors, "date",
            "required.date", "Date is required.");
        ValidationUtils.rejectIfEmpty(errors, "hour",
            "required.hour", "Hour is required.");
        ValidationUtils.rejectIfEmptyOrWhitespace(errors, "player.name",
            "required.playerName", "Player name is required.");
        ValidationUtils.rejectIfEmpty(errors, "sportType",
            "required.sportType", "Sport type is required.");

        Reservation reservation = (Reservation) target;
        LocalDate date = reservation.getDate();
        int hour = reservation.getHour();
        if (date != null) {
            if (date.getDayOfWeek() == DayOfWeek.SUNDAY) {
                if (hour < 8 || hour > 22) {
                    errors.reject("invalid.holidayHour", "Invalid holiday hour.");
                }
            } else {
                if (hour < 9 || hour > 21) {
                    errors.reject("invalid.weekdayHour", "Invalid weekday hour.");
                }
            }
        }
    }
}

In this validator, you use utility methods such as rejectIfEmptyOrWhitespace() and rejectIfEmpty() in the ValidationUtils class to validate the required form fields. If any of these form fields are empty, these methods will create a field error and bind it to the field. The second argument of these methods is the property name, while the third and fourth are the error code and default error message.

You also check whether the reservation hour is valid on holidays and weekdays. In case of invalidity, you should use the reject() method to create an object error to be bound to the reservation object, not to a field.

Since the validator class is annotated with the @Component annotation, Spring attempts to instantiate the class as a bean in accordance with the class name, in this case reservationValidator.

Since validators may create errors during validation, you should define messages for the error codes for displaying to the user. If you have ResourceBundleMessageSource defined, you can include the following error messages in your resource bundle for the appropriate locale (e.g., messages.properties for the default locale):

required.courtName=Court name is required
required.date=Date is required
required.hour=Hour is required
required.playerName=Player name is required
required.sportType=Sport type is required
invalid.holidayHour=Invalid holiday hour
invalid.weekdayHour=Invalid weekday hour

To apply this validator, you need to perform the following modification to your controller:

package com.apress.springrecipes.court.service;
.....
    private ReservationService reservationService;
    private ReservationValidator reservationValidator;

    public ReservationFormController(ReservationService reservationService,
        ReservationValidator reservationValidator) {
        this.reservationService = reservationService;
        this.reservationValidator = reservationValidator;
    }

    @RequestMapping(method = RequestMethod.POST)
    public String submitForm(
        @ModelAttribute("reservation") @Validated Reservation reservation,
        BindingResult result, SessionStatus status) {
        if (result.hasErrors()) {
            return "reservationForm";
        } else {
            reservationService.make(reservation);
            return "redirect:reservationSuccess";
        }
    }

    @InitBinder
    public void initBinder(WebDataBinder binder) {
        binder.setValidator(reservationValidator);
    }

The first addition to the controller is the ReservationValidator field , which gives the controller access to an instance of the validator bean.

The next modification takes place in the HTTP POST handler method , which is always called when a user submits a form. Next to the @ModelAttribute annotation there is now an @Validated annotation, which triggers validation of the object. After the validation, the result parameter—the BindingResult object—contains the results for the validation process. Next, a conditional based on the value of result.hasErrors() is made. If the validation class detects errors, this value is true.

If errors are detected in the validation process, the method handler returns the view reservationForm, which corresponds to the same form so a user can resubmit information. If no errors are detected in the validation process, a call is made to perform the reservation— reservationService.make(reservation);—followed by a redirection to the success view reservationSuccess.

The registration of the validator is done in the @InitBinder annotated method , and the validator is set on the WebDataBinder so that it can be used after binding. To register the validator, you need to use the setValidator method. You can also register multiple validators using the addValidators method, which takes a varargs argument for one or more Validator instances.

Expire a Controller’s Session Data

To support the possibility of a form being submitted multiple times and not losing data provided by a user between submissions, the controller relies on the use of the @SessionAttributes annotation. By doing so, a reference to the reservation field represented as a Reservation object is saved between requests.

However, once a form is submitted successfully and a reservation is made, there is no point in keeping the Reservation object in a user’s session. In fact, if a user revisits the form within a short period of time, there is a possibility that remnants of this old Reservation object emerge if not removed.

Values assigned using the @SessionAttributes annotation can be removed using the SessionStatus object, which is an object that can be passed as an input parameter to handler methods. The following code illustrates how to expire the controller’s session data:

package com.apress.springrecipes.court.web;

@Controller
@RequestMapping("/reservationForm")
@SessionAttributes("reservation")
public class ReservationFormController {

    @RequestMapping(method = RequestMethod.POST)
    public String submitForm(
        @ModelAttribute("reservation") Reservation reservation,
        BindingResult result, SessionStatus status) {

        if (result.hasErrors()) {
            return "reservationForm";
        } else {
            reservationService.make(reservation);
            status.setComplete();
            return "redirect:reservationSuccess";
        }
     }
   }

Once the handler method performs the reservation by calling reservationService.make(reservation); and right before a user is redirected to a success page, it becomes an ideal time in which expire a controller’s session data. This is done by calling the setComplete() method on the SessionStatus object. It’s that simple .

Create Wizard Form Pages

Suppose you want to show users the periodic reservation form split across three different pages. Each page has a portion of the form fields. The first page is reservationCourtForm.jsp, which contains only the court name field for the periodic reservation .

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

<html>                    
<head>                    
<title>Reservation Court Form</title>                
<style>                    
.error {
    color: #ff0000;
    font-weight: bold;
}
</style>                    
</head>                    

                      <body>                    
<form:form method="post" modelAttribute="reservation">
                      <table>                    
    <tr>                
        <td>Court Name</td>                
        <td><form:input path="courtName" /></td>                
        <td><form:errors path="courtName" cssClass="error" /></td>                
    </tr>                
    <tr>                
        <td colspan="3">
            <input type="hidden" value="0" name="_page" />
            <input type="submit" value="Next" name="_target1" />
            <input type="submit" value="Cancel" name="_cancel" />
        </td>                
    </tr>                
                      </table>                    
                      </form:form>                    
                      </body>                    
                      </html>                    

The form and input fields in this page are defined with Spring’s <form:form> and <form:input> tags. They are bound to the model attribute reservation and its properties. There’s also an error tag for displaying the field error message to the user. Note that there are two submit buttons in this page. The Next button’s name must be _target1. It asks the wizard form controller to step forward to the second page, whose page index is 1 (zero-based). The Cancel button’s name must be _cancel. It asks the controller to cancel this form. In addition, there is also a hidden form field to keep track of the page a user is on; in this case, it corresponds to 0.

The second page is reservationTimeForm.jsp. It contains the date and time fields for a periodic reservation .

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

<html>                    
<head>                    
<title>Reservation Time Form</title>                
<style>                    
.error {
    color: #ff0000;
    font-weight: bold;
}
</style>                    
</head>                    

<body>
<form:form method="post" modelAttribute="reservation">
<table>                    
    <tr>                
        <td>From Date</td>                
        <td><form:inputpath="fromDate" /></td>                
        <td><form:errors path="fromDate" cssClass="error" /></td>                
    </tr>                
    <tr>                
        <td>To Date</td>                
        <td><form:input path="toDate" /></td>                
        <td><form:errors path="toDate" cssClass="error" /></td>                
    </tr>                
    <tr>                
        <td>Period</td>                
        <td><form:select path="period" items="${periods}" /></td>                
        <td><form:errors path="period" cssClass="error" /></td>                
    </tr>                
    <tr>                
        <td>Hour</td>                
        <td><form:input path="hour" /></td>                
        <td><form:errors path="hour" cssClass="error" /></td>                
    </tr>                
    <tr>                
        <td colspan="3">
            <input type="hidden" value="1" name="_page"/>
            <input type="submit" value="Previous" name="_target0" />
            <input type="submit" value="Next" name="_target2" />
            <input type="submit" value="Cancel" name="_cancel" />
        </td>                
    </tr>                
</table>                    
</form:form>                    
</body>                    
</html>                    

There are three submit buttons in this form. The names of the Previous and Next buttons must be _target0 and _target2, respectively . They ask the wizard form controller to step to the first page and the third page. The Cancel button asks the controller to cancel this form. In addition, there is a hidden form field to keep track of the page a user is on; in this case, it corresponds to 1.

The third page is reservationPlayerForm.jsp. It contains the player information fields for a periodic reservation .

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

<html>                    
<head>                    
<title>Reservation Player Form</title>                
<style>                    
.error {
    color: #ff0000;
    font-weight: bold;
}
</style>                    
</head>                    

<body>                    
<form:form method="POST" commandName="reservation">
<table>                    
    <tr>                
        <td>Player Name</td>                
        <td><form:input path="player.name" /></td>                
        <td><form:errors path="player.name" cssClass="error" /></td>                
    </tr>                
    <tr>                
        <td>Player Phone</td>                
        <td><form:input path="player.phone" /></td>                
        <td><form:errors path="player.phone" cssClass="error" /></td>                
    </tr>                
    <tr>                
        <td colspan="3">
            <input type="hidden" value="2" name="_page"/>
            <input type="submit" value="Previous" name="_target1" />
            <input type="submit" value="Finish" name="_finish" />
            <input type="submit" value="Cancel" name="_cancel" />
        </td>                
    </tr>                
</table>                    
</form:form>                    
</body>                    
</html>                    

There are three submit buttons in this form. The Previous button asks the wizard form controller to step back to the second page. The Finish button’s name must be _finish. It asks the controller to finish this form. The Cancel button asks the controller to cancel this form. In addition, there is a hidden form field to keep track of the page a user is on; in this case, it corresponds to 2.

Create a Wizard Form Controller

Now let’s create a wizard form controller to handle this periodic reservation form. Like the previous Spring MVC controllers, this controller has four main handler methods—one for HTTP GET requests and others for HTTP POST requests—as well as makes use of the same controller elements (e.g., annotations, validation, or sessions) used in prior controllers. For a wizard form controller, all the form fields in different pages are bound to a single model attribute’s Reservation object, which is stored in a user’s session across multiple requests.

package com.apress.springrecipes.court.web;

import com.apress.springrecipes.court.domain.PeriodicReservation;
import com.apress.springrecipes.court.domain.Player;
import com.apress.springrecipes.court.service.ReservationService;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.bind.support.SessionStatus;
import org.springframework.web.util.WebUtils;

import javax.annotation.PostConstruct;
import javax.servlet.http.HttpServletRequest;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.Map;

@Controller
@RequestMapping("/periodicReservationForm")
@SessionAttributes("reservation")
public class PeriodicReservationController {

    private final Map<Integer, String> pageForms = new HashMap<>(3);
    private final ReservationService reservationService;

    public PeriodicReservationController(ReservationService reservationService) {
        this.reservationService = reservationService;
    }

    @PostConstruct
    public void initialize() {
        pageForms.put(0, "reservationCourtForm");
        pageForms.put(1, "reservationTimeForm");
        pageForms.put(2, "reservationPlayerForm");
    }

    @GetMapping
    public String setupForm(Model model) {
        PeriodicReservation reservation = new PeriodicReservation();
        reservation.setPlayer(new Player());
        model.addAttribute("reservation", reservation);
        return "reservationCourtForm";
    }

    @PostMapping(params = {"_cancel"})
    public String cancelForm(@RequestParam("_page") int currentPage) {

        return pageForms.get(currentPage);
    }

    @PostMapping(params = {"_finish"})
    public String completeForm(
        @ModelAttribute("reservation") PeriodicReservation reservation,
        BindingResult result, SessionStatus status,
        @RequestParam("_page") int currentPage) {

        if (!result.hasErrors()) {
            reservationService.makePeriodic(reservation);
            status.setComplete();
            return "redirect:reservationSuccess";
        } else {
            return pageForms.get(currentPage);
        }
    }

    @PostMapping
    public String submitForm(
        HttpServletRequest request,
        @ModelAttribute("reservation") PeriodicReservation reservation,
        BindingResult result, @RequestParam("_page") int currentPage) {

        int targetPage = getTargetPage(request, "_target", currentPage);
        if (targetPage < currentPage) {
            return pageForms.get(targetPage);
        }

        if (!result.hasErrors()) {
            return pageForms.get(targetPage);
        } else {
            return pageForms.get(currentPage);
        }
    }

    @ModelAttribute("periods")
    public Map<Integer, String> periods() {

        Map<Integer, String> periods = new HashMap<Integer, String>();
        periods.put(1, "Daily");
        periods.put(7, "Weekly");
        return periods;
    }

    private int getTargetPage(HttpServletRequest request, String paramPrefix, int currentPage) {

        Enumeration<String> paramNames = request.getParameterNames();
        while (paramNames.hasMoreElements()) {
            String paramName = paramNames.nextElement();
            if (paramName.startsWith(paramPrefix)) {
                for (int i = 0; i < WebUtils.SUBMIT_IMAGE_SUFFIXES.length; i++) {
                    String suffix = WebUtils.SUBMIT_IMAGE_SUFFIXES[i];
                    if (paramName.endsWith(suffix)) {
                        paramName = paramName.substring(0, paramName.length() - suffix.length());
                    }
                }
                return Integer.parseInt(paramName.substring(paramPrefix.length()));
            }
        }
        return currentPage;
    }
}

This controller uses some of the same elements used in the previous ReservationFormController controller, so we won’t go into specifics about what’s already been explained. But to recap, it uses the @SessionAttributes annotation to place the reservation object in a user’s session. It has the same HTTP GET method used to assign empty Reservation and Player objects upon loading the first form view.

Next, the controller defines a HashMap in which it associates page numbers to view names. This HashMap is used various times in the controller since the controller needs to determine target views for a variety of scenarios (e.g., validation or a user clicking Cancel or Next).

You can also find the method decorated with the @ModelAttribute("periods") annotation. As it was illustrated in previous controllers, this declaration allows a list of values to be made available to any returning view placed in the controller. If you look at the previous form reservationTimeForm.jsp, you can see that it expects to have access to a model attribute named periods.

Then you can find that the first @PostMapping will be called if the incoming request has the _cancel parameter in the URL. It also tries to extract the currentPage value by extracting the page attribute from the request using @RequestParam("page"). When this method is called, it returns control to the view corresponding to the currentPage value. The result is that the input is reset to the input prior to changing the content of the input fields.

The next @PostMapping(params={"_finish"}) will be called if the incoming request has the _finish parameter in the URL, which is the case if the user clicked the Finish button. As this is the final step in the process, you want to validate the Reservation object, and for that you annotate the attribute with @Validated. When there are no errors, the handler method makes the reservation by calling reservationService.makePeriodic(reservation); and redirects the user to the reservationSuccess view.

The final handler method with @PostMapping handles the remaining cases and declares an input parameter for the HttpServletRequest, allowing the handler method to access this object’s contents. Previous handler methods used parameters such as @RequestParam to input data typically located in these standard objects, as a shortcut mechanism. It demonstrates that full access to the standard HttpServletRequest and HttpServletResponse objects inside a handler method is possible. The names and notation for the remaining input parameters should be familiar to you from earlier controllers. If this handler method is called, it means the user clicked either the Next or Previous button on either of the forms. As a consequence, this means that inside the HttpServletRequest object there is a parameter named _target. This is because each of the form’s Next and Previous buttons is assigned this parameter.

Using the getTargetPage method , the value for the _target parameter is extracted, which corresponds to either target0, target1, or target2 and is trimmed to 0, 1, or 2 representing the target page.

Once you have the target page number and the current page number, you can determine whether the user clicked the Next or Previous button. If the target page is lower than the current page, this means the user clicked the Previous button. If the target page number is greater than the current page number, this means the user clicked the Next button.

At this juncture, it isn’t clear why you need to determine whether a user clicked the Next or Previous button, especially since a view corresponding to the target page is always returned. But the reason behind this logic is the following: if a user clicked the Next button, you will want to validate the data, whereas if a user clicked the Previous button, there is no need to validate anything. This will become obvious in the next section when validation is incorporated into the controller.

As you have the PeriodicReservationController class decorated with the @RequestMapping("/periodicReservationForm") annotation, you can access this controller through the following URL :

http://localhost:8080/court/periodicReservation

Validate Wizard Form Data

In a simple form controller, you validate the entire model attribute object in one shot when the form is submitted. However, as there are multiple form pages for a wizard form controller, you have to validate each page when it’s submitted. For this reason, you create the following validator, which splits the validate() method into several fine-grained validate methods, each of which validates fields in a particular page:

package com.apress.springrecipes.court.domain;

import org.springframework.validation.Errors;
import org.springframework.validation.ValidationUtils;
import org.springframework.validation.Validator;

public class PeriodicReservationValidator implements Validator {

    public boolean supports(Class clazz) {
        return PeriodicReservation.class.isAssignableFrom(clazz);
    }

    public void validate(Object target, Errors errors) {
        validateCourt(target, errors);
        validateTime(target, errors);
        validatePlayer(target, errors);
    }

    public void validateCourt(Object target, Errors errors) {
        ValidationUtils.rejectIfEmptyOrWhitespace(errors, "courtName",
            "required.courtName", "Court name is required.");
    }

    public void validateTime(Object target, Errors errors) {
        ValidationUtils.rejectIfEmpty(errors, "fromDate",
            "required.fromDate", "From date is required.");
        ValidationUtils.rejectIfEmpty(errors, "toDate", "required.toDate",
            "To date is required.");
        ValidationUtils.rejectIfEmpty(errors, "period",
            "required.period", "Period is required.");
        ValidationUtils.rejectIfEmpty(errors, "hour", "required.hour",
            "Hour is required.");
    }

    public void validatePlayer(Object target, Errors errors) {
        ValidationUtils.rejectIfEmptyOrWhitespace(errors, "player.name",
            "required.playerName", "Player name is required.");
    }
}

Similar to the earlier validator example, notice that this validator also relies on the @Component annotation to automatically register the validator class as a bean. Once the validator bean is registered, the only thing left to do is incorporate the validator into the controller .

package com.apress.springrecipes.court.web;

import com.apress.springrecipes.court.domain.PeriodicReservation;
import com.apress.springrecipes.court.domain.PeriodicReservationValidator;
import com.apress.springrecipes.court.domain.Player;
import com.apress.springrecipes.court.service.ReservationService;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.WebDataBinder;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.bind.support.SessionStatus;
import org.springframework.web.util.WebUtils;

import javax.annotation.PostConstruct;
import javax.servlet.http.HttpServletRequest;
import java.util.Enumeration;
import java.util.HashMap;
import java.util.Map;

@Controller
@RequestMapping("/periodicReservationForm")
@SessionAttributes("reservation")
public class PeriodicReservationController {

    private final Map<Integer, String> pageForms = new HashMap<>(3);
    private final ReservationService reservationService;
    private final PeriodicReservationValidator validator;

    public PeriodicReservationController(ReservationService reservationService,
                                         PeriodicReservationValidator periodicReservationValidator) {
        this.reservationService = reservationService;
        this.validator = periodicReservationValidator;
    }

    @InitBinder
    public void initBinder(WebDataBinder binder) {
        binder.setValidator(this.validator);
    }

    @PostMapping(params = {"_finish"})
    public String completeForm(
        @Validated @ModelAttribute("reservation") PeriodicReservation reservation,
        BindingResult result, SessionStatus status,
        @RequestParam("_page") int currentPage) {
        if (!result.hasErrors()) {
            reservationService.makePeriodic(reservation);
            status.setComplete();
            return "redirect:reservationSuccess";
        } else {
            return pageForms.get(currentPage);
        }
    }

    @PostMapping
    public String submitForm(
        HttpServletRequest request,
        @ModelAttribute("reservation") PeriodicReservation reservation,
        BindingResult result, @RequestParam("_page") int currentPage) {
        int targetPage = getTargetPage(request, "_target", currentPage);
        if (targetPage < currentPage) {
            return pageForms.get(targetPage);
        }
        validateCurrentPage(reservation, result, currentPage);
        if (!result.hasErrors()) {
            return pageForms.get(targetPage);
        } else {
            return pageForms.get(currentPage);
        }
    }

    private void validateCurrentPage(PeriodicReservation reservation,        BindingResult result, int currentPage) {
        switch (currentPage) {
            case 0:
                validator.validateCourt(reservation, result);
                break;
            case 1:
                validator.validateTime(reservation, result);
                break;
            case 2:
                validator.validatePlayer(reservation, result);
                break;
        }
    }

    ...
}

The first addition to the controller is the validator field that is assigned an instance of the PeriodicReservationValidator validator bean via the class’s constructor. You can then find two references to the validator in the controller.

The first one is when a user finishes submitting a form. To call the validator, you need to add the @Validated annotation to the method’s Reservation argument. To make that actually do something, you also need to add an @InitBinder annotated method , which registers the PeriodicReservationValidator with the data binder. If the validator returns no errors, the reservation is committed, a user’s session is reset, and the user is redirected to the reservationSuccess view. If the validator returns errors, a user is sent to the current view form to correct the errors. (See also recipe 3-9.)

The second occasion the validator is used in the controller is when a user clicks the Next button on a form. Since a user is attempting to advance to the next form, it’s necessary to validate whatever data a user provided. Given there are three possible form views to validate, a case statement is used to determine what validator method to invoke. Once the execution of a validator method returns, if errors are detected, a user is sent to the currentPage view to can correct the errors; if no errors are detected, a user is sent to the targetPage view; note that these target pages numbers are mapped to a Map in the controller.

Create Excel Views

An Excel view can be created by extending the AbstractXlsView or AbstractXlsxView class (for Apache POI). Here, AbstractXlsxView is used as an example. In the buildExcelDocument() method, you can access the model passed from the controller and also a precreated Excel workbook. Your task is to populate the workbook with the data in the model.

<dependency>
    <groupId>org.apache.poi</groupId>
    <artifactId>poi</artifactId>
    <version>3.10-FINAL</version>
</dependency>

package com.apress.springrecipes.court.web.view;

import com.apress.springrecipes.court.domain.Reservation;
import org.apache.poi.ss.usermodel.Row;
import org.apache.poi.ss.usermodel.Sheet;
import org.apache.poi.ss.usermodel.Workbook;
import org.springframework.web.servlet.view.document.AbstractXlsxView;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.List;
import java.util.Map;

public class ExcelReservationSummary extends AbstractXlsxView {

    @Override
    protected void buildExcelDocument(Map<String, Object> model, Workbook workbook, HttpServletRequest request, HttpServletResponse response) throws Exception {
        @SuppressWarnings({"unchecked"})
        final List<Reservation> reservations =            (List<Reservation>) model.get("reservations");
        final DateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
        final Sheet sheet = workbook.createSheet();

        addHeaderRow(sheet);

        reservations.forEach(reservation -> createRow(dateFormat, sheet, reservation));
    }

    private void addHeaderRow(Sheet sheet) {
        Row header = sheet.createRow(0);
        header.createCell((short) 0).setCellValue("Court Name");
        header.createCell((short) 1).setCellValue("Date");
        header.createCell((short) 2).setCellValue("Hour");
        header.createCell((short) 3).setCellValue("Player Name");
        header.createCell((short) 4).setCellValue("Player Phone");
    }

    private void createRow(DateFormat dateFormat, Sheet sheet, Reservation reservation) {
        Row row = sheet.createRow(sheet.getLastRowNum() + 1);
        row.createCell((short) 0).setCellValue(reservation.getCourtName());
        row.createCell((short) 1).setCellValue(dateFormat.format(reservation.getDate()));
        row.createCell((short) 2).setCellValue(reservation.getHour());
        row.createCell((short) 3).setCellValue(reservation.getPlayer().getName());
        row.createCell((short) 4).setCellValue(reservation.getPlayer().getPhone());
    }
}

In the preceding Excel view, you first create a sheet in the workbook. In this sheet, you show the headers of this report in the first row. Then you iterate over the reservation list to create a row for each reservation.

As you have @RequestMapping("/reservationSummary*") configured in your controller and the handler method requires a date as a request parameter, you can access this Excel view through the following URL:

http://localhost:8080/court/reservationSummary.xls?date=2009-01-14

Create PDF Views

A PDF view is created by extending the AbstractPdfView class . In the buildPdfDocument() method, you can access the model passed from the controller and also a precreated PDF document. Your task is to populate the document with the data in the model.

<dependency>
    <groupId>com.lowagie</groupId>    
<artifactId>itext</artifactId>    
<version>4.2.1</version>
</dependency

package com.apress.springrecipes.court.web.view;
...
import org.springframework.web.servlet.view.document.AbstractPdfView;

import com.lowagie.text.Document;
import com.lowagie.text.Table;
import com.lowagie.text.pdf.PdfWriter;

public class PdfReservationSummary extends AbstractPdfView {

    protected void buildPdfDocument(Map model, Document document,
        PdfWriter writer, HttpServletRequest request,
        HttpServletResponse response) throws Exception {
        List<Reservation> reservations = (List) model.get("reservations");
        DateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
        Table table = new Table(5);

        table.addCell("Court Name");
        table.addCell("Date");
        table.addCell("Hour");
        table.addCell("Player Name");
        table.addCell("Player Phone");

        for (Reservation reservation : reservations) {
            table.addCell(reservation.getCourtName());
            table.addCell(dateFormat.format(reservation.getDate()));
            table.addCell(Integer.toString(reservation.getHour()));
            table.addCell(reservation.getPlayer().getName());
            table.addCell(reservation.getPlayer().getPhone());
        }

        document.add(table);
    }
}

As you have @RequestMapping("/reservationSummary*") configured in your controller and the handler method requires a date as a request parameter, you can access this PDF view through the following URL:

http://localhost:8080/court/reservationSummary.pdf?date=2009-01-14

Create Resolvers for Excel and PDF Views

In recipe 3-6, you learned different strategies for resolving logical view names to specific view implementations. One of these strategies was resolving views from a resource bundle; this is the better-suited strategy for mapping logical view names to view implementations consisting of PDF or XLS classes.

Ensuring you have the ResourceBundleViewResolver bean configured in your web application context as a view resolver, you can then define views in the views.properties file included in a web application’s classpath root.

You can add the following entry to views.properties to map the XLS view class to a logical view name:

reservationSummary.(class)=com.apress.springrecipes.court.web.view.ExcelReservationSummary

Since the application relies on the process of content negotiation, this implies that the same view name is mapped to multiple view technologies. In addition, since it’s not possible to have duplicate names in the same views.properties file, you need to create a separate file named secondaryviews.properties to map the PDF view class to a logical view name, as illustrated next:

reservationSummary.(class)=com.apress.springrecipes.court.web.view.PdfReservationSummary

Take note that this file—secondaryviews.properties—needs to be configured in its own ResourceBundleViewResolver resolver. The property name—reservationSummary—corresponds to the view’s name returned by the controller. It’s the task of the ContentNegotiatingViewResolver resolver to determine which of these classes to use based on a user’s request. Once this is determined, the execution of the corresponding class generates either a PDF or XLS file.

Create Date-Based PDF and XLS File Names

When a user makes a request for a PDF or XLS file using any of the following URLs:

http://localhost:8080/court/reservationSummary.pdf?date=2008-01-14
http://localhost:8080/court/reservationSummary.xls?date=2008-02-24

the browser prompts a user with a question like “Save as reservationSummary.pdf ?” or “Save as reservationSummary.xls?” This convention is based on the URL a user is requesting a resource from. However, given that a user is also providing a date in the URL, a nice feature can be an automatic prompt in the form “Save as ReservationSummary_2009_01_24.xls?” or “Save as ReservationSummary_2009_02_24.xls?” This can be done by applying an interceptor to rewrite the returning URL. The following code illustrates this interceptor:

package com.apress.springrecipes.court.web
...

public class ExtensionInterceptor extends HandlerInterceptorAdapter {

    public void postHandle(HttpServletRequest request,
        HttpServletResponse response, Object handler,
            ModelAndView modelAndView) throws Exception {
        // Report date is present in request                
        String reportName = null;
        String reportDate = request.getQueryString().replace("date=","").replace("-","_");
        if(request.getServletPath().endsWith(".pdf")) {
            reportName= "ReservationSummary_" + reportDate + ".pdf";
        }
        if(request.getServletPath().endsWith(".xls")) {
            reportName= "ReservationSummary_" + reportDate + ".xls";
        }
        if (reportName != null) {
            response.setHeader("Content-Disposition","attachment; filename="+reportName);
        }
    }
}

The interceptor extracts the entire URL if it contains a .pdf or .xls extension. If it detects such an extension, it creates a value for the return file name in the form ReservationSummary_<report_date>.<.pdf|.xls>. To ensure a user receives a download prompt in this form, the HTTP header Content-Disposition is set with this file name format.

To deploy this interceptor and that it only be applied to the URL corresponding to the controller charged with generating PDF and XLS files, we advise you to look over recipe 3-3, which contains this particular configuration and more details about interceptor classes.

CONTENT NEGOTIATION AND SETTING HTTP HEADERS IN AN INTERCEPTOR

Though this application uses the ContentNegotiatingViewResolver resolver to select an appropriate view, the process of modifying a return URL is outside the scope of view resolvers. Therefore, it’s necessary to use an interceptor to manually inspect a request extension, as well as set the necessary HTTP headers to modify the outgoing URL.