Polish documentation

spring-boot-docs/src/main/asciidoc/deployment.adoc

@@ -14,7 +14,6 @@ This section covers some of the more common deployment scenarios.
 
 [[cloud-deployment]]
 == Deploying to the cloud
-
 Spring Boot's executable jars are ready-made for most popular cloud PaaS
 (platform-as-a-service) providers. These providers tend to require that you
 "`bring your own container`"; they manage application processes (not Java applications
@@ -302,6 +301,7 @@ there without some modifications. See the <<howto.adoc#howto-servlet-2-5, Servle
 of this guide.
 
 
+
 [[deployment-service]]
 == Installing Spring Boot applications
 In additional to running Spring Boot applications using `java -jar` it is also possible
@@ -347,33 +347,47 @@ if you use Debian:
 	$ update-rc.d myapp defaults <priority>
 ----
 
+
+
 === Running a JAR as a regular (not service) script
+The script accepts the following parameters as environment variables, so you can change
+the default behavior in a script or on the command line:
+
+[cols="1,6"]
+|===
+|Variable |Description
 
-The script accepts the following parameters as environment variables, so you can change the
-default behaviour in a script or on the command line:
+|`MODE`
+|The "mode" of operation. The default depends on the way the jar was built, but will
+ usually be "auto" (meaning it tries to guess if it is an init script by checking if it
+ is a symlink in a directory called "init.d"). You can explicitly set it to "service" so
+ that the "stop|start|status|restart" commands work, or to "run" if you just want to run
+ the script and not in the background.
 
-* `MODE` - the "mode" of operation. The default depends on the way the jar was built, but
-will usually be "auto" (meaning it tries to guess if it is an init script by checking if
-it is a symlink in a directory called "init.d"). You can explicitly set it to "service"
-so that the "stop|start|status|restart" commands work, or to "run" if you just want to
-run the script and not in the background.
+|`PID_FOLDER`
+|The root name of the pid folder (`/var/run` by default).
 
-* `PID_FOLDER` - the root name of the pid folder (`/var/run` by default).
+|`LOG_FOLDER`
+|The name of the folder to put log files in (`/var/log` by default).
 
-* `LOG_FOLDER` - the name of the folder to put log files in (`/var/log` by default).
+|`APP_NAME`
+|The name of the app. If the jar is run from a symlink the script guesses the app name,
+ but if it is not a symlink, or you want to explicitly set the app name this can be
+ useful.
 
-* `APP_NAME` - the name of the app. If the jar is run from a symlink the script guesses the 
-app name, but if it is not a symlink, or you want to explicitly set the app name this can be
-useful.
+|`JAVA_HOME`
+|The location of the `java` executable is discovered by using the `PATH` by default, but
+ you can set it explicitly if there is an executable file at `$JAVA_HOME/bin/java`.
 
-* `JAVA_HOME` - the location of the `java` executable is discovered by using the `PATH` by 
-default, but you can set it explicitly if there is an executable file at `$JAVA_HOME/bin/java`.
+|`JARFILE`
+|The explicit location of the jar file, in case the script is being used to launch a jar
+ that it is not actually embedded in.
 
-* `JARFILE` - the explicit location of the jar file, in case the script is being used to launch
-a jar that it is not actually embedded in.
+|`DEBUG`
+|if not empty will set the `-x` flag on the shell process, making it easy to see the logic
+ in the script.
+|===
 
-* `DEBUG` - if not empty will set the `-x` flag on the shell process, making it easy to
-see the logic in the script.
 
 
 ==== Installation as a systemd service

spring-boot-docs/src/main/asciidoc/howto.adoc

@@ -156,6 +156,8 @@ The actual application will _not_ show the banner and use three sources for the
 `ApplicationContext` (in that order): `demo.MyApp`, `com.acme.Config`,
 `com.acme.ExtraConfig`.
 
+
+
 [[howto-change-the-location-of-external-properties]]
 === Change the location of external properties of an application
 By default properties from different sources are added to the Spring `Environment` in a

spring-boot-docs/src/main/asciidoc/production-ready-features.adoc

@@ -832,6 +832,8 @@ for all supported data sources; you can add additional `DataSourcePoolMetadataPr
 beans if your favorite data source isn't supported out of the box. See
 `DataSourcePoolMetadataProvidersConfiguration` for examples.
 
+
+
 [[production-ready-datasource-cache]]
 === Cache metrics
 The following metrics are exposed for each supported cache defined in your application:
@@ -910,9 +912,9 @@ beans are gathered by the endpoint. You can easily change that by defining your
 `MetricsEndpoint`.
 
 
+
 [[production-ready-metric-repositories]]
 === Special features with Java 8
-
 The default implementation of `GaugeService` and `CounterService` provided by Spring Boot
 depends on the version of Java that you are using. With Java 8 (or better) the
 implementation switches to a high-performance version optimized for fast writes, backed by
@@ -932,51 +934,42 @@ used by default if you are on Java 8 or if you are using Dropwizard metrics.
 
 [[production-ready-metric-writers]]
 === Metric writers, exporters and aggregation
-
-Spring Boot provides a couple of implementations of a marker interface
-called `Exporter` which can be used to copy metric readings from the
-in-memory buffers to a place where they can be analysed and
-displayed. Indeed, if you provide a `@Bean` that implements the
-`MetricWriter` interface and mark it `@ExportMetricWriter`, then it
-will automatically be hooked up to an `Exporter` and fed metric
-updates every 5 seconds (configured via
+Spring Boot provides a couple of implementations of a marker interface called `Exporter`
+which can be used to copy metric readings from the in-memory buffers to a place where they
+can be analyzed and displayed. Indeed, if you provide a `@Bean` that implements the
+`MetricWriter` interface and mark it `@ExportMetricWriter`, then it will automatically be
+hooked up to an `Exporter` and fed metric updates every 5 seconds (configured via
 `spring.metrics.export.delayMillis`) via a `@Scheduled` annotation in
-`MetricRepositoryAutoConfiguration`. In addition, any `MetricReader`
-that you define and mark as `@ExportMetricReader` will have its values
-exported by the default exporter.
+`MetricRepositoryAutoConfiguration`. In addition, any `MetricReader` that you define and
+mark as `@ExportMetricReader` will have its values exported by the default exporter.
 
 
-The default exporter is a `MetricCopyExporter` which tries to optimize
-itself by not copying values that haven't changed since it was last
-called (the optimization can be switched off using a flag
-`spring.metrics.export.sendLatest`). Note also that the Dropwizard
-`MetricRegistry` has no support for timestamps, so the optimization is
-not available if you are using Dropwizard metrics (all metrics will be
-copied on every tick).
+The default exporter is a `MetricCopyExporter` which tries to optimize itself by not
+copying values that haven't changed since it was last called (the optimization can be
+switched off using a flag `spring.metrics.export.sendLatest`). Note also that the
+Dropwizard `MetricRegistry` has no support for timestamps, so the optimization is not
+available if you are using Dropwizard metrics (all metrics will be copied on every tick).
 
-The default values for the export trigger (`delayMillis`, `includes`,
-`excludes`, `ignoreTimestamps` and `sendLatest`) can be set as
-`spring.metrics.export.\*`. Individual values for specific
-`MetricWriters` can be set as
-`spring.metrics.export.triggers.<name>.*` where `<name>` is a bean
-name (or pattern for matching bean names).
+The default values for the export trigger (`delayMillis`, `includes`, `excludes`,
+`ignoreTimestamps` and `sendLatest`) can be set as `spring.metrics.export.\*`. Individual
+values for specific `MetricWriters` can be set as
+`spring.metrics.export.triggers.<name>.*` where `<name>` is a bean name (or pattern for
+matching bean names).
 
 
 
 [[production-ready-metric-writers-export-to-redis]]
 ==== Example: Export to Redis
+If you provide a `@Bean` of type `RedisMetricRepository` and mark it `@ExportMetricWriter`
+the metrics are exported to a Redis cache for aggregation. The `RedisMetricRepository` has
+two important parameters to configure it for this purpose: `prefix` and `key` (passed into
+its constructor). It is best to use a prefix that is unique to the application instance
+(e.g. using a random value and maybe the logical name of the application to make it
+possible to correlate with other instances of the same application).  The "key" is used to
+keep a global index of all metric names, so it should be unique "globally", whatever that
+means for your system (e.g.  2 instances of the same system could share a Redis cache if
+they have distinct keys).
 
-If you provide a `@Bean` of type `RedisMetricRepository` and mark it
-`@ExportMetricWriter` the metrics are exported to a Redis cache for
-aggregation. The `RedisMetricRepository` has 2 important parameters to
-configure it for this purpose: `prefix` and `key` (passed into its
-constructor). It is best to use a prefix that is unique to the
-application instance (e.g. using a random value and maybe the logical
-name of the application to make it possible to correlate with other
-instances of the same application).  The "key" is used to keep a
-global index of all metric names, so it should be unique "globally",
-whatever that means for your system (e.g.  2 instances of the same
-system could share a Redis cache if they have distinct keys).
 Example:
 
 [source,java,indent=0]
@@ -984,7 +977,7 @@ Example:
 @Bean
 @ExportMetricWriter
 MetricWriter metricWriter(MetricExportProperties export) {
-	return new RedisMetricRepository(connectionFactory, 
+	return new RedisMetricRepository(connectionFactory,
       export.getRedis().getPrefix(), export.getRedis().getKey());
 }
 ----
@@ -1008,30 +1001,27 @@ start with the master prefix (like `metrics.mysystem.*` in the example above). I
 efficient to read all the keys from a "master" repository like that, but inefficient to
 read a subset with a longer prefix (e.g. using one of the writing repositories).
 
-NOTE: the example above uses `MetricExportProperties` to inject and
-extract the key and prefix. This is provided to you as a convenience
-by Spring Boot, and the defaults for that will be sensible, but there
-is nothing to stop you using your own values as long as they follow
-the recommendations.
+NOTE: the example above uses `MetricExportProperties` to inject and extract the key and
+prefix. This is provided to you as a convenience by Spring Boot, and the defaults for that
+will be sensible, but there is nothing to stop you using your own values as long as they
+follow the recommendations.
+
 
 
 [[production-ready-metric-writers-export-to-open-tdsb]]
 ==== Example: Export to Open TSDB
+If you provide a `@Bean` of type `OpenTsdbHttpMetricWriter` and mark it
+`@ExportMetricWriter` the metrics are exported to http://opentsdb.net/[Open TSDB] for
+aggregation. The `OpenTsdbHttpMetricWriter` has a `url` property that you need to set
+to the Open TSDB "/put" endpoint, e.g. `http://localhost:4242/api/put`). It also has a
+`namingStrategy` that you can customize or configure to make the metrics match the data
+structure you need on the server. By default it just passes through the metric name as an
+Open TSDB metric name and adds a tag "domain" with value "org.springframework.metrics" and
+another tag "process" with value equals to the object hash of the naming strategy. Thus,
+after running the application and generating some metrics (e.g. by pinging the home page)
+you can inspect the metrics in the TDB UI (http://localhost:4242 by default).
 
-If you provide a `@Bean` of type `OpenTsdbHttpMetricWriter` and mark
-it `@ExportMetricWriter` the metrics are exported to
-http://opentsdb.net/[Open TSDB] for aggregation. The
-`OpenTsdbHttpMetricWriter` has a `url` property that you need to set
-to the Open TSDB "/put" endpoint, e.g.
-`http://localhost:4242/api/put`). It also has a `namingStrategy` that
-you can customize or configure to make the metrics match the data
-structure you need on the server. By default it just passes through
-the metric name as an Open TSDB metric name and adds a tag "domain"
-with value "org.springframework.metrics" and another tag "process"
-with value equals to the object hash of the naming strategy. Thus,
-after running the application and generating some metrics (e.g. by
-pinging the home page) you can inspect the metrics in the TDB UI
-(http://localhost:4242 by default). Example:
+Example:
 
 [source,indent=0]
 ----
@@ -1145,6 +1135,7 @@ NOTE: the `MetricReaders` above are not `@Beans` and are not marked as
 data from other repositories, and don't want to export their values.
 
 
+
 [[production-ready-dropwizard-metrics]]
 === Dropwizard Metrics
 A default `MetricRegistry` Spring bean will be created when you declare a dependency to
@@ -1239,6 +1230,7 @@ the capacity. You can also create your own alternative `TraceRepository` impleme
 if needed.
 
 
+
 [[production-ready-process-monitoring]]
 == Process monitoring
 In Spring Boot Actuator you can find a couple of classes to create files that are useful

spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc

@@ -1462,14 +1462,16 @@ All of the above can be switched on and off or modified using external propertie
 features add a `@Bean` of type `WebSecurityConfigurerAdapter` with
 `@Order(SecurityProperties.ACCESS_OVERRIDE_ORDER)`.
 
-=== OAuth2
 
+
+=== OAuth2
 If you have `spring-security-oauth2` on your classpath you can take advantage of some
 autoconfiguration to make it easy to set up Authorization or Resource Server features by
 configuring some property values in the `Environment`.
 
-==== Authorization Server
 
+
+==== Authorization Server
 To create an Authorization Server and grant access tokens you need to
 `@EnableAuthorizationServer` and provide
 `spring.oauth2.client.[clientId,clientSecret]`. The client will be
@@ -1490,8 +1492,9 @@ To switch off the autoconfiguration and configure the Authorization
 Server features yourself just add a `@Bean` of type
 `AuthorizationServerConfigurer`.
 
-==== Resource Server
 
+
+==== Resource Server
 To use the access token you need a Resource Server (which can be the
 same as the Authorization Server). Creating a Resource Server is easy:
 just add `@EnableResourceServer` and provide some configuration to
@@ -1507,8 +1510,8 @@ the following:
 * `spring.oauth2.resource.tokenInfoUri` to use the token decoding endpoint
 (e.g. "https://uaa.run.pivotal.io/check_token" on PWS).
 
-If you specify both the `userInfoUri` and the `tokenInfoUri` then 
-you can set a flag to say that one is preferred over the other 
+If you specify both the `userInfoUri` and the `tokenInfoUri` then
+you can set a flag to say that one is preferred over the other
 (`preferTokenInfo=true` is the default).
 
 Alternatively (instead of `userInfoUri` or `tokenInfoUri`) if the
@@ -1530,16 +1533,18 @@ authorization server needs to be running when your application starts
 up. It will log a warning if it can't find the key, and tell you what
 to do to fix it.
 
-=== Token Type in User Info
 
+
+=== Token Type in User Info
 Google (and certain other 3rd party identity providers) is more strict
 about the token type name that is sent in the headers to the user info
 endpoint. The default is "Bearer" which suits most providers and
 matches the spec, but if you need to change it you can set
 `spring.oauth2.resource.tokenType`.
 
-=== Customizing the User Info RestTemplate
 
+
+=== Customizing the User Info RestTemplate
 If you have a `userInfoUri`, the Resource Server features use an
 `OAuth2RestTemplate` internally to fetch user details for
 authentication. This is provided as a qualified `@Bean` with id
@@ -1571,8 +1576,9 @@ the key value (it's a standard YAML language feature). Example:
 ----
 ====
 
-==== Client
 
+
+==== Client
 To make your webapp into an OAuth2 client you can simply
 `@EnableOAuth2Client` and Spring Boot will create an
 `OAuth2RestTemplate` for you to autowire. It uses the
@@ -1603,7 +1609,7 @@ other provider for more flexibility).
 
 To limit the scope that the client asks for when it obtains an access token
 you can set `spring.oauth2.client.scope` (comma separated or an array in YAML). By
-default the scope is empty and it is up to to Authorization Server to 
+default the scope is empty and it is up to to Authorization Server to
 decide what the defaults should be, usually depending on the settings in
 the client registration that it holds.
 
@@ -1624,8 +1630,9 @@ client credentials token grant you will be asking for if you use it
 `spring.oauth2.client.clientId` from your configuration (or make it
 the empty string).
 
-==== Single Sign On
 
+
+==== Single Sign On
 An OAuth2 Client can be used to fetch user details from the provider
 if such features are provided (e.g. by using the `userInfoUri` that
 the Resource Server supports as above), and then the user details can
@@ -1679,8 +1686,9 @@ to the home page at "/" and keep the default for everything else:
 	}
 ----
 
-=== Actuator Security
 
+
+=== Actuator Security
 If the Actuator is also in use, you will find:
 
 * The management endpoints are secure even if the application endpoints are unsecure.
@@ -2295,7 +2303,6 @@ http://docs.spring.io/spring-data/elasticsearch/docs/[reference documentation].
 
 [[boot-features-caching]]
 == Caching
-
 The Spring Framework provides support for transparently adding caching into an
 application. At its core, the abstraction applies caching to methods, reducing thus the
 number of executions based on the information available in the cache. The caching logic
@@ -2329,8 +2336,9 @@ them.
 TIP: It is also possible to {spring-reference}/#cache-annotations-put[update] or
 {spring-reference}/#cache-annotations-evict[evict] data from the cache transparently.
 
-=== Supported cache providers
 
+
+=== Supported cache providers
 NOTE: To easily get started, just add `spring-boot-starter-cache` to the dependencies of
 your application.
 
@@ -2354,15 +2362,17 @@ Spring Boot tries to detect the following providers (in that order):
 It is also possible to _force_ the cache provider to use via the `spring.cache.type`
 property.
 
+
+
 [[boot-features-caching-provider-generic]]
 ==== Generic
-
 If the context defines _at least_ one `org.springframework.cache.Cache` bean, a
 `CacheManager` wrapping them is configured.
 
+
+
 [[boot-features-caching-provider-ehcache2]]
 ==== EhCache 2.x
-
 EhCache 2.x tries to locate a configuration file named `ehcache.xml` at the root of the
 classpath. If EhCache 2.x and such file is present it is used to bootstrap the cache
 manager. An alternate configuration file can be provide a well:
@@ -2399,9 +2409,10 @@ Infinispan has no default configuration file location so it must be specified ex
 Caches can be created on startup via the `spring.cache.cache-names` property. If a custom
 `ConfigurationBuilder` bean is defined, it is used to customize them.
 
+
+
 [[boot-features-caching-provider-jcache]]
 ==== JCache
-
 JCache is bootstrapped via the presence of a `javax.cache.spi.CachingProvider` on the
 classpath (i.e. a JSR-107 compliant caching library). It might happen than more that one
 provider is present, in which case the provider must be explicitly specified. Even if the
@@ -2431,16 +2442,18 @@ TIP: If a standard `javax.cache.CacheManager` bean is defined, it is wrapped
 automatically in a `org.springframework.cache.CacheManager` implementation that the
 abstraction expects. No further customization is applied on it.
 
+
+
 [[boot-features-caching-provider-redis]]
 ==== Redis
-
 If Redis is available and configured, the `RedisCacheManager` is auto-configured. It is
 also possible to create additional caches on startup using the `spring.cache.cache-names`
 property.
 
+
+
 [[boot-features-caching-provider-guava]]
 ==== Guava
-
 If Guava is present, a `GuavaCacheManager` is auto-configured. Caches can be created
 on startup using the `spring.cache.cache-names` property and customized by one of the
 following (in that order):
@@ -2461,14 +2474,16 @@ size of 500 and a _time to live_ of 10 minutes
 Besides, if a `com.google.common.cache.CacheLoader` bean is defined, it is automatically
 associated to the `GuavaCacheManager`.
 
+
+
 [[boot-features-caching-provider-simple]]
 ==== Simple
-
 If none of these options worked out, a simple implementation using `ConcurrentHashMap`
 as cache store is configured. This is the default if no caching library is present in
 your application.
 
 
+
 [[boot-features-messaging]]
 == Messaging
 The Spring Framework provides extensive support for integrating with messaging systems: