KeyValueObjectMapping

Automatically parse any kind of key/value representation to an object. Such as JSON, XML, PLIST and more. Easy to use and to customize.

  • Language: Objective-C
    Framework: AppKit
  • Released: Jun 16, 2012
    Last Update: Jun 15, 2012

Introduction

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.

Features

  • Transform any kind of Key/Value type to a desired object. Can be a JSON, XML, plist or a simple NSDictionary.
  • Don't generate accessors to all the attribute, keep your properties readonly and framework will do it's magic to put the value on the object.
  • Based on Convention over Configuration
    1. If your attribute follow the same name of the key on the NSDictionary everything will be done automatically.
    2. If the keys on source are separated by some character, you can configure which character is and the framework will split and camelcase it to find the properly attribute.
  • Map any key to a specific attribute that doesn't follow the convention using DCObjectMapping.
  • To map an one-to-many relation use DCArrayMapping to tell what is the specific type of elements that will be inserted.
  • Aggregate values to an specific attribute using DCPropertyAggregator.
  • Parse 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.
  • Having a property pointing to a NSURL, framework will try to use [NSURL URLWithString:] method passing the value as a NSString.
Hide

Instalation

Installation

  • Just download the ZIP, unzip it and drag to your application. No additional framework is needed.

  • 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 drag the .framework that iOS-Universal-Framework generates into your application, import the header DCKeyValueObjectMapping.h and start using the framework.

    • There is a zip of the .framework here: https://github.com/downloads/dchohfi/KeyValueObjectMapping/KeyValueObjectMapping.framework.zip

    • Required import:

    objc #import

Hide

Usage

Usage

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.dateFormat = @"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);
Hide

Customization

DCParserConfiguration

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.dateFormat = @"dd/MM/yyyy";

DCKeyValueObjectMapping *parser = [DCKeyValueObjectMapping mapperForClass: [Tweet class] andConfiguration: config];

Overriding Key Name for Attribute

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];

Parsing NSArray properties

Since 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];

Aggregating values to specific type

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];
You need to log-in or create an account
  • Create an account
  • Log-in
Please use your real name.
Activation link will be sent to this address.
Minimum 8 characters
Enter your password again

Clicking this button confirms you read and agreed to the terms of use and privacy policy.

X

Save your watchlist

Fill your details below to receive project updates from your watch list - including new versions, price changes and discounts.

I agree to the terms of use and privacy policy.

License » MIT license Download
or Get a quote

for customization or integration services

Post a comment

Or enter your name and Email
  • M Mohsin 7 months ago
    I am also face the same issue ( NSUnknownKeyException) for custom Model Object.
  • PG P G 2 years ago
    It seems your component is an awesome one. However I am running into an issue when I start using your parser (it gives me NSUnknownKeyException). However if I replace your parser with the other ones that are publicly available it works. So I am wondering whether you can attach any specific xcode demo app so it will help developers like me to identify whether anything has been incorrectly setup to begin with. Thanks in advance..