Saving and restoring IBM Director object data

This topic describes how IBM Director classifies data and describes how to save and restore persistent object data.

Subtopics

Related topics

Understanding persistent and non-persistent objects

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.

Saving and updating persistent object data

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:

  1. Instantiate an object that extends TWGPersistentObject, using the default or alternative constructors.
  2. If needed for customization, invoke additional setter methods against the newly created object.
  3. To actually save the persistent object to disk, invoke the following method of TWGPersistentObject:

    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.

  4. The saveData() method for each derived subclass should do the following:

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.

Restoring persistent object data

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:

  1. A TWGPersistentObjectDictionary object is populated with the class name (key) and byte array (data) for each class that contributed data during the save operation.
  2. First pass: the object is instantiated using the default constructor. Second pass: the original ID is assigned to the object.
  3. The restoreData() method is invoked against the object. The restoreData() method for each derived subclass should do the following:

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.