// Codable.java
// By Ned Etcode
// Copyright 1995, 1996 Netscape Communications Corp.  All rights reserved.

package netscape.util;

/** The Codable interface describes the methods that an object must implement
  * to encode and decode its essential state. An object describes its essential
  * state through a set of key-value pairs, where the keys are strings and the
  * values are one of the primitive Codable types listed below. The order in
  * which the key-value pairs are used is not important. However, it is more
  * efficient to encode and decode them in the same order as the
  * <b>addField()</b> declarations in the class' <b>describeClassInfo()</b>
  * method. The follwing sample shows how a View subclass might encode itself:
  *
  * <pre>
  *     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();
  *         }
  *    }
  * </pre>
  *
  * <i><b>Note:</b> To be Codable, an object must be public and must implement
  * a public empty constructor.  This empty constructor is called to create the
  * object prior to a call to its <b>decode()</b> method.</i>
  *
  * @see Encoder
  * @see Decoder
  * @see Archiver
  * @see Unarchiver
  * @see ClassInfo
  */

public interface Codable {
    /** Primitive Codable type.
      */
    public static final byte BOOLEAN_TYPE       =  0;
    /** Primitive Codable type.
      */
    public static final byte BOOLEAN_ARRAY_TYPE =  1;
    /** Primitive Codable type.
      */
    public static final byte CHAR_TYPE          =  2;
    /** Primitive Codable type.
      */
    public static final byte CHAR_ARRAY_TYPE    =  3;
    /** Primitive Codable type.
      */
    public static final byte BYTE_TYPE          =  4;
    /** Primitive Codable type.
      */
    public static final byte BYTE_ARRAY_TYPE    =  5;
    /** Primitive Codable type.
      */
    public static final byte SHORT_TYPE         =  6;
    /** Primitive Codable type.
      */
    public static final byte SHORT_ARRAY_TYPE   =  7;
    /** Primitive Codable type.
      */
    public static final byte INT_TYPE           =  8;
    /** Primitive Codable type.
      */
    public static final byte INT_ARRAY_TYPE     =  9;
    /** Primitive Codable type.
      */
    public static final byte LONG_TYPE          = 10;
    /** Primitive Codable type.
      */
    public static final byte LONG_ARRAY_TYPE    = 11;
    /** Primitive Codable type.
      */
    public static final byte FLOAT_TYPE         = 12;
    /** Primitive Codable type.
      */
    public static final byte FLOAT_ARRAY_TYPE   = 13;
    /** Primitive Codable type.
      */
    public static final byte DOUBLE_TYPE        = 14;
    /** Primitive Codable type.
      */
    public static final byte DOUBLE_ARRAY_TYPE  = 15;
    /** Primitive Codable type.
      */
    public static final byte STRING_TYPE        = 16;
    /** Primitive Codable type.
      */
    public static final byte STRING_ARRAY_TYPE  = 17;
    /** Primitive Codable type.
      */
    public static final byte OBJECT_TYPE        = 18;
    /** Primitive Codable type.
      */
    public static final byte OBJECT_ARRAY_TYPE  = 19;


    /** Classes must be able to describe their schema to be encoded. They
      * must call <b>super.describeClassInfo()</b> and then add their own
      * information via <b>info.addClass()</b> and <b>info.addField()</b>.
      * @see ClassInfo
      */
    public void describeClassInfo(ClassInfo info);

    /** Called to encode the object. The object should describe its
      * state to the encoder.
      * @see Encoder
      * @see Archiver
      */
    public void encode(Encoder encoder) throws CodingException;

    /** Called immediately after the object's empty constructor, to restore
      * the object's state using data contained in the decoder.
      * @see Decoder
      * @see Unarchiver
      */
    public void decode(Decoder decoder) throws CodingException;

    /** Because objects retrieved from <b>decodeObject()</b> might not have
      * been fully initialized, this method gives newly created instances an
      * opportunity to talk to other objects just after <b>decode()</b> has
      * been called on all of them.
      * @see Decoder
      * @see Unarchiver
      */
    public void finishDecoding() throws CodingException;
}