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

Most Cocoa applications are typically either "regular" or multi-document. TextEdit, for example, is a multi-documentation application, whereas AddressBook is not. This tutorial does not discuss multi-document applications, though the concepts are very similar.

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:

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:

Finally, change Mailbox.h to indicate that the Mailbox class now conforms to the NSCodingprotocol:

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:

Here's the code to enable loading from disk:

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:

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:

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:

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 NSKeyedArchiverto 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:

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:

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 toNSKeyedArchiver, 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:

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:

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

	Intro to Cocoa Bindings	the original tutorial which used MailDemo
	Archives and Serialization	Apple's official documentation for archiving
	Cocoa Dev Central blog	author's personal site

Copyright © 2005 Scott Stevenson

From: http://www.cocoadevcentral.com/articles/000084.php