root
/
spring-boot
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

Polish documentation

Browse Source
pull/3143/merge
Phillip Webb 10 years ago
parent 25f74cbaef
commit c7677d10ca
4 changed files with 203 additions and 209 deletions
Show Stats Download Patch File Download Diff File

4
spring-boot-docs/src/main/asciidoc/getting-started.adoc
Unescape Escape View File

@ -4,7 +4,7 @@
[partintro] [partintro]
-- --
If you're just getting started with Spring Boot, or 'Spring' in general, this is the section If you're just getting started with Spring Boot, or 'Spring' in general, this is the section
for you! Here we answer the basic '"`what?`"', '"`how?`"' and '"`why?`"' questions. You'll for you! Here we answer the basic "`what?`", "`how?`" and "`why?`" questions. You'll
find a gentle introduction to Spring Boot along with installation instructions. find a gentle introduction to Spring Boot along with installation instructions.
We'll then build our first Spring Boot application, discussing some core principles as We'll then build our first Spring Boot application, discussing some core principles as
we go. we go.
@ -524,7 +524,7 @@ endif::[]
---- ----
This should give you a working build, you can test it out by running `mvn package` (you This should give you a working build, you can test it out by running `mvn package` (you
can ignore the "`jar will be empty - no content was marked for inclusion!'`" warning for can ignore the "`jar will be empty - no content was marked for inclusion!`" warning for
now). now).
NOTE: At this point you could import the project into an IDE (most modern Java IDE's NOTE: At this point you could import the project into an IDE (most modern Java IDE's

66
spring-boot-docs/src/main/asciidoc/production-ready-features.adoc
Unescape Escape View File

@ -964,10 +964,10 @@ the metrics are exported to a Redis cache for aggregation. The `RedisMetricRepos
two important parameters to configure it for this purpose: `prefix` and `key` (passed into 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 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 (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 possible to correlate with other instances of the same application). The "`key`" is used
keep a global index of all metric names, so it should be unique "globally", whatever that to keep a global index of all metric names, so it should be unique "`globally`", whatever
means for your system (e.g. 2 instances of the same system could share a Redis cache if that means for your system (e.g. two instances of the same system could share a Redis cache
they have distinct keys). if they have distinct keys).
Example: Example:
@ -991,33 +991,33 @@ spring.metrics.export.redis.key: keys.metrics.mysystem
The prefix is constructed with the application name and id at the end, so it can easily be used The prefix is constructed with the application name and id at the end, so it can easily be used
to identify a group of processes with the same logical name later. to identify a group of processes with the same logical name later.
NOTE: it's important to set both the key and the prefix. The key is used for all NOTE: It's important to set both the `key` and the `prefix`. The key is used for all
repository operations, and can be shared by multiple repositories. If multiple repository operations, and can be shared by multiple repositories. If multiple
repositories share a key (like in the case where you need to aggregate across them), then repositories share a key (like in the case where you need to aggregate across them), then
you normally have a read-only "master" repository that has a short, but identifiable, you normally have a read-only "`master`" repository that has a short, but identifiable,
prefix (like "metrics.mysystem"), and many write-only repositories with prefixes that prefix (like "`metrics.mysystem`"), and many write-only repositories with prefixes that
start with the master prefix (like `metrics.mysystem.*` in the example above). It is start with the master prefix (like `metrics.mysystem.*` in the example above). It is
efficient to read all the keys from a "master" repository like that, but inefficient to 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). 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 TIP: 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 prefix. This is provided to you as a convenience by Spring Boot, configured with sensible
will be sensible, but there is nothing to stop you using your own values as long as they defaults. There is nothing to stop you using your own values as long as they follow the
follow the recommendations. recommendations.
[[production-ready-metric-writers-export-to-open-tdsb]] [[production-ready-metric-writers-export-to-open-tdsb]]
==== Example: Export to Open TSDB ==== Example: Export to Open TSDB
If you provide a `@Bean` of type `OpenTsdbHttpMetricWriter` and mark it If you provide a `@Bean` of type `OpenTsdbHttpMetricWriter` and mark it
`@ExportMetricWriter` the metrics are exported to http://opentsdb.net/[Open TSDB] for `@ExportMetricWriter` metrics are exported to http://opentsdb.net/[Open TSDB] for
aggregation. The `OpenTsdbHttpMetricWriter` has a `url` property that you need to set 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 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 `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 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 Open TSDB metric name, and adds the tags "`domain`" (with value
another tag "process" with value equals to the object hash of the naming strategy. Thus, "`org.springframework.metrics`") and "`process`" (with the value equal to the object hash
after running the application and generating some metrics (e.g. by pinging the home page) of the naming strategy). Thus, after running the application and generating some metrics
you can inspect the metrics in the TDB UI (http://localhost:4242 by default). you can inspect the metrics in the TDB UI (http://localhost:4242 by default).
Example: Example:
@ -1072,7 +1072,9 @@ MetricWriter metricWriter() {
If you provide a `@Bean` of type `JmxMetricWriter` marked `@ExportMetricWriter` the metrics are exported as MBeans to If you provide a `@Bean` of type `JmxMetricWriter` marked `@ExportMetricWriter` the metrics are exported as MBeans to
the local server (the `MBeanExporter` is provided by Spring Boot JMX autoconfiguration as the local server (the `MBeanExporter` is provided by Spring Boot JMX autoconfiguration as
long as it is switched on). Metrics can then be inspected, graphed, alerted etc. using any long as it is switched on). Metrics can then be inspected, graphed, alerted etc. using any
tool that understands JMX (e.g. JConsole or JVisualVM). Example: tool that understands JMX (e.g. JConsole or JVisualVM).
Example:
[source,java,indent=0] [source,java,indent=0]
---- ----
@ -1098,10 +1100,12 @@ period-separated prefix, and the reader will aggregate (by truncating the metric
and dropping the prefix). Counters are summed and everything else (i.e. gauges) take their and dropping the prefix). Counters are summed and everything else (i.e. gauges) take their
most recent value. most recent value.
This is very useful (for instance) if multiple application instances are feeding to a This is very useful if multiple application instances are feeding to a central (e.g.
central (e.g. redis) repository and you want to display the results. Particularly Redis) repository and you want to display the results. Particularly recommended in
recommended in conjunction with a `MetricReaderPublicMetrics` for hooking up to the conjunction with a `MetricReaderPublicMetrics` for hooking up to the results to the
results to the "/metrics" endpoint. Example: "`/metrics`" endpoint.
Example:
[source,java,indent=0] [source,java,indent=0]
---- ----
@ -1125,17 +1129,17 @@ results to the "/metrics" endpoint. Example:
} }
---- ----
NOTE: the example above uses `MetricExportProperties` to inject and NOTE: The example above uses `MetricExportProperties` to inject and extract the key and
extract the key and prefix. This is provided to you as a convenience prefix. This is provided to you as a convenience by Spring Boot, and the defaults will be
by Spring Boot, and the defaults will be sensible. They are set up in sensible. They are set up in `MetricExportAutoConfiguration`.
`MetricExportAutoConfiguration`.
NOTE: the `MetricReaders` above are not `@Beans` and are not marked as NOTE: The `MetricReaders` above are not `@Beans` and are not marked as
`@ExportMetricReader` because they are just collecting and analysing `@ExportMetricReader` because they are just collecting and analyzing data from other
data from other repositories, and don't want to export their values. repositories, and don't want to export their values.
[[production-ready-code-hale-metrics]]
[[production-ready-dropwizard-metrics]] [[production-ready-dropwizard-metrics]]
=== Dropwizard Metrics === Dropwizard Metrics
A default `MetricRegistry` Spring bean will be created when you declare a dependency to A default `MetricRegistry` Spring bean will be created when you declare a dependency to
@ -1149,7 +1153,7 @@ endpoint
When Dropwizard metrics are in use, the default `CounterService` and `GaugeService` are When Dropwizard metrics are in use, the default `CounterService` and `GaugeService` are
replaced with a `DropwizardMetricServices`, which is a wrapper around the `MetricRegistry` replaced with a `DropwizardMetricServices`, which is a wrapper around the `MetricRegistry`
(so you can `@Autowired` one of those services and use it as normal). You can also create (so you can `@Autowired` one of those services and use it as normal). You can also create
"special" Dropwizard metrics by prefixing your metric names with the appropriate type "`special`" Dropwizard metrics by prefixing your metric names with the appropriate type
(i.e. `+timer.*+`, `+histogram.*+` for gauges, and `+meter.*+` for counters). (i.e. `+timer.*+`, `+histogram.*+` for gauges, and `+meter.*+` for counters).
@ -1185,7 +1189,7 @@ and obtain basic information about the last few requests:
[source,json,indent=0] [source,json,indent=0]
---- ----
[{ [{
"timestamp": 1394343677415, "timestamp": 1394343677415,
"info": { "info": {
"method": "GET", "method": "GET",

276
spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
Unescape Escape View File

@ -1464,105 +1464,100 @@ features add a `@Bean` of type `WebSecurityConfigurerAdapter` with
[[boot-features-security-oauth2]]
=== OAuth2 === OAuth2
If you have `spring-security-oauth2` on your classpath you can take advantage of some 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 auto-configuration to make it easy to set up Authorization or Resource Server.
configuring some property values in the `Environment`.
[[boot-features-security-oauth2-authorization-server]]
==== Authorization Server ==== Authorization Server
To create an Authorization Server and grant access tokens you need to To create an Authorization Server and grant access tokens you need to use
`@EnableAuthorizationServer` and provide `@EnableAuthorizationServer` and provide `spring.oauth2.client.client-id` and
`spring.oauth2.client.[clientId,clientSecret]`. The client will be `spring.oauth2.client.client-secret]` properties. The client will be registered for you
registered for you in an in-memory repository. Having done that you in an in-memory repository.
will be able to use the client credentials to create an access token,
e.g.
Having done that you will be able to use the client credentials to create an access token,
for example:
[indent=0]
---- ----
$ curl client:secret@localhost:8080/oauth/token -d grant_type=password -d username=user -d password=pwd $ curl client:secret@localhost:8080/oauth/token -d grant_type=password -d username=user -d password=pwd
---- ----
The basic auth credentials for the `/token` endpoint are the client id The basic auth credentials for the `/token` endpoint are the `client-id` and
and secret, and the user credentials are the normal Spring Security `client-secret`. The user credentials are the normal Spring Security user details (which
user details (which default in Spring Boot to "user" and a random default in Spring Boot to "`user`" and a random password).
password).
To switch off the autoconfiguration and configure the Authorization To switch off the auto-configuration and configure the Authorization Server features
Server features yourself just add a `@Bean` of type yourself just add a `@Bean` of type `AuthorizationServerConfigurer`.
`AuthorizationServerConfigurer`.
[[boot-features-security-oauth2-resource-server]]
==== Resource Server ==== Resource Server
To use the access token you need a Resource Server (which can be the To use the access token you need a Resource Server (which can be the same as the
same as the Authorization Server). Creating a Resource Server is easy: Authorization Server). Creating a Resource Server is easy, just add
just add `@EnableResourceServer` and provide some configuration to `@EnableResourceServer` and provide some configuration to allow the server to decode
allow the server to decode access tokens. If your app is also an access tokens. If your appplication is also an Authorization Server it already knows how
Authorization Server it already knows how to decode tokens, so there to decode tokens, so there is nothing else to do. If your app is a standalone service then you
is nothing else to do. If your app is a standalone service then you need to give it some more configuration, one of the following options:
need to give it some more configuration. Here are the options, one of
the following:
* `spring.oauth2.resource.userInfoUri` to use the "/me" resource * `spring.oauth2.resource.user-info-uri` to use the "/me" resource (e.g.
(e.g. "https://uaa.run.pivotal.io/userinfo" on PWS), or "`https://uaa.run.pivotal.io/userinfo`" on PWS)
* `spring.oauth2.resource.tokenInfoUri` to use the token decoding endpoint * `spring.oauth2.resource.token-info-uri` to use the token decoding endpoint (e.g.
(e.g. "https://uaa.run.pivotal.io/check_token" on PWS). "`https://uaa.run.pivotal.io/check_token`" on PWS).
If you specify both the `userInfoUri` and the `tokenInfoUri` then If you specify both the `user-info-uri` and the `token-info-uri` then you can set a flag
you can set a flag to say that one is preferred over the other to say that one is preferred over the other (`prefer-token-info=true` is the default).
(`preferTokenInfo=true` is the default).
Alternatively (instead of `userInfoUri` or `tokenInfoUri`) if the Alternatively (instead of `user-info-uri` or `token-info-uri`) if the tokens are JWTs you
tokens are JWTs you can configure a can configure a `spring.oauth2.resource.jwt.key-value` to decode them locally (where the
`spring.oauth2.resource.jwt.keyValue` to decode them locally, key is a verification key). The verification key value is either a symmetric secret or
where the key is a verification key. The verification key value is PEM-encoded RSA public key. If you don't have the key and it's public you can provide a
either a symmetric secret or PEM-encoded RSA public key. If you don't URI where it can be downloaded (as a JSON object with a "`value`" field) with
have the key and it's public you can provide a URI where it can be `spring.oauth2.resource.jwt.key-uri`. E.g. on PWS:
downloaded (as a JSON object with a "value" field) with
`spring.oauth2.resource.jwt.keyUri`. E.g. on PWS:
[indent=0]
---- ----
$ curl https://uaa.run.pivotal.io/token_key $ curl https://uaa.run.pivotal.io/token_key
{"alg":"SHA256withRSA","value":"-----BEGIN PUBLIC KEY-----\nMIIBI...\n-----END PUBLIC KEY-----\n"} {"alg":"SHA256withRSA","value":"-----BEGIN PUBLIC KEY-----\nMIIBI...\n-----END PUBLIC KEY-----\n"}
---- ----
WARNING: If you use the `spring.oauth2.resource.jwt.keyUri` the WARNING: If you use the `spring.oauth2.resource.jwt.key-uri` the authorization server
authorization server needs to be running when your application starts needs to be running when your application starts up. It will log a warning if it can't
up. It will log a warning if it can't find the key, and tell you what find the key, and tell you what to do to fix it.
to do to fix it.
[[boot-features-security-oauth2-token-type]]
=== Token Type in User Info === Token Type in User Info
Google (and certain other 3rd party identity providers) is more strict Google, and certain other 3rd party identity providers, are more strict about the token
about the token type name that is sent in the headers to the user info type name that is sent in the headers to the user info endpoint. The default is "`Bearer`"
endpoint. The default is "Bearer" which suits most providers and which suits most providers and matches the spec, but if you need to change it you can set
matches the spec, but if you need to change it you can set `spring.oauth2.resource.token-type`.
`spring.oauth2.resource.tokenType`.
[[boot-features-security-custom-user-info]]
=== Customizing the User Info RestTemplate === Customizing the User Info RestTemplate
If you have a `userInfoUri`, the Resource Server features use an If you have a `user-info-uri`, the resource server features use an `OAuth2RestTemplate`
`OAuth2RestTemplate` internally to fetch user details for internally to fetch user details for authentication. This is provided as a qualified
authentication. This is provided as a qualified `@Bean` with id `@Bean` with id `userInfoRestTemplate`, but you shouldn't need to know that to just
"userInfoRestTemplate", but you shouldn't need to know that to just use it. The default should be fine for most providers, but occasionally you might need to
use it. The default should be fine for most providers, but add additional interceptors, or change the request authenticator (which is how the token
occasionally you might need to add additional interceptors, or change gets attached to outgoing requests). To add a customization just create a bean of type
the request authenticator (which is how the token gets attached to `UserInfoRestTemplateCustomizer` - it has a single method that will be called after the
outgoing requests). To add a customization just create a bean of type bean is created but before it is initialized. The rest template that is being customized
`UserInfoRestTemplateCustomizer` - it has a single method that will be here is _only_ used internally to carry out authentication.
called after the bean is created but before it is initialized. The
rest template that is being customized here is _only_ used internally
to carry out authentication.
[TIP] [TIP]
==== ====
To set an RSA key value in YAML use the "pipe" continuation To set an RSA key value in YAML use the "`pipe`" continuation marker to split it over
marker to split it over multiple lines ("|") and remember to indent multiple lines ("`|`") and remember to indent the key value (it's a standard YAML
the key value (it's a standard YAML language feature). Example: language feature). Example:
[source,yaml,indent=0] [source,yaml,indent=0]
---- ----
@ -1578,17 +1573,16 @@ the key value (it's a standard YAML language feature). Example:
[[boot-features-security-custom-user-info-client]]
==== Client ==== Client
To make your webapp into an OAuth2 client you can simply To make your webapp into an OAuth2 client you can simply add `@EnableOAuth2Client` and
`@EnableOAuth2Client` and Spring Boot will create an Spring Boot will create an `OAuth2RestTemplate` for you to `@Autowire`. It uses the
`OAuth2RestTemplate` for you to autowire. It uses the `spring.oauth2.client.*` as credentials (the same as you might be using in the
`spring.oauth2.client.*` as credentials (the same as you might be Authorization Server), but in addition it will need to know the authorization and token
using in the Authorization Server), but in addition it will need to URIs in the Authorization Server. For example:
know the authorization and token URIs in the Authorization Server. For
example:
.application.yml .application.yml
[source,yaml] [source,yaml,indent=0]
---- ----
spring: spring:
oauth2: oauth2:
@ -1600,72 +1594,62 @@ spring:
clientAuthenticationScheme: form clientAuthenticationScheme: form
---- ----
An app with this configuration will redirect to github for An application with this configuration will redirect to Github for authorization when you
authorization if you attempt to use the `OAuth2RestTemplate`. If you attempt to use the `OAuth2RestTemplate`. If you are already signed into Github you won't
are already signed into github you won't even notice that it has even notice that it has authenticated. These specific credentials will only work if your
authenticated. These specific credentials will only work if your app application is running on port 8080 (register your own client app in Github or other
is running on port 8080 (register your own client app in Github or provider for more flexibility).
other provider for more flexibility).
To limit the scope that the client asks for when it obtains an access token To limit the scope that the client asks for when it obtains an access token you can set
you can set `spring.oauth2.client.scope` (comma separated or an array in YAML). By `spring.oauth2.client.scope` (comma separated or an array in YAML). By default the scope
default the scope is empty and it is up to to Authorization Server to is empty and it is up to to Authorization Server to decide what the defaults should be,
decide what the defaults should be, usually depending on the settings in usually depending on the settings in the client registration that it holds.
the client registration that it holds.
NOTE: There is also a setting for NOTE: There is also a setting for `spring.oauth2.client.client-authentication-scheme`
`spring.oauth2.client.clientAuthenticationScheme` which defaults to which defaults to "`header`" (but you might need to set it to "`form`" if, like Github for
"header" (but you might need to set it to "form" if, like Github for instance, your OAuth2 provider doesn't like header authentication). In fact, the
instance, your OAuth2 provider doesn't like header authentication). In `spring.oauth2.client.*` properties are bound to an instance of
fact, the `spring.oauth2.client.*` properties are bound to an instance `AuthorizationCodeResourceDetails` so all its properties can be specified.
of `AuthorizationCodeResourceDetails` so all its properties can be
specified.
TIP: In a non-web application you can still `@Autowired` an TIP: In a non-web application you can still `@Autowire` an `OAuth2RestOperations` and it
`OAuth2RestOperations` and it is still wired into the is still wired into the `spring.oauth2.client.*` configuration. In this case it is a
`spring.oauth2.client.*` configuration, but in this case it is a "`client credentials token grant`" you will be asking for if you use it (and there is no
client credentials token grant you will be asking for if you use it need to use `@EnableOAuth2Client` or `@EnableOAuth2Sso`). To switch it off, just remove
(and there is no need to use `@EnableOAuth2Client` or the `spring.oauth2.client.client-id` from your configuration (or make it the empty
`@EnableOAuth2Sso`). To switch it off, just remove the string).
`spring.oauth2.client.clientId` from your configuration (or make it
the empty string).
[[boot-features-security-oauth2-single-sign-on]]
==== Single Sign On ==== Single Sign On
An OAuth2 Client can be used to fetch user details from the provider An OAuth2 Client can be used to fetch user details from the provider (if such features are
if such features are provided (e.g. by using the `userInfoUri` that available) and then convert them into an `Authentication` token for Spring Security.
the Resource Server supports as above), and then the user details can The Resource Server above support this via the `user-info-uri` property This is the basis
be converted to an `Authentication` token for Spring Security. This is for a Single Sign On (SSO) protocol based on OAuth2, and Spring Boot makes it easy to
the basis for a Single Sign On (SSO) protocol based on OAuth2, and participate by providing an annotation `@EnableOAuth2Sso`. The Github client above can
Spring Boot makes it easy to participate by providing an annotation protect all its resources and authenticate using the Github `/user/` endpoint, by adding
`@EnableOAuth2Sso`. The Github client above can protect all its that annotation and declaring where to find the endpoint (in addition to the
resources and authenticate using the Github `/user/` endpoint, by `spring.oauth2.client.*` configuration already listed above):
adding that annotation and declaring where to find the endpoint (in
addition to the `spring.oauth2.client.*` configuration already listed
above):
.application.yml .application.yml
[source,yaml] [source,yaml,indent=0]]
---- ----
spring: spring:
oauth2: oauth2:
... ...
resource: resource:
userInfoUri: https://api.github.com/user userInfoUri: https://api.github.com/user
preferTokenInfo: false preferTokenInfo: false
---- ----
Since all paths are secure by default, there is no "home" page that Since all paths are secure by default, there is no "`home`" page that you can show to
you can show to unauthenticated users and invite them to login (by unauthenticated users and invite them to login (by visiting the `/login` path, or the
visiting the `/login` path, or the path specified by path specified by `spring.oauth2.sso.login-path`).
`spring.oauth2.sso.loginPath`).
To customize the access rules or paths to protect, so you can add a To customize the access rules or paths to protect, so you can add a "`home`" page for
"home" page for instance, `@EnableOAuth2Sso` can be added to a instance, `@EnableOAuth2Sso` can be added to a `WebSecurityConfigurerAdapter` and the
`WebSecurityConfigurerAdapter` and the annotation will cause it to be annotation will cause it to be decorated and enhanced with the necessary pieces to get
decorated and enhanced with the necessary pieces to get the `/login` the `/login` path working. For example, here we simply allow unauthenticated access
path working. For example, here we simply allow unauthenticated access
to the home page at "/" and keep the default for everything else: to the home page at "/" and keep the default for everything else:
[source,java,indent=0] [source,java,indent=0]
@ -1688,6 +1672,7 @@ to the home page at "/" and keep the default for everything else:
[[boot-features-security-actuator]]
=== Actuator Security === Actuator Security
If the Actuator is also in use, you will find: If the Actuator is also in use, you will find:
@ -2301,12 +2286,13 @@ TIP: For complete details of Spring Data Elasticsearch, refer to their
http://docs.spring.io/spring-data/elasticsearch/docs/[reference documentation]. http://docs.spring.io/spring-data/elasticsearch/docs/[reference documentation].
[[boot-features-caching]] [[boot-features-caching]]
== Caching == Caching
The Spring Framework provides support for transparently adding caching into an The Spring Framework provides support for transparently adding caching to an application.
application. At its core, the abstraction applies caching to methods, reducing thus the At its core, the abstraction applies caching to methods, reducing thus the number of
number of executions based on the information available in the cache. The caching logic executions based on the information available in the cache. The caching logic is applied
is applied transparently without any interference to the invoker. transparently, without any interference to the invoker.
NOTE: Check the {spring-reference}/#cache[relevant section] of the Spring Framework NOTE: Check the {spring-reference}/#cache[relevant section] of the Spring Framework
reference for more details. reference for more details.
@ -2324,7 +2310,9 @@ relevant annotation to its method:
public class MathService { public class MathService {
@CacheResult @CacheResult
public int computePiDecimal(int i) { ... } public int computePiDecimal(int i) {
// ...
}
} }
---- ----
@ -2339,16 +2327,17 @@ TIP: It is also possible to {spring-reference}/#cache-annotations-put[update] or
=== Supported cache providers === Supported cache providers
NOTE: To easily get started, just add `spring-boot-starter-cache` to the dependencies of
your application.
The cache abstraction does not provide an actual store and relies on a abstraction The cache abstraction does not provide an actual store and relies on a abstraction
materialized by the `org.springframework.cache.Cache` and materialized by the `org.springframework.cache.Cache` and
`org.springframework.cache.CacheManager` interfaces. Spring Boot auto-configures a `org.springframework.cache.CacheManager` interfaces. Spring Boot auto-configures a
suitable `CacheManager` according to the implementation as long as the caching support is suitable `CacheManager` according to the implementation as long as the caching support is
enabled via the `@EnableCaching` annotation. enabled via the `@EnableCaching` annotation.
Spring Boot tries to detect the following providers (in that order): TIP: Use the `spring-boot-starter-cache` "`Starter POM`" to quickly add required caching
dependencies. If you are adding dependencies manually you should note that certain
implementations are only provided by the `spring-context-support` jar.
Spring Boot tries to detect the following providers (in this order):
* <<boot-features-caching-provider-generic,Generic>> * <<boot-features-caching-provider-generic,Generic>>
* <<boot-features-caching-provider-ehcache2,EhCache 2.x>> * <<boot-features-caching-provider-ehcache2,EhCache 2.x>>
@ -2366,38 +2355,40 @@ property.
[[boot-features-caching-provider-generic]] [[boot-features-caching-provider-generic]]
==== Generic ==== Generic
If the context defines _at least_ one `org.springframework.cache.Cache` bean, a Generic caching is used if the context defines _at least_ one
`CacheManager` wrapping them is configured. `org.springframework.cache.Cache` bean, a `CacheManager` wrapping them is configured.
[[boot-features-caching-provider-ehcache2]] [[boot-features-caching-provider-ehcache2]]
==== EhCache 2.x ==== EhCache 2.x
EhCache 2.x tries to locate a configuration file named `ehcache.xml` at the root of the EhCache 2.x is used if a file named `ehcache.xml` can be found at the root of the
classpath. If EhCache 2.x and such file is present it is used to bootstrap the cache 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: manager. An alternate configuration file can be provide a well using:
[source,properties,indent=0] [source,properties,indent=0]
---- ----
spring.cache.ehcache.config=classpath:config/another-config.xml spring.cache.ehcache.config=classpath:config/another-config.xml
---- ----
[[boot-features-caching-provider-hazelcast]] [[boot-features-caching-provider-hazelcast]]
==== Hazelcast ==== Hazelcast
Hazelcast is used if a `hazelcast.xml` file can be found in the current working
Hazelcast tries to locate its configuration file as follows: An `hazelcast.xml` file directory, at the root of the classpath or a location specified via the `hazelcast.config`
stored either in the current working directory or at the root of the classpath, or a system property. Spring Boot detects all of these and also allows for explicit location
location specified via the `hazelcast.config` system property. Spring Boot detects all using:
of these and allow for explicit location as well:
[source,properties,indent=0] [source,properties,indent=0]
---- ----
spring.cache.hazelcast.config=classpath:config/my-hazelcast.xml spring.cache.hazelcast.config=classpath:config/my-hazelcast.xml
---- ----
[[boot-features-caching-provider-infinispan]] [[boot-features-caching-provider-infinispan]]
==== Infinispan ==== Infinispan
Infinispan has no default configuration file location so it must be specified explicitly Infinispan has no default configuration file location so it must be specified explicitly
(or the default bootstrap is used). (or the default bootstrap is used).
@ -2423,7 +2414,6 @@ configuration file, Spring Boot does its best to accommodate with implementation
---- ----
# Only necessary if more than one provider is present # Only necessary if more than one provider is present
spring.cache.jcache.provider=com.acme.MyCachingProvider spring.cache.jcache.provider=com.acme.MyCachingProvider
spring.cache.jcache.config=classpath:acme.xml spring.cache.jcache.config=classpath:acme.xml
---- ----
@ -2456,7 +2446,7 @@ property.
==== Guava ==== Guava
If Guava is present, a `GuavaCacheManager` is auto-configured. Caches can be created 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 on startup using the `spring.cache.cache-names` property and customized by one of the
following (in that order): following (in this order):
1. A cache spec defined by `spring.cache.guava.spec` 1. A cache spec defined by `spring.cache.guava.spec`
2. A `com.google.common.cache.CacheBuilderSpec` bean is defined 2. A `com.google.common.cache.CacheBuilderSpec` bean is defined

2
spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc
Unescape Escape View File

@ -238,7 +238,7 @@ where `+*+` is a particular type of application. This naming structure is intend
help when you need to find a starter. The Maven integration in many IDEs allow you to help when you need to find a starter. The Maven integration in many IDEs allow you to
search dependencies by name. For example, with the appropriate Eclipse or STS plugin search dependencies by name. For example, with the appropriate Eclipse or STS plugin
installed, you can simply hit `ctrl-space` in the POM editor and type installed, you can simply hit `ctrl-space` in the POM editor and type
''spring-boot-starter'' for a complete list. "`spring-boot-starter`" for a complete list.
Third party starters should not start with `spring-boot-starter` as it is reserved for Third party starters should not start with `spring-boot-starter` as it is reserved for
official starters. A third-party starter for `acme` will be typically named official starters. A third-party starter for `acme` will be typically named

Write Preview
Loading…
Cancel
Save