Creating a Project with Spring Initializr
In this screencast, we're going to create a simple Spring Boot hello-world application, which will display some text locally in our browser.
First let's create our project. I'm going to use IntelliJ IDEA, ultimate version 2021.1. For this demo, I'm using IntelliJ IDEA Ultimate. Ultimate has support for Spring Initializr, which can generate a Spring Boot project structure for you. From the welcome screen, let's select new project and then Spring Initializer.
We can give our project a name such as 'hello world' and change the location if required. For this screencast, I'm going to use Maven as my build system. The language I want to use is Java, so again, I'll leave that as the default. I'll change my group to something more meaningful to me, such as 'springdemo'. The artifact and package name are generated based on the name and group, so you don't need to change these.
I'm going to use Java 11 as that's the latest long-term support release from Oracle at the time of recording. Finally, we can use a jar here. We would need to use a war if we were deploying to an application server, but we won't be doing that. Instead, we're going to rely on Spring Boot to supply it.
That's everything here. Let's click next.
Selecting Spring Boot Dependencies
This screen is where you can select your dependencies for your Spring Boot project, which Maven will manage for you because we selected that in the previous step. You can expand the nodes and browse the dependencies available from Spring Initializr here. The groupings can help you to figure out the dependencies that you want to add, initially. However, the fastest way to navigate this dialogue is by typing your search criteria directly into it.
For example, we can type 'web' because we know we're looking for a web server for our hello world application. There's quite a few options to choose from here, but let's start with Spring Web because we can see on the right-hand side that that will give us support for web content, RESTful calls, and it also comes with an Apache Tomcat server.
Lastly, the version of Spring Boot is shown in the top drop down. The latest version at the time of recording is 2.5.0, so I'm going to use that. Let's click Finish and get IntelliJ IDEA to create our Spring Boot project with that one dependency.
Exploring the Generated Project Structure
One point of note here is that it's very easy to add dependencies to the application once you've created it, so you don't need to select all the ones that you think you might need at this step. You can do that later.
Let's take a look around at our Spring Boot project that's been created for us. We can maximize the editor and hide the windows we don't need. I'm going to minimize the Maven window and the Preview window. I'll leave the Project Tool window open for now so we can take a look around the project.
Our .mvn folder contains the Maven wrapper files. Spring Boot uses the Maven wrapper rather than Maven itself. This means you don't need to download and install Maven; it is already contained within your Spring Boot project.
By typing 'pom', we can navigate to our Maven pom.xml file, which contains two dependencies. Firstly, the one we selected, spring-boot-starter-web, and secondly, one called spring-boot-starter-test. This dependency is there because Spring Boot assumes rightly that you'll want to write some tests for your application. spring-boot-starter-test includes support for common testing frameworks, such as JUnit, Mockito and Hamcrest.
At the start of this screencast, I mentioned that it's easy to add dependencies at a later date. You can do that here in your pom.xml file with Cmd+N on Mac or Alt+Ins on Windows, and then type in the dependency that you're looking for. For example, MongoDB. However, we're not going to add any more dependencies to this project, so I'll press Escape to close this dialog.
Let's look at the Java files that have been created for us in our main and test directory. This is our main application class. The first annotation tells Spring that it's a Spring Boot project. This means that Spring Boot will make a number of assumptions about the shape of your code at runtime, including the dependencies required. Line 10 is the main run method for our Spring application.
In our test directory, we have a new test class that currently just checks that it can load the Spring application context. This test is a useful starting point for your integration tests.
Running the App and Seeing the Default Error
Since we already have the basics of a Spring Boot application, let's run it and see what we get. We can do that with Ctrl+R on Mac or Shift+F10 on Windows or from the gutter icons in our main application class.
Once our application has been built and run, we can view the output and note that a Tomcat server has been started locally on port 8080. Let's open a browser and see what's available on our localhost port 8080. When we type in our URL and press enter, we get this white label error page, which is what we expect at this stage. We've used spring-boot-starter-web, which gave us support for a Spring Rest Controller, but we haven't created one yet. In addition, we'll need to add a request mapping to that controller so that the application knows what to do at the root of the directory, as in this case.
Writing a Failing Test with TDD
Instead of creating that Spring controller first, let's create a test for it.
Let's minimize our run window with Cmd+4 for Mac or Alt+4 for windows and then stop our application from running with Command+F2 on Mac or Ctrl+F2 on windows. Now, in our test directory, we can write an automated test to check for the correct response from the server. We'll call it CheckHTTPResponse.
Let's annotate our class with @SpringBootTest and pass in webEnvironment.RANDOMPORT. This means we can start a webserver with a random port number. We then need to get that port number and annotate that with @LocalServerPort. This allows our testing framework to inject this field with a random port.
The annotation @SpringBootTest that we used means that we can use the @Autowired annotation to tell Spring to get a TestRestTemplate from the context. For our test itself, annotate it with @Test. We want it to pass when our expected value is the same as our actual value from the web server. We'll write an assertEquals statement that compares the string we're going to put in our controller with the string we are serving from local hosts at this random port. We need to use the getForObject method call on our instance of the TestRestTemplate and convert that to a string to do a comparison with the string that we want to use.
Finally, we can get IntelliJ IDEA to add the import for JUnit 5 and put each of our arguments onto separate lines so that it's easier to read using Alt+Enter.
Now let's run this test using the gutter icons in the test class. We're expecting it to fail because we haven't implemented a Spring controller yet. Starting with a failing test is a great way to ensure that your code does what you expect it to do. And the test has failed as we expected.
Implementing the REST Controller to Pass the Test
Let's implement our Spring controller next so that our test passes.
Let's add a new class to our source directory called 'helloWorldController'. We need to annotate this as a @RestController, so that Spring knows what to do with it. Our method needs to be annotated with @Request, which will default the root directory, because we're not providing any arguments. It will return a string, and that string will be “Hello World from Spring Boot”, the same string that we used in our test class.
Let's navigate back to our test with Cmd+E on Mac or control+E on windows and run it again. It should pass this time because we created a Spring Controller with a request mapping containing the string that we're expecting.
Great. It's passed. Now we can move on to our next step.
Verifying the Endpoint in the Browser
Let's run our Spring application again. To run our application again, let's use Ctrl+Option+R on Mac or Alt+Shift+F10 on windows to choose our run configuration. Once our project has been built and run, we can go back to our browser and refresh the page.
Let's refresh this. Now that we have that Spring Controller and Request Mapping, we can see that our text is being correctly displayed.
Adding a Second Request Mapping
Let's make one final change and then wrap things up.
Back in our Spring Controller class, we can add an additional method, which again, we'll annotate with Request Mapping, but this time we'll pass forward slash goodbye in as a parameter for the request. Our new method is also going to return a string so that we can see the change when we refresh our browser.
Let's run our application again, to see that change in action. When we type forward slash goodbye, which is what we explicitly passed into our Request Mapping, we can see our string is being returned as we expect.
Using IntelliJ IDEA's HTTP Client
Finally, IntelliJ IDEA Ultimate has a built in HTTP client, which you can use to view responses without navigating to the browser each time. Each time you can click on the small, grey globe icon to the right of the request mapping and select Open in HTTP client. Press tab to fill in the request, and then you can run the request to see the result returned, providing your application is still running.
Likewise, we can do this with our first method. This time, we'll see our 'hello world' string when we make the request.
In this screencast, we learned about creating a simple Spring Boot application with the Spring Initializr project type in IntelliJ IDEA Ultimate. We created a Spring controller with test driven development, and we looked at how you can use the HTTP client of your responses within your IDE.
Thanks for watching.
