A class category describes a set of behaviours that apply to object classes.  The Persistate package defines a number of standard class categories that you can use, and these should be sufficient for most needs.  Here is an example of the definition of one of the standard categories.

Orderable classes have functions
   use cache,
   clone on mutate,
   allow order
.

This defines a class category called orderable, which includes three behaviours.  These behaviours are adopted by objects which are instances of classes defined as in a class category which has that behaviour defined.  So for example, from the above example, we can see that an instance of a class in the orderable category will follow the use cache behaviour.

Behaviours

There are a fixed set of behaviours, as listed below.

Use cache

The persistent object is held in a cache in memory.  If the object is already in the cache, it need not be retrieved again from persistent storage. This also means that there is only ever one copy of that object in memory at one time (except for temporary clones made on object mutation - see clone on mutate below).

Clone on mutate

When you modify the persistent object for the first time, using a generated property, a clone is taken of the object before it is modified. This clone is subsequently used to restore the original value if the current transaction is rolled back.

Allow order

The class will automatically be given an Order property, and will implement the IOrderable interface. This is required to allow ordered collections of the class.  You can make use of this by including the ordered qualifier in collections of this class.  Objects in ordered collections have fixed positions in the collection.

Log associations

When you make an association to the persistent object, a reverse reference to the associator is also held in persistent storage.  Associations are references to an object by another object other than its parent object. You can then subsequently obtain a collection of all objects with associations to the object using the Persistent.GetAssociators method.

Save in configuration

This causes the object to be saved in a package's configuration file.  This file contains serialised values of the package object (which is configurative) and all its configurative descendents, as well as configurative objects in the package's own tree in the development environment.  This means that new installations of the package, both stand-alone and in Persistate Servers, will contain the configurative objects which were created in the environment in which the package was developed.  See the Deploy operation.

Volatile

This behaviour means that objects are not held in persistent storage, but exist only in memory.

Standard Class Categories

The standard class categories cover most usable combinations of these behaviours.  The following sections list these categories, along with the behaviours they include, and gives an idea of the type of information that they should be used for.

Stable

Used for objects which are relatively permanent, tend not to be associated with a point in time, and tend not to accumulate much. Behaviours are Use cache, Clone on mutate.

Logged

Used for Stable objects which require access to all associators. Behaviours are Use cache, Clone on mutate, Log associations.

Orderable

Used for Stable objects which are to be held in ordered collections. Behaviours are Use cache, Clone on mutate, Allow order.

Logged orderable

Used for Stable objects which require access to all associators, and are to be held in ordered collections. Behaviours are Use cache, Clone on mutate, Log associations, Allow order.

Configurative

Used for objects which are similar to Stable objects, but which hold configuration data, and tend to be shared, as default values anyway, by all installations of an application. Behaviours are Use cache, Save in configuration, Clone on mutate.

Logged configurative

Used for Configurative objects which require access to all associators. Behaviours are Use cache, Save in configuration, Clone on mutate, Log associations.

Orderable configurative

Used for Configurative objects which are to be held in ordered collections. Behaviours are Use cache, Save in configuration, Clone on mutate, Allow order.

Logged orderable configurative

Used for Configurative objects which require access to all associators, and are to be held in ordered collections. Behaviours are Use cache, Save in configuration, Clone on mutate, Log associations, Allow order.

Transitory

Used for objects which are usually associated with a point in time and tend to accumulate in persistent storage. No behaviours are associated with the Transitory category.

Volatile

Used for object which are not held in persistent storage. The single behaviour is Volatile.

Syntax

ClassCategory = CategoryName "classes" "have" "functions" FunctionNames ;
CategoryName = <symbol> { <symbol> } ;
FunctionNames = FunctionName { "," FunctionName } ;
FunctionName = <symbol> { <symbol> } ;

See Grammar Notation in Syntax Sections for an explanation of the format and symbols used here

Description

ClassCategory

This defines a class category.  There are no optional clauses - everything must be included.

CategoryName

The name you give to a class category consists of one or more symbols, and must be unique in the package.

FunctionNames

At least one function name must be given, and they must be separated by commas.

FunctionName

The only function names allowed are those listed above.