RKObjectRequestOperation Class Reference
| 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
-
– initWithHTTPRequestOperation:responseDescriptors:Initializes an object request operation with an HTTP request operation and a set of response descriptors.
-
– initWithRequest:responseDescriptors:Initializes an object request operation with a request object and a set of response descriptors.
Configuring Object Mapping
-
responseDescriptorsThe array of
propertyRKResponseDescriptorobjects that specify how the deserializedresponseDatais to be object mapped. -
targetObjectThe target object for the object mapping operation.
property
Accessing Operation Results
-
mappingResultThe mapping result returned by the underlying
propertyRKObjectResponseMapperOperation. -
errorThe error, if any, that occurred during execution of the operation.
property
Accessing the HTTP Request Operation
-
HTTPRequestOperationThe underlying
propertyRKHTTPRequestOperationobject used to manage the HTTP request/response lifecycle of the object request operation.
Setting the Completion Block and Callback Queues
-
– setCompletionBlockWithSuccess:failure:Sets the
completionBlockproperty with a block that executes either the specified success or failure block, depending on the state of the object request on completion. Iferrorreturns a value, which can be set during HTTP transport by the underlyingHTTPRequestOperationor during object mapping by theRKResponseMapperOperationobject, thenfailureis executed. If the object request operation is cancelled, then neither success nor failure will be executed. Otherwise,successis executed. -
successCallbackQueueThe callback dispatch queue on success. If
propertyNULL(default), the main queue is used. -
failureCallbackQueueThe callback dispatch queue on failure. If
propertyNULL(default), the main queue is used. -
– 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
-
+ responseMappingQueueReturns 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
responseandresponseDataproperties. -
– willFinishInvoked 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 *HTTPRequestOperationDeclared In
RKObjectRequestOperation.herror
The error, if any, that occurred during execution of the operation.
@property (nonatomic, strong, readonly) NSError *errorDiscussion
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.hfailureCallbackQueue
The callback dispatch queue on failure. If NULL (default), the main queue is used.
@property (nonatomic, assign) dispatch_queue_t failureCallbackQueueDiscussion
The queue is retained while this operation is living
Declared In
RKObjectRequestOperation.hmappingResult
The mapping result returned by the underlying RKObjectResponseMapperOperation.
@property (nonatomic, strong, readonly) RKMappingResult *mappingResultDiscussion
This property is nil if the operation is failed due to a network transport error.
Declared In
RKObjectRequestOperation.hresponseDescriptors
The array of RKResponseDescriptor objects that specify how the deserialized responseData is to be object mapped.
@property (nonatomic, strong, readonly) NSArray *responseDescriptorsDeclared In
RKObjectRequestOperation.hClass Methods
responseMappingQueue
Returns the operation queue used by all object request operations when object mapping the body of a response loaded via HTTP.
+ (NSOperationQueue *)responseMappingQueueReturn 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.hInstance 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 *)responseDescriptorsParameters
- responseDescriptors
An array of
RKResponseDescriptorobjects 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.hinitWithRequest:responseDescriptors:
Initializes an object request operation with a request object and a set of response descriptors.
- (id)initWithRequest:(NSURLRequest *)request responseDescriptors:(NSArray *)responseDescriptorsParameters
- request
The request object to be used with the underlying network operation.
- responseDescriptors
An array of
RKResponseDescriptorobjects 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.hperformMappingOnResponse:
Performs object mapping using the response and responseData properties.
- (RKMappingResult *)performMappingOnResponse:(NSError **)errorParameters
- error
A pointer to an
NSErrorobject 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.hsetCompletionBlockWithSuccess: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 ))failureParameters
- 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.hsetWillMapDeserializedResponseBlock:
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 ))blockParameters
- block
A block object to be executed before the deserialized response is passed to the response mapper. The block has an
idreturn 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 thedeserializedResponseBodyblock argument. Returningnilwill decline the mapping from proceeding and fail the operation with an error with theRKMappingErrorMappingDeclinedcode.
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