ARConnection Class Reference

Connects to a site using a format. More...

#import <ARConnection.h>

Inheritance diagram for ARConnection:

Collaboration diagram for ARConnection:

Instance Methods
(id)	- initWithSite:format:
(id)	- initWithSite:
(void)	- sendRequest:completionHandler:
	Sends a request.
(NSMutableURLRequest *)	- requestForHTTPMethod:path:headers:
	Builds a mutable HTTP request given a HTTP method, a path and headers.
(id)	- init [implementation]
(NSDictionary *)	- defaultHeaders
	Supplies default headers for the connection; none by default unless a sub-class overrides this method.
(NSDictionary *)	- buildRequestHeaderFieldsUsingHeaders:forHTTPMethod:
(NSDictionary *)	- HTTPFormatHeaderForHTTPMethod:
	Answers a format header for the given HTTP request method.

Class Methods
(NSError *)	+ errorForResponse:
	Decides how to handle the given HTTP response based on the response status code.

Properties
NSURL *	site
id< ARFormat >	format
NSTimeInterval	timeout

Detailed Description

Connects to a site using a format.

Connections do not have responsibility for decoding response bodies. With respect to formatting, connections only carry responsibility for setting up the correct header fields.

Definition at line 45 of file ARConnection.h.

Method Documentation

- (NSDictionary *) buildRequestHeaderFieldsUsingHeaders:		(NSDictionary *)	headers
forHTTPMethod:		(NSString *)	HTTPMethod

Provided by category ARConnection(Private).

Definition at line 40 of file ARConnection+Private.m.

- (NSDictionary *) defaultHeaders

Supplies default headers for the connection; none by default unless a sub-class overrides this method.

Sub-classes can override this method to provide headers required for the underlying connection. Please note however, the implementation subsequently overwrites the format header. Similarly, user-supplied headers override headers injected here as defaults.

Interface Note

Rails' Active Resource gem calls this method default_header, singular. This interface makes it plural since the answer is a dictionary of headers.

Provided by category ARConnection(Private).

Definition at line 35 of file ARConnection+Private.m.

+ (NSError *) errorForResponse:

(ARHTTPResponse *)

response

Decides how to handle the given HTTP response based on the response status code.

The Rails implementation of handle_response checks the status code and raises an exception for any status outside the normal range. The Objective-C implementation does not raise exceptions however, by design. Instead, “handling a response” refers to deriving an error object for an otherwise-successful response.

Returns

Answers an NSError object if the response indicates a problem; nil otherwise. The error object's error code and localised description outline the issue. You can also retrieve the HTTP response object itself by accessing the error's user information dictionary with the ARConnectionHTTPResponseKey key; this key-value pair captures the given ARHTTPResponse wrapper which includes the body as well as the original URL response.

Definition at line 75 of file ARConnection.m.

- (NSDictionary *) HTTPFormatHeaderForHTTPMethod:

(NSString *)

HTTPMethod

Answers a format header for the given HTTP request method.

Parameters

HTTPMethod

String containing either GET, PUT, POST, DELETE or HEAD that specifies the HTTP request method. Case must match.

Returns

A dictionary containing either an Accept or Content-Type format header along with the appropriate MIME type. Merge this dictionary with any other request header fields.

Provided by category ARConnection(Private).

Definition at line 55 of file ARConnection+Private.m.

- (id) init

implementation

Definition at line 44 of file ARConnection.m.

- (id) initWithSite:

(NSURL *)

site

Definition at line 65 of file ARConnection.m.

- (id) initWithSite:		(NSURL *)	site
format:		(id<ARFormat>)	format

Definition at line 54 of file ARConnection.m.

- (NSMutableURLRequest *) requestForHTTPMethod:		(NSString *)	HTTPMethod
path:		(NSString *)	path
headers:		(NSDictionary *)	headers

Builds a mutable HTTP request given a HTTP method, a path and headers.

The request site and timeout originates with the message receiver. You can open either an asynchronous connection using the request, or send it synchronously and wait for the response. You might even enqueue the request in a pool of pending requests. This interface method exists and belongs to the public API in order to provide a flexible approach to handling connections: asynchronous or synchronous, queued or immediate. The method simply prepares the request ready to go.

Parameters

HTTPMethod	HTTP request method, one of: GET, HEAD, PUT, POST or DELETE.
path	URL path element to apply to the site's base URL.
headers	Zero or more header fields. These override all other headers within the request, including authorisation and formatting headers. Use nil for no headers.

Definition at line 150 of file ARConnection.m.

- (void) sendRequest:		(NSURLRequest *)	request
completionHandler:		(ARConnectionCompletionHandler)	completionHandler

Sends a request.

Sending a request answers the raw body data. At this level, the connection only handles the actual sending. It does not attempt to handle the response. Other object methods interpret the response code and decode the response body according to the expected format.

Reimplemented in ARURLConnection, ARQueuedLoadingURLConnection, and ARSynchronousLoadingURLConnection.

Definition at line 70 of file ARConnection.m.

Property Documentation

- (id<ARFormat>) format

readwriteatomicstrong

Definition at line 49 of file ARConnection.h.

- (NSURL*) site

readwriteatomicstrong

Definition at line 47 of file ARConnection.h.

- (NSTimeInterval) timeout

readwriteatomicassign

Definition at line 51 of file ARConnection.h.

---

The documentation for this class was generated from the following files:

• ActiveResourceKit/ARConnection.h
• ActiveResourceKit/ARConnection.m