Automatic KeyValue Object Mapping for Objective-C, parse JSON/plist/Dictionary automatically
KeyValueObjectMapping is a Cocoa framework that provides an easy way to deal with any key/value type, as JSON
, XML
, plist
and even a common NSDictionary
. With no additional framework.
It’s made to be used together with a parser, such: NSJSONSerialization
, JSONKit
, NSXMLParser
and other resources, and the main goal is to avoid the tedious work when you need to deal with key/value types.
JSON
, XML
, plist
or a simple NSDictionary
.NSDictionary
everything will be done automatically.DCCustomInitialize
and DCCustomParser
.DCObjectMapping
.DCArrayMapping
to tell what is the specific type of elements that will be inserted.DCPropertyAggregator
.NSDate
using a specific date pattern(passed through the configuration) or if it’s send on JSON
in milliseconds since Jan 1, 1970 (UNIX timestamp) will be parsed with no additional configuration.NSURL
, framework will try to use [NSURL URLWithString:]
method passing the value as a NSString
.Using CocoaPods
, the easier way to manage dependencies on Objective-C world.
Using iOS-Universal-Framework
Since KeyValueObjectMapping uses iOS-Universal-Framework
to build and compile the project, you can easily compile and drag the .framework that iOS-Universal-Framework generates into your application, import the header DCKeyValueObjectMapping.h and start using the framework.
#import <DCKeyValueObjectMapping/DCKeyValueObjectMapping.h>
KeyValueObjectMapping is a simple object, all you need to do is create a new object and start to transform a dictionary to any classes.
Let’s assume that you have some JSON
like that:
{
"id_str": "27924446",
"name": "Diego Chohfi",
"screen_name": "dchohfi",
"location": "São Paulo",
"description": "Instrutor na @Caelum, desenvolvedor de coração, apaixonado por música e cerveja, sempre cerveja.",
"url": "http://about.me/dchohfi",
"protected": false,
"created_at": "Tue Mar 31 18:01:12 +0000 2009"
}
And your User
model looks like:
@interface User : NSObject
@property(nonatomic, strong) NSString *idStr;
@property(nonatomic, strong) NSString *name;
@property(nonatomic, strong) NSString *screenName;
@property(nonatomic, strong) NSString *location;
@property(nonatomic, strong) NSString *description;
@property(nonatomic, strong) NSURL *url;
@property(nonatomic, strong) BOOL protected;
@property(nonatomic, strong) NSNumber *followersCount;
@property(nonatomic, strong) NSDate *createdAt;
@end
Using any JSON
parser you need to transform this NSString
to a NSDictionary
representation:
NSError *error;
NSDictionary *jsonParsed = [NSJSONSerialization JSONObjectWithData:jsonData
options:NSJSONReadingMutableContainers error:&error];
If you don’t use KeyValueObjectMapping you need to create an instance of User
type, and set all the properties with the same key name on the dictionary. And transform it when needed.
User *user = [[User alloc] init];
[user setIdStr: [jsonParsed objectForKey: @"id_str"]];
[user setName: [jsonParsed objectForKey: @"name"]];
[user setScreenName: [jsonParsed objectForKey: @"screen_name"]];
NSDateFormatter *formatter = [[NSDateFormatter alloc] init];
formatter.datePattern = @"eee MMM dd HH:mm:ss ZZZZ yyyy";
NSDate *date = [formatter dateFromString:@"Sat Apr 14 00:20:07 +0000 2012"];
[user setCreatedAt: date];
Boring job, don’t you think? So, if you use KeyValueObjectMapping you just need to give the dictionary and the class that you want to create, and everthing else will be made automatically.
DCKeyValueObjectMapping *parser = [DCKeyValueObjectMapping mapperForClass: [Tweet class]];
Tweet *tweet = [parser parseDictionary:jsonParsed];
NSLog(@"%@ - %@", tweet.idStr, tweet.name);
If your NSDate
pattern are different then the default, which is @"eee MMM dd HH:mm:ss ZZZZ yyyy"
, you can configure to use a different one. So, there is an object to add custom configuration to the framework.
Using DCParserConfiguration
you can change the default behavior of some components, like the default pattern to parse a date.
DCParserConfiguration *config = [DCParserConfiguration configuration];
config.datePattern = @"dd/MM/yyyy";
DCKeyValueObjectMapping *parser = [DCKeyValueObjectMapping mapperForClass: [Tweet class] andConfiguration: config];
If your JSON
have some specific key that doesn’t match the attribute name you can use DCObjectMapping
to map this key to the attribute, the attribute type can be a specific Object either.
Your Tweet
model:
@interface Tweet : NSObject
@property(nonatomic, readonly) NSString *idStr;
@property(nonatomic, readonly) NSString *tweetText;
@property(nonatomic, readonly) User *userOwner;
@end
And the JSON
received follow the struct:
{
"id_str": 190957570511478800,
"text": "Tweet text",
"user": {
"name": "Diego Chohfi",
"screen_name": "dchohfi",
"location": "São Paulo"
}
}
Using DCObjectMapping
you can parse this JSON
and override the key names like that:
DCParserConfiguration *config = [DCParserConfiguration configuration];
DCObjectMapping *textToTweetText = [DCObjectMapping mapKeyPath:@"text" toAttribute:@"tweetText" onClass:[Tweet class]];
DCObjectMapping *userToUserOwner = [DCObjectMapping mapKeyPath:@"user" toAttribute:@"userOwner" onClass:[Tweet class]];
[config addObjectMapping:textToTweetText];
[config addObjectMapping:userToUserOwner];
DCKeyValueObjectMapping *parser = [DCKeyValueObjectMapping mapperForClass: [Tweet class] andConfiguration:config];
Tweet *tweetParsed = [parser parseDictionary:json];
NSArray
propertiesSince Objective-C don’t support typed collections like Java and other static language we can’t figure out what it the type of elements inside a collection.
But KeyValueObjectMapping can be configured to learn what is the type of elements that will be added to the collection on the specific attribute for the class.
So, if the model User
have many Tweets:
@interface User : NSObject
@property(nonatomic, strong) NSString *idStr;
@property(nonatomic, strong) NSString *name;
@property(nonatomic, strong) NSString *screenName;
@property(nonatomic, strong) NSString *location;
@property(nonatomic, strong) NSString *description;
@property(nonatomic, strong) NSURL *url;
@property(nonatomic, strong) BOOL protected;
@property(nonatomic, strong) NSNumber *followersCount;
@property(nonatomic, strong) NSDate *createdAt;
@property(nonatomic, strong) NSArray *tweets;
@end
The Tweet
looks like:
@interface Tweet : NSObject
@property(nonatomic, strong) NSString *idStr;
@property(nonatomic, strong) NSString *text;
@property(nonatomic, strong) NSDate *createdAt;
@end
And the JSON
looks like:
{
"id_str": "27924446",
"name": "Diego Chohfi",
"screen_name": "dchohfi",
"location": "São Paulo",
"description": "Instrutor na @Caelum, desenvolvedor de coração, apaixonado por música e cerveja, sempre cerveja.",
"url": "http://about.me/dchohfi",
"protected": false,
"created_at": "Tue Mar 31 18:01:12 +0000 2009",
"tweets" : [
{
"created_at" : "Sat Apr 14 00:20:07 +0000 2012",
"id_str" : 190957570511478784,
"text" : "Tweet text"
},
{
"created_at" : "Sat Apr 14 00:20:07 +0000 2012",
"id_str" : 190957570511478784,
"text" : "Tweet text"
}
]
}
Using DCArrayMapping
and adding it to the configuration, you tell to the KeyValueObjectMapping how to parse this specific attribute.
DCArrayMapping *mapper = [DCArrayMapping mapperForClassElements:[Tweet class] forAttribute:@"tweets" onClass:[User class]];
DCParserConfiguration *config = [DCParserConfiguration configuration];
[config addArrayMapper:mapper];
DCKeyValueObjectMapping *parser = [[DCKeyValueObjectMapping mapperForClass:[User class] andConfiguration:configuration];
User *user = [parser parseDictionary:jsonParsed];
Sometimes you faces an JSON
to parse that you don’t have access to modify the struct, and you don’t want to make your classes follow that specific struct.
Using DCPropertyAggregator
you can aggregate more than one key/value to a specific attribute on your domain.
So, if your JSON
looks like that:
{
"tweet" : "Some text",
"latitude" : -23.588453,
"longitude" : -46.632103,
"distance" : 100
}
If you follow this JSON
struct your objects won’t be so organized, right?
So, you can make your objects follow something different:
@interface Tweet : NSObject
@property(nonatomic, readonly) NSString *text;
@property(nonatomic, readonly) Location *location;
@end
@interface Location : NSObject
@property(nonatomic, readonly) NSNumber *distance;
@property(nonatomic, readonly) Point *point;
@end
@interface Point : NSObject
@property(nonatomic, readonly) NSNumber *latitude;
@property(nonatomic, readonly) NSNumber *longitude;
@end
And using DCPropertyAggregator
to map this specific behavior:
DCPropertyAggregator *aggregteLatLong = [DCPropertyAggregator aggregateKeys:[NSSet setWithObjects:@"latitude", @"longitude", nil] intoAttribute:@"point"];
DCPropertyAggregator *aggregatePointDist = [DCPropertyAggregator aggregateKeys:[NSSet setWithObjects:@"point", @"distance", nil] intoAttribute:@"location"];
DCParserConfiguration *configuration = [DCParserConfiguration configuration];
[configuration addAggregator:aggregteLatLong];
[configuration addAggregator:aggregatePointDist];
DCKeyValueObjectMapping *parser = [DCKeyValueObjectMapping mapperForClass:[Tweet class] andConfiguration:configuration];
Tweet *tweet = [parser parseDictionary: json];