858 lines
30 KiB
Plaintext
858 lines
30 KiB
Plaintext
[[getting-started]]
|
|
= Getting Started
|
|
|
|
[partintro]
|
|
--
|
|
If you are getting started with Spring Boot, or "`Spring`" in general, start by reading
|
|
this section. It answers the basic "`what?`", "`how?`" and "`why?`" questions. It
|
|
includes an introduction to Spring Boot, along with installation instructions. We then
|
|
walk you through building your first Spring Boot application, discussing some core
|
|
principles as we go.
|
|
--
|
|
|
|
|
|
|
|
[[getting-started-introducing-spring-boot]]
|
|
== Introducing Spring Boot
|
|
Spring Boot makes it easy to create stand-alone, production-grade Spring-based
|
|
Applications that you can run. We take an opinionated view of the Spring platform and
|
|
third-party libraries, so that you can get started with minimum fuss. Most Spring Boot
|
|
applications need very little Spring configuration.
|
|
|
|
You can use Spring Boot to create Java applications that can be started by using
|
|
`java -jar` or more traditional war deployments. We also provide a command line tool that
|
|
runs "`spring scripts`".
|
|
|
|
Our primary goals are:
|
|
|
|
* Provide a radically faster and widely accessible getting-started experience for all
|
|
Spring development.
|
|
* Be opinionated out of the box but get out of the way quickly as requirements start to
|
|
diverge from the defaults.
|
|
* Provide a range of non-functional features that are common to large classes of projects
|
|
(such as embedded servers, security, metrics, health checks, and externalized
|
|
configuration).
|
|
* Absolutely no code generation and no requirement for XML configuration.
|
|
|
|
|
|
|
|
[[getting-started-system-requirements]]
|
|
== System Requirements
|
|
Spring Boot {spring-boot-version} requires https://www.java.com[Java 8 or 9] and
|
|
{spring-reference}[Spring Framework {spring-version}] or above. Explicit build support is
|
|
provided for Maven 3.2+ and Gradle 4.
|
|
|
|
|
|
|
|
[[getting-started-system-requirements-servlet-containers]]
|
|
=== Servlet Containers
|
|
Spring Boot supports the following embedded servlet containers:
|
|
|
|
|===
|
|
|Name |Servlet Version
|
|
|
|
|Tomcat 8.5
|
|
|3.1
|
|
|
|
|Jetty 9.4
|
|
|3.1
|
|
|
|
|Undertow 1.4
|
|
|3.1
|
|
|===
|
|
|
|
You can also deploy Spring Boot applications to any Servlet 3.1+ compatible container.
|
|
|
|
|
|
|
|
[[getting-started-installing-spring-boot]]
|
|
== Installing Spring Boot
|
|
Spring Boot can be used with "`classic`" Java development tools or installed as a command
|
|
line tool. Either way, you need https://www.java.com[Java SDK v1.8] or higher. Before you
|
|
begin, you should check your current Java installation by using the following command:
|
|
|
|
[indent=0]
|
|
----
|
|
$ java -version
|
|
----
|
|
|
|
If you are new to Java development or if you want to experiment with Spring Boot, you
|
|
might want to try the <<getting-started-installing-the-cli, Spring Boot CLI>> (Command
|
|
Line Interface) first. Otherwise, read on for "`classic`" installation instructions.
|
|
|
|
|
|
|
|
[[getting-started-installation-instructions-for-java]]
|
|
=== Installation Instructions for the Java Developer
|
|
You can use Spring Boot in the same way as any standard Java library. To do so, include
|
|
the appropriate `+spring-boot-*.jar+` files on your classpath. Spring Boot does not
|
|
require any special tools integration, so you can use any IDE or text editor. Also, there
|
|
is nothing special about a Spring Boot application, so you can run and debug a Spring
|
|
Boot application as you would any other Java program.
|
|
|
|
Although you _could_ copy Spring Boot jars, we generally recommend that you use a build
|
|
tool that supports dependency management (such as Maven or Gradle).
|
|
|
|
|
|
|
|
[[getting-started-maven-installation]]
|
|
==== Maven Installation
|
|
Spring Boot is compatible with Apache Maven 3.2 or above. If you do not already have
|
|
Maven installed, you can follow the instructions at https://maven.apache.org.
|
|
|
|
TIP: On many operating systems, Maven can be installed with a package manager. If you use
|
|
OSX Homebrew, try `brew install maven`. Ubuntu users can run
|
|
`sudo apt-get install maven`. Windows users with https://chocolatey.org/[Chocolatey] can
|
|
run `choco install maven` from an elevated (administrator) prompt.
|
|
|
|
Spring Boot dependencies use the `org.springframework.boot` `groupId`. Typically, your
|
|
Maven POM file inherits from the `spring-boot-starter-parent` project and declares
|
|
dependencies to one or more <<using-spring-boot.adoc#using-boot-starter,"`Starters`">>.
|
|
Spring Boot also provides an optional
|
|
<<build-tool-plugins.adoc#build-tool-plugins-maven-plugin, Maven plugin>> to create
|
|
executable jars.
|
|
|
|
The following listing shows a typical `pom.xml` file:
|
|
|
|
[source,xml,indent=0,subs="verbatim,quotes,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 http://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>
|
|
|
|
<!-- Inherit defaults from Spring Boot -->
|
|
<parent>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-starter-parent</artifactId>
|
|
<version>{spring-boot-version}</version>
|
|
</parent>
|
|
|
|
<!-- Add typical dependencies for a web application -->
|
|
<dependencies>
|
|
<dependency>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-starter-web</artifactId>
|
|
</dependency>
|
|
</dependencies>
|
|
|
|
<!-- Package as an executable jar -->
|
|
<build>
|
|
<plugins>
|
|
<plugin>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-maven-plugin</artifactId>
|
|
</plugin>
|
|
</plugins>
|
|
</build>
|
|
|
|
ifeval::["{spring-boot-repo}" != "release"]
|
|
<!-- Add Spring repositories -->
|
|
<!-- (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>
|
|
----
|
|
|
|
TIP: The `spring-boot-starter-parent` is a great way to use Spring Boot, but it might not
|
|
be suitable all of the time. Sometimes you may need to inherit from a different parent
|
|
POM, or you might not like our default settings. In those cases, see
|
|
<<using-boot-maven-without-a-parent>> for an alternative solution that uses an `import`
|
|
scope.
|
|
|
|
|
|
|
|
[[getting-started-gradle-installation]]
|
|
==== Gradle Installation
|
|
Spring Boot is compatible with Gradle 4. If you do not already have Gradle installed, you
|
|
can follow the instructions at https://gradle.org.
|
|
|
|
Spring Boot dependencies can be declared by using the `org.springframework.boot` `group`.
|
|
Typically, your project declares dependencies to one or more
|
|
<<using-spring-boot.adoc#using-boot-starter, "`Starters`">>. Spring Boot
|
|
provides a useful <<build-tool-plugins.adoc#build-tool-plugins-gradle-plugin, Gradle
|
|
plugin>> that can be used to simplify dependency declarations and to create executable
|
|
jars.
|
|
|
|
.Gradle Wrapper
|
|
****
|
|
The Gradle Wrapper provides a nice way of "`obtaining`" Gradle when you need to build a
|
|
project. It is a small script and library that you commit alongside your code to
|
|
bootstrap the build process. See {gradle-user-guide}/gradle_wrapper.html for details.
|
|
****
|
|
|
|
The following example shows a typical `build.gradle` file:
|
|
|
|
[source,groovy,indent=0,subs="verbatim,attributes"]
|
|
----
|
|
ifeval::["{spring-boot-repo}" == "release"]
|
|
plugins {
|
|
id 'org.springframework.boot' version '{spring-boot-version}'
|
|
id 'java'
|
|
}
|
|
endif::[]
|
|
ifeval::["{spring-boot-repo}" != "release"]
|
|
buildscript {
|
|
repositories {
|
|
jcenter()
|
|
maven { url 'https://repo.spring.io/snapshot' }
|
|
maven { url 'https://repo.spring.io/milestone' }
|
|
}
|
|
dependencies {
|
|
classpath 'org.springframework.boot:spring-boot-gradle-plugin:{spring-boot-version}'
|
|
}
|
|
}
|
|
|
|
apply plugin: 'java'
|
|
apply plugin: 'org.springframework.boot'
|
|
apply plugin: 'io.spring.dependency-management'
|
|
|
|
endif::[]
|
|
jar {
|
|
baseName = 'myproject'
|
|
version = '0.0.1-SNAPSHOT'
|
|
}
|
|
|
|
repositories {
|
|
jcenter()
|
|
ifeval::["{spring-boot-repo}" != "release"]
|
|
maven { url "https://repo.spring.io/snapshot" }
|
|
maven { url "https://repo.spring.io/milestone" }
|
|
endif::[]
|
|
}
|
|
|
|
dependencies {
|
|
compile("org.springframework.boot:spring-boot-starter-web")
|
|
testCompile("org.springframework.boot:spring-boot-starter-test")
|
|
}
|
|
----
|
|
|
|
|
|
|
|
[[getting-started-installing-the-cli]]
|
|
=== Installing the Spring Boot CLI
|
|
The Spring Boot CLI (Command Line Interface) is a command line tool that you can use to
|
|
quickly prototype with Spring. It lets you run http://groovy-lang.org/[Groovy] scripts,
|
|
which means that you have a familiar Java-like syntax without so much boilerplate code.
|
|
|
|
You do not need to use the CLI to work with Spring Boot, but it is definitely the
|
|
quickest way to get a Spring application off the ground.
|
|
|
|
|
|
|
|
[[getting-started-manual-cli-installation]]
|
|
==== Manual Installation
|
|
You can download the Spring CLI distribution from the Spring software repository:
|
|
|
|
* https://repo.spring.io/{spring-boot-repo}/org/springframework/boot/spring-boot-cli/{spring-boot-version}/spring-boot-cli-{spring-boot-version}-bin.zip[spring-boot-cli-{spring-boot-version}-bin.zip]
|
|
* https://repo.spring.io/{spring-boot-repo}/org/springframework/boot/spring-boot-cli/{spring-boot-version}/spring-boot-cli-{spring-boot-version}-bin.tar.gz[spring-boot-cli-{spring-boot-version}-bin.tar.gz]
|
|
|
|
Cutting edge
|
|
https://repo.spring.io/snapshot/org/springframework/boot/spring-boot-cli/[snapshot
|
|
distributions] are also available.
|
|
|
|
Once downloaded, follow the
|
|
{github-raw}/spring-boot-project/spring-boot-cli/src/main/content/INSTALL.txt[INSTALL.txt]
|
|
instructions from the unpacked archive. In summary, there is a `spring` script
|
|
(`spring.bat` for Windows) in a `bin/` directory in the `.zip` file. Alternatively, you
|
|
can use `java -jar` with the `.jar` file (the script helps you to be sure that the
|
|
classpath is set correctly).
|
|
|
|
|
|
|
|
[[getting-started-sdkman-cli-installation]]
|
|
==== Installation with SDKMAN!
|
|
SDKMAN! (The Software Development Kit Manager) can be used for managing multiple versions
|
|
of various binary SDKs, including Groovy and the Spring Boot CLI.
|
|
Get SDKMAN! from http://sdkman.io and install Spring Boot by using the following
|
|
commands:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ sdk install springboot
|
|
$ spring --version
|
|
Spring Boot v{spring-boot-version}
|
|
----
|
|
|
|
If you develop features for the CLI and want easy access to the version you built,
|
|
use the following commands:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ sdk install springboot dev /path/to/spring-boot/spring-boot-cli/target/spring-boot-cli-{spring-boot-version}-bin/spring-{spring-boot-version}/
|
|
$ sdk default springboot dev
|
|
$ spring --version
|
|
Spring CLI v{spring-boot-version}
|
|
----
|
|
|
|
The preceding instructions install a local instance of `spring` called the `dev`
|
|
instance. It points at your target build location, so every time you rebuild Spring Boot,
|
|
`spring` is up-to-date.
|
|
|
|
You can see it by running the following command:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ sdk ls springboot
|
|
|
|
================================================================================
|
|
Available Springboot Versions
|
|
================================================================================
|
|
> + dev
|
|
* {spring-boot-version}
|
|
|
|
================================================================================
|
|
+ - local version
|
|
* - installed
|
|
> - currently in use
|
|
================================================================================
|
|
----
|
|
|
|
|
|
|
|
[[getting-started-homebrew-cli-installation]]
|
|
==== OSX Homebrew Installation
|
|
If you are on a Mac and use http://brew.sh/[Homebrew], you can install the Spring Boot
|
|
CLI by using the following commands:
|
|
|
|
[indent=0]
|
|
----
|
|
$ brew tap pivotal/tap
|
|
$ brew install springboot
|
|
----
|
|
|
|
Homebrew installs `spring` to `/usr/local/bin`.
|
|
|
|
NOTE: If you do not see the formula, your installation of brew might be out-of-date. In
|
|
that case, run `brew update` and try again.
|
|
|
|
|
|
|
|
[[getting-started-macports-cli-installation]]
|
|
==== MacPorts Installation
|
|
If you are on a Mac and use http://www.macports.org/[MacPorts], you can install the
|
|
Spring Boot CLI by using the following command:
|
|
|
|
[indent=0]
|
|
----
|
|
$ sudo port install spring-boot-cli
|
|
----
|
|
|
|
|
|
|
|
[[getting-started-cli-command-line-completion]]
|
|
==== Command-line Completion
|
|
The Spring Boot CLI includes scripts that provide command completion for the
|
|
https://en.wikipedia.org/wiki/Bash_%28Unix_shell%29[BASH] and
|
|
https://en.wikipedia.org/wiki/Z_shell[zsh] shells. You can `source` the script (also named
|
|
`spring`) in any shell or put it in your personal or system-wide bash completion
|
|
initialization. On a Debian system, the system-wide scripts are in
|
|
`/shell-completion/bash` and all scripts in that directory are executed when a new shell
|
|
starts. For example, to run the script manually if you have installed by using SDKMAN!,
|
|
use the following commands:
|
|
|
|
[indent=0]
|
|
----
|
|
$ . ~/.sdkman/candidates/springboot/current/shell-completion/bash/spring
|
|
$ spring <HIT TAB HERE>
|
|
grab help jar run test version
|
|
----
|
|
|
|
NOTE: If you install the Spring Boot CLI by using Homebrew or MacPorts, the command-line
|
|
completion scripts are automatically registered with your shell.
|
|
|
|
|
|
|
|
[[getting-started-scoop-cli-installation]]
|
|
==== Windows Scoop Installation
|
|
If you are on a Windows and use http://scoop.sh/[Scoop], you can install the Spring Boot
|
|
CLI by using the following commands:
|
|
|
|
[indent=0]
|
|
----
|
|
> scoop bucket add extras
|
|
> scoop install springboot
|
|
----
|
|
|
|
Scoop installs `spring` to `~/scoop/apps/springboot/current/bin`.
|
|
|
|
NOTE: If you do not see the app manifest, your installation of scoop might be out-of-date.
|
|
In that case, run `scoop update` and try again.
|
|
|
|
|
|
|
|
[[getting-started-cli-example]]
|
|
==== Quick-start Spring CLI Example
|
|
You can use the following web application to test your installation. To start, create a
|
|
file called `app.groovy`, as follows:
|
|
|
|
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
@RestController
|
|
class ThisWillActuallyRun {
|
|
|
|
@RequestMapping("/")
|
|
String home() {
|
|
"Hello World!"
|
|
}
|
|
|
|
}
|
|
----
|
|
|
|
Then run it from a shell, as follows:
|
|
|
|
[indent=0]
|
|
----
|
|
$ spring run app.groovy
|
|
----
|
|
|
|
NOTE: The first run of your application is slow, as dependencies are downloaded.
|
|
Subsequent runs are much quicker.
|
|
|
|
Open `http://localhost:8080` in your favorite web browser. You should see the following
|
|
output:
|
|
|
|
[indent=0]
|
|
----
|
|
Hello World!
|
|
----
|
|
|
|
|
|
|
|
[[getting-started-upgrading-from-an-earlier-version]]
|
|
=== Upgrading from an Earlier Version of Spring Boot
|
|
If you are upgrading from an earlier release of Spring Boot, check the
|
|
{github-wiki}/Spring-Boot-2.0-Migration-Guide["`migration guide`" on the project wiki]
|
|
that provides detailed upgrade instructions. Check also the
|
|
{github-wiki}["`release notes`"] for a list of "`new and noteworthy`" features for each
|
|
release.
|
|
|
|
When upgrading to a new feature release, some properties may have been renamed or removed.
|
|
Spring Boot provides a way to analyze your application's environment and print diagnostics
|
|
at startup, but also temporarily migrate properties at runtime for you. To enable that
|
|
feature, add the following dependency to your project:
|
|
|
|
[source,xml,indent=0]
|
|
----
|
|
<dependency>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-properties-migrator</artifactId>
|
|
<scope>runtime</scope>
|
|
</dependency>
|
|
----
|
|
|
|
WARNING: properties that are added late to the environment, such as when using
|
|
`@PropertySource`, will not be taken into account.
|
|
|
|
NOTE: Once you're done with the migration, please make sure to remove this module from
|
|
your project's dependencies.
|
|
|
|
To upgrade an existing CLI installation, use the appropriate package manager command (for
|
|
example, `brew upgrade`) or, if you manually installed the CLI, follow the
|
|
<<getting-started-manual-cli-installation, standard instructions>>, remembering to update
|
|
your `PATH` environment variable to remove any older references.
|
|
|
|
|
|
|
|
[[getting-started-first-application]]
|
|
== Developing Your First Spring Boot Application
|
|
This section describes how to develop a simple "`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-first-application-code,start coding right away>>. Check
|
|
the {spring-initializr-reference}/#user-guide[Spring Initializr documentation] 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.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015-11-10T16:41:47+00: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 folder. Subsequent instructions assume
|
|
that you have created a suitable folder 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,quotes,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 http://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>
|
|
|
|
<!-- Additional lines to be added here... -->
|
|
|
|
ifeval::["{spring-boot-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 sample application has already used `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-spring-boot.adoc#using-boot-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,quotes,attributes"]
|
|
----
|
|
<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 folder structure and
|
|
then add a file named `src/main/java/Example.java` to contain the following code:
|
|
|
|
[source,java,indent=0]
|
|
----
|
|
import org.springframework.boot.*;
|
|
import org.springframework.boot.autoconfigure.*;
|
|
import org.springframework.web.bind.annotation.*;
|
|
|
|
@RestController
|
|
@EnableAutoConfiguration
|
|
public class Example {
|
|
|
|
@RequestMapping("/")
|
|
String home() {
|
|
return "Hello World!";
|
|
}
|
|
|
|
public static void main(String[] args) throws Exception {
|
|
SpringApplication.run(Example.class, args);
|
|
}
|
|
|
|
}
|
|
----
|
|
|
|
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-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-reference}web.html#mvc[MVC
|
|
section] in the Spring Reference Documentation for more details.
|
|
|
|
|
|
|
|
[[getting-started-first-application-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-main-method]]
|
|
==== The "`main`" Method
|
|
The final part of our application is the `main` method. This is just 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="attributes"]
|
|
----
|
|
$ mvn spring-boot:run
|
|
|
|
. ____ _ __ _ _
|
|
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
|
|
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
|
|
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
|
|
' |____| .__|_| |_|_| |_\__, | / / / /
|
|
=========|_|==============|___/=/_/_/_/
|
|
:: Spring Boot :: (v{spring-boot-version})
|
|
....... . . .
|
|
....... . . . (log output here)
|
|
....... . . .
|
|
........ Started Example 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 <<appendix-executable-jar-format.adoc#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,quotes,attributes"]
|
|
----
|
|
<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-site}/usage.html[plugin
|
|
documentation] for details.
|
|
|
|
Save your `pom.xml` and run `mvn package` from the command line, as follows:
|
|
|
|
[indent=0,subs="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="attributes"]
|
|
----
|
|
$ java -jar target/myproject-0.0.1-SNAPSHOT.jar
|
|
|
|
. ____ _ __ _ _
|
|
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
|
|
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
|
|
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
|
|
' |____| .__|_| |_|_| |_\__, | / / / /
|
|
=========|_|==============|___/=/_/_/_/
|
|
:: Spring Boot :: (v{spring-boot-version})
|
|
....... . . .
|
|
....... . . . (log output here)
|
|
....... . . .
|
|
........ Started Example in 2.536 seconds (JVM running for 2.864)
|
|
----
|
|
|
|
As before, to exit the application, press `ctrl-c`.
|
|
|
|
|
|
|
|
[[getting-started-whats-next]]
|
|
== What to Read Next
|
|
Hopefully, this section provided some of the Spring Boot basics and got you on your way
|
|
to writing your own applications. If you are a task-oriented type of developer, you might
|
|
want to jump over to https://spring.io and check out some of the
|
|
https://spring.io/guides/[getting started] guides that solve specific "`How do I do that
|
|
with Spring?`" problems. We also have Spring Boot-specific
|
|
"`<<howto.adoc#howto, How-to>>`" reference documentation.
|
|
|
|
The https://github.com/{github-repo}[Spring Boot repository] also has a
|
|
{github-code}/spring-boot-samples[bunch of samples] you can run. The samples are
|
|
independent of the rest of the code (that is, you do not need to build the rest to run or
|
|
use the samples).
|
|
|
|
Otherwise, the next logical step is to read _<<using-spring-boot.adoc#using-boot>>_. If
|
|
you are really impatient, you could also jump ahead and read about
|
|
_<<spring-boot-features.adoc#boot-features, Spring Boot features>>_.
|