Oberon || Library || Module Index || Search Engine || Definition || Module

Ulm's Oberon Library:
PersistentDisciplines

NAME

PersistentDisciplines - attach additional data structures to persistent objects

SYNOPSIS

TYPE Identifier = LONGINT;
TYPE Discipline = POINTER TO DisciplineRec;
TYPE DisciplineRec =
   RECORD
      (PersistentObjects.ObjectRec)
      id: Identifier;
   END;
TYPE Object = POINTER TO ObjectRec;
TYPE ObjectRec =
   RECORD
      (PersistentObjects.ObjectRec)
   END;
TYPE AddProc = PROCEDURE (object: Disciplines.Object; discipline: Discipline);
TYPE RemoveProc = PROCEDURE (object: Disciplines.Object; id: Identifier);
TYPE SeekProc = PROCEDURE (object: Disciplines.Object; id: Identifier;
                           VAR discipline: Discipline) : BOOLEAN;
TYPE Interface = POINTER TO InterfaceRec;
TYPE InterfaceRec =
   RECORD
      (Objects.ObjectRec)
      add: AddProc;
      remove: RemoveProc;
      seek: SeekProc;
   END;



PROCEDURE Unique(sample: Discipline) : Identifier;
PROCEDURE GetSample(id: Identifier) : Discipline;
PROCEDURE AttachInterface(object: Disciplines.Object; if: Interface);
PROCEDURE UseInterfaceOf(object, host: Disciplines.Object);
PROCEDURE Add(object: Disciplines.Object; discipline: Discipline);
PROCEDURE Remove(object: Disciplines.Object; id: Identifier);
PROCEDURE Seek(object: Disciplines.Object; id: Identifier;
               VAR discipline: Discipline) : BOOLEAN;
PROCEDURE CreateObject(VAR object: Object);

DESCRIPTION

PersistentDisciplines allows to attach additional data structures to persistent objects. These added data structures are also persistent and they are written/read to/from a stream together with the object they are attached to.

Every module which implements a discipline should call Unique during its initialization. The returned identifier is needed later to locate the data structures contributed by a specific module. Note that identifiers are always local to the current process environment. Thus, identifiers must not be marshalled by the read or write interface procedure for PersistentObjects. Instead, identifiers are to be assigned by the create procedure.

Unique requires a sample of the discipline to be provided. This technique allows to map local identifiers to remote identifiers in case of remote objects. For this to work, PersistentObjects.Init must have been called for the sample. GetSample returns the sample for a given identifier. Invalid identifiers cause NIL to be returned.

Add attaches discipline to object. The identifier is given by the id component of discipline. Adding a discipline with the same identifier twice to the same object causes the discipline to be replaced.

Remove removes the discipline with the given id from object, if it exists.

Seek seeks for a discipline with the given id and returns it in discipline, if it exists. Otherwise, FALSE is returned.

Usually, PersistentDisciplines uses builtin implementations of Add, Remove, and Seek. These default implementations may be overridden by calling AttachInterface. Calls of AttachInterface are ignored if the list of already attached disciplines is non-empty. AttachInterface is mainly intended for proxy objects, i.e. objects which forward all messages to the original object which may be located elsewhere.

UseInterfaceOf causes all Add, Remove, and Seek operations to be forwarded from object to host. Note that PersistentDisciplines supports Forwarders, i.e. Forwarders.Forward calls UseInterfaceOf implicitly.

CreateObject creates a new object. This procedure should be used instead of NEW, if you want to create an object of type Object.

AUTHORS

The original implementation and manual page was written 1993 by Detlef Birkholz. The revisions are due to Andreas Borchert.

Edited by: borchert, last change: 1996/09/16, revision: 1.10, converted to HTML: 1997/04/28