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

Ulm's Oberon Library:
PersistentTexts

NAME

PersistentTexts - persistent objects representing texts

SYNOPSIS

TYPE Text = POINTER TO TextRec;
TYPE TextRec = RECORD (PersistentDisciplines.ObjectRec) END;



PROCEDURE Create(VAR text: Text; s: Streams.Stream) : BOOLEAN;



PROCEDURE Open(VAR s: Streams.Stream; text: Text;
               VAR errors: RelatedEvents.Object) : BOOLEAN;

DESCRIPTION

PersistentTexts allows texts streams of arbitrary size to be handled as persistent objects. Streams are expected to work like those of Texts, LargeTexts, or MemStreams, i.e. they are contiguous and support read, write, and seek operations.

Create creates a persistent text object representing s. The length of s is measured (by seeking to the end of s and taking the current position), a rewind is performed, and a sub stream (see SubStreams) of s is opened covering the current length. This allows text to keep in touch with s but avoids conflicts regarding shared stream positions if all other parties interested in accessing s create sub streams as well. A termination of s (see Resources) causes text to terminate, too. Likewise, a termination of text causes its connection to s to be dropped.

Open returns a stream that allows to access the contents of text. Multiple open operations are permitted and return different sub streams of the internal base stream of text.

EXAMPLE

PersistentTexts may be used to transport and store graphs of persistent objects (see LinearizedStructures and ModularizedStructures) with the option to delay the time-consuming restoration until it is needed, or to avoid restoration where it is unnecessary as, for example, in a separately running database process like cdbd.

Following procedures show how to convert a graph of persistent objects (represented by one root object) into a text object and vice versa:

PROCEDURE ConvertObjectToText(object: PersistentObjects.Object;
                              VAR text: PersistentTexts.Text;
                              errors: RelatedEvents.Object) : BOOLEAN;
   VAR
      textbuf: Texts.Text;
BEGIN
   Texts.Open(textbuf); RelatedEvents.Forward(textbuf, errors);
   IF ~LinearizedStructures.Write(textbuf, object) THEN
      RETURN FALSE
   END;
   RETURN PersistentTexts.Create(text, textbuf)
END ConvertObjectToText;

PROCEDURE ConvertTextToObject(text: PersistentTexts.Text;
                              VAR object: PersistentObjects.Object;
                              errors: RelatedEvents.Object) : BOOLEAN;
   VAR
      s: Streams.Stream;
      ok: BOOLEAN;
BEGIN
   IF ~PersistentTexts.Open(s, text, errors) THEN
      RETURN FALSE
   END;
   RelatedEvents.Forward(s, errors);
   ok := LinearizedStructures.Read(s, object);
   Streams.Release(s);
   RETURN ok
END ConvertTextToObject;

DIAGNOSTICS

PersistentTexts does not generate any error events on its own. Create returns FALSE if it is unable to measure the length of s. Open returns FALSE in case of terminated text objects.

BUGS

While streams are not necessarily in-memory streams, the marshalling read operation of PersistentTexts stores the entire text into memory.

While the contents of a text object may be changed, its length cannot be modified.

Edited by: borchert, last change: 2004/04/09, revision: 1.2, converted to HTML: 2004/04/09