Welcome to the first part of my Spring Boot tutorial, where I will cover the very basics of Spring and Spring Boot. In this part we will talk briefly about the pros and cons of Spring and how Spring Boot fits into the picture. After the theoretical part, we will create our very first Spring Boot application and import it as a project into Visual Studio Code. With a Java IDE setup, we will build our application with Maven, run it and test it. To wrap things up, we will write some code to create an http endpoint and call the endpoint via http. This tutorial should take about an hour to work through and I highly recommend to code along with the examples to get the most out of it.

What is the Spring Framework?

The Spring Framework is an open-source framework for the Java programming language that provides a programming and configuration model for building modern, scalable, and modular applications. The framework was first released in 2004 and has since become the most popular frameworks for enterprise application development in Java.

The Spring Framework is very modular and provides a wide range of libraries that can be used individually or together.

These are some of the popular modules within the Spring Framework:

• Spring Core: Inversion of Control (IoC) and Dependency Injection (DI) for managing object dependencies and creating loosely coupled applications.
• Spring Web: A MVC (Model-View-Controller) framework for building web applications that separates the presentation layer, business logic, and data access layer.
• Spring Batch: A high-performance API to build Java based batch applications.
• Spring Data: A programming framework to access relational and non-relational database systems
• Spring Security: A highly adaptable framework to secure your application and integrate existing authentication and authorisation infrastructure.
• Furthermore, there are plenty of modules that simplify cloud based development of your application by centralising application configuration, authentication and authorization and much more.

While the Spring Framework is quite a great framework and makes a lot of things quite easy, there are also some points that are criticized about the Spring Framework:

• Configuration Overhead: The framework relies heavily on annotation and (in older versions) XML-based configurations, which can become difficult to manage and maintain as the application grows.
• Runtime Performance: The framework’s heavy use of reflection can impact runtime performance, particularly in large and complex applications.
• Heavy on Dependencies: The framework has many dependencies, which can increase the size of the application and can make the development process slow and cause problems running Spring based applications in containerized environments like Docker and Kubernetes.
• Versioning Issues: The Spring Framework has a complex versioning scheme and frequent releases, which can make it challenging to keep up with the latest updates and ensure compatibility with all required libraries and frameworks.

Spring vs. Spring Boot

To address some of the disadvantages mentioned in the last section, the folks at Pivotal had the idea to create the Spring Boot project as a simple way to bootstrap a Spring application. For this, Spring Boot will create dynamic templates depending on the required modules of your application. The idea is that you simply specify the requirements for your application, e.g. what kind of database to use, what kind if interfaces required to external systems or what kind of monitoring you want, and Spring Boot will create the source code and all configuration required for a working application. From there, you only need to write the business logic and specify the interfaces to get a production ready Spring application.

This takes care of the often criticized configuration overhead and will automatically sort out any dependencies you will need for the modules you have chosen. Furthermore, Spring Boot will only need a single version number and will deduce all module version numbers automatically for you. That means that you will always have compatible module versions in your application and not have to deal with finding matching module versions yourself anymore.

A Spring Boot application will also come with a pre-configured Maven or Gradle build script that can easily be integrated in any continuous integration system like Jenkins, Travis or Bamboo. The result of the build script will be a standalone executable jar-File that won’t need any other dependencies apart from a simple Java runtime environment installed on the system you want to run it on.

All these feature of Spring Boot lead to a much nicer developer experience compared to the often frustrating experience in the days before Spring Boot. You simply specify what you need and get a working application in return. I think Spring Boot also contributed a lot to the popularity of the Spring framework today compared to Oracle’s Java EE or Jakarta EE. Although the Jakarta EE world tried to catch up with the Quarkus or Micronaut frameworks, which try to give EE developers a similar developer experience, Spring Boot still offers a lot more modules for almost all uses cases and adds new modules very frequently while the Jakarta EE world moves quite slowly with very little progress in the last couple of years.

Creating a new Spring Boot Project

Let’s start the practical part of this tutorial by creating a brand new Spring Boot application.

There is a very neat official website at https://start.spring.io called the Spring Initializr that provides a UI to specify your application’s needs and gives you the zipped source code in return.

On the right-hand side of the page, you can choose which build tool to use for the included build script: Either Maven or Gradle (in either Kotlin or Groovy flavour).

You can also choose in which programming language the basic configuration should be coded in: Java, Kotlin or Groovy. Since all three languages run on a regular JVM (Java Virtual Machine), you still can switch the language you want to code in later.

Next, you can choose which Spring Boot version to use in your project. There is a always an option for the latest development version, the latest released version and an older snapshot and released version. Remember that this will be the only Spring related version you will need to pick. All versions of dependent Spring modules will be based on compatibility to this version. If you want an older Spring Boot version, you can still change this later to any version you want.

The next section lets you specify some metadata for your application. If you are familiar with Maven you will recognize these properties. If not, here is a quick rundown what they mean:

• Group: A general category for your application. This could be your companies name, the name of your git organization or a product name if the product has several submodules.
• Artifact: The logical name of your application. This should give some information about what it does. Group and Artifact together should result in a unique name. Both parameters cannot include any whitespace.
• Name: This should be the name of your application in a readable form. Here you can also use whitespace.
• Description: Fill this if you have anything more to say about your application. Keep it short though.
• Package name: This will be the base package all source code will be created in. You can still later create more packages if you like.

The last two remaining parameters are how to package your application when the build script is run and the Java version. Always use jar for packaging here. If your boss still wants you to release your application in war format, it is time to look for another job.

The Java version you want to use is up to you, only keep in mind that Spring Boot version 3.0 and later requires Java 17+ as a baseline. If you want to use Spring Boot 2.7 or earlier versions, these still run with pretty much any ancient Java version from Java 8 and later.

On the right handside you can now click the Add Dependencies button to add any Spring modules you want to use in your application.

This will open up a huge list of modules you can add to your application. Most commonly used is the Spring Web module, which is used to create HTTP endpoints. For this example let’s pick the Spring Web module. You can actually search in the Dependencies text field to get to the modules you want faster.

To generate the application from the setting you simply click the Generate button in the bottom of the screen (or press control + enter), which will generate and download our application.

Suggested IDE

The next step to build your application would be to customize it to your needs and actually run and test it. To do so, I highly recommend to use a Java IDE. For the rest of this tutorial, I am going to use Microsoft Visual Studio Code as my IDE. VS Code is a powerful and free IDE that greatly increases your productivity.

There are other good IDEs out there worth mentioning like IntelliJ or Eclipse, but from the free ones I personally like VS Code the most. Which one you want to use is of course up to you. All of them will do the job.

You can download VS Code for different operating systems (Windows, Linux,Mac) here: https://code.visualstudio.com/Download

After you downloaded and installed the IDE, there are two useful addons available to install to get started with developing Spring application in Java. The first one is the general Java extension pack, which includes a debugger, the language support in the editor, a test runner and several other helpful tools. You can find a link for the download here. The second one is the extension pack for Spring Boot which includes several useful tools to start and stop Spring applications and access to the Spring Initializer from the IDE.

To open our Spring Boot project after installing these two extensions, unzip the download you got earlier from the Spring Initializr into any folder on your local development machine. The download is a simple zip that can be extracted by any zip utility.

Next, open your VS code installation and click on the File menu and click the option Open Folder …

Navigate to the folder you just extracted from the download and select it. This will open the newly created Spring Boot application in VS Code.

Anatomy of a Spring Boot Project

Next, we will have a closer look on the files in our new project that we extracted and imported into VS Code.

After you opened the folder you should see something similar to the following files and folders:

There is a single Java file DemoApplication.java in the folder src/main/java in the package com.example.demo. This is the package that we picked earlier when created the project and it is used to start our application. There is also a corresponding test called DemoApplicationTest.java to test our application in the folder src/test/java under the package com.example.demo.

There is a file called application.properties in the folder src/main/resources that will contain additional configuration settings if we required any. For now we don’t so the file is empty.

In the root of the folder there is a file called pom.xml. This is a Maven build file and contains all information about the required dependencies of the application and how to build it, but will will get into this in more detail later. Together with this file there were also a folder called .mvn and two files called mvnw and mvnw.cmd created . All these are required to build your project with Mavon. The contents don’t matter much and you will most likely never need to change these.

Finally, there is a file called .gitignore which contains some useful meta information if you later want to store your code in a git repository and a file called HELP.md. with some useful links to the Spring and Maven documentation and to get started with the technologies you picked when you created the project.

A short Introduction to Maven

As mentioned in the last section, Maven is used as the build technology in our new project and we have already seen a couple of Maven related files in it. Let me explain some Maven basics to understand what these files do and how you can use them.

The most important Maven related file for a developer is the pom.xml in the root of your project. This file specifies everything Maven needs to know to build your project. Maven is not only used in combination with Spring Boot but also to build other Java and even none Java projects. To make our application a Spring Boot project, Maven requires some configuration, which needs to be imported into the pom.file. This is done by the parent tag in the beginning of the file:

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.0.2</version>
  <relativePath/>
</parent>

The groupId and artifactId make it a Spring Boot project and the version tag specifies which Spring Boot version to use. If you later want to change the Spring Boot version, just change it here.

Next in our pom file, there are some tags that describe the metadata of our project. These don’t do much to the project but define a unique name and version and how the output files are called when we later run the script to build our application.

<groupId>com.example</groupId>
<artifactId>demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>demo</name>
<description>Demo project for Spring Boot</description>

Which Java version to use for the project is specified in a property tag. For this demo I picked Java 19 but you can change it here later if you need to.

<properties>
  <java.version>19</java.version>
</properties>

The next section in the pom.xml lists the modules we picked when we created the application in the Spring Initializer. These were the Spring Web (spring-boot-starter-web) and Spring Actuator (spring-boot-starter-actuator) modules. There is a additional dependency for testing (spring-boot-starter-test) automatically included in our application, because you wanted to have that one anyways, right?

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

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

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

Finally, there is a the Spring Boot Maven plugin specified in the end of the pom.xml. This plugin will to all the magic to assemble the application into a single executable jar file we run the build script.

<build>
  <plugins>
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
    </plugin>
  </plugins>
</build>

If you want to start the build of your application, just open a terminal in VS Code (go to Terminal -> New Terminal) and type the following Maven command:

mvn package

This will start a build of your application, which will result in an executable jar file and a lot of output in the console. After the build, you will have a new folder in your project called target. If you expand this folder, you can find a file called demo-0.0.1-SNAPSHOT.jar in there, which is the result of your build. The name is derived by the metadata you specified earlier, so if you used a different name in the pom.xml, the file will be called differently. Ignore the other files in the target folder for now, since these not important for you yet.

How to Start a Spring Boot Application

Now that we have a first version of our application, there are three ways to start it:

1. Start it from the Java main method
2. Start the executable jar file
3. Build and start it with Maven

The easiest way to start it, is to start the main method of the DemoApplication.java file in your IDE. This is the only Java class in your project that has the @SpringBootApplication annotation on the class level. If you are presented with a more complex project by someone, just look for a class with that annotation and you can start the app.

In VS Code you just open the file and click the run button in the upper right corner of the window:

This will start the Spring Boot application with lots of output in the console:

This is an easy way to start and test your application locally with the latest changes in your project included.

Of course you can also start the resulting jar file from your Maven build earlier. For this, just open another terminal and navigate into the target folder. From the target folder, you can start the executable jar file with the java command:

 java -jar .\demo-0.0.1-SNAPSHOT.jar

This will start the last application from the jar file and not from your local sources. If you changed files after the last Maven build, these changes will not be included.

Finally, you can also start a Maven build and execute the resulting jar file in one step with a Maven command. This is another very handy feature of the Spring Boot Maven plugin. By this, the latest changes in your project will be included in the jar file.

mvn spring-boot:run

There is one last option to start your application indirectly by executing the default unit test against it. Since the Spring Initializer created us a default test when we created it, we can start that one. The default test is not a simple unit test, but an integration test which starts the application and runs the test code against it. Since this is the default test case, there is no actual test code to run, but it will start the application and shut it down anyways. If this startup of your application fails by any reason, the test will fail as well although there is no actual test code in it.

To start the test, open the default test file DemoApplicationTest.java and click the play button:

Not much to see after you clicked the button, but after a couple of seconds the test will (hopefully) have executed successfully:

Creating an HTTP Endpoint

Now that we know what files are inside our project, how to build, start and test it, it is time to write some Java code for our business logic. Let’s assume we have a great collection of books at home and want to give other applications the means to query a list of them.

To tell Spring Boot that you want an http endpoint that returns data, you have to create a new Java class and annotate it with @RestController annotation on the class level.

Next, you will also need a callback method that is called when the URL of the http endpoint is called. This is done by annotating a method with the @GetMapping annotation. Finally, to specify the URL of the endpoint you need to put the @RequestMapping annotation on the method and specify the URL as a String parameter.

Here is an example of the BookEndpoint.java file. Remember that file must be in the same package that we specified earlier during project creation or any subpackage of it.

package com.example.demo;

import java.util.List;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class BookEndpoint {

    @GetMapping
    @RequestMapping("/books")
    public List<Book> getBooks(){
        return List.of(new Book("The Lord of The Rings","J.R.R. Tolkien"),
            new Book("The Lord of Flies","William Golding"),
            new Book("1984","George Orwell"));
    }
    
}

record Book (String name, String author){}

I created a simple Book record class in the bottom of the endpoint file to return it in the callback method. Of course you can put that record in a separate file if you want.

This is all you have to do to define the endpoint. If you start your application again locally, the endpoint will be automatically started as well. Once the application is up, you can hit your endpoint at the following URL:

http://localhost:8080/books

The first part of the URL (http://localhost:8080) is specified by the Spring Boot default configuration. The second part /books by our @RequestMapping annotation.

If you hit this URL in a browser, you will get the list of my three books back in JSON format:

[
  {"name":"The Lord of The Rings","author":"J.R.R. Tolkien"},
  {"name":"The Lord of Flies","author":"William Golding"},
  {"name":"1984","author":"George Orwell"}
]

Wrap up

This is pretty much all you need to know about Spring and Spring Boot to get started. We discussed what Spring and Spring Boot is all about, how to create a new Spring Boot project, how to start stop and test the new project and finally how to write and configure an http endpoint to return my lovely book collection.

In the next part of this tutorial, we will write code to test our newly created endpoint and secure the endpoint with the Spring Security module. After that it is time to create some more methods in the endpoint class to add, search and delete books.

If you want to look into the source code of this example, you can find it in this github repository, but I strongly recommend that you go over these steps by yourself and create your own application. If you liked this first part of the tutorial just star the repo or drop me a mail through the contact form.