Package org.springframework.web.client

# Interface RestClient.RequestHeadersSpec<S extends RestClient.RequestHeadersSpec<S>>

Type Parameters:
  `S` - a self reference to the spec type

All Known Subinterfaces:
  `RestClient.RequestBodySpec`, `RestClient.RequestBodyUriSpec`, `RestClient.RequestHeadersUriSpec<S>`

Enclosing interface:
  RestClient

public static interface RestClient.RequestHeadersSpec<S extends RestClient.RequestHeadersSpec<S>>
Contract for specifying request headers leading up to the exchange.

## Nested Class Summary

Nested Classes
Modifier and Type
Interface
Description
`static interface`
`RestClient.RequestHeadersSpec.ConvertibleClientHttpResponse`
Extension of `ClientHttpResponse` that can convert the body.
`static interface`
`RestClient.RequestHeadersSpec.ExchangeFunction<T>`
Defines the contract for `exchange(ExchangeFunction)`.
`static interface`
`RestClient.RequestHeadersSpec.RequiredValueExchangeFunction<T>`
Variant of `RestClient.RequestHeadersSpec.ExchangeFunction` returning a non-null required value.

## Method Summary

Modifier and Type
Method
Description
`S`
`accept(MediaType... acceptableMediaTypes)`
Set the list of acceptable media types, as specified by the `Accept` header.
`S`
`acceptCharset(Charset... acceptableCharsets)`
Set the list of acceptable charsets, as specified by the `Accept-Charset` header.
`S`
`attribute(String name, Object value)`
Set the attribute with the given name to the given value.
`S`
`attributes(Consumer<Map<String,Object>> attributesConsumer)`
Provides access to every attribute declared so far with the possibility to add, replace, or remove values.
`S`
`cookie(String name, String value)`
Add a cookie with the given name and value.
`S`
`cookies(Consumer<org.springframework.util.MultiValueMap<String,String>> cookiesConsumer)`
Provides access to every cookie declared so far with the possibility to add, replace, or remove values.
`default <T> T`
`exchange(RestClient.RequestHeadersSpec.ExchangeFunction<T> exchangeFunction)`
Exchange the `ClientHttpResponse` for a value of type `T`.
`<T> T`
`exchange(RestClient.RequestHeadersSpec.ExchangeFunction<T> exchangeFunction, boolean close)`
Exchange the `ClientHttpResponse` for a value of type `T`.
`default <T> T`
`exchangeForRequiredValue(RestClient.RequestHeadersSpec.RequiredValueExchangeFunction<T> exchangeFunction)`
Exchange the `ClientHttpResponse` for a value of type `T`.
`<T> T`
`exchangeForRequiredValue(RestClient.RequestHeadersSpec.RequiredValueExchangeFunction<T> exchangeFunction, boolean close)`
Exchange the `ClientHttpResponse` for a value of type `T`.
`S`
`header(String headerName, String... headerValues)`
Add the given, single header value under the given name.
`S`
`headers(Consumer<HttpHeaders> headersConsumer)`
Provides access to every header declared so far with the possibility to add, replace, or remove values.
`S`
`httpRequest(Consumer<ClientHttpRequest> requestConsumer)`
Callback for access to the `ClientHttpRequest` that in turn provides access to the native request of the underlying HTTP library.
`S`
`ifModifiedSince(ZonedDateTime ifModifiedSince)`
Set the value of the `If-Modified-Since` header.
`S`
`ifNoneMatch(String... ifNoneMatches)`
Set the values of the `If-None-Match` header.
`RestClient.ResponseSpec`
`retrieve()`
Enter the retrieve workflow and use the returned `RestClient.ResponseSpec` to select from a number of built-in options to extract the response.

## Method Details

### accept

S accept(MediaType... acceptableMediaTypes)
Set the list of acceptable media types, as specified by the `Accept` header.

Parameters:
  `acceptableMediaTypes` - the acceptable media types
Returns:
  this builder

### acceptCharset

S acceptCharset(Charset... acceptableCharsets)
Set the list of acceptable charsets, as specified by the `Accept-Charset` header.

Parameters:
  `acceptableCharsets` - the acceptable charsets
Returns:
  this builder

### cookie

S cookie(String name, String value)
Add a cookie with the given name and value.

Parameters:
  `name` - the cookie name
  `value` - the cookie value
Returns:
  this builder
Since:
  6.2

### cookies

S cookies(Consumer<org.springframework.util.MultiValueMap<String,String>> cookiesConsumer)
Provides access to every cookie declared so far with the possibility to add, replace, or remove values.

Parameters:
  `cookiesConsumer` - the consumer to provide access to
Returns:
  this builder
Since:
  6.2

### ifModifiedSince

S ifModifiedSince(ZonedDateTime ifModifiedSince)
Set the value of the `If-Modified-Since` header.

Parameters:
  `ifModifiedSince` - the new value of the header
Returns:
  this builder

### ifNoneMatch

S ifNoneMatch(String... ifNoneMatches)
Set the values of the `If-None-Match` header.

Parameters:
  `ifNoneMatches` - the new value of the header
Returns:
  this builder

### header

S header(String headerName, String... headerValues)
Add the given, single header value under the given name.

Parameters:
  `headerName` - the header name
  `headerValues` - the header value(s)
Returns:
  this builder

### headers

S headers(Consumer<HttpHeaders> headersConsumer)
Provides access to every header declared so far with the possibility to add, replace, or remove values.

Parameters:
  `headersConsumer` - the consumer to provide access to
Returns:
  this builder

### attribute

S attribute(String name, Object value)
Set the attribute with the given name to the given value.

Parameters:
  `name` - the name of the attribute to add
  `value` - the value of the attribute to add
Returns:
  this builder
Since:
  6.2

### attributes

S attributes(Consumer<Map<String,Object>> attributesConsumer)
Provides access to every attribute declared so far with the possibility to add, replace, or remove values.

Parameters:
  `attributesConsumer` - the consumer to provide access to
Returns:
  this builder
Since:
  6.2

### httpRequest

S httpRequest(Consumer<ClientHttpRequest> requestConsumer)
Callback for access to the `ClientHttpRequest` that in turn provides access to the native request of the underlying HTTP library.

This could be useful for setting advanced, per-request options that are exposed by the underlying library.

Parameters:
  `requestConsumer` - a consumer to access the `ClientHttpRequest` with
Returns:
  this builder

### retrieve

@CheckReturnValue RestClient.ResponseSpec retrieve()
Enter the retrieve workflow and use the returned `RestClient.ResponseSpec` to select from a number of built-in options to extract the response. For example:

     ResponseEntity<Person> entity = client.get()
         .uri("/persons/1")
         .accept(MediaType.APPLICATION_JSON)
         .retrieve()
         .toEntity(Person.class);

Or if interested only in the body:

     Person person = client.get()
         .uri("/persons/1")
         .accept(MediaType.APPLICATION_JSON)
         .retrieve()
         .body(Person.class);

Note that this method does not actually execute the request until you call one of the returned `RestClient.ResponseSpec`. Use the `exchange(ExchangeFunction)` variants if you need to separate request execution from response extraction.

By default, 4xx response code result in a `HttpClientErrorException` and 5xx response codes in a `HttpServerErrorException`. To customize error handling, use `onStatus` handlers.

Returns:
  `ResponseSpec` to specify how to decode the body

### exchange

@Nullable default <T> T exchange(RestClient.RequestHeadersSpec.ExchangeFunction<T> exchangeFunction)
Exchange the `ClientHttpResponse` for a value of type `T`. This can be useful for advanced scenarios, for example to decode the response differently depending on the response status:

     Person person = client.get()
         .uri("/people/1")
         .accept(MediaType.APPLICATION_JSON)
         .exchange((request, response) -> {
             if (response.getStatusCode().equals(HttpStatus.OK)) {
                 return deserialize(response.getBody());
             }
             else {
                 throw new BusinessException();
             }
         });

Note: The response is closed after the exchange function has been invoked.

Type Parameters:
  `T` - the type the response will be transformed to
Parameters:
  `exchangeFunction` - the function to handle the response with
Returns:
  the value returned from the exchange function, potentially `null`
See Also:
  - `exchangeForRequiredValue(RequiredValueExchangeFunction)`

### exchangeForRequiredValue

default <T> T exchangeForRequiredValue(RestClient.RequestHeadersSpec.RequiredValueExchangeFunction<T> exchangeFunction)
Exchange the `ClientHttpResponse` for a value of type `T`. This can be useful for advanced scenarios, for example to decode the response differently depending on the response status:

     Person person = client.get()
         .uri("/people/1")
         .accept(MediaType.APPLICATION_JSON)
         .exchange((request, response) -> {
             if (response.getStatusCode().equals(HttpStatus.OK)) {
                 return deserialize(response.getBody());
             }
             else {
                 throw new BusinessException();
             }
         });

Note: The response is closed after the exchange function has been invoked.

Type Parameters:
  `T` - the type the response will be transformed to
Parameters:
  `exchangeFunction` - the function to handle the response with
Returns:
  the value returned from the exchange function, never `null`
Since:
  6.2.6

### exchange

@Nullable <T> T exchange(RestClient.RequestHeadersSpec.ExchangeFunction<T> exchangeFunction, boolean close)
Exchange the `ClientHttpResponse` for a value of type `T`. This can be useful for advanced scenarios, for example to decode the response differently depending on the response status:

     Person person = client.get()
         .uri("/people/1")
         .accept(MediaType.APPLICATION_JSON)
         .exchange((request, response) -> {
             if (response.getStatusCode().equals(HttpStatus.OK)) {
                 return deserialize(response.getBody());
             }
             else {
                 throw new BusinessException();
             }
         });

Note: If `close` is `true`, then the response is closed after the exchange function has been invoked. When set to `false`, the caller is responsible for closing the response.

Type Parameters:
  `T` - the type the response will be transformed to
Parameters:
  `exchangeFunction` - the function to handle the response with
  `close` - `true` to close the response after `exchangeFunction` is invoked, `false` to keep it open
Returns:
  the value returned from the exchange function, potentially `null`
See Also:
  - `exchangeForRequiredValue(RequiredValueExchangeFunction, boolean)`

### exchangeForRequiredValue

<T> T exchangeForRequiredValue(RestClient.RequestHeadersSpec.RequiredValueExchangeFunction<T> exchangeFunction, boolean close)
Exchange the `ClientHttpResponse` for a value of type `T`. This can be useful for advanced scenarios, for example to decode the response differently depending on the response status:

     Person person = client.get()
         .uri("/people/1")
         .accept(MediaType.APPLICATION_JSON)
         .exchange((request, response) -> {
             if (response.getStatusCode().equals(HttpStatus.OK)) {
                 return deserialize(response.getBody());
             }
             else {
                 throw new BusinessException();
             }
         });

Note: If `close` is `true`, then the response is closed after the exchange function has been invoked. When set to `false`, the caller is responsible for closing the response.

Type Parameters:
  `T` - the type the response will be transformed to
Parameters:
  `exchangeFunction` - the function to handle the response with
  `close` - `true` to close the response after `exchangeFunction` is invoked, `false` to keep it open
Returns:
  the value returned from the exchange function, never `null`
Since:
  6.2.6