---

NSArchiver

Class at a Glance

An NSArchiver encodes objects into a format that can be written to a file. The archiving process traverses a set of interconnected objects, making sure to encode each one only once.

Principal Attributes

• An NSMutableData object containing the encoded data

Creation

NSArchiver Constructors

Returns an archiver.

Commonly Used Methods

archiveRootObjectToFile

Archives a graph of objects to a file.

archivedDataWithRootObject

Archives a graph of objects into an NSMutableData object.

Overview

NSArchiver, a concrete subclass of NSCoder, provides a way to encode objects into an architecture-independent format that can be stored in a file. When you archive a set of objects, the class information and instance variables for each object are written to the archive. NSArchiver’s companion class, NSUnarchiver, decodes the data in an archive and creates a set of objects equivalent to the original set.

NSArchiver stores the archive data in a mutable data object (NSMutableData). After encoding the objects, you can have the NSArchiver object write this mutable data object immediately to a file, or you can retrieve the mutable data object for some other use.

Tasks

Constructors

• NSArchiver

Archiving Data

• archivedDataWithRootObject
• archiveRootObjectToFile
• classNameGloballyEncodedForTrueClassName
• globallyEncodeClassNameIntoClassName
• encodeRootObject
• encodeConditionalObject
• encodeByte
• encodeChar
• encodeDataObject
• encodeDouble
• encodeFloat
• encodeInt
• encodeLong
• encodeObject
• encodeShort
• versionForClassName

Getting the Archived Data

• data

Substituting Classes or Objects

• classNameEncodedForTrueClassName
• encodeClassNameIntoClassName
• replaceObject

Static Methods

archivedDataWithRootObject

Returns a data object containing the encoded form of the object graph whose root object is rootObject.

public static NSData archivedDataWithRootObject(Object rootObject)

Discussion

This method invokes encodeRootObject to create a temporary archiver that encodes the object graph.

See Also

• encodeRootObject

archiveRootObjectToFile

Creates a temporary instance of NSArchiver and archives rootObject by encoding it into a data object and writing the resulting data object to the file path.

public static boolean archiveRootObjectToFile(Object rootObject, String path)

Discussion

This convenience method invokes archivedDataWithRootObject to get the encoded data. Returns true upon success.

The archived data should be retrieved from the archive by an NSUnarchiver object.

See Also

• archivedDataWithRootObject

classNameGloballyEncodedForTrueClassName

Returns the class name globally used to archive instances of the class trueName.

public static String classNameGloballyEncodedForTrueClassName(String trueName)

See Also

• globallyEncodeClassNameIntoClassName
• classNameEncodedForTrueClassName

globallyEncodeClassNameIntoClassName

Encodes a substitute name globally used for the class named trueName.

public static void globallyEncodeClassNameIntoClassName(String trueName, String inArchiveName)

Discussion

Any subsequently encountered objects of class trueName are archived as instances of class inArchiveName. It is safest not to invoke this method during the archiving process. Instead, invoke it before encodeRootObject.

See Also

• classNameGloballyEncodedForTrueClassName
• encodeClassNameIntoClassName

Instance Methods

classNameEncodedForTrueClassName

Returns the class name used to archive instances of the class trueName.

public String classNameEncodedForTrueClassName(String trueName)

See Also

• encodeClassNameIntoClassName
• classNameGloballyEncodedForTrueClassName

data

Returns the archived data.

public NSMutableData data()

Discussion

The returned data object is the same one specified as the argument to the constructor. It contains whatever data has been encoded thus far by invocations of the various encoding methods. It is safest not to invoke this method until after encodeRootObject has returned. In other words, although it is possible for a class to invoke this method from within an encoding method, that method must not alter the data.

encodeByte

Encodes aByte.

public void encodeByte(byte aByte)

Discussion

This method must be matched by a subsequent decodeByte message.

encodeChar

Encodes aChar.

public void encodeChar(char aChar)

Discussion

This method must be matched by a subsequent decodeChar message.

encodeClassNameIntoClassName

Encodes a substitute name for the class named trueName.

public void encodeClassNameIntoClassName(String trueName, String inArchiveName)

Discussion

Any subsequently encountered objects of class trueName are archived as instances of class inArchiveName. It is safest not to invoke this method during the archiving process . Instead, invoke it before encodeRootObject.

See Also

• classNameEncodedForTrueClassName
• globallyEncodeClassNameIntoClassName

encodeConditionalObject

Archives object conditionally.

public void encodeConditionalObject(Object object)

Discussion

This method overrides the superclass implementation to allow object to be encoded only if it is also encoded unconditionally by another object in the object graph. Conditional encoding lets you encode one part of a graph detached from the rest. (See “Archives” for more information.)

If object is null, the NSArchiver encodes it unconditionally as null. This method throws an InvalidArgumentException if no root object has been encoded.

encodeDataObject

Encodes aData.

public void encodeDataObject(NSData aData)

Discussion

This method must be matched by a subsequent decodeDataObject message.

encodeDouble

Encodes aDouble.

public void encodeDouble(double aDouble)

Discussion

This method must be matched by a subsequent decodeDouble message.

encodeFloat

Encodes aFloat.

public void encodeFloat(float aFloat)

Discussion

This method must be matched by a subsequent decodeFloat message.

encodeInt

Encodes anInt.

public void encodeInt(int anInt)

Discussion

This method must be matched by a subsequent decodeInt message.

encodeLong

Encodes aLong.

public void encodeLong(long aLong)

Discussion

This method must be matched by a subsequent decodeLong message.

encodeObject

Encodes anObject.

public void encodeObject(Object anObject)

Discussion

This method must be matched by a subsequent decodeObject message.

encodeRootObject

Archives rootObject along with all the objects to which it is connected.

public void encodeRootObject(Object rootObject)

Discussion

If any object is encountered more than once while traversing the graph, it is encoded only once, but the multiple references to it are stored. (See “Archives” for more information.)

This message must not be sent more than once to a given NSArchiver; an InvalidArgumentException is thrown if a root object has already been encoded. Therefore, don’t attempt to reuse an NSArchiver; instead, create a new one. To encode multiple object graphs, use distinct NSArchivers.

encodeShort

Encodes aShort.

public void encodeShort(short aShort)

Discussion

This method must be matched by a subsequent decodeShort message.

replaceObject

Causes the NSArchiver to treat subsequent requests to encode object as though they were requests to encode newObject.

public void replaceObject(Object object, Object newObject)

Discussion

Both object and newObject must be valid objects.

versionForClassName

Returns the version number for the current implementation of the class named className or NSArray.NotFound if no class named className exists.

public int versionForClassName(String className)

Discussion

The class version number of each encoded object is written to the archive so that newer versions of the class can detect and properly decode older archived versions.

---