diff --git a/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc b/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc index 724ab8e0fd..6c503eba99 100644 --- a/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc +++ b/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc @@ -4,7 +4,7 @@ [partintro] -- Spring Boot provides build tool plugins for Maven and Gradle. The plugins offer a -variety of features, including the packaging of executable jars. The section provides +variety of features, including the packaging of executable jars. This section provides more details on both plugins, as well as some help should you need to extend an unsupported build system. If you are just getting started, you might want to read ``<>'' from the @@ -155,9 +155,11 @@ The following configuration options are available for the `spring-boot:repackage |Name |Description |`classifier` -|Classifier to add to the artifact generated. If given, the artifact will be attached. If +|Classifier to add to the generated artifact. If given, the artifact will be attached. If this is not given, it will merely be written to the output directory according to the - `finalName`. + `finalName`. Attaching the artifact allows to deploy it alongside to the original one, + see http://maven.apache.org/plugins/maven-deploy-plugin/examples/deploying-with-classifiers.html[ + the maven documentation for more details] |`mainClass` |The name of the main class. If not specified will search for a single compiled class @@ -362,7 +364,7 @@ default) reloadable in the live application, which can be helpful at development [[build-tool-plugins-gradle-repackage-configuration]] === Repackage configuration The gradle plugin automatically extends your build script DSL with a `springBoot` element -for configuration. Simply set the appropriate properties as you would any other Gradle +for configuration. Simply set the appropriate properties as you would with any other Gradle extension (see below for a list of configuration options): [source,groovy,indent=0,subs="verbatim,attributes"] @@ -379,7 +381,7 @@ extension (see below for a list of configuration options): Sometimes it may be more appropriate to not package default dependencies resolved from `compile`, `runtime` and `provided` scopes. If the created executable jar file is intended to be run as it is, you need to have all dependencies nested inside it; -however, if the plan is to explode a jar file and run main class manually, you may already +however, if the plan is to explode a jar file and run the main class manually, you may already have some of the libraries available via `CLASSPATH`. This is a situation where you can repackage your jar with a different set of dependencies. diff --git a/spring-boot-docs/src/main/asciidoc/cloud-deployment.adoc b/spring-boot-docs/src/main/asciidoc/cloud-deployment.adoc index 1889793b48..b12af54fe5 100644 --- a/spring-boot-docs/src/main/asciidoc/cloud-deployment.adoc +++ b/spring-boot-docs/src/main/asciidoc/cloud-deployment.adoc @@ -102,7 +102,7 @@ information is exposed to the application as environment variables (for example: environment variables are language agnostic. Environment variables don't always make for the easiest API so Spring Boot automatically -extracts then and flattens the data into properties that can be accessed through +extracts them and flattens the data into properties that can be accessed through Spring's `Environment` abstraction: [source,java,indent=0] @@ -232,7 +232,7 @@ that covers the steps that you need to follow when deploying to CloudBees. == What to read next Check out the http://www.cloudfoundry.com/[Cloud Foundry], https://www.heroku.com/[Heroku] and http://www.cloudbees.com[CloudBees] web sites for more information about the kinds of -features that a PaaS can offer. These are just three of the more popular Java PaaS +features that a PaaS can offer. These are just three of the most popular Java PaaS providers, since Spring Boot is so amenable to cloud-based deployment you free to consider other providers as well. diff --git a/spring-boot-docs/src/main/asciidoc/getting-started.adoc b/spring-boot-docs/src/main/asciidoc/getting-started.adoc index f169dcf5a1..3ce630108d 100644 --- a/spring-boot-docs/src/main/asciidoc/getting-started.adoc +++ b/spring-boot-docs/src/main/asciidoc/getting-started.adoc @@ -469,8 +469,8 @@ that provides useful Maven defaults. It also provides a `dependency-management` 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 web application we will -add a `spring-boot-starter-web` dependency -- but before that, lets look at what we +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, lets look at what we currently have. [indent=0] @@ -486,7 +486,7 @@ currently have. ---- The `mvn dependency:tree` command prints tree representation of your project dependencies. -You can see that `spring-boot-starter-parent` has already provides some useful test +You can see that `spring-boot-starter-parent` has already provided some useful test dependencies. Lets edit our `pom.xml` and add the `spring-boot-starter-web` dependency just below the `parent` section: @@ -508,8 +508,8 @@ 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` so you need to create that folder structure, then add a file named -`src/main/java/Example.java`: +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] ---- diff --git a/spring-boot-docs/src/main/asciidoc/index.adoc b/spring-boot-docs/src/main/asciidoc/index.adoc index a0264a1542..bfffcc8548 100644 --- a/spring-boot-docs/src/main/asciidoc/index.adoc +++ b/spring-boot-docs/src/main/asciidoc/index.adoc @@ -23,6 +23,7 @@ Phillip Webb; Dave Syer; Josh Long; :dc-spring-boot-autoconfigure: {dc-root}/org/springframework/boot/autoconfigure :dc-spring-boot-actuator: {dc-root}/org/springframework/boot/actuate :spring-reference: http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle +:spring-javadoc: http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework :spring-data-javadoc: http://docs.spring.io/spring-data/jpa/docs/current/api/org/springframework/data/jpa :spring-data-commons-javadoc: http://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data :spring-data-mongo-javadoc: http://docs.spring.io/spring-data/mongodb/docs/current/api/org/springframework/data/mongodb diff --git a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc b/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc index e2bd1c0e57..89bce73904 100644 --- a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc @@ -13,8 +13,8 @@ Auditing, health and metrics gathering can be automatically applied to your appl [[production-ready-enabling]] == Enabling production-ready features. -The `spring-boot-actuator` project provides all of Spring Boot's production-ready -features. The simplist way to enable the features is to add a dependency to the +The `spring-boot-actuator` module provides all of Spring Boot's production-ready +features. The simplest way to enable the features is to add a dependency to the `spring-boot-starter-actuator` ``Starter POM''. .Definition of Actuator @@ -170,7 +170,7 @@ implementation that attempts a simple database test. [[production-ready-application-info]] === Custom application info information -You can customize the data exposed by the `info` endpoint by settings `info.*` Spring +You can customize the data exposed by the `info` endpoint by setting `info.*` Spring properties. All `Environment` properties under the info key will be automatically exposed. For example, you could add the following to your `application.properties`: @@ -244,7 +244,7 @@ for Gradle users, although a little more work is required to generate the proper [[production-ready-monitoring]] == Monitoring and management over HTTP If you are developing a Spring MVC application, Spring Boot Actuator will auto-configure -all non-sensitive endpoints to be exposed over HTTP. The default convention it to use the +all non-sensitive endpoints to be exposed over HTTP. The default convention is to use the `id` of the endpoint as the URL path. For example, `health` is exposed as `/health`. @@ -381,7 +381,7 @@ property to `false`: === Using Jolokia for JMX over HTTP Jolokia is a JMX-HTTP bridge giving an alternative method of accessing JMX beans. To use Jolokia, simply include a dependency to `org.jolokia:jolokia-core`. For example, -using Maven you you add the following: +using Maven you would add the following: [source,xml,indent=0] ---- @@ -415,7 +415,7 @@ If you are using Jolokia but you don't want Spring Boot to configure it, simply [source,properties,indent=0] ---- - jolokia.config.enabled=false + endpoints.jolokia.enabled=false ---- @@ -511,7 +511,8 @@ Here is a simple ``hello world'' command that could be loaded from ---- package commands - import org.springframework.boot.actuate.endpoint.BeansEndpoint + import org.crsh.cli.Usage + import org.crsh.cli.Command class hello { @@ -621,7 +622,7 @@ Here is a simple example that counts the number of times that a method is invoke } ---- -TIP: You can use any string as a metric name but you following guidelines of your chosen +TIP: You can use any string as a metric name but you should follow guidelines of your chosen store/graphing technology. Some good guidelines for Graphite are available on http://matt.aimonetti.net/posts/2013/06/26/practical-guide-to-graphite-monitoring/[Matt Aimonetti's Blog]. @@ -678,7 +679,7 @@ use that directly, or you can simply publish `AuditApplicationEvent` via the Spr [[production-ready-tracing]] == Tracing -Tracing is automatically enable for all HTTP requests. You can view the `trace` endpoint +Tracing is automatically enabled for all HTTP requests. You can view the `trace` endpoint and obtain basic information about the last few requests: [source,json,indent=0] diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index d0823c5691..616f30ba5c 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -25,7 +25,7 @@ the static `SpringApplication.run` method: } ---- -When you application starts you should see something similar to the following: +When your application starts you should see something similar to the following: [indent=0,subs="attributes"] ---- @@ -43,7 +43,7 @@ When you application starts you should see something similar to the following: 2014-03-04 13:09:56.501 INFO 41370 --- [ main] o.s.b.s.app.SampleApplication : Started SampleApplication in 2.992 seconds (JVM running for 3.658) ---- -By default `INFO` logging messages will shown, including some relevant startup details +By default `INFO` logging messages will be shown, including some relevant startup details such as the user that launched the application. @@ -103,8 +103,9 @@ context, otherwise there is no way for Spring Boot to create the `ServletContext [[boot-features-application-events-and-listeners]] === Application events and listeners -In addition to the usual Spring Framework events, such as `ContextRefreshedEvent`, a -`SpringApplication` sends some additional application events. Some events are actually +In addition to the usual Spring Framework events, such as +{spring-javadoc}/context/event/ContextRefreshedEvent.{dc-ext}[`ContextRefreshedEvent`], +a `SpringApplication` sends some additional application events. Some events are actually triggered before the `ApplicationContext` is created. You can register event listeners in a number of ways, the most common being @@ -139,7 +140,7 @@ you need to override the default. It is also possible to take complete control of the `ApplicationContext` type that will be used by calling `setApplicationContextClass(...)`. -TIP: It is often desirable call `setWebEnvironment(false)` when using `SpringApplication` +TIP: It is often desirable to call `setWebEnvironment(false)` when using `SpringApplication` within a JUnit test. @@ -255,7 +256,8 @@ following locations and add them to the Spring `Environment`: The list is ordered by precedence (locations higher in the list override lower items). -NOTE: You can also use YAML ('.yml') files as an alternative to '.properties' (see below) +NOTE: You can also <> as +an alternative to '.properties'. If you don't like `application.properties` as the configuration file name you can switch to another by specifying a `spring.config.name` environment property. You can also refer @@ -596,7 +598,7 @@ Logback routing is also included to ensure that dependent libraries that use Java Util Logging, Commons Logging, Log4J or SLF4J will all work correctly. TIP: There are a lot of logging frameworks available for Java. Don't worry if the above -list seems confusing, generally you won't need to change your logging dependencues and +list seems confusing, generally you won't need to change your logging dependencies and the Spring Boot defaults will work just fine. @@ -966,9 +968,9 @@ you can see how to set things up. [[boot-features-sql]] == Working with SQL databases The Spring Framework provides extensive support for working with SQL databases. From -direct JDBC access using `JdbcTemplate` though to complete ``object relational mapping'' +direct JDBC access using `JdbcTemplate` to complete ``object relational mapping'' technologies such as Hibernate. Spring Data provides an additional level of functionality, -creating `Repoistory` implementations directly from interfaces and using conventions to +creating `Repository` implementations directly from interfaces and using conventions to generate queries from your method names. @@ -983,7 +985,7 @@ credentials to establish a database connection. [[boot-features-embedded-database-support]] ==== Embedded Database Support -It's often convenient develop applications using an in-memory embedded database. +It's often convenient to develop applications using an in-memory embedded database. Obviously, in-memory databases do not provide persistent storage; you will need to populate your database when your application starts and be prepared to throw away data when your application ends. @@ -1161,7 +1163,7 @@ how-to. [[boot-features-spring-data-jpa-repositories]] ==== Spring Data JPA Repositories Spring Data JPA repositories are interfaces that you can define to access data. JPA -queries are created automatically from your method names. For example, a `CityRepoistory` +queries are created automatically from your method names. For example, a `CityRepository` interface might declare a `findAllByState(String state)` method to find all cities in a given state. @@ -1222,7 +1224,7 @@ http://projects.spring.io/spring-data-gemfire/[Gemfire], http://projects.spring.io/spring-data-couchbase/[Couchbase] and http://projects.spring.io/spring-data-cassandra/[Cassandra]. Spring Boot provides auto-configuration for MongoDB; you can make use of the other -project, but you will need to configure them yourself. Refer to the appropriate +projects, but you will need to configure them yourself. Refer to the appropriate reference documentation at http://projects.spring.io/spring-data. @@ -1316,7 +1318,7 @@ See the `MongoOperations` Javadoc for complete details. [[boot-features-spring-data-mongo-repositories]] ==== Spring Data MongoDB repositories Spring Data includes repository support for MongoDB. As with the JPA repositories -discussed earlier, the basic principal is that queries are constructed for you +discussed earlier, the basic principle is that queries are constructed for you automatically based on method names. In fact, both Spring Data JPA and Spring Data MongoDB share the same common @@ -1439,7 +1441,7 @@ useful when testing your application. ==== ConfigFileApplicationContextInitializer `ConfigFileApplicationContextInitializer` is an `ApplicationContextInitializer` that can apply to your tests to load Spring Boot `application.properties` files. You can use -when you don't need the full features provided by `@SpringApplicationConfiguration`. +this when you don't need the full features provided by `@SpringApplicationConfiguration`. [source,java,indent=0] ---- @@ -1572,15 +1574,15 @@ when searching for beans. NOTE: `@Conditional` annotations are processed when `@Configuration` classes are parsed. Auto-configure `@Configuration` is always parsed last (after any user defined beans), however, if you are using these annotations on regular `@Configuration` classes, -care must be take not to refer to bean definitions that have not yet been created. +care must be taken not to refer to bean definitions that have not yet been created. [[boot-features-resource-conditions]] ==== Resource conditions -The `@ConditionalOnResource` annotation allows configuration to be skipped when a specific -resource is not present. Resources can be specified using the usual Spring conventions, -for example, `file:/home/user/test.dat`. +The `@ConditionalOnResource` annotation allows configuration to be included only when a +specific resource is present. Resources can be specified using the usual Spring +conventions, for example, `file:/home/user/test.dat`. diff --git a/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc b/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc index 70be2bee11..84842e9abf 100644 --- a/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc +++ b/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc @@ -131,7 +131,7 @@ want to change the settings defined in the parent. [[using-boot-gradle]] === Gradle Gradle users can directly import ``starter POMs'' in their `dependencies` section. Unlike -Maven, there is no ``super parent'' to import. +Maven, there is no ``super parent'' to import to share some configuration. [source,groovy,indent=0,subs="attributes"] ---- @@ -284,7 +284,7 @@ swap specific technical facets. |Imports the Jetty HTTP engine (to be used as an alternative to Tomcat) |`spring-boot-starter-log4j` -|Support the Log4J looggin framework +|Support the Log4J logging framework |`spring-boot-starter-logging` |Import Spring Boot's default logging framework (Logback). @@ -310,7 +310,7 @@ should be avoided. It can cause particular problems for Spring Boot applications use `@ComponentScan` or `@EntityScan` annotations, since every class from every jar, will be read. -TIP: We recommend that you use the follow Java's recommended package naming conventions +TIP: We recommend that you follow Java's recommended package naming conventions and use a reversed domain name (for example, `com.example.project`). @@ -450,13 +450,13 @@ you can use the exclude attribute of `@EnableAutoConfiguration` to disable them. [[using-boot-spring-beans-and-dependency-injection]] == Spring Beans and dependency injection -You are free to use any the standard Spring Framework techniques to defines your beans +You are free to use any of the standard Spring Framework techniques to define your beans and their injected dependencies. For simplicity, we often find that using `@ComponentScan` to find your beans, in combination with `@Autowired` constructor injection works well. If you structure your code as suggested above (locating your application class in a root package), you can add `@ComponentScan` without any arguments. All of your application -components (`@Component`, `@Service`, `@Repoistory`, `@Controller` etc.) will be +components (`@Component`, `@Service`, `@Repository`, `@Controller` etc.) will be automatically registered as Spring Beans. Here is an example `@Service` Bean that uses constructor injection to obtain a