Polish docs

This commit is contained in:
Phillip Webb 2021-05-05 23:41:52 -07:00
parent aeea15be0f
commit d3207b107c
31 changed files with 92 additions and 76 deletions

View File

@ -16,7 +16,6 @@ In order to use the endpoint, a valid UAA token must be passed with the request.
If you want to fully disable the `/cloudfoundryapplication` endpoints, you can add the following setting to your `application.properties` file:
.application.properties
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
management:
@ -31,7 +30,6 @@ If you want to fully disable the `/cloudfoundryapplication` endpoints, you can a
By default, the security verification for `/cloudfoundryapplication` endpoints makes SSL calls to various Cloud Foundry services.
If your Cloud Foundry UAA or Cloud Controller services use self-signed certificates, you need to set the following property:
.application.properties
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
management:

View File

@ -791,17 +791,17 @@ The following table shows the default status mappings for the built-in statuses:
|===
| Status | Mapping
| DOWN
| SERVICE_UNAVAILABLE (503)
| `DOWN`
| `SERVICE_UNAVAILABLE` (`503`)
| OUT_OF_SERVICE
| SERVICE_UNAVAILABLE (503)
| `OUT_OF_SERVICE`
| `SERVICE_UNAVAILABLE` (`503`)
| UP
| No mapping by default, so http status is 200
| `UP`
| No mapping by default, so HTTP status is `200`
| UNKNOWN
| No mapping by default, so http status is 200
| `UNKNOWN`
| No mapping by default, so HTTP status is `200`
|===

View File

@ -67,14 +67,14 @@ You can register any number of `MeterRegistryCustomizer` beans to further config
[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/gettingstarted/commontags/MyMeterRegistryConfiguration.java
include::{docs-java}/actuator/metrics/gettingstarted/commontags/MyMeterRegistryConfiguration.java[]
----
You can apply customizations to particular registry implementations by being more specific about the generic type:
[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/gettingstarted/specifictype/MyMeterRegistryConfiguration.java
include::{docs-java}/actuator/metrics/gettingstarted/specifictype/MyMeterRegistryConfiguration.java[]
----
Spring Boot also <<actuator#actuator.metrics.supported,configures built-in instrumentation>> that you can control via configuration or dedicated annotation markers.
@ -229,7 +229,7 @@ An auto-configured `GraphiteConfig` and `Clock` beans are provided unless you de
[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/export/graphite/MyGraphiteConfiguration.java
include::{docs-java}/actuator/metrics/export/graphite/MyGraphiteConfiguration.java[]
----
@ -302,7 +302,7 @@ An auto-configured `JmxConfig` and `Clock` beans are provided unless you define
[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/actuator/metrics/export/jmx/MyJmxConfiguration.java
include::{docs-java}/actuator/metrics/export/jmx/MyJmxConfiguration.java[]
----

View File

@ -9,7 +9,7 @@
:sectnums:
:hide-uri-scheme:
:docinfo: shared,private
:chomp: tags formatters headers packages
:chomp: default headers packages
:spring-boot-artifactory-repo: snapshot
:github-tag: main
:spring-boot-version: current

View File

@ -161,10 +161,15 @@ The `$PORT` environment variable is assigned to us by the Heroku PaaS.
This should be everything you need.
The most common deployment workflow for Heroku deployments is to `git push` the code to production, as shown in the following example:
[source,shell,indent=0,subs="verbatim,quotes"]
[source,shell,indent=0,subs="verbatim"]
----
$ git push heroku main
----
Which will result in the following:
[indent=0,subs="verbatim,quotes"]
----
Initializing repository, *done*.
Counting objects: 95, *done*.
Delta compression using up to 8 threads.

View File

@ -66,12 +66,14 @@ Disable launch script configuration when building a jar file that is intended to
Heres how you can launch your jar with a `layertools` jar mode:
[source,shell,indent=0,subs="verbatim"]
----
$ java -Djarmode=layertools -jar my-app.jar
----
This will provide the following output:
[subs="verbatim"]
----
Usage:
java -Djarmode=layertools -jar my-app.jar
@ -85,6 +87,7 @@ Available commands:
The `extract` command can be used to easily split the application into layers to be added to the dockerfile.
Here's an example of a Dockerfile using `jarmode`.
[source,dockerfile,indent=0,subs="verbatim"]
----
FROM adoptopenjdk:11-jre-hotspot as builder
WORKDIR application
@ -103,9 +106,9 @@ ENTRYPOINT ["java", "org.springframework.boot.loader.JarLauncher"]
Assuming the above `Dockerfile` is in the current directory, your docker image can be built with `docker build .`, or optionally specifying the path to your application jar, as shown in the following example:
[indent=0]
[source,shell,indent=0,subs="verbatim"]
----
docker build --build-arg JAR_FILE=path/to/myapp.jar .
$ docker build --build-arg JAR_FILE=path/to/myapp.jar .
----
This is a multi-stage dockerfile.

View File

@ -34,7 +34,7 @@ Spring Boot provides auto-configuration for Spring MVC that works well with most
The auto-configuration adds the following features on top of Spring's defaults:
* Inclusion of `ContentNegotiatingViewResolver` and `BeanNameViewResolver` beans.
* Support for serving static resources, including support for WebJars (covered <<features#features.developing-web-applications.spring-mvc.static-content,later in this document>>)).
* Support for serving static resources, including support for WebJars (covered <<features#features.developing-web-applications.spring-mvc.static-content,later in this document>>).
* Automatic registration of `Converter`, `GenericConverter`, and `Formatter` beans.
* Support for `HttpMessageConverters` (covered <<features#features.developing-web-applications.spring-mvc.message-converters,later in this document>>).
* Automatic registration of `MessageCodesResolver` (covered <<features#features.developing-web-applications.spring-mvc.message-codes,later in this document>>).
@ -218,7 +218,7 @@ Nowadays, Content Negotiation is much more reliable.
There are other ways to deal with HTTP clients that don't consistently send proper "Accept" request headers.
Instead of using suffix matching, we can use a query parameter to ensure that requests like `"GET /projects/spring-boot?format=json"` will be mapped to `@GetMapping("/projects/spring-boot")`:
[source,yaml,indent=0,subs="verbatim",configblocks]
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
spring:
mvc:
@ -228,7 +228,7 @@ Instead of using suffix matching, we can use a query parameter to ensure that re
Or if you prefer to use a different parameter name:
[source,properties,indent=0,subs="verbatim"]
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
spring:
mvc:
@ -239,7 +239,7 @@ Or if you prefer to use a different parameter name:
Most standard media types are supported out-of-the-box, but you can also define new ones:
[source,yaml,indent=0,subs="verbatim",configblocks]
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
spring:
mvc:
@ -372,7 +372,7 @@ The name of the file should be the exact status code or a series mask.
For example, to map `404` to a static HTML file, your directory structure would be as follows:
[source,indent=0,subs="verbatim"]
[indent=0,subs="verbatim"]
----
src/
+- main/
@ -387,7 +387,7 @@ For example, to map `404` to a static HTML file, your directory structure would
To map all `5xx` errors by using a FreeMarker template, your directory structure would be as follows:
[source,indent=0,subs="verbatim"]
[indent=0,subs="verbatim"]
----
src/
+- main/

View File

@ -125,7 +125,9 @@ The following example shows how to specify two locations:
[source,shell,indent=0,subs="verbatim"]
----
$ java -jar myproject.jar --spring.config.location=optional:classpath:/default.properties,optional:classpath:/override.properties
$ java -jar myproject.jar --spring.config.location=\
optional:classpath:/default.properties,\
optional:classpath:/override.properties
----
TIP: Use the prefix `optional:` if the <<features#features.external-config.files.optional-prefix,locations are optional>> and you don't mind if they don't exist.
@ -671,7 +673,7 @@ If you wish you return a non-null instance of `Security` even when no properties
[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/features/externalconfig/typesafeconfigurationproperties/constructorbinding/nonnull/MyProperties.java[]
include::{docs-java}/features/externalconfig/typesafeconfigurationproperties/constructorbinding/nonnull/MyProperties.java[tag=*]
----

View File

@ -11,7 +11,7 @@ Spring Data provides additional projects that help you access a variety of NoSQL
* {spring-data-couchbase}[Couchbase]
* {spring-data-ldap}[LDAP]
Spring Boot provides auto-configuration for Redis, MongoDB, Neo4j, Elasticsearch, Solr Cassandra, Couchbase, and LDAP.
Spring Boot provides auto-configuration for Redis, MongoDB, Neo4j, Solr, Elasticsearch, Cassandra, Couchbase, LDAP and InfluxDB.
You can make use of the other projects, but you must configure them yourself.
Refer to the appropriate reference documentation at {spring-data}.

View File

@ -272,6 +272,7 @@ You can register multiple relying parties under the `spring.security.saml2.relyi
- certificate-location: "path-to-verification-cert"
entity-id: "remote-idp-entity-id1"
sso-url: "https://remoteidp1.sso.url"
my-relying-party2:
signing:
credentials:

View File

@ -171,7 +171,7 @@ include::{docs-java}/features/springapplication/customizingspringapplication/MyA
----
NOTE: The constructor arguments passed to `SpringApplication` are configuration sources for Spring beans.
In most cases, these are references to `@Configuration` classes, but they could also be references to XML configuration or to packages that should be scanned.
In most cases, these are references to `@Configuration` classes, but they could also be direct references `@Component` classes.
It is also possible to configure the `SpringApplication` by using an `application.properties` file.
See _<<features#features.external-config>>_ for details.
@ -395,7 +395,7 @@ TIP: If you want to know on which HTTP port the application is running, get the
=== Application Startup tracking
During the application startup, the `SpringApplication` and the `ApplicationContext` perform many tasks related to the application lifecycle,
the beans lifecycle or even processing application events.
With {spring-framework-api}/core/metrics/ApplicationStartup.html[`ApplicationStartup`], Spring Framework {spring-framework-docs}/core.html#context-functionality-startup[allows you to track the application startup sequence with ``StartupStep``s].
With {spring-framework-api}/core/metrics/ApplicationStartup.html[`ApplicationStartup`], Spring Framework {spring-framework-docs}/core.html#context-functionality-startup[allows you to track the application startup sequence with `StartupStep` objects].
This data can be collected for profiling purposes, or just to have a better understanding of an application startup process.
You can choose an `ApplicationStartup` implementation when setting up the `SpringApplication` instance.

View File

@ -105,7 +105,7 @@ For instance, if you use the {tomcat-docs}/jdbc-pool.html#Common_Attributes[Tomc
test-on-borrow: true
----
This will set the pool to wait 10000 ms before throwing an exception if no connection is available, limit the maximum number of connections to 50 and validate the connection before borrowing it from the pool.
This will set the pool to wait 10000ms before throwing an exception if no connection is available, limit the maximum number of connections to 50ms and validate the connection before borrowing it from the pool.
@ -253,18 +253,24 @@ By default, JPA databases are automatically created *only* if you use an embedde
You can explicitly configure JPA settings by using `+spring.jpa.*+` properties.
For example, to create and drop tables you can add the following line to your `application.properties`:
[indent=0]
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
spring.jpa.hibernate.ddl-auto=create-drop
spring:
jpa:
hibernate.ddl-auto: "create-drop"
----
NOTE: Hibernate's own internal property name for this (if you happen to remember it better) is `hibernate.hbm2ddl.auto`.
You can set it, along with other Hibernate native properties, by using `+spring.jpa.properties.*+` (the prefix is stripped before adding them to the entity manager).
The following line shows an example of setting JPA properties for Hibernate:
[indent=0]
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
----
spring.jpa.properties.hibernate.globally_quoted_identifiers=true
spring:
jpa:
properties:
hibernate:
"globally_quoted_identifiers": "true"
----
The line in the preceding example passes a value of `true` for the `hibernate.globally_quoted_identifiers` property to the Hibernate entity manager.

View File

@ -4,7 +4,8 @@ If you have Spring WebFlux on your classpath, you can also choose to use `WebCli
Compared to `RestTemplate`, this client has a more functional feel and is fully reactive.
You can learn more about the `WebClient` in the dedicated {spring-framework-docs}/web-reactive.html#webflux-client[section in the Spring Framework docs].
Spring Boot creates and pre-configures a `WebClient.Builder` for you; it is strongly advised to inject it in your components and use it to create `WebClient` instances.
Spring Boot creates and pre-configures a `WebClient.Builder` for you.
It is strongly advised to inject it in your components and use it to create `WebClient` instances.
Spring Boot is configuring that builder to share HTTP resources, reflect codecs setup in the same fashion as the server ones (see <<features#features.developing-web-applications.spring-webflux.httpcodecs,WebFlux HTTP codecs auto-configuration>>), and more.
The following code shows a typical example:

View File

@ -59,18 +59,6 @@ Open your favorite text editor and add the following:
<version>{spring-boot-version}</version>
</parent>
<description/>
<developers>
<developer/>
</developers>
<licenses>
<license/>
</licenses>
<scm>
<url/>
</scm>
<url/>
<!-- Additional lines to be added here... -->
ifeval::["{spring-boot-artifactory-repo}" != "release"]
@ -161,7 +149,7 @@ We step through the important parts in the next few sections.
[[getting-started.first-application.code.mvc-annotations]]
==== The @RestController and @RequestMapping Annotations
The first annotation on our `Example` class is `@RestController`.
The first annotation on our `MyApplication` class is `@RestController`.
This is known as a _stereotype_ annotation.
It provides hints for people reading the code and for Spring that the class plays a specific role.
In this case, our class is a web `@Controller`, so Spring considers it when handling incoming web requests.
@ -196,7 +184,7 @@ The final part of our application is the `main` method.
This is a standard method that follows the Java convention for an application entry point.
Our main method delegates to Spring Boot's `SpringApplication` class by calling `run`.
`SpringApplication` bootstraps our application, starting Spring, which, in turn, starts the auto-configured Tomcat web server.
We need to pass `Example.class` as an argument to the `run` method to tell `SpringApplication` which is the primary Spring component.
We need to pass `MyApplication.class` as an argument to the `run` method to tell `SpringApplication` which is the primary Spring component.
The `args` array is also passed through to expose any command-line arguments.

View File

@ -68,7 +68,7 @@ More details on getting started with Spring Boot and Gradle can be found in the
The Spring Boot CLI (Command Line Interface) is a command line tool that you can use to quickly prototype with Spring.
It lets you run https://groovy-lang.org/[Groovy] scripts, which means that you have a familiar Java-like syntax without so much boilerplate code.
You do not need to use the CLI to work with Spring Boot, but it is definitely the quickest way to get a Spring application off the ground.
You do not need to use the CLI to work with Spring Boot, but it is a quick way to get a Spring application off the ground without an IDE.

View File

@ -1,6 +1,6 @@
[[getting-started.introducing-spring-boot]]
== Introducing Spring Boot
Spring Boot helps you to create stand-alone, production-grade Spring-based Applications that you can run.
Spring Boot helps you to create stand-alone, production-grade Spring-based applications that you can run.
We take an opinionated view of the Spring platform and third-party libraries, so that you can get started with minimum fuss.
Most Spring Boot applications need very little Spring configuration.

View File

@ -1,6 +1,6 @@
[[getting-started.system-requirements]]
== System Requirements
Spring Boot {spring-boot-version} requires https://www.java.com[Java 8] and is compatible up to Java 16 (included).
Spring Boot {spring-boot-version} requires https://www.java.com[Java 8] and is compatible up to and including Java 16.
{spring-framework-docs}/[Spring Framework {spring-framework-version}] or above is also required.
Explicit build support is provided for the following build tools:

View File

@ -161,7 +161,6 @@ And the following example shows one way to set up the starters in Gradle:
}
}
}
}
----
NOTE: The Log4j starters gather together the dependencies for common logging requirements (such as having Tomcat use `java.util.logging` but configuring the output using Log4j 2).

View File

@ -7,7 +7,7 @@ Testcontainers can be used in a Spring Boot test as follows:
[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/howto/testcontainers/vanilla/MyIntegrationTests.java
include::{docs-java}/howto/testcontainers/vanilla/MyIntegrationTests.java[]
----
This will start up a docker container running Neo4j (if Docker is running locally) before any of the tests are run.
@ -17,7 +17,7 @@ This can be done with a static `@DynamicPropertySource` method that allows addin
[source,java,indent=0,subs="verbatim"]
----
include::{docs-java}/howto/testcontainers/dynamicproperties/MyIntegrationTests.java
include::{docs-java}/howto/testcontainers/dynamicproperties/MyIntegrationTests.java[]
----
The above configuration allows Neo4j-related beans in the application to communicate with Neo4j running inside the Testcontainers-managed Docker container.

View File

@ -118,7 +118,7 @@ The starters contain a lot of the dependencies that you need to get a project up
All **official** starters follow a similar naming pattern; `+spring-boot-starter-*+`, where `+*+` is a particular type of application.
This naming structure is intended to help when you need to find a starter.
The Maven integration in many IDEs lets you search dependencies by name.
For example, with the appropriate Eclipse or STS plugin installed, you can press `ctrl-space` in the POM editor and type "`spring-boot-starter`" for a complete list.
For example, with the appropriate Eclipse or Spring Tools plugin installed, you can press `ctrl-space` in the POM editor and type "`spring-boot-starter`" for a complete list.
As explained in the "`<<features#features.developing-auto-configuration.custom-starter,Creating Your Own Starter>>`" section, third party starters should not start with `spring-boot`, as it is reserved for official Spring Boot artifacts.
Rather, a third-party starter typically starts with the name of the project.

View File

@ -358,7 +358,7 @@ The remote client application is designed to be run from within your IDE.
You need to run `org.springframework.boot.devtools.RemoteSpringApplication` with the same classpath as the remote project that you connect to.
The application's single required argument is the remote URL to which it connects.
For example, if you are using Eclipse or STS and you have a project named `my-app` that you have deployed to Cloud Foundry, you would do the following:
For example, if you are using Eclipse or Spring Tools and you have a project named `my-app` that you have deployed to Cloud Foundry, you would do the following:
* Select `Run Configurations...` from the `Run` menu.
* Create a new `Java Application` "`launch configuration`".
@ -368,7 +368,7 @@ For example, if you are using Eclipse or STS and you have a project named `my-ap
A running remote client might resemble the following listing:
[indent=0,subs="verbatim"]
[indent=0,subs="verbatim,attributes"]
----
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ ___ _ \ \ \ \

View File

@ -22,7 +22,7 @@ Maven includes plugins for https://maven.apache.org/plugins/maven-eclipse-plugin
Gradle offers plugins for {gradle-docs}/userguide.html[various IDEs].
TIP: If you accidentally run a web application twice, you see a "`Port already in use`" error.
STS users can use the `Relaunch` button rather than the `Run` button to ensure that any existing instance is closed.
Spring Tools users can use the `Relaunch` button rather than the `Run` button to ensure that any existing instance is closed.

View File

@ -27,7 +27,10 @@ public class MyReactiveHealthIndicator implements ReactiveHealthIndicator {
@Override
public Mono<Health> health() {
return doHealthCheck().onErrorResume((exception) -> Mono.just(new Health.Builder().down(exception).build()));
// @formatter:off
return doHealthCheck().onErrorResume((exception) ->
Mono.just(new Health.Builder().down(exception).build()));
// @formatter:on
}
private Mono<Health> doHealthCheck() {

View File

@ -28,11 +28,13 @@ public class MyCouchbaseCacheManagerConfiguration {
@Bean
public CouchbaseCacheManagerBuilderCustomizer myCouchbaseCacheManagerBuilderCustomizer() {
// @formatter:off
return (builder) -> builder
.withCacheConfiguration("cache1",
CouchbaseCacheConfiguration.defaultCacheConfig().entryExpiry(Duration.ofSeconds(10)))
.withCacheConfiguration("cache2",
CouchbaseCacheConfiguration.defaultCacheConfig().entryExpiry(Duration.ofMinutes(1)));
.withCacheConfiguration("cache1", CouchbaseCacheConfiguration
.defaultCacheConfig().entryExpiry(Duration.ofSeconds(10)))
.withCacheConfiguration("cache2", CouchbaseCacheConfiguration
.defaultCacheConfig().entryExpiry(Duration.ofMinutes(1)));
// @formatter:on
}

View File

@ -28,11 +28,13 @@ public class MyRedisCacheManagerConfiguration {
@Bean
public RedisCacheManagerBuilderCustomizer myRedisCacheManagerBuilderCustomizer() {
// @formatter:off
return (builder) -> builder
.withCacheConfiguration("cache1",
RedisCacheConfiguration.defaultCacheConfig().entryTtl(Duration.ofSeconds(10)))
.withCacheConfiguration("cache2",
RedisCacheConfiguration.defaultCacheConfig().entryTtl(Duration.ofMinutes(1)));
.withCacheConfiguration("cache1", RedisCacheConfiguration
.defaultCacheConfig().entryTtl(Duration.ofSeconds(10)))
.withCacheConfiguration("cache2", RedisCacheConfiguration
.defaultCacheConfig().entryTtl(Duration.ofMinutes(1)));
// @formatter:on
}

View File

@ -22,7 +22,7 @@ import org.springframework.boot.autoconfigure.logging.ConditionEvaluationReportL
import org.springframework.boot.logging.LogLevel;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;
public class MyConditionEvaluationReportingTests {
class MyConditionEvaluationReportingTests {
@Test
void autoConfigTest() {

View File

@ -44,7 +44,7 @@ public class MyRestController {
}
@GetMapping("/{user}/customers")
Flux<Customer> getUserCustomers(@PathVariable Long userId) {
public Flux<Customer> getUserCustomers(@PathVariable Long userId) {
return this.userRepository.findById(userId).flatMapMany(this.customerRepository::findByUser);
}

View File

@ -32,7 +32,7 @@ public class MyBean {
this.amqpTemplate = amqpTemplate;
}
// @fold:on
// @fold:on // ...
public void someMethod() {
this.amqpAdmin.getQueueInfo("someQueue");
}

View File

@ -34,9 +34,12 @@ public class MyKafkaStreamsConfiguration {
@Bean
public KStream<Integer, String> kStream(StreamsBuilder streamsBuilder) {
KStream<Integer, String> stream = streamsBuilder.stream("ks1In");
stream.map((k, v) -> new KeyValue<>(k, v.toUpperCase())).to("ks1Out",
Produced.with(Serdes.Integer(), new JsonSerde<>()));
stream.map(this::uppercaseValue).to("ks1Out", Produced.with(Serdes.Integer(), new JsonSerde<>()));
return stream;
}
private KeyValue<Integer, String> uppercaseValue(Integer key, String value) {
return new KeyValue<>(key, value.toUpperCase());
}
}

View File

@ -32,10 +32,10 @@ public class MyBean {
this.databaseClient = databaseClient;
}
// @fold: on // ...
// @fold:on // ...
public Flux<Map<String, Object>> someMethod() {
return this.databaseClient.sql("select * from user").fetch().all();
}
// @fold: off
// @fold:off
}

View File

@ -31,10 +31,13 @@ public class MyReactorNettyClientConfiguration {
@Bean
ClientHttpConnector clientHttpConnector(ReactorResourceFactory resourceFactory) {
// @formatter:off
HttpClient httpClient = HttpClient.create(resourceFactory.getConnectionProvider())
.runOn(resourceFactory.getLoopResources()).option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 60000)
.runOn(resourceFactory.getLoopResources())
.option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 60000)
.doOnConnected((connection) -> connection.addHandlerLast(new ReadTimeoutHandler(60)));
return new ReactorClientHttpConnector(httpClient);
// @formatter:on
}
}