From deac8e556e10f8ec352f5dae36e54e897fea2b2e Mon Sep 17 00:00:00 2001 From: sdeleuze Date: Wed, 27 Dec 2017 16:50:19 +0100 Subject: [PATCH] Improve Kotlin extensions doc about type erasure Since type erasure can be fixed only when using ParameterizedTypeReference based Java methods, RestOperations and WebFlux API documentation should be updated to specify which extensions are subject to type erasure, and which are not. Issue: SPR-16273 --- .../web/client/RestOperationsExtensions.kt | 110 ++++++++++++------ .../client/ClientResponseExtensions.kt | 12 +- .../function/client/WebClientExtensions.kt | 9 +- .../server/ServerRequestExtensions.kt | 6 +- .../server/ServerResponseExtensions.kt | 8 +- 5 files changed, 96 insertions(+), 49 deletions(-) diff --git a/spring-web/src/main/kotlin/org/springframework/web/client/RestOperationsExtensions.kt b/spring-web/src/main/kotlin/org/springframework/web/client/RestOperationsExtensions.kt index 70a00f03ba..274bcb9ea1 100644 --- a/spring-web/src/main/kotlin/org/springframework/web/client/RestOperationsExtensions.kt +++ b/spring-web/src/main/kotlin/org/springframework/web/client/RestOperationsExtensions.kt @@ -24,8 +24,10 @@ import org.springframework.http.ResponseEntity import java.net.URI /** - * Extension for [RestOperations.getForObject] avoiding specifying the type - * parameter thanks to Kotlin reified type parameters. + * Extension for [RestOperations.getForObject] providing a `getForObject(...)` + * variant leveraging Kotlin reified type parameters. Like the original Java method, this + * extension is subject to type erasure. Use [exchange] if you need to retain actual + * generic type arguments. * * @author Jon Schneider * @author Sebastien Deleuze @@ -36,8 +38,10 @@ inline fun RestOperations.getForObject(url: String, vararg uriV getForObject(url, T::class.java, *uriVariables) /** - * Extension for [RestOperations.getForObject] avoiding specifying the type - * parameter thanks to Kotlin reified type parameters. + * Extension for [RestOperations.getForObject] providing a `getForObject(...)` + * variant leveraging Kotlin reified type parameters. Like the original Java method, this + * extension is subject to type erasure. Use [exchange] if you need to retain actual + * generic type arguments. * * @author Jon Schneider * @author Sebastien Deleuze @@ -48,8 +52,10 @@ inline fun RestOperations.getForObject(url: String, uriVariable getForObject(url, T::class.java, uriVariables) /** - * Extension for [RestOperations.getForObject] avoiding specifying the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.getForObject] providing a `getForObject(...)` + * variant leveraging Kotlin reified type parameters. Like the original Java method, this + * extension is subject to type erasure. Use [exchange] if you need to retain actual + * generic type arguments. * * @author Jon Schneider * @author Sebastien Deleuze @@ -60,8 +66,10 @@ inline fun RestOperations.getForObject(url: URI): T? = getForObject(url, T::class.java) /** - * Extension for [RestOperations.getForEntity] avoiding requiring the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.getForEntity] providing a `getForEntity(...)` + * variant leveraging Kotlin reified type parameters. Like the original Java method, this + * extension is subject to type erasure. Use [exchange] if you need to retain actual + * generic type arguments. * * @author Sebastien Deleuze * @since 5.0.2 @@ -71,8 +79,10 @@ inline fun RestOperations.getForEntity(url: URI): ResponseEntit getForEntity(url, T::class.java) /** - * Extension for [RestOperations.getForEntity] avoiding requiring the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.getForEntity] providing a `getForEntity(...)` + * variant leveraging Kotlin reified type parameters. Like the original Java method, this + * extension is subject to type erasure. Use [exchange] if you need to retain actual + * generic type arguments. * * @author Jon Schneider * @author Sebastien Deleuze @@ -83,8 +93,10 @@ inline fun RestOperations.getForEntity(url: String, vararg uriV getForEntity(url, T::class.java, *uriVariables) /** - * Extension for [RestOperations.getForEntity] avoiding requiring the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.getForEntity] providing a `getForEntity(...)` + * variant leveraging Kotlin reified type parameters. Like the original Java method, this + * extension is subject to type erasure. Use [exchange] if you need to retain actual + * generic type arguments. * * @author Sebastien Deleuze * @since 5.0.2 @@ -94,8 +106,10 @@ inline fun RestOperations.getForEntity(url: String, uriVariable getForEntity(url, T::class.java, uriVariables) /** - * Extension for [RestOperations.patchForObject] avoiding specifying the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.patchForObject] providing a `patchForObject(...)` + * variant leveraging Kotlin reified type parameters. Like the original Java method, this + * extension is subject to type erasure. Use [exchange] if you need to retain actual + * generic type arguments. * * @author Sebastien Deleuze * @since 5.0.2 @@ -105,8 +119,10 @@ inline fun RestOperations.patchForObject(url: String, request: patchForObject(url, request, T::class.java, *uriVariables) /** - * Extension for [RestOperations.patchForObject] avoiding specifying the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.patchForObject] providing a `patchForObject(...)` + * variant leveraging Kotlin reified type parameters. Like the original Java method, this + * extension is subject to type erasure. Use [exchange] if you need to retain actual + * generic type arguments. * * @author Sebastien Deleuze * @since 5.0.2 @@ -116,8 +132,10 @@ inline fun RestOperations.patchForObject(url: String, request: patchForObject(url, request, T::class.java, uriVariables) /** - * Extension for [RestOperations.patchForObject] avoiding specifying the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.patchForObject] providing a `patchForObject(...)` + * variant leveraging Kotlin reified type parameters. Like the original Java method, this + * extension is subject to type erasure. Use [exchange] if you need to retain actual + * generic type arguments. * * @author Sebastien Deleuze * @since 5.0.2 @@ -127,8 +145,10 @@ inline fun RestOperations.patchForObject(url: URI, request: Any patchForObject(url, request, T::class.java) /** - * Extension for [RestOperations.postForObject] avoiding specifying the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.postForObject] providing a `postForObject(...)` + * variant leveraging Kotlin reified type parameters. Like the original Java method, this + * extension is subject to type erasure. Use [exchange] if you need to retain actual + * generic type arguments. * * @author Jon Schneider * @author Sebastien Deleuze @@ -139,8 +159,10 @@ inline fun RestOperations.postForObject(url: String, request: A postForObject(url, request, T::class.java, *uriVariables) /** - * Extension for [RestOperations.postForObject] avoiding specifying the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.postForObject] providing a `postForObject(...)` + * variant leveraging Kotlin reified type parameters. Like the original Java method, this + * extension is subject to type erasure. Use [exchange] if you need to retain actual + * generic type arguments. * * @author Jon Schneider * @author Sebastien Deleuze @@ -151,8 +173,10 @@ inline fun RestOperations.postForObject(url: String, request: A postForObject(url, request, T::class.java, uriVariables) /** - * Extension for [RestOperations.postForObject] avoiding specifying the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.postForObject] providing a `postForObject(...)` + * variant leveraging Kotlin reified type parameters. Like the original Java method, this + * extension is subject to type erasure. Use [exchange] if you need to retain actual + * generic type arguments. * * @author Jon Schneider * @author Sebastien Deleuze @@ -163,8 +187,10 @@ inline fun RestOperations.postForObject(url: URI, request: Any) postForObject(url, request, T::class.java) /** - * Extension for [RestOperations.postForEntity] avoiding specifying the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.postForEntity] providing a `postForEntity(...)` + * variant leveraging Kotlin reified type parameters. Like the original Java method, this + * extension is subject to type erasure. Use [exchange] if you need to retain actual + * generic type arguments. * * @author Jon Schneider * @author Sebastien Deleuze @@ -176,8 +202,10 @@ inline fun RestOperations.postForEntity(url: String, request: A postForEntity(url, request, T::class.java, *uriVariables) /** - * Extension for [RestOperations.postForEntity] avoiding specifying the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.postForEntity] providing a `postForEntity(...)` + * variant leveraging Kotlin reified type parameters. Like the original Java method, this + * extension is subject to type erasure. Use [exchange] if you need to retain actual + * generic type arguments. * * @author Jon Schneider * @author Sebastien Deleuze @@ -189,8 +217,10 @@ inline fun RestOperations.postForEntity(url: String, request: A postForEntity(url, request, T::class.java, uriVariables) /** - * Extension for [RestOperations.postForEntity] avoiding specifying the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.postForEntity] providing a `postForEntity(...)` + * variant leveraging Kotlin reified type parameters. Like the original Java method, this + * extension is subject to type erasure. Use [exchange] if you need to retain actual + * generic type arguments. * * @author Jon Schneider * @author Sebastien Deleuze @@ -201,8 +231,9 @@ inline fun RestOperations.postForEntity(url: URI, request: Any) postForEntity(url, request, T::class.java) /** - * Extension for [RestOperations.exchange] avoiding specifying the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.exchange] providing an `exchange(...)` + * variant leveraging Kotlin reified type parameters. This extension is not subject to + * type erasure and retains actual generic type arguments. * * @author Jon Schneider * @author Sebastien Deleuze @@ -214,8 +245,9 @@ inline fun RestOperations.exchange(url: String, method: HttpMet exchange(url, method, requestEntity, object : ParameterizedTypeReference() {}, *uriVariables) /** - * Extension for [RestOperations.exchange] avoiding specifying the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.exchange] providing an `exchange(...)` + * variant leveraging Kotlin reified type parameters. This extension is not subject to + * type erasure and retains actual generic type arguments. * * @author Jon Schneider * @author Sebastien Deleuze @@ -227,8 +259,9 @@ inline fun RestOperations.exchange(url: String, method: HttpMet exchange(url, method, requestEntity, object : ParameterizedTypeReference() {}, uriVariables) /** - * Extension for [RestOperations.exchange] avoiding specifying the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.exchange] providing an `exchange(...)` + * variant leveraging Kotlin reified type parameters. This extension is not subject to + * type erasure and retains actual generic type arguments. * * @author Jon Schneider * @author Sebastien Deleuze @@ -240,8 +273,9 @@ inline fun RestOperations.exchange(url: URI, method: HttpMethod exchange(url, method, requestEntity, object : ParameterizedTypeReference() {}) /** - * Extension for [RestOperations.exchange] avoiding specifying the type parameter - * thanks to Kotlin reified type parameters. + * Extension for [RestOperations.exchange] providing an `exchange(...)` + * variant leveraging Kotlin reified type parameters. This extension is not subject to + * type erasure and retains actual generic type arguments. * * @author Jon Schneider * @author Sebastien Deleuze diff --git a/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/client/ClientResponseExtensions.kt b/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/client/ClientResponseExtensions.kt index 2260fac1f6..e2e1da0b2d 100644 --- a/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/client/ClientResponseExtensions.kt +++ b/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/client/ClientResponseExtensions.kt @@ -23,7 +23,8 @@ import reactor.core.publisher.Mono /** * Extension for [ClientResponse.bodyToMono] providing a `bodyToMono()` variant - * leveraging Kotlin reified type parameters. + * leveraging Kotlin reified type parameters. This extension is not subject to type + * erasure and retains actual generic type arguments. * * @author Sebastien Deleuze * @since 5.0 @@ -33,7 +34,8 @@ inline fun ClientResponse.bodyToMono(): Mono = /** * Extension for [ClientResponse.bodyToFlux] providing a `bodyToFlux()` variant - * leveraging Kotlin reified type parameters. + * leveraging Kotlin reified type parameters. This extension is not subject to type + * erasure and retains actual generic type arguments. * * @author Sebastien Deleuze * @since 5.0 @@ -43,7 +45,8 @@ inline fun ClientResponse.bodyToFlux(): Flux = /** * Extension for [ClientResponse.toEntity] providing a `toEntity()` variant - * leveraging Kotlin reified type parameters. + * leveraging Kotlin reified type parameters. This extension is not subject to type + * erasure and retains actual generic type arguments. * * @author Sebastien Deleuze * @since 5.0 @@ -53,7 +56,8 @@ inline fun ClientResponse.toEntity(): Mono> /** * Extension for [ClientResponse.toEntityList] providing a `bodyToEntityList()` variant - * leveraging Kotlin reified type parameters. + * leveraging Kotlin reified type parameters. This extension is not subject to type + * erasure and retains actual generic type arguments. * * @author Sebastien Deleuze * @since 5.0 diff --git a/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/client/WebClientExtensions.kt b/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/client/WebClientExtensions.kt index c2e79b9a31..264d129867 100644 --- a/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/client/WebClientExtensions.kt +++ b/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/client/WebClientExtensions.kt @@ -25,7 +25,8 @@ import reactor.core.publisher.Mono /** * Extension for [WebClient.RequestBodySpec.body] providing a `body()` variant - * leveraging Kotlin reified type parameters. + * leveraging Kotlin reified type parameters. This extension is not subject to type + * erasure and retains actual generic type arguments. * * @author Sebastien Deleuze * @since 5.0 @@ -36,7 +37,8 @@ inline fun > RequestBodySpec.body(publisher: S /** * Extension for [WebClient.ResponseSpec.bodyToMono] providing a `bodyToMono()` variant - * leveraging Kotlin reified type parameters. + * leveraging Kotlin reified type parameters. This extension is not subject to type + * erasure and retains actual generic type arguments. * * @author Sebastien Deleuze * @since 5.0 @@ -47,7 +49,8 @@ inline fun WebClient.ResponseSpec.bodyToMono(): Mono = /** * Extension for [WebClient.ResponseSpec.bodyToFlux] providing a `bodyToFlux()` variant - * leveraging Kotlin reified type parameters. + * leveraging Kotlin reified type parameters. This extension is not subject to type + * erasure and retains actual generic type arguments. * * @author Sebastien Deleuze * @since 5.0 diff --git a/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/server/ServerRequestExtensions.kt b/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/server/ServerRequestExtensions.kt index 6ee48e924e..0f0cc51e44 100644 --- a/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/server/ServerRequestExtensions.kt +++ b/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/server/ServerRequestExtensions.kt @@ -22,7 +22,8 @@ import reactor.core.publisher.Mono /** * Extension for [ServerRequest.bodyToMono] providing a `bodyToMono()` variant - * leveraging Kotlin reified type parameters. + * leveraging Kotlin reified type parameters. This extension is not subject to type + * erasure and retains actual generic type arguments. * * @author Sebastien Deleuze * @since 5.0 @@ -32,7 +33,8 @@ inline fun ServerRequest.bodyToMono(): Mono = /** * Extension for [ServerRequest.bodyToFlux] providing a `bodyToFlux()` variant - * leveraging Kotlin reified type parameters. + * leveraging Kotlin reified type parameters. This extension is not subject to type + * erasure and retains actual generic type arguments. * * @author Sebastien Deleuze * @since 5.0 diff --git a/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/server/ServerResponseExtensions.kt b/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/server/ServerResponseExtensions.kt index 6f4adc83cd..922effd520 100644 --- a/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/server/ServerResponseExtensions.kt +++ b/spring-webflux/src/main/kotlin/org/springframework/web/reactive/function/server/ServerResponseExtensions.kt @@ -22,7 +22,9 @@ import org.springframework.http.MediaType import reactor.core.publisher.Mono /** - * Extension for [ServerResponse.BodyBuilder.body] providing a `body(Publisher)` variant. + * Extension for [ServerResponse.BodyBuilder.body] providing a `body(Publisher)` + * variant. This extension is not subject to type erasure and retains actual generic + * type arguments. * * @author Sebastien Deleuze * @since 5.0 @@ -31,7 +33,9 @@ inline fun ServerResponse.BodyBuilder.body(publisher: Publishe body(publisher, object : ParameterizedTypeReference() {}) /** - * Extension for [ServerResponse.BodyBuilder.body] providing a `bodyToServerSentEvents(Publisher)` variant. + * Extension for [ServerResponse.BodyBuilder.body] providing a + * `bodyToServerSentEvents(Publisher)` variant. This extension is not subject to type + * erasure and retains actual generic type arguments. * * @author Sebastien Deleuze * @since 5.0