Archives

Archives are the persistent storage mechanism for all Guildhall applet data. In the host system they exist as a simple data file. In the Guildhall context they appear as a volume (disk) with files, folders, and free space. The data objects (files) stored on archives are managed by the TArchiveObject class, and generally that class is instantiated with a derivative of ADataType (defined in the Properties section) that contains applet specific data.

When an archive object is stored in an archive, it exists as two separate blocks, an info block, designed to contain ephemeral information such as creation and modification dates, and a data block, designed to contain three forks, a version fork, a resource fork, and the main data fork. Since info blocks tend to be much smaller than data blocks, changes to their contents are recorded much more quickly than are recorded changes to the data block. Operations such as moving a window on the desktop without editing the contents of that window will update the info block but not the data block. Likewise, objects opened read-only can still record changes to ephemeral information if that information is stored in the info block.

The data block (ADataType) managed by the archive object is built upon the TMemoryStream class, which class manages the three forks mentioned above. The version fork retains a record of any object streamed to the data fork which has a version history greater than zero. This doesn't happen automatically. A class that has moved to a new version must either manage versioning on its own (by streaming out a version number before streaming anything else) or it can rely upon the version fork by directly registering its version number. When streamed in the version information can be collected from the stream itself, with an assumed version of zero if nothing has been recorded for the class being streamed.

The resource fork is in fact a collection of TMemoryStream objects, organized by an arbitrary type and an arbitrary number, strongly reminiscent of resources on Classic Mac. And while it might seem that a situation could be created where the data fork and a resource might contain streamed elements with different versions, that's okay, because each TMemoryStream has a version fork of its own. For that matter it has its own resource fork, and how deep that hierarchy descends is up to the applet developer.

Finally, the data fork is just a chunk of memory to which binary data is streamed, starting with calling operator>>= on the ADataType subclass itself and continuing recursively through every persistent member variable until all of the object has been stored. The reverse process calls operator<<= on the ADataType subclass and continues recursively through every member until all of the object has been retrieved.

Special routines are available for persistent polymorphic objects. These routines first stream out the type of the class via an Entomb method, followed by calling the object's virtual operator>>= method. When streamed in by the Exhume method, the type is read first and used to create a discrete instance of the polymorphic object by request to Guildhall's runtime. The remainder of the input is deferred to that discrete object's virtual operator<<= method. Note that this requires that such discrete objects and their associated types be presented to Guildhall's runtime before any objects are streamed in. To accomplish this, each source module that implements such objects registers for a callback during static initialization. When static initialization is complete, specifically once the heap has been initialized, the runtime then calls each module to register its discrete objects. The runtime is thus made ready for all polymorphic streaming input.

Constructible Classes

• TPathname
• TFileID
• TFileSelection
• TArchive
• TArchiveInfoObject
• TArchiveObject
• TStint
• TStintArray
• TStintData
• TBasicData
• TImageData
• TGraphData
• TSoundData