NSCoding

Package:
com.webobjects.foundation

Interface Description

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). See the NSCoder class specification for an introduction to coding.

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 coder provided. 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 and others may be derivable from related state upon decoding. Other instance variables should be encoded only under certain conditions.

For example, suppose you were creating a fictitious MapView class 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 your class does not implement NSCoding, you should omit the line that invokes super's encodeWithCoder method.

encodeObject and encodeInt are coder methods that you can use to encode instance variables of your class. There are other coder methods for other types. The coder also defines corresponding methods for decoding values. See the NSCoder class specification for a list of methods.

Decoding

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 your class does not implement NSCoding, you should simply create a new instance of your class instead of invoking the superclass's decodeObject method.

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 its encoded. The coder uses the class returned by this method instead of the object's actual class.

Static Methods

decodeObject

public static Object decodeObject(NSCoder coder)

Creates an object from the data in coder. Classes that implement the NSCoding interface must also implement this method.

This method isn't strictly part of this interface because static methods can't be formally declared in an interface. However, this method is so closely related to the interface as to be considered part of it.

Instance Methods

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.

encodeWithCoder

public void encodeWithCoder(NSCoder coder)

Encodes the receiver using coder.