Inherits from NSObject
Declared in RKMappingOperation.h

Overview

Instances of RKMappingOperation perform transformation between object representations according to the rules expressed in RKObjectMapping objects. Mapping operations provide the foundation for the RestKit object mapping engine and perform the work of inspecting the attributes and relationships of a source object and determining how to map them into new representations on a destination object.

Metadata Mapping

The mapping operation provides support for mapping for a dictionary of metadata in addition to the source object. This metadata is made available by mapping key paths nested under a specially designated parent key that cannot exist in a source representation. By convention, metadata is typically nested under sub keys to effectively namespace usage between components. The object mapping engine itself reserves the ‘mapping’ key for its usage. Metadata is passed down through a hierarchy of mapping operations (i.e. as relationships are traversed), making a common set of ancillary information available for mapping for by any operation executed.

To understand how metadata works, consider the following example:

@interface RKMetadataExample : NSObject
@property (nonatomic, copy) NSString *name;
@property (nonatomic, copy) NSURL *URL;
@property (nonatomic, copy) NSDate *mappedAt;
@end

RKMetadataExample *example = [RKMetadataExample new];
NSDictionary *representation = @{ @"name": @"Blake Watters" };
NSDictionary *metadata = @{ @"URL": [NSURL URLWithString:@"http://restkit.org"] };

RKObjectMapping *objectMapping = [RKObjectMapping mappingForClass:[RKMetadataExample class]];
[objectMapping addAttributeMappingsFromDictionary:@{ @"name": @"name", @"@metadata.URL": @"URL" }];

RKMappingOperation *mappingOperation = [[RKMappingOperation alloc] initWithSourceObject:representation destinationObject:example mapping:objectMapping];
mappingOperation.metadata = metadata;

NSError *error = nil;
BOOL success = [mappingOperation execute:&error];

Note the use of the special key path @"@metadata.URL". The @metadata prefix indicates that the property is to be mapped from the metadata dictionary instead of from the source object representation. If any relationships were mapped, it would have access to this same metadata information as well.

In addition to any metadata provided to the mapping operation via the metadata property, the operation itself makes the following metadata key paths available for mapping:

  1. @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.
  2. @metadata.mapping.parentObject - The direct parent object of the object that is currently being mapped. This key is only available for objects that are mapped as relationships of a parent object.

Traversing the Representation Hierarchy

In certain mapping scenarios it can become desirable to access ancestors of the current source object. For example, consider the following example JSON:

{
    "user": {
        "id": 1,
        "name": "Blake Watters",
        "preferences": [
            {
                { 
                    "name": "push_notifications_enabled",
                    "value": true,
                },
                {
                    "name": "subscribed_to_mailing_list",
                    "value": false
                }
            }
        ]
    }
}

And it’s corresponding model:

@interface RKPreferenceExample : NSObject
@property (nonatomic, strong) NSNumber *userID;
@property (nonatomic, copy) NSString *name;
@property (nonatomic, strong) id value;
@end

Notice that userID is a field that we wish to model as part of our local RKPreferenceExample class, but its not available within the @"preferences" key path that our mapping will target. In this case we’d up like to reach “up” in the parsed JSON hierarchy to access our parent node, as demonstrated in the following mapping:

RKObjectMapping *objectMapping = [RKObjectMapping mappingForClass:[RKPreferenceExample class]];
[objectMapping addAttributeMappingsFromDictionary:@{ @"name": @"name", @"value": @"value", @"@parent.id": @"userID" }];

Note the use of the @parent key in the final attribute mapping: this pseudo-key always points to the direct parent node of the representation being mapped (or nil if there is none). Parent access can be chained to traverse upward all the way to the root node of the representation.

Representation Traversal Keys

There are currently two keys provided for traversing the representation hierarchy:

  1. @"root" - Returns the root node of the representation being mapped. When a large JSON document is being mapped by an instance of RKMapperOperation this will point to the parsed JSON document that was used to initialize the operation.
  2. @"parent" - Returns the direct parent node of the sourceObject being mapped or nil if the sourceObject is itself a root node.

Tasks

Initializing a Mapping Operation

Accessing Mapping Configuration

  •   sourceObject

    A dictionary of mappable elements containing simple values or nested object structures.

    property
  •   destinationObject

    The target object for this operation. Mappable values in the source object will be applied to the destination object using key-value coding.

    property
  •   newDestinationObject

    Property which is YES when the destinationObject was provided from the data source, and NO when the destination object was provided externally to the operation.

    property
  •   mapping

    The mapping defining how values contained in the source object should be transformed to the destination object via key-value coding.

    property
  •   objectMapping

    The concrete object mapping for the operation.

    property
  •   metadataList

    A list of metadata objects available for mapping in addition to the source object.

    property

Configuring Delegate and Data Source

Accessing Mapping Details

  •   error

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

    property
  •   mappingInfo

    Returns a dictionary containing information about the mappings applied during the execution of the operation. The keys of the dictionary are key paths into the destinationObject for values that were mapped and the values are instances of RKMappingDetails that specify the object mapping and property mappings that were applied.

    property
  •   cancelled

    Property to indicate whether this operation has been cancelled or not. It will be NO until cancel is called, after which it will return YES.

    property
  • – cancel

    Cancels the operation, by setting the cancelled property to YES. Various steps of the process check the cancelled property and will abort when it gets set.

Performing Mapping

  • – start

    Process all mappable values from the mappable dictionary and assign them to the target object according to the rules expressed in the object mapping definition. The error properties need to be checked to see if the operation was successful.

  • – performMapping:

    Process all mappable values from the mappable dictionary and assign them to the target object according to the rules expressed in the object mapping definition.

Properties

cancelled

@property (nonatomic, readonly, getter=isCancelled) BOOL cancelled
Discussion

Property to indicate whether this operation has been cancelled or not. It will be NO until cancel is called, after which it will return YES.

Declared In

RKMappingOperation.h

dataSource

@property (nonatomic, weak) id<RKMappingOperationDataSource> dataSource
Discussion

The data source is responsible for providing the mapping operation with an appropriate target object for mapping when the destinationObject is nil.

Declared In

RKMappingOperation.h

delegate

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

The delegate to inform of interesting events during the mapping operation lifecycle.

Declared In

RKMappingOperation.h

destinationObject

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

The target object for this operation. Mappable values in the source object will be applied to the destination object using key-value coding.

If initialized with a nil destination object, the mapping operation will attempt to find or create a destination object via the data source and will populate the value of the destinationObject property.

Declared In

RKMappingOperation.h

error

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

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

Declared In

RKMappingOperation.h

mapping

@property (nonatomic, strong, readonly) RKMapping *mapping
Discussion

The mapping defining how values contained in the source object should be transformed to the destination object via key-value coding.

Will either be an instance of RKObjectMapping or RKDynamicMapping.

Declared In

RKMappingOperation.h

mappingInfo

@property (nonatomic, readonly) RKMappingInfo *mappingInfo
Discussion

Returns a dictionary containing information about the mappings applied during the execution of the operation. The keys of the dictionary are key paths into the destinationObject for values that were mapped and the values are instances of RKMappingDetails that specify the object mapping and property mappings that were applied.

Mapping info is aggregated for all child mapping operations executed for relationships.

Declared In

RKMappingOperation.h

metadataList

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

A list of metadata objects available for mapping in addition to the source object.

Declared In

RKMappingOperation.h

newDestinationObject

@property (nonatomic, readonly, getter=isNewDestinationObject) BOOL newDestinationObject
Discussion

Property which is YES when the destinationObject was provided from the data source, and NO when the destination object was provided externally to the operation.

Declared In

RKMappingOperation.h

objectMapping

@property (nonatomic, strong, readonly) RKObjectMapping *objectMapping
Discussion

The concrete object mapping for the operation.

If the value of mapping is an RKObjectMapping, returns the same value as mapping. If mapping is an RKDynamicMapping, then returns the concrete RKObjectMapping object selected for mapping sourceObject.

Declared In

RKMappingOperation.h

sourceObject

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

A dictionary of mappable elements containing simple values or nested object structures.

Declared In

RKMappingOperation.h

Instance Methods

cancel

- (void)cancel
Discussion

Cancels the operation, by setting the cancelled property to YES. Various steps of the process check the cancelled property and will abort when it gets set.

Declared In

RKMappingOperation.h

initWithSourceObject:destinationObject:mapping:

- (instancetype)initWithSourceObject:(id)sourceObject destinationObject:(id)destinationObject mapping:(RKMapping *)objectOrDynamicMapping
Discussion

Initializes the receiver with a source object, a destination object and an object mapping with which to perform an object mapping.

Parameters

sourceObject

The source object to be mapped. Cannot be nil.

destinationObject

The destination object the results are to be mapped onto. May be nil, in which case a new object target object will be obtained from the dataSource.

objectOrDynamicMapping

An instance of RKObjectMapping or RKDynamicMapping defining how the mapping is to be performed.

Return Value

The receiver, initialized with a source object, a destination object, and a mapping.

Declared In

RKMappingOperation.h

initWithSourceObject:destinationObject:mapping:metadataList:

- (instancetype)initWithSourceObject:(id)sourceObject destinationObject:(id)destinationObject mapping:(RKMapping *)objectOrDynamicMapping metadataList:(NSArray *)metadataList
Discussion

Initializes the receiver with a source object, a destination object and an object mapping with which to perform an object mapping, and metadata information to be made available to the mapping.

Parameters

sourceObject

The source object to be mapped. Cannot be nil.

destinationObject

The destination object the results are to be mapped onto. May be nil, in which case a new object target object will be obtained from the dataSource.

objectOrDynamicMapping

An instance of RKObjectMapping or RKDynamicMapping defining how the mapping is to be performed.

metadataList

A list of objects (usually dictionaries) which provide metadata to the operation, available via the @metadata key in mapping paths. Each object should respond to -valueForKeyPath:, and return nil if the requested key path is not represented in the object (in which case the following object in the list will be consulted).

Return Value

The receiver, initialized with a source object, a destination object, and a mapping.

Declared In

RKMappingOperation.h

performMapping:

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

Process all mappable values from the mappable dictionary and assign them to the target object according to the rules expressed in the object mapping definition.

Parameters

error

A pointer to an NSError reference to capture any error that occurs during the mapping. May be nil.

Return Value

A Boolean value indicating if the mapping operation was successful.

Declared In

RKMappingOperation.h

start

- (void)start
Discussion

Process all mappable values from the mappable dictionary and assign them to the target object according to the rules expressed in the object mapping definition. The error properties need to be checked to see if the operation was successful.

Declared In

RKMappingOperation.h