You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
818 lines
28 KiB
818 lines
28 KiB
[[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 |
|
By default, Spring Boot {spring-boot-version} requires http://www.java.com[Java 7] and |
|
Spring Framework {spring-version} or above. You can use Spring Boot with Java 6 with some |
|
additional configuration. See <<howto.adoc#howto-use-java-6>> for more details. Explicit |
|
build support is provided for Maven (3.2+) and Gradle (1.12 or 2.x). Gradle 3 is not |
|
supported. |
|
|
|
TIP: Although you can use Spring Boot with Java 6 or 7, we generally recommend Java 8 if |
|
at all possible. |
|
|
|
=== Servlet containers |
|
The following embedded servlet containers are supported out of the box: |
|
|
|
|=== |
|
|Name |Servlet Version |Java Version |
|
|
|
|Tomcat 8 |
|
|3.1 |
|
|Java 7+ |
|
|
|
|Tomcat 7 |
|
|3.0 |
|
|Java 6+ |
|
|
|
|Jetty 9 |
|
|3.1 |
|
|Java 7+ |
|
|
|
|Jetty 8 |
|
|3.0 |
|
|Java 6+ |
|
|
|
|Undertow 1.1 |
|
|3.1 |
|
|Java 7+ |
|
|=== |
|
|
|
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.6] 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. |
|
|
|
TIP: Although Spring Boot is compatible with Java 1.6, if possible, you should consider |
|
using the latest version of Java. |
|
|
|
|
|
|
|
[[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-poms, "`Starter |
|
POMs`">>. 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 1.12 or 2.x. 2.14.1 is recommended. Gradle 3 is not |
|
supported. 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-poms, "`Starter POMs`">>. 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"] |
|
---- |
|
buildscript { |
|
repositories { |
|
jcenter() |
|
ifndef::release[] |
|
maven { url "http://repo.spring.io/snapshot" } |
|
maven { url "http://repo.spring.io/milestone" } |
|
endif::release[] |
|
} |
|
dependencies { |
|
classpath("org.springframework.boot:spring-boot-gradle-plugin:{spring-boot-version}") |
|
} |
|
} |
|
|
|
apply plugin: 'java' |
|
apply plugin: 'spring-boot' |
|
|
|
jar { |
|
baseName = 'myproject' |
|
version = '0.0.1-SNAPSHOT' |
|
} |
|
|
|
repositories { |
|
jcenter() |
|
ifndef::release[] |
|
maven { url "http://repo.spring.io/snapshot" } |
|
maven { url "http://repo.spring.io/milestone" } |
|
endif::release[] |
|
} |
|
|
|
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/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 the way>>. 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.7.0_51" |
|
Java(TM) SE Runtime Environment (build 1.7.0_51-b13) |
|
Java HotSpot(TM) 64-Bit Server VM (build 24.51-b03, mixed mode) |
|
---- |
|
|
|
[indent=0] |
|
---- |
|
$ mvn -v |
|
Apache Maven 3.2.3 (33f8c3e1027c3ddde99d3cdebad2656a31e8fdf4; 2014-08-11T13:58:10-07:00) |
|
Maven home: /Users/user/tools/apache-maven-3.1.1 |
|
Java version: 1.7.0_51, 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 "`Starter POMs`" 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 "`Starter POMs`" 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. |
|
|
|
.Starter POMs and Auto-Configuration |
|
**** |
|
Auto-configuration is designed to work well with "`Starter POMs`", but the two concepts |
|
are not directly tied. You are free to pick-and-choose jar dependencies outside of the |
|
starter POMs 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>>_.
|
|
|