Setting up a basic Spring Boot web application with Maven

In this tutorial I am going to show you, how to set up a basic web application using Spring Boot and Maven. The web application will have a single “home” page, rendered using a spring controller and a jsp file.

spring-by-pivotal

Technologies used in this tutorial:

  • Apache Tomcat 8.0.35
  • Apache Maven 3.3.9
  • Java 1.8.0_60

The structure of the project

Here you can see the file structure of the completed project:

structure-jtuts-2016-05-20-boot

Setting up the POM file

A basic Spring Boot web application requires very little configuration in the POM. We only have to include one dependency (apart from the servlet api needed for using jsp views). This is the spring-boot-starter-web, that transitively contains all other dependencies that are required for the spring controllers, logging etc.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>jtuts</groupId>
    <artifactId>jtuts-2016-05-20-setting-up-basic-spring-boot-web-app-with-maven</artifactId>
    <version>1.0</version>
    <packaging>war</packaging>
    <name>Setting up a basic Spring Boot web application with Maven</name>

    <properties>

        <!-- Dependency versions -->

        <spring.boot.version>1.3.5.RELEASE</spring.boot.version>
        <servlet.api.version>3.1.0</servlet.api.version>

        <!-- Plugin versions -->

        <maven.compiler.plugin.version>3.5.1</maven.compiler.plugin.version>

        <!-- Misc versions -->

        <java.version>1.8</java.version>

    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>${spring.boot.version}</version>
        </dependency>

        <!-- Provided dependencies -->
        
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>${servlet.api.version}</version>
            <scope>provided</scope>
        </dependency>

    </dependencies>



    <build>
        <finalName>boot-web-app</finalName>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>${maven.compiler.plugin.version}</version>
                <configuration>
                    <source>${java.version}</source>
                    <target>${java.version}</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <configuration>
                    <failOnMissingWebXml>false</failOnMissingWebXml>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

In the plugin configuration there is nothing Boot specific. We just set the Java version using the maven-compiler-plugin and also set the failOnMissingWebXml to false, because we deliberately don’t have a web.xml file.

The application runner class

A spring boot application can be initialized by a very simple class containing a main method.

package com.jtuts.config;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.web.SpringBootServletInitializer;
import org.springframework.context.annotation.ComponentScan;

@SpringBootApplication
@ComponentScan(basePackages = "com.jtuts")
public class Application extends SpringBootServletInitializer {

    public static void main(final String[] args) {
        SpringApplication.run(Application.class, args);
    }

}

Note, that we have the @SpringBootApplication annotation, which is actually is a shorthand for the following ones:

  • @Configuration marks the class as a source of bean definitions for the application context.
  • @EnableAutoConfiguration tells Spring Boot to start adding beans based on classpath settings, other beans, and various property settings.
  • @EnableWebMvc is automatically added when Boot sees spring-webmvc on the classpath. This flags the application as a web application and activates key behaviors such as setting up a DispatcherServlet.
  • @ComponentScan tells Spring to look for other components, configurations.

The  @Component annotation is automatically added, but by default it only looks for components in the current package, so we needed to override it, to look for components in the parent package. This way, it’ll see our controller also.

Extending the SpringBootServletInitializer is required to be able to deploy the application as a war file to a container (e.g. Tomcat). It is actually an implementation of the WebApplicationInitializer interface, that you would use when you want to create a web application without Boot.

That’s it for the application startup.

Creating the controller

Our controller is plain and simple, just returns a view without passing any parameters.

package com.jtuts.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.servlet.ModelAndView;

@Controller
public class HomeController {

    private static final String HOME = "home";

    @RequestMapping(value = HOME)
    public ModelAndView home() {
        return new ModelAndView(HOME);
    }
}

For this controller to work, we also have to specify a view resolver in a configuration class, that tells Spring where to find the view files based on their names.

package com.jtuts.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.ViewResolver;
import org.springframework.web.servlet.view.InternalResourceViewResolver;

@Configuration
public class ViewConfiguration {

    private static final String VIEW_PATH = "/WEB-INF/views/";
    private static final String JSP_EXTENSION = ".jsp";

    @Bean
    public ViewResolver setupViewResolver() {
        InternalResourceViewResolver resolver = new InternalResourceViewResolver();

        resolver.setPrefix(VIEW_PATH);
        resolver.setSuffix(JSP_EXTENSION);

        return resolver;
    }

}

Our view file

The view file is just a really simple one:

<%@ page language="java" contentType="text/html; charset=UTF-8" %>
<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>Home page</title>
</head>
<body>
    <h1>Welcome to the home page.</h1>
</body>
</html>

How to launch the app

To launch this application, you just have to copy the war file created during build to a Tomcat container.

Additional notes

As you can see, a logback.xml is also included. This is because Spring Boot by default expects the logback configuration and the app would fail to start without that. The exact logging configuration is not really relevant to this tutorial, but anyway, here is the content of that file:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <include resource="org/springframework/boot/logging/logback/base.xml"/>
    <logger name="org.springframework.web" level="DEBUG"/>
</configuration>

Download

You can download the working example project here.