Inherits from NSOperation
Conforms to NSCopying
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 assignment 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.

Metadata Mapping

The RKObjectRequestOperation class provides support for metadata mapping via the mappingMetadata property. This optional dictionary of user supplied information is made available to the mapping operations executed when processing the HTTP response loaded by an object request operation. More details about the metadata mapping architecture is available on the RKMappingOperation documentation.

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

  •   responseDescriptors

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

    property
  •   targetObject

    The target object for the object mapping operation.

    property
  •   mappingMetadata

    An optional dictionary of metadata to make available to mapping operations executed while processing the HTTP response loaded by the receiver.

    property

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 the failure block will be executed with either a RKOperationCancelledError or a NSURLErrorCancelled, depending on the internal state of the operation at time of cancellation. 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.

Determining Whether a Request Can Be Processed

  • + canProcessRequest:

    Returns a Boolean value determining whether or not the class can process the specified request.

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

  • – performMappingOnResponseWithCompletionBlock:

    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

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

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

Declared In

RKObjectRequestOperation.h

error

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

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

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

@property (nonatomic, assign) dispatch_queue_t failureCallbackQueue
Discussion

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

The queue is retained while this operation is living

Declared In

RKObjectRequestOperation.h

mappingMetadata

@property (nonatomic, copy) NSDictionary *mappingMetadata
Discussion

An optional dictionary of metadata to make available to mapping operations executed while processing the HTTP response loaded by the receiver.

Declared In

RKObjectRequestOperation.h

mappingResult

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

The mapping result returned by the underlying RKObjectResponseMapperOperation.

This property is nil if the operation is failed due to a network transport error or no mapping was peformed on the response.

Declared In

RKObjectRequestOperation.h

responseDescriptors

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

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

The response descriptors define the acceptable HTTP Status Codes of the receiver.

Declared In

RKObjectRequestOperation.h

successCallbackQueue

@property (nonatomic, assign) dispatch_queue_t successCallbackQueue
Discussion

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

The queue is retained while this operation is living

Declared In

RKObjectRequestOperation.h

targetObject

@property (nonatomic, strong) id targetObject
Discussion

The target object for the object mapping operation.

Declared In

RKObjectRequestOperation.h

Class Methods

canProcessRequest:

+ (BOOL)canProcessRequest:(NSURLRequest *)request
Discussion

Returns a Boolean value determining whether or not the class can process the specified request.

Parameters

request

The request that is determined to be supported or not supported for this class.

Declared In

RKObjectRequestOperation.h

responseMappingQueue

+ (NSOperationQueue *)responseMappingQueue
Discussion

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

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.

Return Value

The response mapping queue.

Declared In

RKObjectRequestOperation.h

Instance Methods

initWithHTTPRequestOperation:responseDescriptors:

- (instancetype)initWithHTTPRequestOperation:(RKHTTPRequestOperation *)requestOperation responseDescriptors:(NSArray *)responseDescriptors
Discussion

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

This is the designated initializer.

Parameters

requestOperation

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.

Declared In

RKObjectRequestOperation.h

initWithRequest:responseDescriptors:

- (instancetype)initWithRequest:(NSURLRequest *)request responseDescriptors:(NSArray *)responseDescriptors
Discussion

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

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];

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.

Declared In

RKObjectRequestOperation.h

performMappingOnResponseWithCompletionBlock:

- (void)performMappingOnResponseWithCompletionBlock:(void ( ^ ) ( RKMappingResult *mappingResult , NSError *error ))completionBlock
Discussion

Performs object mapping using the response and responseData properties.

The RKObjectRequestOperation superclass is responsible for the invocation of this method and the subsequent handling of the mapping result or 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.

Declared In

RKObjectRequestOperationSubclass.h

setCompletionBlockWithSuccess:failure:

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

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 the failure block will be executed with either a RKOperationCancelledError or a NSURLErrorCancelled, depending on the internal state of the operation at time of cancellation. Otherwise, success is executed.

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:

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

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.

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.

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.

Declared In

RKObjectRequestOperation.h

willFinish

- (void)willFinish
Discussion

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.

Declared In

RKObjectRequestOperationSubclass.h