2015/03/30

Android : Deprecated HTTP Classes on Android5.1

Deprecated HTTP Classes on Android5.1

The org.apache.http classes and the AndroidHttpClient class have been deprecated in Android 5.1. These classes are no longer being maintained and you should migrate any app code using these APIs to the URLConnection classes as soon as possible.

org.apache.httpパッケージとAndroidHttpClientクラスはAndroid5.1で非推奨扱いとなる. 今後これらのクラスはメンテナンスされることがない. これらのAPIを使用しているアプリケーションはURLConnectionクラスへの変更が推奨される.

Deprecated APIs

org.apache.http.* と AndroidHttpClient

org.apache.http.impl.client.DefaultHttpClientとそのサブクラスであるAndroidHttpClientはWebブラウザ向けに最適化されたHTTPクライアントである. これらのAPIは巨大でフレキシブルなAPIを備えており安定した実装であるが, いくつかのバグを含んでいる.

巨大なAPIであるため互換性を維持しながら改善することが困難であり, AndroidチームはこれらのAPIを積極的に保守することをしていない.

今回, Android5.1のリリースを迎えてこれらのAPIは公式に保守されなく(Deprecatedと)なった.

HttpURLConnection

HttpURLConnection多くのアプリケーションに適応できる汎用かつ軽量なHTTPクライアントである. 軽量であるため保守性にも優れている. Android5.1で非推奨となったHttpClient系のかわりにこちらを使用すること.

HttpURLConnectionはAndroid Froyo以前で重大なバグを抱えている(Issue 2939).
ReadableなInputStreamからclose()を呼ぶとConnection poolを汚染することがある. Connection pooling を無効にしてこの問題を回避する方法は下記. 

private void disableConnectionReuseIfNecessary() {
    // HTTP connection reuse which was buggy pre-froyo
    if (Integer.parseInt(Build.VERSION.SDK) < Build.VERSION_CODES.FROYO) {
        System.setProperty("http.keepAlive", "false");
    }
}

このバグはGingerbreadで改修されている.
さらにGingerbreadからtransparent response compressionに対応し, ICSからはResponse cacheに対応している.

以降はURLConnection系クラスのoverviewである.

URLConnection Class Overview

A connection to a URL for reading or writing. For HTTP connections, see HttpURLConnection for documentation of HTTP-specific features.
For example, to retrieve ftp://mirror.csclub.uwaterloo.ca/index.html:

読み書きのためURLへ接続する. HTTPコネクションはHTTP機能に特化したHttpURLConnectionを参照.
ftp://mirror.csclub.uwaterloo.ca/index.htmlを取得するサンプルは下記. 

   URL url = new URL("ftp://mirror.csclub.uwaterloo.ca/index.html");
   URLConnection urlConnection = url.openConnection();
   InputStream in = new BufferedInputStream(urlConnection.getInputStream());
   try {
     readStream(in);
    finally {
     in.close();
   }

URLConnection must be configured before it has connected to the remote resource. Instances of URLConnection are not reusable: you must use a different instance for each connection to a resource.

URLConnectionの設定はリモートリソースに接続する前に行うこと. URLConnectionのインスタンスは再利用できない. 異なるリソースへの接続は異なるインスタンスで行う事.

Timeouts

URLConnection supports two timeouts: a connect timeout and a read timeout. By default, operations never time out.

URLConnectionは接続タイムアウトとリードタイムアウトの2種類をサポートする. デフォルトでは操作でタイムアウトすることは無い.

Built-in Protocols

  • File
    Resources from the local file system can be loaded using file: URIs. File connections can only be used for input.

  • FTP
    File Transfer Protocol (RFC 959) is supported, but with no public subclass. FTP connections can be used for input or output but not both.
    By default, FTP connections will be made using anonymous as the username and the empty string as the password. Specify alternate usernames and passwords in the URL: ftp://username:password@host/path.

  • HTTP and HTTPS
    Refer to the HttpURLConnection and HttpsURLConnection subclasses.

  • Jar
    Refer to the JarURLConnection subclass.

  • File
    ローカルファイルシステムのリソースに対してはfile:スキームを使用する. File接続はinputのみ使用できる.

  • FTP
    File Transfer Protocol(RFC959)がサポートされているが, 公開されたサブクラスはない. FTPではinputかoutputの片方を使用することができ, 両方の使用はできない.

  • HTTP and HTTPS
    HttpURLConnectionとHttpsURLConnectionのサブクラスを参照.

  • Jar
    JarURLConnectionのサブクラスを参照.

Registering Additional Protocols

Use setURLStreamHandlerFactory(URLStreamHandlerFactory) to register handlers for other protocol types.

setURLStreamHandlerFactory(URLStreamHandlerFactory)を使い, 異なるプロトコル種別のハンドラを設定する.

HttpURLConnection Class Overview

An URLConnection for HTTP (RFC 2616) used to send and receive data over the web. Data may be of any type and length. This class may be used to send and receive streaming data whose length is not known in advance. Uses of this class follow a pattern:

URLConnectionはHTTP(RFC2616)を使用したWebを介したデータ送受信のために使用される. データの種類や長さは任意. このクラスは事前に長さが知らされていないストリーミングデータを受信するのにも使用できる.
このクラスの使用パターンは下記.

  1. Obtain a new HttpURLConnection by calling URL.openConnection() and casting the result to HttpURLConnection.
  2. Prepare the request. The primary property of a request is its URI. Request headers may also include metadata such as credentials, preferred content types, and session cookies.
  3. Optionally upload a request body. Instances must be configured with setDoOutput(true) if they include a request body. Transmit data by writing to the stream returned by getOutputStream().
  4. Read the response. Response headers typically include metadata such as the response body’s content type and length, modified dates and session cookies. The response body may be read from the stream returned by getInputStream(). If the response has no body, that method returns an empty stream.
  5. Disconnect. Once the response body has been read, the HttpURLConnection should be closed by calling disconnect(). Disconnecting releases the resources held by a connection so they may be closed or reused.

  1. 新しいHttpURLConnectionを取得する. URL.openConnection()を呼び, HttpURLConnectionにキャストする.

  2. リクエストを準備する. 主なプロパティはURIである. リクエストヘッダには認証情報, コンテンツ種別, セッションクッキーのメタデータが含まれる.

  3. 必要に応じてリクエストボディをアップロードする. リクエストボディを含めるにはsetDoOutput(true)を設定し, getOutputStream()で返却されるストリームにデータを書き込む.

  4. レスポンスを読み込む. レスポンスヘッダには一般的にレスポンスボディのコンテントタイプ, 長さ, 更新日とセッションクッキーといったメタデータが含まれる. レスポンスボディはgetInputStream()で取得できるストリームから読み込める. レスポンスにボディが含まれない場合, このメソッドは空のストリームを返す.

  5. コネクションの切断. レスポンスボディが読み込まれた後, HttpURLConnectionをdisconnect()メソッドで閉じる必要がある. コネクションを切断する事で関連するリソースを開放し, コネクションが再利用できるようになる.

For example, to retrieve the webpage at http://www.android.com/:

   URL url = new URL("http://www.android.com/");
   HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection();
   try {
     InputStream in = new BufferedInputStream(urlConnection.getInputStream());
     readStream(in);
    finally {
     urlConnection.disconnect();
   }

Secure Communication with HTTPS

Calling openConnection() on a URL with the “https” scheme will return an HttpsURLConnection, which allows for overriding the default HostnameVerifier and SSLSocketFactory. An application-supplied SSLSocketFactory created from an SSLContext can provide a custom X509TrustManager for verifying certificate chains and a custom X509KeyManager for supplying client certificates. See HttpsURLConnection for more details.

“https”スキーム付きのURLでopenConnection()を呼び出すとHttpsURLConnectionが返却される. これはデフォルトで使用されるHostnameVerifierとSSLSocketFactoryのオーバライドを可能にする.
SSLContextから生成されるアプリケーション提供のSSLSocketFactoryは, 証明書チェーンのためのカスタムX509TrustManagerと, クライアント証明書のためのカスタムX509KeyManagerを提供する.

Response Handling

HttpURLConnection will follow up to five HTTP redirects. It will follow redirects from one origin server to another. This implementation doesn’t follow redirects from HTTPS to HTTP or vice versa.
If the HTTP response indicates that an error occurred, getInputStream() will throw an IOException. Use getErrorStream() to read the error response. The headers can be read in the normal way using getHeaderFields(),

HttpURLConnectionは5回分のHTTPリダイレクトをフォローアップする. オリジンサーバから異なるサーバへのリダイレクトがフォローされる. この実装はHTTPsからHTTPへのリダイレクトやその逆はフォローされない. もしHTTPレスポンスがエラーを示す場合, getInputStream()がIOExceptionをスローする. getErrorStream()を使用してエラーレスポンスを読み込むことができる. 通常通りgetHeaderFields()でヘッダを読み込むことができる.

Posting Content

To upload data to a web server, configure the connection for output using setDoOutput(true).
For best performance, you should call either setFixedLengthStreamingMode(int) when the body length is known in advance, or setChunkedStreamingMode(int) when it is not. Otherwise HttpURLConnection will be forced to buffer the complete request body in memory before it is transmitted, wasting (and possibly exhausting) heap and increasing latency.

WebサーバにデータをアップロードするにはsetDoOutput(true)でコネクションを出力用に設定する. パフォーマンスのために, ボディの長さが判明している場合はsetFixedLengthStreamingMode(int)を設定する. そうでない場合ははsetChunkedStreamingMode(int)を設定する. そうでない場合HttpURLConnectionはリクエスト送信を終えるまでリクエストボディを全てメモリにバッファするためヒープと待ち時間をいたずらに消費する.

For example, to perform an upload:

   HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection();
   try {
     urlConnection.setDoOutput(true);
     urlConnection.setChunkedStreamingMode(0);

     OutputStream out = new BufferedOutputStream(urlConnection.getOutputStream());
     writeStream(out);

     InputStream in = new BufferedInputStream(urlConnection.getInputStream());
     readStream(in);
    finally {
     urlConnection.disconnect();
   }
 }

Performance

The input and output streams returned by this class are not buffered. Most callers should wrap the returned streams with BufferedInputStream or BufferedOutputStream. Callers that do only bulk reads or writes may omit buffering.
When transferring large amounts of data to or from a server, use streams to limit how much data is in memory at once. Unless you need the entire body to be in memory at once, process it as a stream (rather than storing the complete body as a single byte array or string).

URLConnectionクラスはバッファされないinput / output streamを返す. 多くの場合これらをBufferedInputStream / BufferedOutputStreamでラップする. もし一度にまとめて読み書きしたい場合にはバッファリングは省略されるだろう.
サーバへ/から巨大なデータを転送する場合, 確保必要なメモリ容量を抑えるためにstreamは使用される. もしボディーの情報を全てメモリ上に展開してバイト配列や文字列として扱う
必要でも無い限りstreamを使用すること.

To reduce latency, this class may reuse the same underlying Socket for multiple request/response pairs. As a result, HTTP connections may be held open longer than necessary. Calls to disconnect() may return the socket to a pool of connected sockets. This behavior can be disabled by setting the http.keepAlive system property to false before issuing any HTTP requests. The http.maxConnections property may be used to control how many idle connections to each server will be held.

待ち時間を短縮するために, このクラスは対となる複数の要求/応答に同じSocketを使用する.
しかし, この結果HTTPコネクションは必要以上に保持される.
disconnect()を呼ぶと接続済SocketプールにSocketが返却される. この振る舞いはHTTPリクエストの開始より前にシステムプロパティhttp.keepAliveをfalseに設定することで無効化できる. http.maxConnectionsプロパティは各サーバ毎にどれだけのidleコネクションを保持させるかを制御する.

By default, this implementation of HttpURLConnection requests that servers use gzip compression. Since getContentLength() returns the number of bytes transmitted, you cannot use that method to predict how many bytes can be read from getInputStream(). Instead, read that stream until it is exhausted: when read() returns -1. Gzip compression can be disabled by setting the acceptable encodings in the request header:

HttpURLConnectionの標準実装では, サーバがgzip圧縮を使用するリクエストを投げる. getContentLength()は送信されたバイト数を返却するため, getInputStream()でどれだけのバイトが読み込まれるかを予測するためにこの数字を使用することはできない. かわりに, streamのread()が-1を返すまで読み続ける. Gzip圧縮はリクエストヘッダのAccept-Encodingで無効化することができる. 

urlConnection.setRequestProperty("Accept-Encoding", "identity");

Handling Network Sign-On

Some Wi-Fi networks block Internet access until the user clicks through a sign-on page. Such sign-on pages are typically presented by using HTTP redirects. You can use getURL() to test if your connection has been unexpectedly redirected. This check is not valid until after the response headers have been received, which you can trigger by calling getHeaderFields() or getInputStream(). For example, to check that a response was not redirected to an unexpected host:

いくつかのWi-Fiネットワークはユーザのサインオンページを経由してインターネットにアクセスする. このようなサインオンページは通常HTTPリダイレクトを使用して提供される.
getURL()を使用することで期待しないリダイレクトによる接続であるかをテストできる. このチェックはレスポンスヘッダの受信後では有効ではない. getHeaderFields()かgetInputStream()を呼び出す際にトリガーすることができる. 次のコードは期待しないホストへリダイレクトされていないことをチェックするものである. 

   HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection();
   try {
     InputStream in = new BufferedInputStream(urlConnection.getInputStream());
     if (!url.getHost().equals(urlConnection.getURL().getHost())) {
       // we were redirected! Kick the user out to the browser to sign on?

     ...
   } finally {
     urlConnection.disconnect();
   }

HTTP Authentication

HttpURLConnection supports HTTP basic authentication. Use Authenticator to set the VM-wide authentication handler:

HttpURLConnectionはHTTPベーシック認証をサポートする. VM全体で使う認証ハンドラにAuthenticator
を設定するには次, 

   Authenticator.setDefault(new Authenticator() {
     protected PasswordAuthentication getPasswordAuthentication() {
       return new PasswordAuthentication(username, password.toCharArray());

   });
 }

Unless paired with HTTPS, this is not a secure mechanism for user authentication. In particular, the username, password, request and response are all transmitted over the network without encryption.

これはHTTPSで使用されない限りセキュアでないユーザ認証である. ユーザ名, パスワードや要求/応答は暗号化されずにネットワークを介してデータ送信される.

Sessions with Cookies

To establish and maintain a potentially long-lived session between client and server, HttpURLConnection includes an extensible cookie manager. Enable VM-wide cookie management using CookieHandler and CookieManager:

クライアントとサーバ間の潜在的なセッションを長時間確立するため, HttpURLConnectionは拡張可能なcookie managerを包含している. CookieHandlerとCookieManagerを使ってVM全体のCookie管理を有効にする. 

   CookieManager cookieManager = new CookieManager();
   CookieHandler.setDefault(cookieManager);

By default, CookieManager accepts cookies from the origin server only. Two other policies are included: ACCEPT_ALL and ACCEPT_NONE. Implement CookiePolicy to define a custom policy.
The default CookieManager keeps all accepted cookies in memory. It will forget these cookies when the VM exits. Implement CookieStore to define a custom cookie store.

標準で, CookieManagerはorigin serverからのみcookieを受け入れる. 異なる2つのポリシーとして, ACCEPT_ALLとACCEPT_NONEが用意されている. カスタムポリシーを定義するためにはCookiePolicyを実装する. デフォルトのCookieManagerは記憶された受け入れcookieを全て保持する. VMが終了するとこれらのcookieは忘れられる. カスタムcookieを記録するにはCookieStoreを実装する.

In addition to the cookies set by HTTP responses, you may set cookies programmatically. To be included in HTTP request headers, cookies must have the domain and path properties set.
By default, new instances of HttpCookie work only with servers that support RFC 2965 cookies. Many web servers support only the older specification, RFC 2109. For compatibility with the most web servers, set the cookie version to 0.

HTTPレスポンスで設定されるcookieの他に, プログラムでcookieを設定することができる. HTTPリクエストヘッダに含まれるようにcookieが設定されているドメインとパスのプロパティを設定する.

For example, to receive www.twitter.com in French:

フランス語でwww.twitter.comを受信する例は以下の通り。

   HttpCookie cookie = new HttpCookie("lang", "fr");
   cookie.setDomain("twitter.com");
   cookie.setPath("/");
   cookie.setVersion(0);
   cookieManager.getCookieStore().add(new URI("http://twitter.com/"), cookie);

HTTP Methods

HttpURLConnection uses the GET method by default. It will use POST if setDoOutput(true) has been called. Other HTTP methods (OPTIONS, HEAD, PUT, DELETE and TRACE) can be used with setRequestMethod(String).

HttpURLConnectionは標準でGETメソッドを使用する. POSTメソッドを使うにはsetDoOutput(true)を使用する. 他のHTTPメソッド(OPTIONS, HEAD, PUT, DELETE, TRACE)はsetRequestMethod(String)を使用する.

Proxies

By default, this class will connect directly to the origin server. It can also connect via an HTTP or SOCKS proxy. To use a proxy, use URL.openConnection(Proxy) when creating the connection.

標準でこのクラスはorigin serverへ直接接続する. これはHTTPかSOCKS proxy経由で接続することができる. Proxyを使用するにはコネクションを生成するのにURL.openConnection(Proxy)を使用する.

IPv6 Support

This class includes transparent support for IPv6. For hosts with both IPv4 and IPv6 addresses, it will attempt to connect to each of a host’s addresses until a connection is established.

このクラスはIPv6をサポートする. ホストがIPv4とIPv6両方をサポートする場合, 接続が確立されるまで両方での接続を試みます.

Response Caching

Android 4.0 (Ice Cream Sandwich, API level 15) includes a response cache. See android.net.http.HttpResponseCache for instructions on enabling HTTP caching in your application.

Android4.0でresponse cacheが追加された. アプリケーションでHTTPキャッシングを有効にする方法についてはandroid.net.http.HttpResponseCacheを参照.

Avoiding Bugs In Earlier Releases

Prior to Android 2.2 (Froyo), this class had some frustrating bugs. In particular, calling close() on a readable InputStream could poison the connection pool. Work around this by disabling connection pooling:

Android2.2以前, このクラスにはイライラするバグを抱えている. 具体的にはreadableなInputStreamでclose()を呼んだ時コネクションプールを汚染するというものである. コネクションプーリングを無効化することでこの問題を回避できる. 

  private void disableConnectionReuseIfNecessary() {
     // Work around pre-Froyo bugs in HTTP connection reuse.
    if (Integer.parseInt(Build.VERSION.SDK) < Build.VERSION_CODES.FROYO) {
      System.setProperty("http.keepAlive", "false");
    }
  }

Each instance of HttpURLConnection may be used for one request/response pair. Instances of this class are not thread safe.

HttpURLConnectionのインスタンスは要求/応答のペアに対して1つ使用できる. このクラスはスレッドセーフではない.

HttpsURLConnection Class Overview

An HttpURLConnection for HTTPS (RFC 2818). A connected HttpsURLConnection allows access to the negotiated cipher suite, the server certificate chain, and the client certificate chain if any.

HTTPS(RFC2818)のためのHttpURLConnection. HttpsURLConnectionによる接続はChiperスイートによるネゴシエーション, サーバ証明書チェーン, クライアント証明書チェーンがある場合にアクセスを可能とする.

Providing an application specific X509TrustManager

If an application wants to trust Certificate Authority (CA) certificates that are not part of the system, it should specify its own X509TrustManager via a SSLSocketFactory set on the HttpsURLConnection. The X509TrustManager can be created based on a KeyStore using a TrustManagerFactory to supply trusted CA certificates. Note that self-signed certificates are effectively their own CA and can be trusted by including them in a KeyStore.
For example, to trust a set of certificates specified by a KeyStore:

アプリケーションがシステムの一部ではないCA証明書を信頼したい場合, HttpsURLConnectionでSSLSocketFactoryを介して独自のX509TrustManagerを設定する. 

   KeyStore keyStore = ...;
   String algorithm = TrustManagerFactory.getDefaultAlgorithm();
   TrustManagerFactory tmf = TrustManagerFactory.getInstance(algorithm);
   tmf.init(keyStore);

   SSLContext context = SSLContext.getInstance("TLS");
   context.init(null, tmf.getTrustManagers(), null);

   URL url = new URL("https://www.example.com/");
   HttpsURLConnection urlConnection = (HttpsURLConnection) url.openConnection();
   urlConnection.setSSLSocketFactory(context.getSocketFactory());
   InputStream in = urlConnection.getInputStream();

It is possible to implement X509TrustManager directly instead of using one created by a TrustManagerFactory. While this is straightforward in the insecure case of allowing all certificate chains to pass verification, writing a proper implementation will usually want to take advantage of CertPathValidator. In general, it might be better to write a custom KeyStore implementation to pass to the TrustManagerFactory than to try and write a custom X509TrustManager.

TrustManagerFactoryによって生成されたものではなく, 直接X509TrustManagerを実装することができる. 全ての証明書チェーンが検証をパスしないと安全でないような簡単なケースで実装にはCertPathValidatorを使用したいと考えるだろう. 一般的にカスタムされたX509TrustManagerを実装するよりはTrustManagerFactoryにカスタムKeyStoreを渡すほうが良い方法となる.

Providing an application specific X509KeyManager

A custom X509KeyManager can be used to supply a client certificate and its associated private key to authenticate a connection to the server. The X509KeyManager can be created based on a KeyStore using a KeyManagerFactory.
For example, to supply client certificates from a KeyStore:

カスタムされたX509KeyManagerはクライアント証明書と秘密鍵で関連づけられたサーバへの接続の認証に使用できる. X509KeyManagerはKeyManagerFactoryを使用してKeyStoreを基に作成できる. 

   KeyStore keyStore = ...;
   String algorithm = KeyManagerFactory.getDefaultAlgorithm();
   KeyManagerFactory kmf = KeyManagerFactory.getInstance(algorithm);
   kmf.init(keyStore);

   SSLContext context = SSLContext.getInstance("TLS");
   context.init(kmf.getKeyManagers(), null, null);

   URL url = new URL("https://www.example.com/");
   HttpsURLConnection urlConnection = (HttpsURLConnection) url.openConnection();
   urlConnection.setSSLSocketFactory(context.getSocketFactory());
   InputStream in = urlConnection.getInputStream();

A X509KeyManager can also be implemented directly. This can allow an application to return a certificate and private key from a non-KeyStore source or to specify its own logic for selecting a specific credential to use when many may be present in a single KeyStore.

X509KeyManagerは直接実装できる. これはアプリケーションにKeyStoreをソースとしない秘密鍵と証明書を返却させるか, 多くは1つのKeyStoreに存在する特定の証明書を選択する独自ロジックを実装する.

TLS Intolerance Support

This class attempts to create secure connections using common TLS extensions and SSL deflate compression. Should that fail, the connection will be retried with SSLv3 only.

このクラスは一般的なTLS拡張とSSL deflate圧縮を使用したセキュアなコネクションを生成する. 接続が失敗した際にはSSLv3での再接続を試みる.

APIs

参考

License:
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.