807 lines
28 KiB
Plaintext
807 lines
28 KiB
Plaintext
[[getting-started]]
|
|
= Getting started
|
|
|
|
[partintro]
|
|
--
|
|
If you're just getting started with Spring Boot, or 'Spring' in general, this is the section
|
|
for you! Here we answer the basic "`what?`", "`how?`" and "`why?`" questions. You'll
|
|
find a gentle introduction to Spring Boot along with installation instructions.
|
|
We'll then build our 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 "`just run`". We take an opinionated view of the Spring
|
|
platform and third-party libraries so 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 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
|
|
(e.g. embedded servers, security, metrics, health checks, externalized configuration).
|
|
* Absolutely no code generation and no requirement for XML configuration.
|
|
|
|
|
|
|
|
[[getting-started-system-requirements]]
|
|
== System Requirements
|
|
Spring Boot {spring-boot-version} requires http://www.java.com[Java 8] and Spring
|
|
Framework {spring-version} or above. Explicit build support is provided for Maven
|
|
(3.2+), and Gradle 3 (3.4 or later).
|
|
|
|
|
|
[[getting-started-system-requirements-servlet-containers]]
|
|
=== Servlet containers
|
|
The following embedded servlet containers are supported out of the box:
|
|
|
|
|===
|
|
|Name |Servlet Version
|
|
|
|
|Tomcat 8.5
|
|
|3.1
|
|
|
|
|Jetty 9.4
|
|
|3.1
|
|
|
|
|Undertow 1.3
|
|
|3.1
|
|
|===
|
|
|
|
You can also deploy Spring Boot applications to any Servlet 3.0+ 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. Regardless, you will need http://www.java.com[Java SDK v1.8] or higher. You
|
|
should check your current Java installation before you begin:
|
|
|
|
[indent=0]
|
|
----
|
|
$ java -version
|
|
----
|
|
|
|
If you are new to Java development, or if you just want to experiment with Spring Boot
|
|
you might want to try the <<getting-started-installing-the-cli, Spring Boot CLI>> 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. Simply 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; and there is
|
|
nothing special about a Spring Boot application, so you can run and debug as you would
|
|
any other Java program.
|
|
|
|
Although you _could_ just 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 don't already have Maven
|
|
installed you can follow the instructions at http://maven.apache.org.
|
|
|
|
TIP: On many operating systems Maven can be installed via a package manager. If you're an
|
|
OSX Homebrew user try `brew install maven`. Ubuntu users can run
|
|
`sudo apt-get install maven`.
|
|
|
|
Spring Boot dependencies use the `org.springframework.boot` `groupId`. Typically your
|
|
Maven POM file will inherit from the `spring-boot-starter-parent` project and declare
|
|
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.
|
|
|
|
Here is 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>http://repo.spring.io/snapshot</url>
|
|
<snapshots><enabled>true</enabled></snapshots>
|
|
</repository>
|
|
<repository>
|
|
<id>spring-milestones</id>
|
|
<url>http://repo.spring.io/milestone</url>
|
|
</repository>
|
|
</repositories>
|
|
<pluginRepositories>
|
|
<pluginRepository>
|
|
<id>spring-snapshots</id>
|
|
<url>http://repo.spring.io/snapshot</url>
|
|
</pluginRepository>
|
|
<pluginRepository>
|
|
<id>spring-milestones</id>
|
|
<url>http://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 just not like our default settings. 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 3 (3.4 or later). If you don't already have Gradle
|
|
installed you can follow the instructions at http://www.gradle.org/.
|
|
|
|
Spring Boot dependencies can be declared using the `org.springframework.boot` `group`.
|
|
Typically your project will declare 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's 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.
|
|
****
|
|
|
|
Here is 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 'http://repo.spring.io/snapshot' }
|
|
maven { url 'http://repo.spring.io/milestone' }
|
|
}
|
|
dependencies {
|
|
classpath 'org.springframework.boot:spring-boot-gradle-plugin:{spring-boot-version}'
|
|
}
|
|
}
|
|
|
|
apply plugin: 'java'
|
|
apply plugin: 'org.springframework.boot'
|
|
|
|
endif::[]
|
|
jar {
|
|
baseName = 'myproject'
|
|
version = '0.0.1-SNAPSHOT'
|
|
}
|
|
|
|
repositories {
|
|
jcenter()
|
|
ifeval::["{spring-boot-repo}" != "release"]
|
|
maven { url "http://repo.spring.io/snapshot" }
|
|
maven { url "http://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 is a command line tool that can be used if you want to quickly
|
|
prototype with Spring. It allows you to run http://groovy.codehaus.org/[Groovy] scripts,
|
|
which means that you have a familiar Java-like syntax, without so much boilerplate code.
|
|
|
|
You don't need to use the CLI to work with Spring Boot but it's 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:
|
|
|
|
* http://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]
|
|
* http://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 http://repo.spring.io/snapshot/org/springframework/boot/spring-boot-cli/[snapshot distributions]
|
|
are also available.
|
|
|
|
Once downloaded, follow the {github-raw}/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, or 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 with
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ sdk install springboot
|
|
$ spring --version
|
|
Spring Boot v{spring-boot-version}
|
|
----
|
|
|
|
If you are developing features for the CLI and want easy access to the version you just
|
|
built, follow these extra instructions.
|
|
|
|
[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}
|
|
----
|
|
|
|
This will 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` will be up-to-date.
|
|
|
|
You can see it by doing this:
|
|
|
|
[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 using http://brew.sh/[Homebrew], all you need to do to install
|
|
the Spring Boot CLI is:
|
|
|
|
[indent=0]
|
|
----
|
|
$ brew tap pivotal/tap
|
|
$ brew install springboot
|
|
----
|
|
|
|
Homebrew will install `spring` to `/usr/local/bin`.
|
|
|
|
NOTE: If you don't see the formula, your installation of brew might be out-of-date.
|
|
Just execute `brew update` and try again.
|
|
|
|
|
|
|
|
[[getting-started-macports-cli-installation]]
|
|
==== MacPorts installation
|
|
If you are on a Mac and using http://www.macports.org/[MacPorts], all you need to do to
|
|
install the Spring Boot CLI is:
|
|
|
|
[indent=0]
|
|
----
|
|
$ sudo port install spring-boot-cli
|
|
----
|
|
|
|
|
|
|
|
[[getting-started-cli-command-line-completion]]
|
|
==== Command-line completion
|
|
Spring Boot CLI ships with scripts that provide command completion for
|
|
http://en.wikipedia.org/wiki/Bash_%28Unix_shell%29[BASH] and
|
|
http://en.wikipedia.org/wiki/Zsh[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. To run the script
|
|
manually, e.g. if you have installed using SDKMAN!
|
|
|
|
[indent=0]
|
|
----
|
|
$ . ~/.sdkman/candidates/springboot/current/shell-completion/bash/spring
|
|
$ spring <HIT TAB HERE>
|
|
grab help jar run test version
|
|
----
|
|
|
|
NOTE: If you install Spring Boot CLI using Homebrew or MacPorts, the command-line
|
|
completion scripts are automatically registered with your shell.
|
|
|
|
|
|
|
|
[[getting-started-cli-example]]
|
|
==== Quick start Spring CLI example
|
|
Here's a really simple web application that you can use to test your installation. Create
|
|
a file called `app.groovy`:
|
|
|
|
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
@RestController
|
|
class ThisWillActuallyRun {
|
|
|
|
@RequestMapping("/")
|
|
String home() {
|
|
"Hello World!"
|
|
}
|
|
|
|
}
|
|
----
|
|
|
|
Then simply run it from a shell:
|
|
|
|
[indent=0]
|
|
----
|
|
$ spring run app.groovy
|
|
----
|
|
|
|
NOTE: It will take some time when you first run the application as dependencies are
|
|
downloaded. Subsequent runs will be much quicker.
|
|
|
|
Open http://localhost:8080 in your favorite web browser and 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 "`release notes`"
|
|
hosted on the {github-wiki}[project wiki]. You'll find upgrade instructions along with
|
|
a list of "`new and noteworthy`" features for each release.
|
|
|
|
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
|
|
Let's develop a simple "`Hello World!`" web application in Java that highlights some
|
|
of Spring Boot's key features. We'll use Maven to build this project since most IDEs
|
|
support it.
|
|
|
|
[TIP]
|
|
====
|
|
The http://spring.io[spring.io] web site contains many "`Getting Started`" guides
|
|
that use Spring Boot. If you're looking 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. This will automatically generate a new
|
|
project structure so that you can <<getting-started-first-application-code,start coding
|
|
right away>>. Check the https://github.com/spring-io/initializr[documentation for
|
|
more details].
|
|
====
|
|
|
|
Before we begin, open a terminal to check 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
|
|
will be 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>http://repo.spring.io/snapshot</url>
|
|
<snapshots><enabled>true</enabled></snapshots>
|
|
</repository>
|
|
<repository>
|
|
<id>spring-milestones</id>
|
|
<url>http://repo.spring.io/milestone</url>
|
|
</repository>
|
|
</repositories>
|
|
<pluginRepositories>
|
|
<pluginRepository>
|
|
<id>spring-snapshots</id>
|
|
<url>http://repo.spring.io/snapshot</url>
|
|
</pluginRepository>
|
|
<pluginRepository>
|
|
<id>spring-milestones</id>
|
|
<url>http://repo.spring.io/milestone</url>
|
|
</pluginRepository>
|
|
</pluginRepositories>
|
|
endif::[]
|
|
</project>
|
|
----
|
|
|
|
This should give you a working build, you can test it out by running `mvn package` (you
|
|
can ignore the "`jar will be empty - no content was marked for inclusion!`" warning for
|
|
now).
|
|
|
|
NOTE: At this point you could import the project into an IDE (most modern Java IDE's
|
|
include built-in support for Maven). For simplicity, we will 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 make easy to 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`" simply provide dependencies that you are likely to need when
|
|
developing a specific type of application. Since we are developing a web application, we
|
|
will add a `spring-boot-starter-web` dependency -- but before that, let's look at what we
|
|
currently have.
|
|
|
|
[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. Let's edit our `pom.xml` and add the `spring-boot-starter-web` dependency
|
|
just 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 will 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. Maven will compile sources
|
|
from `src/main/java` by default so you need to create that folder structure, then add a
|
|
file named `src/main/java/Example.java`:
|
|
|
|
[source,java,indent=0]
|
|
----
|
|
import org.springframework.boot.*;
|
|
import org.springframework.boot.autoconfigure.*;
|
|
import org.springframework.stereotype.*;
|
|
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 isn't much code here, quite a lot is going on. Let's step through the
|
|
important parts.
|
|
|
|
|
|
|
|
[[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 will consider it when handling incoming web requests.
|
|
|
|
The `@RequestMapping` annotation provides "`routing`" information. It is telling 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}#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 will 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 will assume that you are developing a web application
|
|
and setup 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 and Spring Boot will still do 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` will
|
|
bootstrap our application, starting Spring which will in turn start 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 our application should work. Since we have used the
|
|
`spring-boot-starter-parent` POM we have a useful `run` goal that we can use to start
|
|
the application. Type `mvn spring-boot:run` from the root project directory to start the
|
|
application:
|
|
|
|
[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 hit `ctrl-c`.
|
|
|
|
|
|
|
|
[[getting-started-first-application-executable-jar]]
|
|
=== Creating an executable jar
|
|
Let's 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 any standard way to load nested jar files (i.e. 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 simply packages
|
|
all classes, from all jars, into a single archive. The problem with this approach is that
|
|
it becomes hard to see which libraries you are actually using 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 allows you to actually nest jars directly.
|
|
****
|
|
|
|
To create an executable jar we need to add the `spring-boot-maven-plugin` to our
|
|
`pom.xml`. 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 are not using the parent POM you will 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:
|
|
|
|
[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`:
|
|
|
|
[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:
|
|
|
|
[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 gracefully exit the application hit `ctrl-c`.
|
|
|
|
|
|
|
|
[[getting-started-whats-next]]
|
|
== What to read next
|
|
Hopefully this section has provided you with some of the Spring Boot basics, and got you
|
|
on your way to writing your own applications. If you're a task-oriented type of
|
|
developer you might want to jump over to http://spring.io and check out some of the
|
|
http://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 http://github.com/{github-repo}[Spring Boot repository] has also 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 don't 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're really impatient, you could also jump ahead and read about
|
|
_<<spring-boot-features.adoc#boot-features, Spring Boot features>>_.
|