PATH  Documentation > Mac OS X > Foundation Reference: Java



Table of Contents

NSArchiver


Inherits from:
NSCoder : NSObject
Package:
com.apple.yellow.foundation

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


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.


Class Description


NSArchiver, a concrete subclass of NSCoder, provides a way to encode Objective-C 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.


Archiving a Graph of Objects


The easiest way to archive an object is to invoke a single class method-either archiveRootObjectToFile or archivedDataWithRootObject, depending on whether you want the encoded data to be stored in a file immediately. These convenience methods create a temporary NSArchiver and send it an encodeRootObject message-you need do no more. However, if you want to customize the archiving process (for example, by substituting certain classes for others), you must instead create an instance of NSArchiver yourself, configure it as desired, and send it an encodeRootObject message explicitly.

The "root object" that you specify as the argument to any of these three methods indicates the starting point for archiving. The NSArchiver commences by archiving the root object. This typically encodes the root object's instance variables, which isn't necessarily a straightforward process-the instance variables can themselves be other objects that must be encoded, and so on, yielding a possibly complex graph of objects that need to be archived.

The fact that many objects contain references to other objects poses two problems for archiving. The first is redundancy. An object graph isn't necessarily a simple tree structure. Two objects can contain references to each other, for example, creating a cycle. To address this problem, NSArchiver overrides NSCoder's encodeRootObject: method to keep track of all the objects encountered while traversing the graph. The first time an object is encountered, the object is encoded normally. On subsequent occurrences of the same object, a reference to the original object is encoded instead of the object itself.

The second problem is that it's not always appropriate to archive the entire graph. To use an example from the Application Kit, when you archive an NSView as the root object, its subviews should be archived, but not its superview. In this case, the superview is considered an extraneous part of the graph. To solve this dilemma, NSArchiver implements conditional archiving, overriding the minimal encodeConditionalObject method that's inherited from NSCoder. A class can invoke encodeConditionalObject to archive inessential object instance variables. The NSArchiver doesn't actually archive a conditionally encoded object unless some other object in the graph encodes it unconditionally (using one of the other encode...Object: methods declared by NSCoder). When everything is unarchived, all original references to the conditionally encoded object are properly restored as references to the single unarchived object. For example, an NSView encodes its superview with encodeConditionalObject, because it doesn't own the superview but does need to preserve its connection to it if some other object archives the superview.

In contrast, encodeObject unconditionally instructs an object to encode itself. This method is most often used for instance variables that are intrinsic to the receiver and essential for proper functioning.

All the objects to be placed in a single archive must be interconnected members of a single graph. In other words, there can only be one root object per archive. The only recommended way to archive objects is to send an NSArchiver a single encodeRootObject message, whether directly, or indirectly by invoking archiveRootObjectToFile or archivedDataWithRootObject. Don't try to add data to the archive by invoking any of NSCoder's other encode... methods.

To extract an object graph from an archive, use the NSUnarchiver class method unarchiveObjectWithFile or unarchiveObjectWithData, assigning the return value to the desired root object.


Archiving other Data Types


It's possible to create an archive that doesn't contain any objects. To archive other data types, invoke one of the encode... methods, such as encodeByte, encodeChar, or encodeDouble, directly for each data item to be archived, instead of using encodeRootObject. When you create an archive in this way, the corresponding unarchiving code must follow exactly the same sequence of data types.

This approach shouldn't be used to archive objects. Use encodeRootObject instead, to avoid the problems mentioned in the previous section and to simplify unarchiving.

An NSSerializer provides another means to store data in an architecture-independent format. See the NSSerializer class specification for more information.


Superclass Methods to Avoid


NSArchiver's superclass, NSCoder, supplies methods for both encoding and decoding. However, only the encoding methods are applicable to NSArchiver-don't send an NSArchiver any decode... messages. (Similarly, don't send encode... messages to an NSUnarchiver.)




Method Types


Constructors
NSArchiver
Archiving data
archivedDataWithRootObject
archiveRootObjectToFile
classNameGloballyEncodedForTrueClassName
globallyEncodeClassNameIntoClassName
encodeRootObject
encodeConditionalObject
encodeByte
encodeChar
encodeDataObject
encodeDouble
encodeFloat
encodeInt
encodeLong
encodeObject
Getting the archived data
decodeByte
decodeChar
decodeDataObject
decodeDouble
decodeFloat
decodeInt
decodeLong
decodeObject
decodeShort
Substituting classes or objects
classNameEncodedForTrueClassName
encodeClassNameIntoClassName
replaceObject


Constructors



NSArchiver

public NSArchiver()

Description forthcoming.

public NSArchiver(NSMutableData aNSMutableData)

Description forthcoming.


Static Methods



archiveRootObjectToFile

public static boolean archiveRootObjectToFile( Object rootObject, String path)

Creates a temporary instance of NSArchiver and archives rootObject by encoding it into a data object. Once the object has been encoded, this method writes the resulting data object to the file path. This convenience method invokes archivedDataWithRootObject to get the encoded data. Returns true upon success.

See Also: archivedDataWithRootObject



archivedDataWithRootObject

public static NSData archivedDataWithRootObject(Object rootObject)

Returns a data object containing the encoded form of the object graph whose root object is rootObject. This method invokes initForWritingWithMutableData: and encodeRootObject to create a temporary archiver that encodes the object graph.

See Also: initForWritingWithMutableData:, encodeRootObject



classNameGloballyEncodedForTrueClassName

public static String classNameGloballyEncodedForTrueClassName(String trueName)

Description forthcoming.

globallyEncodeClassNameIntoClassName

public static void globallyEncodeClassNameIntoClassName( String className, String targetClassName)

Description forthcoming.


Instance Methods



classNameEncodedForTrueClassName

public String classNameEncodedForTrueClassName(String trueName)

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

See Also: encodeClassNameIntoClassName



data

public NSMutableData data()

Description forthcoming.

decodeByte

public byte decodeByte()

Decodes and returns a byte structure that was previously encoded with encodeByte.

decodeChar

public char decodeChar()

Decodes and returns a char structure that was previously encoded with encodeChar.

decodeDataObject

public NSData decodeDataObject()

Decodes and returns an NSData structure that was previously encoded with encodeDataObject.

decodeDouble

public double decodeDouble()

Decodes and returns a double structure that was previously encoded with encodeDouble.

decodeFloat

public float decodeFloat()

Decodes and returns a float structure that was previously encoded with encodeFloat.

decodeInt

public int decodeInt()

Decodes and returns an int structure that was previously encoded with encodeInt.

decodeLong

public long decodeLong()

Decodes and returns a long structure that was previously encoded with encodeLong.

decodeObject

public Object decodeObject()

Decodes and returns an Object structure that was previously encoded with encodeObject.

decodeShort

public short decodeShort()

Decodes and returns a short structure that was previously encoded with encodeShort.

encodeByte

public void encodeByte(byte aByte)

Encodes aByte.

This method must be matched by a subsequent decodeByte message.



encodeChar

public void encodeChar(char aChar)

Encodes aChar.

This method must be matched by a subsequent decodeChar message.



encodeClassNameIntoClassName

public void encodeClassNameIntoClassName( String trueName, String inArchiveName)

Encodes a substitute name for the class named trueName. Any subsequently encountered objects of class trueName will be archived as instances of class inArchiveName. It's safest not to invoke this method during the archiving process . Instead, invoke it before encodeRootObject.

See Also: classNameEncodedForTrueClassName



encodeConditionalObject

public void encodeConditionalObject(Object object)

Archives object conditionally. This method overrides the superclass implementation to allow object to be encoded only if it's 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 the class description 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

public void encodeDataObject(NSData aNSData)

Encodes aNSData.

This method must be matched by a subsequent decodeDataObject message.



encodeDouble

public void encodeDouble(double aDouble)

Encodes aDouble.

This method must be matched by a subsequent decodeDouble message.



encodeFloat

public void encodeFloat(float aFloat)

Encodes aFloat.

This method must be matched by a subsequent decodeFloat message.



encodeInt

public void encodeInt(int anInt)

Encodes anInt.

This method must be matched by a subsequent decodeInt message.



encodeLong

public void encodeLong(long aLong)

Encodes aLong.

This method must be matched by a subsequent decodeLong message.



encodeObject

public void encodeObject(Object anObject)

Encodes anObject.

This method must be matched by a subsequent decodeObject message.



encodeRootObject

public void encodeRootObject(Object rootObject)

Archives rootObject along with all the objects it's connected to. If any object is encountered more than once while traversing the graph, it's encoded only once, but the multiple references to it are stored. (See the discussion of object graphs in the class description.)

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

public void encodeShort(short aShort)

Encodes aShort.

This method must be matched by a subsequent decodeShort message.



replaceObject

public void replaceObject( Object object, Object newObject)

Causes the NSArchiver to treat subsequent requests to encode object as though they were requests to encode newObject. Both object and newObject must be valid objects.

versionForClassName

public int versionForClassName(String aString)

Description forthcoming.


Table of Contents