Storing information

The Basic Document framework puts in place the mechanisms that support information storage. It defines both the basic storage methods and abstracts the storage media to provide a stable interface.

Filing vs. streaming

Two new terms describe how information is stored in the CommonPoint application system.

Information is streamed into storage when you want to store an entire document or object. The data representing the object is converted to a byte-encoded stream. You stream an object that you mean to be sent to another process or another machine. Generally, you would stream an object and all of its containees as well.

Conversely, you file information to storage when you only want to store a portion of it (for instance, a document's attributes). Filing is for persistent storage only. Filing allows you a greater granularity in your choice of whether to store an entire object or just some part of it.

When a storage mechanism creates a stream, it attaches an attribute to this stream to indicate whether the stream will be used for filing and then invokes the streaming operators on the object it needs to file.

Filing in a document

Filing a document out to storage is a several-step process:

The document server looks up a document store using the store reference passed to it by the Workspace.
The document provides a document reference to the document store and asks it to file in the document.
In response, the document store creates a prototypical document instance and asks it to file in itself.
The just-created document instantiation then files in the document state and the document cross-reference table.

Saving data

By default, the CommonPoint application system only files out the document state when the document is closed. All persistent data is committed to store simultaneously.

Layering of the storage classes

The storage classes are layered. The store class (TStore) sits at the highest level. Subclasses of it define the application interface for storing objects such as documents. The storage mechanism (TStorageMechanism) classes sit at the intermediate level and provide access to physical storage to the store class. The storage bin (TStorageBin) classes sit at the lowest level and define the type of storage available to the application.

You only need to understand the mechanics of the storage mechanism if you wish to supply a new physical storage mechanism or you need to extend the storage mechanism API to add new ways of storing data (for instance, adding a dictionary interface).

You can derive from the store subclass to support a different semantic interface on top of an existing storage mechanism (for instance, an appliance store using a standard storage mechanism). The store class can also be subclassed to support a different implementation of the same storage semantics on top of a new storage mechanism with extended API (for instance, a document store using an OODB storage mechanism).

Ownership of storage mechanisms

All the classes in the TStorageMechanism family are implemented as hidden master surrogates. (Refer to the volume Taligent's Guide to Designing Programs for a complete explanation of hidden master surrogates.)

The three reasons for this design are:

Multiple threads in a document task can share the same storage mechanism.

Storage mechanism classes need to be lightweight handles that another object can use (for instance, the way that TDocumentStore uses TStandardStorageMechanism).
Storage mechanism classes need to insulate the Compound Document Framework from the underlying storage services (for instance, TDocumentStore cannot directly use TDirectory).

The surrogate provides an access path to the storage mechanism. The hidden master resolves multiple execution threads with multiple access paths into a single access path, and provides synchronization among these threads to enforce multiple reader or single writer semantics.

Accessing storage mechanism and storage bins

Access to a storage mechanism and its bins is normally expressed as access to a document and its contents. When a document is created, its permission is specified as either read-only, annotatable, or read-write. By default, all documents will be created with read-write permission.

Request access to a document by instantiating a document surrogate. One of the arguments to the document surrogate constructor is an access mode. The access mode must be less than or equal to the document permission for the access to be granted. For example, read-only access will be granted on documents with read-only permission.

Access to a document from multiple threads within a task or from multiple tasks are synchronized to enforce multiple reader or single writer semantics. In this manner, multiple threads within a task and/or multiple tasks can be granted read-only access to a document.

The first thread within a task that is granted read-write access to a document will preclude all other threads from that task and all other tasks from accessing the document.

Read-write access is not required to access document attributes (for instance , icon, title, or any other information available in a Macintosh Standard File Get-Info menu item). One thread within a document task can read the document attributes while another thread within the same task or another task can update the document data.

[Contents] [Previous] [Next]

Click the icon to mail questions or corrections about this material to Taligent personnel.

Generated with WebMaker