Pluggable session storage is the storage which implemented by the user. For example, it could be used to implement High-Availability (HA) Solutions, one can implement a Pluggable Session Storage which stores data to shareable storage and if one server, with the CME iLink 3 Handler, fails and another reserve server stands up then the CME iLink 3 Handler can restore session states from the same shareable storage. Such a storage should implement the OnixS::CME::iLink3::SessionStorage interface.
There are few basic rules that should be applied to an implementation of Pluggable Storage.
Lifecycle of the storage should be managed by the user
The Handler core treats instance of Pluggable Storage as a "foreign" object and, therefore, never attempts to delete it. On the other hand, there is strong requirement to keep storage instance valid, until the OnixS::CME::iLink3::Session instance is destroyed.
Be as fast as possible
Since Pluggable Storage is incorporated into the message send/receive route, it has a direct affection on sending/receiving latency, and overall throughput of the system. So, to keep high performance, it is needed to handle callbacks as fast as possible.
Prevent against exceptions
Exceptions thrown from Pluggable Storage callbacks, always immediately break a session. So you usually need to use exception-free code for callbacks.
Don't make assumptions about parameters lifecycle
Messages and pointers, passed to Pluggable Storage callbacks, should be completely handled, before these callbacks return control to Handler core. Whenever you need to keep such data for separate usage, you should make copies of messages or memory blocks, and store them in an appropriate place, but don't keep raw pointers, passed to callbacks.
No specific synchronization is needed
The Handler core manages all synchronization issues by itself, so all methods of Pluggable Storage are called sequentially. Therefore, you don't need to implement separate synchronization to ensure, that SessionStorage::storeInboundMessage and SessionStorage::storeOutboundMessage methods are not called simultaneously. Of course, it is still possible to use synchronizations for other needs.
Track message numbers, when the message is logged
Message sequence numbers should be tracked while messages are logged, i.e. during OnixS::CME::iLink3::SessionStorage::storeInboundMessage or OnixS::CME::iLink3::SessionStorage::storeOutboundMessage methods are handled. These numbers should be kept and returned to Handler through OnixS::CME::iLink3::SessionStorage::inSeqNum() and OnixS::CME::iLink3::SessionStorage::outSeqNum() calls for incoming and outgoing messages respectively.
OnixS::CME::iLink3::SessionStorage::inSeqNum(SeqNumber) and OnixS::CME::iLink3::SessionStorage::outSeqNum(SeqNumber) are called only duringsession startup, the initial negotiation and session shutdown the processes.
This section explains how different methods of Pluggable Storage are called in different situations.
Incoming message handling
If an exception is thrown by the user's code on any stage (during SessionStorage or SessionListener handling), the session becomes disconnected, and subsequent stages are omitted.
Outgoing message handling
There is a quite schematic illustration for the pluggable storage usage.
Please, check the PluggableStorage sample, included into distribution package of CME iLink 3 Handler.