RKMapperOperation Class Reference
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 sourceObject
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.
The NSNull Key
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 sourceObject
is processed using the given mapping. This provides support for mapping content that does not have an outer nesting attribute.
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 sourceObject
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.
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
-
– initWithObject:mappingsDictionary:
Initializes the operation with a source object and a mappings dictionary.
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
propertynil
value indicates that no mappable object representations were found and no mapping was performed.
Managing Mapping Configuration
-
sourceObject
The source object representation against which the mapping is performed.
property -
mappingsDictionary
A dictionary of key paths to
propertyRKMapping
objects specifying how object representations in thesourceObject
are to be mapped. -
targetObject
The target object of the mapper. When configured, all object mapping will target the specified object.
property -
mappingOperationDataSource
The data source for the underlying
propertyRKMappingOperation
objects that perform the mapping work configured by the mapper. -
delegate
The delegate for the mapper operation.
property
Properties
delegate
The delegate for the mapper operation.
@property (nonatomic, weak) id<RKMapperOperationDelegate> delegate
Declared In
RKMapperOperation.h
error
The error, if any, that occurred during the mapping process.
@property (nonatomic, strong, readonly) NSError *error
Declared In
RKMapperOperation.h
mappingOperationDataSource
The data source for the underlying RKMappingOperation
objects that perform the mapping work configured by the mapper.
@property (nonatomic, strong) id<RKMappingOperationDataSource> mappingOperationDataSource
Declared In
RKMapperOperation.h
mappingResult
The result of the mapping process. A nil
value indicates that no mappable object representations were found and no mapping was performed.
@property (nonatomic, strong, readonly) RKMappingResult *mappingResult
Declared In
RKMapperOperation.h
mappingsDictionary
A dictionary of key paths to RKMapping
objects specifying how object representations in the sourceObject
are to be mapped.
@property (nonatomic, strong, readonly) NSDictionary *mappingsDictionary
Discussion
Please see the above discussion for in-depth details about the mappings dictionary.
Declared In
RKMapperOperation.h
Instance Methods
initWithObject:mappingsDictionary:
Initializes the operation with a source object and a mappings dictionary.
- (id)initWithObject:(id)object mappingsDictionary:(NSDictionary *)mappingsDictionary
Parameters
- object
An
NSDictionary
orNSArray
ofNSDictionary
object representations to be mapped into local domain objects.
- mappingsDictionary
An
NSDictionary
wherein the keys are mappable key paths inobject
and the values areRKMapping
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