Overview

The RKDynamicMapping class is an RKMapping subclass that provides an interface for deferring the decision about how a given object representation is to be mapped until run time. This enables many interesting mapping strategies, such as mapping similarly structured data differently and constructing object mappings at run time by examining the data being mapped.

Configuring Mapping Selection

Dynamic mappings support the selection of the concrete object mapping in one of two ways:

1. Through the use of a mapping selection block configured by setObjectMappingForRepresentationBlock:. When configured, the block is called with a reference to the current object representation being mapped and is expected to return an RKObjectMapping object. Returning nil declines the mapping of the representation.
2. Through the configuration of one of more RKObjectMappingMatcher objects. The matchers are consulted in registration order and the first matcher to return an object mapping is used to map the matched representation.

When both a mapping selection block and matchers are configured on a RKDynamicMapping object, the matcher objects are consulted first and if none match, the selection block is invoked.

Using Matcher Objects

The RKObjectMappingMatcher class provides an interface for evaluating a key path or predicate based match and returning an appropriate object mapping. Matchers can be added to the RKDynamicMapping objects to declaratively describe a particular mapping strategy.

For example, suppose that we have a JSON fragment for a person that we want to map differently based on the gender of the person. When the gender is ‘male’, we want to use the Boy class and when then the gender is ‘female’ we want to use the Girl class. The JSON might look something like this:

[ { "name": "Blake", "gender": "male" }, { "name": "Sarah", "gender": "female" } ]

We might define configure the dynamic mapping like so:

RKDynamicMapping *mapping = [RKDynamicMapping new];
RKObjectMapping *boyMapping = [RKObjectMapping mappingForClass:[Boy class]];
RKObjectMapping *girlMapping = [RKObjectMapping mappingForClass:[Girl class]];
[mapping addMatcher:[RKObjectMappingMatcher matcherWithKeyPath:@"gender" expectedValue:@"male" objectMapping:boyMapping]];
[mapping addMatcher:[RKObjectMappingMatcher matcherWithKeyPath:@"gender" expectedValue:@"female" objectMapping:girlMapping]];

When evaluated, the matchers will invoke valueForKeyPath:@"gender" against each dictionary in the array of object representations and apply the appropriate object mapping for each representation. This would return a mapping result containing an array of two objects, one an instance of the Boy class and the other an instance of the Girl class.

HTTP Integration

Dynamic mappings can be used to map HTTP requests and responses by adding them to an RKRequestDescriptor or RKResponseDescriptor objects.