5.2. RESTクライアント（HTTPクライアント）¶

5.2.1. Overview ¶

本節では、Spring Frameworkが提供するorg.springframework.web.client.RestTemplateを使用してRESTful Web Service(REST API)を呼び出す実装方法について説明する。

5.2.1.1. `RestTemplate`とは ¶

RestTemplateは、REST API(Web API)を呼び出すためのメソッドを提供するクラスであり、Spring Frameworkが提供するHTTPクライアントである。

具体的な実装方法の説明を行う前に、RestTemplateがどのようにREST API(Web API)にアクセスしているかを説明する。

項番	コンポーネント	説明
(1)	アプリケーション	`RestTemplate`のメソッドを呼び出して、REST API(Web API)の呼び出し依頼を行う。
(2)	`RestTemplate`	`HttpMessageConverter`を使用して、Javaオブジェクトをリクエストボディに設定する電文(JSON等)に変換する。
(3)		`ClientHttpRequestFactory`から`ClientHttpRequest`を取得して、電文(JSON等)の送信依頼を行う。
(4)	`ClientHttpRequest`	電文(JSON等)をリクエストボディに設定して、REST API(Web API)にHTTP経由でリクエストを行う。
(5)	`RestTemplate`	`ResponseErrorHandler`を使用して、HTTP通信のエラー判定及びエラー処理を行う。
(6)	`ResponseErrorHandler`	`ClientHttpResponse`からレスポンスデータを取得して、エラー判定及びエラー処理を行う。
(7)	`RestTemplate`	`HttpMessageConverter`を使用して、レスポンスボディに設定されている電文(JSON等)をJavaオブジェクトに変換する。
(8)		REST API(Web API)の呼び出し結果(Javaオブジェクト)をアプリケーションへ返却する。

Note

非同期処理への対応

REST APIからの応答を別スレッドで処理したい場合(非同期で処理したい場合)は、RestTemplateの代わりにorg.springframework.web.reactive.function.client.WebClientを使用する。

非同期処理の実装例については、非同期リクエストを参照されたい。

5.2.1.1.1. `HttpMessageConverter`¶

org.springframework.http.converter.HttpMessageConverterは、アプリケーションで扱うJavaオブジェクトとサーバと通信するための電文(JSON等)を相互に変換するためのインタフェースである。

RestTemplateを使用した場合、デフォルトで以下のHttpMessageConverterの実装クラスが登録される。

**デフォルトで登録されるHttpMessageConverter**¶
項番	クラス名	説明	サポート型
(1)	`org.springframework.http.converter.` `ByteArrayHttpMessageConverter`	「HTTPボディ(テキスト or バイナリデータ)⇔バイト配列」変換用のクラス。デフォルトですべてのメディアタイプ(`/`)をサポートする。	`byte[]`
(2)	`org.springframework.http.converter.` `StringHttpMessageConverter`	「HTTPボディ(テキスト)⇔文字列」変換用のクラス。デフォルトですべてのテキストメディアタイプ(`text/*`)をサポートする。	`String`
(3)	`org.springframework.http.converter.` `ResourceHttpMessageConverter`	「HTTPボディ(バイナリデータ)⇔Springのリソースオブジェクト」変換用のクラス。デフォルトですべてのメディアタイプ(`/`)をサポートする。	`Resource`[1]
(4)	`org.springframework.http.converter.xml.` `SourceHttpMessageConverter`	「HTTPボディ(XML)⇔XMLソースオブジェクト」変換用のクラス。デフォルトでXML用のメディアタイプ(`text/xml`,`application/xml`,`application/*-xml`)をサポートする。	`Source`[2]
(5)	`org.springframework.http.converter.support.` `AllEncompassingFormHttpMessageConverter`	「HTTPボディ⇔`MultiValueMap`オブジェクト」変換用のクラス。 `FormHttpMessageConverter`の拡張クラスで、multipartのパートデータとしてXMLとJSONへの変換がサポートされている。デフォルトでフォームデータ用のメディアタイプ(`application/x-www-form-urlencoded`,`multipart/form-data`)をサポートする。メディアタイプが`application/x-www-form-urlencoded`の場合、`MultiValueMap<String, String>`として読込/書込される。メディアタイプが`multipart/form-data`の場合、`MultiValueMap<String, Object>`として書込され、`Object`は`AllEncompassingFormHttpMessageConverter`内に別途設定される`HttpMessageConveter`で変換される。（注意： Note 参照）デフォルトで登録されるパートデータ変換用の`HttpMessageConveter`は、AllEncompassingFormHttpMessageConverterと FormHttpMessageConverterのソースを参照されたい。なお、任意の`HttpMessageConverter`を登録することもできる。	`MultiValueMap`[3]

Note

AllEncompassingFormHttpMessageConverterのメディアタイプがmultipart/form-dataの場合について

メディアタイプがmultipart/form-dataの場合、「MultiValueMapオブジェクトから HTTPボディ」への変換は可能だが、「HTTPボディから MultiValueMapオブジェクト」への変換は現状サポートされていない。よって、「HTTPボディから MultiValueMapオブジェクト」への変換を行いたい場合は、独自に実装する必要がある。

**依存ライブラリがクラスパス上に存在する場合に登録されるHttpMessageConverter**¶
項番	クラス名	説明	サポート型
(6)	`org.springframework.http.converter.feed.` `AtomFeedHttpMessageConverter`	「HTTPボディ(Atom)⇔Atomフィードオブジェクト」変換用のクラス。デフォルトでATOM用のメディアタイプ(`application/atom+xml`)をサポートする。 (ROMEがクラスパスに存在する場合に登録される)	`Feed`[4]
(7)	`org.springframework.http.converter.feed.` `RssChannelHttpMessageConverter`	「HTTPボディ(RSS)⇔Rssチャネルオブジェクト」変換用のクラス。デフォルトでRSS用のメディアタイプ(`application/rss+xml`)をサポートする。 (ROMEがクラスパスに存在する場合に登録される)	`Channel`[5]
(8)	`org.springframework.http.converter.json.` `MappingJackson2HttpMessageConverter`	「HTTPボディ(JSON)⇔JavaBean」変換用のクラス。デフォルトでJSON用のメディアタイプ(`application/json`,`application/*+json`)をサポートする。 (Jackson2がクラスパスに存在する場合に登録される)	`Object`(JavaBean) `Map`
(9)	`org.springframework.http.converter.xml.` `MappingJackson2XmlHttpMessageConverter`	「HTTPボディ(XML)⇔JavaBean」変換用のクラス。デフォルトでXML用のメディアタイプ(`text/xml`,`application/xml`,`application/*-xml`)をサポートする。 (Jackson-dataformat-xmlがクラスパスに存在する場合に登録される)	`Object`(JavaBean) `Map`
(10)	`org.springframework.http.converter.xml.` `Jaxb2RootElementHttpMessageConverter`	「HTTPボディ(XML)⇔JavaBean」変換用のクラス。デフォルトでXML用のメディアタイプ(`text/xml`,`application/xml`,`application/*-xml`)をサポートする。 (JAXBがクラスパスに存在する場合に登録される) Note Java SE 17環境にてJAXBをクラスパスに登録するにはJAXBの削除を参照されたい。	`Object`(JavaBean)
(11)	`org.springframework.http.converter.json.` `GsonHttpMessageConverter`	「HTTPボディ(JSON)⇔JavaBean」変換用のクラス。デフォルトでJSON用のメディアタイプ(`application/json`,`application/*+json`)をサポートする。 (Gsonがクラスパスに存在する場合に登録される)	`Object`(JavaBean) `Map`

5.2.1.1.2. `ClientHttpRequestFactory`¶

RestTemplateは、サーバとの通信処理を以下の３つのインタフェースの実装クラスに委譲することで実現している。

org.springframework.http.client.ClientHttpRequestFactory
org.springframework.http.client.ClientHttpRequest
org.springframework.http.client.ClientHttpResponse

この3つのインタフェースのうち、開発者が意識するのはClientHttpRequestFactoryである。ClientHttpRequestFactoryは、サーバとの通信処理を行うクラス(ClientHttpRequestと ClientHttpResponseインタフェースの実装クラス)を解決する役割を担っている。

なお、Spring Frameworkが提供している主なClientHttpRequestFactoryの実装クラスは以下の通りである。

**Spring Frameworkが提供している主なClientHttpRequestFactoryの実装クラス**¶
項番	クラス名	説明
(1)	`org.springframework.http.client.` `SimpleClientHttpRequestFactory`	Java SE標準のHttpURLConnectionのAPIを使用して通信処理(同期、非同期)を行うための実装クラス。(デフォルトで使用される実装クラス)
(2)	`org.springframework.http.client.` `HttpComponentsClientHttpRequestFactory`	Apache HttpComponents HttpClientのAPIを使用して同期型の通信処理を行うための実装クラス。(HttpClient 5.2以上が必要)
(3)	`org.springframework.http.client.` `OkHttpClientHttpRequestFactory`	Square OkHttpのAPIを使用して通信処理（同期、非同期）を行うための実装クラス。

Note

使用するClientHttpRequestFactoryの実装クラスについて

RestTemplateが使用するデフォルト実装はSimpleClientHttpRequestFactoryであり、本ガイドラインでもSimpleClientHttpRequestFactoryを使用した際の実装例となっている。Java SEのHttpURLConnectionで要件が満たせない場合は、Netty、Apache Http Componentsなどのライブラリの利用を検討されたい。

Note

Content-Lengthヘッダについて

Spring Framework 6.1より、RestTemplateのメモリ使用量を減らすために、ほとんどのClientHttpRequestFactory実装クラスはサーバーへ送信する前にリクエストボディをバッファリングしなくなった。これにより、Content-Lengthヘッダが設定されなくなったため、Content-Lengthヘッダを設定する必要がある場合はBufferingClientHttpRequestFactoryでClientHttpRequestFactoryをラップする必要がある。

bean定義ファイルの定義例

ApplicationContextConfig.java

@Bean("restTemplate")
public RestTemplate restTemplate() {
    return new RestTemplate(new BufferingClientHttpRequestFactory(new SimpleClientHttpRequestFactory()));
}

applicationContext.xml

<bean id="restTemplate" class="org.springframework.web.client.RestTemplate">
    <constructor-arg>
        <bean class="org.springframework.http.client.BufferingClientHttpRequestFactory">
            <constructor-arg>
                <bean class="org.springframework.http.client.SimpleClientHttpRequestFactory" />
            </constructor-arg>
        </bean>
    </constructor-arg>
</bean>

5.2.1.1.3. `ResponseErrorHandler`¶

RestTemplateは、サーバとの通信エラーのハンドリングをorg.springframework.web.client.ResponseErrorHandlerインタフェースに委譲することで実現している。

ResponseErrorHandlerには、

エラー判定を行うメソッド(hasError)
エラー処理を行うメソッド(handleError)

が定義されており、Spring Frameworkはデフォルト実装としてorg.springframework.web.client.DefaultResponseErrorHandlerを提供している。

DefaultResponseErrorHandlerは、サーバから応答されたHTTPステータスコードの値によって以下のようなエラー処理を行う。

レスポンスコードが正常系(2xx)の場合は、エラー処理は行わない。
レスポンスコードがクライアントエラー系(4xx)の場合は、org.springframework.web.client.HttpClientErrorExceptionを発生させる。
レスポンスコードがサーバエラー系(5xx)の場合は、org.springframework.web.client.HttpServerErrorExceptionを発生させる。
レスポンスコードが未定義のコード(ユーザ定義のカスタムコード)の場合は、org.springframework.web.client.UnknownHttpStatusCodeExceptionを発生させる。

Note

エラー時のレスポンスデータの取得方法

エラー時のレスポンスデータ(HTTPステータスコード、レスポンスヘッダ、レスポンスボディなど)は、例外クラスのgetterメソッドを呼び出すことで取得することができる。

5.2.1.1.4. `ClientHttpRequestInterceptor`¶

org.springframework.http.client.ClientHttpRequestInterceptorは、サーバとの通信の前後に共通的な処理を実装するためのインタフェースである。

ClientHttpRequestInterceptorを使用すると、

サーバとの通信ログ
認証ヘッダの設定

といった共通的な処理をRestTemplateに適用することができる。

Note

ClientHttpRequestInterceptorの動作仕様

ClientHttpRequestInterceptorは複数適用することができ、指定した順番でチェーン実行される。これはサーブレットフィルタの動作によく似ており、最後に実行されるチェーン先としてClientHttpRequestによるHTTP通信処理が登録されている。例えば、ある条件に一致した際にサーバとの通信処理をキャンセルしたいという要件があった場合は、チェーン先を呼びださなければよい。

この仕組みを活用すると、

サーバとの通信の閉塞
通信処理のリトライ

といった処理を適用することもできる。

5.2.2. How to use ¶

本節では、RestTemplateを使用したクライアント処理の実装方法について説明する。

Note

RestTemplateがサポートするHTTPメソッドについて

本ガイドラインでは、GETメソッドとPOSTメソッドを使用したクライアント処理の実装例のみを紹介するが、RestTemplateは他のHTTPメソッド(PUT, PATCH, DELETE, HEAD, OPTIONSなど)もサポートしており、同じような要領で使用することができる。

詳細はRestTemplateのJavadocを参照されたい。

5.2.2.1. `RestTemplate`のセットアップ ¶

RestTemplateを使用する場合は、RestTemplateをDIコンテナに登録し、RestTemplateを利用するコンポーネントにインジェクションする。

5.2.2.1.1. 依存ライブラリ設定 ¶

RestTemplateを使用するためにpom.xmlに、Spring Frameworkのspring-webライブラリを追加する。

マルチプロジェクト構成の場合は、domainプロジェクトのpom.xmlに追加する。

<dependencies>

    <!-- (1) -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-web</artifactId>
    </dependency>

</dependencies>

Note

上記設定例は、依存ライブラリのバージョンを親プロジェクトである terasoluna-gfw-parent で管理する前提であるため、pom.xmlでのバージョンの指定は不要である。

上記の依存ライブラリはterasoluna-gfw-parentが依存しているSpring Bootで管理されている。

項番	説明
(1)	Spring Frameworkの`spring-web`ライブラリをdependenciesに追加する。

5.2.2.1.2. `RestTemplate`のbean定義 ¶

RestTemplateのbean定義を行い、DIコンテナに登録する。

bean定義ファイルの定義例

ApplicationContextConfig.java
```
@Bean("restTemplate")
public RestTemplate restTemplate() {
    return new RestTemplate(); // (1)
}
```
項番

説明

(1)

RestTemplateをデフォルト設定のまま利用する場合は、デフォルトコンストラクタを使用してbeanを登録する。

applicationContext.xml
```
<bean id="restTemplate" class="org.springframework.web.client.RestTemplate" /> 
```
項番

説明

(1)

RestTemplateをデフォルト設定のまま利用する場合は、デフォルトコンストラクタを使用してbeanを登録する。

Note

RestTemplateのカスタマイズ方法

HTTP通信処理をカスタマイズする場合は、以下のようなbean定義となる。

// (1)
@Bean("clientHttpRequestFactory")
public SimpleClientHttpRequestFactory clientHttpRequestFactory() {
    SimpleClientHttpRequestFactory bean = new SimpleClientHttpRequestFactory();
    // omitted
    return bean;
}

@Bean("restTemplate")
public RestTemplate restTemplate() {
    return new RestTemplate(clientHttpRequestFactory()); // (2)
}
項番

説明

(1)

ClientHttpRequestFactoryのbean定義を行う。

本ガイドラインではタイムアウトの設定をカスタマイズする方法を紹介している。

詳細は通信タイムアウトの設定を参照されたい。

(2)

ClientHttpRequestFactoryを引数に指定するコンストラクタを使用してbeanを登録する。
<bean id="clientHttpRequestFactory"
    class="org.springframework.http.client.SimpleClientHttpRequestFactory"> 
    
</bean>

<bean id="restTemplate" class="org.springframework.web.client.RestTemplate">
    <constructor-arg ref="clientHttpRequestFactory" /> 
</bean>
項番

説明

(1)

ClientHttpRequestFactoryのbean定義を行う。

本ガイドラインではタイムアウトの設定をカスタマイズする方法を紹介している。

詳細は通信タイムアウトの設定を参照されたい。

(2)

ClientHttpRequestFactoryを引数に指定するコンストラクタを使用してbeanを登録する。
なお、HttpMessageConverter、ResponseErrorHandler、ClientHttpRequestInterceptorのカスタマイズ方法については、

任意のHttpMessageConverterを登録する方法

ResponseEntityの返却（エラーハンドラの拡張）

共通処理の適用（ClientHttpRequestInterceptor）

を参照されたい。

5.2.2.1.3. `RestTemplate`の利用 ¶

RestTemplateを利用する場合は、DIコンテナに登録されているRestTemplateをインジェクションする。

RestTemplateのインジェクション例

@Service
public class AccountServiceImpl implements AccountService {

    @Inject
    RestTemplate restTemplate;

    // omitted

}

5.2.2.2. GETリクエストの送信 ¶

RestTemplateは、GETリクエストを行うためのメソッドを複数提供している。

通常はgetForObjectメソッド又はgetForEntityメソッドを使用する。
任意のヘッダを設定するなどリクエストに細かい設定を行いたい場合は、org.springframework.http.RequestEntityとexchangeメソッドを使用する。

5.2.2.2.1. `getForObject`メソッドを使用した実装 ¶

レスポンスボディのみ取得できればよい場合は、getForObjectメソッドを使用する。

getForObjectメソッドの使用例

フィールド宣言部

@Value("${api.url:http://localhost:8080/api}")
URI uri;

メソッド内部

User user = restTemplate.getForObject(uri, User.class); // (1)

項番	説明
(1)	`getForObject`メソッドを使用した場合は、戻り値はレスポンスボディの値になる。レスポンスボディのデータは`HttpMessageConverter`によって第2引数に指定したJavaクラスへ変換された後、返却される。

5.2.2.2.2. `getForEntity`メソッドを使用した実装 ¶

HTTPステータスコード、レスポンスヘッダ、レスポンスボディを取得する必要がある場合は、getForEntityメソッドを使用する。

getForEntityメソッドの使用例

ResponseEntity<User> responseEntity =
        restTemplate.getForEntity(uri, User.class); // (1)
HttpStatus statusCode = responseEntity.getStatusCode(); // (2)
HttpHeaders header = responseEntity.getHeaders(); // (3)
User user = responseEntity.getBody(); // (4)

項番	説明
(1)	`getForEntity`メソッドを使用した場合は、戻り値は`org.springframework.http.ResponseEntity`となる。
(2)	HTTPステータスコードは`getStatusCode`メソッドを用いて取得する。
(3)	レスポンスヘッダは`getHeaders`メソッドを用いて取得する。
(4)	レスポンスボディは`getBody`メソッドを用いて取得する。

Note

ResponseEntityとは

ResponseEntityはHTTPレスポンスを表すクラスで、HTTPステータスコード、レスポンスヘッダ、レスポンスボディの情報を取得することができる。

詳細はResponseEntityのJavadocを参照されたい。

5.2.2.2.3. `exchange`メソッドを使用した実装 ¶

リクエストヘッダを指定する必要がある場合は、org.springframework.http.RequestEntityを生成しexchangeメソッドを使用する。

exchangeメソッドの使用例

import部

import org.springframework.http.RequestEntity;
import org.springframework.http.ResponseEntity;

フィールド宣言部

@Value("${api.url:http://localhost:8080/api}")
URI uri;

メソッド内部

RequestEntity requestEntity = RequestEntity
        .get(uri)//(1)
        .build();//(2)

ResponseEntity<User> responseEntity =
        restTemplate.exchange(requestEntity, User.class);//(3)

User user = responseEntity.getBody();//(4)

項番	説明
(1)	`RequestEntity`の`get`メソッドを使用し、GETリクエスト用のリクエストビルダを生成する。パラメータにURIを設定する。
(2)	`RequestEntity.HeadersBuilder`の`build`メソッドを使用し、`RequestEntity`オブジェクトを作成する。
(3)	`exchange`メソッドを使用し、リクエストを送信する。第二引数に、レスポンスデータの型を指定する。レスポンスは、`ResponseEntity<T>`になる。型パラメータに、レスポンスデータの型を設定する。
(4)	`getBody`メソッドを使用し、レスポンスボディのデータを取得する。

Note

RequestEntityとは

RequestEntityはHTTPリクエストを表すクラスで、接続URI、HTTPメソッド、リクエストヘッダ、リクエストボディを設定することができる。

詳細はRequestEntityのJavadocを参照されたい。

なお、リクエストヘッダの設定方法については、リクエストヘッダの設定を参照されたい。

5.2.2.3. POSTリクエストの送信 ¶

RestTemplateは、POSTリクエストを行うためのメソッドを複数提供している。

通常は、postForObject、postForEntityを使用する。
任意のヘッダを設定するなどリクエストに細かい設定を行いたい場合は、RequestEntityと exchangeメソッドを使用する。

5.2.2.3.1. `postForObject`メソッドを使用した実装 ¶

POSTした結果としてレスポンスボディのみ取得できればよい場合は、postForObjectメソッドを使用する。

postForObjectメソッドの使用例

User user = new User();

// omitted

User user = restTemplate.postForObject(uri, user, User.class); // (1)

項番	説明
(1)	`postForObject`メソッドは、簡易にPOSTリクエストを実装できる。第二引数には、`HttpMessageConverter`によってリクエストボディに変換されるJavaオブジェクトを設定する。 `postForObject`メソッドを使用した場合は、戻り値はレスポンスボディの値になる。

5.2.2.3.2. `postForEntity`メソッドを使用した実装 ¶

POSTした結果としてHTTPステータスコード、レスポンスヘッダ、レスポンスボディを取得する必要がある場合は、postForEntityメソッドを使用する。

postForEntityメソッドの使用例

User user = new User();

// omitted

ResponseEntity<User> responseEntity =
        restTemplate.postForEntity(uri, user, User.class); // (1)

項番	説明
(1)	`postForEntity`メソッドも`getForObject`メソッドと同様に簡易にPOSTリクエストを実装できる。 `postForEntity`メソッドを使用した場合は、戻り値は`ResponseEntity`となる。レスポンスボディの値は、`ResponseEntity`から取得する。

5.2.2.3.3. `exchange`メソッドを使用した実装 ¶

リクエストヘッダを指定する必要がある場合は、RequestEntityを生成しexchangeメソッドを使用する。

exchangeメソッドの使用例

import部

import org.springframework.http.RequestEntity;
import org.springframework.http.ResponseEntity;

フィールド宣言部

@Value("${api.url:http://localhost:8080/api}")
URI uri;

メソッド内部

User user = new User();

// omitted

RequestEntity<User> requestEntity = RequestEntity//(1)
        .post(uri)//(2)
        .body(user);//(3)

ResponseEntity<User> responseEntity =
        restTemplate.exchange(requestEntity, User.class);//(4)

項番	説明
(1)	`RequestEntity`を使用して、リクエストを生成する。型パラメータに、リクエストボディに設定するデータの型を指定する。
(2)	`post`メソッドを使用し、POSTリクエスト用のリクエストビルダを生成する。パラメータにURIを設定する。
(3)	`RequestEntity.BodyBuilder`の`body`メソッドを使用し、`RequestEntity`オブジェクトを作成する。パラメータにリクエストボディに変換するJavaオブジェクトを設定する。
(4)	`exchange`メソッドを使用し、リクエストを送信する。

Note

リクエストヘッダの設定方法

リクエストヘッダの設定方法については、リクエストヘッダの設定を参照されたい。

5.2.2.4. コレクション形式のデータ取得 ¶

サーバから応答されるレスポンスボディの電文(JSON等)がコレクション形式の場合は、以下のような実装となる。

コレクション形式のデータの取得例

ResponseEntity<List<User>> responseEntity = //(1)
    restTemplate.exchange(requestEntity, new ParameterizedTypeReference<List<User>>(){}); //(2)

List<User> userList = responseEntity.getBody();//(3)

項番	説明
(1)	`ResponseEntity`の型パラメータに`List`<レスポンスデータの型>を指定する。
(2)	`exchange`メソッドの第二引数に`org.springframework.core.ParameterizedTypeReference`のインスタンスを指定し、型パラメータに`List`<レスポンスデータの型>を指定する。
(3)	`getBody`メソッドで、レスポンスボディのデータを取得する。

5.2.2.5. リクエストヘッダの設定 ¶

RequestEntityとexchangeメソッドを使用すると、RequestEntityのメソッドを使用して特定のヘッダ及び任意のヘッダを設定することができる。

詳細はRequestEntityのJavadocを参照されたい。

本ガイドラインでは、

Content-Typeヘッダの設定
Acceptヘッダの設定
任意のリクエストヘッダの設定

について説明する。

5.2.2.5.1. Content-Typeヘッダの設定 ¶

サーバへデータを送信する場合は、通常Content-Typeヘッダの指定が必要となる。

Content-Typeヘッダの設定例

User user = new User();

// omitted

RequestEntity<User> requestEntity = RequestEntity
        .post(uri)
        .contentType(MediaType.APPLICATION_JSON) // (1)
        .body(user);

項番	説明
(1)	`RequestEntity.BodyBuilder`の`contentType`メソッドを使用し、Context-Typeヘッダの値を指定する。上記の実装例では、データ形式がJSONであることを示す「`application/json`」を設定している。

5.2.2.5.2. Acceptヘッダの設定 ¶

サーバから取得するデータの形式を指定する場合は、Acceptヘッダの指定が必要となる。

サーバが複数のデータ形式のレスポンスをサポートしていない場合は、Acceptヘッダを明示的に指定しなくてもよいケースもある。

Acceptヘッダの設定例

User user = new User();

// omitted

RequestEntity<User> requestEntity = RequestEntity
        .post(uri)
        .accept(MediaType.APPLICATION_JSON) // (1)
        .body(user);

項番	説明
(1)	`RequestEntity.HeadersBuilder`の`accept`メソッドを使用して、Acceptヘッダの値を設定する。上記の実装例では、取得可能なデータ形式がJSONであることを示す「`application/json`」を設定している。

5.2.2.5.3. 任意のリクエストヘッダの設定 ¶

サーバへアクセスするために、リクエストヘッダの設定が必要になるケースがある。

任意ヘッダの設定例

User user = new User();

// omitted

RequestEntity<User> requestEntity = RequestEntity
        .post(uri)
        .header("Authorization", "Basic " + base64Credentials) // (1)
        .body(user);

項番	説明
(1)	`RequestEntity.HeadersBuilder`の`header`メソッドを使用してリクエストヘッダの名前と値を設定する。上記の実装例では、AuthorizationヘッダにBasic認証に必要な資格情報を設定している。

5.2.2.6. エラーハンドリング ¶

5.2.2.6.1. 例外ハンドリング(デフォルトの動作)¶

RestTemplateのデフォルト実装(DefaultResponseErrorHandler)では、

レスポンスコードがクライアントエラー系(4xx)の場合は、HttpClientErrorException
レスポンスコードがサーバエラー系(5xx)の場合は、HttpServerErrorException
レスポンスコードが未定義のコード(ユーザ定義のカスタムコード)の場合は、UnknownHttpStatusCodeException

が発生するため、必要に応じてこれらの例外をハンドリングする必要がある。

例外ハンドリングの実装例

Note

以下の実装例は、サーバエラーが発生した際の例外ハンドリングの一例である。

アプリケーションの要件に応じて適切な例外ハンドリングを行うこと。

フィールド宣言部

@Value("${api.retry.maxCount}")
int retryMaxCount;

@Value("${api.retry.retryWaitTimeCoefficient}")
int retryWaitTimeCoefficient;

メソッド内部

int retryCount = 0;
while (true) {
    try {

        responseEntity = restTemplate.exchange(requestEntity, String.class);

        if (logger.isInfoEnabled()) {
            logger.info("Success({}) ", responseEntity.getStatusCode());
        }

        break;

    } catch (HttpServerErrorException e) { // (1)

        if (retryCount == retryMaxCount) {
            throw e;
        }

        retryCount++;

        if (logger.isWarnEnabled()) {
            logger.warn("An error ({}) occurred on the server. (The number of retries:{} Times)", e.getStatusCode(),
                retryCount);
        }

        try {
            Thread.sleep(retryWaitTimeCoefficient * retryCount);
        } catch (InterruptedException ie) {
            Thread.currentThread().interrupt();
        }

        // omitted
    }

}

項番	説明
(1)	例外をキャッチしてエラー処理を行う。サーバエラー（500系）の場合、`HttpServerErrorException`をキャッチする。

5.2.2.6.2. `ResponseEntity`の返却（エラーハンドラの拡張）¶

org.springframework.web.client.ResponseErrorHandlerインタフェースの実装クラスをRestTemplateに設定することで、独自のエラー処理を行うことができる。

以下の例では、サーバエラー及びクライアントエラーが発生した場合でもResponseEntityを返すようにエラーハンドラを拡張している。

エラーハンドラの実装クラスの作成例

import org.springframework.http.client.ClientHttpResponse;
import org.springframework.web.client.DefaultResponseErrorHandler;

public class CustomErrorHandler extends DefaultResponseErrorHandler { // (1)

    @Override
    public void handleError(ClientHttpResponse response) throws IOException {
        //Don't throw Exception.
    }

}

項番	説明
(1)	`ResponseErrorHandler`インタフェースの実装クラスを作成する。上記の作成例では、デフォルトのエラーハンドラの実装クラスである`DefaultResponseErrorHandler`を拡張し、サーバエラー及びクライアントエラーが発生した際に例外を発生させずに`ResponseEntity`が返るようにしている。

bean定義ファイルの定義例

ApplicationContextConfig.java

// (1)
@Bean("customErrorHandler")
public CustomErrorHandler customErrorHandler() {
    return new CustomErrorHandler();
}

@Bean("restTemplate")
public RestTemplate restTemplate() {
    RestTemplate bean = new RestTemplate();
    bean.setErrorHandler(customErrorHandler()); // (2)
    return bean;
}

項番	説明
(1)	`ResponseErrorHandler`の実装クラスのbean定義を行う。
(2)	`errorHandler`プロパティに`ResponseErrorHandler`のbeanを設定する。

applicationContext.xml

<bean id="customErrorHandler" class="com.example.restclient.CustomErrorHandler" /> <!-- (1) -->

<bean id="restTemplate" class="org.springframework.web.client.RestTemplate">
    <property name="errorHandler" ref="customErrorHandler" /><!-- (2) -->
</bean>

項番	説明
(1)	`ResponseErrorHandler`の実装クラスのbean定義を行う。
(2)	`errorHandler`プロパティに`ResponseErrorHandler`のbeanをインジェクションする。

クライアント処理の実装例

int retryCount = 0;
while (true) {

    responseEntity = restTemplate.exchange(requestEntity, User.class);

    if (responseEntity.getStatusCode() == HttpStatus.OK) { // (1)

        break;

    } else if (responseEntity.getStatusCode() == HttpStatus.SERVICE_UNAVAILABLE) { // (2)

        if (retryCount == retryMaxCount) {
            break;
        }

        retryCount++;

        if (logger.isWarnEnabled()) {
            logger.warn("An error ({}) occurred on the server. (The number of retries:{} Times)",
                responseEntity.getStatusCode(), retryCount);
        }

        try {
            Thread.sleep(retryWaitTimeCoefficient * retryCount);
        } catch (InterruptedException ie) {
            Thread.currentThread().interrupt();
        }

        // omitted
    }
}

項番	説明
(1)	上記の実装例では、エラー時にも`ResponseEntity`を返すようにエラーハンドラを拡張しているので、返却された`ResponseEntity`からHTTPステータスコードを取得して、処理結果が正常であったか確認する必要がある。
(2)	エラー発生時も返却された`ResponseEntity`からHTTPステータスコードを取得して、その値に応じて処理を制御することができる。

5.2.2.7. 通信タイムアウトの設定 ¶

サーバとの通信に対してタイムアウト時間を指定したい場合は、以下のようなbean定義を行う。

bean定義ファイルの定義例

ApplicationContextConfig.java

// (1)
@Value("${api.connectTimeout:2000}")
private int connectTimeout;

// (2)
@Value("${api.readTimeout:2000}")
private int readTimeout;

// omitted

@Bean("clientHttpRequestFactory")
public SimpleClientHttpRequestFactory clientHttpRequestFactory() {
    SimpleClientHttpRequestFactory bean = new SimpleClientHttpRequestFactory();
    bean.setConnectTimeout(connectTimeout); // (1)
    bean.setReadTimeout(readTimeout); // (2)
    return bean;
}

@Bean("timeoutRestTemplate")
public RestTemplate timeoutRestTemplate() {
    return new RestTemplate(clientHttpRequestFactory());
}

項番	説明
(1)	`connectTimeout`プロパティにサーバとの接続タイムアウト時間(ミリ秒)を設定する。タイムアウト発生時は`org.springframework.web.client.ResourceAccessException`が発生する。
(2)	`readTimeout`プロパティにレスポンスデータの読み込みタイムアウト時間(ミリ秒)を設定する。タイムアウト発生時は`ResourceAccessException`が発生する。

Warning

プロパティが別の型にマッピングされる

SimpleClientHttpRequestFactoryのタイムアウト時間の設定に関して、以下の様にXMLConfigで以下の様に定義した場合、誤った型にマッピングされてしまう事象が確認されている。（Spring#31872, Spring#32159）

applicationContext.xml

<bean id="clientHttpRequestFactory"
      class="org.springframework.http.client.SimpleClientHttpRequestFactory">
    <property name="connectTimeout" value="${api.connectTimeout: 2000}" />
    <property name="readTimeout" value="${api.readTimeout: 2000}" />
</bean>

Spring Framework 6.1.3 では解決されておらず、XMLConfigではタイムアウト時間を設定することができないため、SimpleClientHttpRequestFactoryにタイムアウト時間を設定したい場合はFactoryBeanで定義すること。

サーバとの通信に対してタイムアウト時間を指定したい場合は、以下のようなbean定義を行う。

SimpleClientHttpRequestFactoryBean.java

package com.example.restclient;

// omitted

public class SimpleClientHttpRequestFactoryBean implements
                                                FactoryBean<SimpleClientHttpRequestFactory> {

    @Value("${api.connectTimeout:2000}")
    private int connectTimeout;

    @Value("${api.readTimeout:2000}")
    private int readTimeout;

    @Override
    public SimpleClientHttpRequestFactory getObject() throws Exception {
        SimpleClientHttpRequestFactory bean = new SimpleClientHttpRequestFactory();
        bean.setConnectTimeout(this.connectTimeout); // (1)
        bean.setReadTimeout(this.readTimeout); // (2)
        return bean;
    }

    @Override
    public Class<?> getObjectType() {
        return SimpleClientHttpRequestFactory.class;
    }

}

項番	説明
(1)	`connectTimeout`プロパティにサーバとの接続タイムアウト時間(ミリ秒)を設定する。タイムアウト発生時は`org.springframework.web.client.ResourceAccessException`が発生する。
(2)	`readTimeout`プロパティにレスポンスデータの読み込みタイムアウト時間(ミリ秒)を設定する。タイムアウト発生時は`ResourceAccessException`が発生する。

applicationContext.xml

<bean id="clientHttpRequestFactory" class="com.example.restclient.SimpleClientHttpRequestFactoryBean" />

<bean id="restTemplate" class="org.springframework.web.client.RestTemplate">
    <constructor-arg ref="clientHttpRequestFactory" />
</bean>

Note

タイムアウト発生時の起因例外

ResourceAccessExceptionは起因例外をラップしており、接続タイムアウト及び読み込みタイムアウト発生時の起因例外は共にjava.net.SocketTimeoutExceptionである。デフォルト実装(SimpleClientHttpRequestFactory)を使用した場合は、どちらのタイムアウトが発生したかを例外クラスの種類で区別できないという点を補足しておく。

なお、他のHttpRequestFactoryを使用した場合の動作は未検証であるため、起因例外が上記と異なる可能性がある。他のHttpRequestFactoryを使用する場合は、タイムアウト時に発生する例外を把握した上で適切な例外ハンドリングを行うこと。

5.2.2.8. SSL自己署名証明書の使用 ¶

テスト環境などでSSL自己署名証明書を使用する場合は、以下のように実装する。

FactoryBeanの実装例

RestTemplateのBean定義で、コンストラクタの引数に渡す org.springframework.http.client.ClientHttpRequestFactoryを作成するための org.springframework.beans.factory.FactoryBeanを実装する。

サンプルコードであるため、HttpClientConnectionManagerやHttpClientの設定値は業務要件に応じ適切に設定されたい。

import java.security.KeyStore;

import javax.net.ssl.KeyManagerFactory;
import javax.net.ssl.SSLContext;
import javax.net.ssl.TrustManagerFactory;

import org.apache.hc.client5.http.classic.HttpClient;
import org.apache.hc.client5.http.config.RequestConfig;
import org.apache.hc.client5.http.cookie.StandardCookieSpec;
import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClientBuilder;
import org.apache.hc.client5.http.impl.classic.HttpClients;
import org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManager;
import org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManagerBuilder;
import org.apache.hc.client5.http.ssl.SSLConnectionSocketFactoryBuilder;
import org.apache.hc.core5.http.io.SocketConfig;
import org.apache.hc.core5.http.ssl.TLS;
import org.apache.hc.core5.pool.PoolConcurrencyPolicy;
import org.apache.hc.core5.pool.PoolReusePolicy;
import org.apache.hc.core5.util.TimeValue;
import org.apache.hc.core5.util.Timeout;
import org.springframework.beans.factory.DisposableBean;
import org.springframework.beans.factory.FactoryBean;
import org.springframework.http.client.ClientHttpRequestFactory;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;

public class RequestFactoryBean implements
                                FactoryBean<ClientHttpRequestFactory>,
                                DisposableBean { // (17)

    private String keyStoreFileName;

    private char[] keyStorePassword;

    private HttpComponentsClientHttpRequestFactory factory; // (17)

    @Override
    public ClientHttpRequestFactory getObject() throws Exception {

        // (1)
        SSLContext sslContext = SSLContext.getInstance("TLS");

        KeyStore ks = KeyStore.getInstance(KeyStore.getDefaultType());
        ks.load(this.getClass().getClassLoader().getResourceAsStream(
                this.keyStoreFileName), this.keyStorePassword);

        KeyManagerFactory kmf = KeyManagerFactory.getInstance(KeyManagerFactory
                .getDefaultAlgorithm());
        kmf.init(ks, this.keyStorePassword);

        TrustManagerFactory tmf = TrustManagerFactory.getInstance(
                TrustManagerFactory.getDefaultAlgorithm());
        tmf.init(ks);

        sslContext.init(kmf.getKeyManagers(), tmf.getTrustManagers(), null);

        // @formatter:off
        PoolingHttpClientConnectionManager connectionManager = PoolingHttpClientConnectionManagerBuilder.create() // (2)
                .setSSLSocketFactory( // (3)
                        SSLConnectionSocketFactoryBuilder.create()
                        .setSslContext(sslContext)
                        .setTlsVersions(TLS.V_1_3, TLS.V_1_2)
                        .build())
                .setDefaultSocketConfig( // (4)
                        SocketConfig.custom()
                        .setSoTimeout(Timeout.ofMinutes(1L))
                        .build())
                .setMaxConnTotal(1) // (5)
                .setMaxConnPerRoute(1) // (6)
                .setPoolConcurrencyPolicy(PoolConcurrencyPolicy.STRICT) // (7)
                .setConnPoolPolicy(PoolReusePolicy.LIFO) // (8)
                .setDefaultConnectionConfig( // (9)
                        ConnectionConfig.custom()
                        .setTimeToLive(TimeValue.ofMinutes(1L)) // (10)
                        .setConnectTimeout(Timeout.ofSeconds(5L)) // (11)
                        .build())
                .build();
        // @formatter:on

        // @formatter:off
        CloseableHttpClient httpClient = HttpClients.custom() // (12)
                .setConnectionManager(connectionManager) // (13)
                .setDefaultRequestConfig(
                        RequestConfig.custom()
                        .setResponseTimeout(Timeout.ofSeconds(10L)) // (14)
                        .setCookieSpec(StandardCookieSpec.STRICT) // (15)
                        .build())
                .build();
        // @formatter:on

        // (16)
        this.factory = new HttpComponentsClientHttpRequestFactory(httpClient);

        return this.factory;
    }

    @Override
    public Class<?> getObjectType() {
        return ClientHttpRequestFactory.class;
    }

    @Override
    public boolean isSingleton() {
        return true;
    }

    public void setKeyStoreFileName(String keyStoreFileName) {
        this.keyStoreFileName = keyStoreFileName;
    }

    public void setKeyStorePassword(char[] keyStorePassword) {
        this.keyStorePassword = keyStorePassword;
    }

    // (17)
    @Override
    public void destroy() throws Exception {
        if (this.factory != null) {
            this.factory.destroy();
        }
    }
}

項番	説明
(1)	後述のbean定義で指定されたキーストアファイルのファイル名とパスワードを元に、SSLコンテキストを作成する。使用するSSL自己署名証明書のキーストアファイルは、クラスパス上に配置する。
(2)	(1)で作成したSSLコンテキストを設定するためのHttpClientConnectionManagerを作成する。ここでは、実装クラスとして`org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManager`を指定している。
(3)	(1)で作成したSSLコンテキストを設定する。
(4)	Socket Configのデフォルト値を設定する。 `Socket`から提供される`InputStream`の`read()`のブロック時間がSoTimeoutを越えた場合、通常、`java.net.SocketTimeoutException`が発生するが、TCPコネクション確立後、SSLハンドシェイクを行っている間にこのタイムアウトが起きた場合には、`org.apache.hc.client5.http.ConnectTimeoutException`が発生する。 Note SoTimeoutはSSLハンドシェイクが完了する十分な長さを確保すること。 SSLハンドシェイク完了前に`SoTimeout`によってタイムアウトした際に、SSLハンドシェイクが中断される(SSLハンドシェイクに関する続きの通信を行わなくなる)がTCPコネクションのcloseも行われない事象を確認している。この状態になると、サーバ側で処理を破棄しない限りサーバ側はSSLハンドシェイクの続きを待つこととなってしまう。そのため、SSLハンドシェイク中に通信障害や通信相手のハードウェア障害等に遭遇し通信相手からのパケットが届かない時間が長く続く場合(クライアント側で通信の継続を諦めなければならない場合)以外においては、`SoTimeout`を利用したタイムアウトは避けたほうが良い。 SSLハンドシェイク完了後のHTTPSリクエストに対するレスポンスのタイムアウトには、後述の`ResponseTimeout`が利用できるため、 HTTPSリクエストに対する応答に関するタイムアウトには`ResponseTimeout` `ResponseTimeout`の有効範囲外(HTTPSリクエスト送信前)となるSSLハンドシェイク中の応答に関するタイムアウトには`SoTimeout`(正常稼働時にはタイムアウトしないよう長めに設定) という具合に使い分けること。なお、`SoTimeout`のデフォルト値は3分となっている。
(5)	最大合計接続数を設定する。最大合計接続数を超える場合、後続処理はコネクションの取得を待機する。
(6)	宛先（ホスト名 + ポート番号及びスキーマ定義）ごとの最大接続数を設定する。最大接続数を超える場合、後続処理はコネクションの取得を待機する。
(7)	プール同時実行ポリシーを設定する。
(8)	プールされたコネクションの再利用ポリシーを設定する。
(9)	コネクションに関連するデフォルト値を設定する。
(10)	コネクションが接続されてから切断されるまでの最大生存時間を設定する。使用状況にかかわらず、ConnectionTimeToLiveを越えた場合にコネクションを破棄する。
(11)	新しい接続が確立されるまでのタイムアウトのデフォルト値を設定する。接続の確立にConnectTimeout以上かかった場合、`org.apache.hc.client5.http.HttpHostConnectException`が発生する。
(12)	作成したSSLコンテキストを利用する `org.apache.hc.client5.http.impl.classic.CloseableHttpClient`を作成する。
(13)	(2)で作成した`HttpClientConnectionManager`を設定する。
(14)	レスポンスタイムアウトのデフォルト値を設定する。レスポンス返却にResponseTimeout以上かかった場合、`java.net.SocketTimeoutException`が発生する。
(15)	HttpClientがサポートするCookieの仕様を設定する。
(16)	作成した`HttpClient`を利用する`ClientHttpRequestFactory`を作成する。
(17)	`FactoryBean`で生成したオブジェクトのライフサイクルはDIコンテナで管理されないため、破棄時に特定の処理を実行するには`FactoryBean`に`DisposableBean`インタフェースの`destroy`メソッドを実装する必要がある。ここでは、`getObject`メソッドで生成した `HttpComponentsClientHttpRequestFactory`の`destroy`メソッドを呼び出し、`HttpClient`をクローズしている。このため、生成したオブジェクトを変数に保持している。

Note

通信先のアプリケーションがTLS 1.2以前のバージョンにしか対応していない等の理由により、使用するTLSのバージョンをJVMレベルで変更するにはHTTP通信におけるTLS(Transport Layer Security) v1.3のサポートを参照されたい。

ただし、JVMレベルで設定してしまうと一つのクライアントアプリからTLS 1.2とTLS 1.3を利用した別々のアプリケーションに接続するような要件を実現することができない。このような場合は、HttpClientごとに利用するTLSのバージョンを指定するような実装を検討されたい。

HttpClientおよび HttpClientBuilderを使用するためには、Apache HttpComponents HttpClient のライブラリが必要となる。

以下を pom.xmlに追加し、Apache HttpComponents HttpClient を依存ライブラリに追加する。

pom.xml
```
<dependency>
    <groupId>org.apache.httpcomponents.client5</groupId>
    <artifactId>httpclient5</artifactId>
</dependency>
```
Note

上記設定例は、依存ライブラリのバージョンを親プロジェクトである terasoluna-gfw-parent で管理する前提であるため、pom.xmlでのバージョンの指定は不要である。

上記の依存ライブラリはterasoluna-gfw-parentが依存しているSpring Bootで管理されている。

bean定義ファイルの定義例

SSL自己署名証明書を使用したSSL通信を行う RestTemplateを定義する。

ApplicationContextConfig.java

@Value("${rscl.keystore.filename}")
private String keystoreFilename;

@Value("${rscl.keystore.password}")
private String keystorePassword;

// omitted

@Bean("httpsRestTemplate")
public RestTemplate httpsRestTemplate() throws Exception {
    return new RestTemplate(httpsRequestFactoryBean().getObject()); // (1)
}

// (1)
@Bean("httpsRequestFactoryBean")
public RequestFactoryBean httpsRequestFactoryBean() {
    RequestFactoryBean factory = new RequestFactoryBean();
    factory.setKeyStoreFileName(keystoreFilename);
    factory.setKeyStorePassword(keystorePassword.toCharArray());
    return factory;
}

項番	説明
(1)	作成した `RequestFactoryBean`を `RestTemplate`のコンストラクタに指定する。 `RequestFactoryBean`には、キーストアファイルのファイル名とパスワードを渡す。

applicationContext.xml

<bean id="httpsRestTemplate" class="org.springframework.web.client.RestTemplate">
    <constructor-arg>
        <bean class="com.example.restclient.RequestFactoryBean"> <!-- (1) -->
            <property name="keyStoreFileName" value="${rscl.keystore.filename}" />
            <property name="keyStorePassword" value="${rscl.keystore.password}" />
        </bean>
    </constructor-arg>
</bean>

項番	説明
(1)	作成した `RequestFactoryBean`を `RestTemplate`のコンストラクタに指定する。 `RequestFactoryBean`には、キーストアファイルのファイル名とパスワードを渡す。

RestTemplateの使用方法

RestTemplateの使い方については、SSL自己署名証明書を使用しない場合と同じである。

5.2.2.9. Basic認証 ¶

サーバがBasic認証を要求する場合は、以下のように実装する。このとき、Java標準のjava.util.Base64を使用する。

Basic認証の実装例

フィールド宣言部

@Value("${api.auth.username}")
String username;

@Value("${api.auth.password}")
String password;

メソッド内部

String plainCredentials = username + ":" + password; // (1)
String base64Credentials = Base64.getEncoder()
        .encodeToString(plainCredentials.getBytes(StandardCharsets.UTF_8)); // (2)

RequestEntity requestEntity = RequestEntity
      .get(uri)
      .header("Authorization", "Basic " + base64Credentials) // (3)
      .build();

項番	説明
(1)	ユーザ名とパスワードを「”`:`“ 」でつなげる。
(2)	（1）をバイト配列に変換して、Base64エンコードする。
(3)	AuthorizationヘッダをBasic認証の資格情報を設定する。

Note

Spring Security 5より、org.springframework.security.crypto.codec.Base64は非推奨になったため、Java標準のjava.util.Base64に置き換えることを推奨する。

5.2.2.10. ファイルアップロード(マルチパートリクエスト)¶

RestTemplateを使用してファイルアップロード(マルチパートリクエスト)を行う場合は、以下のように実装する。

ファイルアップロードの実装例

MultiValueMap<String, Object> multiPartBody = new LinkedMultiValueMap<>();//(1)
multiPartBody.add("file", new ClassPathResource("/uploadFiles/User.txt"));//(2)

RequestEntity<MultiValueMap<String, Object>> requestEntity = RequestEntity
        .post(uri)
        .contentType(MediaType.MULTIPART_FORM_DATA)//(3)
        .body(multiPartBody);//(4)

項番	説明
(1)	マルチパートリクエストとして送信するデータを格納するために`MultiValueMap`を生成する。
(2)	パラメータ名をキーに指定して、アップロードするファイルを`MultiValueMap`に追加する。上記例では、`file`というパラメータ名を指定して、クラスパス上に配置されているファイルをアップロードファイルとして追加している。
(3)	Content-Typeヘッダのメディアタイプを`multipart/form-data`に設定する。
(4)	アップロードするファイルが格納されている`MultiValueMap`をリクエストボディに設定する。

Note

Spring Frameworkが提供するResourceクラスについて

Spring Frameworkはリソースを表現するインタフェースとしてorg.springframework.core.io.Resourceを提供しており、ファイルをアップロードする際に使用することができる。

Resourceインタフェースの主な実装クラスは以下の通りである。

org.springframework.core.io.PathResource
org.springframework.core.io.FileSystemResource
org.springframework.core.io.ClassPathResource
org.springframework.core.io.UrlResource
org.springframework.core.io.InputStreamResource (ファイル名をサーバに連携できない)
org.springframework.core.io.ByteArrayResource (ファイル名をサーバに連携できない)

5.2.2.11. ファイルダウンロード ¶

RestTeamplateを使用してファイルダウンロードを行う場合は、以下のように実装する。

ファイルダウンロードの実装例（ファイルサイズが小さい場合）

RequestEntity requestEntity = RequestEntity
        .get(uri)
        .build();

ResponseEntity<byte[]> responseEntity =
        restTemplate.exchange(requestEntity, byte[].class);//(1)

byte[] downloadContent = responseEntity.getBody();//(2)

項番	説明
(1)	ダウンロードファイルを指定したデータ型で扱う。ここでは、バイト配列を指定。
(2)	レスポンスボディからダウンロードしたファイルのデータを取得する。

Warning

サイズの大きいファイルをダウンロードする際の注意点

サイズの大きなファイルをデフォルトで登録されているHttpMessageConverterを使用して byte配列で取得すると、 java.lang.OutOfMemoryErrorが発生する可能性がある。そのため、サイズの大きなファイルをダウンロードしたい場合は、レスポンスから InputStreamを取得して、ダウンロードデータを少しずつファイルに書き出す必要がある。

ファイルダウンロードの実装例（ファイルサイズが大きい場合）

// (1)
final ResponseExtractor<ResponseEntity<File>> responseExtractor =
        new ResponseExtractor<ResponseEntity<File>>() {

    // (2)
    @Override
    public ResponseEntity<File> extractData(ClientHttpResponse response)
            throws IOException {

        File rcvFile = File.createTempFile("rcvFile", "zip");

        FileCopyUtils.copy(response.getBody(), new FileOutputStream(rcvFile));

        return ResponseEntity.status(response.getStatusCode())
                .headers(response.getHeaders()).body(rcvFile);
    }

};

// (3)
ResponseEntity<File> responseEntity = this.restTemplate.execute(targetUri,
        HttpMethod.GET, null, responseExtractor);
if (HttpStatus.OK.equals(responseEntity.getStatusCode())) {
    File getFile = responseEntity.getBody();

    // omitted

}

項番	説明
(1)	`RestTemplate#execute`で取得されたレスポンスから、`RestTemplate#execute`の戻り値を作成するための処理を作成する。
(2)	レスポンスボディ(`InputStream`)からデータを読込み、ファイルを作成する。作成したファイルとHTTPヘッダ、ステータスコードを `ResponseEntity<File>`に格納して返却する。
(3)	`RestTemplate#execute`を使用して、ファイルのダウンロードを行う。

ファイルダウンロードの実装例（ファイルサイズが大きい場合（ResponseEntityを使わない例））

ステータスコードの判定やHTTPヘッダの参照等が不要な場合は、以下のようにResponseEntityではなく Fileを返却すればよい。

final ResponseExtractor<File> responseExtractor = new ResponseExtractor<File>() {

    @Override
    public File extractData(ClientHttpResponse response)
            throws IOException {

        File rcvFile = File.createTempFile("rcvFile", "zip");

        FileCopyUtils.copy(response.getBody(), new FileOutputStream(
                rcvFile));

        return rcvFile;
    }

};

File getFile = this.restTemplate.execute(targetUri, HttpMethod.GET,
        null, responseExtractor);
// omitted

5.2.2.12. RESTfulなURL(URIテンプレート)を扱う方法と実装例 ¶

RESTfulなURLを扱うには、URIテンプレートを使用して実装を行えばよい。

getForObjectメソッドでの使用例

フィールド宣言部

@Value("${api.serverUrl}/api/users/{userId}") // (1)
String uriStr;

メソッド内部

User user = restTemplate.getForObject(uriStr, User.class, "0001"); // (2)

項番	説明
(1)	URIテンプレートの変数{userId}は、`RestTeamplate`の使用時に指定の値に変換される。
(2)	URIテンプレートの変数1つ目が`getForObject`メソッドの第3引数に指定した値で置換され、『`http://localhost:8080/api/users/0001`』として処理される。

exchangeメソッドでの使用例

@Value("${api.serverUrl}/api/users/{action}") // (1)
String uriStr;

メソッド内部

URI targetUri = UriComponentsBuilder.fromUriString(uriStr).
        buildAndExpand("create").toUri(); //(2)

User user = new User();

// omitted

RequestEntity<User> requestEntity = RequestEntity
        .post(targetUri)
        .body(user);

ResponseEntity<User> responseEntity = restTemplate.exchange(requestEntity, User.class);

項番	説明
(1)	URIテンプレートの変数{action}は、`RestTeamplate`の使用時に指定の値に変換される。
(2)	`UriComponentsBuilder`を使用することで、URIテンプレートの変数1つ目が`buildAndExpand`の引数で指定した値に置換され、『`http://localhost:8080/api/users/create`』のURIが作成される。詳細はUriComponentsBuilderのJavadocを参照されたい。

5.2.3. How to extend ¶

本節では、RestTemplateの拡張方法について説明する。

5.2.3.1. 任意の`HttpMessageConverter`を登録する方法 ¶

デフォルトで登録されている HttpMessageConverterで電文変換の要件を満たせない場合は、任意のHttpMessageConverterを登録することができる。ただし、デフォルトで登録されていたHttpMessageConverterは削除されるので、必要なHttpMessageConverterをすべて個別に登録する必要がある。

bean定義ファイルの定義例

ApplicationContextConfig.java

// (1)
@Bean("jaxb2CollectionHttpMessageConverter")
public Jaxb2CollectionHttpMessageConverter<?> jaxb2CollectionHttpMessageConverter() {
    return new Jaxb2CollectionHttpMessageConverter<>();
}

@Bean("collectionRestTemplate")
public RestTemplate collectionRestTemplate() {
    RestTemplate bean = new RestTemplate();
    List<HttpMessageConverter<?>> messageConverters = new ArrayList<>();
    messageConverters.add(jaxb2CollectionHttpMessageConverter()); // (2)
    bean.setMessageConverters(messageConverters);
    return bean;
}

項番	説明
(1)	登録する`HttpMessageConverter`の実装クラスをbean定義する。
(2)	`messageConverters`プロパティに登録する`HttpMessageConverter`のbeanを設定する。

applicationContext.xml

<bean id="jaxb2CollectionHttpMessageConverter"
      class="org.springframework.http.converter.xml.Jaxb2CollectionHttpMessageConverter" /> <!-- (1) -->

<bean id="restTemplate" class="org.springframework.web.client.RestTemplate">
    <property name="messageConverters"> <!-- (2) -->
        <list>
            <ref bean="jaxb2CollectionHttpMessageConverter" />
        </list>
    </property>
</bean>

項番	説明
(1)	登録する`HttpMessageConverter`の実装クラスをbean定義する。
(2)	`messageConverters`プロパティに登録する`HttpMessageConverter`のbeanをインジェクションする。

5.2.3.2. 共通処理の適用（`ClientHttpRequestInterceptor`）¶

ClientHttpRequestInterceptorを使用することで、サーバとの通信処理の前後に任意の処理を実行させることができる。

ここでは、ロギング処理と、Basic認証用のリクエストヘッダ設定処理を適用する方法を紹介する。

5.2.3.2.1. ロギング処理 ¶

サーバとの通信ログを出力したい場合は、以下のような実装を行う。

通信ログ出力の実装例

package com.example.restclient;

import java.io.IOException;
import java.nio.charset.StandardCharsets;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpRequest;
import org.springframework.http.client.ClientHttpRequestExecution;
import org.springframework.http.client.ClientHttpRequestInterceptor;
import org.springframework.http.client.ClientHttpResponse;

public class LoggingInterceptor implements ClientHttpRequestInterceptor { //(1)

    private static final Logger logger = LoggerFactory.getLogger(LoggingInterceptor.class);

    @Override
    public ClientHttpResponse intercept(HttpRequest request, byte[] body,
            ClientHttpRequestExecution execution) throws IOException {

        if (logger.isInfoEnabled()) {
            String requestBody = new String(body, StandardCharsets.UTF_8);

            logger.info("Request Header {}", request.getHeaders()); //(2)
            logger.info("Request Body {}", requestBody);
        }

        ClientHttpResponse response = execution.execute(request, body); //(3)

        if (logger.isInfoEnabled()) {
            logger.info("Response Header {}", response.getHeaders()); // (4)
            logger.info("Response Status Code {}", response.getStatusCode()); // (5)
        }

        return response; // (6)
    }

}

項番	説明
(1)	`ClientHttpRequestInterceptor`インタフェースを実装する。
(2)	リクエストする前に行いたい共通処理を実装する。上記の実装例では、リクエストヘッダーとリクエストボディの内容をログに出力している。
(3)	`intercept`メソッドの引数として受け取った`ClientHttpRequestExecution`の`execute`メソッドを実行し、リクエストの送信を実行する。
(4)	レスポンスを受け取った後に行いたい共通処理を実装する。上記の実装例では、レスポンスヘッダの内容をログに出力している。
(5)	(4)と同様に、ステータスコードの内容をログに出力している。
(6)	(3)で受信したレスポンスをリターンする。

bean定義ファイルの定義例

ApplicationContextConfig.java

// (1)
@Bean("loggingInterceptor")
public LoggingInterceptor loggingInterceptor() {
    return new LoggingInterceptor();
}

項番	説明
(1)	`ClientHttpRequestInterceptor`の実装クラスのbean定義を行う。

applicationContext.xml
```

<bean id="loggingInterceptor" class="com.example.restclient.LoggingInterceptor" />
```
項番

説明

(1)

ClientHttpRequestInterceptorの実装クラスのbean定義を行う。

5.2.3.2.2. Basic認証用のリクエストヘッダ設定処理 ¶

サーバにアクセスするためにBasic認証用のリクエストヘッダを設定する必要がある場合は、以下のようなbean定義を行う。

bean定義ファイルの定義例

ApplicationContextConfig.java

// (2)
@Value("${api.auth.username}")
private String basicAuthUsername;

// (3)
@Value("${api.auth.password}")
private String basicAuthPassword;

// (1)
@Bean("basicAuthInterceptor")
public BasicAuthenticationInterceptor basicAuthInterceptor() {
    return new BasicAuthenticationInterceptor(basicAuthUsername, basicAuthPassword); // (2)(3)
}

項番	説明
(1)	`ClientHttpRequestInterceptor`インタフェースを実装した`BasicAuthorizationInterceptor`のbean定義を行う。
(2)	コンストラクタ引数の`username`にユーザ名を設定する。
(3)	コンストラクタ引数の`password`にパスワードを設定する。

applicationContext.xml

<!-- (1) -->
<bean id="basicAuthInterceptor" class="org.springframework.http.client.support.BasicAuthorizationInterceptor">
    <constructor-arg name="username" value="${api.auth.username}" /><!-- (2) -->
    <constructor-arg name="password" value="${api.auth.password}" /><!-- (3) -->
</bean>

項番	説明
(1)	`ClientHttpRequestInterceptor`インタフェースを実装した`BasicAuthorizationInterceptor`のbean定義を行う。
(2)	コンストラクタ引数の`username`にユーザ名を設定する。
(3)	コンストラクタ引数の`password`にパスワードを設定する。

5.2.3.2.3. `ClientHttpRequestInterceptor`の適用 ¶

RestTemplateに作成したClientHttpRequestInterceptorを適用する場合は、以下のようなbean定義を行う。

bean定義ファイルの定義例

ApplicationContextConfig.java

@Bean("basicAuthInterceptor")
public BasicAuthenticationInterceptor basicAuthInterceptor() {
    // omitted
}

@Bean("loggingInterceptor")
public LoggingInterceptor loggingInterceptor() {
    // omitted
}

@Bean("restTemplate")
public RestTemplate restTemplate() {
    RestTemplate bean = new RestTemplate();
    List<ClientHttpRequestInterceptor> list = new ArrayList<>(); // (1)
    list.add(basicAuthInterceptor()); // (1)
    list.add(loggingInterceptor()); // (1)
    bean.setInterceptors(list); // (1)
    return bean;
}

項番	説明
(1)	`interceptors`プロパティに`ClientHttpRequestInterceptor`のListを設定する。複数のbeanを設定した場合は、リストの先頭から順にチェーン実行される。上記の例だと、`BasicAuthorizationInterceptor` -> `LoggingInterceptor` -> `ClientHttpRequest` の順番でリクエスト前の処理が実行される。(レスポンス後の処理は順番が逆転する)

applicationContext.xml

<bean id="restTemplate" class="org.springframework.web.client.RestTemplate">
    <property name="interceptors"><!-- (1) -->
        <list>
            <ref bean="basicAuthInterceptor" />
            <ref bean="loggingInterceptor" />
        </list>
    </property>
</bean>

項番	説明
(1)	`interceptors`プロパティに`ClientHttpRequestInterceptor`のListをインジェクションする。複数のbeanをインジェクションした場合は、リストの先頭から順にチェーン実行される。上記の例だと、`BasicAuthorizationInterceptor` -> `LoggingInterceptor` -> `ClientHttpRequest` の順番でリクエスト前の処理が実行される。(レスポンス後の処理は順番が逆転する)

5.2.3.3. 非同期リクエスト ¶

非同期リクエストを行う場合は、org.springframework.web.reactive.function.client.WebClientを使用する。

Note

Spring Framework 6.0からAsyncRestTemplateは削除されており、非同期リクエストはSpring Web Reactive APIのWebClientを使用するように案内されている。

Macchinetta Server Framework (1.x)ではAsyncRestTemplateの代替機能としてWebClientを案内しているだけであり、Spring Web Reactiveをサポートしているわけではない点に注意されたい。

5.2.3.3.1. `WebClient`のセットアップ ¶

WebClientを使用する場合は、WebClientをDIコンテナに登録し、WebClientを利用するコンポーネントにインジェクションする。

5.2.3.3.1.1. 依存ライブラリ設定¶

WebClientを使用するためにpom.xmlに、Spring Frameworkのspring-webfluxライブラリを追加する。

マルチプロジェクト構成の場合は、domainプロジェクトのpom.xmlに追加する。

<dependencies>

    <!-- (1) -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-webflux</artifactId>
    </dependency>
    <!-- (2) -->
    <dependency>
          <groupId>io.projectreactor.netty</groupId>
          <artifactId>reactor-netty</artifactId>
    </dependency>

</dependencies>

項番	説明
(1)	`spring-webflux`ライブラリをdependenciesに追加する。
(1)	`reactor-netty`ライブラリをdependenciesに追加する。

Note

上記設定例は、依存ライブラリのバージョンを親プロジェクトである terasoluna-gfw-parent で管理する前提であるため、pom.xmlでのバージョンの指定は不要である。

上記の依存ライブラリはterasoluna-gfw-parentが依存しているSpring Bootで管理されている。

5.2.3.3.2. `WebClient`のbean定義 ¶

WebClientのbean定義を行い、DIコンテナに登録する。

Bean定義の実装例(WebClientConfig.java)

@Configuration
public class WebClientConfig {

    @Bean
    public WebClient defaultWebClient() {
        // (1)
        return WebClient.builder().build();
    }

}

項番

説明

(1)

WebClient.BuilderをbuildすることでWebClientを生成しBeanとして登録する。
WebClient.Builderはオプションを付けることでカスタマイズすることが可能である。
設定できるオプションは以下の通り。

Configuration	説明
uriBuilderFactory	ベースURLとして使用するUriBuilderFactoryをカスタマイズ。
defaultUriVariables	URIテンプレートを展開する際に使用するデフォルト値。
defaultHeader	リクエストのHeader。
defaultCookie	リクエストごとのCookie。
defaultRequest	リクエストをカスタマイズ。
filter	リクエスト時に使用されるFilter
exchangeStrategies	HTTP MessageのReader/Writerをカスタマイズ。
clientConnector	HTTP Client ライブラリを設定。

5.2.3.3.3. 非同期リクエストの実装 ¶

非同期リクエストの実装例

フィールド宣言部

@Inject
WecClient webClient;

メソッド内部

CompletableFuture<ResponseEntity<User>> responseEntity = this.webClient
        .get() // (1)
        .uri(uri) // (1)
        .retrieve() // (2)
        .toEntity(User.class) // (2)
        .doOnSuccess(r -> { // (3)
            // omitted
        })
        .doOnError(t -> { // (3)
            // omitted
        })
        .toFuture(); // (4)

項番	説明
(1)	`WebClient`の各メソッドを使用して、非同期リクエストを送信する。上記の実装例では、`uri`に対しGETメソッドでHTTPリクエストを送信している。使用できるメソッドについてはWebClientのJavadocを参照されたい。
(2)	処理結果の取得方法を定義する。この例では、`User.class`でレスポンスを受け取れるよう定義している。
(3)	成功のレスポンスが返ってきた場合の処理を`doOnSuccess`に実装する。エラーが発生した場合の処理を`doOnError`に実装する。
(4)	非同期処理の結果をCompletableFutureでラップした`ResponseEntity<User>`として受け取る。 Note WebClientの返却値について Reactive APIが使用する戻り値の型は、単数の場合はreactor.core.publisher.Mono、複数の場合はreactor.core.publisher.Fluxが一般的に用いられるが、この例では`CompletableFuture`を返却するようにしている。 Tip `block()`を使用し、同期的に処理させることも可能である。その場合の戻り値の型は`ResponseEntity<User>`となる。

5.2.3.3.4. カスタマイズ ¶

WebClient.Builderをカスタマイズし、WebClientにデフォルトで設定する方法を説明する。

ここでの説明はあくまで一例であるため、業務要件に合わせ適宜カスタマイズされたい。

5.2.3.3.4.1. コネクションプールの設定¶

コネクションプールの設定を行う方法を説明する。

Bean定義の実装例(WebClientConfig.java)

@Configuration
public class WebClientConfig {

  // omitted

  @Bean
  public WebClient connectionWebClient() {

      // @formatter:off
      ConnectionProvider connectionProvider = ConnectionProvider.builder(this.connectionName) // (1)
              .maxConnections(this.maxConnections) // (2)
              .pendingAcquireMaxCount(this.pendingAcquireMaxCount) // (3)
              .pendingAcquireTimeout(Duration.ofSeconds(this.pendingAcquireTimeout)) // (4)
              .build();
      // @formatter:on

      HttpClient httpClient = HttpClient.create(connectionProvider); // (5)

      ReactorClientHttpConnector httpConnector = new ReactorClientHttpConnector(httpClient); // (6)

      // @formatter:off
      WebClient webClient = WebClient.builder()
              .clientConnector(httpConnector) // (7)
              .build();
      // @formatter:on

      return webClient;
  }

項番	説明
(1)	`reactor.netty.resources.ConnectionProvider`のbuilderを作成する。
(2)	builderにMaxコネクション数を設定する。設定しない場合は、デフォルト値`2 * プロセッサ数`が使用される。
(3)	builderにMaxプール数を設定する。 “`-1`“を設定した場合は無制限となる。
(4)	TimeoutException がスローされるまでの最大時間(ms)を設定する。設定しない場合は、デフォルト45秒が使用される。 “`-1`“を設定した場合は無制限となる。
(5)	(1)~(4)で生成した`reactor.netty.resources.ConnectionProvider`を設定した`reactor.netty.http.client.HttpClient`を生成する。
(6)	(5)で定義した`HttpClient`を設定した`org.springframework.http.client.reactive.ReactorClientHttpConnector`のbeanを登録する。
(7)	(6)で定義した`ReactorClientHttpConnector`を設定した`WebClient`のbeanを登録する。

5.2.3.3.4.2. フィルターの設定¶

org.springframework.web.reactive.function.client.ExchangeFilterFunctionを実装することで、サーバとの通信処理前に任意の処理を実行させることができる。

ここでは単純な例として、通信前のロギング処理の実装例を紹介する。なお、サーバとの通信処理後に任意の処理を実施したい場合は、doOnSuccessに実装すればよい。

通信ログ出力の実装例

package com.example.webclient;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.reactive.function.client.ClientRequest;
import org.springframework.web.reactive.function.client.ClientResponse;
import org.springframework.web.reactive.function.client.ExchangeFilterFunction;
import org.springframework.web.reactive.function.client.ExchangeFunction;

import reactor.core.publisher.Mono;

public class WebClientExchangeFilterFunction implements ExchangeFilterFunction { // (1)

    private static final Logger LOGGER = LoggerFactory.getLogger(
            WebClientExchangeFilterFunction.class);

    @Override
    public Mono<ClientResponse> filter(ClientRequest request,
            ExchangeFunction next) {
        LOGGER.info("External Request to {}", request.url()); // (2)
        return next.exchange(request); // (3)
    }

}

項番	説明
(1)	`ExchangeFilterFunction`インタフェースを実装する。
(2)	非同期リクエストを送信する前に実行する処理を実装する。上記の実装例では、通信先のURLを出力している。
(3)	次の`ExchangeFilterFunction`を呼び出す。

Bean定義の実装例(WebClientConfig.java)

@Configuration
public class WebClientConfig {

    @Bean
    public WebClient loggingWebClient() {

        // @formatter:off
        WebClient webClient = WebClient.builder()
                .filter(new LoggingExchangeFilterFunction()) // (1)
                .build();
        // @formatter:on

        return webClient;
    }

項番

説明

(1)

ExchangeFilterFunctionの実装クラスをfilterに登録する。

Note

複数のFilterを登録したい場合は、filtersを使用してFilterを登録する。

WebClient webClient = WebClient.builder().filters(f -> {
    f.add(0, new FirstExchangeFilterFunction());
    f.add(1, new SecondExchangeFilterFunction());
    f.add(2, new ThirdExchangeFilterFunction());
}).build();

リストに登録された順番に処理されるようになる。

5.2.4. Appendix ¶

5.2.4.1. HTTP Proxyサーバの設定方法 ¶

サーバへアクセスする際にHTTP Proxyサーバを経由する必要がある場合は、システムプロパティやJVM起動引数、またはRestTemplateのBean定義にてHTTP Proxyサーバの設定が必要となる。

システムプロパティやJVM起動引数に設定した場合、アプリケーション全体に影響を与えてしまうため、RestTemplate毎にHTTP Proxyサーバの設定を行う例を紹介する。

RestTemplate毎のHTTP Proxyサーバの設定は、ClientHttpRequestFactoryインタフェースのデフォルト実装であるSimpleClientHttpRequestFactoryに付与することが可能である。ただし、SimpleClientHttpRequestFactoryでは資格情報を設定することはできないため、Proxy認証を行う場合はHttpComponentsClientHttpRequestFactoryを使用する。

HttpComponentsClientHttpRequestFactoryは、Apache HttpComponents HttpClientを用いてリクエストを生成するClientHttpRequestFactoryインタフェースの実装クラスである。

5.2.4.1.1. SimpleClientHttpRequestFactoryを使用したHTTP Proxyサーバの設定方法 ¶

資格情報が不要なHTTP Proxyサーバの接続先の指定については、RestTemplateがデフォルトで使用するSimpleClientHttpRequestFactoryで指定することが可能である。

Bean定義ファイル

// (2)
@Value("${rscl.http.proxyHost}")
private String httpProxyHost;

// (3)
@Value("${rscl.http.proxyPort}")
private int httpProxyPort;

// (1)
@Bean("inetSocketAddress")
public InetSocketAddress inetSocketAddress() {
    return new InetSocketAddress(httpProxyHost, httpProxyPort); // (2)(3)
}

// (4)
@Bean("simpleClientRestTemplate")
public RestTemplate simpleClientRestTemplate() {
    return new RestTemplate(simpleClientHttpRequestFactory()); // (5)
}

// (5)
@Bean
public SimpleClientHttpRequestFactory simpleClientHttpRequestFactory() {
    SimpleClientHttpRequestFactory bean = new SimpleClientHttpRequestFactory();
    bean.setProxy(proxy()); // (6)
    return bean;
}

// (6)
@Bean
public Proxy proxy() {
    return new Proxy(Proxy.Type.HTTP, inetSocketAddress()); // (7)
}

項番	説明
(1)	`java.net.InetSocketAddress`にHTTP Proxyサーバの設定を行う。
(2)	`InetSocketAddress`のコンストラクタ引数の`hostname`に、プロパティファイルに設定されたキー`rscl.http.proxyHost`の値をHTTP Proxyサーバのホスト名として設定する。
(3)	`InetSocketAddress`のコンストラクタ引数の`port`に、プロパティファイルに設定されたキー`rscl.http.proxyPort`の値をHTTP Proxyサーバのポート番号として設定する。
(4)	`RestTemplate`のBean定義を行う。
(5)	`RestTemplate`のコンストラクタの引数に、`SimpleClientHttpRequestFactory`を設定する。
(6)	`SimpleClientHttpRequestFactory`の`proxy`プロパティに`java.net.Proxy`を設定する。
(7)	`Proxy`のコンストラクタの引数に、`java.net.Proxy.Type.HTTP`と生成した`InetSocketAddress`を設定する。

<!-- (1) -->
<bean id="inetSocketAddress" class="java.net.InetSocketAddress" >
    <constructor-arg name="hostname" value="${rscl.http.proxyHost}" />    <!-- (2) -->
    <constructor-arg name="port" value="${rscl.http.proxyPort}" />    <!-- (3) -->
</bean>

<!-- (4) -->
<bean id="simpleClientRestTemplate" class="org.springframework.web.client.RestTemplate" >
    <constructor-arg>
        <!-- (5) -->
        <bean class="org.springframework.http.client.SimpleClientHttpRequestFactory">
            <!-- (6) -->
            <property name="proxy">
                <bean class="java.net.Proxy" >
                    <!-- (7) -->
                    <constructor-arg name="type">
                        <util:constant static-field="java.net.Proxy.Type.HTTP"/>
                    </constructor-arg>
                    <constructor-arg name="sa" ref="inetSocketAddress"/>
                </bean>
            </property>
        </bean>
    </constructor-arg>
</bean>

項番	説明
(1)	`java.net.InetSocketAddress`にHTTP Proxyサーバの設定を行う。
(2)	`InetSocketAddress`のコンストラクタ引数の`hostname`に、プロパティファイルに設定されたキー`rscl.http.proxyHost`の値をHTTP Proxyサーバのホスト名として設定する。
(3)	`InetSocketAddress`のコンストラクタ引数の`port`に、プロパティファイルに設定されたキー`rscl.http.proxyPort`の値をHTTP Proxyサーバのポート番号として設定する。
(4)	`RestTemplate`のBean定義を行う。
(5)	`RestTemplate`のコンストラクタの引数に、`SimpleClientHttpRequestFactory`を設定する。
(6)	`SimpleClientHttpRequestFactory`の`proxy`プロパティに`java.net.Proxy`を設定する。
(7)	`Proxy`のコンストラクタの引数に、`java.net.Proxy.Type.HTTP`と生成した`InetSocketAddress`を設定する。

5.2.4.1.2. HttpComponentsClientHttpRequestFactoryを使用したHTTP Proxyサーバの設定方法 ¶

5.2.4.1.2.1. HTTP Proxyサーバの指定方法¶

資格情報が必要なHTTP Proxyサーバの接続先の指定は、RestTemplateに対して、HttpComponentsClientHttpRequestFactoryを使用し指定する。

pom.xml

<!-- (1) -->
<dependency>
    <groupId>org.apache.httpcomponents.client5</groupId>
    <artifactId>httpclient5</artifactId>
</dependency>

項番	説明
(1)	`HttpComponentsClientHttpRequestFactory`内で使用する`Apache HTTP Client`を使用するために、`Apache HttpComponents Client`を`pom.xml`の依存ライブラリに追加する。

Note

上記設定例は、依存ライブラリのバージョンを親プロジェクトである terasoluna-gfw-parent で管理する前提であるため、pom.xmlでのバージョンの指定は不要である。

上記の依存ライブラリはterasoluna-gfw-parentが依存しているSpring Bootで管理されている。

Bean定義ファイル

// (1)
@Bean("proxyHttpClientBuilder")
public HttpClientBuilder proxyHttpClientBuilder() {
    HttpClientBuilder bean = HttpClientBuilder.create();
    bean.setProxy(httpHost()); // (2)
    return bean;
}

// (2)
@Bean
public HttpHost httpHost() {
    return new HttpHost(httpProxyHost, httpProxyPort); // (3) (4)
}

// (5)
@Bean("proxyRestTemplate")
public RestTemplate proxyRestTemplate() {
    return new RestTemplate(httpComponentsClientHttpRequestFactory()); // (6)
}

// (6)
@Bean("httpComponentsClientHttpRequestFactory")
public HttpComponentsClientHttpRequestFactory httpComponentsClientHttpRequestFactory() {
    return new HttpComponentsClientHttpRequestFactory(proxyHttpClientBuilder()
            .build()); // (7)
}

項番	説明
(1)	`org.apache.hc.client5.http.impl.classic.HttpClientBuilder`を使用し、`org.apache.http.client5.HttpClient`の設定を行う。
(2)	`HttpClientBuilder`の`proxy`プロパティに、HTTP Proxyサーバの設定を行った`org.apache.http.HttpHost`を設定する。
(3)	`HttpHost`のコンストラクタ引数の`hostname`に、プロパティファイルに設定されたキー`rscl.http.proxyHost`の値をHTTP Proxyサーバのホスト名として設定する。
(4)	`HttpHost`のコンストラクタ引数の`port`に、プロパティファイルに設定されたキー`rscl.http.proxyPort`の値をHTTP Proxyサーバのポート番号として設定する。
(5)	`RestTemplate`のBean定義を行う。
(6)	`RestTemplate`のコンストラクタの引数に、`HttpComponentsClientHttpRequestFactory`を設定する。
(7)	`HttpComponentsClientHttpRequestFactory`のコンストラクタの引数に、`HttpClientBuilder`から生成した`HttpClient`を設定する。

<!-- (1) -->
<bean id="proxyHttpClientBuilder" class="org.apache.hc.client5.http.impl.classic.HttpClientBuilder" factory-method="create">
    <!-- (2) -->
    <property name="proxy">
        <bean class="org.apache.hc.core5.http.HttpHost">
            <!-- (3) -->
            <constructor-arg type="java.lang.String" name="hostname" value="${rscl.http.proxyHost}" />
            <!-- (4) -->
            <constructor-arg type="int" name="port" value="${rscl.http.proxyPort}" />
        </bean>
    </property>
</bean>

<!-- (5) -->
<bean id="proxyRestTemplate" class="org.springframework.web.client.RestTemplate" >
    <constructor-arg>
        <!-- (6) -->
        <bean class="org.springframework.http.client.HttpComponentsClientHttpRequestFactory">
            <!-- (7) -->
            <constructor-arg>
                <bean factory-bean="proxyHttpClientBuilder" factory-method="build" />
            </constructor-arg>
        </bean>
    </constructor-arg>
</bean>

項番	説明
(1)	`org.apache.hc.client5.http.impl.classic.HttpClientBuilder`を使用し、`org.apache.http.client5.HttpClient`の設定を行う。
(2)	`HttpClientBuilder`の`proxy`プロパティに、HTTP Proxyサーバの設定を行った`org.apache.http.HttpHost`を設定する。 Warning オーバーロードされている場合に誤ったコンストラクタが使用されることがある当実装例は、本来であれば以下の様に記述することが可能である。 <bean class="org.apache.hc.core5.http.HttpHost"> <constructor-arg name="hostname" value="${rscl.http.proxyHost}" /> <constructor-arg name="port" value="${rscl.http.proxyPort}" /> </bean> ただし、Spring#31871で報告されているように、コンストラクタがオーバーロードされている場合に想定とは異なるコンストラクタが使用されてしまう可能性がある。そのためtype属性を設定し、明示的に使用するコンストラクタを決定している。
(3)	`HttpHost`のコンストラクタ引数の`hostname`に、プロパティファイルに設定されたキー`rscl.http.proxyHost`の値をHTTP Proxyサーバのホスト名として設定する。
(4)	`HttpHost`のコンストラクタ引数の`port`に、プロパティファイルに設定されたキー`rscl.http.proxyPort`の値をHTTP Proxyサーバのポート番号として設定する。
(5)	`RestTemplate`のBean定義を行う。
(6)	`RestTemplate`のコンストラクタの引数に、`HttpComponentsClientHttpRequestFactory`を設定する。
(7)	`HttpComponentsClientHttpRequestFactory`のコンストラクタの引数に、`HttpClientBuilder`から生成した`HttpClient`を設定する。

5.2.4.1.2.2. HTTP Proxyサーバの資格情報の指定方法¶

HTTP Proxyサーバにアクセスする際に資格情報(ユーザ名とパスワード)が必要な場合は、org.apache.http.impl.client.BasicCredentialsProviderを使用し資格情報を設定する。

BasicCredentialsProviderのsetCredentialsメソッドが引数を2つ取るため、セッターインジェクションを利用してBeanを生成することができない。このため、org.springframework.beans.factory.FactoryBeanを利用してBeanを生成する。

FactoryBeanクラス

import org.apache.hc.client5.http.auth.AuthScope;
import org.apache.hc.client5.http.auth.UsernamePasswordCredentials;
import org.apache.hc.client5.http.impl.auth.BasicCredentialsProvider;
import org.springframework.beans.factory.FactoryBean;
import org.springframework.beans.factory.annotation.Value;

// (1)
public class BasicCredentialsProviderFactoryBean implements FactoryBean<BasicCredentialsProvider> {

    // (2)
    @Value("${rscl.http.proxyHost}")
    String host;

    // (3)
    @Value("${rscl.http.proxyPort}")
    int port;

    // (4)
    @Value("${rscl.http.proxyUserName}")
    String userName;

    // (5)
    @Value("${rscl.http.proxyPassword}")
    String password;

    @Override
    public BasicCredentialsProvider getObject() throws Exception {

        // (6)
        AuthScope authScope = new AuthScope(this.host, this.port);

        // (7)
        char[] passwordCharArray = this.password == null ? null
                : this.password.toCharArray();
        UsernamePasswordCredentials usernamePasswordCredentials = new UsernamePasswordCredentials(this.userName, passwordCharArray);

        // (8)
        BasicCredentialsProvider credentialsProvider = new BasicCredentialsProvider();

        credentialsProvider.setCredentials(authScope,
                usernamePasswordCredentials);

        return credentialsProvider;
    }

    @Override
    public Class<?> getObjectType() {
        return BasicCredentialsProvider.class;
    }

    @Override
    public boolean isSingleton() {
        return true;
    }
}

項番	説明
(1)	`org.springframework.beans.factory.FactoryBean`を実装した`BasicCredentialsProviderFactoryBean`クラスを定義する。 Beanの型に`BasicCredentialsProvider`を設定する。
(2)	プロパティファイルに設定されたキー`rscl.http.proxyHost`の値をHTTP Proxyサーバのホスト名として、インスタンス変数に設定する。
(3)	プロパティファイルに設定されたキー`rscl.http.proxyPort`の値をHTTP Proxyサーバのポート番号として、インスタンス変数に設定する。
(4)	プロパティファイルに設定されたキー`rscl.http.proxyUserName`の値をHTTP Proxyサーバのユーザ名として、インスタンス変数に設定する。
(5)	プロパティファイルに設定されたキー`rscl.http.proxyPassword`の値をHTTP Proxyサーバのパスワードとして、インスタンス変数に設定する。
(6)	`org.apache.http.auth.AuthScope` を作成し資格情報のスコープを設定する。この例は、HTTP Proxyサーバのホスト名とポート番号を指定したものである。その他の設定方法については、AuthScope (Apache HttpClient API)を参照されたい。
(7)	`org.apache.http.auth.UsernamePasswordCredentials`を作成し資格情報を設定する。
(8)	`org.apache.http.impl.client.BasicCredentialsProvider`を作成し、`setCredentials`メソッドを使用し、資格情報のスコープと資格情報を設定する。

Bean定義ファイル

@Bean("proxyHttpClientBuilder")
public HttpClientBuilder proxyAuthHttpClientBuilder() throws Exception {
    HttpClientBuilder bean = HttpClientBuilder.create();
    bean.setDefaultCredentialsProvider(basicCredentialsProviderFactoryBean()
            .getObject()); // (1)
    bean.setProxy(httpHost);
    return bean;
}

// (1)
@Bean
public BasicCredentialsProviderFactoryBean basicCredentialsProviderFactoryBean() {
    return new BasicCredentialsProviderFactoryBean();
}

@Bean
public HttpHost httpHost() {
    return new HttpHost(httpProxyHost, httpProxyPort);
}

@Bean("proxyRestTemplate")
public RestTemplate proxyRestTemplate() {
    return new RestTemplate(httpComponentsClientHttpRequestFactory());
}

@Bean("httpComponentsClientHttpRequestFactory")
public HttpComponentsClientHttpRequestFactory httpComponentsClientHttpRequestFactory() {
    return new HttpComponentsClientHttpRequestFactory(proxyHttpClientBuilder()
            .build());

項番	説明
(1)	`HttpClientBuilder`の`defaultCredentialsProvider`プロパティに、`BasicCredentialsProvider`を設定する。 `BasicCredentialsProvider`は、`FactoryBean`を実装した`BasicCredentialsProviderFactoryBean`を使用しBeanを作成する。

<bean id="proxyHttpClientBuilder" class="org.apache.hc.client5.http.impl.classic.HttpClientBuilder" factory-method="create">
    <!-- (1) -->
    <property name="defaultCredentialsProvider">
        <bean class="com.example.restclient.BasicCredentialsProviderFactoryBean" />
    </property>
    <property name="proxy">
        <bean id="proxyHost" class="org.apache.hc.core5.http.HttpHost">
            <constructor-arg name="hostname" value="${rscl.http.proxyHost}" />
            <constructor-arg name="port" value="${rscl.http.proxyPort}" />
        </bean>
    </property>
</bean>

<bean id="proxyRestTemplate" class="org.springframework.web.client.RestTemplate">
    <constructor-arg>
        <bean class="org.springframework.http.client.HttpComponentsClientHttpRequestFactory">
            <constructor-arg>
                <bean factory-bean="proxyHttpClientBuilder" factory-method="build" />
            </constructor-arg>
        </bean>
    </constructor-arg>
</bean>

項番	説明
(1)	`HttpClientBuilder`の`defaultCredentialsProvider`プロパティに、`BasicCredentialsProvider`を設定する。 `BasicCredentialsProvider`は、`FactoryBean`を実装した`BasicCredentialsProviderFactoryBean`を使用しBeanを作成する。

項番	説明
(1)	`ClientHttpRequestFactory`のbean定義を行う。本ガイドラインではタイムアウトの設定をカスタマイズする方法を紹介している。詳細は通信タイムアウトの設定を参照されたい。
(2)	`ClientHttpRequestFactory`を引数に指定するコンストラクタを使用してbeanを登録する。