From d91347291978429ba27c0bdd4591debdcd959eb4 Mon Sep 17 00:00:00 2001 From: Scott Frederick Date: Fri, 28 Apr 2023 14:31:01 -0500 Subject: [PATCH] Add Kotlin samples and polish SSL bundle documentation Closes gh-35105 --- .../src/docs/asciidoc/features/ssl.adoc | 12 +++++- .../src/docs/asciidoc/io/rest-client.adoc | 9 ++++- .../io/restclient/resttemplate/Details.java | 4 +- .../resttemplate/ssl/MyService.java | 38 +++++++++++++++++++ .../docs/io/restclient/webclient/Details.java | 21 ++++++++++ .../io/restclient/webclient/MyService.java | 1 - .../restclient/webclient/ssl/MyService.java | 2 +- .../docs/features/ssl/bundles/MyComponent.kt | 31 +++++++++++++++ .../io/restclient/resttemplate/MyService.kt | 6 +-- .../restclient/resttemplate/ssl/MyService.kt | 37 ++++++++++++++++++ .../docs/io/restclient/webclient/Details.kt | 19 ++++++++++ .../docs/io/restclient/webclient/MyService.kt | 7 +--- .../io/restclient/webclient/ssl/MyService.kt | 10 ++--- 13 files changed, 174 insertions(+), 23 deletions(-) create mode 100644 spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/resttemplate/ssl/MyService.java create mode 100644 spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/webclient/Details.java create mode 100644 spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/ssl/bundles/MyComponent.kt create mode 100644 spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/resttemplate/ssl/MyService.kt create mode 100644 spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/webclient/Details.kt diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/ssl.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/ssl.adoc index de53ec48de..161446ebab 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/ssl.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/ssl.adoc @@ -84,14 +84,22 @@ See {spring-boot-autoconfigure-module-code}/ssl/PemSslBundleProperties.java[PemS [[features.ssl.applying]] === Applying SSL Bundles Once configured using properties, SSL bundles can be referred to by name in configuration properties for various types of connections that are auto-configured by Spring Boot. -See the sections on <> and <> for further information. +See the sections on <>, <>, and <> for further information. [[features.ssl.bundles]] === Using SSL Bundles Spring Boot auto-configures a bean of type `SslBundles` that provides access to each of the named bundles configured using the `spring.ssl.bundle` properties. -An `SslBundle` can be retrieved from the auto-configured `SslBundles` bean and used to create a `javax.net.ssl.SSLContext` or objects of other types from the `java.net.ssl` package that are typically used to configure SSL connectivity in other APIs. + +An `SslBundle` can be retrieved from the auto-configured `SslBundles` bean and used to create objects that are used to configure SSL connectivity in client libraries. +The `SslBundle` provides a layered approach of obtaining these SSL objects: + +- `getStores()` provides access to the key store and trust store `java.security.KeyStore` instances as well as any required key store password. +- `getManagers()` provides access to the `java.net.ssl.KeyManagerFactory` and `java.net.ssl.TrustManagerFactory` instances as well as the `java.net.ssl.KeyManager` and `java.net.ssl.TrustManager` arrays that they create. +- `createSslContext()` provides a convenient way to obtain a new `java.net.ssl.SSLContext` instance. + +In addition, the `SslBundle` provides details about the key being used, the protocol to use and any option that should be applied to the SSL engine. The following example shows retrieving an `SslBundle` and using it to create an `SSLContext`: diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/io/rest-client.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/io/rest-client.adoc index 56e778a52e..9ae6995c29 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/io/rest-client.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/io/rest-client.adoc @@ -15,7 +15,6 @@ include::code:MyService[] `RestTemplateBuilder` includes a number of useful methods that can be used to quickly configure a `RestTemplate`. For example, to add BASIC authentication support, you can use `builder.basicAuthentication("user", "password").build()`. -To add SSL support using an <>, you can use `builder.setSslBundle(sslBundle).build()`. @@ -45,6 +44,14 @@ In addition to replacing the auto-configured builder, this also prevents any `Re +[[io.rest-client.resttemplate.ssl]] +==== RestTemplate SSL Support +If you need custom SSL configuration on the `RestTemplate`, you can apply an <> to the `RestTemplateBuilder` as shown in this example: + +include::code:MyService[] + + + [[io.rest-client.webclient]] === WebClient If you have Spring WebFlux on your classpath, you can also choose to use `WebClient` to call remote REST services. diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/resttemplate/Details.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/resttemplate/Details.java index f4de791fb6..03e839cc4a 100644 --- a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/resttemplate/Details.java +++ b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/resttemplate/Details.java @@ -1,5 +1,5 @@ /* - * Copyright 2012-2021 the original author or authors. + * Copyright 2012-2023 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -16,6 +16,6 @@ package org.springframework.boot.docs.io.restclient.resttemplate; -class Details { +public class Details { } diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/resttemplate/ssl/MyService.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/resttemplate/ssl/MyService.java new file mode 100644 index 0000000000..5d5407faf9 --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/resttemplate/ssl/MyService.java @@ -0,0 +1,38 @@ +/* + * Copyright 2012-2023 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.boot.docs.io.restclient.resttemplate.ssl; + +import org.springframework.boot.docs.io.restclient.resttemplate.Details; +import org.springframework.boot.ssl.SslBundles; +import org.springframework.boot.web.client.RestTemplateBuilder; +import org.springframework.stereotype.Service; +import org.springframework.web.client.RestTemplate; + +@Service +public class MyService { + + private final RestTemplate restTemplate; + + public MyService(RestTemplateBuilder restTemplateBuilder, SslBundles sslBundles) { + this.restTemplate = restTemplateBuilder.setSslBundle(sslBundles.getBundle("mybundle")).build(); + } + + public Details someRestCall(String name) { + return this.restTemplate.getForObject("/{name}/details", Details.class, name); + } + +} diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/webclient/Details.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/webclient/Details.java new file mode 100644 index 0000000000..58a2640d4b --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/webclient/Details.java @@ -0,0 +1,21 @@ +/* + * Copyright 2012-2023 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.boot.docs.io.restclient.webclient; + +public class Details { + +} diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/webclient/MyService.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/webclient/MyService.java index a632d9c637..1757276d2d 100644 --- a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/webclient/MyService.java +++ b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/webclient/MyService.java @@ -16,7 +16,6 @@ package org.springframework.boot.docs.io.restclient.webclient; -import org.neo4j.cypherdsl.core.Relationship.Details; import reactor.core.publisher.Mono; import org.springframework.stereotype.Service; diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/webclient/ssl/MyService.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/webclient/ssl/MyService.java index ef851ecbb6..7ed0790f8f 100644 --- a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/webclient/ssl/MyService.java +++ b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/io/restclient/webclient/ssl/MyService.java @@ -16,10 +16,10 @@ package org.springframework.boot.docs.io.restclient.webclient.ssl; -import org.neo4j.cypherdsl.core.Relationship.Details; import reactor.core.publisher.Mono; import org.springframework.boot.autoconfigure.web.reactive.function.client.WebClientSsl; +import org.springframework.boot.docs.io.restclient.webclient.Details; import org.springframework.stereotype.Service; import org.springframework.web.reactive.function.client.WebClient; diff --git a/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/ssl/bundles/MyComponent.kt b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/ssl/bundles/MyComponent.kt new file mode 100644 index 0000000000..a9b958039b --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/ssl/bundles/MyComponent.kt @@ -0,0 +1,31 @@ +/* + * Copyright 2012-2023 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.springframework.boot.docs.features.ssl.bundles + +import org.springframework.boot.ssl.SslBundles +import org.springframework.stereotype.Component + +@Component +@Suppress("UNUSED_VARIABLE") +class MyComponent(sslBundles: SslBundles) { + + init { + val sslBundle = sslBundles.getBundle("mybundle") + val sslContext = sslBundle.createSslContext() + // do something with the created sslContext + } + +} diff --git a/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/resttemplate/MyService.kt b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/resttemplate/MyService.kt index adc6f6dbce..859eb91d07 100644 --- a/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/resttemplate/MyService.kt +++ b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/resttemplate/MyService.kt @@ -20,7 +20,6 @@ import org.springframework.boot.web.client.RestTemplateBuilder import org.springframework.stereotype.Service import org.springframework.web.client.RestTemplate -@Suppress("UNUSED_PARAMETER") @Service class MyService(restTemplateBuilder: RestTemplateBuilder) { @@ -31,10 +30,7 @@ class MyService(restTemplateBuilder: RestTemplateBuilder) { } fun someRestCall(name: String): Details { - return restTemplate.getForObject( - "/{name}/details", - Details::class.java, name - )!! + return restTemplate.getForObject("/{name}/details", Details::class.java, name)!! } } \ No newline at end of file diff --git a/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/resttemplate/ssl/MyService.kt b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/resttemplate/ssl/MyService.kt new file mode 100644 index 0000000000..5787b7f4d8 --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/resttemplate/ssl/MyService.kt @@ -0,0 +1,37 @@ +/* + * Copyright 2012-2023 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.springframework.boot.docs.io.restclient.resttemplate.ssl + +import org.springframework.boot.docs.io.restclient.resttemplate.Details +import org.springframework.boot.ssl.SslBundles +import org.springframework.boot.web.client.RestTemplateBuilder +import org.springframework.stereotype.Service +import org.springframework.web.client.RestTemplate + +@Service +class MyService(restTemplateBuilder: RestTemplateBuilder, sslBundles: SslBundles) { + + private val restTemplate: RestTemplate + + init { + restTemplate = restTemplateBuilder.setSslBundle(sslBundles.getBundle("mybundle")).build() + } + + fun someRestCall(name: String): Details { + return restTemplate.getForObject("/{name}/details", Details::class.java, name)!! + } + +} diff --git a/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/webclient/Details.kt b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/webclient/Details.kt new file mode 100644 index 0000000000..e74cfeae57 --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/webclient/Details.kt @@ -0,0 +1,19 @@ +/* + * Copyright 2012-2023 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.boot.docs.io.restclient.webclient + +class Details diff --git a/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/webclient/MyService.kt b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/webclient/MyService.kt index 6caf787320..4c31830681 100644 --- a/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/webclient/MyService.kt +++ b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/webclient/MyService.kt @@ -16,7 +16,6 @@ package org.springframework.boot.docs.io.restclient.webclient -import org.neo4j.cypherdsl.core.Relationship import org.springframework.stereotype.Service import org.springframework.web.reactive.function.client.WebClient import reactor.core.publisher.Mono @@ -30,10 +29,8 @@ class MyService(webClientBuilder: WebClient.Builder) { webClient = webClientBuilder.baseUrl("https://example.org").build() } - fun someRestCall(name: String?): Mono { - return webClient.get().uri("/{name}/details", name).retrieve().bodyToMono( - Relationship.Details::class.java - ) + fun someRestCall(name: String?): Mono
{ + return webClient.get().uri("/{name}/details", name).retrieve().bodyToMono(Details::class.java) } } diff --git a/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/webclient/ssl/MyService.kt b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/webclient/ssl/MyService.kt index 4b2219dfe7..3ddac190f9 100644 --- a/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/webclient/ssl/MyService.kt +++ b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/io/restclient/webclient/ssl/MyService.kt @@ -1,5 +1,5 @@ /* - * Copyright 2012-2022 the original author or authors. + * Copyright 2012-2023 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -16,8 +16,8 @@ package org.springframework.boot.docs.io.restclient.webclient.ssl -import org.neo4j.cypherdsl.core.Relationship import org.springframework.boot.autoconfigure.web.reactive.function.client.WebClientSsl +import org.springframework.boot.docs.io.restclient.webclient.Details import org.springframework.stereotype.Service import org.springframework.web.reactive.function.client.WebClient import reactor.core.publisher.Mono @@ -31,10 +31,8 @@ class MyService(webClientBuilder: WebClient.Builder, ssl: WebClientSsl) { webClient = webClientBuilder.baseUrl("https://example.org").apply(ssl.fromBundle("mybundle")).build() } - fun someRestCall(name: String?): Mono { - return webClient.get().uri("/{name}/details", name).retrieve().bodyToMono( - Relationship.Details::class.java - ) + fun someRestCall(name: String?): Mono
{ + return webClient.get().uri("/{name}/details", name).retrieve().bodyToMono(Details::class.java) } }