Inherits from NSOperation
Conforms to RKMapperOperationDelegate
Declared in RKObjectRequestOperation.h

Overview

RKObjectRequestOperation is an NSOperation subclass that implements object mapping on the response body of an NSHTTPResponse loaded via an RKHTTPRequestOperation.

Object request operations are initialized with a fully configured NSURLRequest object and an array of RKResponseDescriptor objects. RKObjectRequestOperation is internally implemented as an aggregate operation that constructs and starts an RKHTTPRequestOperation to perform the network access and retrieve the mappable data. If an error occurs during HTTP transport, the object request operation is failed with the transport error. Once response data is loaded for the request, the object request operation creates and starts an RKObjectResponseMapperOperation to perform the object mapping on the response body. If the mapping operation fails, then object request operation is failed and the error property is set. If mapping is successful, then the mappingResult property is set and the operation is finished successfully.

Acceptable Content Types and Status Codes

Instances of RKObjectRequestOperation determine the acceptability of status codes and content types differently than is typical for AFNetworking derived network opertations. The RKHTTPRequestOperation (which is a subclass of the AFNetworking AFHTTPRequestOperation class) supports the dynamic assigning of acceptable status codes and content types. This facility is utilized during the configuration of the network operation for an object request operation. The set of acceptable content types is determined by consulting the RKMIMETypeSerialization via an invocation of [RKMIMETypeSerialization registeredMIMETypes]. The registeredMIMETypes method returns an NSSet containing either NSString or NSRegularExpression objects that specify the content types for which RKSerialization classes have been registered to handle. The set of acceptable status codes is determined by aggregating the value of the statusCodes property from all registered RKResponseDescriptor objects.

Error Mapping

If the HTTP request returned a response in the Client Error (400-499 range) or Server Error (500-599 range) class and an appropriate RKResponseDescriptor is provided to perform mapping on the response, then the object mapping result is considered to contain a server returned error. In this case, an NSError object is created in the RKErrorDomain with an error code of RKMappingErrorFromMappingResult and the object request operation is failed. In the event that an a response is returned in an error class and no RKResponseDescriptor has been provided to the operation to handle it, then an NSError object in the AFNetworkingErrorDomain with an error code of NSURLErrorBadServerResponse will be returned by the underlying RKHTTPRequestOperation indicating that an unexpected status code was returned.

Prioritization and Cancellation

Object request operations support prioritization and cancellation of the underlying RKHTTPRequestOperation and RKResponseMapperOperation operations that perform the network transport and object mapping duties on their behalf. The queue priority of the object request operation, as set via the [NSOperation setQueuePriority:] method, is applied to the underlying response mapping operation when it is enqueued onto the responseMappingQueue. If the object request operation is cancelled, then the underlying HTTP request operation and response mapping operation are also cancelled.

Caching

Instances of RKObjectRequestOperation support all the HTTP caching facilities available via the NSURLConnection family of API’s. For caching to be enabled, the remote web server that the application is communicating with must emit the appropriate Cache-Control, Expires, and/or ETag headers. When the response headers include the appropriate caching information, the shared NSURLCache instance will manage responses and transparently add conditional GET support to cachable requests. HTTP caching is a deep topic explored in depth across the web and detailed in RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html

The RKObjectRequestOperation class also provides support for utilizing the NSURLCache to satisfy requests without hitting the network. This support enables applications to display views presenting data retrieved via a cachable GET request without revalidating with the server and incurring any overhead. The optimization is controlled via avoidsNetworkAccess property. When enabled, the operation will skip the network transport portion of the object request operation and proceed directly to object mapping the cached response data. When the object request operation is an instance of RKManagedObjectRequestOperation, the deserialization and mapping portion of the process can be skipped entirely and the operation will fetch the appropriate object directly from Core Data, falling back to network transport once the cache entry has expired. Please refer to the documentation accompanying RKManagedObjectRequestOperation for more details.

Core Data

RKObjectRequestOperation is not able to perform object mapping that targets Core Data destination entities. Please refer to the RKManagedObjectRequestOperation subclass for details regarding performing a Core Data object request operation.

Subclassing Notes

The RKObjectRequestOperation is a non-current NSOperation subclass and can be extended by subclassing and providing an implementation of the main method. It conforms to the RKMapperOperationDelegate protocol, providing access to the lifecycle of the mapping process to subclasses.

Tasks

Initializing an Object Request Operation

Configuring Object Mapping

Accessing Operation Results

Accessing the HTTP Request Operation

Setting the Completion Block and Callback Queues

  • – setCompletionBlockWithSuccess:failure:

    Sets the completionBlock property with a block that executes either the specified success or failure block, depending on the state of the object request on completion. If error returns a value, which can be set during HTTP transport by the underlying HTTPRequestOperation or during object mapping by the RKResponseMapperOperation object, then failure is executed. If the object request operation is cancelled, then neither success nor failure will be executed. Otherwise, success is executed.

  •   successCallbackQueue

    The callback dispatch queue on success. If NULL (default), the main queue is used.

    property
  •   failureCallbackQueue

    The callback dispatch queue on failure. If NULL (default), the main queue is used.

    property
  • – setWillMapDeserializedResponseBlock:

    Sets a block to be executed before the object request operation begins mapping the deserialized response body, providing an opportunity to manipulate the mappable representation input that will be passed to the response mapper.

Accessing the Response Mapping Queue

  • + responseMappingQueue

    Returns the operation queue used by all object request operations when object mapping the body of a response loaded via HTTP.

ForSubclassEyesOnly Methods

  • – performMappingOnResponse:

    Performs object mapping using the response and responseData properties.

  • – willFinish

    Invoked to tell the receiver that the object request operation is finishing its work and is about to transition into the finished state. Used to perform any necessary cleanup before the operation is finished.

Properties

HTTPRequestOperation

The underlying RKHTTPRequestOperation object used to manage the HTTP request/response lifecycle of the object request operation.

@property (nonatomic, strong, readonly) RKHTTPRequestOperation *HTTPRequestOperation

Declared In

RKObjectRequestOperation.h

error

The error, if any, that occurred during execution of the operation.

@property (nonatomic, strong, readonly) NSError *error

Discussion

Errors may originate during the network transport or object mapping phases of the object request operation. A nil error value indicates that the operation completed successfully.

Declared In

RKObjectRequestOperation.h

failureCallbackQueue

The callback dispatch queue on failure. If NULL (default), the main queue is used.

@property (nonatomic, assign) dispatch_queue_t failureCallbackQueue

Discussion

The queue is retained while this operation is living

Declared In

RKObjectRequestOperation.h

mappingResult

The mapping result returned by the underlying RKObjectResponseMapperOperation.

@property (nonatomic, strong, readonly) RKMappingResult *mappingResult

Discussion

This property is nil if the operation is failed due to a network transport error.

Declared In

RKObjectRequestOperation.h

responseDescriptors

The array of RKResponseDescriptor objects that specify how the deserialized responseData is to be object mapped.

@property (nonatomic, strong, readonly) NSArray *responseDescriptors

Declared In

RKObjectRequestOperation.h

successCallbackQueue

The callback dispatch queue on success. If NULL (default), the main queue is used.

@property (nonatomic, assign) dispatch_queue_t successCallbackQueue

Discussion

The queue is retained while this operation is living

Declared In

RKObjectRequestOperation.h

targetObject

The target object for the object mapping operation.

@property (nonatomic, strong) id targetObject

Declared In

RKObjectRequestOperation.h

Class Methods

responseMappingQueue

Returns the operation queue used by all object request operations when object mapping the body of a response loaded via HTTP.

+ (NSOperationQueue *)responseMappingQueue

Return Value

The response mapping queue.

Discussion

By default, the response mapping queue is configured with a maximum concurrent operation count of 1, ensuring that only one HTTP response is mapped at a time.

Declared In

RKObjectRequestOperation.h

Instance Methods

initWithHTTPRequestOperation:responseDescriptors:

Initializes an object request operation with an HTTP request operation and a set of response descriptors.

- (id)initWithHTTPRequestOperation:(RKHTTPRequestOperation *)requestOperation responseDescriptors:(NSArray *)responseDescriptors

Parameters

responseDescriptors

An array of RKResponseDescriptor objects specifying how object mapping is to be performed on the response loaded by the network operation.

request

The request object to be used with the underlying network operation.

Return Value

The receiver, initialized with the given request and response descriptors.

Discussion

This is the designated initializer.

Declared In

RKObjectRequestOperation.h

initWithRequest:responseDescriptors:

Initializes an object request operation with a request object and a set of response descriptors.

- (id)initWithRequest:(NSURLRequest *)request responseDescriptors:(NSArray *)responseDescriptors

Parameters

request

The request object to be used with the underlying network operation.

responseDescriptors

An array of RKResponseDescriptor objects specifying how object mapping is to be performed on the response loaded by the network operation.

Return Value

The receiver, initialized with the given request and response descriptors.

Discussion

This method is a convenience initializer for initializing an object request operation from a URL request with the default HTTP operation class RKHTTPRequestOperation. This method is functionally equivalent to the following example code:

RKHTTPRequestOperation *requestOperation = [[RKHTTPRequestOperation alloc] initWithRequest:request];
RKObjectRequestOperation *objectRequestOperation = [[RKObjectRequestOperation alloc] initWithHTTPRequestOperation:requestOperation responseDescriptors:responseDescriptors];

Declared In

RKObjectRequestOperation.h

performMappingOnResponse:

Performs object mapping using the response and responseData properties.

- (RKMappingResult *)performMappingOnResponse:(NSError **)error

Parameters

error

A pointer to an NSError object to be set in the event that the object mapping process has failed.

Return Value

A mapping result or nil if an error has occurred.

Discussion

The RKObjectRequestOperation superclass is responsible for the invocation of this method and the subsequent handling of the mapping result or error.

Declared In

RKRequestOperationSubclass.h

setCompletionBlockWithSuccess:failure:

Sets the completionBlock property with a block that executes either the specified success or failure block, depending on the state of the object request on completion. If error returns a value, which can be set during HTTP transport by the underlying HTTPRequestOperation or during object mapping by the RKResponseMapperOperation object, then failure is executed. If the object request operation is cancelled, then neither success nor failure will be executed. Otherwise, success is executed.

- (void)setCompletionBlockWithSuccess:(void ( ^ ) ( RKObjectRequestOperation *operation , RKMappingResult *mappingResult ))success failure:(void ( ^ ) ( RKObjectRequestOperation *operation , NSError *error ))failure

Parameters

success

The block to be executed on the completion of a successful operation. This block has no return value and takes two arguments: the receiver operation and the mapping result from object mapping the response data of the request.

failure

The block to be executed on the completion of an unsuccessful operation. This block has no return value and takes two arguments: the receiver operation and the error that occurred during the execution of the operation.

Declared In

RKObjectRequestOperation.h

setWillMapDeserializedResponseBlock:

Sets a block to be executed before the object request operation begins mapping the deserialized response body, providing an opportunity to manipulate the mappable representation input that will be passed to the response mapper.

- (void)setWillMapDeserializedResponseBlock:(id ( ^ ) ( id deserializedResponseBody ))block

Parameters

block

A block object to be executed before the deserialized response is passed to the response mapper. The block has an id return type and must return a dictionary or array of dictionaries corresponding to the object representations that are to be mapped. The block accepts a single argument: the deserialized response data that was loaded via HTTP. If you do not wish to make any chances to the response body before mapping begins, the block should return the value passed in the deserializedResponseBody block argument. Returning nil will decline the mapping from proceeding and fail the operation with an error with the RKMappingErrorMappingDeclined code.

Discussion

Warning: The deserialized response body may or may not be immutable depending on the implementation details of the RKSerialization class that deserialized the response. If you wish to make changes to the mappable object representations, you must obtain a mutable copy of the response body input.

Declared In

RKObjectRequestOperation.h

willFinish

Invoked to tell the receiver that the object request operation is finishing its work and is about to transition into the finished state. Used to perform any necessary cleanup before the operation is finished.

- (void)willFinish

Declared In

RKRequestOperationSubclass.h