I have been learning iPhone development lately and needed to add some persistence capability to my application. There are varied options available for persistence such as using “User Defaults” for small user specific settings, serialization similar to serialization or pickle features of other languages and builtin support of embeded Sqlite. I found Sqlite more performant, memory efficient and flexible than other options so I chose it. Using Sqlite with iPhone is fairly straight forward and there are tons of examples such Creating Todo list using Sqlite. However, when I looked for some O/R mapping framework for iPhone, I found that iPhone SDK unlike Mac development didn’t have any support and neither I could find any other solution elsewhere. So, I started writing a simple O/R mapping library based on Active Object pattern. This is similar to how Rails and Django implement O/R mapping. Based on convention over configuration, it simply maps object properties to the database table fields. At this time, this is very basic O/R mapping library and does not support relations, validation, database integrity support, etc. Nevertheless, it met my simple needs and I have released it as open source project under OCActiveObjects on GitHub.
The OCActiveObjects library is fairly small and consists of following classes:
ActiveObject
This is the base class that you extend in order to add automatic O/R support. You have to override following Class methods to specify name of the database and table:
+ (NSString *) getTableName;
Above method defines name of table where instances of the object will be stored.
+ (NSString *) getDatabaseName;
Above method defines name of the database to be used. You will then be able to call following methods to interact with the Sqlite database:
+ (void) openDatabase;
Above method must be called once before any other methods, usually at the start of your application.
+ (void) closeDatabase;
Above method must be called once before you shutodnw your application.
- (void) save;
Above method saves a new object or updates an existing object. Each subclass of ActiveObject is automatically assigned a unique database id with a property
named “objectId”. This is another example of convention where all tables will use a numeric surrogate key to identify each row.
If that property is nil then it assumes this is new object and inserts a new row in the database, otherwise it updates an existing row in the
database. It assumes that name of database fields are same as property names, though you can override that behavior by overriding _getPropertyNamesAndTypes Class method.
+ (ActiveObject *) findByPrimaryKey:(NSNumber *)objId;
Above method queries an object in the database matching objectId property, which identifies each object in the database.
+ (NSArray *) findWithCriteria:(NSDictionary *)criteria;
Above method returns an array of objects that match criteria. The criteria at this time is simple dictionary, i.e., pair of name and values that are joined by
“AND” clause. There is a immediate need to extend this to support more flexible queries.
+ (NSArray *) findAll;
Above method returns all objects, which may not be good for iPhone application due to limited amount of memory. This is another area that needs immediate attention.
+ (int) removeAll;
Above method removes all rows in the table so be careful with this.
+ (int) removeWithCriteria:(NSDictionary *)criteria;
Above method removes only methods matching criteria. Again criteria consists of name/value pairs.
+ (int) countWithCriteria:(NSDictionary *)criteria;
Above method counts the number of rows in the database matching criteria.
+ (int) countAll;
Above method returns count of all rows in the table.
Exension Methods in ActiveObject
There are number of extension methods to customize SQLs or behavior of the object such as
- (void) _insert;
Above method inserts an object into the database.
- (void) _update;
Above method updates an existing object into the database.
+ (NSDictionary *) _getPropertyNamesAndTypes;
You can override above method to change properties that needs to be persisted.
+ (NSString *) _getCreateSQL;
Above method generates an SQL for creating table.
+ (NSMutableString *) _getInsertSQL;
Above method generates an SQL for inserting a row in the table.
+ (NSMutableString *) _getUpdateSQL;
Above method generates an SQL for updating a row in the table.
+ (NSMutableString *) _getSelectSQL;
Above method generates an SQL for selecting fields from the database.
+ (void) _createTable;
Above method creates database table.
IntrospectHelper
The OCActiveObjects library uses some Objective C magical runtime support to query for properties and this class encapsulates those methods.
SqliteHelper
This class some helper methods for Sqlite3.
How to use
In order to test it, let’s define a simple Person class that extends ActiveObject, e.g.
#import <Foundation/Foundation.h>
#import "ActiveObject.h"
@interface Person : ActiveObject {
NSString *name;
short age;
int rank;
long votes;
char sex;
double income;
BOOL active;
NSInteger flags;
NSNumber *rating;
NSDate *birthdate;
}
@property (nonatomic, retain) NSString *name;
@property (nonatomic, assign) short age;
@property (nonatomic, assign) int rank;
@property (nonatomic, assign) long votes;
@property (nonatomic, assign) char sex;
@property (nonatomic, assign) double income;
@property (nonatomic, assign) BOOL active;
@property (nonatomic, assign) NSInteger flags;
@property (nonatomic, retain) NSNumber *rating;
@property (nonatomic, retain) NSDate *birthdate;
- (BOOL)isEqualToPerson:(Person *)aPerson;
@end
Implemention of Person.m looks like:
#import "Person.h"
@implementation Person
@synthesize name;
@synthesize age;
@synthesize rank;
@synthesize votes;
@synthesize sex;
@synthesize income;
@synthesize active;
@synthesize flags;
@synthesize rating;
@synthesize birthdate;
- (BOOL)isEqual:(id)other {
if (other == self)
return YES;
if (!other || ![other isKindOfClass:[self class]])
return NO;
return [self isEqualToPerson:other];
}
- (BOOL)isEqualToPerson:(Person *)aPerson {
if (self == aPerson)
return YES;
if (![(id)[self name] isEqual:[aPerson name]])
return NO;
return YES;
}
- (NSUInteger)hash {
NSUInteger hash = 0;
hash += [[self name] hash];
return hash;
}
- (NSString *)description {
return [NSString stringWithFormat:@"id %@, name %@", self.objectId, self.name);
}
- (void) dealloc {
[name release];
[birthdate release];
[super dealloc];
}
+ (NSString *) getTableName {
return @"persons";
}
+ (NSString *) getDatabaseName {
return @"personsdb";
}
@end
Then you can first open the database, e.g.
[Person openDatabase];
Then create a new person object, e.g.
Person *person = [[[Person alloc] init] autorelease];
person.birthdate = [[NSDate alloc]init];
int random = [person.birthdate timeIntervalSince1970];
person.age = random % 30;
person.rank = random % 20;
person.votes = random % 10;
person.sex = 'M';
person.name = [NSString stringWithFormat:@"Joe #%d", random % 1000];
person.income = random % 3000;
person.active = YES;
person.flags = random % 30 + 0.5;
person.rating = [NSNumber numberWithInt:20.5];
return person;
You will then be able to save the person object as
[person save];
You can see how many rows are in the database by
int count = [Person countAll];
And then retrieve the object that we saved as
Person *person2 = (Person *) [Person findByPrimaryKey:person.objectId];
When you are done, you can then close the database:
[Person closeDatabase];
One of the frustrating aspect of iPhone development has been lack of good unit testing support. Though, XCode comes with OCUnit, but it is hard to install and use with iPhone. I kept getting weird errors like:
exited abnormally with code 139
failed tests for architecture 'i386'
Though, there are some basic tutorials like Test Driving Your Code with OCUnit or OCUnit: Integrated Unit Testing In Xcode, but they didn’t help. I also tried adding google-toolbox-for-mac but macro errors are extremely frustrating. Besides better testing, OCActiveObjects needs a lot of help to add better support of criteria, paging, relational mapping and validation. I also had hard time figuring out how to create a static library until I found Building static libraries with the iPhone SDK though I still need help in adding framework level support. Hopefuly, other people can contribute to the open source project. You can send me your suggestions and comments as well via email “bhatti AT plexobject DOT com” or tweet me at bhatti_shahzad.