kylefang/RestKit
1
0
Fork 0
mirror of https://github.com/zhigang1992/RestKit.git synced 2026-05-06 17:32:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

Docs update. Eliminate mappingOperationFromObject:

Browse Source
This commit is contained in:
Blake Watters
2012-09-20 19:11:38 -04:00
parent bd4130a546
commit 7e816904ff
6 changed files with 65 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
Code/ObjectMapping/RKMapping.h
View File

@@ -19,38 +19,39 @@
//
/**
RKMapping is an abstract class for objects defining RestKit object mappings.
Its interface is common to all object mapping classes, including its concrete subclasses
RKObjectMapping and RKDynamicMapping.
`RKMapping` is an abstract class for objects defining RestKit object mappings. Its interface is common to all object mapping classes, including its concrete subclasses `RKObjectMapping` and `RKDynamicMapping`.
*/
@interface RKMapping : NSObject
///---------------------------------
/// @name Forcing Collection Mapping
///---------------------------------
/**
Forces the mapper to treat the mapped keyPath as a collection even if it does not
return an array or a set of objects. This permits mapping where a dictionary identifies
a collection of objects.
Forces the mapper to treat the mapped keyPath as a collection even if it does not return an array or a set of objects. This permits mapping where a dictionary identifies a collection of objects.
When enabled, each key/value pair in the resolved dictionary will be mapped as a separate
entity. This is useful when you have a JSON structure similar to:
When enabled, each key/value pair in the resolved dictionary will be mapped as a separate entity. This is useful when you have a JSON structure similar to:
{ "users":
{
"blake": { "id": 1234, "email": "blake@restkit.org" },
"rachit": { "id": 5678", "email": "rachit@restkit.org" }
}
}
{ "users": {
"blake": { "id": 1234, "email": "blake@restkit.org" },
"rachit": { "id": 5678", "email": "rachit@restkit.org" }
}
}
By enabling forceCollectionMapping, RestKit will map "blake" => attributes and
"rachit" => attributes as independent objects. This can be combined with
mapKeyOfNestedDictionaryToAttribute: to properly map these sorts of structures.
By enabling `forceCollectionMapping`, RestKit will map "blake" => attributes and "rachit" => attributes as independent objects. This can be combined with `mapKeyOfNestedDictionaryToAttribute:` to properly map these sorts of structures.
@default NO
@see mapKeyOfNestedDictionaryToAttribute
@default `NO`
@see `mapKeyOfNestedDictionaryToAttribute`
*/
@property (nonatomic, assign) BOOL forceCollectionMapping;
///-------------------------
/// @name Comparing Mappings
///-------------------------
/**
Returns YES if the receiver and the specified mapping are considered equivalent.
Returns `YES` if the receiver and the specified mapping are considered equivalent.
**NOTE**: Must be implemented in subclass.
*/

98
Code/ObjectMapping/RKMappingOperation.h
View File

@@ -25,28 +25,24 @@
@protocol RKMappingOperationDataSource;
/**
Objects acting as the delegate for RKMappingOperation objects must adopt the
RKMappingOperationDelegate protocol. These methods enable the delegate to be
notified of events such as the application of attribute and relationship mappings
during a mapping operation.
Objects acting as the delegate for `RKMappingOperation` objects must adopt the `RKMappingOperationDelegate` protocol. These methods enable the delegate to be notified of events such as the application of attribute and relationship mappings during a mapping operation.
*/
@protocol RKMappingOperationDelegate <NSObject>
@optional
/**
Tells the delegate that an attribute or relationship mapping was found for a given key
path within the data being mapped.
Tells the delegate that an attribute or relationship mapping was found for a given key path within the data being mapped.
@param operation The object mapping operation being performed.
@param mapping The RKAttributeMapping or RKRelationshipMapping found for the key path.
@param mapping The `RKAttributeMapping` or `RKRelationshipMapping` found for the key path.
@param keyPath The key path in the source object for which the mapping is to be applied.
*/
- (void)mappingOperation:(RKMappingOperation *)operation didFindMapping:(RKPropertyMapping *)mapping forKeyPath:(NSString *)keyPath;
// TODO: mappingOperation: willMapKeyPath: usingMapping: ???
/**
Tells the delegate that no attribute or relationships mapping was found for a given key
path within the data being mapped.
Tells the delegate that no attribute or relationships mapping was found for a given key path within the data being mapped.
@param operation The object mapping operation being performed.
@param keyPath The key path in the source object for which no mapping was found.
@@ -54,8 +50,7 @@
- (void)mappingOperation:(RKMappingOperation *)operation didNotFindMappingForKeyPath:(NSString *)keyPath;
/**
Tells the delegate that the mapping operation has set a value for a given key path with
an attribute or relationship mapping.
Tells the delegate that the mapping operation has set a value for a given key path with an attribute or relationship mapping.
@param operation The object mapping operation being performed.
@param value A new value that was set on the destination object.
@@ -65,8 +60,7 @@
- (void)mappingOperation:(RKMappingOperation *)operation didSetValue:(id)value forKeyPath:(NSString *)keyPath usingMapping:(RKPropertyMapping *)propertyMapping;
/**
Tells the delegate that the mapping operation has declined to set a value for a given
key path because the value has not changed.
Tells the delegate that the mapping operation has declined to set a value for a given key path because the value has not changed.
@param operation The object mapping operation being performed.
@param value A unchanged value for the key path in the destination object.
@@ -91,87 +85,75 @@
@param operation The mapping operation.
@param objectMapping The concrete object mapping with which to perform the mapping.
@param dynamicMapping The dynamic source mapping from which the object mapping was determined.
@since 0.11.0
*/
- (void)mappingOperation:(RKMappingOperation *)operation didSelectObjectMapping:(RKObjectMapping *)objectMapping forDynamicMapping:(RKDynamicMapping *)dynamicMapping;
@end
/**
Instances of RKMappingOperation perform transformation between object
representations according to the rules express 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.
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.
*/
@interface RKMappingOperation : NSObject
///---------------------------------------
/// @name Initializing a Mapping Operation
///---------------------------------------
/**
Initializes the receiver with a source object, a destination object and an object mapping with which to perform an object mapping.
@param sourceObject The source object to be mapped. Cannot be `nil`.
@param 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`.
@param objectOrDynamicMapping An instance of `RKObjectMapping` or `RKDynamicMapping` defining how the mapping is to be performed.
@return The receiver, initialized with a source object, a destination object, and a mapping.
*/
- (id)initWithSourceObject:(id)sourceObject destinationObject:(id)destinationObject mapping:(RKMapping *)objectOrDynamicMapping;
///--------------------------------------
/// @name Accessing Mapping Configuration
///--------------------------------------
/**
A dictionary of mappable elements containing simple values or nested object structures.
*/
@property (nonatomic, strong, readonly) id sourceObject;
/**
The target object for this operation. Mappable values in elements will be applied to object
using key-value coding.
The target object for this operation. Mappable values in elements will be applied to object using key-value coding.
*/
@property (nonatomic, strong, readonly) id destinationObject;
/**
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.
Will either be an instance of `RKObjectMapping` or `RKDynamicMapping`.
*/
@property (nonatomic, strong, readonly) RKMapping *mapping;
///-------------------------------------------
/// @name Configuring Delegate and Data Source
///-------------------------------------------
/**
The delegate to inform of interesting events during the mapping operation
The delegate to inform of interesting events during the mapping operation lifecycle.
*/
@property (nonatomic, weak) id<RKMappingOperationDelegate> delegate;
/**
The data source is responsible for providing the mapping operation with an appropriate target object for
mapping when the destination is nil.
The data source is responsible for providing the mapping operation with an appropriate target object for mapping when the `destinationObject` is `nil`.
@see RKMappingOperationDataSource
@see `RKMappingOperationDataSource`
*/
@property (nonatomic, weak) id<RKMappingOperationDataSource> dataSource;
/**
Creates and returns a new mapping operation configured to transform the object representation
in a source object to a new destination object according to an object mapping definition.
Note that if Core Data support is available, an instance of RKManagedObjectMappingOperation may be returned.
@param sourceObject The source object to be mapped. Cannot be nil.
@param destinationObject The destination object the results are to be mapped onto. May be nil,
in which case a new object will be constructed during the mapping.
@param objectOrDynamicMapping An instance of RKObjectMapping or RKDynamicMapping defining how the
mapping is to be performed.
@return An instance of RKObjectMappingOperation or RKManagedObjectMappingOperation for performing the mapping.
*/
+ (id)mappingOperationFromObject:(id)sourceObject toObject:(id)destinationObject withMapping:(RKMapping *)objectOrDynamicMapping;
///-------------------------
/// @name Performing Mapping
///-------------------------
/**
Initializes the receiver with a source and destination objects and an object mapping
definition for performing a mapping.
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
@param sourceObject The source object to be mapped. Cannot be nil.
@param destinationObject The destination object the results are to be mapped onto. May be nil,
in which case a new object will be constructed during the mapping.
@param objectOrDynamicMapping An instance of RKObjectMapping or RKDynamicMapping defining how the
mapping is to be performed.
@return The receiver, initialized with a source object, a destination object, and a mapping.
*/
- (id)initWithSourceObject:(id)sourceObject destinationObject:(id)destinationObject mapping:(RKMapping *)objectOrDynamicMapping;
/**
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
@param error A pointer to an NSError reference to capture any error that occurs during the mapping. May be nil.
@param error A pointer to an `NSError` reference to capture any error that occurs during the mapping. May be `nil`.
@return A Boolean value indicating if the mapping operation was successful.
*/
- (BOOL)performMapping:(NSError **)error;

8
Code/ObjectMapping/RKMappingOperation.m
View File

@@ -75,12 +75,6 @@ BOOL RKObjectIsValueEqualToValue(id sourceValue, id destinationValue) {
@implementation RKMappingOperation
+ (id)mappingOperationFromObject:(id)sourceObject toObject:(id)destinationObject withMapping:(RKMapping *)objectOrDynamicMapping
{
return [[self alloc] initWithSourceObject:sourceObject destinationObject:destinationObject mapping:objectOrDynamicMapping];
}
- (id)initWithSourceObject:(id)sourceObject destinationObject:(id)destinationObject mapping:(RKMapping *)objectOrDynamicMapping
{
NSAssert(sourceObject != nil, @"Cannot perform a mapping operation without a sourceObject object");
@@ -426,7 +420,7 @@ BOOL RKObjectIsValueEqualToValue(id sourceValue, id destinationValue) {
NSError *error = nil;
RKLogTrace(@"Performing nested object mapping using mapping %@ for data: %@", relationshipMapping, anObject);
RKMappingOperation *subOperation = [RKMappingOperation mappingOperationFromObject:anObject toObject:anotherObject withMapping:relationshipMapping.mapping];
RKMappingOperation *subOperation = [[RKMappingOperation alloc] initWithSourceObject:anObject destinationObject:anotherObject mapping:relationshipMapping.mapping];
subOperation.dataSource = self.dataSource;
subOperation.delegate = self.delegate;
if (NO == [subOperation performMapping:&error]) {

4
Code/ObjectMapping/RKObjectMapper.m
View File

@@ -211,9 +211,7 @@ NSString * const RKMappingErrorKeyPathErrorKey = @"keyPath";
NSError *error = nil;
RKMappingOperation *mappingOperation = [RKMappingOperation mappingOperationFromObject:mappableObject
toObject:destinationObject
withMapping:mapping];
RKMappingOperation *mappingOperation = [[RKMappingOperation alloc] initWithSourceObject:mappableObject destinationObject:destinationObject mapping:mapping];
mappingOperation.dataSource = self.mappingOperationDataSource;
if ([self.delegate respondsToSelector:@selector(mapper:willPerformMappingOperation:)]) {
[self.delegate mapper:self willPerformMappingOperation:mappingOperation];