Editorial changes to Getting Started documentation
See gh-10763
This commit is contained in:
Jay Bryant
Andy Wilkinson
parent
3ef67004a3
commit
ce40de5cbb
|
|
@ -1,12 +1,12 @@
|
|||
[[getting-started]]
|
||||
= 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
|
||||
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.
|
||||
--
|
||||
|
||||
|
|
@ -14,11 +14,11 @@ 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
|
||||
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 using `java -jar`
|
||||
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`".
|
||||
|
||||
|
|
@ -26,10 +26,10 @@ 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
|
||||
* 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).
|
||||
(such as embedded servers, security, metrics, health checks, and externalized configuration).
|
||||
* Absolutely no code generation and no requirement for XML configuration.
|
||||
|
||||
|
||||
|
|
@ -38,11 +38,11 @@ diverge from the defaults.
|
|||
== 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 4.
|
||||
3.2+, and Gradle 4.
|
||||
|
||||
|
||||
[[getting-started-system-requirements-servlet-containers]]
|
||||
=== Servlet containers
|
||||
=== Servlet Containers
|
||||
The following embedded servlet containers are supported out of the box:
|
||||
|
||||
|===
|
||||
|
|
@ -65,51 +65,51 @@ You can also deploy Spring Boot applications to any Servlet 3.0+ compatible cont
|
|||
[[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:
|
||||
line tool. Either way, you need http://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 just want to experiment with Spring Boot
|
||||
you might want to try the <<getting-started-installing-the-cli, Spring Boot CLI>> first,
|
||||
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. Simply include the
|
||||
=== 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; and there is
|
||||
nothing special about a Spring Boot application, so you can run and debug as you would
|
||||
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_ just copy Spring Boot jars, we generally recommend that you use a
|
||||
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 don't already have Maven
|
||||
installed you can follow the instructions at http://maven.apache.org.
|
||||
==== 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 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
|
||||
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 Chocolatey can run `choco install maven`
|
||||
from an elevated prompt.
|
||||
from an elevated (administrator) prompt.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
Here is a typical `pom.xml` file:
|
||||
The following listing shows a typical `pom.xml` file:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
|
|
@ -177,19 +177,19 @@ endif::[]
|
|||
|
||||
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
|
||||
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 don't already have Gradle installed you
|
||||
==== Gradle Installation
|
||||
Spring Boot is compatible with Gradle 4. If you do not 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
|
||||
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.
|
||||
|
|
@ -197,7 +197,7 @@ that can be used to simplify dependency declarations and to create executable ja
|
|||
.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
|
||||
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.
|
||||
****
|
||||
|
||||
|
|
@ -251,17 +251,17 @@ endif::[]
|
|||
|
||||
[[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-lang.org/[Groovy] scripts,
|
||||
which means that you have a familiar Java-like syntax, without so much boilerplate code.
|
||||
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 don't need to use the CLI to work with Spring Boot but it's definitely the quickest
|
||||
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
|
||||
==== 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]
|
||||
|
|
@ -271,8 +271,8 @@ Cutting edge http://repo.spring.io/snapshot/org/springframework/boot/spring-boot
|
|||
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, or alternatively you
|
||||
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).
|
||||
|
||||
|
|
@ -282,7 +282,7 @@ classpath is set correctly).
|
|||
==== 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
|
||||
Get SDKMAN! from http://sdkman.io and install Spring Boot by using the following commands:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
|
|
@ -291,8 +291,8 @@ Get SDKMAN! from http://sdkman.io and install Spring Boot with
|
|||
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.
|
||||
If you are developing features for the CLI and want easy access to the version you
|
||||
built, use the following commands:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
|
|
@ -302,11 +302,11 @@ built, follow these extra instructions.
|
|||
Spring CLI v{spring-boot-version}
|
||||
----
|
||||
|
||||
This will install a local instance of `spring` called the `dev` instance.
|
||||
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` will be up-to-date.
|
||||
Boot, `spring` is up-to-date.
|
||||
|
||||
You can see it by doing this:
|
||||
You can see it by running the following command:
|
||||
|
||||
[indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
|
|
@ -328,9 +328,9 @@ You can see it by doing this:
|
|||
|
||||
|
||||
[[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:
|
||||
==== 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]
|
||||
----
|
||||
|
|
@ -338,17 +338,17 @@ the Spring Boot CLI is:
|
|||
$ brew install springboot
|
||||
----
|
||||
|
||||
Homebrew will install `spring` to `/usr/local/bin`.
|
||||
Homebrew installs `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.
|
||||
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 using http://www.macports.org/[MacPorts], all you need to do to
|
||||
install the Spring Boot CLI is:
|
||||
==== 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]
|
||||
----
|
||||
|
|
@ -358,14 +358,14 @@ install the Spring Boot CLI is:
|
|||
|
||||
|
||||
[[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
|
||||
==== Command-line Completion
|
||||
The Spring Boot CLI includes scripts that provide command completion for
|
||||
the 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!
|
||||
`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 using SDKMAN!, use the following commands:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
|
|
@ -374,15 +374,15 @@ manually, e.g. if you have installed using SDKMAN!
|
|||
grab help jar run test version
|
||||
----
|
||||
|
||||
NOTE: If you install Spring Boot CLI using Homebrew or MacPorts, the command-line
|
||||
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-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`:
|
||||
==== 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"]
|
||||
----
|
||||
|
|
@ -397,17 +397,17 @@ a file called `app.groovy`:
|
|||
}
|
||||
----
|
||||
|
||||
Then simply run it from a shell:
|
||||
Then run it from a shell, as follows:
|
||||
|
||||
[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.
|
||||
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 and you should see the following
|
||||
Open http://localhost:8080 in your favorite web browser. You should see the following
|
||||
output:
|
||||
|
||||
[indent=0]
|
||||
|
|
@ -418,7 +418,7 @@ output:
|
|||
|
||||
|
||||
[[getting-started-upgrading-from-an-earlier-version]]
|
||||
=== Upgrading from an earlier version of Spring Boot
|
||||
=== 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.
|
||||
|
|
@ -431,25 +431,25 @@ 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
|
||||
== 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 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.
|
||||
The http://spring.io[spring.io] web site contains many "`Getting Started`" http://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. This will automatically generate a new
|
||||
"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 https://github.com/spring-io/initializr[documentation for
|
||||
more details].
|
||||
right away>>. Check the https://github.com/spring-io/initializr[Spring Initializr documentation] for
|
||||
more details.
|
||||
====
|
||||
|
||||
Before we begin, open a terminal to check that you have valid versions of Java and Maven
|
||||
installed.
|
||||
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]
|
||||
----
|
||||
|
|
@ -475,7 +475,7 @@ 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:
|
||||
is used to build your project. Open your favorite text editor and add the following:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
----
|
||||
|
|
@ -523,29 +523,28 @@ 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).
|
||||
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 will continue to use a plain
|
||||
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 make easy to add jars to your
|
||||
=== 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`" simply provide dependencies that you are likely to need when
|
||||
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
|
||||
will add a `spring-boot-starter-web` dependency -- but before that, let's look at what we
|
||||
currently have.
|
||||
add a `spring-boot-starter-web` dependency. Before that, we can look at what we
|
||||
currently have by running the following command:
|
||||
|
||||
[indent=0]
|
||||
----
|
||||
|
|
@ -556,8 +555,8 @@ currently have.
|
|||
|
||||
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:
|
||||
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"]
|
||||
----
|
||||
|
|
@ -569,16 +568,16 @@ just below the `parent` section:
|
|||
</dependencies>
|
||||
----
|
||||
|
||||
If you run `mvn dependency:tree` again, you will see that there are now a number of
|
||||
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. 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`:
|
||||
=== 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]
|
||||
----
|
||||
|
|
@ -602,52 +601,52 @@ file named `src/main/java/Example.java`:
|
|||
}
|
||||
----
|
||||
|
||||
Although there isn't much code here, quite a lot is going on. Let's step through the
|
||||
important parts.
|
||||
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 @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.
|
||||
_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 is telling Spring
|
||||
that any HTTP request with the path "`/`" should be mapped to the `home` method. The
|
||||
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
|
||||
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 @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
|
||||
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 will assume that you are developing a web application
|
||||
and setup Spring accordingly.
|
||||
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 and Spring Boot will still do its best to auto-configure your application.
|
||||
starters and Spring Boot still does its best to auto-configure your application.
|
||||
****
|
||||
|
||||
|
||||
|
||||
[[getting-started-first-application-main-method]]
|
||||
==== The "`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
|
||||
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.
|
||||
|
|
@ -655,11 +654,11 @@ 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
|
||||
=== 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:
|
||||
application. You should see output similar to the following:
|
||||
|
||||
[indent=0,subs="attributes"]
|
||||
----
|
||||
|
|
@ -678,33 +677,33 @@ application:
|
|||
........ 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:
|
||||
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`.
|
||||
To gracefully exit the application, press `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
|
||||
=== 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 any standard way to load nested jar files (i.e. jar files that are
|
||||
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 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
|
||||
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.
|
||||
|
||||
|
|
@ -712,8 +711,8 @@ Spring Boot takes a <<appendix-executable-jar-format.adoc#executable-jar, differ
|
|||
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:
|
||||
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"]
|
||||
----
|
||||
|
|
@ -728,11 +727,11 @@ To create an executable jar we need to add the `spring-boot-maven-plugin` to our
|
|||
----
|
||||
|
||||
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
|
||||
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:
|
||||
Save your `pom.xml` and run `mvn package` from the command line, as follows:
|
||||
|
||||
[indent=0,subs="attributes"]
|
||||
----
|
||||
|
|
@ -753,8 +752,8 @@ Save your `pom.xml` and run `mvn package` from the command line:
|
|||
[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`:
|
||||
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]
|
||||
----
|
||||
|
|
@ -765,7 +764,7 @@ You should also see a much smaller file named `myproject-0.0.1-SNAPSHOT.jar.orig
|
|||
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:
|
||||
To run that application, use the `java -jar` command, as follows:
|
||||
|
||||
[indent=0,subs="attributes"]
|
||||
----
|
||||
|
|
@ -784,24 +783,24 @@ To run that application, use the `java -jar` command:
|
|||
........ Started Example in 2.536 seconds (JVM running for 2.864)
|
||||
----
|
||||
|
||||
As before, to gracefully exit the application hit `ctrl-c`.
|
||||
As before, to exit the application, press `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
|
||||
== 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 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
|
||||
"`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
|
||||
The http://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 don't need to build the rest to run
|
||||
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're really impatient, you could also jump ahead and read about
|
||||
you are really impatient, you could also jump ahead and read about
|
||||
_<<spring-boot-features.adoc#boot-features, Spring Boot features>>_.
|
||||
|
|
|
|||
Loading…
Reference in New Issue