GemStone/S 64 Bit Supplemental Documentation
Object Canonicalization Framework
1.1 Object Canonicalization Framework
For objects that have a finite set of possible values, and which are used frequently within an application, it can be very useful to reduce the number of duplicate instances. One example is GemStone DateTime instances.
The Object Canonicalization Framework provides an way to reduce these duplicate instances in your application. It allows you to register a class and use this for object creation.
This framework does not guarantee that instances of the given class are entirely canonical.If multiple users create instances at the same time, duplicate instances are created (this is intentional, to avoid commit conflicts); and it is not restricted from creating instances that do not use the framework. Comparisons of instances of the given class should use = rather than == .
The classes that support this framework are:
CanonicalObjectManager
CanonicalObjectPolicy
CanonicalObjectRegistry
AbstractReferencingObjectPolicy
ReferencingObjectPolicy
Implementing Canonical instances
To create canonical instances, first register a class as being canonicalizable, using CanonicalObjectManager>>createRegistryFor:. Then, to request a canonical instance of that class, use canonicalObjectFor:.
For example, to create canonical instances of DateTime,
CanonicalObjectManager default createRegistryFor: DateTime.
CanonicalObjectManager default canonicalObjectFor:
(DateTime fromString: '01/01/2015 00:00:00')
As mentioned, to avoid commit conflicts, if a canonical object is not yet in the registry, the framework allows overlapping transactions to see different objects as the canonical one. This means that two overlapping transactions that create an equivalent object will result in two equivalent instances. Subsequent transactions will see one of the earlier ones. To ensure that only one object is used, send ultimateCanonicalObjectFor: and be prepared to handle commit conflicts.
Post-creation canonicalization
An alternate way to canonicalize objects is to provide a set of objects to the manager and have it scan them for references to canonicalizable objects, using the method CanonicalObjectManager >> cleanupAll:. This would typically be used with objects found using a repository scan, such as the results of Repository>>listReferencesToInstancesOfClasses:toDirectory:. Using this, you can canonicalize existing objects in your application.
Because some objects should not have references arbitrarily replaced (e.g., IdentitySets), the framework uses a pluggable policy to decide which referencing objects can be modified. The default ReferencingObjectPolicy bases the decision on the referencing object class.
Further Integration
To fully implement a transparent canonicalization scheme, applications may want to use CanonicalObjectManager>>cleanupWriteSet to scan the write set for the current transaction and replaces references as indicated by the policy. A properly configured manager could do appropriate cleanup before each commit.
By default, the default instance of CanonicalObjectManager has world write permission so that canonical objects can be created by any session and shared. You can modify this using CanonicalObjectManager class>>#securityPolicy:.