Spring/spring-boot
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Polish documentation

Browse Source
This commit is contained in:
Phillip Webb
2015-06-03 11:57:28 -07:00
parent bce4bb8860
commit 312471f996
4 changed files with 117 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
spring-boot-docs/src/main/asciidoc/deployment.adoc
View File

@@ -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:
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

2
spring-boot-docs/src/main/asciidoc/howto.adoc
View File

@@ -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

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

@@ -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

53
spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
View File

@@ -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: