In a nutshell: saving data created by the user
Most applications need a way to save data to disk and bring it back later. In
many cases, the best built-in class to use for this is NSKeyedArchiver. It
doesn't provide the scalability of a SQL database, but it is incredibly easy
to use.
In this tutorial, you'll add saving support to the MailDemo application, which
was originally used in the Cocoa Bindings tutorial. It's not necessary to read
that tutorial first, but you do need to understand Objective-C and general
Cocoa concepts.
Download the project so you can follow along and make the changes as they're
described. Note that this is not the finished project, just the starting point.
Mac OS X 10.3 (Panther) is required to use this project.
> Download the MailDemo Xcode project 56k
1 of 9
NSKeyedArchiver in a Nutshell
The NSKeyedArchiver class accepts data objects from your application and stores them
on disk. It stores the objects in a file as binary data.
You can open a binary data file in a text editor, but it's quite hard to make any
sense of the contents that way. Binary files are designed to be easily read by the
computer, not a person. As a result, binary files take up less space on disk than
plain text files and can be loaded by an application very quickly.
Interface Builder, for example, typically stores NIB files in a binary format.
2 of 9
Adding Saving Support to Mailbox
The process of converting objects into binary data is called encoding.
Your job is to tell Cocoa how your data should be encoded. Here's the code
to add to Mailbox.m to do that:
Mailbox.m
- (void) encodeWithCoder: (NSCoder *)coder
{
[coder encodeObject: properties forKey:@"properties"];
[coder encodeObject: emails forKey:@"emails"];
}
This method adds the Mailbox's data to the NSCoder object that's passed in,
using the -encodeObject:forKey: message to store each item. You can choose
whatever names you like for the keys, but they must mirror those used in
-initWithCoder.
The -initWithCoder: method is called when data is being
loaded back from disk. Here's the version of that method to put in Mailbox.m:
- (id) initWithCoder: (NSCoder *)coder
{
if (self = [super init])
{
[self setProperties: [coder decodeObjectForKey:@"properties"]];
[self setEmails: [coder decodeObjectForKey:@"emails"]];
}
return self;
}
Finally, change Mailbox.h to indicate that the Mailbox
class now conforms to the NSCoding protocol:
Mailbox.h
@interface Mailbox : NSObject <NSCoding>
That's all we need to do in this file.
3 of 9
Adding Saving Support to Email
Here's the code to add to Email.m to enable saving for the Email class:
Email.m
- (void) encodeWithCoder: (NSCoder *)coder
{
[coder encodeObject: properties forKey:@"properties"];
}
Here's the code to enable loading from disk:
- (id) initWithCoder: (NSCoder *)coder
{
if (self = [super init])
{
[self setProperties: [coder decodeObjectForKey:@"properties"]];
}
return self;
}
This code is nearly identical to the methods added to Mailbox. The difference is that
there's one less instance variable to store.
Just as before, add NSCoding to Email.h:
Email.h
@interface Email : NSObject <NSCoding>
We're now done with this file.
4 of 9
Declare New Methods in MyController.h
We'll create three new methods to MailDemo's MyController class to support saving.
Add these declarations to the MyController.h file:
MyController.h
- (NSString *) pathForDataFile;
- (void) saveDataToDisk;
- (void) loadDataFromDisk;
The first method returns the destination path of the data file. The other two
methods are used to save and load the data, respectively.
5 of 9
Choosing the File Location
Before an application can save, the developer must select a location for the
data. Mac OS X applications generally store such things in ~/Library/Application
Support/<Application>/. The application must create that directory if it doesn't
already exist.
Here's the code to add to MyController.m to do all of this:
MyController.m
- (NSString *) pathForDataFile
{
NSFileManager *fileManager = [NSFileManager defaultManager];
NSString *folder = @"~/Library/Application Support/MailDemo/";
folder = [folder stringByExpandingTildeInPath];
if ([fileManager fileExistsAtPath: folder] == NO)
{
[fileManager createDirectoryAtPath: folder attributes: nil];
}
NSString *fileName = @"MailDemo.cdcmaildemo";
return [folder stringByAppendingPathComponent: fileName];
}
On the first line of this method, we set up an instance of NSFileManager. Many of the
file-related tasks that you would typically do by hand with the Finder can be accomplished
using NSFileManager.
Next, we create an NSString named folder, and set it to the path of the destination
folder.
The next line is a bit tricky in that it re-assigns the folder variable to a different
version of the same string. The -stringByExpandingTildeInPath method returns a version of
the folder path with the tilde replaced by the user's home directory, such as
"/Users/scott".
On the next line, we ask NSFileManager if the folder already exists. If it doesn't, we
request that it is created by sending the -createDirectoryAtPath:attributes: message.
Finally, we append the file name to the folder path and return the complete path.
6 of 9
Archiving the Data
Now that you have added the NSCoding methods to the data classes, you can ask
NSKeyedArchiver to write your objects to disk. You only need to tell the archiver
about your top-level objects. In this case, the term "top level" just means the
objects which are listed as instance variables in MyController.h.
The only top-level object for the MyController class is the "mailboxes" array.
Here's the code to add to MyController.m to save the array (and everything it
contains) to disk:
MyController.m
- (void) saveDataToDisk
{
NSString * path = [self pathForDataFile];
NSMutableDictionary * rootObject;
rootObject = [NSMutableDictionary dictionary];
[rootObject setValue: [self mailboxes] forKey:@"mailboxes"];
[NSKeyedArchiver archiveRootObject: rootObject toFile: path];
}
On the first line, we retrieve the destination file path. After that, we create an
NSMutableDictionary and place the mailboxes array in it. If you have other
top-level objects, add them to this dictionary.
This dictionary is considered the "root object" -- a master object which contains a
tree of all other data objects. We pass this dictionary to NSKeyedArchiver in the
+archiveRootObject:toFile: class method.
7 of 9
How Archiving Works
Once NSKeyedArchiver receives the +archiveRootObject:toFile: message,
it recursively calls -encodeWithCoder on the entire tree of objects inside the
root object. Each instance of Mailbox and Email adds its own bit of data to the
archiver.
After all of the objects have added their encoded data, the archiver automatically creates an
NSData object and writes its contents to the file path we supplied.
8 of 9
Reloading Data at Startup
Now we will implement a method in MyController.m to load the data from disk:
MyController.m
- (void) loadDataFromDisk
{
NSString * path = [self pathForDataFile];
NSDictionary * rootObject;
rootObject = [NSKeyedUnarchiver unarchiveObjectWithFile:path];
[self setMailboxes: [rootObject valueForKey:@"mailboxes"]];
}
This is essentially the reverse of the saving method. Once again, we retrieve the path to
the file and create a dictionary which will serve as the root object.
This time, though, we're talking to the NSKeyedUnarchiver class, which is similar to NSKeyedArchiver,
but specializes in loading data from disk. We send it the -unarchiveObjectWithFile message, which will
read the data file, un-encode the contents, and return the root object.
After that, it's just a matter of using -setMailboxes to repopulate
the mailboxes array with the saved data.
9 of 9
Automating Save and Reload
MailDemo can now save and reload data, but the process should ideally be transparent
to the user. We only need to add a few lines of code to MyController.m to make that
happen:
MyController.m
- (void) awakeFromNib
{
[NSApp setDelegate: self];
[self loadDataFromDisk];
}
The -setDelegate message registers MyController to be the application delegate.
It's possible to do this in Interface Builder as well.
The next line of code simply calls -loadDataFromDisk. Since MailDemo uses
Cocoa bindings, the table views are automatically updated after the data is loaded.
To complete the cycle, we need to make sure the data is saved when the application quits. To do
this, add the -applicationWillTerminate delegate method show below:
- (void) applicationWillTerminate: (NSNotification *)note
{
[self saveDataToDisk];
}
We're all set! Build and run the project. You should see that your data stays intact between
sessions. If you encountered any difficulties, go back and repeat the steps above.
Wrap Up
We've added NSCoding support to the data classes and saving support to the
application. Implementing encoding also sets your application up to support
copy/paste and drag-and-drop. Both are typically accomplished by writing
encoded objects to the pasteboard.
> Download the Finished MailDemo Xcode project 57k
As always, let us know what you think about the tutorial.
Further Reading
Feedback
