SessionItem is the base class for all objects which persist state in the session. The core SessionItems already contain logic to save and restore but plugins and custom model elements (those which implement the AnyData interface) will not perform any special serialization. A PlugIn subclass can implement the SessionItem::serialize() and SessionItem::deserialize() methods. The SessionManager will automatically recreate PlugIn objects when the session is restored, these objects only need to save and restore internal state including attachments to other objects. Serialization and deserialization utilize SessionItemSerializer and SessionItemDeserializer to save and load raw data to the session. Examples can be found in many core plugins including sample plugins.
XMLWriter and XmlReader can be used to save and restore state using XML. State can also be saved as a raw octet stream. A SessionItem can save multiple blocks of data which are analogous to multiple files. See SessionItemSerializer and SessionItemDeserializer for additional information on session blocks.
Attachments and other "has a" relationships between SessionItems are typically represented by storing the ID of the SessionItem at the other end of the relation. When restoring these relationships, use SessionManager::getSessionItem() to retrieve a pointer to the SessionItem with a specific ID.
There are many patterns which can be used to store the state of many objects used by a plugin. If all the objects which have state are PlugIns, then each can store and load their own internal state and Opticks will call the appropriate methods on all of the objects. This is the simplest pattern to implement.
If there are objects which do not implement the SessionItem interface but have internal state which needs to be stored then the manager pattern is an effective way to handle session save and load. A single PlugIn manages the lifespan of the other objects. This saves and restores the state of all objects which it manages. This provides much more control of save and restore ordering but requires more infrastructure in the manager plug-in.
ExecutableAgent::execute() will lock the SessionManager preventing save and restore so a plugin can assume that it will not be saved or restored while execute() is running. A developer may lock the SessionManager using a SessionSaveLock resource which is used to define a critical section of the code.
Session restoration is a two phase process. All session items are first created and then deserialized. This ensures that any SessionItem storing another SessionItem ID can retrieve a pointer to the second SessionItem during deserialization. Deserialization of SessionItems is ordered by SessionItem type however the exact order is subject to change and changes will be documented. SessionItems are restored in the following order:
The restoration order of individual objects within these object categories is undefined. If a plugin requires restored data from a Window or View object, delayed intialization can be performed by connecting to the SessionManager::signalSessionRestored() signal.
During session restore, no plugins are executed including execute-on-startup plugins. A plugin should assume that deserialize() will be called without a corresponding execute().
The session will be closed before loading a saved session and a plugin should properly handle cleanup tasks during session close.