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

Ulm's Oberon Library:
Keys

NAME

Keys - key-based total order relations

SYNOPSIS

TYPE Key = POINTER TO KeyRec;
TYPE KeyRec = RECORD (PersistentDisciplines.ObjectRec) END;
TYPE Value = POINTER TO ValueRec;
TYPE ValueRec = RECORD (PersistentDisciplines.ObjectRec) END;
ExtractProc = PROCEDURE (object: Services.Object;
                         key: Key; VAR keyval: Value);
CompareProc = PROCEDURE (key: Key; keyval1, keyval2: Value) : INTEGER;



PROCEDURE DefineService(name: ARRAY OF CHAR;
                        type: Services.Type;
                        compare: CompareProc;
                        VAR service: Services.Service);
PROCEDURE Init(key: Key; service: Services.Service);
PROCEDURE GetService(key: Key; VAR service: Services.Service);
PROCEDURE Support(service: Services.Service;
                  for: Services.Type;
                  extract: ExtractProc);
PROCEDURE Supported(object: Services.Object; key: Key) : BOOLEAN;
PROCEDURE Compare(key: Key; object1, object2: Services.Object) : INTEGER;
PROCEDURE Extract(object: Services.Object; key: Key; VAR keyval: Value);
PROCEDURE Compatible(keyval: Value; key: Key) : BOOLEAN;
PROCEDURE CompareKeyValues(key: Key; keyval1, keyval2: Value) : INTEGER;

DESCRIPTION

A key consists of

a set of attributes which can be extracted from various kinds of objects, and
the definition of a total order relation for values of that key.

A key allows to sort a set of heterogeneous objects if the specific key is supported for all kinds of objects in the set. Note that keys are not necessarily identifying in the sense of the relational database theory and that more than one key may be supported for one kind of objects. Using the mechanism of Services, it is possible to define and support keys for objects types without modifying their associated modules.

Both, keys and key values, are persistent objects, i.e. extensions of PersistentDisciplines.Object.

Client roles

There are four types of modules in the context of Keys (XXX, YYY, and ZZZ are place holders for arbitrary names):

XXXs: a module which defines an extension of Services.Object named XXXs.XXX but needs not to be aware of Keys.
YYYKeys: defines a key, i.e. an attribute set and a total order relation. Note that this type of modules does not need to know anything about the later to be supported object types (e.g. XXXs). YYYKeys is responsible for providing the interface procedures of PersistentObjects for its extensions of Key and Value.
YYYKeyForXXXs: defines how to extract a specific key (e.g. YYYKeys.Key) from a specific kind of objects (e.g. XXXs.XXX).
ZZZ: is a module which compares heterogeneous objects by using a key. This module does not need to know any object-specific or key-specific details.

Definition of a key

Modules of the type YYYKeys have to call DefineService during their initialization. The name of the service should be that of the module (e.g. "YYYKeys"), type is the Services.Type of the associated key values (e.g. YYYKeys.Value). The compare interface procedure has to define a total order relation for the key values defined by YYYKeys. DefineService creates and returns a service which has later to be passed to Init for each created key (of type YYYKeys.Key).

Note that Keys guarantees that the key value parameters of the compare interface procedure are extensions of YYYKeys.Value. The returned integer value of compare must be less than, equal to, or greater than zero if keyval1 is found, respectively, to be less than, equal to, or greater than keyval2.

GetService allows to retrieve the associated service of a key.

Supporting a key

Modules which support a specific key for a specific kind of objects (e.g. YYYKeyForXXXs) have to call Support during their initialization time to pass their extract interface procedure. The service parameter is the service named after that module which defines the key (e.g. "YYYKeys"), and for is the Services.Type of XXXs.XXX. The extract interface procedure gets an object which is guaranteed to be an extension of XXXs.XXX, a key which is an extension of YYYKeys.Key, and has to return a key value which must be an extension of YYYKeys.Value.

Note that Keys supports implicitly all keys for their associated key values.

Using keys

Compare allows to compare two objects by using key and returns an integer value which is less than, equal to, or greater than zero if object1 is found, respectively, to be less than, equal to, or greater than object2 regarding key. Note that Compare requires key to be supported for the types of object1 and object2. This may be checked for by Supported.

Key values may be compared not only by Compare but also (somewhat faster) directly by CompareKeyValues. Note that both key values must be compatible to the given key. This may be checked for by Compatible.

Extract allows to extract a key value for key from object. NIL is returned if key is not supported for the type of object.

DIAGNOSTICS

All kinds of errors lead to failed assertions (with the exception of Extract which returns NIL):

DefineService checks type and compare for being non-NIL.
Init asserts that service is non-NIL.
GetService requires key to be initialized by Init.
Support asserts that service originates from Keys, i.e. that service is the return value of a former call of DefineService.
Compare requires that key is supported for the types of object1 and object2.
CompareKeyValues checks that both key values, keyval1 and keyval2, are compatible to key.
The return value of the extract interface procedure is always checked to be an extension of the corresponding key value type (e.g. YYYKeys.Value).

Ulm's Oberon Library: Keys