Overview

Solstice allows the use of different backends to store volatile information.

Users' sessions, button records and so forth fall into this category - information that doesn't need to stay stored forever.

Right now, Solstice supports two backends, MySQL and Memcached.

Creating a Backend

To create a backend, you must subclass a few Solstice modules and provide methods to do the storage/retrieval work needed by Solstice. In the following documentation <Backend> should be taken to mean the name of the subclass you are creating, such as MySQL, or Memcached.

Solstice::Session Module

Sessions are the persistent data a user keeps across all applications and clicks. Your subclass of Solstice::Session must implement:

_store($session_id)

This method takes a session ID argument and is responsible for storing it's $self into the datastore such that it can be fully restored by _loadSessionByID.

No return is necessary.

_loadSessionByID($session_id)

This method takes a session ID argument and is responsible for returning the specified session object if it exists in the datastore.

The returned session should be a fully blessed Solstice::Session::<Backend> object with all of the attributes it had when _store was called.

If the specified session does not exist in the datastore, this method should return undef.

_getSessionLock($session_id)

This method takes a session ID argument and is responsible for establishing a lock on changes to that session. This is optional but encouraged. We found that when a user was acting in multiple browser windows simultaneously, they could create a "last session stored wins" situation that occasionally caused errors.

No return is necessary.

_releaseSessionLock($session_id)

Responsible for releasing the lock on the session ID passed in.

No return is necessary.

Solstice::Subsession Module

Subsessions are the data that a user keeps as they follow an individual clickpath in an application. They are stored historically in chains, so that a user may continue from any point in their browser's history. Your subclass of Solstice::Subsession must implement:

_store($subsession_id, $chain_id, $session_id)

This method takes a subession ID argument and is responsible for storing it's $self into the datastore such that it can be fully restored by _loadSubessionByID.

The chain ID argument is also important - because of how Solstice handles continuations it is necessary to be able to look up a list of all the Subsessions that belong to a given chain. Use the chain ID argument to achieve this, and see _deleteSubsessionsInChain and _getFallbackSubsession for a better idea of why this is required.

The session ID argument is present for logging and debugging reasons - it is often nice to look up what subsessions are owned by which session, though it is not programmatically necessary to do anything with this value.

No return is necessary.

_loadSubsessionByID($subsession_id)

This method takes a subsession ID argument and is responsible for returning the specified subsession object if it exists in the datastore.

The returned session should be a fully blessed Solstice::Subsession::<Backend> object with all of the attributes it had when _store was called.

If the specified session does not exist in the datastore, this method should return undef.

_isSubsessionLegal($subsession_id)

Using the provide subsession ID, this method should check if the datastore contains a subsession with the given ID. It may not if the subsession has been expired or was never stored.

Return TRUE if the subsession exists, FALSE otherwise.

_getFallbackSubsession($chain_id)

Using the chain ID specified, this method is responsible for returning the most recent existing subsession that belonged to this chain. Return that fully initialized subsession object or undef if there are no valid subsessions in the chain.

_deleteSubsessionsInChain($chain_id)

Use the provided chain ID to delete all the subsessions stored from that chain. If _isSubsessionLegal or _loadSubsessionByID are called for a subsession deleted by this method, they should return FALSE and undef.

No return value is necessary.

Solstice::ButtonService Module

ButtonService is used to track the controls shown to a user for purposes of attaching reliable data to any given navigation, and identifying which subsession a given click should continue from.

Two methods must be overridden in your subclass:

_storeButtonList($button_arrayref, $commit_id)

This method is used to store all the buttons created for a given screen.

The $button_arrayref contains a list of these button objects, which should be stored in their entirety, in a fashion so that they can be looked up by their Name attribute (ie, $button->getName()).

The commit ID argument is useful for grouping all the buttons for a particular screen together, but is not programmatically important.

No return value is necessary.

_selectedButtonLookup($button_name)

This method is called by Solstice to retrieve the fully initialized button object indicated by the name passed.

The method must return the button object in the same state it was when stored.