This topic describes how IBM Director classifies data and describes how to save and restore persistent object data.
IBM Director server objects can be divided into two classes: persistent and non-persistent objects. Persistent objects have data that must be "remembered" between server executions so the data can be recollected when the server is restarted.
Non-persistent objects do not have persistent data and are usually instantiated as needed during server execution.
Examples of persistent objects in the IBM Director server include:
Examples of non-persistent objects include:
In the IBM Director Server, both persistent and non-persistent objects are subclasses of TWGObject. Non-persistent objects are extended directly from TWGObject, whereas persistent objects extend from TWGPersistentObject, which extends TWGObject. Each TWGObject-based object, either persistent or non-persistent, is assigned a unique ID which is used throughout IBM Director to address server objects. For example, when a user at the IBM Director console drops a task on a system, the console identifies both the task and the targeted system to the server by sending their respective IDs to the server along with the action requested (in this case, activate). The IBM Director Server component receiving this activation request uses the lookup facilities of TWGObject to resolve the task and system IDs into real objects.
Each IBM Director Server object that needs to save and retain data between IBM Director Server executions must subclass TWGPersistentObject, provide a public default constructor, and override the following methods:
protected void saveData( TWGPersistentObjectDictionary dictionary )
throws TWGPersistentObjectSaveException
protected void restoreData( TWGPersistentObjectDictionary dictionary,
boolean resolveObjectReferences )
throws TWGPersistentObjectRestoreException
The procedure for saving persistent object data is as follows:
public final void save() throws TWGPersistentObjectSaveException
The save() method creates an empty TWGPersistentObjectDictionary object to collect the persistent instance data for each subclass and invokes the object's saveData() method.
public void put( String name, byte [] data )
super.saveData( dictionary );
After the saveData() method returns, the save() method of TWGPersistentObject combines the byte arrays from each subclass in the TWGPersistentObjectDictionary into a single byte array and writes this data to disk.
Note: A persistent ID is generated and assigned to an object the first time it is saved through the TWGPersistentObject save() method.
Updates to persistent objects are handled using a similar procedure; setter methods are invoked to change the object and then the save() method is invoked. Setter methods that change persistent data should invoke the following method of TWGPersistentObject to indicate that the object is "dirty" and needs to be rewritten to disk:
public final void setSaveRequired()
To save the updated persistent object, invoke the save() method.
When the IBM Director Server is started, persistent objects stored to disk are restored when the server invokes the restoreAll() class method of TWGPersistentObject. This method enumerates each entry in the persistent object database. For each entry in the database the following steps are taken:
public byte [] get( String name )
Note: Restore references to other objects only when the resolveObjectReferences argument is TRUE.
super.restoreData( dictionary, resolveObjectReferences );
The restoreAll() method enumerates its database twice. On the first pass, the restoreData() method is invoked for each object with resolveObjectReferences set to FALSE. On the second pass, resolveObjectReferences is set to TRUE and the individual restoreData() methods can, therefore, restore object references using the lookup facilities of TWGObject.
Note: Only registered classes can be restored (refer to Creating IBM Director Extensions for more information on restoring registered classes). If an extension that registers and saves persistent objects is removed, the persistent objects of the removed extension are not restored the next time the IBM Director Server is started.