JSP Integration

# ── Known limitations (see the Spring Boot reference documentation): ───

# 1. No executable JAR support
#    A JSP cannot be served from an executable JAR because of a hard-coded
#    file pattern in Tomcat. Package the application as a WAR instead:
#      - an executable WAR still runs with:  java -jar myapp.war
#      - the same WAR can be deployed to an external Tomcat
#    During development, mvn spring-boot:run also works.

# 2. Undertow does not support JSP
#    Use embedded Tomcat (the default in spring-boot-starter-web).

# 3. A custom error.jsp does not replace the default error view
#    Use Spring Boot custom error pages or a @ControllerAdvice instead.

# 4. Edited JSPs may not be picked up automatically
#    While developing, set server.servlet.jsp.init-parameters.development=true
#    (shown in the configuration section), or restart after changing a JSP.

# ── When JSP is acceptable: ───────────────────────────────────────────
# - Migrating a legacy Spring MVC application to Spring Boot
# - Team has deep JSP expertise and no budget to migrate
# - Deploying as WAR to an external Tomcat (standard enterprise setup)

# ── Recommended alternatives: ────────────────────────────────────────
# - Thymeleaf   → spring-boot-starter-thymeleaf  (recommended)
# - FreeMarker  → spring-boot-starter-freemarker
# - Mustache    → spring-boot-starter-mustache

<!-- pom.xml — packaging must be war: -->
<packaging>war</packaging>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- Only if you deploy to an external Tomcat (the WAR still runs with java -jar): -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-tomcat</artifactId>
        <scope>provided</scope>
    </dependency>

    <!-- Jasper — JSP compiler: -->
    <dependency>
        <groupId>org.apache.tomcat.embed</groupId>
        <artifactId>tomcat-embed-jasper</artifactId>
        <scope>provided</scope>
    </dependency>

    <!-- JSTL (Jakarta Tags 3.0 for Spring Boot 3) — taglib URIs are jakarta.tags.*: -->
    <dependency>
        <groupId>jakarta.servlet.jsp.jstl</groupId>
        <artifactId>jakarta.servlet.jsp.jstl-api</artifactId>
    </dependency>
    <dependency>
        <groupId>org.glassfish.web</groupId>
        <artifactId>jakarta.servlet.jsp.jstl</artifactId>
    </dependency>
</dependencies>

<!-- Gradle: apply the 'war' plugin and keep JSPs in src/main/webapp -->

# ── application.yml: ──────────────────────────────────────────────────
spring:
  mvc:
    view:
      prefix: /WEB-INF/views/
      suffix: .jsp

# Development only — recompile edited JSPs without restarting:
server:
  servlet:
    jsp:
      init-parameters:
        development: true

# ── File layout: ──────────────────────────────────────────────────────
# src/main/
# ├── java/
# │   └── com/example/
# │       ├── MyApplication.java
# │       └── ServletInitializer.java   ← needed for external Tomcat only
# ├── resources/
# │   └── static/
# │       └── css/main.css              ← served at /css/main.css
# └── webapp/
#     └── WEB-INF/
#         ├── tags/
#         │   └── layout.tag            ← reusable page layout (tag file)
#         └── views/
#             ├── common/
#             │   └── header.jspf       ← included fragment
#             └── users/
#                 ├── list.jsp
#                 └── form.jsp

// ── Main application class (unchanged): ──────────────────────────────
@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

// ── ServletInitializer — needed when deploying to an external Tomcat: ─
public class ServletInitializer extends SpringBootServletInitializer {

    @Override
    protected SpringApplicationBuilder configure(
            SpringApplicationBuilder application) {
        return application.sources(MyApplication.class);
    }
}

// ── Optional explicit resolver (normally auto-configured from application.yml).
//    Note the bean name: "viewResolver" would disable Boot's own resolver. ──
@Configuration
public class MvcConfig {

    @Bean
    public ViewResolver jspViewResolver() {
        InternalResourceViewResolver resolver = new InternalResourceViewResolver();
        resolver.setViewClass(JstlView.class);   // already the default when JSTL is present
        resolver.setPrefix("/WEB-INF/views/");
        resolver.setSuffix(".jsp");
        return resolver;
    }
}

# Build the WAR
mvn clean package

# Run it standalone (embedded Tomcat; JSPs work because it is a WAR)
java -jar target/myapp.war

# Or deploy to an external Tomcat. Spring Boot 3 needs Tomcat 10.1 or later (Jakarta EE 10).
cp target/myapp.war $CATALINA_HOME/webapps/
# Served at http://localhost:8080/myapp/   (context path = WAR file name)
# Name the file ROOT.war to serve from "/"

@Controller
@RequestMapping("/users")
public class UserPageController {

    private final UserService userService;

    public UserPageController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping
    public String list(Model model) {
        model.addAttribute("pageTitle", "All Users");
        model.addAttribute("users", userService.findAll());
        return "users/list";   // -> /WEB-INF/views/users/list.jsp
    }
}

<%-- src/main/webapp/WEB-INF/views/users/list.jsp --%>
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ taglib prefix="c"   uri="jakarta.tags.core" %>
<%@ taglib prefix="fmt" uri="jakarta.tags.fmt" %>
<%@ taglib prefix="fn"  uri="jakarta.tags.functions" %>
<!DOCTYPE html>
<html>
<head>
    <title>Users</title>
    <%-- Files in src/main/resources/static are served from the root path: --%>
    <link rel="stylesheet" href="<c:url value='/css/main.css'/>">
</head>
<body>

<%-- One-time message set with a redirect flash attribute: --%>
<c:if test="${not empty message}">
    <p class="notice"><c:out value="${message}" /></p>
</c:if>

<%-- c:out — prints a value and HTML-escapes it (protects against XSS): --%>
<h1><c:out value="${pageTitle}" /></h1>

<%-- c:if — conditional rendering: --%>
<c:if test="${empty users}">
    <p>No users found.</p>
</c:if>

<%-- c:forEach — iterate over a collection: --%>
<c:if test="${not empty users}">
<table>
    <tr>
        <th>Name</th><th>Email</th><th>Role</th><th>Created</th><th>Actions</th>
    </tr>
    <c:forEach items="${users}" var="user" varStatus="status">
    <tr class="${status.index % 2 == 0 ? 'even' : 'odd'}">
        <td><c:out value="${user.name}" /></td>
        <td><c:out value="${user.email}" /></td>
        <td>
            <%-- c:choose / c:when / c:otherwise — multi-branch logic: --%>
            <c:choose>
                <c:when test="${user.role == 'ADMIN'}"><span class="badge-red">Admin</span></c:when>
                <c:when test="${user.role == 'USER'}"><span class="badge-blue">User</span></c:when>
                <c:otherwise><span class="badge-gray">Unknown</span></c:otherwise>
            </c:choose>
        </td>
        <td>
            <%-- fmt:formatDate — formats java.util.Date only: --%>
            <fmt:formatDate value="${user.createdAt}" pattern="dd MMM yyyy" />
        </td>
        <td>
            <a href="<c:url value='/users/${user.id}'/>">View</a>
            <a href="<c:url value='/users/${user.id}/edit'/>">Edit</a>
        </td>
    </tr>
    </c:forEach>
</table>
</c:if>

<%-- c:url — build URLs (handles the context path): --%>
<a href="<c:url value='/users/new'/>">Add User</a>
<img src="<c:url value='/images/logo.png'/>" alt="Logo" />

<%-- fn: — JSTL functions: --%>
<p>Total: ${fn:length(users)} users</p>

</body>
</html>

<%-- src/main/webapp/WEB-INF/views/common/header.jspf --%>
<%@ taglib prefix="c" uri="jakarta.tags.core" %>
<header>
    <a href="<c:url value='/'/>">Home</a> | <a href="<c:url value='/users'/>">Users</a>
</header>

<%-- src/main/webapp/WEB-INF/tags/layout.tag — a reusable page layout --%>
<%@ tag description="Common page layout" pageEncoding="UTF-8" %>
<%@ attribute name="title" required="true" %>
<%@ taglib prefix="c" uri="jakarta.tags.core" %>
<!DOCTYPE html>
<html>
<head>
    <title><c:out value="${title}" /></title>
    <link rel="stylesheet" href="<c:url value='/css/main.css'/>">
</head>
<body>
    <%@ include file="/WEB-INF/views/common/header.jspf" %>
    <main>
        <jsp:doBody />
    </main>
</body>
</html>

<%-- A page that uses the layout (src/main/webapp/WEB-INF/views/users/about.jsp) --%>
<%@ taglib prefix="t" tagdir="/WEB-INF/tags" %>
<t:layout title="About">
    <h1>About this application</h1>
    <p>Content of the page goes here.</p>
</t:layout>

// ── Form object: a JavaBean (not a record) ───────────────────────────
@Getter @Setter   // Lombok, or write plain getters and setters
public class UserForm {

    @NotBlank @Size(max = 100)
    private String name;

    @NotBlank @Email
    private String email;

    @NotNull
    private Role role;

    private boolean active = true;
}

// ── Controller ────────────────────────────────────────────────────────
@Controller
@RequestMapping("/users")
public class UserFormController {

    private final UserService userService;

    public UserFormController(UserService userService) {
        this.userService = userService;
    }

    // Runs before every handler in this controller, including after a failed POST
    @ModelAttribute("roles")
    public Role[] roles() {
        return Role.values();
    }

    @GetMapping("/new")
    public String newForm(Model model) {
        model.addAttribute("userForm", new UserForm());   // required by modelAttribute="userForm"
        return "users/form";
    }

    @PostMapping
    public String create(@Valid @ModelAttribute("userForm") UserForm form,
                         BindingResult result,            // must directly follow the form object
                         RedirectAttributes redirect) {
        if (result.hasErrors()) {
            return "users/form";                          // redisplay with the errors
        }
        userService.create(form);
        redirect.addFlashAttribute("message", "User created");
        return "redirect:/users";                         // post/redirect/get
    }
}

<%-- src/main/webapp/WEB-INF/views/users/form.jsp --%>
<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ taglib prefix="form" uri="http://www.springframework.org/tags/form" %>
<%@ taglib prefix="c"    uri="jakarta.tags.core" %>

<%-- servletRelativeAction adds the context path to the action: --%>
<form:form method="post" servletRelativeAction="/users" modelAttribute="userForm">

    <div>
        <label for="name">Name</label>
        <%-- form:input — pre-populates value from the model object: --%>
        <form:input path="name" id="name" cssClass="form-control"
                    cssErrorClass="form-control is-invalid" />
        <%-- form:errors — displays validation errors for the field: --%>
        <form:errors path="name" cssClass="invalid-feedback" element="div" />
    </div>

    <div>
        <label for="email">Email</label>
        <form:input path="email" type="email" id="email" />
        <form:errors path="email" cssClass="error" element="span" />
    </div>

    <div>
        <label for="role">Role</label>
        <%-- form:select — renders <select> bound to the enum field: --%>
        <form:select path="role" id="role">
            <form:option value="">-- Select --</form:option>
            <form:options items="${roles}" />
        </form:select>
        <form:errors path="role" element="span" />
    </div>

    <div>
        <label>
            <%-- form:checkbox — binds to the boolean field: --%>
            <form:checkbox path="active" /> Active
        </label>
    </div>

    <%-- All errors (field and global) in one place: --%>
    <form:errors path="*" element="div" cssClass="alert alert-danger" />

    <button type="submit">Save</button>
    <a href="<c:url value='/users'/>">Cancel</a>

</form:form>

@WebMvcTest(UserPageController.class)
class UserPageControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockitoBean   // use @MockBean on Spring Boot versions before 3.4
    private UserService userService;

    @Test
    void listReturnsUsersView() throws Exception {
        mockMvc.perform(get("/users"))
            .andExpect(status().isOk())
            .andExpect(view().name("users/list"))
            .andExpect(forwardedUrl("/WEB-INF/views/users/list.jsp"))
            .andExpect(model().attributeExists("users"));
    }
}

@WebMvcTest(UserFormController.class)
class UserFormControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockitoBean
    private UserService userService;

    @Test
    void invalidFormIsShownAgainWithErrors() throws Exception {
        mockMvc.perform(post("/users")
                .param("name", "")           // blank
                .param("email", "not-an-email"))
            .andExpect(status().isOk())
            .andExpect(view().name("users/form"))
            .andExpect(model().attributeHasFieldErrors("userForm", "name", "email", "role"));
    }
}