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:

  1. 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 the RKErrorDomain is created with the NSURLErrorBadServerResponse 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 of treatsEmptyResponseAsSuccess. When YES, empty responses result in the successful completion of the operation with an RKMappingResult containing the targetObject of the operation, if any.
  2. 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:

  1. @metadata.HTTP.request.URL - The NSURL object identifying the URL of the request that loaded the response.
  2. @metadata.HTTP.request.method - An NSString specifying the HTTP method of the request that loaded the response.
  3. @metadata.HTTP.request.headers - An NSDictionary object containing all HTTP headers and values for the request that loaded the response.
  4. @metadata.HTTP.response.URL - The NSURL object identifying the URL of the response.
  5. @metadata.HTTP.response.headers - An NSDictionary 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

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 nil.

    property
  •   data

    The response data that is to be deserialized and mapped by the operation. May be nil.

    property

Configuring Object Mapping

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 nil.

    property
  •   error

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

    property

Configuring Callbacks

  • – 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.

  • – setDidFinishMappingBlock:

    Sets a block to be executed when the response mapper operation has completed its mapping activities. This method is distinct from the completionBlock because it is invoked while the operation is still executing. This block is guaranteed to be called even if the receiver is cancelled before it has been started.

Registering a Mapping Operation Data Source Class

Properties

data

@property (nonatomic, strong, readonly) NSData *data
Discussion

The response data that is to be deserialized and mapped by the operation. May be nil.

Declared In

RKResponseMapperOperation.h

error

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

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

Declared In

RKResponseMapperOperation.h

mapperDelegate

@property (nonatomic, weak) id<RKMapperOperationDelegate> mapperDelegate
Discussion

The delegate for the RKMapperOperation created by the receiver to perform object mapping on the deserialized response data. May be nil.

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

@property (nonatomic, copy) NSDictionary *mappingMetadata
Discussion

An optional dictionary of metadata to make available to mapping operations executed by the receiver.

Declared In

RKResponseMapperOperation.h

mappingResult

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

The results of performing object mapping on the deserialized response data. In the event that the operation has failed, the value will is nil.

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

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

Returns an array containing all RKResponseDescriptor objects in the configured responseDescriptors array that were found to match the response.

Declared In

RKResponseMapperOperation.h

request

@property (nonatomic, strong, readonly) NSURLRequest *request
Discussion

An request object for which the response was loaded.

Declared In

RKResponseMapperOperation.h

response

@property (nonatomic, strong, readonly) NSHTTPURLResponse *response
Discussion

The response object that loaded the data that is to be object mapped by the operation. Cannot be nil.

Declared In

RKResponseMapperOperation.h

responseDescriptors

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

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.

Declared In

RKResponseMapperOperation.h

responseMappingsDictionary

@property (nonatomic, strong, readonly) NSDictionary *responseMappingsDictionary
Discussion

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.

Declared In

RKResponseMapperOperation.h

targetObject

@property (nonatomic, strong) id targetObject
Discussion

The target object for the object mapping operation performed on the deserialized response data. May be nil.

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

@property (nonatomic, assign) BOOL treatsEmptyResponseAsSuccess
Discussion

A Boolean value that indicates if the receiver should consider empty responses as being successfully mapped even though no mapping is actually performed.

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

Class Methods

registerMappingOperationDataSourceClass:

+ (void)registerMappingOperationDataSourceClass:(Class<RKMappingOperationDataSource>)dataSourceClass
Discussion

Registers the given data source class to to be used for mapper operations constructed by instances of the receiver.

NOTE: The receiver class is significant to the registration: [RKObjectResponseMapperOperation registerMappingOperationDataSourceClass:[MyDataSourceClass class]] registers a data source for use with instances of RKObjectResponseMapperOperation exclusively. When registering a data source for RKManagedObjectResponseMapperOperation the given class must inherit from RKManagedObjectMappingOperationDataSource.

Parameters

dataSourceClass

The class conforming to the RKMappingOperationDataSource protocol to be registered for use with mapper operations.

Declared In

RKResponseMapperOperation.h

Instance Methods

initWithRequest:response:data:responseDescriptors:

- (instancetype)initWithRequest:(NSURLRequest *)request response:(NSHTTPURLResponse *)response data:(NSData *)data responseDescriptors:(NSArray *)responseDescriptors
Discussion

Initializes and returns a newly created response mapper operation with the given request, HTTP response, response data, and an array of RKResponseDescriptor objects.

Parameters

request

The request object for which the response was loaded.

response

The HTTP response object to be used for object mapping.

data

The data loaded for the response body.

responseDescriptors

An array whose elements are RKResponseDescriptor objects specifying object mapping configurations that may be applied to the response.

Return Value

The receiver, initialized with the response, data, and response descriptor objects.

Declared In

RKResponseMapperOperation.h

setDidFinishMappingBlock:

- (void)setDidFinishMappingBlock:(void ( ^ ) ( RKMappingResult *mappingResult , NSError *error ))block
Discussion

Sets a block to be executed when the response mapper operation has completed its mapping activities. This method is distinct from the completionBlock because it is invoked while the operation is still executing. This block is guaranteed to be called even if the receiver is cancelled before it has been started.

Parameters

block

A block object to be executed when the response mapping is finished. The block has no return value and accepts two arguments: an RKNappingResult object that was mapped from the response or an NSError error indicating that the mapping has failed.

Declared In

RKResponseMapperOperation.h

setWillMapDeserializedResponseBlock:

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

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.

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

RKResponseMapperOperation.h