[iPhone] Basic Data Persistence

Key Words: Data Persistence, Property List, plist, Archiving, SQLite3

1. Data Persistence Ways
1. Property List
2. Object Archive
3. SQLite3 (Database)
4. Other Ways
1. Traditional way: fopen, fread, fwrite
   
2. Cocoa's low-level file management tools
   
5. ...
   
2. Directories for Data Persistence
1. Every application (Except some Apple applications, such as Settings) are restricted to store its own folder under application installation path.
   
2. Directories for Application
1. /Documents
   Store application data (with exception of NSUserDefaults-based preference settings which is stored in /User/Library/Preferences)
   
2. /tmp
   Store temporary files. Files under this folder will not be backed up by iTunes when your iPhone syncs, but your application need to take responsibility for deleting the files in this folder once they are no longer needed, to avoid filling up the file system.
3. ...
   
3. Get Directories
1. Get Path of /Documents With NSSearchPathForDirectoriesInDomains
   ie,
   NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirecotory, NSUserDomainMask, YES];
   NSString *documentsDir = [paths objectAtIndex:0]; // We used index 0 since we know the array paths only contains one element.
   NSString *fileName = [documentsDir stringByAppendingPathComponent:@"theFile.txt"];
   
2. Get Path of /tmp With NSTemporaryDirectory
   NSString *tempDir = NSTEmporaryDirectory();
   NSString *fileName = [tempDir stringByAppendingPathComponent:@"theFile.txt"];
   
3. ...
   
4. ...
   
3. Property List
1. Property list file name end with extensions .plist
2. Property list file can be edited with XCode, or Properties List Editor
3. NSDictionary and NSArray can be used to hode persistence date in property list approch
4. Only objects of following classed can be serialized into properties list file, user custom objects or other Cocoa Touch objects (such as NSURL, NSImage, NSColor) can't be used directly.
   
   • NSArray
   • NSMutableArray
   • NSDictionary
   • NSMutableDictionary
   • NSData
   • NSMutableData
   • NSNumber
   • NSDate
5. Details
   About how to property list file into NSDictionary/NSArray, and how to store data holded in NSDictionary/NSArray into property list file, and how to parse data in property file list, please refer to offical document Property List Programming Guide.
   
6. ...
   
4. Archiving Model Objects
1. Objective
   Let you easily write complex objects to a file and then read them back in
   
2. Objects That Can Be Archived
   
   • Scalars: like int, float
   • Instance of a class that conforms to NSCoding protocol (In such approach, it is recommended to implement another protocol NSCopying to allow your object can be copied)
     
3. Define Data Model
1. Implement NSCoding Methods (Required)
   NSCoding defines 2 methods to encode and decode objects, you can encode and decode both objects and scalars using key-value coding.
   
   Implement mehtod encodeWithCoder. To support archiving in your object, you have to encode each of your instalce variables into encoder using the appropriate encoding method.
   
   Implement method initWithCoder, initialize an object instance using [super init] or [super initWithCoder:decoder] (decoder is argument of NSCoding:initWithCoder).
   
2. Implement NSCopying Methods (Optional)
   Implement copyWithZone
   
3. Sample
   //==================================================
   //Declare Data Model class in MyDataModel.h
   #define kFieldNameKey @"FieldName"
   #define kFieldSalaryKey  @"FieldSalary"
   #define kFieldYearKey  @"FieldYear"
   
   #import
   
   @nterface MyDataModel : NSObject
   {
       NSString *fieldName;
       NSString *fieldSalary;
       int fieldYear;
   }
   
   @property (nonatomic, retain NSString *fieldName;
   @property (nonatomic, retain NSString *fieldSalary;
   @end
   
   
   //==================================================
   //Define Data Model class in MyDataModel.m
   @import "MyDataModel.h"
   @implementation MyDataModel
   @synthesize fieldName;
   @synthesize fieldSalary;
   
   #pragma mark NSCoding
   - (void) encodeWithCoder:(NSCoder *)encoder
   {
       [encoder encodeObject:fieldName forKey:kFieldNameKey];
       [encoder encodeObject:fieldSalary forKey:kFieldSalaryKey];
       [encoder encodeObject:fieldYear forKey:kFieldYearKey];
   }
   - (id) initWithCoder:(NSCoder *) decoder
   {
       if (self = [super init]) // of if (self = [super initWithCoder:decoder)
       {
           fieldName = [decoder decodeOBjectForKey:kFieldNameKey];
           fieldSalary = [decoder decodeOBjectForKey:kFieldSalaryKey];
           fieldYear = [decoder decodeOBjectForKey:kFieldYearKey];
       }
   }
   
   #pragma mark NSCopying
   - (void) copyWithZone:(NSZone *) zone
   {
       MyDataModel *copy = [[[self class] allocWithZone:zone] init];
       copy.fieldName = [self.fieldName copy];
       copy.fieldName = [self.fieldName copy];
       copy.fieldYear = self.fieldYear;
   
       return copy;
   }
   
4. ...
   
4. Archving and Unarchiving
   @import "MyDataModel.h"
   #define kFileName @"archive"
   #define kDataKey @"Data"
   
   //==============================
   //Archiving
   MyDataModel *myData = [[MyDataModel alloc] init];
   myData.fieldName = @"Jimmy";
   myData.fieldSallary = @"200000";
   myData.fieldYear = 1980;
   
   NSMutableData *data = [[NSMutableData alloc] init];
   NSKeyedArchiver *archiver = [[NSKeyedArchiver alloc] initForWritingWithMutableData:data];
   [archiver endoceObject:myData forKey:kDataKey];
   [archiver finishEncoding];
   [data writeToFile:[self dataFilePath] atomically:YES];
   [myData release];
   [archiver release];
   [data release];
   
   
   //==============================
   //Unarchiving
   NSMutableData *data = [[NSMutableData alloc] initWithContentsOfFile:[self dataFilePath]];
   NSKeyedUnarchiver *unarchiver = [[NSKeyedUnarchiver alloc] initForReadingWithData:data];
   MyDataModel *myData = [unarchiver decodeObjectForKey:kDataKey];
   String *name = myData.fieldName;
   String *salary = myData.fieldSalary;
   int year = myData.fieldYear;
   [unarchiver finishDecoding];
   [unarchiver release];
   [data release];
   [myData release];
   
5. ...
   
5. SQLite3
1. SQLite3 is embedded SQL database, it uses Structured Query Language (SQL)
2. Dependency
1. Header
   /usr/include/sqlite3.h
   
2. Library
   /usr/lib/libsqlite3.dylib
   - Go to XCode, select Frameworks in Groups & Files pane
   - Select Add to Project ... from the Project menu
   - Navigate to /Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator2.1.sdk/usr/lib, and find the file called libaqlite3.dylib
   - When you are prompted, make sure
       uncheck Copy items into destination groups's folder (if needed).
       change Reference Type to Current SDK
   
3. ...
   
3. Basic
   use sqlite2_xxx APIs,
   
1. String
   SQLite3 was written in portable C, not Objective-c, so it use C string, not NSString, you need to convert between C string and NSString
   C String -> NSString
   char *pszData = "This is C String";
   NSString *strData = [[NSString alloc] initWithUTF8String:pszData];
   
   NSString -> C String
   NSString *strData = @"This is NSString";
   char *pszData = [strData UTF8String];
   
2. Datebase
   Data Type:
       sqlite3
   APIs:
       sqlite3_open   //Open databases, or create a new one if it doesn't exist
       sqlite3_close  //Close datebase
3. Run Command That Doesn't Return Data
   sqlite3_exec   //Perform Create/Delete/AddColumn on Table, update, insert ...
   
4. Retrive Data
   Data Type:
       sqlite_stmt
   APIs:
       sqlite3_prepare_v2
                |
                |----sqlite3_step
                |----sqlite3_column_int
                |----sqlite3_column_text
                |----sqlite3_column_xxxx
                |----sqlite3_column_finalize
   
4. Advanced
   
   
   
5. ...
6. ...

Reference:

1. Beginning iPhone Development: Exploring the iPhone SDK
   Chapter: Basic Data Persistence
   Page: P329~359
2. ...