Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Object archiving
Archiving is the process of converting a group of related objects to a form that can be stored or transferred between applications. The end result of archiving—an archive—is a stream of bytes that records the identity of objects, their encapsulated values, and their relationships with other objects. Unarchiving, the reverse process, takes an archive and reconstitutes an identical network of objects.
The main value of archiving is that it provides a generic way to make objects persistent. Instead of writing object data out in a special file format, applications frequently store their model objects in archives that they can write out as files. An application can also transfer a network of objects—commonly known as an object graph—to another application using archiving. Applications often do this for pasteboard operations such as copy and paste.
For its instances to be included in an archive, a class must adopt the NSCoding protocol and implement the required methods for encoding and decoding objects. Cocoa archives can hold Objective-C objects, scalar values, C arrays, structures, and strings. Archives store the types of objects along with the encapsulated data, so an object decoded from a stream of bytes is of the same class as the object that was originally encoded into the stream.
Keyed and Sequential Archivers
The Foundation framework provides two sets of classes for archiving and unarchiving networks of objects. They include methods for initiating the archiving and unarchiving processes and for encoding and decoding the instance data of your objects. Objects of these classes are sometimes referred to as archivers and unarchivers.
Keyed archivers and unarchivers (
NSKeyedArchiverandNSKeyedUnarchiver). These objects use string keys as identifiers of the data to be encoded and decoded. They are the preferred objects for archiving and unarchiving objects, especially with new applications.Sequential archivers and unarchivers (
NSArchiverandNSUnarchiver). This “old-style” archiver encodes object state in a certain order; the unarchiver expects to decode object state in the same order. Their intended use is for legacy code; new applications should use keyed archives instead.
Creating and Decoding Keyed Archives
An application creates an archive by invoking the archiveRootObject:toFile: class method of NSKeyedArchiver. The first parameter of this method takes a reference to the root object of an object graph. Starting with this root object, each object in the graph that conforms to the NSCoding protocol is given an opportunity to encode itself into the archive. The resulting byte stream is written to the specified file.
Decoding an archive proceeds in the opposite direction. An application calls the NSKeyedUnarchiver class method unarchiveObjectWithFile:. Given an archive file, the method recreates the object graph, asking the class of each object in the graph to decode the relevant data in the byte stream and recreate the object. The method ends by returning a reference to the root object.
The NSKeyedArchiver class methods archivedDataWithRootObject: and unarchiveObjectWithData: are equivalent to the above methods, except they work with a data object rather than a file.
Copyright © 2018 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2018-04-06