GitHub-Spring
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

WebFlux and Integration share webflux-client.adoc 

Extract WebClient content into a separate file that is now included
both in the WebFlux and in the Integration sections.

This allows having RestTemplate and WebClient documented in one place
under Integration while also keeping the same included in the WebFlux
section too.
pull/1519/merge
Rossen Stoyanchev 9 years ago
parent
71ccf3c9e3
commit
67910ee48c
3 changed files with 274 additions and 296 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 50
      src/docs/asciidoc/integration.adoc
  2. 260
      src/docs/asciidoc/web/webflux-client.adoc
  3. 260
      src/docs/asciidoc/web/webflux.adoc

50
src/docs/asciidoc/integration.adoc
Unescape View File

@ -946,50 +946,24 @@ plugging in third-party or custom solutions here. @@ -946,50 +946,24 @@ plugging in third-party or custom solutions here.
[[rest-client-access]]
=== Accessing RESTful services on the Client
The `RestTemplate` is the core class for client-side access to RESTful services. It is
conceptually similar to other template classes in Spring, such as `JdbcTemplate` and
`JmsTemplate` and other template classes found in other Spring portfolio projects.
`RestTemplate`'s behavior is customized by providing callback methods and configuring
the `HttpMessageConverter` used to marshal objects into the HTTP request body and to
unmarshal any response back into an object. As it is common to use XML as a message
format, Spring provides a `MarshallingHttpMessageConverter` that uses the Object-to-XML
framework that is part of the `org.springframework.oxm` package. This gives you a wide
range of choices of XML to Object mapping technologies to choose from.
=== Accessing REST endpoints
This section describes how to use the `RestTemplate` and its associated
`HttpMessageConverters`.
The Spring Framework offers two choices for client-side access to REST endpoints:
* <<rest-resttemplate>> -- the original Spring REST client with an API similar to other
template classes in Spring, such as `JdbcTemplate`, `JmsTemplate` and others. The
`RestTemplate` is built for synchronous use with the blocking I/O.
* <<webflux-client,WebClient>> -- reactive client with a functional,
fluent API. It is built on a non-blocking foundation for async and sync scenarios and
supports Reactive Streams back pressure.
[[rest-resttemplate]]
==== RestTemplate
Invoking RESTful services in Java is typically done using a helper class such as Apache
HttpComponents `HttpClient`. For common REST operations this approach is too low level as
shown below.
[source,java,indent=0]
[subs="verbatim,quotes"]
----
String uri = "http://example.com/hotels/1/bookings";
PostMethod post = new PostMethod(uri);
String request = // create booking request content
post.setRequestEntity(new StringRequestEntity(request));
httpClient.executeMethod(post);
if (HttpStatus.SC_CREATED == post.getStatusCode()) {
Header location = post.getRequestHeader("Location");
if (location != null) {
System.out.println("Created new booking at :" + location.getValue());
}
}
----
RestTemplate provides higher level methods that correspond to each of the six main HTTP
methods that make invoking many RESTful services a one-liner and enforce REST best
practices.
The `RestTemplate` provides a higher level API over HTTP client libraries with methods
that correspond to each of the six main HTTP methods that make invoking many RESTful
services a one-liner and enforce REST best practices.
[NOTE]
@ -1373,6 +1347,8 @@ The `AsyncRestTemplate` is deprecated. @@ -1373,6 +1347,8 @@ The `AsyncRestTemplate` is deprecated.
Please use the <<web-reactive.adoc#webflux-client,WebClient>> instead.
include::web/webflux-client.adoc[leveloffset=+3]
[[ejb]]

260
src/docs/asciidoc/web/webflux-client.adoc
Unescape View File

@ -0,0 +1,260 @@ @@ -0,0 +1,260 @@
[[webflux-client]]
= WebClient
The `spring-webflux` module includes a non-blocking, reactive client for HTTP requests
with Reactive Streams back pressure. It shares
<<web-reactive.adoc#webflux-codecs,HTTP codecs>> and other infrastructure with the
server <<web-reactive.adoc#webflux-fn,functional web framework>>.
`WebClient` provides a higher level API over HTTP client libraries. By default
it uses https://github.com/reactor/reactor-netty[Reactor Netty] but that is pluggable
with a different `ClientHttpConnector`. The `WebClient` API returns Reactor `Flux` or
`Mono` for output and accepts Reactive Streams `Publisher` as input (see
<<web-reactive.adoc#webflux-reactive-libraries>>).
[TIP]
====
By comparison to the
<<integration.adoc#rest-resttemplate,RestTemplate>>, the `WebClient` offers a more
functional and fluent API that taking full advantage of Java 8 lambdas. It supports both
sync and async scenarios, including streaming, and brings the efficiency of
non-blocking I/O.
====
[[webflux-client-retrieve]]
== Retrieve
The `retrieve()` method is the easiest way to get a response body and decode it:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
WebClient client = WebClient.create("http://example.org");
Mono<Person> result = client.get()
.uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON)
.retrieve()
.bodyToMono(Person.class);
----
You can also get a stream of objects decoded from the response:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
Flux<Quote> result = client.get()
.uri("/quotes").accept(TEXT_EVENT_STREAM)
.retrieve()
.bodyToFlux(Quote.class);
----
By default, responses with 4xx or 5xx status codes result in an error of type
`WebClientResponseException` but you can customize that:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
Mono<Person> result = client.get()
.uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON)
.retrieve()
.onStatus(HttpStatus::is4xxServerError, response -> ...)
.onStatus(HttpStatus::is5xxServerError, response -> ...)
.bodyToFlux(Person.class);
----
[[webflux-client-exchange]]
== Exchange
The `exchange()` method provides more control. The below example is equivalent
to `retrieve()` but also provides access to the `ClientResponse`:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
Mono<Person> result = client.get()
.uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON)
.exchange()
.flatMap(response -> response.bodyToMono(Person.class));
----
At this level you can also create a full `ResponseEntity`:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
Mono<ResponseEntity<Person>> result = client.get()
.uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON)
.exchange()
.flatMap(response -> response.bodyToEntity(Person.class));
----
Note that unlike `retrieve()`, with `exchange()` there are no automatic error signals for
4xx and 5xx responses. You have to check the status code and decide how to proceed.
[CAUTION]
====
When you use `exchange()`, you must call `response.close()` if you do not intend to read
the response body in order to close the underlying HTTP connection. Not doing so can
result in connection pool inconsistencies or memory leaks.
You do not have to call `response.close()` if you consume the body because forcing a
connection to be closed negates the benefits of persistent connections and connection
pooling.
====
[[webflux-client-body]]
== Request body
The request body can be encoded from an Object:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
Mono<Person> personMono = ... ;
Mono<Void> result = client.post()
.uri("/persons/{id}", id)
.contentType(MediaType.APPLICATION_JSON)
.body(personMono, Person.class)
.retrieve()
.bodyToMono(Void.class);
----
You can also have a stream of objects encoded:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
Flux<Person> personFlux = ... ;
Mono<Void> result = client.post()
.uri("/persons/{id}", id)
.contentType(MediaType.APPLICATION_STREAM_JSON)
.body(personFlux, Person.class)
.retrieve()
.bodyToMono(Void.class);
----
Or if you have the actual value, use the `syncBody` shortcut method:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
Person person = ... ;
Mono<Void> result = client.post()
.uri("/persons/{id}", id)
.contentType(MediaType.APPLICATION_JSON)
.syncBody(person)
.retrieve()
.bodyToMono(Void.class);
----
[[webflux-client-builder]]
== Builder options
A simple way to create `WebClient` is through the static factory methods `create()` and
`create(String)` with a base URL for all requests. You can also use `WebClient.builder()`
for access to more options.
To customize the underlying HTTP client:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
SslContext sslContext = ...
ClientHttpConnector connector = new ReactorClientHttpConnector(
builder -> builder.sslContext(sslContext));
WebClient webClient = WebClient.builder()
.clientConnector(connector)
.build();
----
To customize the <<web-reactive.adoc#webflux-codecs,HTTP codecs>> used for encoding and
decoding HTTP messages:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
ExchangeStrategies strategies = ExchangeStrategies.builder()
.codecs(configurer -> {
// ...
})
.build();
WebClient webClient = WebClient.builder()
.exchangeStrategies(strategies)
.build();
----
The builder can be used to insert <<webflux-client-filter>>.
Explore the `WebClient.Builder` in your IDE for other options related to URI building,
default headers (and cookies), and more.
After the `WebClient` is built, you can always obtain a new builder from it, in order to
build a new `WebClient`, based on, but without affecting the current instance:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
WebClient modifiedClient = client.mutate()
// user builder methods...
.build();
----
[[webflux-client-filter]]
== Filters
`WebClient` supports interception style request filtering:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
WebClient client = WebClient.builder()
.filter((request, next) -> {
ClientRequest filtered = ClientRequest.from(request)
.header("foo", "bar")
.build();
return next.exchange(filtered);
})
.build();
----
`ExchangeFilterFunctions` provides a filter for basic authentication:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
// static import of ExchangeFilterFunctions.basicAuthentication
WebClient client = WebClient.builder()
.filter(basicAuthentication("user", "pwd"))
.build();
----
You can also mutate an existing `WebClient` instance without affecting the original:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
WebClient filteredClient = client.mutate()
.filter(basicAuthentication("user", "pwd")
.build();
----

260
src/docs/asciidoc/web/webflux.adoc
Unescape View File

@ -1386,265 +1386,7 @@ from the base class and you can still have any number of other ``WebMvcConfigure @@ -1386,265 +1386,7 @@ from the base class and you can still have any number of other ``WebMvcConfigure
the classpath.
[[webflux-client]]
== WebClient
The `spring-webflux` module includes a non-blocking, reactive client for HTTP requests
with Reactive Streams back pressure. It shares <<webflux-codecs,HTTP codecs>> and other
infrastructure with the server <<webflux-fn,functional web framework>>.
`WebClient` provides a higher level API over HTTP client libraries. By default
it uses https://github.com/reactor/reactor-netty[Reactor Netty] but that is pluggable
with a different `ClientHttpConnector`. The `WebClient` API returns Reactor `Flux` or
`Mono` for output and accepts Reactive Streams `Publisher` as input (see
<<webflux-reactive-libraries>>).
[TIP]
====
By comparison to the
<<integration.adoc#rest-resttemplate,RestTemplate>>, the `WebClient` offers a more
functional and fluent API that taking full advantage of Java 8 lambdas. It supports both
sync and async scenarios, including streaming, and brings the efficiency of
non-blocking I/O.
====
[[webflux-client-retrieve]]
=== Retrieve
The `retrieve()` method is the easiest way to get a response body and decode it:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
WebClient client = WebClient.create("http://example.org");
Mono<Person> result = client.get()
.uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON)
.retrieve()
.bodyToMono(Person.class);
----
You can also get a stream of objects decoded from the response:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
Flux<Quote> result = client.get()
.uri("/quotes").accept(TEXT_EVENT_STREAM)
.retrieve()
.bodyToFlux(Quote.class);
----
By default, responses with 4xx or 5xx status codes result in an error of type
`WebClientResponseException` but you can customize that:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
Mono<Person> result = client.get()
.uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON)
.retrieve()
.onStatus(HttpStatus::is4xxServerError, response -> ...)
.onStatus(HttpStatus::is5xxServerError, response -> ...)
.bodyToFlux(Person.class);
----
[[webflux-client-exchange]]
=== Exchange
The `exchange()` method provides more control. The below example is equivalent
to `retrieve()` but also provides access to the `ClientResponse`:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
Mono<Person> result = client.get()
.uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON)
.exchange()
.flatMap(response -> response.bodyToMono(Person.class));
----
At this level you can also create a full `ResponseEntity`:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
Mono<ResponseEntity<Person>> result = client.get()
.uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON)
.exchange()
.flatMap(response -> response.bodyToEntity(Person.class));
----
Note that unlike `retrieve()`, with `exchange()` there are no automatic error signals for
4xx and 5xx responses. You have to check the status code and decide how to proceed.
[CAUTION]
====
When you use `exchange()`, you must call `response.close()` if you do not intend to read
the response body in order to close the underlying HTTP connection. Not doing so can
result in connection pool inconsistencies or memory leaks.
You do not have to call `response.close()` if you consume the body because forcing a
connection to be closed negates the benefits of persistent connections and connection
pooling.
====
[[webflux-client-body]]
=== Request body
The request body can be encoded from an Object:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
Mono<Person> personMono = ... ;
Mono<Void> result = client.post()
.uri("/persons/{id}", id)
.contentType(MediaType.APPLICATION_JSON)
.body(personMono, Person.class)
.retrieve()
.bodyToMono(Void.class);
----
You can also have a stream of objects encoded:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
Flux<Person> personFlux = ... ;
Mono<Void> result = client.post()
.uri("/persons/{id}", id)
.contentType(MediaType.APPLICATION_STREAM_JSON)
.body(personFlux, Person.class)
.retrieve()
.bodyToMono(Void.class);
----
Or if you have the actual value, use the `syncBody` shortcut method:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
Person person = ... ;
Mono<Void> result = client.post()
.uri("/persons/{id}", id)
.contentType(MediaType.APPLICATION_JSON)
.syncBody(person)
.retrieve()
.bodyToMono(Void.class);
----
[[webflux-client-builder]]
=== Builder options
A simple way to create `WebClient` is through the static factory methods `create()` and
`create(String)` with a base URL for all requests. You can also use `WebClient.builder()`
for access to more options.
To customize the underlying HTTP client:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
SslContext sslContext = ...
ClientHttpConnector connector = new ReactorClientHttpConnector(
builder -> builder.sslContext(sslContext));
WebClient webClient = WebClient.builder()
.clientConnector(connector)
.build();
----
To customize the <<webflux-codecs,HTTP codecs>> used for encoding and decoding HTTP messages:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
ExchangeStrategies strategies = ExchangeStrategies.builder()
.codecs(configurer -> {
// ...
})
.build();
WebClient webClient = WebClient.builder()
.exchangeStrategies(strategies)
.build();
----
The builder can be used to insert <<webflux-client-filter>>.
Explore the `WebClient.Builder` in your IDE for other options related to URI building,
default headers (and cookies), and more.
After the `WebClient` is built, you can always obtain a new builder from it, in order to
build a new `WebClient`, based on, but without affecting the current instance:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
WebClient modifiedClient = client.mutate()
// user builder methods...
.build();
----
[[webflux-client-filter]]
=== Filters
`WebClient` supports interception style request filtering:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
WebClient client = WebClient.builder()
.filter((request, next) -> {
ClientRequest filtered = ClientRequest.from(request)
.header("foo", "bar")
.build();
return next.exchange(filtered);
})
.build();
----
`ExchangeFilterFunctions` provides a filter for basic authentication:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
// static import of ExchangeFilterFunctions.basicAuthentication
WebClient client = WebClient.builder()
.filter(basicAuthentication("user", "pwd"))
.build();
----
You can also mutate an existing `WebClient` instance without affecting the original:
[source,java,intent=0]
[subs="verbatim,quotes"]
----
WebClient filteredClient = client.mutate()
.filter(basicAuthentication("user", "pwd")
.build();
----
include::webflux-client.adoc[leveloffset=+1]
[[webflux-reactive-libraries]]

Write Preview
Loading…
Cancel
Save