As most examples are written in Java, we will also need an Integrated Development Environment (IDE) and a good framework to help us write simple web applications (as the OAuth 2.0 protocol was designed for HTTP usage), which will be Spring. To simplify the usage of Spring related technologies, this recipe will help you prepare an application using Spring Boot, providing an example endpoint and how to run this project using Maven.
As I previously mentioned, we will run most of the recipes using the Spring Boot Framework which eases the development of applications based on the Spring Framework. So to run this recipe, you just need an environment where you can download some files from the internet, Java 8 properly configured on your machine, and the CURL
tool.
Note
CURL
is a tool which allows you to run HTTP requests through the command line. It is available by default in Linux and Mac OS environments, so if you are running the recipes on Windows you should install it first. This tool can be downloaded fromhttps://curl.haxx.se/download.htmland to install it, you just have to unpack it and add the path for binaries to the PATH environment variable of Windows.
The following steps describe how to prepare the environment and show how to generate a simple project from the Spring Initializr website which will be executed using the appropriate Maven commands:
- Generate a project using Spring Initializr service by visiting https://start.spring.io/. Spring Initializr provides lots of options to start setting up your project, such as if you want to use Maven or Gradle to manage your project dependencies, which version of Spring Boot to use, which dependencies to use, and even changing the language from Java to Groovy or Kotlin.
- For this simple test, just use the default values for the project manager,
Maven Project
, withJava
language and version1.5.7
of the Spring Boot. - At
Project Metadata
, change the value of the fieldGroup
tocom.packt.example
. - Still on
Project Metadata
, change the name of theArtifact
tosimplemvc
. - In the
Dependencies
section, typeweb
and selectFull-stack web development with Tomcat and Spring MVC
. After selecting the right choice, you will see the tagWeb
underneathSelected Dependencies
as follows:
- After setting up all the requirements for this simple example, click on the
Generate Project
button and your browser will start downloading the ZIP file into yourDownloads
folder. - After downloading this file, you can unzip it and import it to your IDE just to explore the structure of the created project. For Eclipse users, just import the project as a Maven project.
- Open the class
SimplemvcApplication
and you would see the following code in your IDE:
@SpringBootApplication public class SimplemvcApplication { public static void main(String[] args) { SpringApplication.run(SimplemvcApplication.class, args); } }
- Let's turn the class
SimplemvcApplication
into a controller by adding the annotation@Controller
as presented in the following code:
@Controller @SpringBootApplication public class SimplemvcApplication { public static void main(String[] args) { SpringApplication.run(SimplemvcApplication.class, args); } }
- Now that our class is declared as a controller, we can define an endpoint so we can see if the project is running properly. Add the method
getMessage
as follows, within the classSimplemvcApplication
:
@GetMapping("/message") public ResponseEntity<String> getMessage() { return ResponseEntity.ok("Hello!"); }
- If you want to run your project inside the Eclipse IDE, you should just run the class
SimplemvcApplication
as a Java application by right-clicking at the class and selecting the menu optionRun As |
Java Application.
- After the application is started you should see something like the following message at the end of the output presented in your console:
Started SimplemvcApplication in 13.558 seconds (JVM running for 14.011)
- Execute the following command to know if your application works properly (just check if the output prints
Hello
):
curl "http://localhost:8080/message"
- If you would like to use the command line you can also start your application by running the following Maven command (to run the application with Maven through the command line, you must install Maven, as explained in the next sections):
mvn spring-boot:run
- If you don't have Maven installed on your machine, the first thing to do is to start downloading the latest version from https://maven.apache.org/download.cgi which at the time of this writing was
apache-maven-3.5.0-bin.tar.gz
. - After the file has downloaded, just unpack it into any folder you want and start running Maven commands.
- Copy the full path of the Maven directory, which was created when you unpacked the downloaded file from the Maven website. If you are running macOS or Linux, run
pwd
at the command line to discover the full path. - After that, you must add the path for Maven's directory to the
PATH
environment variable. If you are using Linux or macOS, create the variableMVN_HOME
within the.bash_profile
file and append the content ofMVN_HOME
to the end of thePATH
environment variable, as presented in the following code:
MVN_HOME=/Users/{your_user_name}/maven-3.5.0 export PATH=$PATH:$MVN_HOME/bin
Note
The file.bash_profile
should be found at the user's directory. So, to edit this file, you should open the file/Users/{your_user_name}/.bash_profile
, or in a shorter way, by using~/.bash_profile
.If you are using Windows, all the environment variables can be edited through the visual interface.
- After editing this file, run the command
source ~/.bash_profile
to reload all the contents. - To check if Maven is perfectly running on your environment, run the following command:
mvn --version.
- The OAuth 2.0 specification is available as RFC 6749 at https://tools.ietf.org/html/rfc6749
- You can read more about Spring Boot at https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/
Because of the usage of Spring Boot we can take advantage of projects like Spring MVC and Spring Security. These Spring projects help us to write web applications, REST APIs, and help us to secure our applications. By using the Spring Security OAuth2 project, for example, we can configure our own OAuth 2.0 Providers in addition, to act like clients. This is important because someone trying to write his own OAuth Provider will have to deal with too many details which could easily lead to an insecure OAuth Provider. Spring Security OAuth2 already addresses the main concerns any developer would have to think about.
In addition, Spring Boot eases the initial steps for the bootstrap of the application. When creating a Spring project without Spring Boot we need to deal with dependencies manually by taking care of possible library conflicts. To solve this problem, Spring Boot has some pre-configured modules provided by starters. As an example of a useful starter, let's consider an application with Spring Data JPA. Instead of declaring all the dependencies for hibernate
, entity-manager
, and transaction-api
, just by declaring spring-boot-starter-data-jpa
all the dependencies will be imported automatically.
While starting using Spring Boot, things can still become easier by using the Spring Initializr service provided by Pivotal (the Spring maintainer now).
All the examples presented in Java can be imported and executed on any Java IDE, but we will use Eclipse just because it is a large, accepted tool among developers around the world. Although this book presents recipes using Eclipse, you can also stick with your preferred tool if you want.
Nowadays, many projects have been designed using Gradle, but many developers are still used to creating their projects using Maven to manage dependencies and the project itself. So, to avoid trick bugs with IDE plugins or any other kind of issue, the recipes using Spring Boot will be managed by Maven. In addition, Eclipse IDE already comes with a Maven plugin which at the time of writing this book was not true for Gradle. To run projects with Gradle in Eclipse, you must install a specific plugin.
Spring Boot provides a lot of starters to help you develop applications using a plethora of tools and libraries. If you want to search for more just go to http://docs.spring.io/spring-boot/docs/1.5.7.RELEASE/reference/htmlsingle/#using-boot-starter.