Update references to HTTP service clients in docs
Closes gh-35522
This commit is contained in:
rstoyanchev
parent
79738d921a
commit
e9e19f5ed7
|
|
@ -314,7 +314,7 @@
|
|||
*** xref:web/webflux-webclient/client-context.adoc[]
|
||||
*** xref:web/webflux-webclient/client-synchronous.adoc[]
|
||||
*** xref:web/webflux-webclient/client-testing.adoc[]
|
||||
** xref:web/webflux-http-interface-client.adoc[]
|
||||
** xref:web/webflux-http-service-client.adoc[]
|
||||
** xref:web/webflux-websocket.adoc[]
|
||||
** xref:web/webflux-test.adoc[]
|
||||
** xref:rsocket.adoc[]
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ The Spring Framework provides the following choices for making calls to REST end
|
|||
* xref:integration/rest-clients.adoc#rest-restclient[`RestClient`] -- synchronous client with a fluent API
|
||||
* xref:integration/rest-clients.adoc#rest-webclient[`WebClient`] -- non-blocking, reactive client with fluent API
|
||||
* xref:integration/rest-clients.adoc#rest-resttemplate[`RestTemplate`] -- synchronous client with template method API
|
||||
* xref:integration/rest-clients.adoc#rest-http-interface[HTTP Interface Clients] -- annotated interface backed by generated proxy
|
||||
* xref:integration/rest-clients.adoc#rest-http-service-client[HTTP Service Clients] -- annotated interface backed by generated proxy
|
||||
|
||||
|
||||
[[rest-restclient]]
|
||||
|
|
@ -855,8 +855,8 @@ It can be used to migrate from the latter to the former.
|
|||
|===
|
||||
|
||||
|
||||
[[rest-http-interface]]
|
||||
== HTTP Interface Clients
|
||||
[[rest-http-service-client]]
|
||||
== HTTP Service Clients
|
||||
|
||||
You can define an HTTP Service as a Java interface with `@HttpExchange` methods, and use
|
||||
`HttpServiceProxyFactory` to create a client proxy from it for remote access over HTTP via
|
||||
|
|
@ -928,7 +928,7 @@ Now, you're ready to create client proxies:
|
|||
// Use service methods for remote calls...
|
||||
----
|
||||
|
||||
[[rest-http-interface-method-parameters]]
|
||||
[[rest-http-service-client-method-parameters]]
|
||||
=== Method Parameters
|
||||
|
||||
`@HttpExchange` methods support flexible method signatures with the following inputs:
|
||||
|
|
@ -1000,13 +1000,13 @@ parameter annotation) is set to `false`, or the parameter is marked optional as
|
|||
`StreamingHttpOutputMessage.Body` that allows sending the request body by writing to an
|
||||
`OutputStream`.
|
||||
|
||||
[[rest-http-interface.custom-resolver]]
|
||||
[[rest-http-service-client.custom-resolver]]
|
||||
=== Custom Arguments
|
||||
|
||||
You can configure a custom `HttpServiceArgumentResolver`. The example interface below
|
||||
uses a custom `Search` method parameter type:
|
||||
|
||||
include-code::./CustomHttpServiceArgumentResolver[tag=httpinterface,indent=0]
|
||||
include-code::./CustomHttpServiceArgumentResolver[tag=httpserviceclient,indent=0]
|
||||
|
||||
A custom argument resolver could be implemented like this:
|
||||
|
||||
|
|
@ -1021,7 +1021,7 @@ the use of more fine-grained method parameters for individual parts of the reque
|
|||
|
||||
|
||||
|
||||
[[rest-http-interface-return-values]]
|
||||
[[rest-http-service-client-return-values]]
|
||||
=== Return Values
|
||||
|
||||
The supported return values depend on the underlying client.
|
||||
|
|
@ -1097,7 +1097,7 @@ underlying HTTP client, which operates at a lower level and provides more contro
|
|||
`InputStream` or `ResponseEntity<InputStream>` that provides access to the raw response
|
||||
body content.
|
||||
|
||||
[[rest-http-interface-exceptions]]
|
||||
[[rest-http-service-client-exceptions]]
|
||||
=== Error Handling
|
||||
|
||||
To customize error handling for HTTP Service client proxies, you can configure the
|
||||
|
|
@ -1134,7 +1134,7 @@ documentation for each client, as well as the Javadoc of `defaultStatusHandler`
|
|||
|
||||
|
||||
|
||||
[[rest-http-interface-adapter-decorator]]
|
||||
[[rest-http-service-client-adapter-decorator]]
|
||||
=== Decorating the Adapter
|
||||
|
||||
`HttpExchangeAdapter` and `ReactorHttpExchangeAdapter` are contracts that decouple HTTP
|
||||
|
|
@ -1162,8 +1162,8 @@ built-in decorators to suppress 404 exceptions and return a `ResponseEntity` wit
|
|||
|
||||
|
||||
|
||||
[[rest-http-interface-group-config]]
|
||||
=== HTTP Interface Groups
|
||||
[[rest-http-service-client-group-config]]
|
||||
=== HTTP Service Groups
|
||||
|
||||
It's trivial to create client proxies with `HttpServiceProxyFactory`, but to have them
|
||||
declared as beans leads to repetitive configuration. You may also have multiple
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
[[webflux-http-interface-client]]
|
||||
= HTTP Interface Client
|
||||
[[webflux-http-service-client]]
|
||||
= HTTP Service Client
|
||||
|
||||
The Spring Frameworks lets you define an HTTP service as a Java interface with HTTP
|
||||
exchange methods. You can then generate a proxy that implements this interface and
|
||||
performs the exchanges. This helps to simplify HTTP remote access and provides additional
|
||||
flexibility for to choose an API style such as synchronous or reactive.
|
||||
|
||||
See xref:integration/rest-clients.adoc#rest-http-interface[REST Endpoints] for details.
|
||||
See xref:integration/rest-clients.adoc#rest-http-service-client[HTTP Service Clients] for details.
|
||||
|
|
@ -17,7 +17,7 @@ to annotated controller methods with an API version
|
|||
to functional endpoints with an API version
|
||||
|
||||
Client support for API versioning is available also in `RestClient`, `WebClient`, and
|
||||
xref:integration/rest-clients.adoc#rest-http-interface[HTTP Service] clients, as well as
|
||||
xref:integration/rest-clients.adoc#rest-http-service-client[HTTP Service] clients, as well as
|
||||
for testing in `WebTestClient`.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -629,17 +629,16 @@ Kotlin::
|
|||
== `@HttpExchange`
|
||||
[.small]#xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-httpexchange-annotation[See equivalent in the Servlet stack]#
|
||||
|
||||
While the main purpose of `@HttpExchange` is to abstract HTTP client code with a
|
||||
generated proxy, the
|
||||
xref:integration/rest-clients.adoc#rest-http-interface[HTTP Interface] on which
|
||||
such annotations are placed is a contract neutral to client vs server use.
|
||||
In addition to simplifying client code, there are also cases where an HTTP Interface
|
||||
may be a convenient way for servers to expose their API for client access. This leads
|
||||
to increased coupling between client and server and is often not a good choice,
|
||||
especially for public API's, but may be exactly the goal for an internal API.
|
||||
It is an approach commonly used in Spring Cloud, and it is why `@HttpExchange` is
|
||||
supported as an alternative to `@RequestMapping` for server side handling in
|
||||
controller classes.
|
||||
While the main purpose of `@HttpExchange` is for an HTTP Service
|
||||
xref:integration/rest-clients.adoc#rest-http-service-client[client with a generated proxy],
|
||||
the HTTP Service interface on which such annotations are placed is a contract neutral
|
||||
to client vs server use. In addition to simplifying client code, there are also cases
|
||||
where an HTTP Service interface may be a convenient way for servers to expose their
|
||||
API for client access. This leads to increased coupling between client and server and
|
||||
is often not a good choice, especially for public API's, but may be exactly the goal
|
||||
for an internal API. It is an approach commonly used in Spring Cloud, and it is why
|
||||
`@HttpExchange` is supported as an alternative to `@RequestMapping` for server side
|
||||
handling in controller classes.
|
||||
|
||||
For example:
|
||||
|
||||
|
|
@ -710,5 +709,5 @@ path, and content types.
|
|||
For method parameters and returns values, generally, `@HttpExchange` supports a
|
||||
subset of the method parameters that `@RequestMapping` does. Notably, it excludes any
|
||||
server-side specific parameter types. For details, see the list for
|
||||
xref:integration/rest-clients.adoc#rest-http-interface-method-parameters[@HttpExchange] and
|
||||
xref:integration/rest-clients.adoc#rest-http-service-client-method-parameters[@HttpExchange] and
|
||||
xref:web/webflux/controller/ann-methods/arguments.adoc[@RequestMapping].
|
||||
|
|
|
|||
|
|
@ -30,12 +30,12 @@ libraries.
|
|||
See xref:integration/rest-clients.adoc#rest-resttemplate[`RestTemplate`] for details.
|
||||
|
||||
|
||||
[[webmvc-http-interface]]
|
||||
== HTTP Interface
|
||||
[[webmvc-http-service-client]]
|
||||
== HTTP Service Client
|
||||
|
||||
The Spring Framework lets you define an HTTP service as a Java interface with HTTP
|
||||
exchange methods. You can then generate a proxy that implements this interface and
|
||||
performs the exchanges. This helps to simplify HTTP remote access and provides additional
|
||||
flexibility for choosing an API style such as synchronous or reactive.
|
||||
|
||||
See xref:integration/rest-clients.adoc#rest-http-interface[HTTP Interface] for details.
|
||||
See xref:integration/rest-clients.adoc#rest-http-service-client[HTTP Service Client] for details.
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@ to annotated controller methods with an API version
|
|||
to functional endpoints with an API version
|
||||
|
||||
Client support for API versioning is available also in `RestClient`, `WebClient`, and
|
||||
xref:integration/rest-clients.adoc#rest-http-interface[HTTP Service] clients, as well as
|
||||
xref:integration/rest-clients.adoc#rest-http-service-client[HTTP Service] clients, as well as
|
||||
for testing in MockMvc and `WebTestClient`.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -659,10 +659,9 @@ Kotlin::
|
|||
[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-httpexchange-annotation[See equivalent in the Reactive stack]#
|
||||
|
||||
While the main purpose of `@HttpExchange` is to abstract HTTP client code with a
|
||||
generated proxy, the
|
||||
xref:integration/rest-clients.adoc#rest-http-interface[HTTP Interface] on which
|
||||
such annotations are placed is a contract neutral to client vs server use.
|
||||
In addition to simplifying client code, there are also cases where an HTTP Interface
|
||||
generated proxy, the interface on which such annotations are placed is a contract neutral
|
||||
to client vs server use. In addition to simplifying client code, there are also cases
|
||||
where an xref:integration/rest-clients.adoc#rest-http-service-client[HTTP Service Client]
|
||||
may be a convenient way for servers to expose their API for client access. This leads
|
||||
to increased coupling between client and server and is often not a good choice,
|
||||
especially for public API's, but may be exactly the goal for an internal API.
|
||||
|
|
@ -739,7 +738,7 @@ path, and content types.
|
|||
For method parameters and returns values, generally, `@HttpExchange` supports a
|
||||
subset of the method parameters that `@RequestMapping` does. Notably, it excludes any
|
||||
server-side specific parameter types. For details, see the list for
|
||||
xref:integration/rest-clients.adoc#rest-http-interface-method-parameters[@HttpExchange] and
|
||||
xref:integration/rest-clients.adoc#rest-http-service-client-method-parameters[@HttpExchange] and
|
||||
xref:web/webmvc/mvc-controller/ann-methods/arguments.adoc[@RequestMapping].
|
||||
|
||||
`@HttpExchange` also supports a `headers()` parameter which accepts `"name=value"`-like
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@
|
|||
* limitations under the License.
|
||||
*/
|
||||
|
||||
package org.springframework.docs.integration.resthttpinterface.customresolver;
|
||||
package org.springframework.docs.integration.resthttpserviceclient.customresolver;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
|
|
@ -28,14 +28,14 @@ import org.springframework.web.service.invoker.HttpServiceProxyFactory;
|
|||
|
||||
public class CustomHttpServiceArgumentResolver {
|
||||
|
||||
// tag::httpinterface[]
|
||||
// tag::httpserviceclient[]
|
||||
public interface RepositoryService {
|
||||
|
||||
@GetExchange("/repos/search")
|
||||
List<Repository> searchRepository(Search search);
|
||||
|
||||
}
|
||||
// end::httpinterface[]
|
||||
// end::httpserviceclient[]
|
||||
|
||||
class Sample {
|
||||
|
||||
|
|
@ -14,7 +14,7 @@
|
|||
* limitations under the License.
|
||||
*/
|
||||
|
||||
package org.springframework.docs.integration.resthttpinterface.customresolver
|
||||
package org.springframework.docs.integration.resthttpserviceclient.customresolver
|
||||
|
||||
import org.springframework.core.MethodParameter
|
||||
import org.springframework.web.client.RestClient
|
||||
|
|
@ -26,14 +26,14 @@ import org.springframework.web.service.invoker.HttpServiceProxyFactory
|
|||
|
||||
class CustomHttpServiceArgumentResolver {
|
||||
|
||||
// tag::httpinterface[]
|
||||
// tag::httpserviceclient[]
|
||||
interface RepositoryService {
|
||||
|
||||
@GetExchange("/repos/search")
|
||||
fun searchRepository(search: Search): List<Repository>
|
||||
|
||||
}
|
||||
// end::httpinterface[]
|
||||
// end::httpserviceclient[]
|
||||
|
||||
class Sample {
|
||||
fun sample() {
|
||||
|
|
@ -127,7 +127,7 @@ public class HttpRequestValues {
|
|||
/**
|
||||
* Return the {@link UriBuilderFactory} to expand
|
||||
* the {@link HttpRequestValues#uriTemplate} and {@link #getUriVariables()} with.
|
||||
* <p>The {@link UriBuilderFactory} is passed into the HTTP interface method
|
||||
* <p>The {@link UriBuilderFactory} is passed into the HTTP Service client method
|
||||
* in order to override the UriBuilderFactory (and its baseUrl) used by the
|
||||
* underlying client.
|
||||
* @since 6.1
|
||||
|
|
|
|||
|
|
@ -33,7 +33,7 @@ public interface HttpServiceProxyRegistry {
|
|||
* Return an HTTP service client from any group as long as there is only one
|
||||
* client of this type across all groups.
|
||||
* @param httpServiceType the type of client
|
||||
* @param <P> the type of HTTP interface client
|
||||
* @param <P> the type of HTTP service client
|
||||
* @return the matched client
|
||||
* @throws IllegalArgumentException if there is no client of the given type,
|
||||
* or there is more than one client of the given type.
|
||||
|
|
@ -44,7 +44,7 @@ public interface HttpServiceProxyRegistry {
|
|||
* Return an HTTP service client from the named group.
|
||||
* @param groupName the name of the group
|
||||
* @param httpServiceType the type of client
|
||||
* @param <P> the type of HTTP interface client
|
||||
* @param <P> the type of HTTP service client
|
||||
* @return the matched client
|
||||
* @throws IllegalArgumentException if there is no matching client.
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue