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

Ulm's Oberon Library:
Containers

NAME

SYNOPSIS

TYPE Container = POINTER TO ContainerRec;
TYPE ContainerRec = RECORD (Services.ObjectRec) END;



TYPE Transaction = Transactions.Transaction;
TYPE Ident = LONGINT;
TYPE Object = PersistentDisciplines.Object;



CONST first = 0; last = 1; this = 2; pred = 3; succ = 4;
TYPE SearchDir = SHORTINT; (* first..succ *)



TYPE InsertProc = PROCEDURE (cont: Container; trans: Transaction;
                             VAR id: Ident; object: Object) : BOOLEAN;
TYPE DeleteProc = PROCEDURE (cont: Container; trans: Transaction;
                             id: Ident) : BOOLEAN;
TYPE ReplaceProc = PROCEDURE (cont: Container; trans: Transaction;
                              id: Ident; object: Object) : BOOLEAN;
TYPE ObtainProc = PROCEDURE (cont: Container; trans: Transaction;
                             id: Ident; VAR object: Object) : BOOLEAN;
TYPE ElementsProc = PROCEDURE (cont: Container; trans: Transaction;
                               VAR nelems: LONGINT) : BOOLEAN;
TYPE FindProc = PROCEDURE (cont: Container; trans: Transaction;
                           dir: SearchDir; VAR id: Ident) : BOOLEAN;
TYPE ReorganizeProc = PROCEDURE (cont: Container;
                                 trans: Transaction) : BOOLEAN;
TYPE SetAnchorProc = PROCEDURE (cont: Container; trans: Transaction;
                                id: Ident) : BOOLEAN;
TYPE GetAnchorProc = PROCEDURE (cont: Container; trans: Transaction;
                                VAR id: Ident) : BOOLEAN;
TYPE CloseProc = PROCEDURE (cont: Container) : BOOLEAN;
TYPE Interface = POINTER TO InterfaceRec;
TYPE InterfaceRec =
   RECORD
      (Objects.ObjectRec)
      insert: InsertProc;
      delete: DeleteProc;
      replace: ReplaceProc;
      obtain: ObtainProc;
      elements: ElementsProc;
      find: FindProc;
      reorganize: ReorganizeProc;
      setAnchor: SetAnchorProc;
      getAnchor: GetAnchorProc;
      close: CloseProc;
   END;



CONST insert = 0; delete = 1; replace = 2; obtain = 3;
CONST elements = 4; find = 5; reorganize = 6;
CONST setAnchor = 7; getAnchor = 8; close = 9;
TYPE Capability = SHORTINT; (* insert..close *)
TYPE Operation = SHORTINT;  (* insert..close *)
TYPE CapabilitySet = SET;   (* OF Capability *)



CONST notSupported = 0;
CONST badParams = 1;
CONST alreadyClosed = 2;
CONST operationFailed = 3;
CONST errors = 4;
TYPE ErrorCode = SHORTINT; (* notSupported..operationFailed *)
TYPE ErrorEvent = POINTER TO ErrorEventRec;
TYPE ErrorEventRec =
   RECORD
      (Events.EventRec)
      errcode: ErrorCode;
      operation: Operation;
      trans: Transaction;
   END;
VAR error: Events.EventType;
VAR errormsg: ARRAY errors OF Events.Message;



PROCEDURE Init(cont: Container; if: Interface);
PROCEDURE Close(cont: Container) : BOOLEAN;
PROCEDURE Capabilities(cont: Container) : CapabilitySet;



PROCEDURE Insert(cont: Container; trans: Transaction;
                 VAR id: Ident; object: Object) : BOOLEAN;
PROCEDURE Delete(cont: Container; trans: Transaction;
                 id: Ident) : BOOLEAN;
PROCEDURE Replace(cont: Container; trans: Transaction;
                  id: Ident; object: Object) : BOOLEAN;
PROCEDURE Obtain(cont: Container; trans: Transaction;
                 id: Ident; VAR object: Object) : BOOLEAN;



PROCEDURE Elements(cont: Container; trans: Transaction;
                   VAR nelems: LONGINT) : BOOLEAN;
PROCEDURE Find(cont: Container; trans: Transaction; dir: SearchDir;
               VAR id: Ident) : BOOLEAN;



PROCEDURE Reorganize(cont: Container; trans: Transaction) : BOOLEAN;



PROCEDURE SetAnchor(cont: Container; trans: Transaction;
                    id: Ident) : BOOLEAN;
PROCEDURE GetAnchor(cont: Container; trans: Transaction;
                    VAR id: Ident) : BOOLEAN;



PROCEDURE Exchange(cont: Container; trans: Transaction; id: Ident;
                   new: Object; VAR old: Object) : BOOLEAN;
PROCEDURE Remove(cont: Container; trans: Transaction;
                 id: Ident; VAR object: Object) : BOOLEAN;

DESCRIPTION

Implementors of containers have to call Init during their opening process providing their specific implementations of the container operations in form of an interface record if. Containers expects the interface procedures to fulfill the following specifications:

insert: PROCEDURE(cont: Container; trans: Transaction; VAR id: Ident; object: Object) : BOOLEAN;

Insert a new object object into the container cont and return a unique id for accessing the stored object.

delete: PROCEDURE(cont: Container; trans: Transaction; id: Ident) : BOOLEAN;

Delete the object identified by id from the container.

replace: PROCEDURE(cont: Container; trans: Transaction; id: Ident; object: Object) : BOOLEAN;

Delete the object identified by id from the container and replace it by object.

obtain: PROCEDURE(cont: Container; trans: Transaction; id: Ident; VAR object: Object) : BOOLEAN;

Retrieve the object identified by id from the container.

elements: PROCEDURE(cont: Container; trans: Transaction; VAR nelems: LONGINT) : BOOLEAN;

Return the number of elements currently stored in cont.

find: PROCEDURE(cont: Container; trans: Transaction; dir: SearchDir; VAR id: Ident) : BOOLEAN;

Find out certain object identifications dependent on dir and id where dir defines the direction and id the starting position of the search.

this

Determine if an object with id is stored.

succ

Increment id to the next greater object identification used.

pred

Decrement id to the next smaller identification used.

first

Return the lowest id in use.

last

Return the highest id in use.

Implementations should be aware that in combination with this, succ and pred the initial value of id has to be used for computation (even if declared as VAR).

reorganize: PROCEDURE(cont: Container; trans: Transaction) : BOOLEAN;

Reorganize the container in an implementation-dependent manner.

setAnchor: PROCEDURE(cont: Container; trans: Transaction; id: Ident) : BOOLEAN;

Define or redefine an anchor id for the container (see below).

getAnchor: PROCEDURE(cont: Container; trans: Transaction; VAR id: Ident) : BOOLEAN;

Return the anchor id of the container.

close: PROCEDURE(cont: Container) : BOOLEAN;

Execute necessary clean-up activities before the container is closed.

Implementations are free to implement all of the listed operations or only a subset of them. Note, however, that the set of implemented operations must not be empty. The set of capabilities is computed by Containers from the interface procedures not set to NIL and can be accessed by Capabilities. All accessing operations are always associated to a running transaction which is given by trans (see Transactions). There may be implementations of Containers which ignore trans and accept any value for it, including NIL.

Applications can access a container by the exported procedures which in general follow the specifications of the corresponding interface procedures. SetAnchor and GetAnchor are intended to maintain the identification of an anchor object for the container. This feature is very helpful for implementations that want to organize the objects in a certain way and need some handles for this goal (e.g. the beginning of a list or the root of a tree).

Remove is equivalent to Obtain + Delete, Exchange has the same effect as Obtain and Replace. Any other procedure call is directly delegated to the corresponding interface procedure.

DIAGNOSTICS

Init checks its parameters for validity by assertions.

SEE ALSO

RelatedEvents

error handling

PersistentDisciplines

definition of persistent objects with additional data structures

PersistentObjects

basic definition of persistent objects

RemoteContainers

remote access to containers

Services

type system of the library

StandardContainers

standard implementation of containers

Transactions

abstraction for distributed transactions

AUTHOR

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