Archiving

NSCoder is an abstract class that declares the interface used to both marshal and unmarshall object graphs. The marshalling process converts an object’s information into a series of bytes, and the unmarshalling process creates an object from a (previously marshalled) series of bytes. NSCoder includes methods for encoding and decoding data of various types, testing an NSCoder instance, and provides support for secure coding. The Foundation Framework includes four concrete subclasses of NSCoder: NSArchiver, NSUnarchiver, NSKeyedArchiver, and NSKeyedUnarchiver.

NSString *greeting = @"Hello, World!";
NSString *cwd = [[NSFileManager defaultManager] currentDirectoryPath];
NSString *archivePath = [cwd stringByAppendingString:@"/greeting.archive"];
BOOL result = [NSKeyedArchiver archiveRootObject:greeting toFile:archivePath];

NSString *greeting = [NSKeyedUnarchiver unarchiveObjectWithFile:archivePath];

@interface MyType : NSObject <NSCoding>

@property NSString *type;

@end

@implementation MyType

- (void)encodeWithCoder:(NSCoder *)coder
{
  [coder encodeObject:self.type forKey:@"TYPE_KEY"];
}

- (id)initWithCoder:(NSCoder *)coder
{
  if ((self = [super init]))
  {
    type = [coder decodeObjectForKey:@"TYPE_KEY"];
  }
  return self;
}

@end

Property List Serialization

Property list serialization provides a means of converting a property list, a structured collection of data organized as name-value pairs, to/from an architecture-independent byte stream. The Foundation Framework NSPropertyListSerialization class provides methods to serialize and deserialize property lists directly and validate a property list. It also supports conversion of property lists to/from XML or an optimized binary format. In contrast to archiving, basic serialization does not record the data type of the values nor the relationships between them; only the values themselves are recorded. Hence, you must write your code to deserialize data with the proper types and in the proper order.

A property list organizes data as named values and collections of values. They are frequently used to store, organize, and access standard types of data. Property lists can be created programmatically, or more commonly, as XML files.

NSError *errorStr;
NSDictionary *data = @{ @"FirstName" : @"John", @"LastName" : @"Doe" };
NSData *plistData = [NSPropertyListSerialization dataWithPropertyList:data
                     format:NSPropertyListXMLFormat_v1_0
                     options:0
                     error:&errorStr];

NSError *errorStr;
NSDictionary *plist = [NSPropertyListSerialization
                       propertyListWithData:plistData
                       options:NSPropertyListImmutable
                       format:NULL
                       error:&errorStr];

Archiving an Object Graph

OK, now that you have a good handle on the archiving and serialization classes, you’re going to create a program that demonstrates use of the Foundation Framework Archiving APIs. This program will create an object graph from a class hierarchy and then encode and decode the object graph from an archive. The classes that you’ll develop are diagrammed in Figure 12-1.

As shown in Figure 12-1, the program consists of a class hierarchy (the Subfamily-Family-Order classes) and a class (Archiver) that’s used to archive instances of this hierarchy. In Xcode, create a new project by selecting New Project . . . from the Xcode File menu. In the New Project Assistant pane, create a command-line application. In the Project Options window, specify ArchiveCat for the Product Name, choose Foundation for the Project Type, and select ARC memory management by selecting the Use Automatic Reference Counting check box. Specify the location in your file system where you want the project to be created (if necessary, select New Folder and enter the name and location for the folder), uncheck the Source Control check box, and then click the Create button.

Next, you’re going to create the class hierarchy for the object graph. You’ll start with the base class and then successively implement the remaining subclasses. Select New File . . . from the Xcode File menu, select the Objective-C class template, and name the class Order. Select the ArchiveCat folder for the files location and the ArchiveCat project as the target, and then click the Create button. Next, in the Xcode project navigator pane, select the resulting header file named Order.h and update the interface, as shown in Listing 12-9.

Listing 12-9.  Order Interface

#import <Foundation/Foundation.h>

@interface Order : NSObject <NSCoding>

@property (readonly) NSString *order;

- (id)initWithOrder:(NSString *)order;

@end

The Order interface adopts the NSCoding protocol, as required for classes that support archiving. The read-only property order identifies the order group in biological classification. The initWithOrder: method initializes an Order object, setting the property to the input parameter value. Now select the Order.m file and update the implementation, as shown in Listing 12-10.

Listing 12-10.  Order Implementation

#import "Order.h"

@implementation Order

- (id)initWithOrder:(NSString *)order
{
  if ((self = [super init]))
  {
    _order = order;
  }
   
  return self;
}

- (id)initWithCoder:(NSCoder *)coder
{
  if ((self = [super init]))
  {
    _order = [coder decodeObjectForKey:@"ORDER_KEY"];
  }
  return self;
}

- (void)encodeWithCoder:(NSCoder *)coder
{
  [coder encodeObject:self.order forKey:@"ORDER_KEY"];
}

- (NSString *) description
{
  return [NSString stringWithFormat:@"Order:%@", self.order];
}

@end

The initWithOrder: implementation is very similar to init methods you’ve developed elsewhere in this book. It simply assigns the order input parameter to the order property’s backing instance variable.

The initWithCoder: method, declared by the NSCoding protocol, initializes the object using the archived state. Its input parameter, coder, is the NSCoder instance used to decode the Order instance archive. The superclass of Order is NSObject; because NSObject doesn’t adopt the NSCoding protocol, the self variable is assigned the returned value of the superclass init call.

self = [super init]

Next, the Order class state (represented by its properties and instance variables) is decoded and initialized. As the Order class has a single property named order, the property’s instance variable is assigned to the value decoded by the decodeObjectForKey: method, where the key is named ORDER_KEY.

The encodeWithCoder: method is used to archive the Order class state, its input parameter, coder, is the NSCoder instance used to encode the Order instance archive. Because the superclass of Order doesn’t adopt the NSCoding protocol, this method doesn’t invoke the superclass’s encodeWithCoder: method, but just encodes the Order class state. Specifically, the method invokes the encodeWithCoder: method on the coder for each property/variable that needs to be archived.

[coder encodeObject:self.order forKey:@"ORDER_KEY"];

Finally, the class overrides the description method (inherited from its superclass) to return a text string listing the value for the order property.

Now you’ll implement the next class in the hierarchy. Select New File . . . from the Xcode File menu, select the Objective-C class template, and name the class Family. Select the ArchiveCat folder for the files location and the ArchiveCat project as the target, and then click the Create button. Next, in the Xcode project navigator pane, select the resulting header file named Family.h and update the interface, as shown in Listing 12-11.

Listing 12-11.  Family Interface

#import "Order.h"

@interface Family : Order

@property(readonly) NSString *family;

- (id)initWithFamily:(NSString *)family order:(NSString *)order;

@end

The Family interface subclasses the Order class, and hence adopts the NSCoding protocol. The read-only property family specifies the family group in a biological classification. The initWithFamily:order: method initializes a Family object, setting the family and order properties to the input parameter values provided. Now select the Family.m file and update the implementation, as shown in Listing 12-12.

Listing 12-12.  Family Implementation

#import "Family.h"

@implementation Family

- (id)initWithFamily:(NSString *)family order:(NSString *)order
{
  if ((self = [super initWithOrder:order]))
  {
    _family = family;
  }
   
  return self;
}

- (id)initWithCoder:(NSCoder *)coder
{
  if ((self = [super initWithCoder:coder]))
  {
    _family = [coder decodeObjectForKey:@"FAMILY_KEY"];
  }
  return self;
}

- (void)encodeWithCoder:(NSCoder *)coder
{
  [super encodeWithCoder:coder];
  [coder encodeObject:self.family forKey:@"FAMILY_KEY"];
}

- (NSString *) description
{
  return [NSString stringWithFormat:@"Family:%@, %@", self.family,
          [super description]];
}

@end

This implementation is very similar to that of the Order class, so you’ll just focus on the key differences. The initWithFamily:order: invokes the superclass initWithOrder: method to initialize the superclass state properly, and then assigns the family input parameter to the property’s backing instance variable.

The initWithCoder: method is very similar to that provided for the Order class (as shown in Listing 12-10). However, as the superclass of the Family class (Order) adopts the NSCoding protocol, the self variable is assigned the returned value of the superclass initWithCoder: call.

self = [super initWithCoder:coder]

In this way, the superclass state (the order property) is initialized properly. Next, the Family class state (represented by its properties and instance variables) is decoded and initialized. As the Family class has a single property named family, the property’s instance variable is assigned to the value decoded by the coder’s decodeObjectForKey: method, where the key is named FAMILY_KEY.

The encodeWithCoder: method is used to archive the Family class state. Because the superclass of Family (the Order class) adopts the NSCoding protocol, this method first invokes invoke the superclass’s encodeWithCoder: method. Next, it invokes the encodeWithCoder: method on the coder for each property/variable that needs to be archived; in this case, the family property.

As with the Order class, the description method returns a text string consisting of the value of the family property concatenated with the value of the description for its superclass.

return [NSString stringWithFormat:@"Family:%@, %@", self.family,
        [super description]];

Now you’ll implement the final class in the hierarchy. Select New File . . . from the Xcode File menu, select the Objective-C class template, and name the class Subfamily. Select the ArchiveCat folder for the files location and the ArchiveCat project as the target, and then click the Create button. Next, in the Xcode project navigator pane, select the resulting header file named Subfamily.h and update the interface, as shown in Listing 12-13.

Listing 12-13.  Subfamily Interface

#import "Family.h"

@interface Subfamily : Family

@property(readonly) NSString *genus;
@property(readonly) NSString *species;

- (id)initWithSpecies:(NSString *)species
             genus:(NSString *)genus
            family:(NSString *)family
             order:(NSString *)order;

@end

The Subfamily interface subclasses the Family class. The read-only properties genus and species specifies the genus and species for an animal group in a biological classification. The initWithSpecies:family:order: method initializes a Subfamily object, similar to the corresponding methods for the Family and Order classes. Now select the Subfamily.m file and update the implementation, as shown in Listing 12-14.

Listing 12-14.  Subfamily Implementation

#import "Subfamily.h"

@implementation Subfamily

- (id)initWithSpecies:(NSString *)species
             genus:(NSString *)genus
            family:(NSString *)family
             order:(NSString *)order
{
  if ((self = [super initWithFamily:family order:order]))
  {
    _species = species;
    _genus = genus;
  }
   
  return self;
}

- (id)initWithCoder:(NSCoder *)coder
{
  if ((self = [super initWithCoder:coder]))
  {
    _species = [coder decodeObjectForKey:@"SPECIES_KEY"];
    _genus = [coder decodeObjectForKey:@"GENUS_KEY"];
  }
  return self;
}

- (void)encodeWithCoder:(NSCoder *)coder
{
  [super encodeWithCoder:coder];
  [coder encodeObject:self.species forKey:@"SPECIES_KEY"];
  [coder encodeObject:self.genus forKey:@"GENUS_KEY"];
}

- (NSString *) description
{
  return [NSString stringWithFormat:@"Animal - Species:%@ Genus:%@, %@",
          self.species, self.genus, [super description]];
}

@end

This implementation is very similar to that of the Family class, differing primarily in the Subfamily class state (the genus and species properties). In all other respects, the logic is identical, as you’ll see if you compare Listing 12-12 and Listing 12-14. Now you’ll implement the class used to archive the hierarchy. Select New File . . . from the Xcode File menu, select the Objective-C class template, and name the class Archiver. Select the ArchiveCat folder for the files location and the ArchiveCat project as the target, and then click the Create button. Next, in the Xcode project navigator pane, select the resulting header file named Archiver.h and update the interface, as shown in Listing 12-15.

Listing 12-15.  Archiver Interface

#import <Foundation/Foundation.h>

@interface Archiver : NSObject

@property (readwrite) NSString *path;

- (BOOL) encodeArchive:(id)data toFile:(NSString *)file;
- (id) decodeArchiveFromFile:(NSString *) file;

@end

The Archiver interface has a single property, path, which defines the path for the file the archive is written to. The methods encodeArchive:toFile: and decodeArchiveFromFile: are used to encode/decode an archive to/from a file on the file system. Now select the Archiver.m file and update the implementation, as shown in Listing 12-16.

Listing 12-16.  Archiver Implementation

#import "Archiver.h"

@implementation Archiver

- (id) init
{
  if ((self = [super init]))
  {
    _path = NSTemporaryDirectory();
  }
   
  return self;
}

- (BOOL) encodeArchive:(id)objectGraph toFile:(NSString *)file
{
  NSString *archivePath = [self.path stringByAppendingPathComponent:file];
   
  // Create an archiver for encoding data
  NSMutableData *mdata = [[NSMutableData alloc] init];
  NSKeyedArchiver *archiver = [[NSKeyedArchiver alloc]
                               initForWritingWithMutableData:mdata];
   
  // Encode the data, keyed with a simple string
  [archiver encodeObject:objectGraph forKey:@"FELINE_KEY"];
  [archiver finishEncoding];
   
  // Write the encoded data to a file, returning status of the write
  BOOL result = [mdata writeToFile:archivePath atomically:YES];
  return result;
}

- (id) decodeArchiveFromFile:(NSString *) file
{
  // Get path to file with archive
  NSString *archivePath = [self.path stringByAppendingPathComponent:file];
   
  // Create an unarchiver for decoding data
  NSData *data = [[NSMutableData alloc] initWithContentsOfFile:archivePath];
  NSKeyedUnarchiver *unarchiver = [[NSKeyedUnarchiver alloc]
                                   initForReadingWithData:data];
   
  // Decode the data, keyed with simple string
  id result = [unarchiver decodeObjectForKey:@"FELINE_KEY"];
  [unarchiver finishDecoding];
   
  // Return the decoded data
  return result;
}

@end

As shown in Listing 12-16, the init method sets the value for the path property. It uses the Foundation NSTemporaryDirectory() function to create a path to the user’s temporary directory on the file system, and assigns that value to the property’s backing instance variable.

The encodeArchive:toFile: method encodes an object graph to a file. It creates a file path by prepending the path property to the input file string. It then creates a mutable data object for archiving the graph. Next, it creates an NSKeyArchiver instance to perform the archiving, initialized with the data object. It encodes the graph to the data object with the key FELINE_KEY, and then finishes the encoding. Finally, it writes the archived data object to the file, returning a Boolean that indicates the success/failure of the write.

The decodeArchiveFromFile: method decodes an archive from a file, returning the initialized object graph. It creates a file path by prepending the path property to the input file string. It then creates a data object for unarchiving the graph. Next, it creates an NSKeyUnarchiver instance to perform the unarchiving, initialized with the data object. It decodes the graph to a data object with the key FELINE_KEY, finishes the decoding, and then returns the initialized data object.

And that’s it! Now that you have implemented the class hierarchy and the archiver class, let’s use this to archive an object graph. In the Xcode project navigator, select the main.m file and update the main() function, as shown in Listing 12-17.

Listing 12-17.  ArchiveCat main( ) Function

#import <Foundation/Foundation.h>
#import "Archiver.h"
#import "Subfamily.h"

int main(int argc, const char * argv[])
{
  @autoreleasepool
  {
    // Create an Archiver to encode/decode an object graph
    Archiver *archiver = [[Archiver alloc] init];
     
    // Create an object graph and archive it to a file
    id animal = [[Subfamily alloc] initWithSpecies:@"Lion"
                                             genus:@"Panther"
                                            family:@"Felid"
                                             order:@"Carnivore"];
    NSLog(@"
%@", [animal description]);
    NSString *file = @"data.archive";
     
    // Display results
    if ([archiver encodeArchive:animal toFile:file])
    {
      NSLog(@"You encoded an archive to file %@",
            [[archiver path] stringByAppendingString:file]);
    }
     
    // Decode object graph from archive and log its description
    id data = [archiver decodeArchiveFromFile:file];
    if ([archiver decodeArchiveFromFile:file])
    {
      NSLog(@"You decoded an archive from file %@
%@",
            [[archiver path] stringByAppendingString:file], [data description]);
    }
     
  }
  return 0;
}

As shown in Listing 12-17, the main() function begins by creating an Archiver object. It then creates an object graph, logs its description to the output pane, and names the archive file. Next, the graph is archived to the named archive file, and if successful, a message is logged to the console.

The next set of statements decodes an object graph from the archive. First, it decodes the archive using the Archiver decodeArchiveFromFile: method. It then performs a condition check on the result of the method call, and if it returns an object graph (meaning the operation completed successfully), it logs a description of the object graph to the output pane. Now when you compile and run the ArchiveCat program, you should observe messages in the output pane comparable to those shown in Figure 12-2.

As shown in the output pane, a Subfamily object (i.e., object graph) is created and initialized with its input parameters, and its description is logged to the output pane. Next, the object is archived to the specified file, and the full path of the archive file is logged to the output pane. A corresponding object is then decoded from the archive and its description is logged to the output pane. As the description for the initially created object and the object decoded from the archive is identical, this validates that the archive was correctly encoded and decoded. This demonstrates use of the Archiving APIs to encode/decode an archive. Look this code over for a while and make sure that you have a good handle on the archiving process. When you’re ready, let’s move on to distributed objects.