8.80. File tom/coding

class tom.ObjectCoder

ObjectCoder is a workaround for circular hierarchy - it is only a placeholder for methods called from State (Coding).

inherits

State supers: Conditions, Constants

methods


void
  encodeObject State obj
    usingCoder Encoder coder;

Undocumented.


void
  initObject State obj
  usingCoder Decoder coder;

Undocumented.

instance tom.ObjectCoder

class tom.State (Coding)

This extension of State defines the functionality for encoding and decoding objects. To be able to encode an object, it must at least properly implement encodeUsingCoder. Similarly, to be decodable, it must implement initWithCoder.

The unit of archiving is a class, not an extension. This means that if an extension adds state information which needs to be archived (or encoded onto a too.PortCoder), the extension must re-implement the coding methods.

variables

public mutable boolean encode_simply;

Classes that want to be encoded in the obvious way, by writing the values of their variables, set this to TRUE.

methods


int
  version;

Return the current version of the class cls. This is the version that will be written when coding instances of this class or a subclass thereof. The default version is 0.

A version should only be returned if self is identical to the class containing the method definition, i.e. the method is not inherited. Otherwise, the two are unequal, and the version of a subclass is requested that does not implement this method, and hence should return version 0.


boolean
  never-encode-simply-p;

Return YES if encode_simply of all classes involved in the receiving object will always return FALSE. Coding is sped up tremendously in that case. The defaultis NO, to not speed up and allow for passive encoding.


boolean
  persistent-coding-p;

Return YES.

instance tom.State (Coding)

methods


class (State)
  classForCoder Encoder coder;

Return the class to be put in the coded stream as the class of this object. The default implementation simply returns isa, which is the receiving object's class.


void
  encodeUsingCoder Encoder coder;

Encode the receiving object to the target coder. Every object should first invoke this method of all its direct superclasses before encoding its instance variables, but only if hasBeenCodedFor for the class implementing the method returns FALSE. For classes that set encode_simply to TRUE, this method will use introspection to encode the class variables.


boolean
  never-encode-simply-p;

Return YES if encode_simply of all classes involved in the receiving object will always return FALSE. Coding is sped up tremendously in that case.


boolean
  persistent-coding-p;

Return NO.


Any (self)
  replacementForStreamCoder StreamEncoder coder;

Return the object to be encoded on the StreamEncoder coder (i.e. archived or wired) instead of the receiving object. The default implementation simply returns self.


void
  initWithCoder Decoder coder;

Initialize the receiving object from the coder. After verifying that this method implementation has not yet been invoked (using hasBeenCodedFor), this method should invoke the implementation of this method by the superclasses, followed the fields that were encoded by this class. Decoding must be done in the same order as encoding. Default implementation on State will use introspection to init the objects that requested it by setting encode_simply on their class to TRUE.

Note that this method returns void. An object can change the actual object returned from decoding by implementing awakeAfterUsingCoder.


id (self)
  awakeAfterUsingCoder Decoder coder;

Return the object to be the object retrieved from decoding instead of the receiving object. The default implementation returns self.

Objects can use this method to return their administered counterpart, like UniqueString objects do.

Note that if an object is referenced during its decoding (i.e. object A is referenced by an object B which is decoded because B is (indirectly) referenced by A), it must not return a different object from awakeAfterUsingCoder. If it does, a coding-condition is raised.

class tom.Coder

inherits

State supers: State, Conditions

methods


int
  version;

The version of the coding scheme used. The current version is 0.

instance tom.Coder

methods


void
  willCodeVariable String name
         forObject All object
       inExtension Extension x;

Notify the coder object about the variable being coded. This allows primitive form of state versioning control. Note that there are no guarantees that every class will send this notification while encoding itself.


void
  willCodeExtension Extension x
          forObject All object;

Notify the coder of the extension being coded. There are no guarantees that every class will send this notification.


void
  doneCodingExtension Extension x;

Notify the coder that the coding of the extension x is finished.

class tom.BinaryCoder

The BinaryCoder classes BinaryEncoder and BinaryDecoder can archive dearchive a graph of objects in a binary form onto/from a stream. The format is rather simple: Every item stored is preceded by a tag byte indicating what the next item is. There are a few secondary tags to introduce classes, etc.

Every instance or class written is internally numbered in the order the objects are written. References to these objects are encoded in the number of bytes necessary for the number of currently known objects. The secondary tags 2 and 4 switch to 2 and 4 byte reference encoding, respectively.

The nil object is denoted by the 0 tag.

Selectors are encoded as a tag S, followed by the assigned selector number (which is an int, starting at 1) and the corresponding Selector object. Selectors already encoded are denoted by a tag s and the int selector number. The invalid selector (the default value of selector typed variables, also available as [Runtime nullSelector]) is identified by the tag s followed by 0 as the selector number.

inherits

State supers: Coder

instance tom.BinaryCoder

variables

int reference_size;

The number of bytes issued for a reference. This starts with 1 (a byte), and can become 2 (a char) or 4 (an int).

methods


id
  init;

Undocumented.

class tom.Encoder

inherits

State supers: Coder

instance tom.Encoder

variables

MutableEqDictionary tmp_objects_done;

Keyed on the objects already encoded, the value is the identifier (which is an IntNumber) used for this object. This dict only contains temporary objects, i.e. objects that can be forgotten about after each encodeRoot.

MutableEqDictionary perm_objects_done;

Similar, the non-temporary objects. This includes class objects and Selector objects.

MutableEqSet objects_skipped;

The set of conditional objects that were skipped.

MutableEqSet coded_classes;

The classes which, for the current object, have already done their part in the coding.

int last_object_id;

The most recently issued object identifier.

methods


void
  encodeRoot State object;

The main entry Encoder method: encode the object and the whole object graph implied by it. This method is not reentrant.


id
  init;

Designated initializer.


boolean
  hasBeenCodedFor class (State) the_class;

Return NO if the object currently being encoded on this coder has not yet been encoded for the_class. Return YES otherwise. While coding an object, only the first invocation for a certain the_class will return YES; subsequent invocations will return NO.


void
  encode State object;

Encode the object, unconditionally.


void
  encodeConditionally State object;

Encode the object, but only if it already is part of the output graph. If this is not the case, nil is encoded, and if later on in the coding process the object previously encoded as nil is encountered (unconditionally), a program-condition will be raised to flag the inconsistency.


deferred void
  encode boolean v;

Encode the boolean v.


deferred void
  encode byte v;

Encode the byte v.


deferred void
  encode char v;

Encode the char v.


deferred void
  encode int v;

Encode the int v.


deferred void
  encode long v;

Encode the long v.


deferred void
  encode float v;

Encode the float v.


deferred void
  encode double v;

Encode the double v.


deferred void
  encode selector v;

Encode the selector v.


deferred void
  encodeBytes (int, int) (start, length)
         from ByteArray r
pre
  start >= 0 && length >= -1;

Encode the bytes in the range (start, length) from the array r.


deferred void
  encodeBytes (pointer, int) (address, length);

Encode the length bytes of which the first one resides at the address.


deferred protected State
  replacementObjectFor State object;

Return the object to be encoded to this coder instead of the object. This method is implemented by subclasses to retrieve the actual object from the object itself, for instance by asking for it replacementForStreamCoder or replacementForPortCoder.


deferred protected void
  encodeNilObject;

Encode the nil reference.


deferred protected void
  encodeReference int v;

Encode a reference to the object known as v.


protected int
  identityFor All object;

Return the identity to be used for the non-class object. This returns the next value of last_object_id.


protected int
  identityForClass class (State) a_class;

Return the identity to be used for the class object a_class. This returns the next value of last_object_id.


class (State)
  startEncoding State object;

Undocumented.


protected void
  finishEncoding All object;

Invoked when the object has been encoded. Default does nothing.


protected void
  startEncodingRoot All object;

Invoked when coding starts with the root object. Default does nothing.


protected void
  finishEncodingRoot All object;

Invoked when coding the root object has finished. Default does nothing.

class tom.BinaryEncoder

inherits

State supers: BinaryCoder, Encoder

instance tom.BinaryEncoder

variables

MutableDictionary selectors;

The selector dictionary, from Selector to IntNumber.

methods


id
  init;

Designated initializer.


class (State)
  startEncoding State object;

Undocumented.


protected void
  finishEncoding All object;

Invoked when the object has been encoded. Emit a close paren.


protected void
  updateReferenceSize;

Undocumented.


protected int
  identityFor All object;

Undocumented.


protected int
  identityForClass class (State) a_class;

Identify this class on the output stream, reporting its coding version.


protected void
  encodeNilObject;

Undocumented.


protected void
  encodeReference int v;

Undocumented.


void
  encode boolean v;

Undocumented.


void
  encode byte v;

Undocumented.


void
  encode char v;

Undocumented.


void
  encode int v;

Undocumented.


void
  encode long v;

Undocumented.


void
  encode float v;

Undocumented.


void
  encode double v;

Undocumented.


void
  encode selector v;

Undocumented.


void
  encodeBytes (pointer, int) (address, length);

Undocumented.


void
  encodeBytes (int, int) (start, length)
         from ByteArray r;

Undocumented.


protected void
  writeReference int r
pre
  reference_size == 1 || reference_size == 2 || reference_size == 4;

Undocumented.


deferred protected void
  writeByte byte b;

Undocumented.


deferred protected void
  writeBytes (int, int) (start, length)
        from ByteArray r;

Undocumented.


deferred protected void
  writeBytes (pointer, int) (address, length);

Undocumented.


protected void
  writeChar char c;

Undocumented.


protected void
  writeInt int i;

Undocumented.


protected void
  writeLong long l;

Undocumented.

class tom.Decoder

The Decoder class defines the interface to all decoder classes, be it binary or textual, stream or port base.

inherits

State supers: Coder

instance tom.Decoder

variables

MutableIntDictionary tmp_objects_done;

Objects, indexed on their identity, as retrieved from this coder.

MutableIntDictionary perm_objects_done;

IntegerRangeSet objects_referenced;

The identity of the objects that have been referenced while being decoded.

MutableEqDictionary class_versions;

Mapping from a class to the decoding version of that class.

MutableEqSet coded_classes;

The classes which, for the current object, have already done their part in the coding.

methods


id
  init;

Designated initializer.


Any
  decodeRoot;

This is the entry point for the user of this decoder. The user invokes decodeRoot to retrieve an object, plus its underlying graph, from this decoder. The object is returned.


boolean
  hasBeenCodedFor class (State) the_class;

Return NO if the object currently being decoded on this coder has not yet been decoded for the_class. Return YES otherwise. While coding an object, only the first invocation for a certain the_class will return YES; subsequent invocations will return NO.


int
  versionOfClass class (State) cls
pre
  class_versions[cls] != nil;

Return the version of the class cls as encountered by this coder. The version can only be retrieved of classes already encountered curing the decoding process.


deferred Any
  decode;

Retrieve an object from this decoder and return it.


deferred boolean
  decode;

Undocumented.


deferred byte
  decode;

Undocumented.


deferred char
  decode;

Undocumented.


deferred int
  decode;

Undocumented.


deferred long
  decode;

Undocumented.


deferred float
  decode;

Undocumented.


deferred double
  decode;

Undocumented.


deferred selector
  decode;

Undocumented.


deferred (pointer, int)
  decodeBytes;

Decode a sequence of bytes from the coder to newly allocated memory space. Return the address and the length.


deferred void
  decodeBytes int num
           to pointer address;

Decode the num bytes from the coder to the address.


protected Any
  decodeObject class (State) cls
            as int ref;

Undocumented.


protected void
  finishDecoding All o;

Invoked by decodeObject as, after having invoked initWithCoder, but before awakeAfterUsingCoder. The default implementation does nothing.


protected Any
  reference int i;

Return the object referenced as the number i.

class tom.BinaryDecoder

The BinaryDecoder is an abstract decoding class which can decode binary encoded objects. It serves as the decoding engine for the BinaryStreamDecoder and too.PortDecoder.

inherits

State supers: BinaryCoder, Decoder, C

instance tom.BinaryDecoder

variables

MutableArray selectors;

The selectors encountered so far, indexed on their identity.

methods


id
  init;

Designated initializer.


Any
  decode;

Decode and return an object.


Any
  decode byte b;

Decode and return an object, announced by the tag b.


boolean
  decode;

Undocumented.


byte
  decode;

Undocumented.


char
  decode;

Undocumented.


int
  decode;

Undocumented.


long
  decode;

Undocumented.


float
  decode;

Undocumented.


double
  decode;

Undocumented.


selector (result)
  decode;

Undocumented.


(pointer, int)
  decodeBytes;

Undocumented.


void
  decodeBytes int length
           to pointer address;

Undocumented.


protected void
  finishDecoding All o;

Invoked when the object o has been decoded. Read a close paren.


protected byte
  nextPrimary;

Return the next primary tag byte, handling secondary tags such as reference size changes and class declarations.

If an unknown class is encountered, a unknown-class-condition is signaled. A handler may return a replacement class to be used instead. Failure to do so will later on result in a nil-receiver condition or a failed precondition.


protected byte
  nextPrimary byte expected;

Return the next primary tag byte, which must match expected. If it doesn't, a program-condition is raised.


protected int
  readReference
pre
  reference_size == 1 || reference_size == 2 || reference_size == 4;

Read an object reference from this decoder. Depending on the reference_size this read 1, 2, or 4 bytes.


protected Any
  readReference;

Read an object reference from this decoder and return the object referenced. This raises a coding-condition in case not a proper reference is encountered, or if the referenced object is unknown.


deferred protected byte
  readByte;

Return the next single byte.


deferred protected void
  readBytes int num
         to pointer address;

Undocumented.


protected char
  readChar;

Return the next two bytes as a char.


protected int
  readInt;

Return the next four bytes as an int.


protected long
  readLong;

Return the next 8 bytes as a long.