329 lines
13 KiB
Plaintext
329 lines
13 KiB
Plaintext
[[getting-started.first-application]]
|
|
== Developing Your First Spring Boot Application
|
|
This section describes how to develop a small "`Hello World!`" web application that highlights some of Spring Boot's key features.
|
|
We use Maven to build this project, since most IDEs support it.
|
|
|
|
[TIP]
|
|
====
|
|
The https://spring.io[spring.io] web site contains many "`Getting Started`" https://spring.io/guides[guides] that use Spring Boot.
|
|
If you need to solve a specific problem, check there first.
|
|
|
|
You can shortcut the steps below by going to https://start.spring.io and choosing the "Web" starter from the dependencies searcher.
|
|
Doing so generates a new project structure so that you can <<getting-started#getting-started.first-application.code,start coding right away>>.
|
|
Check the https://github.com/spring-io/start.spring.io/blob/main/USING.adoc[start.spring.io user guide] for more details.
|
|
====
|
|
|
|
Before we begin, open a terminal and run the following commands to ensure that you have valid versions of Java and Maven installed:
|
|
|
|
[indent=0]
|
|
----
|
|
$ java -version
|
|
java version "1.8.0_102"
|
|
Java(TM) SE Runtime Environment (build 1.8.0_102-b14)
|
|
Java HotSpot(TM) 64-Bit Server VM (build 25.102-b14, mixed mode)
|
|
----
|
|
|
|
[indent=0]
|
|
----
|
|
$ mvn -v
|
|
Apache Maven 3.5.4 (1edded0938998edf8bf061f1ceb3cfdeccf443fe; 2018-06-17T14:33:14-04:00)
|
|
Maven home: /usr/local/Cellar/maven/3.3.9/libexec
|
|
Java version: 1.8.0_102, vendor: Oracle Corporation
|
|
----
|
|
|
|
NOTE: This sample needs to be created in its own directory.
|
|
Subsequent instructions assume that you have created a suitable directory and that it is your current directory.
|
|
|
|
|
|
|
|
[[getting-started.first-application.pom]]
|
|
=== Creating the POM
|
|
We need to start by creating a Maven `pom.xml` file.
|
|
The `pom.xml` is the recipe that is used to build your project.
|
|
Open your favorite text editor and add the following:
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes"]
|
|
----
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
|
|
<modelVersion>4.0.0</modelVersion>
|
|
|
|
<groupId>com.example</groupId>
|
|
<artifactId>myproject</artifactId>
|
|
<version>0.0.1-SNAPSHOT</version>
|
|
|
|
<parent>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-starter-parent</artifactId>
|
|
<version>{spring-boot-version}</version>
|
|
</parent>
|
|
|
|
<description/>
|
|
<developers>
|
|
<developer/>
|
|
</developers>
|
|
<licenses>
|
|
<license/>
|
|
</licenses>
|
|
<scm>
|
|
<url/>
|
|
</scm>
|
|
<url/>
|
|
|
|
<!-- Additional lines to be added here... -->
|
|
|
|
ifeval::["{spring-boot-artifactory-repo}" != "release"]
|
|
<!-- (you don't need this if you are using a .RELEASE version) -->
|
|
<repositories>
|
|
<repository>
|
|
<id>spring-snapshots</id>
|
|
<url>https://repo.spring.io/snapshot</url>
|
|
<snapshots><enabled>true</enabled></snapshots>
|
|
</repository>
|
|
<repository>
|
|
<id>spring-milestones</id>
|
|
<url>https://repo.spring.io/milestone</url>
|
|
</repository>
|
|
</repositories>
|
|
<pluginRepositories>
|
|
<pluginRepository>
|
|
<id>spring-snapshots</id>
|
|
<url>https://repo.spring.io/snapshot</url>
|
|
</pluginRepository>
|
|
<pluginRepository>
|
|
<id>spring-milestones</id>
|
|
<url>https://repo.spring.io/milestone</url>
|
|
</pluginRepository>
|
|
</pluginRepositories>
|
|
endif::[]
|
|
</project>
|
|
----
|
|
|
|
The preceding listing should give you a working build.
|
|
You can test it by running `mvn package` (for now, you can ignore the "`jar will be empty - no content was marked for inclusion!`" warning).
|
|
|
|
NOTE: At this point, you could import the project into an IDE (most modern Java IDEs include built-in support for Maven).
|
|
For simplicity, we continue to use a plain text editor for this example.
|
|
|
|
|
|
|
|
[[getting-started.first-application.dependencies]]
|
|
=== Adding Classpath Dependencies
|
|
Spring Boot provides a number of "`Starters`" that let you add jars to your classpath.
|
|
Our applications for smoke tests use the `spring-boot-starter-parent` in the `parent` section of the POM.
|
|
The `spring-boot-starter-parent` is a special starter that provides useful Maven defaults.
|
|
It also provides a <<using#using.build-systems.dependency-management,`dependency-management`>> section so that you can omit `version` tags for "`blessed`" dependencies.
|
|
|
|
Other "`Starters`" provide dependencies that you are likely to need when developing a specific type of application.
|
|
Since we are developing a web application, we add a `spring-boot-starter-web` dependency.
|
|
Before that, we can look at what we currently have by running the following command:
|
|
|
|
[indent=0]
|
|
----
|
|
$ mvn dependency:tree
|
|
|
|
[INFO] com.example:myproject:jar:0.0.1-SNAPSHOT
|
|
----
|
|
|
|
The `mvn dependency:tree` command prints a tree representation of your project dependencies.
|
|
You can see that `spring-boot-starter-parent` provides no dependencies by itself.
|
|
To add the necessary dependencies, edit your `pom.xml` and add the `spring-boot-starter-web` dependency immediately below the `parent` section:
|
|
|
|
[source,xml,indent=0,subs="verbatim"]
|
|
----
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-starter-web</artifactId>
|
|
</dependency>
|
|
</dependencies>
|
|
----
|
|
|
|
If you run `mvn dependency:tree` again, you see that there are now a number of additional dependencies, including the Tomcat web server and Spring Boot itself.
|
|
|
|
|
|
|
|
[[getting-started.first-application.code]]
|
|
=== Writing the Code
|
|
To finish our application, we need to create a single Java file.
|
|
By default, Maven compiles sources from `src/main/java`, so you need to create that directory structure and then add a file named `src/main/java/MyApplication.java` to contain the following code:
|
|
|
|
[source,java,indent=0,subs="verbatim"]
|
|
----
|
|
include::{docs-java}/gettingstarted/firstapplication/code/MyApplication.java[]
|
|
----
|
|
|
|
Although there is not much code here, quite a lot is going on.
|
|
We step through the important parts in the next few sections.
|
|
|
|
|
|
|
|
[[getting-started.first-application.code.mvc-annotations]]
|
|
==== The @RestController and @RequestMapping Annotations
|
|
The first annotation on our `Example` class is `@RestController`.
|
|
This is known as a _stereotype_ annotation.
|
|
It provides hints for people reading the code and for Spring that the class plays a specific role.
|
|
In this case, our class is a web `@Controller`, so Spring considers it when handling incoming web requests.
|
|
|
|
The `@RequestMapping` annotation provides "`routing`" information.
|
|
It tells Spring that any HTTP request with the `/` path should be mapped to the `home` method.
|
|
The `@RestController` annotation tells Spring to render the resulting string directly back to the caller.
|
|
|
|
TIP: The `@RestController` and `@RequestMapping` annotations are Spring MVC annotations (they are not specific to Spring Boot).
|
|
See the {spring-framework-docs}/web.html#mvc[MVC section] in the Spring Reference Documentation for more details.
|
|
|
|
|
|
|
|
[[getting-started.first-application.code.enable-auto-configuration]]
|
|
==== The @EnableAutoConfiguration Annotation
|
|
The second class-level annotation is `@EnableAutoConfiguration`.
|
|
This annotation tells Spring Boot to "`guess`" how you want to configure Spring, based on the jar dependencies that you have added.
|
|
Since `spring-boot-starter-web` added Tomcat and Spring MVC, the auto-configuration assumes that you are developing a web application and sets up Spring accordingly.
|
|
|
|
.Starters and Auto-configuration
|
|
****
|
|
Auto-configuration is designed to work well with "`Starters`", but the two concepts are not directly tied.
|
|
You are free to pick and choose jar dependencies outside of the starters.
|
|
Spring Boot still does its best to auto-configure your application.
|
|
****
|
|
|
|
|
|
|
|
[[getting-started.first-application.code.main-method]]
|
|
==== The "`main`" Method
|
|
The final part of our application is the `main` method.
|
|
This is a standard method that follows the Java convention for an application entry point.
|
|
Our main method delegates to Spring Boot's `SpringApplication` class by calling `run`.
|
|
`SpringApplication` bootstraps our application, starting Spring, which, in turn, starts the auto-configured Tomcat web server.
|
|
We need to pass `Example.class` as an argument to the `run` method to tell `SpringApplication` which is the primary Spring component.
|
|
The `args` array is also passed through to expose any command-line arguments.
|
|
|
|
|
|
|
|
[[getting-started.first-application.run]]
|
|
=== Running the Example
|
|
At this point, your application should work.
|
|
Since you used the `spring-boot-starter-parent` POM, you have a useful `run` goal that you can use to start the application.
|
|
Type `mvn spring-boot:run` from the root project directory to start the application.
|
|
You should see output similar to the following:
|
|
|
|
[indent=0,subs="verbatim,attributes"]
|
|
----
|
|
$ mvn spring-boot:run
|
|
|
|
. ____ _ __ _ _
|
|
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
|
|
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
|
|
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
|
|
' |____| .__|_| |_|_| |_\__, | / / / /
|
|
=========|_|==============|___/=/_/_/_/
|
|
:: Spring Boot :: (v{spring-boot-version})
|
|
....... . . .
|
|
....... . . . (log output here)
|
|
....... . . .
|
|
........ Started MyApplication in 2.222 seconds (JVM running for 6.514)
|
|
----
|
|
|
|
If you open a web browser to `http://localhost:8080`, you should see the following output:
|
|
|
|
[indent=0]
|
|
----
|
|
Hello World!
|
|
----
|
|
|
|
To gracefully exit the application, press `ctrl-c`.
|
|
|
|
|
|
|
|
[[getting-started.first-application.executable-jar]]
|
|
=== Creating an Executable Jar
|
|
We finish our example by creating a completely self-contained executable jar file that we could run in production.
|
|
Executable jars (sometimes called "`fat jars`") are archives containing your compiled classes along with all of the jar dependencies that your code needs to run.
|
|
|
|
.Executable jars and Java
|
|
****
|
|
Java does not provide a standard way to load nested jar files (jar files that are themselves contained within a jar).
|
|
This can be problematic if you are looking to distribute a self-contained application.
|
|
|
|
To solve this problem, many developers use "`uber`" jars.
|
|
An uber jar packages all the classes from all the application's dependencies into a single archive.
|
|
The problem with this approach is that it becomes hard to see which libraries are in your application.
|
|
It can also be problematic if the same filename is used (but with different content) in multiple jars.
|
|
|
|
Spring Boot takes a <<executable-jar#executable-jar, different approach>> and lets you actually nest jars directly.
|
|
****
|
|
|
|
To create an executable jar, we need to add the `spring-boot-maven-plugin` to our `pom.xml`.
|
|
To do so, insert the following lines just below the `dependencies` section:
|
|
|
|
[source,xml,indent=0,subs="verbatim"]
|
|
----
|
|
<build>
|
|
<plugins>
|
|
<plugin>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-maven-plugin</artifactId>
|
|
</plugin>
|
|
</plugins>
|
|
</build>
|
|
----
|
|
|
|
NOTE: The `spring-boot-starter-parent` POM includes `<executions>` configuration to bind the `repackage` goal.
|
|
If you do not use the parent POM, you need to declare this configuration yourself.
|
|
See the {spring-boot-maven-plugin-docs}#getting-started[plugin documentation] for details.
|
|
|
|
Save your `pom.xml` and run `mvn package` from the command line, as follows:
|
|
|
|
[indent=0,subs="verbatim,attributes"]
|
|
----
|
|
$ mvn package
|
|
|
|
[INFO] Scanning for projects...
|
|
[INFO]
|
|
[INFO] ------------------------------------------------------------------------
|
|
[INFO] Building myproject 0.0.1-SNAPSHOT
|
|
[INFO] ------------------------------------------------------------------------
|
|
[INFO] .... ..
|
|
[INFO] --- maven-jar-plugin:2.4:jar (default-jar) @ myproject ---
|
|
[INFO] Building jar: /Users/developer/example/spring-boot-example/target/myproject-0.0.1-SNAPSHOT.jar
|
|
[INFO]
|
|
[INFO] --- spring-boot-maven-plugin:{spring-boot-version}:repackage (default) @ myproject ---
|
|
[INFO] ------------------------------------------------------------------------
|
|
[INFO] BUILD SUCCESS
|
|
[INFO] ------------------------------------------------------------------------
|
|
----
|
|
|
|
If you look in the `target` directory, you should see `myproject-0.0.1-SNAPSHOT.jar`.
|
|
The file should be around 10 MB in size.
|
|
If you want to peek inside, you can use `jar tvf`, as follows:
|
|
|
|
[indent=0]
|
|
----
|
|
$ jar tvf target/myproject-0.0.1-SNAPSHOT.jar
|
|
----
|
|
|
|
You should also see a much smaller file named `myproject-0.0.1-SNAPSHOT.jar.original` in the `target` directory.
|
|
This is the original jar file that Maven created before it was repackaged by Spring Boot.
|
|
|
|
To run that application, use the `java -jar` command, as follows:
|
|
|
|
[indent=0,subs="verbatim,attributes"]
|
|
----
|
|
$ java -jar target/myproject-0.0.1-SNAPSHOT.jar
|
|
|
|
. ____ _ __ _ _
|
|
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
|
|
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
|
|
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
|
|
' |____| .__|_| |_|_| |_\__, | / / / /
|
|
=========|_|==============|___/=/_/_/_/
|
|
:: Spring Boot :: (v{spring-boot-version})
|
|
....... . . .
|
|
....... . . . (log output here)
|
|
....... . . .
|
|
........ Started MyApplication in 2.536 seconds (JVM running for 2.864)
|
|
----
|
|
|
|
As before, to exit the application, press `ctrl-c`.
|