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

Caution

本バージョンの内容は既に古くなっています。最新のガイドラインはこちらからご参照ください。

Overview
- RestTemplate とは
How to use
How to extend
Appendix
- HTTP Proxyサーバの設定方法
  - HTTP Proxyサーバの指定方法
  - HTTP Proxyサーバの資格情報の指定方法

5.17.1. Overview ¶

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

5.17.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.client.AsyncRestTemplateを使用すればよい。非同期処理の実装例については、非同期リクエストを参照されたい。

5.17.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がクラスパスに存在する場合に登録される)	`Object` (JavaBean)
(11)	`org.springframework.http.converter.json.` `GsonHttpMessageConverter`	「HTTPボディ(JSON)⇔JavaBean」変換用のクラス。デフォルトでJSON用のメディアタイプ(`application/json`,`application/*+json`)をサポートする。 (Gsonがクラスパスに存在する場合に登録される)	`Object` (JavaBean) `Map`

[1]	`org.springframework.core.io`パッケージのクラス

[2]	`javax.xml.transform`パッケージのクラス

[3]	`org.springframework.util`パッケージのクラス

[4]	`com.rometools.rome.feed.atom`パッケージのクラス

[5]	`com.rometools.rome.feed.rss`パッケージのクラス

5.17.1.1.2. `ClientHttpRequestFactory`¶

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

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

この３つのインタフェースのうち、開発者が意識するのは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.` `Netty4ClientHttpRequestFactory`	Netty 4のAPIを使用して通信処理(同期、非同期)を行うための実装クラス。
(3)	`org.springframework.http.client.` `HttpComponentsClientHttpRequestFactory`	Apache HttpComponents HttpClientのAPIを使用して同期型の通信処理を行うための実装クラス。(HttpClient 4.3以上が必要)
(4)	`org.springframework.http.client.` `HttpComponentsAsyncClientHttpRequestFactory`	Apache HttpComponents HttpAsyncClientのAPIを使用して非同期型の通信処理を行うための実装クラス。(HttpAsyncClient 4.0以上が必要)
(5)	`org.springframework.http.client.` `OkHttpClientHttpRequestFactory`	Square OkHttpのAPIを使用して通信処理（同期、非同期）を行うための実装クラス。

Note

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

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

5.17.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.17.1.1.4. `ClientHttpRequestInterceptor`¶

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

ClientHttpRequestInterceptorを使用すると、

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

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

Note

ClientHttpRequestInterceptorの動作仕様

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

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

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

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

5.17.2. How to use ¶

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

Note

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

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

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

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

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

RestTemplateを使用するためにpom.xmlに、Spring Frameworkのspring-webライブラリを追加する。
マルチプロジェクト構成の場合は、domainプロジェクトのpom.xmlに追加する。
バージョンは、Spring Framework にて管理されているため、ここでバージョンを定義する必要はない。

<dependencies>

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

</dependencies>

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

5.17.2.1.2. `RestTemplate`のbean定義 ¶

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

bean定義ファイル(applicationContext.xml)の定義例

<bean id="restTemplate" class="org.springframework.web.client.RestTemplate" /> <!-- (1) -->

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

Note

RestTemplateのカスタマイズ方法

HTTP通信処理をカスタマイズする場合は、以下のような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.17.2.1.3. `RestTemplate`の利用 ¶

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

RestTemplateのインジェクション例

@Service
public class AccountServiceImpl implements AccountService {

    @Inject
    RestTemplate restTemplate;

    // ...

}

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

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

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

5.17.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.17.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.17.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.17.2.3. POSTリクエストの送信 ¶

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

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

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

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

postForObjectメソッドの使用例

User user = new User();

//...

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

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

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

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

postForEntityメソッドの使用例

User user = new User();

//...

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

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

5.17.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();

//...

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.17.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`<レスポンスデータの型>を指定する。
(2)	`getBody`メソッドで、レスポンスボディのデータを取得する。

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

RequestEntityとexchangeメソッドを使用すると、RequestEntityのメソッドを使用して特定のヘッダ及び任意のヘッダを設定することができる。詳細はRequestEntityのJavadocを参照されたい。

本ガイドラインでは、

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

について説明する。

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

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

Content-Typeヘッダの設定例

User user = new User();

//...

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

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

5.17.2.5.2. Acceptヘッダの設定 ¶

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

Acceptヘッダの設定例

User user = new User();

//...

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

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

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

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

任意ヘッダの設定例

User user = new User();

//...

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

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

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

5.17.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 (log.isInfoEnabled()) {
            log.info("Success({}) ", responseEntity.getStatusCode());
        }

        break;

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

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

        retryCount++;

        if (log.isWarnEnabled()) {
            log.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();
        }

        //...
    }

}

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

5.17.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定義ファイル(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 (log.isWarnEnabled()) {
            log.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();
        }

        //...
    }
}

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

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

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

bean定義ファイル(applicationContext.xml)の定義例

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

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

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

Note

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

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

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

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

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

FactoryBeanの実装例

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

import java.security.KeyStore;

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

import org.apache.http.client.HttpClient;
import org.apache.http.impl.client.HttpClientBuilder;
import org.springframework.beans.factory.FactoryBean;
import org.springframework.http.client.ClientHttpRequestFactory;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;

public class RequestFactoryBean implements
        FactoryBean<ClientHttpRequestFactory> {

    private String keyStoreFileName;

    private char[] keyStorePassword;

    @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);

        // (2)
        HttpClient httpClient = HttpClientBuilder.create()
                .setSSLContext(sslContext).build();

        // (3)
        ClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory(
                httpClient);

        return 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;
    }

}

項番	説明
(1)	後述のbean定義で指定されたキーストアファイルのファイル名とパスワードを元に、SSLコンテキストを作成する。使用するSSL自己署名証明書のキーストアファイルは、クラスパス上に配置する。
(2)	作成したSSLコンテキストを利用する `org.apache.http.client.HttpClient`を作成する。
(3)	作成した`HttpClient`を利用する `ClientHttpRequestFactory`を作成する。

HttpClientおよび HttpClientBuilderを使用するためには、Apache HttpComponents HttpClient のライブラリが必要となる。以下を pom.xmlに追加し、Apache HttpComponents HttpClient を依存ライブラリに追加する。なお、Apache HttpComponents HttpClient のバージョンは、 Spring IO Platform にて管理されているため、ここでApache HttpComponents HttpClient のバージョンを定義する必要はない。

pom.xml

<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpclient</artifactId>
</dependency>

bean定義ファイル(applicationContext.xml)の定義例

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

<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.17.2.9. Basic認証 ¶

サーバがBasic認証を要求する場合は、以下のように実装する。

Basic認証の実装例

フィールド宣言部

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

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

メソッド内部

String plainCredentials = userid + ":" + 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)	ユーザIDとパスワードを「`":"`」でつなげる。
(2)	（1）をバイト配列に変換して、Base64エンコードする。
(3)	AuthorizationヘッダをBasic認証の資格情報を設定する。

Note

Java SE8以降の場合は、Java標準のjava.util.Base64を使用する。それ以前の場合は、Spring Securityのorg.springframework.security.crypto.codec.Base64を使用する。

5.17.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.17.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();

    .....

}

項番	説明
(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);
.....

5.17.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();

//...

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.17.3. How to extend ¶

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

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

デフォルトで登録されている HttpMessageConverterで電文変換の要件を満たせない場合は、任意のHttpMessageConverterを登録することができる。ただし、デフォルトで登録されていたHttpMessageConverterは削除されるので、必要な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.17.3.2. 共通処理の適用（`ClientHttpRequestInterceptor`）¶

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

ここでは、

ロギング処理
Basic認証用のリクエストヘッダ設定処理

の実装例を紹介する。

5.17.3.2.1. ロギング処理 ¶

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

通信ログ出力の実装例

package com.example.restclient;

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 log = LoggerFactory.getLogger(LoggingInterceptor.class);

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

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

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

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

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

        return response; // (6)
    }

}

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

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

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

Basic認証用のリクエストヘッダ設定処理の実装例

package com.example.restclient;

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 BasicAuthInterceptor implements ClientHttpRequestInterceptor { //(1)

    private static final Logger log = LoggerFactory.getLogger(BasicAuthInterceptor.class);

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

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

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

        String plainCredentials = userid + ":" + password;
        String base64Credentials = Base64.getEncoder()
                .encodeToString(plainCredentials.getBytes(StandardCharsets.UTF_8));
        request.getHeaders().add("Authorization", "Basic " + base64Credentials); // (1)

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

        return response;
    }

}

項番	説明
(1)	`intercept`メソッド内で、Basic認証のリクエストヘッダを追加する。

5.17.3.2.3. `ClientHttpRequestInterceptor`の適用 ¶

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

bean定義ファイル(applicationContext.xml)の定義例

<!-- (1) -->
<bean id="basicAuthInterceptor" class="com.example.restclient.BasicAuthInterceptor" />
<bean id="loggingInterceptor" class="com.example.restclient.LoggingInterceptor" />

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

項番説明

(1)

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

(2)

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

5.17.3.3. 非同期リクエスト ¶

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

5.17.3.3.1. `AsyncRestTemplate`のbean定義 ¶

AsyncRestTemplateのbean定義を行う。

bean定義ファイル(applicationContext.xml)の定義例

<bean id="asyncRestTemplate" class="org.springframework.web.client.AsyncRestTemplate" /> <!-- (1) -->

項番説明

(1)

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

デフォルト設定の場合、AsyncRestTemplateのorg.springframework.http.client.AsyncClientHttpRequestFactoryには、org.springframework.core.task.AsyncListenableTaskExecutorとしてorg.springframework.core.task.SimpleAsyncTaskExecutorが設定された SimpleClientHttpRequestFactoryが設定される。

Note

AsyncRestTemplateへのClientHttpRequestInterceptorの適用について

AsyncRestTemplateには ClientHttpRequestInterceptorを適用出来ない。したがって、共通処理等は独自に実装する必要がある。

Note

AsyncRestTemplateのカスタマイズ方法

デフォルトで設定されるSimpleAsyncTaskExecutorは、スレッドプールを使わずにスレッドを生成しており、スレッドの同時実行数に制限は無い。そのため、同時に使用するスレッド数が非常に大きい場合はOutOfMemoryErrorが発生する可能性がある。

AsyncRestTemplateのコンストラクタにorg.springframework.core.task.AsyncListenableTaskExecutorインターフェースのBeanを設定することで、スレッドプール数の上限などを指定できる。下記はorg.springframework.scheduling.concurrent.ThreadPoolTaskExecutorを設定する例である。

<bean id="asyncTaskExecutor" class="org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor">
    <property name="maxPoolSize" value="100" />
</bean>


<bean id="asyncRestTemplate" class="org.springframework.web.client.AsyncRestTemplate" >
    <constructor-arg index="0" ref="asyncTaskExecutor" />
</bean>
項番説明

(1)

AsyncTaskExecutorのbean定義を行う。

ThreadPoolTaskExecutorを使うことで、スレッドプールを使ったスレッド運用が行われる。

また、maxPoolSizeプロパティを設定することで、スレッド数の制御が行える。

(2)

AsyncRestTemplateのbean定義を行う。

ThreadPoolTaskExecutorを引数に指定するコンストラクタを使用してbeanを登録する。

本ガイドラインでは、タスク実行処理をカスタマイズする実装例のみを紹介するが、 AsyncRestTemplateは、HTTP通信処理もカスタマイズ出来る。詳細はAsyncRestTemplateのJavadocを参照されたい。

また、ThreadPoolTaskExecutorについても、スレッドプールサイズ以外のカスタマイズが出来る。詳細はThreadPoolTaskExecutorのJavadocを参照されたい。

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

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

フィールド宣言部

@Inject
AsyncRestTemplate asyncRestTemplate;

メソッド内部

ListenableFuture<ResponseEntity<User>> responseEntity =
        asyncRestTemplate.getForEntity(uri, User.class); // (1)

responseEntity.addCallback(new ListenableFutureCallback<ResponseEntity<User>>() { // (2)
    @Override
    public void onSuccess(ResponseEntity<User> entity) {
        //...
    }

    @Override
    public void onFailure(Throwable t) {
      //...
    }
});

項番	説明
(1)	`AsyncRestTemplate`の各メソッドを使用して、非同期リクエストを送信する。上記の実装例では、`getForEntity`メソッドを使用している。戻り値は、`org.springframework.util.concurrent.ListenableFuture`にラップされた、`ResponseEntity`となっている。各メソッドの使用方法は、`RestTemplate`と似たものとなっている。
(2)	`ListenableFuture`に`org.springframework.util.concurrent.ListenableFutureCallback`を登録して、レスポンスが返ってきた際の処理を実装する。成功のレスポンスが返ってきた場合の処理は`onSuccess`メソッドに、エラーが発生した場合の処理は`onFailure`メソッドに実装する。

@Value("${api.proxy.host}")
String proxyHost;

@Value("${api.proxy.portNum}")
String proxyPort;

//...

System.setProperty("http.proxyHost", proxyHost); // (1)
System.setProperty("http.proxyPort", proxyPort); // (2)

項番	説明
(1)	システムプロパティ「`"http.proxyHost"`」にHTTP Proxyサーバのホスト名又はIPアドレスを設定する。
(2)	システムプロパティ「`"http.proxyPort"`」にHTTP Proxyサーバのポート番号を設定する。 HTTP Proxyサーバのポート番号

JVMの起動パラメータでHTTP Proxyサーバを指定する場合の指定例

java -Dhttps.proxyHost={host name or ip address} -Dhttps.proxyPort={port number} ...

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

HTTP Proxyサーバにアクセスする際に資格情報(ユーザー名とパスワード)が必要な場合は、java.net.Authenticatorに資格情報を設定する。

HTTP Proxyサーバの資格情報の指定例

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

@Value("${api.auth.password}")
char[] password;

//...

Authenticator.setDefault(new Authenticator() { // (1)
            @Override
            protected PasswordAuthentication getPasswordAuthentication() {
                return new PasswordAuthentication(userid, password); // (2)
            }
});

項番	説明
(1)	`Authenticator`の`setDefault`メソッドを呼び出し、HTTP Proxyサーバの資格情報を返却する`Authenticator`オブジェクトを設定する。
(2)	`getPasswordAuthentication`メソッドの返り値として、HTTP Proxyサーバの資格情報(ユーザー名とパスワード)を返却する。

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

項番	説明
(1)	`AsyncTaskExecutor`のbean定義を行う。 `ThreadPoolTaskExecutor`を使うことで、スレッドプールを使ったスレッド運用が行われる。また、`maxPoolSize`プロパティを設定することで、スレッド数の制御が行える。
(2)	`AsyncRestTemplate`のbean定義を行う。 `ThreadPoolTaskExecutor`を引数に指定するコンストラクタを使用してbeanを登録する。