From 312471f9967540645a3d0026729700e0105299db Mon Sep 17 00:00:00 2001 From: Phillip Webb Date: Wed, 3 Jun 2015 11:57:28 -0700 Subject: [PATCH] Polish documentation --- .../src/main/asciidoc/deployment.adoc | 52 +++++---- spring-boot-docs/src/main/asciidoc/howto.adoc | 2 + .../asciidoc/production-ready-features.adoc | 104 ++++++++---------- .../main/asciidoc/spring-boot-features.adoc | 53 +++++---- 4 files changed, 117 insertions(+), 94 deletions(-) diff --git a/spring-boot-docs/src/main/asciidoc/deployment.adoc b/spring-boot-docs/src/main/asciidoc/deployment.adoc index 2e10cdd4c5..2827781cc8 100644 --- a/spring-boot-docs/src/main/asciidoc/deployment.adoc +++ b/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 < ---- + + === 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: -The script accepts the following parameters as environment variables, so you can change the -default behaviour in a script or on the command line: +[cols="1,6"] +|=== +|Variable |Description -* `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 diff --git a/spring-boot-docs/src/main/asciidoc/howto.adoc b/spring-boot-docs/src/main/asciidoc/howto.adoc index 0725fcda5a..7caebb30cf 100644 --- a/spring-boot-docs/src/main/asciidoc/howto.adoc +++ b/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 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 5ad578ce82..d63459aa76 100644 --- a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc +++ b/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..*` where `` 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..*` where `` 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 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 f7940f2caa..4c6404ee1e 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/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: