Interface Codable
All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface Codable

public interface netscape.util.Codable
{
    /* Fields
     */
    public final static byte BOOLEAN_ARRAY_TYPE;
    public final static byte BOOLEAN_TYPE;
    public final static byte BYTE_ARRAY_TYPE;
    public final static byte BYTE_TYPE;
    public final static byte CHAR_ARRAY_TYPE;
    public final static byte CHAR_TYPE;
    public final static byte DOUBLE_ARRAY_TYPE;
    public final static byte DOUBLE_TYPE;
    public final static byte FLOAT_ARRAY_TYPE;
    public final static byte FLOAT_TYPE;
    public final static byte INT_ARRAY_TYPE;
    public final static byte INT_TYPE;
    public final static byte LONG_ARRAY_TYPE;
    public final static byte LONG_TYPE;
    public final static byte OBJECT_ARRAY_TYPE;
    public final static byte OBJECT_TYPE;
    public final static byte SHORT_ARRAY_TYPE;
    public final static byte SHORT_TYPE;
    public final static byte STRING_ARRAY_TYPE;
    public final static byte STRING_TYPE;

    /* Methods
     */
    public abstract void decode(Decoder);
    public abstract void describeClassInfo(ClassInfo);
    public abstract void encode(Encoder);
    public abstract void finishDecoding();
}
The Codable interface declares the methods that permit objects of public classes to be archived and restored. If you are writing an application that simply stores and retrieves objects of a codable class (that is, the class implements the Codable interface), you don't need to know the details of the Codable interface. Rather, you use the methods provided by the Archiver and Unarchiver classes to store and retrieve codable objects.

However, if you are providing a class and you want applications to be able to archive and restore objects of that class, you must implement the Codable interface in that class. The methods of the Codable interface, called by Archiver and Unarchiver objects, enable an object to describe its essential characteristics, and encode and decode the state of those characteristics.

When an Archiver object calls the codable object's describeClassInfo() method, the codable object provides its class name and version and a set of key/type pairs. The key is a string defined by the codable object's class that labels a characteristic of object of that class. The type is a constant, defined by the Codable interface, that identifies a codable data type.

When an Archiver object calls the codable object's encode() method, the codable object describes its essential state by providing a set of key/value pairs. The key identifies a characteristic previously defined through describeClassInfo(). The value is the current value of the characteristic. Encoding an object refers to reporting its current key/value pairs.

When an object is to be restored from an archive, IFC calls the object's empty constructor and then calls its decode() method to initialize it with the values of the object's characteristics saved in the archive. Note: that classes that support the Codable interface must provide a public empty constructor in order for decoding to work properly.

The View class is codable. If you subclass View, you need to implement the Codable interface to save what is unique about your class.

The following sample shows how a custom subclass of View might encode itself.

public class MyView extends View {
        Codable someObject;
        public MyView() {
        }
        public void describeClassInfo(ClassInfo info) {
                        super.describeClassInfo(info);
                        info.addClass("MyView", 1);
                        info.addField("someObject", OBJECT_TYPE);
        }
        public void encode(Encoder encoder) throws CodingException {
                        super.encode(encoder);
                        encoder.encodeObject("someObject", someObject);
        }
        public void decode(Decoder decoder) throws CodingException {
                        super.decode(decoder);
                        someObject = decoder.decodeObject("someObject");
        }
        public void finishDecoding() throws CodingException {
                        super.finishDecoding();
        }
}
See Also:
Encoder, Decoder, Archiver, Unarchiver, ClassInfo

Fields

BOOLEAN_TYPE

  public final static byte BOOLEAN_TYPE
The codable data type constant specifying data of type boolean.

BOOLEAN_ARRAY_TYPE

  public final static byte BOOLEAN_ARRAY_TYPE
The codable data type constant specifying an array of data of type boolean.

CHAR_TYPE

  public final static byte CHAR_TYPE
Primitive Codable type.

CHAR_ARRAY_TYPE

  public final static byte CHAR_ARRAY_TYPE
Primitive Codable type.

BYTE_TYPE

  public final static byte BYTE_TYPE
The codable data type constant specifying data of type byte.

BYTE_ARRAY_TYPE

  public final static byte BYTE_ARRAY_TYPE
The codable data type constant specifying an array of data of type byte.

SHORT_TYPE

  public final static byte SHORT_TYPE
The codable data type constant specifying data of type short.

SHORT_ARRAY_TYPE

  public final static byte SHORT_ARRAY_TYPE
The codable data type constant specifying an array of data of type short.

INT_TYPE

  public final static byte INT_TYPE
The codable data type constant specifying data of type int.

INT_ARRAY_TYPE

  public final static byte INT_ARRAY_TYPE
The codable data type constant specifying an array of data of type int.

LONG_TYPE

  public final static byte LONG_TYPE
The codable data type constant specifying data of type long.

LONG_ARRAY_TYPE

  public final static byte LONG_ARRAY_TYPE
The codable data type constant specifying an array of data of type long.

FLOAT_TYPE

  public final static byte FLOAT_TYPE
The codable data type constant specifying data of type float.

FLOAT_ARRAY_TYPE

  public final static byte FLOAT_ARRAY_TYPE
The codable data type constant specifying an array of data of type float.

DOUBLE_TYPE

  public final static byte DOUBLE_TYPE
The codable data type constant specifying data of type double.

DOUBLE_ARRAY_TYPE

  public final static byte DOUBLE_ARRAY_TYPE
The codable data type constant specifying an array of data of type double.

STRING_TYPE

  public final static byte STRING_TYPE
The codable data type constant specifying data of type string.

STRING_ARRAY_TYPE

  public final static byte STRING_ARRAY_TYPE
The codable data type constant specifying an array of data of type string.

OBJECT_TYPE

  public final static byte OBJECT_TYPE
The codable data type constant specifying object data.

OBJECT_ARRAY_TYPE

  public final static byte OBJECT_ARRAY_TYPE
The codable data type constant specifying an array of objects.

Methods

.describeClassInfo

  public abstract void describeClassInfo(ClassInfo info)
Defines the key/type pairs that describe the essential characteristics of a class. Typically, this method is called by an IFC Archiver object, not an application.

Each class that can be archived has a schema that defines the critical information to be saved for a given instance of that class. This method provides the field names and Codable data types that define the information to be archived for object of a given classs, along with the class name and class version. The field names frequently correspond to the instance variables in the class.

If you are providing a new class that you want to be archivable, you implement describeClassInfo() to describe the key characteristics of your class. If your class is a subclass of a Codable class, first call super.describeClassInfo() to allow the superclass to add its class name, class version, and key/type pairs. Then call info.addClass() and info.addField() to add the key/type pairs that describe your class.

Note that because subclasses of your class can call this method, it might be invoked multiple times. As a result, describeClassInfo() should not contain any code that should not be executed more than once.

See the sample code in the class description.

Parameters:
info - A ClassInfo object that describes the schema to encode the class. The called object populates the instance with the information for its class.
See Also:
ClassInfo, Archiver

.encode

  public abstract void encode(Encoder encoder) throws CodingException
Encodes the essential state of an object. This method is called by an Archiver object to obtain the key/value pair information that defines the called object's current state.

An object of a class that implements this method calls the appropriate Encoder methods to provide key/value pair information for the characteristics defined by its describeClassInfo() method.

The order in which an object encodes its key/value pairs is not important. However, it is more efficient to encode them in the same order that the keys are added in describeClassInfo().

See the class description for information about key/value pairs.

Parameters:
encoder - An Encoder object that stores state information for an object to be archived. The called object populates the instance with information about its state.
Throws: CodingException
Occurs when the object cannot be encoded completely.
See Also:
Encoder, Archiver

.decode

  public abstract void decode(Decoder decoder) throws CodingException
Restores an archived object's essential state. Typically, an Archiver object calls this method immediately after calling the archived object's empty constructor. The new object then restores the saved state by calling the appropriate Decoder methods.

When implementing this method, you can restore your object's key/value pairs in any order. However, it is most efficient to decode them in the same order that you add the keys in the describeClassInfo() method.

Parameters:
decoder - A Decoder object containing the saved state information for the object to be restored.
Throws: CodingException
Occurs when the object cannot be decoded completely.
See Also:
Decoder, Unarchiver

.finishDecoding

  public abstract void finishDecoding() throws CodingException
Gives a restored object an opportunity to communicate with its related objects after all have been decoded. When an object containing a reference to another encoded object is restored from an archive, the referenced object may not be fully initialized. This method provides an opportunity to complete the initialization. More specifically, objects retrieved from decodeObject() might not have been fully initialized, so finishDecoding() gives newly created instances an opportunity to talk to other objects just after decode() hasbeen called on all of them.
Throws: CodingException
Occurs when the object cannot be encoded completely.
See Also:
Decoder, Unarchiver

All Packages  Class Hierarchy  This Package  Previous  Next  Index

Copyright © 1997 Netscape Communications Corporation. All rights reserved
Please send any comments or corrections to ifcfeedback@netscape.com
HTML generated on 21 Oct 1997