RKResponseMapperOperation Class Reference
Inherits from | NSOperation |
Declared in | RKResponseMapperOperation.h |
Overview
RKResponseMapperOperation
is an NSOperation
that provides support for performing object mapping on an NSHTTPURLResponse
and its associated response data.
This is an abstract base class encapsulating the common interface API for its concrete subclasses RKObjectResponseMapperOperation
and RKManagedObjectResponseMapperOperation
.
The common behaviors encapsulated within RKResponseMapperOperation
include:
- Handling Empty Responses: Empty response data (see note below) requires special handling depending on the status code of the HTTP response. If an empty response is loaded with a status code in 4xx (Client Error) range, an
NSError
in theRKErrorDomain
is created with theNSURLErrorBadServerResponse
code to indicate that the response was not processable. If an empty response is loaded with a status code in 2xx (Successful) range, the interpretation of the response is dependent on the value oftreatsEmptyResponseAsSuccess
. WhenYES
, empty responses result in the successful completion of the operation with anRKMappingResult
containing the targetObject of the operation, if any. - Deserializing Response Data: When started, the operation attempts to deserialize the response data into a Foundation object representation using the
RKMIMETypeSerialization
class. This deserialized representation is then made available to subclass implementations that perform the actual object mapping work.
How ‘Empty’ Responses are Evaluated
Any nil
response or NSData
object with a length equal to zero is considered empty. To support a common behavior of the widely deployed Ruby on Rails Framework, RKResponseMapperOperation
also considers a response containing a single space character to be empty. This type of response is generated by Rails whe render :nothing => true
is invoked.
Metadata Mapping
The RKResponseMapperOperation
class integrates with the metadata mapping architecture. Clients of the response mapper can provide a dictionary of metadata via the mappingMetadata
property and it will be made available to the underlying RKMapperOperation
executed to process the response body. In addition to any user supplied metadata, the response mapper makes the following metadata key paths available for mapping:
@meta
data.HTTP.
request.URL
– TheNSURL
object identifying the URL of the request that loaded the response.@meta
data.HTTP.
request.method
– AnNSString
specifying the HTTP method of the request that loaded the response.@meta
data.HTTP.
request.headers
– AnNSDictionary
object containing all HTTP headers and values for the request that loaded the response.@meta
data.HTTP.
response.URL
– TheNSURL
object identifying the URL of the response.@meta
data.HTTP.
response.headers
– AnNSDictionary
object containing all HTTP headers and values for the response.
Please refer to the documentation accompanying RKMappingOperation
for more details on metadata mapping.
Tasks
Initializing a Response Mapping Operation
-
– initWithRequest:response:data:responseDescriptors:
Initializes and returns a newly created response mapper operation with the given request, HTTP response, response data, and an array of
RKResponseDescriptor
objects.
Accessing HTTP Request and Response Data
-
request
An request object for which the response was loaded.
property -
response
The response object that loaded the data that is to be object mapped by the operation. Cannot be
propertynil
. -
data
The response data that is to be deserialized and mapped by the operation. May be
propertynil
.
Configuring Object Mapping
-
responseDescriptors
An array of
propertyRKResponseDescriptor
objects that specify object mapping configurations that may be applied to the deserialized response data if they are found to match the response. -
targetObject
The target object for the object mapping operation performed on the deserialized response data. May be
propertynil
. -
mapperDelegate
The delegate for the
propertyRKMapperOperation
created by the receiver to perform object mapping on the deserialized response data. May benil
. -
mappingMetadata
An optional dictionary of metadata to make available to mapping operations executed by the receiver.
property -
treatsEmptyResponseAsSuccess
A Boolean value that indicates if the receiver should consider empty responses as being successfully mapped even though no mapping is actually performed.
property -
responseMappingsDictionary
Returns a dictionary of key path to
propertyRKMapping
objects that are applicable to mapping the response. This is determined by evaluating the URL and status codes of the response against the set ofresponseDescriptors
. -
matchingResponseDescriptors
Returns an array containing all
propertyRKResponseDescriptor
objects in the configuredresponseDescriptors
array that were found to match the response.
Accessing Mapping Results
-
mappingResult
The results of performing object mapping on the deserialized response data. In the event that the operation has failed, the value will is
propertynil
. -
error
The error, if any, that occured during execution of the operation.
property
Manipulating the Mappable Data
-
– setWillMapDeserializedResponseBlock:
Sets a block to be executed before the response mapper operation begins mapping the deserialized response body, providing an opportunity to manipulate the mappable representation input before mapping begins.
Properties
data
The response data that is to be deserialized and mapped by the operation. May be nil
.
@property (nonatomic, strong, readonly) NSData *data
Declared In
RKResponseMapperOperation.h
error
The error, if any, that occured during execution of the operation.
@property (nonatomic, strong, readonly) NSError *error
Declared In
RKResponseMapperOperation.h
mapperDelegate
The delegate for the RKMapperOperation
created by the receiver to perform object mapping on the deserialized response data. May be nil
.
@property (nonatomic, weak) id<RKMapperOperationDelegate> mapperDelegate
Discussion
The delegate provides access to the details of the mapping process as it is executing. Be aware that the delegate will be invoked from the thread on which the mapping is executing.
Declared In
RKResponseMapperOperation.h
mappingMetadata
An optional dictionary of metadata to make available to mapping operations executed by the receiver.
@property (nonatomic, copy) NSDictionary *mappingMetadata
Declared In
RKResponseMapperOperation.h
mappingResult
The results of performing object mapping on the deserialized response data. In the event that the operation has failed, the value will is nil
.
@property (nonatomic, strong, readonly) RKMappingResult *mappingResult
Discussion
The keyPath
of each RKResponseDescriptor
from the responseDescriptors
set that was successfully mapped from the response data will appear as an entry in the mapping result.
Declared In
RKResponseMapperOperation.h
matchingResponseDescriptors
Returns an array containing all RKResponseDescriptor
objects in the configured responseDescriptors
array that were found to match the response.
@property (nonatomic, strong, readonly) NSArray *matchingResponseDescriptors
Declared In
RKResponseMapperOperation.h
request
An request object for which the response was loaded.
@property (nonatomic, strong, readonly) NSURLRequest *request
Declared In
RKResponseMapperOperation.h
response
The response object that loaded the data that is to be object mapped by the operation. Cannot be nil
.
@property (nonatomic, strong, readonly) NSHTTPURLResponse *response
Declared In
RKResponseMapperOperation.h
responseDescriptors
An array of RKResponseDescriptor
objects that specify object mapping configurations that may be applied to the deserialized response data if they are found to match the response.
@property (nonatomic, strong, readonly) NSArray *responseDescriptors
Declared In
RKResponseMapperOperation.h
responseMappingsDictionary
Returns a dictionary of key path to RKMapping
objects that are applicable to mapping the response. This is determined by evaluating the URL and status codes of the response against the set of responseDescriptors
.
@property (nonatomic, strong, readonly) NSDictionary *responseMappingsDictionary
Declared In
RKResponseMapperOperation.h
targetObject
The target object for the object mapping operation performed on the deserialized response data. May be nil
.
@property (nonatomic, strong) id targetObject
Discussion
When object mapping is being performed against a known object, the targetObject is set to ensure that the mapping is applied to the appropriate object reference. When nil
, the mapping operation will result in the fetching or creation of new objects as necessary to satisfy the mapping configuration.
Declared In
RKResponseMapperOperation.h
treatsEmptyResponseAsSuccess
A Boolean value that indicates if the receiver should consider empty responses as being successfully mapped even though no mapping is actually performed.
@property (nonatomic, assign) BOOL treatsEmptyResponseAsSuccess
Discussion
When YES
and the response data is empty (see below), a mapping result will be returned containing the target object (if any). Otherwise, the response data will be pass through to the parser which may generate an error.
Default: YES
Warning: To support the Ruby on Rails behavior of rendering a single space character on invocation of render :nothing => true
, a response body’s containing only a single space is treated as empty.
Declared In
RKResponseMapperOperation.h
Instance Methods
initWithRequest:response:data:responseDescriptors:
Initializes and returns a newly created response mapper operation with the given request, HTTP response, response data, and an array of RKResponseDescriptor
objects.
- (id)initWithRequest:(NSURLRequest *)request response:(NSHTTPURLResponse *)response data:(NSData *)data responseDescriptors:(NSArray *)responseDescriptors
Parameters
- response
The HTTP response object to be used for object mapping.
- responseDescriptors
An array whose elements are
RKResponseDescriptor
objects specifying object mapping configurations that may be applied to the response.
Declared In
RKResponseMapperOperation.h
setWillMapDeserializedResponseBlock:
Sets a block to be executed before the response mapper operation begins mapping the deserialized response body, providing an opportunity to manipulate the mappable representation input before mapping begins.
- (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 thedeserializedResponseBody
block argument. Returningnil
will decline the mapping from proceeding and fail the operation with an error with theRKMappingErrorMappingDeclined
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
RKResponseMapperOperation.h