ARService Class Reference

An active resource's service configuration. More...

#import <ARService.h>

Inheritance diagram for ARService:

Collaboration diagram for ARService:

Instance Methods
(id)	- initWithSite:
	Initialises a new Active Resource Base instance using a given site.
(id)	- initWithSite:elementName:
(ARService *)	- serviceForSubelementNamed:
	Derives a service for a subelement based on this service, representing nested resources.
(NSArray *)	- knownAttributes
	Answers the known attributes, known because the resource server publishes them; although the server does not necessarily publish everything.
(NSURL *)	- siteWithPrefixParameter
	Answers this service's site URL combined with an additional prefix parameter representing the element attached to this service.
(id< ARFormat >)	- formatLazily
(ARConnection *)	- connectionLazily
(void)	- setConnection:
(NSMutableDictionary *)	- headersLazily
(NSString *)	- elementNameLazily
(NSString *)	- collectionNameLazily
(NSString *)	- primaryKeyLazily
(NSString *)	- foreignKey
	Answers the element's foreign key.
(NSString *)	- prefixSourceLazily
(NSString *)	- prefixWithOptions:
(NSString *)	- elementPathForID:prefixOptions:queryOptions:
(NSString *)	- newElementPathWithPrefixOptions:
(NSString *)	- collectionPathWithPrefixOptions:queryOptions:
(void)	- buildWithAttributes:completionHandler:
(void)	- createWithAttributes:completionHandler:
	Creates a new resource instance, requesting that the remote service saves the new resource.
(void)	- findAllWithOptions:completionHandler:
(void)	- findFirstWithOptions:completionHandler:
(void)	- findLastWithOptions:completionHandler:
(void)	- findSingleWithID:options:completionHandler:
	Finds a single resource for a given identifier using the default URL.
(void)	- findOneWithOptions:completionHandler:
	Finds a single resource from a one-off URL.
(void)	- deleteWithID:options:completionHandler:
	Deletes the resource with the given ID.
(void)	- existsWithID:options:completionHandler:
	Asserts the existence of a resource.
(id)	- init [implementation]
(id< ARFormat >)	- defaultFormat
(NSString *)	- defaultElementName
(NSString *)	- defaultCollectionName
(NSString *)	- defaultPrimaryKey
(NSString *)	- defaultPrefixSource
(void)	- findEveryWithOptions:completionHandler:
(NSArray *)	- instantiateCollection:prefixOptions:
(ARResource *)	- instantiateRecordWithAttributes:prefixOptions:
	Instantiates a resource element (a record) using the given attributes and prefix options.
(NSSet *)	- prefixParameters
(void)	- splitOptions:prefixOptions:queryOptions:
(void)	- get:completionHandler:
	Sends an asynchronous GET request. Used to find a resource.
(void)	- delete:completionHandler:
	Used to delete resources. Sends an asynchronous DELETE request.
(void)	- put:body:completionHandler:
	Sends an asynchronous PUT request.
(void)	- post:body:completionHandler:
	Sends an asynchronous POST request.
(void)	- head:completionHandler:
	Used to obtain meta-information about resources, whether they exist or their size. Sends an asynchronous HEAD request.
(void)	- requestHTTPMethod:path:body:completionHandler:
	Submits an asynchronous request, returning immediately.
(ARConnectionCompletionHandler)	- decodeHandlerWithCompletionHandler:
	Answers a decoding handler which, in turn, after decoding, invokes another given completion block.

Class Methods
(Class)	+ defaultConnectionClass
(void)	+ setDefaultConnectionClass:

Protected Attributes
ARConnection *__strong	_connection

Properties
NSDictionary *	schema
NSURL *	site
id< ARFormat >	format
NSTimeInterval	timeout
NSMutableDictionary *	headers
NSString *	elementName
NSString *	collectionName
NSString *	primaryKey
NSString *	prefixSource

Detailed Description

An active resource's service configuration.

Defines an active resource's site, schema and known attributes, etc. Does not however define an active resource instance. Active resources binding to the same remote element at the same remote site associate with a common base.

ARService corresponds to the singleton class aspects of ActiveResource::Base. Under Rails ActiveResource, the ActiveResource::Base singleton class carries the following state. See list below.

• auth_type
• collection_name
• connection
• element_name
• headers
• known_attributes
• nospam
• password
• prefix_parameters
• primary_key
• proxy
• schema
• site
• ssl_options
• test
• timeout
• user

This might help to define what ARService actually does, its purpose. ARService implements the anonymous singleton class behaviours belonging to ActiveResource::Base. ARResource defines the class for Active Resource instances, but ARService defines the class for Active Resource classes, singleton classes that is. Objective-C 2.0 does not provide anything comparable singleton classes. The Rails singleton class becomes the Objective-C “service” class.

Singleton methods for ActiveResource::Base include the following.

• all
• auth_type
• build
• check_prefix_options
• collection_name
• collection_path
• connection
• create
• create_proxy_uri_from
• create_site_uri_from
• delete
• element_name
• element_path
• exists
• find
• find_every
• find_one
• find_single
• first
• format
• headers
• instantiate_collection
• instantiate_record
• known_attributes
• last
• new_element_path
• password
• prefix
• prefix_parameters
• prefix_source
• primary_key
• proxy
• query_string
• schema
• site
• split_options
• ssl_options
• timeout
• user

Lazy Getters

Use a getter-lazily paradigm in place of actual lazy getting. This has advantages. First, it obviates the need for defining custom getters and setters. This is a useful thing, since the exact setter and getter implementations depend on the memory model being deployed. Automatic Reference Counting (ARC) has one requirement, garbage-collection another, and manual retain-release (MRR) another. Strategy employed here: Let the compiler synthesise the correct setters and getters accordingly. If you want to access the getter but with lazy initialisation, ask for propertyLazily.

Definition at line 140 of file ARService.h.

Method Documentation

- (void) buildWithAttributes:		(NSDictionary *)	attributes
completionHandler:		(ARResourceCompletionHandler)	completionHandler

Asynchronously builds an Active Resource.

Executes the completion handler on success or upon error. Completion handler arguments signal the outcome: non-nil attributes indicate successful completion. In such case, error always equals nil. There is no error.

Definition at line 319 of file ARService.m.

- (NSString *) collectionNameLazily

Definition at line 203 of file ARService.m.

- (NSString *) collectionPathWithPrefixOptions:		(NSDictionary *)	prefixOptions
queryOptions:		(NSDictionary *)	queryOptions

Definition at line 301 of file ARService.m.

- (ARConnection *) connectionLazily

Definition at line 150 of file ARService.m.

- (void) createWithAttributes:		(NSDictionary *)	attributes
completionHandler:		(ARResourceCompletionHandler)	completionHandler

Creates a new resource instance, requesting that the remote service saves the new resource.

Definition at line 351 of file ARService.m.

- (ARConnectionCompletionHandler) decodeHandlerWithCompletionHandler:

(ARServiceRequestCompletionHandler)

completionHandler

Answers a decoding handler which, in turn, after decoding, invokes another given completion block.

Active Resource Kit methods utilise this common response block for decoding according to the required format. In fact, the decoding does a little more than just decode the format. It also handles URL response to HTTP response type casting. The latter carries more information including header fields and HTTP status code.

Provided by category ARService(Private).

Definition at line 194 of file ARService+Private.m.

- (NSString *) defaultCollectionName

Provided by category ARService(Private).

Definition at line 52 of file ARService+Private.m.

+ (Class) defaultConnectionClass

Definition at line 40 of file ARService.m.

- (NSString *) defaultElementName

Provided by category ARService(Private).

Definition at line 47 of file ARService+Private.m.

- (id< ARFormat >) defaultFormat

Provided by category ARService(Private).

Definition at line 42 of file ARService+Private.m.

- (NSString *) defaultPrefixSource

Provided by category ARService(Private).

Definition at line 62 of file ARService+Private.m.

- (NSString *) defaultPrimaryKey

Provided by category ARService(Private).

Definition at line 57 of file ARService+Private.m.

- (void) delete:		(NSString *)	path
completionHandler:		(ARServiceRequestCompletionHandler)	completionHandler

Used to delete resources. Sends an asynchronous DELETE request.

Provided by category ARService(Private).

Definition at line 163 of file ARService+Private.m.

- (void) deleteWithID:		(NSNumber *)	ID
options:		(NSDictionary *)	options
completionHandler:		(ARHTTPResponse *response, NSError *error)	completionHandler

Deletes the resource with the given ID.

Parameters

ID	Identifies the resource to delete.
options	All options specify prefix and query parameters.
completionHandler	Block to execute on success or failure.

Definition at line 429 of file ARService.m.

- (NSString *) elementNameLazily

Definition at line 192 of file ARService.m.

- (NSString *) elementPathForID:		(NSNumber *)	ID
prefixOptions:		(NSDictionary *)	prefixOptions
queryOptions:		(NSDictionary *)	queryOptions

Definition at line 283 of file ARService.m.

- (void) existsWithID:		(NSNumber *)	ID
options:		(NSDictionary *)	options
completionHandler:		(ARHTTPResponse *response, BOOL exists, NSError *error)	completionHandler

Asserts the existence of a resource.

Parameters

ID	Identifies the resource to assert the existence of.
options	Specifies prefix and query parameters if any.
completionHandler	Block to execute on success or failure. The block's parameters include a response, a boolean equal to YES if a resource with the given ID really exists along with an error object describing the error if one occurs.

The resource exists when the block receives exists argument equal to YES. This indicates a valid code-200 response from the remote service. Otherwise, when exists equals NO, either the resource does not exist or there was a communication error. When the remote service fails to locate the given resource, the completion handler receives an error object with an error code matching ARResourceNotFoundErrorCode or ARResourceGoneErrorCode (response codes 404 or 410, respectively).

Note

Asserting existence sends a HEAD request to the remote RESTful service. The standard Rails Rack converts the HEAD request to a GET but then strips the body from the response.

Definition at line 437 of file ARService.m.

- (void) findAllWithOptions:		(NSDictionary *)	options
completionHandler:		(ARResourcesCompletionHandler)	completionHandler

Definition at line 359 of file ARService.m.

- (void) findEveryWithOptions:		(NSDictionary *)	options
completionHandler:		(ARHTTPResponse *response, NSArray *resources, NSError *error)	completionHandler

Provided by category ARService(Private).

Definition at line 67 of file ARService+Private.m.

- (void) findFirstWithOptions:		(NSDictionary *)	options
completionHandler:		(ARResourceCompletionHandler)	completionHandler

Answers just the first resource in a collection of resources. Finds all the resources first, then extracts the first element. Acts as a convenience wrapper.

Definition at line 364 of file ARService.m.

- (void) findLastWithOptions:		(NSDictionary *)	options
completionHandler:		(ARResourceCompletionHandler)	completionHandler

Definition at line 371 of file ARService.m.

- (void) findOneWithOptions:		(NSDictionary *)	options
completionHandler:		(ARResourceCompletionHandler)	completionHandler

Finds a single resource from a one-off URL.

This method expects you to provide the one-off URL using the ARFromKey within the options dictionary. You must also specify query string parameters using the ARParamsKey within the options.

Definition at line 403 of file ARService.m.

- (void) findSingleWithID:		(NSNumber *)	ID
options:		(NSDictionary *)	options
completionHandler:		(ARResourceCompletionHandler)	completionHandler

Finds a single resource for a given identifier using the default URL.

Ruby on Rails Comparison

Under the Rails' ActiveResource gem, this method appears as a private method. Why not here? In Rails, you access the find_single(scope, options) method indirectly as the default find(arguments) case when the first scope argument does not match all, first, last or one (by symbol). Objective-C does not offer so flexible a syntax. Consequently, this implementation folds the find-scope interface into distinct methods: find all, find first, find last, find one and find single. The scope argument resolves to the method name. This approach carries advantages and disadvantages. It eliminates the switch statement necessary to resolve the scope. But at the same stroke eliminates the flexibility of parameterising the scope in cases where scope is a dynamic argument.

Definition at line 378 of file ARService.m.

- (NSString *) foreignKey

Answers the element's foreign key.

The foreign key equates to the element name followed by an underscore and finally the "id" string. This key can appear in URL paths as a prefix parameter, marked by a leading colon.

Definition at line 229 of file ARService.m.

- (id< ARFormat >) formatLazily

Definition at line 129 of file ARService.m.

- (void) get:		(NSString *)	path
completionHandler:		(ARServiceRequestCompletionHandler)	completionHandler

Sends an asynchronous GET request. Used to find a resource.

When the response successfully arrives, the format decodes the data. If the response body decodes successfully, finally sends the decoded object (or objects) to your given completion handler. Objects may be hashes (dictionaries) or arrays, or even primitives.

Provided by category ARService(Private).

Definition at line 158 of file ARService+Private.m.

- (void) head:		(NSString *)	path
completionHandler:		(ARServiceRequestCompletionHandler)	completionHandler

Used to obtain meta-information about resources, whether they exist or their size. Sends an asynchronous HEAD request.

Provided by category ARService(Private).

Definition at line 178 of file ARService+Private.m.

- (NSMutableDictionary *) headersLazily

Definition at line 173 of file ARService.m.

- (id) init

implementation

Definition at line 55 of file ARService.m.

- (id) initWithSite:

(NSURL *)

site

Initialises a new Active Resource Base instance using a given site.

Parameters

site	An URL specifying the remote HTTP or HTTPS resource.

This is not the designated initialiser but rather a shorthand for sending -init followed by -setSite:. The element name, if you do not subsequently assign one, derives from the ARService sub-class name. This assumes that you derive ARService.

Definition at line 70 of file ARService.m.

- (id) initWithSite:		(NSURL *)	site
elementName:		(NSString *)	elementName

Definition at line 80 of file ARService.m.

- (NSArray *) instantiateCollection:		(NSArray *)	collection
prefixOptions:		(NSDictionary *)	prefixOptions

Instantiates a collection of active resources given a collection of attributes; collection here meaning an array. The collection argument specifies an array of dictionaries. Each dictionary specifies attributes for a new active resource. Answers an array of newly instantiated active resources.

Provided by category ARService(Private).

Definition at line 95 of file ARService+Private.m.

- (ARResource *) instantiateRecordWithAttributes:		(NSDictionary *)	attributes
prefixOptions:		(NSDictionary *)	prefixOptions

Instantiates a resource element (a record) using the given attributes and prefix options.

The implementation looks for a class matching the element name. It converts the element name to class name by camel-casing the name. The answer becomes an instance of that class if the class exists and derives from ARResource. Otherwise the answer is a plain instance of ARResource.

Provided by category ARService(Private).

Definition at line 105 of file ARService+Private.m.

- (NSArray *) knownAttributes

Answers the known attributes, known because the resource server publishes them; although the server does not necessarily publish everything.

Known attributes depend on schema. The result amounts to the schema's keys. The schema is a dictionary of attribute name-type pairs.

Definition at line 106 of file ARService.m.

- (NSString *) newElementPathWithPrefixOptions:

(NSDictionary *)

prefixOptions

Definition at line 296 of file ARService.m.

- (void) post:		(NSString *)	path
body:		(NSData *)	data
completionHandler:		(ARServiceRequestCompletionHandler)	completionHandler

Sends an asynchronous POST request.

POST is not idempotent.

Provided by category ARService(Private).

Definition at line 173 of file ARService+Private.m.

- (NSSet *) prefixParameters

Answers a set of prefix parameters based on the current prefix source. These constitute the current set of prefix parameters: an array of strings without the leading colon. Colon immediately followed by a word marks each parameter in the prefix source.

Provided by category ARService(Private).

Definition at line 117 of file ARService+Private.m.

- (NSString *) prefixSourceLazily

Definition at line 241 of file ARService.m.

- (NSString *) prefixWithOptions:

(NSDictionary *)

options

Answers the prefix after translating the prefix parameters according to the given prefix-options dictionary. The options dictionary may be nil. In that case -prefixWithOptions: answers the prefix unmodified. This assumes that the prefix contains no untranslated prefix parameters. The method quietly fails if you do not provide mappings for all parameters. The prefix result will contain parameter placeholders.

Definition at line 260 of file ARService.m.

- (NSString *) primaryKeyLazily

Definition at line 219 of file ARService.m.

- (void) put:		(NSString *)	path
body:		(NSData *)	data
completionHandler:		(ARServiceRequestCompletionHandler)	completionHandler

Sends an asynchronous PUT request.

PUT is idempotent, meaning that multiple PUT requests result in an identical resource state. There should be no side effects. PUT really amounts to an “upsert” database operation where it updates the resource if it already exists but alternatively creates the resource if it does not already exist.

Provided by category ARService(Private).

Definition at line 168 of file ARService+Private.m.

- (void) requestHTTPMethod:		(NSString *)	HTTPMethod
path:		(NSString *)	path
body:		(NSData *)	data
completionHandler:		(ARServiceRequestCompletionHandler)	completionHandler

Submits an asynchronous request, returning immediately.

Constructs a request object and asynchronously transmits it to the remote RESTful service. The completion handler executes in the resource service's operation queue, or the current queue (the operation queue running at the time of the request) if the resource service has no queue.

The completion handler receives three arguments: the HTTP response, the decoded object and any error. The decoded object derives from the response body, decoded according to the service format. Decoding itself can encounter errors. If successful, the completion handler receives a non-nil object and a nil error. If the response is not an HTTP-based response, the completion handler receives a nil response argument and an ARResponseIsNotHTTPError.

Provided by category ARService(Private).

Definition at line 183 of file ARService+Private.m.

- (ARService *) serviceForSubelementNamed:

(NSString *)

elementName

Derives a service for a subelement based on this service, representing nested resources.

The new service shares the connection, if already configured. Otherwise, it constructs its own connection on-demand using the default.

Definition at line 90 of file ARService.m.

- (void) setConnection:

(ARConnection *)

connection

Setting the connection overwrites the given connection's site, format and time-out. You can easily reset any of these attributes afterwards, even though that defeats the purpose.

Definition at line 159 of file ARService.m.

+ (void) setDefaultConnectionClass:

(Class)

aClass

Definition at line 49 of file ARService.m.

- (NSURL *) siteWithPrefixParameter

Answers this service's site URL combined with an additional prefix parameter representing the element attached to this service.

Useful for initialising a nested resource service. You can use the answer to build another service for accessing resources nested below this service element. You need to supply the super-resource identifier as a prefix option when accessing sub-resources, using the super-resource's foreign key as the option key.

Definition at line 117 of file ARService.m.

- (void) splitOptions:		(NSDictionary *)	options
prefixOptions:		(NSDictionary **)	outPrefixOptions
queryOptions:		(NSDictionary **)	outQueryOptions

Splits an options dictionary into two dictionaries, one containing the prefix options, the other containing the leftovers, i.e. any query options.

Provided by category ARService(Private).

Definition at line 128 of file ARService+Private.m.

Member Data Documentation

- (ARConnection* __strong) _connection

protected

Definition at line 142 of file ARService.h.

Property Documentation

- (NSString*) collectionName

readwriteatomiccopy

Definition at line 257 of file ARService.h.

- (NSString*) elementName

readwriteatomiccopy

Definition at line 256 of file ARService.h.

- (id<ARFormat>) format

readwriteatomicstrong

Definition at line 210 of file ARService.h.

- (NSMutableDictionary*) headers

readwriteatomicstrong

Note

The headers property exposes its implementation. This echoes the Rails interface where ActiveResource::Base subclasses derives a singleton class with a directly-accessible mutable hash called headers. If Person inherits from ActiveResource::Base, then an instance of Person exposes its mutable headers at person.class.headers.

Definition at line 241 of file ARService.h.

- (NSString*) prefixSource

readwriteatomiccopy

By default, the prefix source equals the site URL's path.

Definition at line 282 of file ARService.h.

- (NSString*) primaryKey

readwriteatomiccopy

Definition at line 265 of file ARService.h.

- (NSDictionary*) schema

readwriteatomiccopy

Definition at line 178 of file ARService.h.

- (NSURL*) site

readwriteatomiccopy

Always set up the site first. Other things depend on this essential property. You cannot fully operate the resource without the site URL. The site's path becomes the default prefix.

Definition at line 195 of file ARService.h.

- (NSTimeInterval) timeout

readwriteatomicassign

Definition at line 217 of file ARService.h.

---

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

• ActiveResourceKit/ARService.h
• ActiveResourceKit/ARService.m