Class Definition File | PstObj.idl |
Class C++ Binding | PstObj.xh |
Class Hierarchy |
SOMObject
ODObject
ODRefCntObject
ODPersistentObject
|
Description | An object of the ODPersistentObject class implements the protocol for saving and restoring objects to persistent storage. Certain objects created in one OpenDoc session can be saved to persistent storage. In a later session, the same objects can be recreated from their stored data. Similarly, an object that is not being used can be saved to persistent storage to free space in memory. If the object is needed later in the same session, it can be recreated from its stored data. An object whose state can be saved to persistent storage is called a persistent object. The ODPersistentObject class is the abstract superclass for all OpenDoc classes whose objects need to be saved persistently. You should not create immediate subclasses or instances of ODPersistentObject itself. The following subclasses are concrete classes: You can create instances of those classes, but you should not create subclasses of them. The ODPersistentObject class has a fourth subclass, ODPart, which is an abstract class. To develop a part editor, you need to create a subclass of ODPart. The persistent objects that can be saved and recreated from storage are frames, links, link sources, and parts. Each persistent object has an associated storage unit in which it can store its data persistently. Within each draft in a particular session, the storage unit is given an unique identifier (ID) that designates both the storage unit itself and the persistent object whose data it contains. This ID is not part of the object's persistent data but is valid only for the duration of the session. The process of storing a persistent object's data is called externalizing the object. When a persistent object writes itself to storage, it writes into its storage unit whatever information is necessary to restore it to its current state. When a stored persistent object is recreated, it initializes itself to its previous state by reading the data it stored when it was last written. A persistent object can also be cloned, that is, the object and all additional objects that it references can be copied. Typically, an object is cloned when its data must be transferred, for example, when it is copied to the clipboard. For more information about storage units, see the class description of "ODStorageUnit". For more information about cloning, see the chapter on data transfer in the OpenDoc Programming Guide. For more information about the different kinds of persistent objects, see the class descriptions for "ODFrame", "ODLink", "ODLinkSource", and "ODPart". |
Methods | The methods defined by the ODPersistentObject class include: |
Overridden Methods | There are no methods overridden by the ODPersistentObject class. |
This method should clone this persistent object by copying its data into a specified storage unit.
Signature
void CloneInto (ODDraftKey key,
ODStorageUnit *toSU,
ODFrame *scope)
|
Parameters
Returns
None.
Remarks
Your part should never call this method directly; it is called by the draft's Clone and WeakClone methods.
The scope parameter determines which of the referenced objects are within the scope of this cloning operation. Typically, the scope parameter is a reference to a frame and only those objects embedded in that frame are within the scope.
This method copies this object's data into the specified destination storage unit and clones any additional objects to which this object has strong and weak persistent references and that are within the scope of this cloning operation Objects referenced by strong persistent references are strongly cloned by recursive calls to the Clone method; objects referenced by weak persistent references are weakly cloned by calls to the WeakClone method. Otherwise, only those objects logically enclosed in the specified frame are within the scope and should be cloned.
Override Policy
If you subclass ODPersistentObject, you must override this method to support data interchange of internal data. Your override method must calls its inherited method at the beginning of its implementation. The inherited method clones the kODPropCreateDate, kODPropModDate, and kODPropModUser properties.
Your override of this method should write the part's data into the specified storage unit and clone any additional object to which this part has strong or weak persistent reference and that are within the specified scope. OpenDoc calls this method if your part is being copied to the clipboard, a drag-and-drop object, or a link source object.
Related Methods
This method should store the data needed to restore this persistent object to its current state.
Signature
void Externalize () |
Parameters
None.
Returns
None.
Remarks
Your part calls this method of a persistent object (for example, a part or frame) to write that object's data to persistent storage. This method writes the object's persistent state to the properties and values in the object's storage unit. It must write sufficient information to allow the object's InitClassFromStorage method to restore the object to its current state; for example, a part's Externalize method must write the information needed by its InitPartFromStorage method.
Override Policy
If you subclass of ODPersistentObject, you must override the method if your part maintains persistent content. Your override method must call its inherited method at the beginning of its implementation.
Your override of this method should write your part's persistent state to the properties and values your part created when it initialized itself in your part's InitPart method. It should write sufficient information to allow your InitPartFromStorage method to restore your part to its current state. Your part editor calls this method when your part stores its content data.
Related Methods
This method returns the unique ID of this persistent object for the current draft in the current session.
Signature
ODID GetID () |
Parameters
None.
Returns
Remarks
The ID of the persistent object is also the ID of its storage unit. The ID is not persistent data. This persistent object can have a different ID in each different session and in each different draft within the same session.
This method returns a reference to the storage unit in which this persistent object stores its data.
Signature
ODStorageUnit *GetStorageUnit () |
Parameters
None.
Returns
Remarks
When your part calls this method, it should check that the return value is not null before attempting to use the storage unit because nonpersistent frames, which do not have storage units, may be added to your part.
You should never cache a reference to the returned storage unit; instead, you must call this method when you access the storage unit. This method does not increment the reference count of the returned storage unit.
This method initializes this newly created persistent object.
Signature
void InitPersistentObject (ODStorageUnit *storageUnit) |
Parameters
Returns
None.
Remarks
Your part editor should never call this method directly; it is called when a persistent object is created for the first time. Every existing OpenDoc subclass of ODPersistentObject (including ODPart) has an initialization method that calls the inherited InitPersistentObject method at the beginning of its implementation.
For example, the initialization method of ODPart is the InitPart method. When you call the draft's CreatePart method to create a part of your class, that factory method calls your part's InitPart method. Your part's InitPart method should call the inherited InitPart method, which calls the InitPersistentObject method.
The InitPersistentObject method is not called when a stored object is recreated; instead, the InitPersistentObjectFromStorage method is called to restore the object to its state at the time it was last saved.
Related Methods
This method initializes this recreated persistent object from its stored data.
Signature
void InitPersistentObjectFromStorage (ODStorageUnit *storageUnit) |
Parameters
Returns
None.
Remarks
Your part editor should never call this method directly; it is called when a persistent object is recreated from stored data. Every existing OpenDoc subclass of ODPersistentObject (including ODPart) has an InitClassFromStorage method to initialize an object of that class from its stored data; that method calls the inherited InitPersistentObjectFromStorage method and then reads any data that was previously written by the Externalize method when the object was stored. The object's factory method calls the object's InitClassFromStorage method when recreating the object from its stored data.
For example, the ODFrame class has a private InitClassFromStorage method. When you call the draft's AcquireFrame method to recreate a frame, that factory method calls the recreated frame's InitFrameFromStorage method.
Related Methods
This method should release all transitory references from this persistent object to other reference-counted objects.
Signature
void ReleaseAll () |
Parameters
None.
Returns
None.
Remarks
The factory object that creates each persistent object calls that object's ReleaseAll method before deleting it.
Override Policy
If you subclass ODPersistentObject, you must override this method if its objects maintains references to other persistent objects. Your override method must call its inherited method at the end of its implementation.
Your override of this method should release all persistent objects to which it points, remove any link specifications your part has written to the clipboard, relinquish all focuses, and clear any undo actions it has written to the undo stack. For any extension that cannot be deleted, your override method must call its base extension's BaseRemoved method. If your part's embedded frames are being traversed by an embedded frames iterator when the part is deleted, your override must call your embedded frames iterator's PartRemoved method.
OpenDoc calls this method before your part is deleted. If the part being deleted has a promise, the promise is resolved before the part is deleted.