com.webobjects.foundation
Interface NSCoding

All Known Implementing Classes:

NSArray, NSNotification, NSSet, NSTimestamp, NSData, NSDictionary, NSKeyValueCoding.Null, NSTimeZone, EONotQualifier, EOAndQualifier, EOFetchSpecification, EOKeyGlobalID, EOKeyValueQualifier, EOQualifierVariable, EOTemporaryGlobalID, EOSortOrdering, EOOrQualifier, EOKeyComparisonQualifier, EODatabaseDataSource, EODistributedClassDescription, EOAttribute, EORelationship

public interface NSCoding

The NSCoding interface declares the methods that a class must implement so that instances of that class can be encoded and decoded. This capability provides the basis for archiving (where objects and other structures are stored on disk) and distribution (where objects are copied to different address spaces).

In keeping with object-oriented design principles, an object being encoded or decoded is responsible for encoding and decoding its instance variables. A coder instructs the object to do so by invoking encodeWithCoder or decodeObject, respectively. encodeWithCoder instructs the object to encode its instance variables to the provided coder. Conversely, decodeObject is the method that creates an object from the data in the coder provided.

The method decodeObject isn't strictly part of the NSCoding interface, but it is required of any class that implements the interface. decodeObject is a static method, and therefore can't be formally declared in the NSCoding interface. Any class that should be codable must adopt the NSCoding interface, implement its methods, and implement the static method decodeObject.

Encoding

When an object receives an encodeWithCoder message, it should encode all of its vital instance variables, after sending a message to super if its superclass also conforms to the NSCoding interface. An object doesn't have to encode all of its instance variables. Some values may not be important to reestablish the state of the object and others may be derivable from related state upon decoding. Still other instance variables should be encoded only under certain conditions. The important concept to keep in mind is the state of the instance that you want to preserve. Thus, you would only encode and decode (or derive from decoded values) all the instance variables that you think are important to preserve the state of the instance.

For example, suppose a fictitious MapView class was being created that displays a legend and a map at various magnifications. The MapView class defines several instance variables, including the name of the map and the current magnification. The encodeWithCoder method of MapView might look like the following:

 public void encodeWithCoder(NSCoder coder) {
    super.encodeWithCoder(coder);
    coder.encodeObject(mapName);
    coder.encodeInt(magnification);
 }
 

This example assumes that the superclass of MapView also implements the NSCoding interface. If the superclass of the class does not implement NSCoding, you should omit the line that invokes super's encodeWithCoder method.

encodeObject and encodeInt are coder methods in NSCoder that you can and should use to encode instance variables of your class. There are other coder methods for other types. Each encode method in NSCoder has a corresponding decode method used for decoding.

Decoding

As mentioned in the introduction, decodeObject is not defined in NSCoding (since it is a static method) but it is really part of the interface that should be defined to support decoding. It must be implemented as a static method in the class in question. The signature of this method is:

 public static Object decodeObject(NSCoder coder)

In decodeObject the class should first send a message to super's implementation of decodeObject (if appropriate) to initialize inherited instance variables. It should then decode and initialize its own. MapView's implementation of decodeObject might look like this:

 
 public static Object decodeObject(NSCoder coder) {
    MapView result = (MapView)(MapView.class.decodeObject(coder));
    result.mapName = (String)coder.decodeObject();
    result.magnification = coder.decodeInt();
    return result;
 }
 

If the superclass of the class does not implement NSCoding, a new instance of the class should simply be created instead of invoking the superclass's decodeObject method. Notice also that the decode methods used corresponds to the encode methods used during encoding.

Making Substitutions During Coding

During encoding a coder allows an object being coded to substitute a different class for itself than the object's actual class. For example, this allows a private class to be represented in a coder by a public class. To allow the substitution, a coder invokes the method classForCoder on the object before it's encoded. The coder uses the class returned by this method instead of the object's actual class for both encoding and decoding.

See Also:

NSCoder, encodeWithCoder(NSCoder coder), NSCoding.Support.decodeObject(NSCoder coder), classForCoder()

Inner Class Summary

static class

NSCoding.Support NSCoding.Support is an abstract class that defines a mechanism for one class to provide NSCoding behavior on behalf of another class.

Method Summary

Class	classForCoder() Allows the receiver, before being encoded, to substitute a class other than its own in a coder.
void	encodeWithCoder(NSCoder coder) Encodes the receiver using coder.

Method Detail

classForCoder

public Class classForCoder()

Allows the receiver, before being encoded, to substitute a class other than its own in a coder. For example, private subclasses can substitute the name of a public superclass when being encoded.

Returns:

the class a coder should record

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

Encodes the receiver using coder. Object type information along with an object's data is stored.

Parameters:

coder - an NSCoder object that will be used to encode object of classes that implement this interface

See Also:

NSCoder