diff --git a/spring-boot-docs/src/main/asciidoc/getting-started.adoc b/spring-boot-docs/src/main/asciidoc/getting-started.adoc index 31bcab2dfe..c615f5f3dd 100644 --- a/spring-boot-docs/src/main/asciidoc/getting-started.adoc +++ b/spring-boot-docs/src/main/asciidoc/getting-started.adoc @@ -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 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 fe609796ab..5fbd459905 100644 --- a/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/production-ready-features.adoc @@ -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 ---- 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 a58b5a6358..6ee4a40092 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -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 + 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). +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. +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. +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 `@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). +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 + 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`). +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 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): * <> * <> @@ -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 diff --git a/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc b/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc index 3e06876cab..182a9c7a4f 100644 --- a/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc +++ b/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc @@ -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