Module Interface ADT:Storable

SUMMARY: MODULE | CLASS | TYPE | PROC | VAR | CONST | DETAIL: TYPE | PROC | VAR | CONST

# ADT:Storable

The module defines new binary rider classes, which are extensions of the ones defined in module BinaryRider. Concrete implementations of these abstract classes (like module ADT:Object:Storage) provide the mechanisms necessary to externalize and internalize arbitrary data structures. The riders add some type-bound procedures to the interfaces inherited from BinaryRider, and rely on the type-bound procedures Object.Store and Object.Load to store and load an object's private data.

### Import List

        Exception
        IO
        IO:BinaryRider
        Object
        Object

Class List
Object | This class defines a protocol for object persistence using with Object.Store and Object.Load).
Reader | Reader defines the infrastructure for reading of serialized object data.
TypeError |
Writer | Reader defines writing of serialized object data.

Class Summary: Object [Detail]
      +---Object.Object
           |
           +--ADT:Storable.Object
This class defines a protocol for object persistence using with Object.Store and Object.Load).
Method Summary
Load(Reader) Loads data of obj from r.
Store(Writer) Stores data of obj to w.
Inherited Methods
From Object.Object: Equals, HashCode, ToString

Class Summary: Reader [Detail]
      +---IO:BinaryRider.Reader
           |
           +--ADT:Storable.Reader
Reader defines the infrastructure for reading of serialized object data. Its primary task is to add the method Reader.ReadObject to the class BinaryRider.Reader. Together with Object.Load it handles conversion of byte sequences back into living objects. This is an abstract class. For a concrete implementation, see ADT:Object:Storage.Reader.
Inherited Fields
From IO:BinaryRider.Reader: byteOrder, channel
Constructor Summary
InitReader(Reader, ByteChannel) Initializes a new reader instance r for channel ch.
Method Summary
Disconnect() Disconnects reader r, and cleans up the internal data structures.
ReadObject(VAR Object) Reads an object reference from the channel underlying the reader r.
Inherited Methods
From IO:BinaryRider.Reader: ReadBool, ReadBytes, ReadChar, ReadInt, ReadLChar, ReadLInt, ReadLReal, ReadLString, ReadNum, ReadReal, ReadSInt, ReadSet, ReadStr, ReadString, SetByteOrder, SetPos

Class Summary: TypeError [Detail]
      +---Exception.Exception
           |
           +---IO.Error
                |
                +--ADT:Storable.TypeError
Inherited Methods
From Exception.Exception: GetMessage, Name, WriteBacktrace From IO.Error: INIT

Class Summary: Writer [Detail]
      +---IO:BinaryRider.Writer
           |
           +--ADT:Storable.Writer
Reader defines writing of serialized object data. It defines Reader.ReadObject, which together with Object.Store handles serialization of objects into byte streams. This is an abstract class. For a concrete implementation, see ADT:Object:Storage.Writer.
Inherited Fields
From IO:BinaryRider.Writer: byteOrder, channel
Constructor Summary
InitWriter(Writer, ByteChannel) Initializes a new writer instance w for channel ch.
Method Summary
Disconnect() Completes the data written to the channel of writer w, and cleans up the internal data structures.
WriteObject(Object) Writes object to the channel underlying the writer w.
Inherited Methods
From IO:BinaryRider.Writer: SetByteOrder, SetPos, WriteBool, WriteBytes, WriteChar, WriteInt, WriteLChar, WriteLInt, WriteLReal, WriteLString, WriteNum, WriteReal, WriteSInt, WriteSet, WriteStr, WriteString

Procedure Summary
RaiseTypeError(STRING)

Class Detail: Object

Method Detail

### Load

    PROCEDURE (obj: Object) Load(r: Reader)
      RAISES Error;

> Loads data of obj from r. Nested record pointers are loaded by calling the type-bound procecdure Reader.ReadObject. This procedure must be symmetric to Object.Store, or data internalization will break, causing undefined object state or program termination.

> Note: When internalizing a file with alien objects, it is possible that the type-bound procedure Object.Load is invoked more than once for a single object. Except for the results of the last call, all duplicates are discarded. Because of this, all changes by this procedure to any program state that is not part of the object obj are deprecated.

> Pre-condition: This procedure is either activated by a super call, or from the procedure Reader.ReadObject.

### Store

    PROCEDURE (obj: Object) Store(w: Writer)
      RAISES Error;

> Stores data of obj to w. Nested record pointers are stored by calling the type-bound procedure Writer.WriteObject. The procedure is not allowed to make any changes to the global state of the program, except for calling the ``Write`' methods of the writer w. Any redefinition of this procedure must include a super call, preferably as the first statement of the procedure body.

> Pre-condition: This procedure is either activated by a super call, or from the procedure Writer.WriteObject.

Class Detail: Reader

Constructor Detail

### InitReader

    PROCEDURE InitReader(r: Reader;
                         ch: ByteChannel)

> Initializes a new reader instance r for channel ch. Little endian byte ordering is used by the reader.

Method Detail

### Disconnect

    PROCEDURE (r: Reader) Disconnect()

> Disconnects reader r, and cleans up the internal data structures. Any resources allocated by the reader are freed.

### ReadObject

    PROCEDURE (r: Reader) ReadObject(VAR obj: Object)
      RAISES Error;

> Reads an object reference from the channel underlying the reader r. The object obj itself is required to provide the necessary type-bound procedure Object.Load to restore its own data from r.

Class Detail: TypeError

Class Detail: Writer

Constructor Detail

### InitWriter

    PROCEDURE InitWriter(w: Writer;
                         ch: ByteChannel)

> Initializes a new writer instance w for channel ch. Little endian byte ordering is used by the writer.

Method Detail

### Disconnect

    PROCEDURE (w: Writer) Disconnect()

> Completes the data written to the channel of writer w, and cleans up the internal data structures. Without calling Writer.Disconnect the externalized objects may be left in a invalid state, and no new externalization process can be started. After Writer.Disconnect, all operations on w are undefined.

### WriteObject

    PROCEDURE (w: Writer) WriteObject(obj: Object)
      RAISES Error;

> Writes object to the channel underlying the writer w. The externalization framework is provided by the concrete instance of writer w. The object itself is required to provide the necessary type-bound procedure Object.Store to pass its own data to w.

> Pre-condition: obj is NIL, or it is an instance of Object.

Procedure Detail

### RaiseTypeError

    PROCEDURE RaiseTypeError(msg: STRING)
      RAISES TypeError;