AFNetworking 2.0 Migration Guideを読みながらメモ

AFNetworking 2.0 Migration Guideを脱線メモしながら意訳中です。

AFNetworking 2.0 Migration Guide

AFNetworking 2.0 is the next major release of AFNetworking, a delightful networking library for iOS & Mac OS X.
As a major release, following Semantic Versioning conventions, 2.0 introduces several API-breaking changes with its new architecture, which adds support for NSURLSession and introduces a new serialization-based approach to content negotiation.
This guide is provided in order to ease the transition of existing applications using AFNetworking 1.X to the latest APIs, as well as explain the design and structure of new and changed functionality.

AFNetworking 2.0はAFNetworkingの次のメジャーリリースで、
iOSとMac OS Xの為の快適なネットワーキングライブラリです。
メジャーリリースとして、セマンティックバージョン管理規則に従い、
2.0ではNSURLSessionのサポートと、コンテントネゴシエーションの為のSerialization-based approach等
新しいアーキテクチャを採用し、いくつかのAPI互換性に影響する変更を導入しました。

このガイドは又、新規かつ変更された機能の設計と構造を説明し、
AFNetworking 1.Xの最新APIを使用した既存アプリケーションの平易な移行の為に設けられました。

ここまでで自分の理解が浅いキーワード

コンテントネゴシエーション

• Apache公式 https://httpd.apache.org/docs/2.2/ja/content-negotiation.html
• http仕様RFC2616 http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html

セマンティックバージョニング

• セマンティックバージョニング仕様書 http://semver.org/
• 上記の日本語訳 http://shijimiii.info/technical-memo/semver/

New Requirements: iOS 6, Mac OS X 10.8, & Xcode 5

AFNetworking 2.0 officially supports iOS 6+, Mac OS X 10.8+, and Xcode 5.
If you'd like to use AFNetworking in a project targeting a base SDK of iOS 5, or Mac OS X 10.7, use the latest tagged 1.x release. For iOS 4.3 and Mac OS X 10.6 support, use the latest tagged 0.10.x release.

AFNetworking2.0は正式にiOS6以降、Mac OS X10.8以降、そしてXcode5をサポートしています。
iOS5のBaseSDK、又はMac OS X 10.7をターゲットプロジェクトにAFNetworkingを使用したい場合は、
最新のタグ付けされた1.xのリリースを使用して下さい。
iOS4.3及びMac OS X 10.6のサポートについては、最新のタグ付け0.10.xリリースを使用して下さい。

Serialization

One of the most significant changes in AFNetworking 2.0 is its new architecture for content negotiation and serialization. Previously, response validation and serialization was delegated to AFHTTPRequestOperation and its subclasses, with content-specific logic scattered throughout implementations for setCompletionBlockWithSuccess:failure: and other properties. In 2.0, all of this logic is encapsulated in a serializer object that conforms to .

Both & are lightweight protocols, with a single method each:

AFNetworking2.0における最も重要な変化の一つは、
コンテントネゴシエーションとシリアル化のための新しいアーキテクチャです。
以前はレスポンスの検証とシリアル化はコンテンツ固有のロジックがsetCompletionBlockWithSuccessの実装に点在しAFHTTPRequestOperationとそのサブクラスに委譲されていました。
2.0では、このロジックのすべてがに準拠したシリアライザオブジェクトにカプセル化されます。

と はそれぞれ１つのメソッドを持つ軽量なプロトコルです。

- (NSURLRequest *)requestBySerializingRequest:(NSURLRequest *)request
                               withParameters:(NSDictionary *)parameters
                                        error:(NSError *__autoreleasing *)error

 (id)responseObjectForResponse:(NSURLResponse *)response
                           data:(NSData *)data
                          error:(NSError *__autoreleasing *)error

AFNetworking 2.0 comes with a base set of serializations for content types like JSON, XML, property lists, and images. Each of these serializers inherit from a common superclass, AFHTTPSerializer, which serves as a concrete implementation of both & , providing a default URL query string parameter serialization scheme and default headers for requests, and MIME type and status code validation for responses.

For requests with methods not included in HTTPMethodsEncodingParametersInURI, AFJSONSerializer will encode parameters as JSON in the HTTP body, setting the Content-Type header accordingly. Likewise, AFPropertyListSerializer will encode parameters and set the request header for plist content.

AFNetworking2.0は、JSON、XML、プロパティリスト、および画像等のコンテントタイプの為のシリアル化の基本セットが付属しています。
これらのシリアライザはと双方の具体的な実装となる共通のスーパークラス、AFHTTPSerializerから継承していて、
デフォルトのURLクエリ文字列パラメータのシリアル化スキームおよびリクエストに対するデフォルトヘッダー、そしてレスポンスに対するMIMEタイプとステータスコードの検証を提供します。

HTTPMethodsEncodingParametersInURIに含まれていないメソッドを持つ要求の場合、AFJSONSerializerに応じてContent-Typeヘッダを設定し、HTTPボディにJSONなどのパラメータをエンコードします。同様に、AFPropertyListSerializerはパラメータをエンコードし、plistコンテンツの要求ヘッダーを設定します。

AFHTTPRequestOperationManager and AFHTTPSessionManager both have requestSerializer and responseSerializer properties. AFHTTPRequestOperation adds a responseSerializer property as well, which makes it the preferred request operation class for requests of any content type, rather than being merely a superclass.

requestSerializer is responsible for adding authentication and other shared headers to requests created with -requestWithMethod:URLString:parameters:.

responseSerializer is responsible for serializing a response and its associated data into a response object, or generating an error if the response is invalid. Serialization occurs in the completion block of request operations and session tasks.

AFHTTPRequestOperationManagerとAFHTTPSessionManagerはrequestSerializerとresponseSerializerの両方のプロパティを持ち、
AFHTTPRequestOperationは単にスーパークラスであることより、むしろ任意のコンテンツタイプの要求の優先要求操作クラスとなり、同様にresponseSerializerプロパティを追加します。

requestSerializerにはrequestWithMethod:URLString:parametersによって生成されたリクエストの共有ヘッダと認証を追加する為の責任があります。

responseSerializerにはレスポンスとレスポンスオブジェクト内のそれに関連したデータをシリアライズする責任と、レスポンスが無効な場合にエラーを生成する責任があります。
シリアル化はリクエスト操作とセッションタスクの完了ブロックで発生します。

AFHTTPRequestOperation Example

NSURL *URL = [NSURL URLWithString:@"http://example.com/foo.json"];
NSURLRequest *request = [NSURLRequest requestWithURL:URL];
AFHTTPRequestOperation *operation = [[AFHTTPRequestOperation alloc]
                                     initWithRequest:request];
operation.responseSerializer = [AFJSONResponseSerializer serializer];
[operation setCompletionBlockWithSuccess:^(AFHTTPRequestOperation *operation, id responseObject) {
    NSLog(@"%@", responseObject);
} failure:nil];
[operation start];

AFHTTPRequestOperationManager Example

AFHTTPRequestOperationManager *manager = [AFHTTPRequestOperationManager manager];
manager.responseSerializer = [AFJSONResponseSerializer serializer];
[manager GET:@"http://example.com/foo.json" parameters:nil success:^(AFHTTPRequestOperation *operation, id responseObject) {
    NSLog(@"%@", responseObject);
} failure:nil];

Response serializers can also be chained, using AFCompoundSerializer. Compound serializers consult each component serializer in order, until it finds one that successfully performs responseObjectForResponse:data:error: without generating an error.
If a request operation or task, for example, wanted to be able to handle both JSON and XML responses using a single code path, this can be accomplished by setting a compound serializer with XML and JSON serializer components as the responseSerializer of the HTTP request operation or HTTP client. By default, AFHTTPRequestOperationManager and AFHTTPSessionManager have JSON serializers.

Response serializersは又、AFCompoundSerializerを使うことで連鎖させることもできます。
Compound serializersは正常にエラーなく動作するserializerを見つけるまで各シリアライザーを順番に参照します。
...

その他公式資料

AFNetworking2.0のドキュメント
http://cocoadocs.org/docsets/AFNetworking/2.0.0/

GitHub
マスター https://github.com/AFNetworking/AFNetworking
1.x https://github.com/AFNetworking/AFNetworking/tree/1.x

AFNetworking-2.0-Migration-Guide
https://github.com/AFNetworking/AFNetworking/wiki/AFNetworking-2.0-Migration-Guide