Skip to content

S
spring-boot
Commit c7677d10 authored by Phillip Webb's avatar Phillip Webb
Browse files
Options

Polish documentation

parent 25f74cba
Hide whitespace changes
Inline Side-by-side
Showing with 203 additions and 209 deletions
spring-boot-docs/src/main/asciidoc/getting-started.adoc
View file @ c7677d10
......@@ -4,7 +4,7 @@
[partintro]
--
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.
We'll then build our first Spring Boot application, discussing some core principles as
we go.
......@@ -524,7 +524,7 @@ endif::[]
----
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).
NOTE: At this point you could import the project into an IDE (most modern Java IDE's
......
spring-boot-docs/src/main/asciidoc/production-ready-features.adoc
View file @ c7677d10
......@@ -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
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).
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. two instances of the same system could share a Redis cache
if they have distinct keys).
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
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
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,
prefix (like "metrics.mysystem"), and many write-only repositories with prefixes that
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
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).
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.
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, configured with sensible
defaults. 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
`@ExportMetricWriter` 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
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)
Open TSDB metric name, and adds the tags "`domain`" (with value
"`org.springframework.metrics`") and "`process`" (with the value equal to the object hash
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).
Example:
......@@ -1072,7 +1072,9 @@ MetricWriter metricWriter() {
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
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]
----
......@@ -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
most recent value.
This is very useful (for instance) if multiple application instances are feeding to a
central (e.g. redis) repository and you want to display the results. Particularly
recommended in conjunction with a `MetricReaderPublicMetrics` for hooking up to the
results to the "/metrics" endpoint. Example:
This is very useful if multiple application instances are feeding to a central (e.g.
Redis) repository and you want to display the results. Particularly recommended in
conjunction with a `MetricReaderPublicMetrics` for hooking up to the results to the
"`/metrics`" endpoint.
Example:
[source,java,indent=0]
----
......@@ -1125,17 +1129,17 @@ results to the "/metrics" endpoint. Example:
}
----
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 will be sensible. They are set up in
`MetricExportAutoConfiguration`.
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 will be
sensible. They are set up in `MetricExportAutoConfiguration`.
NOTE: the `MetricReaders` above are not `@Beans` and are not marked as
`@ExportMetricReader` because they are just collecting and analysing
data from other repositories, and don't want to export their values.
NOTE: The `MetricReaders` above are not `@Beans` and are not marked as
`@ExportMetricReader` because they are just collecting and analyzing data from other
repositories, and don't want to export their values.
[[production-ready-code-hale-metrics]]
[[production-ready-dropwizard-metrics]]
=== Dropwizard Metrics
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
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
"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).
......@@ -1185,7 +1189,7 @@ and obtain basic information about the last few requests:
[source,json,indent=0]
----
[{
[{
"timestamp": 1394343677415,
"info": {
"method": "GET",
......@@ -1253,9 +1257,9 @@ In `META-INF/spring.factories` file you have to activate the listener(s):
[indent=0]
----
org.springframework.context.ApplicationListener=\
org.springframework.boot.actuate.system.ApplicationPidFileWriter,
org.springframework.boot.actuate.system.EmbeddedServerPortFileWriter
org.springframework.context.ApplicationListener=\
org.springframework.boot.actuate.system.ApplicationPidFileWriter,
org.springframework.boot.actuate.system.EmbeddedServerPortFileWriter
----
......
spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
View file @ c7677d10
......@@ -1464,208 +1464,192 @@ features add a `@Bean` of type `WebSecurityConfigurerAdapter` with
[[boot-features-security-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`.
auto-configuration to make it easy to set up Authorization or Resource Server.
[[boot-features-security-oauth2-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
registered for you in an in-memory repository. Having done that you
will be able to use the client credentials to create an access token,
e.g.
To create an Authorization Server and grant access tokens you need to use
`@EnableAuthorizationServer` and provide `spring.oauth2.client.client-id` and
`spring.oauth2.client.client-secret]` properties. The client will be registered for you
in an in-memory repository.
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
and secret, and the user credentials are the normal Spring Security
user details (which default in Spring Boot to "user" and a random
password).
The basic auth credentials for the `/token` endpoint are the `client-id` and
`client-secret`. The user credentials are the normal Spring Security user details (which
default in Spring Boot to "`user`" and a random password).
To switch off the autoconfiguration and configure the Authorization
Server features yourself just add a `@Bean` of type
`AuthorizationServerConfigurer`.
To switch off the auto-configuration and configure the Authorization Server features
yourself just add a `@Bean` of type `AuthorizationServerConfigurer`.
[[boot-features-security-oauth2-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
allow the server to decode access tokens. If your app is also an
Authorization Server it already knows how to decode tokens, so there
is nothing else to do. If your app is a standalone service then you
need to give it some more configuration. Here are the options, one of
the following:
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 allow the server to decode
access tokens. If your appplication is also an Authorization Server it already knows how
to decode tokens, so there 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:
* `spring.oauth2.resource.userInfoUri` to use the "/me" resource
(e.g. "https://uaa.run.pivotal.io/userinfo" on PWS), or
* `spring.oauth2.resource.user-info-uri` to use the "/me" resource (e.g.
"`https://uaa.run.pivotal.io/userinfo`" on PWS)
* `spring.oauth2.resource.tokenInfoUri` to use the token decoding endpoint
(e.g. "https://uaa.run.pivotal.io/check_token" on PWS).
* `spring.oauth2.resource.token-info-uri` 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
(`preferTokenInfo=true` is the default).
If you specify both the `user-info-uri` and the `token-info-uri` then you can set a flag
to say that one is preferred over the other (`prefer-token-info=true` is the default).
Alternatively (instead of `userInfoUri` or `tokenInfoUri`) if the
tokens are JWTs you can configure a
`spring.oauth2.resource.jwt.keyValue` to decode them locally,
where the key is a verification key. The verification key value is
either a symmetric secret or PEM-encoded RSA public key. If you don't
have the key and it's public you can provide a URI where it can be
downloaded (as a JSON object with a "value" field) with
`spring.oauth2.resource.jwt.keyUri`. E.g. on PWS:
Alternatively (instead of `user-info-uri` or `token-info-uri`) if the tokens are JWTs you
can configure a `spring.oauth2.resource.jwt.key-value` to decode them locally (where the
key is a verification key). The verification key value is either a symmetric secret or
PEM-encoded RSA public key. If you don't have the key and it's public you can provide a
URI where it can be downloaded (as a JSON object with a "`value`" field) with
`spring.oauth2.resource.jwt.key-uri`. E.g. on PWS:
[indent=0]
----
$ curl https://uaa.run.pivotal.io/token_key
{"alg":"SHA256withRSA","value":"-----BEGIN PUBLIC KEY-----\nMIIBI...\n-----END PUBLIC KEY-----\n"}
$ curl https://uaa.run.pivotal.io/token_key
{"alg":"SHA256withRSA","value":"-----BEGIN PUBLIC KEY-----\nMIIBI...\n-----END PUBLIC KEY-----\n"}
----
WARNING: If you use the `spring.oauth2.resource.jwt.keyUri` the
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.
WARNING: If you use the `spring.oauth2.resource.jwt.key-uri` the 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.
[[boot-features-security-oauth2-token-type]]
=== 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`.
Google, and certain other 3rd party identity providers, are 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.token-type`.
[[boot-features-security-custom-user-info]]
=== 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
"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 add additional interceptors, or change
the request authenticator (which is how the token gets attached to
outgoing requests). To add a customization just create a bean of type
`UserInfoRestTemplateCustomizer` - it has a single method that will be
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.
If you have a `user-info-uri`, the resource server features use an `OAuth2RestTemplate`
internally to fetch user details for authentication. This is provided as a qualified
`@Bean` with id `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
add additional interceptors, or change the request authenticator (which is how the token
gets attached to outgoing requests). To add a customization just create a bean of type
`UserInfoRestTemplateCustomizer` - it has a single method that will be 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]
====
To set an RSA key value in YAML use the "pipe" continuation
marker to split it over multiple lines ("|") and remember to indent
the key value (it's a standard YAML language feature). Example:
To set an RSA key value in YAML use the "`pipe`" continuation marker to split it over
multiple lines ("`|`") and remember to indent the key value (it's a standard YAML
language feature). Example:
[source,yaml,indent=0]
----
oauth2:
resource:
jwt:
keyValue: |
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC...
-----END PUBLIC KEY-----
oauth2:
resource:
jwt:
keyValue: |
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKC...
-----END PUBLIC KEY-----
----
====
[[boot-features-security-custom-user-info-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
`spring.oauth2.client.*` as credentials (the same as you might be
using in the Authorization Server), but in addition it will need to
know the authorization and token URIs in the Authorization Server. For
example:
To make your webapp into an OAuth2 client you can simply add `@EnableOAuth2Client` and
Spring Boot will create an `OAuth2RestTemplate` for you to `@Autowire`. It uses the
`spring.oauth2.client.*` as credentials (the same as you might be using in the
Authorization Server), but in addition it will need to know the authorization and token
URIs in the Authorization Server. For example:
.application.yml
[source,yaml]
[source,yaml,indent=0]
----
spring:
oauth2:
client:
clientId: bd1c0a783ccdd1c9b9e4
clientSecret: 1a9030fbca47a5b2c28e92f19050bb77824b5ad1
accessTokenUri: https://github.com/login/oauth/access_token
userAuthorizationUri: https://github.com/login/oauth/authorize
clientAuthenticationScheme: form
----
An app with this configuration will redirect to github for
authorization if you attempt to use the `OAuth2RestTemplate`. If you
are already signed into github you won't even notice that it has
authenticated. These specific credentials will only work if your app
is running on port 8080 (register your own client app in Github or
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
decide what the defaults should be, usually depending on the settings in
the client registration that it holds.
NOTE: There is also a setting for
`spring.oauth2.client.clientAuthenticationScheme` which defaults to
"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 `spring.oauth2.client.*` properties are bound to an instance
of `AuthorizationCodeResourceDetails` so all its properties can be
specified.
TIP: In a non-web application you can still `@Autowired` an
`OAuth2RestOperations` and it is still wired into the
`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 need to use `@EnableOAuth2Client` or
`@EnableOAuth2Sso`). To switch it off, just remove the
`spring.oauth2.client.clientId` from your configuration (or make it
the empty string).
oauth2:
client:
clientId: bd1c0a783ccdd1c9b9e4
clientSecret: 1a9030fbca47a5b2c28e92f19050bb77824b5ad1
accessTokenUri: https://github.com/login/oauth/access_token
userAuthorizationUri: https://github.com/login/oauth/authorize
clientAuthenticationScheme: form
----
An application with this configuration will redirect to Github for authorization when you
attempt to use the `OAuth2RestTemplate`. If you are already signed into Github you won't
even notice that it has authenticated. These specific credentials will only work if your
application is running on port 8080 (register your own client app in Github or 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 decide what the defaults should be,
usually depending on the settings in the client registration that it holds.
NOTE: There is also a setting for `spring.oauth2.client.client-authentication-scheme`
which defaults to "`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
`spring.oauth2.client.*` properties are bound to an instance of
`AuthorizationCodeResourceDetails` so all its properties can be specified.
TIP: In a non-web application you can still `@Autowire` an `OAuth2RestOperations` and it
is still wired into the `spring.oauth2.client.*` configuration. In this case it is a
"`client credentials token grant`" you will be asking for if you use it (and there is no
need to use `@EnableOAuth2Client` or `@EnableOAuth2Sso`). To switch it off, just remove
the `spring.oauth2.client.client-id` from your configuration (or make it the empty
string).
[[boot-features-security-oauth2-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
be converted to an `Authentication` token for Spring Security. This is
the basis for a Single Sign On (SSO) protocol based on OAuth2, and
Spring Boot makes it easy to participate by providing an annotation
`@EnableOAuth2Sso`. The Github client above can protect all its
resources and authenticate using the Github `/user/` endpoint, by
adding that annotation and declaring where to find the endpoint (in
addition to the `spring.oauth2.client.*` configuration already listed
above):
An OAuth2 Client can be used to fetch user details from the provider (if such features are
available) and then convert them into an `Authentication` token for Spring Security.
The Resource Server above support this via the `user-info-uri` property This is the basis
for a Single Sign On (SSO) protocol based on OAuth2, and Spring Boot makes it easy to
participate by providing an annotation `@EnableOAuth2Sso`. The Github client above can
protect all its resources and authenticate using the Github `/user/` endpoint, by adding
that annotation and declaring where to find the endpoint (in addition to the
`spring.oauth2.client.*` configuration already listed above):
.application.yml
[source,yaml]
[source,yaml,indent=0]]
----
spring:
oauth2:
...
resource:
userInfoUri: https://api.github.com/user
preferTokenInfo: false
----
Since all paths are secure by default, there is no "home" page that
you can show to unauthenticated users and invite them to login (by
visiting the `/login` path, or the path specified by
`spring.oauth2.sso.loginPath`).
To customize the access rules or paths to protect, so you can add a
"home" page for instance, `@EnableOAuth2Sso` can be added to a
`WebSecurityConfigurerAdapter` and the annotation will cause it to be
decorated and enhanced with the necessary pieces to get the `/login`
path working. For example, here we simply allow unauthenticated access
spring:
oauth2:
...
resource:
userInfoUri: https://api.github.com/user
preferTokenInfo: false
----
Since all paths are secure by default, there is no "`home`" page that you can show to
unauthenticated users and invite them to login (by visiting the `/login` path, or the
path specified by `spring.oauth2.sso.login-path`).
To customize the access rules or paths to protect, so you can add a "`home`" page for
instance, `@EnableOAuth2Sso` can be added to a `WebSecurityConfigurerAdapter` and the
annotation will cause it to be decorated and enhanced with the necessary pieces to get
the `/login` path working. For example, here we simply allow unauthenticated access
to the home page at "/" and keep the default for everything else:
[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
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].
[[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
is applied transparently without any interference to the invoker.
The Spring Framework provides support for transparently adding caching to 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 is applied
transparently, without any interference to the invoker.
NOTE: Check the {spring-reference}/#cache[relevant section] of the Spring Framework
reference for more details.
......@@ -2324,7 +2310,9 @@ relevant annotation to its method:
public class MathService {
@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
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
materialized by the `org.springframework.cache.Cache` and
`org.springframework.cache.CacheManager` interfaces. Spring Boot auto-configures a
suitable `CacheManager` according to the implementation as long as the caching support is
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-ehcache2,EhCache 2.x>>
......@@ -2366,38 +2355,40 @@ 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.
Generic caching is used 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
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
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]
----
spring.cache.ehcache.config=classpath:config/another-config.xml
----
[[boot-features-caching-provider-hazelcast]]
==== Hazelcast
Hazelcast tries to locate its configuration file as follows: An `hazelcast.xml` file
stored either in the current working directory or at the root of the classpath, or a
location specified via the `hazelcast.config` system property. Spring Boot detects all
of these and allow for explicit location as well:
Hazelcast is used if a `hazelcast.xml` file can be found in the current working
directory, at the root of the classpath or a location specified via the `hazelcast.config`
system property. Spring Boot detects all of these and also allows for explicit location
using:
[source,properties,indent=0]
----
spring.cache.hazelcast.config=classpath:config/my-hazelcast.xml
----
[[boot-features-caching-provider-infinispan]]
==== Infinispan
Infinispan has no default configuration file location so it must be specified explicitly
(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
spring.cache.jcache.provider=com.acme.MyCachingProvider
spring.cache.jcache.config=classpath:acme.xml
----
......@@ -2456,7 +2446,7 @@ property.
==== 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):
following (in this order):
1. A cache spec defined by `spring.cache.guava.spec`
2. A `com.google.common.cache.CacheBuilderSpec` bean is defined
......
spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc
View file @ c7677d10
......@@ -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
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
''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
official starters. A third-party starter for `acme` will be typically named
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment