RestKit/Code/ObjectMapping/RKObjectMappingProvider.h

//
//  RKObjectMappingProvider.h
//  RestKit
//
//  Created by Jeremy Ellison on 5/6/11.
//  Copyright 2011 RestKit
//  
//  Licensed under the Apache License, Version 2.0 (the "License");
//  you may not use this file except in compliance with the License.
//  You may obtain a copy of the License at
//  
//  http://www.apache.org/licenses/LICENSE-2.0
//  
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
//

#import "RKObjectMapping.h"
#import "RKDynamicObjectMapping.h"

/**
 The mapping provider is a repository of registered object mappings for use by instances
 of RKObjectManager and RKObjectMapper. It provides for the storage and retrieval of object
 mappings by keyPath and type.
 
 The mapping provider is responsible for:
    
 1. Providing instances of RKObjectMapper with keyPaths and object mappings for use 
    when attempting to map a parsed payload into objects. Each keyPath is examined using
    valueForKeyPath: to determine if any mappable data exists within the payload. If data is
    found, the RKObjectMapper will instantiate an RKObjectMappingOperation to perform the mapping
    using the RKObjectMapping or RKDynamicObjectMapping associated with the keyPath.
 1. Providing the appropriate serialization mapping to instances of RKObjectManager when an object
    is to be sent to the remote server using [RKObjectManager postObject:delegate:] or 
    [RKObjectManager postObject:delegate]. This mapping is used to serialize the object into a 
    format suitable for encoding into a URL form encoded or JSON representation.
 1. Providing convenient storage of RKObjectMapping references for users who are not using keyPath
    based mapping. Mappings can be added to the provider and retrieved by the [RKObjectMapping objectClass]
    that they target.
 */
@interface RKObjectMappingProvider : NSObject {
    NSMutableArray *_objectMappings;
    NSMutableDictionary *_mappingsByKeyPath;
    NSMutableDictionary *_serializationMappings;
}

/**
 Returns a new auto-released mapping provider
 */
+ (RKObjectMappingProvider *)mappingProvider;

/**
 Instructs the mapping provider to use the mapping provided when it encounters content at the specified
 key path
 */
- (void)setMapping:(id<RKObjectMappingDefinition>)objectOrDynamicMapping forKeyPath:(NSString *)keyPath;

/**
 Returns the RKObjectMapping or RKObjectDynamic mapping configured for use 
 when mappable content is encountered at keyPath
 */
- (id<RKObjectMappingDefinition>)mappingForKeyPath:(NSString *)keyPath;

/**
 Removes a currently registered 
 */
- (void)removeMappingForKeyPath:(NSString *)keyPath;

/**
 Returns a dictionary where the keys are mappable keyPaths and the values are the RKObjectMapping
 or RKObjectDynamic mappings to use for mappable data that appears at the keyPath.
 */
- (NSDictionary *)mappingsByKeyPath;

/**
 Registers an object mapping as being rooted at a specific keyPath. The keyPath will be registered
 and an inverse mapping for the object will be generated and used for serialization. 
 
 This is a shortcut for configuring a pair of object mappings that model a simple resource the same
 way when going to and from the server.
 
 For example, if we configure have a simple resource called 'person' that returns JSON in the following
 format:
 
    { "person": { "first_name": "Blake", "last_name": "Watters" } }
 
 We might configure a mapping like so:
    
    RKObjectMapping* mapping = [RKObjectMapping mappingForClass:[Person class]];
    [mapping mapAttributes:@"first_name", @"last_name", nil];
 
 If we want to parse the above JSON and serialize it such that using postObject: or putObject: use the same format,
 we can auto-generate the serialization mapping and set the whole thing up in one shot:
 
    [[RKObjectManager sharedManager].mappingProvider registerMapping:mapping withRootKeyPath:@"person"];
 
 This will call setMapping:forKeyPath: for you, then generate a serialization mapping and set the root
 keyPath as well.
 
 If you want to manipulate the serialization mapping yourself, you can work with the mapping directly:
 
    RKObjectMapping* serializationMappingForPerson = [personMapping inverseMapping];
    // NOTE: Serialization mapping default to a nil root keyPath and will serialize to a flat dictionary
    [[RKObjectManager sharedManager].mappingProvider setSerializationMapping:serializationMappingForPerson forClass:[Person class]];
 */
- (void)registerMapping:(RKObjectMapping *)objectMapping withRootKeyPath:(NSString *)keyPath;

/**
 Adds an object mapping to the provider for later retrieval. The mapping is not bound to a particular keyPath and
 must be explicitly set on an instance of RKObjectLoader or RKObjectMappingOperation to be applied. This is useful
 in cases where the remote system does not namespace resources in a keyPath that can be used for disambiguation.
 
 You can retrieve mappings added to the provider by invoking objectMappingsForClass: and objectMappingForClass:
 
 @see objectMappingsForClass:
 @see objectMappingForClass:
 */
- (void)addObjectMapping:(RKObjectMapping *)objectMapping;

/**
 Returns all object mappings registered for a particular class on the provider. The collection of mappings is assembled
 by searching for all mappings added via addObjctMapping: and then consulting those registered via objectMappingForKeyPath:
 */
- (NSArray *)objectMappingsForClass:(Class)theClass;

/**
 Returns the first object mapping for a particular class in the provider. Mappings registered via addObjectMapping: take
 precedence over those registered via setObjectMapping:forKeyPath:
 */
- (RKObjectMapping *)objectMappingForClass:(Class)theClass;

/**
 Set a mapping to serialize objects of a specific class into a representation
 suitable for transport over HTTP. Used by the object manager during postObject: and putObject:
 */
- (void)setSerializationMapping:(RKObjectMapping *)mapping forClass:(Class)objectClass;

/**
 returns the serialization mapping for a specific object class
 which has been previously registered.
 */
- (RKObjectMapping *)serializationMappingForClass:(Class)objectClass;

////////////////////////////////////////////////////////////////////////////////////
/// @name Deprecated Object Mapping Methods

/**
 Configure an object mapping to handle data that appears at a particular keyPath in
 a payload loaded from a 
 
 @deprecated
 */
- (void)setObjectMapping:(RKObjectMapping *)mapping forKeyPath:(NSString *)keyPath DEPRECATED_ATTRIBUTE;

/**
 Returns the object mapping to use for mapping the specified keyPath into an object graph
 
 @deprecated
 */
- (RKObjectMapping *)objectMappingForKeyPath:(NSString *)keyPath DEPRECATED_ATTRIBUTE;

/**
 Returns a dictionary where the keys are mappable keyPaths and the values are the object
 mapping to use for objects that appear at the keyPath.
 
 @deprecated
 */
- (NSDictionary *)objectMappingsByKeyPath DEPRECATED_ATTRIBUTE;

@end