PATH  Documentation > Mac OS X > Foundation Reference: Java



Table of Contents

NSCoder


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


Class Description


The NSCoder abstract class declares the interface used by concrete subclasses to transfer objects and other data items between memory and some other format. This capability provides the basis for archiving (where objects and data items are stored on disk) and distribution (where objects and data items are copied between different processes or threads). The concrete subclasses provided by Foundation for these purposes are NSArchiver and NSUnarchiver. Concrete subclasses of NSCoder are referred to in general as coder classes, and instances of these classes as coder objects (or simply coders). A coder object that can only encode values is referred to as an encoder object, and one that can only decode values as a decoder object.

NSCoder operates on id's, scalars, arrays, structures, and strings, and on pointers to these types. It does not handle types whose implementation varies across platforms function pointers, and long chains of pointers. It can also operate on user-defined structures as well as pointers to any of these data types. A coder object stores object type information along with the data, so an object decoded from a stream of bytes is normally of the same class as the object that was originally encoded into the stream.


Encoding and Decoding Objects and Data Items


To encode or decode an object or data item, you must first create a coder object, then send it a message defined by NSCoder or by a concrete subclass to actually encode or decode the item. NSCoder itself defines no particular method for creating a coder; this typically varies with the subclass.

To encode an object or data item, use any of the encode... methods..

To decode an object or data item, simply use the decode... method corresponding to the original encode... method (as given in the individual method descriptions). Matching these is important, as the method originally used determines the format of the encoded data.

NSCoder's interface is quite general. Concrete subclasses aren't required to properly implement all of NSCoder's methods, and may explicitly restrict themselves to certain types of operations. For example, NSArchiver doesn't implement the decode... methods, and NSUnarchiver doesn't implement the encode... methods.


Managing Object Graphs


Objects frequently contain pointers to other objects, which may in turn contain pointers to other objects. When analyzed, a group of objects may contain circular references or one object may be referred to by several other objects. In these cases, the objects form an object graph and require special encoding methods to preserve the graph structure. NSCoder declares the following method to manage object graphs: encodeObject.

See the NSArchiver class specification for more information on managing object graphs.


Creating a Subclass of NSCoder


If you define a subclass of NSCoder, at a minimum your subclass must override the following methods:

encodeDataObject
decodeDataObject

In addition, your subclass may override other methods to provide specialized handling for certain situations. In particular, you can implement any of the following methods:

decodeObject

See the individual method descriptions for more information. See also the NSArchiver class specification for an example of a concrete subclass.

With objects, the object being coded is fully responsible for coding itself. However, a few classes hand this responsibility back to the coder object, either for performance reasons or because proper support depends on more information than the object itself has. The notable class in Foundation that does this is NSData. NSData's low-level nature makes optimization important. For this reason, an NSData object always asks its coder to handle its contents directly using the encodeDataObject and decodeDataObject methods described in this class specification.

An implementor of a concrete coder subclass, however, must encode NSData objects itself. Failure to do so can result in an infinite loop.




Method Types


Constructors
NSCoder
Encoding data
encodeByte
encodeChar
encodeDataObject
encodeDouble
encodeFloat
encodeInt
encodeLong
encodeObject
encodeShort
Decoding data
decodeByte
decodeChar
decodeDataObject
decodeDouble
decodeFloat
decodeInt
decodeLong
decodeObject
decodeShort
Getting version information
systemVersion
versionForClassName


Constructors



NSCoder

public NSCoder()

Description forthcoming.


Instance Methods



decodeByte

public abstract byte decodeByte()

Decodes and returns an byte structure that was previously encoded with encodeByte. Subclasses must override this method.

decodeChar

public abstract char decodeChar()

Decodes and returns an char structure that was previously encoded with encodeChar. Subclasses must override this method.

decodeDataObject

public abstract NSData decodeDataObject()

Must be overridden by subclasses to decode and return an NSData object.

The implementation of your overriding method must match the implementation of your encodeDataObject method. For example, a typical encodeDataObject method encodes the number of bytes of data followed by the bytes themselves. Your override of this method must read the number of bytes, create an NSData object of the appropriate size, and decode the bytes into the new NSData object. Your overriding method should return an NSData object.



decodeDouble

public abstract double decodeDouble()

Decodes and returns an double structure that was previously encoded with encodeDouble. Subclasses must override this method.

decodeFloat

public abstract float decodeFloat()

Decodes and returns an float structure that was previously encoded with encodeFloat. Subclasses must override this method.

decodeInt

public abstract int decodeInt()

Decodes and returns an int structure that was previously encoded with encodeInt. Subclasses must override this method.

decodeLong

public abstract long decodeLong()

Decodes and returns an long structure that was previously encoded with encodeLong. Subclasses must override this method.



decodeObject

public abstract Object decodeObject()

Decodes an object that was previously encoded with any of the encode... methods.

Subclasses must override this method.

See Also: encodeObject



decodeShort

public abstract short decodeShort()

Decodes and returns an short structure that was previously encoded with encodeShort. Subclasses must override this method.

encodeByte

public abstract void encodeByte(byte aByte)

Encodes aByte.Subclasses must override this method.

This method must be matched by a subsequent decodeByte message.



encodeChar

public abstract void encodeChar(char aChar)

Encodes aChar.Subclasses must override this method.

This method must be matched by a subsequent decodeChar message.



encodeDataObject

public abstract void encodeDataObject(NSData data)

Must be overridden by subclasses to encode the NSData object data. This method must be matched by a subsequent decodeDataObject message.

See Also: encodeObject



encodeDouble

public abstract void encodeDouble(double aDouble)

Encodes aDouble.Subclasses must override this method.

This method must be matched by a subsequent decodeDouble message.



encodeFloat

public abstract void encodeFloat(float aFloat)

Encodes aFloat.Subclasses must override this method.

This method must be matched by a subsequent decodeFloat message.



encodeInt

public abstract void encodeInt(int anInt)

Encodes anInt.Subclasses must override this method.

This method must be matched by a subsequent decodeInt message.



encodeLong

public abstract void encodeLong(long aLong)

Encodes aLong.Subclasses must override this method.

This method must be matched by a subsequent decodeLong message.





encodeObject

public abstract void encodeObject(Object object)

Encodes object. NSCoder's implementation simply invokes encodeValueOfObjCType:at: to encode the object. Subclasses must override this method. For example, NSArchiver detects duplicate objects and encodes a reference to the original object rather than encode the same object twice.

This method must be matched by a subsequent decodeObject message.



encodeShort

public abstract void encodeShort(short aShort)

Encodes aShort.Subclasses must override this method.

This method must be matched by a subsequent decodeShort message.



systemVersion

public int systemVersion()

During encoding, this method should return the system version currently in effect. During decoding, this method should return the version that was in effect when the data was encoded.

By default, this method returns the current system version, which is appropriate for encoding but not for decoding. Subclasses that implement decoding must override this method to return the system version of the data being decoded.



versionForClassName

public abstract int versionForClassName(String className)

Must be overridden by subclasses to return the version in effect for the class named className when it was encoded. Returns NotFound if no class named className exists in the archive.


Table of Contents