diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/getting-started.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/getting-started.adoc index 57307638a7..321ad6da09 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/getting-started.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/getting-started.adoc @@ -4,19 +4,20 @@ [partintro] -- If you are getting started with Spring Boot, or "Spring" in general, start by reading -this section. It answers the basic "`what?`", "`how?`" and "`why?`" questions. It includes -an introduction to Spring Boot, along with installation instructions. -We then walk you through building your first Spring Boot application, discussing some core +this section. It answers the basic "`what?`", "`how?`" and "`why?`" questions. It +includes an introduction to Spring Boot, along with installation instructions. We then +walk you through building your first Spring Boot application, discussing some core principles as we go. -- + [[getting-started-introducing-spring-boot]] == Introducing Spring Boot Spring Boot makes it easy to create stand-alone, production-grade Spring based -Applications that you can run. We take an opinionated view of the Spring -platform and third-party libraries, so that you can get started with minimum fuss. Most -Spring Boot applications need very little Spring configuration. +Applications that you can run. We take an opinionated view of the Spring platform and +third-party libraries, so that you can get started with minimum fuss. Most Spring Boot +applications need very little Spring configuration. You can use Spring Boot to create Java applications that can be started by using `java -jar` or more traditional war deployments. We also provide a command line tool that @@ -38,8 +39,9 @@ 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 4. +Framework {spring-version} or above. Explicit build support is provided for Maven 3.2+ +and Gradle 4. + [[getting-started-system-requirements-servlet-containers]] @@ -74,8 +76,8 @@ begin, you should check your current Java installation by using the following co $ java -version ---- -If you are new to Java development or if you want to experiment with Spring Boot, -you might want to try the <> (Command +If you are new to Java development or if you want to experiment with Spring Boot, you +might want to try the <> (Command Line Interface) first, otherwise, read on for "`classic`" installation instructions. @@ -85,28 +87,28 @@ Line Interface) first, otherwise, read on for "`classic`" installation instructi You can use Spring Boot in the same way as any standard Java library. To do so, include the appropriate `+spring-boot-*.jar+` files on your classpath. Spring Boot does not require any special tools integration, so you can use any IDE or text editor. Also, there -is nothing special about a Spring Boot application, so you can run and debug a Spring Boot -application as you would any other Java program. +is nothing special about a Spring Boot application, so you can run and debug a Spring +Boot application as you would any other Java program. -Although you _could_ copy Spring Boot jars, we generally recommend that you use a -build tool that supports dependency management (such as Maven or Gradle). +Although you _could_ copy Spring Boot jars, we generally recommend that you use a build +tool that supports dependency management (such as Maven or Gradle). [[getting-started-maven-installation]] ==== Maven Installation -Spring Boot is compatible with Apache Maven 3.2 or above. If you do not already have Maven -installed, you can follow the instructions at http://maven.apache.org. +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 with a package manager. If you -use OSX Homebrew, 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 (administrator) prompt. Spring Boot dependencies use the `org.springframework.boot` `groupId`. Typically, your Maven POM file inherits from the `spring-boot-starter-parent` project and declares -dependencies to one or more <>. Spring Boot also provides an optional +dependencies to one or more <>. +Spring Boot also provides an optional <> to create executable jars. @@ -176,9 +178,9 @@ 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 not like our default settings. In those cases, see +TIP: The `spring-boot-starter-parent` is a great way to use Spring Boot, but it might not +be suitable all of the time. Sometimes you may need to inherit from a different parent +POM, or you might not like our default settings. In those cases, see <> for an alternative solution that uses an `import` scope. @@ -199,11 +201,11 @@ jars. .Gradle Wrapper **** The Gradle Wrapper provides a nice way of "`obtaining`" Gradle when you need to build a -project. It is a small script and library that you commit alongside your code to bootstrap -the build process. See {gradle-user-guide}/gradle_wrapper.html for details. +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. **** -Here is a typical `build.gradle` file: +The following example shows a typical `build.gradle` file: [source,groovy,indent=0,subs="verbatim,attributes"] ---- @@ -257,8 +259,8 @@ The Spring Boot CLI (Command Line Interface) is a command line tool that you can quickly prototype with Spring. It lets you run http://groovy-lang.org/[Groovy] scripts, which means that you have a familiar Java-like syntax without so much boilerplate code. -You do not need to use the CLI to work with Spring Boot, but it is definitely the quickest -way to get a Spring application off the ground. +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. @@ -269,10 +271,12 @@ 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 +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-project/spring-boot-cli/src/main/content/INSTALL.txt[INSTALL.txt] +Once downloaded, follow the +{github-raw}/spring-boot-project/spring-boot-cli/src/main/content/INSTALL.txt[INSTALL.txt] instructions from the unpacked archive. In summary, there is a `spring` script (`spring.bat` for Windows) in a `bin/` directory in the `.zip` file. Alternatively, you can use `java -jar` with the `.jar` file (the script helps you to be sure that the @@ -282,9 +286,10 @@ classpath is set correctly). [[getting-started-sdkman-cli-installation]] ==== Installation with SDKMAN! -SDKMAN! (The Software Development Kit Manager) can be used for managing multiple versions of -various binary SDKs, including Groovy and the Spring Boot CLI. -Get SDKMAN! from http://sdkman.io and install Spring Boot by using the following commands: +SDKMAN! (The Software Development Kit Manager) can be used for managing multiple versions +of various binary SDKs, including Groovy and the Spring Boot CLI. +Get SDKMAN! from http://sdkman.io and install Spring Boot by using the following +commands: [indent=0,subs="verbatim,quotes,attributes"] ---- @@ -293,8 +298,8 @@ Get SDKMAN! from http://sdkman.io and install Spring Boot by using the following Spring Boot v{spring-boot-version} ---- -If you are developing features for the CLI and want easy access to the version you -built, use the following commands: +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"] ---- @@ -304,9 +309,9 @@ built, use the following commands: Spring CLI v{spring-boot-version} ---- -The preceding instructions install a local instance of `spring` called the `dev` instance. -It points at your target build location, so every time you rebuild Spring -Boot, `spring` is up-to-date. +The preceding instructions install a local instance of `spring` called the `dev` +instance. It points at your target build location, so every time you rebuild Spring Boot, +`spring` is up-to-date. You can see it by running the following command: @@ -331,8 +336,8 @@ You can see it by running the following command: [[getting-started-homebrew-cli-installation]] ==== OSX Homebrew Installation -If you are on a Mac and use http://brew.sh/[Homebrew], you can install -the Spring Boot CLI by using the following commands: +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] ---- @@ -342,15 +347,15 @@ the Spring Boot CLI by using the following commands: Homebrew installs `spring` to `/usr/local/bin`. -NOTE: If you do not see the formula, your installation of brew might be out-of-date. -In that case, run `brew update` and try again. +NOTE: If you do not see the formula, your installation of brew might be out-of-date. In +that case, run `brew update` and try again. [[getting-started-macports-cli-installation]] ==== MacPorts Installation -If you are on a Mac and use http://www.macports.org/[MacPorts], you can -install the Spring Boot CLI by using the following command: +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] ---- @@ -361,8 +366,8 @@ install the Spring Boot CLI by using the following command: [[getting-started-cli-command-line-completion]] ==== 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 +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 @@ -384,8 +389,8 @@ completion scripts are automatically registered with your shell. [[getting-started-cli-example]] ==== Quick-start Spring CLI Example -You can use the following web application to test your installation. To start, create -a file called `app.groovy`, as follows: +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"] ---- @@ -407,8 +412,8 @@ Then run it from a shell, as follows: $ spring run app.groovy ---- -NOTE: The first run of your application is slow, as dependencies are -downloaded. Subsequent runs are 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. You should see the following output: @@ -423,13 +428,13 @@ output: [[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. +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 -<> remembering to -update your `PATH` environment variable to remove any older references. +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 +<> remembering to update +your `PATH` environment variable to remove any older references. @@ -441,14 +446,15 @@ most IDEs support it. [TIP] ==== -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. +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. Doing so generates a new -project structure so that you can <>. Check the https://github.com/spring-io/initializr[Spring Initializr -documentation] for more details. +"Web" starter from the dependencies searcher. Doing so generates a new project structure +so that you can <>. Check +the https://github.com/spring-io/initializr[Spring Initializr documentation] for more +details. ==== Before we begin, open a terminal and run the following commands to ensure that you have @@ -477,8 +483,8 @@ that you have created a suitable folder and that it is your "`current directory` [[getting-started-first-application-pom]] === Creating the POM -We need to start by creating a Maven `pom.xml` file. The `pom.xml` is the recipe that -is used to build your project. Open your favorite text editor and add the following: +We need to start by creating a Maven `pom.xml` file. The `pom.xml` is the recipe that is +used to build your project. Open your favorite text editor and add the following: [source,xml,indent=0,subs="verbatim,quotes,attributes"] ---- @@ -526,29 +532,29 @@ endif::[] ---- -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 +The preceding listing should give you a working build. You can test it by running `mvn +package` (for now, you can ignore the "`jar will be empty - no content was marked for inclusion!`" warning). NOTE: At this point, you could import the project into an IDE (most modern Java IDEs -include built-in support for Maven). For simplicity, we continue to use a plain -text editor for this example. +include built-in support for Maven). For simplicity, we continue to use a plain text +editor for this example. [[getting-started-first-application-dependencies]] === Adding Classpath Dependencies -Spring Boot provides a number of "`Starters`" that let you add jars to your -classpath. Our sample application has already used `spring-boot-starter-parent` in the -`parent` section of the POM. The `spring-boot-starter-parent` is a special starter -that provides useful Maven defaults. It also provides a +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 <> section so that you can omit `version` tags for "`blessed`" dependencies. -Other "`Starters`" provide dependencies that you are likely to need when -developing a specific type of application. Since we are developing a web application, we -add a `spring-boot-starter-web` dependency. Before that, we can look at what we -currently have by running the following command: +Other "`Starters`" provide dependencies that you are likely to need when developing a +specific type of application. Since we are developing a web application, we add a +`spring-boot-starter-web` dependency. Before that, we can look at what we currently have +by running the following command: [indent=0] ---- @@ -558,8 +564,8 @@ currently have by running the following command: ---- The `mvn dependency:tree` command prints a tree representation of your project -dependencies. You can see that `spring-boot-starter-parent` provides no -dependencies by itself. To add the necessary dependencies, edit your `pom.xml` and add the +dependencies. You can see that `spring-boot-starter-parent` provides no dependencies by +itself. To add the necessary dependencies, edit your `pom.xml` and add the `spring-boot-starter-web` dependency immediately below the `parent` section: [source,xml,indent=0,subs="verbatim,quotes,attributes"] @@ -572,8 +578,8 @@ dependencies by itself. To add the necessary dependencies, edit your `pom.xml` a ---- -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. +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. @@ -617,10 +623,10 @@ _stereotype_ annotation. It provides hints for people reading the code and for S that the class plays a specific role. In this case, our class is a web `@Controller`, so Spring considers it when handling incoming web requests. -The `@RequestMapping` annotation provides "`routing`" information. It tells Spring -that any HTTP request with the `/` path should be mapped to the `home` method. The -`@RestController` annotation tells Spring to render the resulting string directly -back to the caller. +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 @@ -631,15 +637,15 @@ section] in the Spring Reference Documentation for more details. [[getting-started-first-application-auto-configuration]] ==== The @EnableAutoConfiguration Annotation The second class-level annotation is `@EnableAutoConfiguration`. This annotation tells -Spring Boot to "`guess`" how you want to configure Spring, based on the jar -dependencies that you have added. Since `spring-boot-starter-web` added Tomcat and -Spring MVC, the auto-configuration assumes that you are developing a web application -and sets up Spring accordingly. +Spring Boot to "`guess`" how you want to configure Spring, based on the jar dependencies +that you have added. Since `spring-boot-starter-web` added Tomcat and Spring MVC, the +auto-configuration assumes that you are developing a web application and sets up Spring +accordingly. .Starters and Auto-Configuration **** -Auto-configuration is designed to work well with "`Starters`", but the two concepts -are not directly tied. You are free to pick-and-choose jar dependencies outside of the +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 still does its best to auto-configure your application. **** @@ -648,12 +654,12 @@ starters and Spring Boot still does its best to auto-configure your application. [[getting-started-first-application-main-method]] ==== The "`main`" Method The final part of our application is the `main` method. This is just a standard method -that follows the Java convention for an application entry point. Our main method delegates -to Spring Boot's `SpringApplication` class by calling `run`. `SpringApplication` -bootstraps our application, starting Spring, which, in turn, starts the auto-configured -Tomcat web server. We need to pass `Example.class` as an argument to the `run` method to -tell `SpringApplication` which is the primary Spring component. The `args` array is also -passed through to expose any command-line arguments. +that follows the Java convention for an application entry point. Our main method +delegates to Spring Boot's `SpringApplication` class by calling `run`. +`SpringApplication` bootstraps our application, starting Spring, which, in turn, starts +the auto-configured Tomcat web server. We need to pass `Example.class` as an argument to +the `run` method to tell `SpringApplication` which is the primary Spring component. The +`args` array is also passed through to expose any command-line arguments. @@ -705,10 +711,10 @@ Java does not provide a standard way to load nested jar files (jar files that ar themselves contained within a jar). This can be problematic if you are looking to distribute a self-contained application. -To solve this problem, many developers use "`uber`" jars. An uber jar packages -all the classes from all the application's dependencies into a single archive. The problem -with this approach is that it becomes hard to see which libraries are in your application. -It can also be problematic if the same filename is used (but with different content) in +To solve this problem, many developers use "`uber`" jars. An uber jar packages all the +classes from all the application's dependencies into a single archive. The problem with +this approach is that it becomes hard to see which libraries are in your application. It +can also be problematic if the same filename is used (but with different content) in multiple jars. Spring Boot takes a < ---- -NOTE: The `spring-boot-starter-parent` POM includes `` configuration to -bind the `repackage` goal. If you do not use the parent POM, you need to declare -this configuration yourself. See the {spring-boot-maven-plugin-site}/usage.html[plugin +NOTE: The `spring-boot-starter-parent` POM includes `` configuration to bind +the `repackage` goal. If you do not use the parent POM, you need to declare this +configuration yourself. See the {spring-boot-maven-plugin-site}/usage.html[plugin documentation] for details. Save your `pom.xml` and run `mvn package` from the command line, as follows: @@ -757,16 +763,16 @@ Save your `pom.xml` and run `mvn package` from the command line, as follows: ---- 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: +file should be around 10 MB in size. If you want to peek inside, you can use `jar tvf`, +as follows: [indent=0] ---- $ jar tvf target/myproject-0.0.1-SNAPSHOT.jar ---- -You should also see a much smaller file named `myproject-0.0.1-SNAPSHOT.jar.original` -in the `target` directory. This is the original jar file that Maven created before it was +You should also see a much smaller file named `myproject-0.0.1-SNAPSHOT.jar.original` in +the `target` directory. This is the original jar file that Maven created before it was repackaged by Spring Boot. To run that application, use the `java -jar` command, as follows: @@ -794,17 +800,17 @@ As before, to exit the application, press `ctrl-c`. [[getting-started-whats-next]] == What to Read Next -Hopefully, this section provided some of the Spring Boot basics and got you -on your way to writing your own applications. If you are a task-oriented type of -developer, you might want to jump over to 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 -_<>_ reference documentation. +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 +"`<>`" reference documentation. 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 do not need to build the rest to run -or use the samples). +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 _<>_. If you are really impatient, you could also jump ahead and read about