Inherits from NSOperation
Declared in RKMapperOperation.h

Overview

RKMapperOperation is an NSOperation subclass that implements object mapping for opaque object representations. Given a dictionary or an array of dictionaries that represent objects and a dictionary describing how to map the representations, the mapper will transform the source representations into NSObject or NSManagedObject instances. Mapper operations are used to map object representations from Foundation object representations, such as those deserialized from a JSON or XML document or loaded from a file. Not all the mappings specified in the mappings dictionary are required to match content in the source object for the operation to succeed. However, if none of the mappable key paths in the mappings dictionary match the source object then the operation will fail and the error property will be set to an NSError object in the RKErrorDomain domain with an error code value of RKMappingErrorNotFound.

RKMapperOperation does not actually perform any mapping work. Instead, it instantiates and starts RKMappingOperation objects to process the mappable object representations it encounters.

RKMapperOperation is a non-concurrent operation. Execution will occur synchronously on the calling thread unless the operation is enqueued onto an NSOperationQueue.

Mappings Dictionary

The mappings dictionary describes how to object map the source object. The keys of the dictionary are key paths into the representation and the values are RKMapping objects describing how to map the representations at the corresponding key path. This dictionary based approach enables a single document to contain an arbitrary number of object representations that can be mapped independently. Consider the following example JSON structure:

{ "tags": [ "hacking", "phreaking" ], "authors": [ "Captain Crunch", "Emmanuel Goldstein" ], "magazine": { "title": "2600 The Hacker Quarterly" } }

Each key in the document could be mapped independently by providing a mapping for the key paths:

RKObjectMapping *tagMapping = [RKObjectMapping mappingForClass:[Tag class]];
RKObjectMapping *authorMapping = [RKObjectMapping mappingForClass:[Author class]];
RKObjectMapping *magazineMapping = [RKObjectMapping mappingForClass:[Magazine class]];
NSDictionary *mappingsDictionary = @{ @"tag": tagMapping, @"author": authorMapping, @"magazine": magazine };

Note that the keys of the dictionary are key paths. Deeply nested content can be mapped by specifying the full key path as the key of the mappings dictionary.

Mapping the Root Object Representation

A mapping set for the key [NSNull null] value has special significance to the mapper operation. When a mapping is encountered with the a null key, the entire representation is processed using the given mapping. This provides support for mapping content that does not have an outer nesting attribute.

Note that it is possible to map the same representation with multiple mappings, including a combination of a root key mapping and nested keypaths.

Data Source

The data source is used to instantiate new objects or find existing objects to be updated during the mapping process. The object set as the mappingOperationDataSource will be set as the dataSource for the RKMappingOperation objects created by the mapper.

Target Object

If a targetObject is configured on the mapper operation, all mapping work on the representation will target the specified object. For transient NSObject mappings, this ensures that the properties of an existing object are updated rather than an new object being created for the mapped representation. If an array of representations is being processed and a targetObject is provided, it must be a mutable collection object else an exception will be raised.

Metadata Mapping

The RKMapperOperation class provides support for metadata mapping provided to the operation via the mappingMetadata property. This dictionary is made available to all RKMappingOperation objects executed by the receiver to process the representation being mapped. In addition to any user supplied metadata, the mapper operation makes the following metadata key paths available for mapping:

  1. @metadata.mapping.rootKeyPath - An object specifying the root key path at which the current representation is nested within the source representation. This will correspond to a key in the mappingsDictionary and is typically an NSString, but can be [NSNull null] if the representation being mapped is at the root.
  2. @metadata.mapping.collectionIndex - An NSNumber object specifying the index of the current object within a collection being mapped. This key is only available if the current representation exists within a collection.

Please refer to the documentation accompanying RKMappingOperation for more details on metadata mapping.

Core Data

RKMapperOperation supports mapping to Core Data target entities. To do so, it must be configured with an RKManagedObjectMappingOperationDataSource object as the data source.

Tasks

Initializing a Mapper Operation

Accessing Mapping Result and Errors

  •   error

    The error, if any, that occurred during the mapping process.

    property
  •   mappingResult

    The result of the mapping process. A nil value indicates that no mappable object representations were found and no mapping was performed.

    property
  •   mappingInfo

    Returns a dictionary containing information about the mappings applied during the execution of the operation. The keys of the dictionary are keyPaths into the mappingResult for values that were mapped and the values are the corresponding RKPropertyMapping objects used to perform the mapping.

    property

Managing Mapping Configuration

Executing the Operation

Private Methods

Properties

delegate

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

The delegate for the mapper operation.

Declared In

RKMapperOperation.h

error

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

The error, if any, that occurred during the mapping process.

Declared In

RKMapperOperation.h

mappingInfo

@property (nonatomic, readonly) NSDictionary *mappingInfo
Discussion

Returns a dictionary containing information about the mappings applied during the execution of the operation. The keys of the dictionary are keyPaths into the mappingResult for values that were mapped and the values are the corresponding RKPropertyMapping objects used to perform the mapping.

Declared In

RKMapperOperation.h

mappingOperationDataSource

@property (nonatomic, strong) id<RKMappingOperationDataSource> mappingOperationDataSource
Discussion

The data source for the underlying RKMappingOperation objects that perform the mapping work configured by the mapper.

Declared In

RKMapperOperation.h

mappingResult

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

The result of the mapping process. A nil value indicates that no mappable object representations were found and no mapping was performed.

Declared In

RKMapperOperation.h

mappingsDictionary

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

A dictionary of key paths to RKMapping objects specifying how object representations in the representation are to be mapped.

Please see the above discussion for in-depth details about the mappings dictionary.

Declared In

RKMapperOperation.h

metadata

@property (nonatomic, copy) NSDictionary *metadata
Discussion

A dictionary of metadata that is available for mappping by any mapping operation started by the receiver.

Declared In

RKMapperOperation.h

representation

@property (nonatomic, strong, readonly) id representation
Discussion

The representation of one or more objects against which the mapping is performed.

Either an NSDictionary or an NSArray of NSDictionary objects.

Declared In

RKMapperOperation.h

targetObject

@property (nonatomic, weak) id targetObject
Discussion

The target object of the mapper. When configured, all object mapping will target the specified object.

Please see the above discussion for details about target objects.

Declared In

RKMapperOperation.h

Instance Methods

execute:

- (BOOL)execute:(NSError **)error
Discussion

Executes the mapper operation to completion.

Parameters

error

A pointer to an NSError object to set in the event an error occurs during execution.

Return Value

A Boolean value that indicates if the operation completed successfully.

Declared In

RKMapperOperation.h

initWithRepresentation:mappingsDictionary:

- (instancetype)initWithRepresentation:(id)representation mappingsDictionary:(NSDictionary *)mappingsDictionary
Discussion

Initializes the operation with a source object and a mappings dictionary.

Parameters

representation

An NSDictionary or NSArray of NSDictionary object representations to be mapped into local domain objects.

mappingsDictionary

An NSDictionary wherein the keys are mappable key paths in object and the values are RKMapping objects specifying how the representations at its key path are to be mapped.

Return Value

The receiver, initialized with the given object and and dictionary of key paths to mappings.

Declared In

RKMapperOperation.h

mapRepresentation:atKeyPath:usingMapping:

- (id)mapRepresentation:(id)mappableObject atKeyPath:(NSString *)keyPath usingMapping:(RKMapping *)mapping

mapRepresentation:toObject:isNew:atKeyPath:usingMapping:metadataList:

- (BOOL)mapRepresentation:(id)mappableObject toObject:(id)destinationObject isNew:(BOOL)isNew atKeyPath:(NSString *)keyPath usingMapping:(RKMapping *)mapping metadataList:(NSArray *)metadata

mapRepresentations:atKeyPath:usingMapping:

- (NSArray *)mapRepresentations:(NSArray *)mappableObjects atKeyPath:(NSString *)keyPath usingMapping:(RKMapping *)mapping

objectForRepresentation:withMapping:

- (id)objectForRepresentation:(id)representation withMapping:(RKMapping *)mapping