MoleculeSoftware.Packages.State 1.0.4

MoleculeSoftware.Packages.State

Documentation

What is State

State is a simple and robust caching system for MoleculeSoftware software packages. It utilizes a SQLite database to create a pseudo NO-SQL data store which accepts simple commands to perform storage, update, delete, retrieval, and purge operations.

Commands

The state manager creates a database that can store and retrieve key/value pairs.

Commands are passed into the state manager using the MoleculeStoate object's DatabaseOperation method.

The database operation method will provide a callback for all commands

The command structure is as follows:

The initiator

The initiator is the first part of the command string which instructs State to perform a particular function. We will begin command strings in several ways

• STORE#> - instructs State to store a new value
• RETRIEVE#> - Retrieves a value
• UPDATE#> - Updates a value
• DELETE#> - Deletes a value
• PURGE#> - Purges all values

Command parameters

The command parameter is the second part of the command string. This parameter typically contains the name of the key, but is also used as a command verifier for the purge command The initiator will be combined with a command parameter as follows:

• STORE#> will accept a key as a the first parameter. This command will appear as: STORE#>KEY_NAME
• RETRIEVE#> will accept a key as the first parameter. This command will appear as: RETRIEVE#>KEY_NAME
• UPDATE#> Will accept a key as the first parameter. This command will appear as: UPDATE#>KEY_NAME
• DELETE#> will accept a key as the first parameter. This command will appear as: DELETE#>KEY_NAME
• PURGE#> will accept a verifier as the first parameter. This command will appear as: PURGE#>1 - Note that unless the verifier is passed, purge will not occur

Value Parameters

Value parameters follow the command parameter and will contain the value that you want to store/update Only the STORE and UPDATE commands require a value parameter

STORE#>KEY_NAME#>VALUE

UPDATE#>KEY_NAME#>VALUE

VALUE = String representation of the value you wish to store

Data Types

Data is stored by State in string form. The user will be required to convert data to his/her preferred data type once retrieved from State

Storing values

Storing a value is accomplished by passing a value parameter into the STORE#>KEY_NAME#> command

This operation will appear as: STORE#>KEY_NAME#>VALUE

With KEY_NAME and VALUE represented by your key and value data

Updating Values

Updating a value is accomplished by passing a value parameter into the UPDATE#>KEY_NAME#> command

This operation will appear as: UPDATE#>KEY_NAME#>NEW_VALUE

With KEY_NAME and VALUE represented by your key and value data

Retrieving Values

Retrieving a value is accomplished by passing the key name as a command parameter into the RETRIEVE#> command

This operation will appear as: RETRIEVE#>KEY_NAME

With KEY_NAME represented by your key data

Deleting Values

Deleting a value is accomplished by passing the key name as a command parameter into the DELETE#> command

This operation will appear as: DELETE#>KEY_NAMEE

With KEY_NAME represented by your key data

Purging the database of all values

Purging the database is accomplished by passing the PURGE#> command with a command verifier as the command parameter

This operation will appear as PURGE#>1

Unless 1 is passed as the command parameter, the purge operation will not complete

Callbacks

Callbacks are

• #OK# is returned after storing a value in the database, performing a successful delete operation, or performing a successful update operation

• #NONE# is returned if no record was located or if there was an error performing the particular command

• VALUE is returned if a record was located when performing the RETRIEVE#> command (Value is the value that will be returned in string form)

  • (please note that you will need to perform a conversion of the data if it is not ultimately to be used as a string.)

Setup

Install the nuget package MoleculeSoftware.Packages.State

Application Startup

When your application that will be using State has started, create a MoleculeState object and call the Init() method. This will delete any existing state database and will perform any migrations that are necessary to set up the database file. The database file is stored in the temporary directory using the name MoelculeStateData.db

• DEFAULT - Init() will set the default database name to MoleculeStateData.db if you do not set the databaseFileName parameter.
• RECOMMENDED - Init(databaseFileName) - the databaseFileName can be set to give the caching database a unique name. This is especially helpful if you have multiple applications running that are using the caching system. It is recommended to set this name so that it is unique to your application, otherwise applications may share, and damage, the caching database from other applications. The default value is only assigned as a safety measure and ensures that some form of a properly named database is created on init.

You should create a SINGLE INSTANCE of the MoleculeState object and share that throughout your application. Once MoleculeState falls out of scope your data will be lost*.

• It is possible to recover the data from the database as long as Init() has not been called again. This will need to be performed manually with an SQLite supported database manager. NOTE: It is NOT recommended that you store any sensitive data in the state manager. But, once state has retrieved a value it will be removed from the database. This may be better than some other options when dealing with sensitive data. BUT BE WARNED the database is not encrypted so that performance is not degraded. You may wish to pre-encrypt any sensitive data prior to storing it.

NOTE: If Init() is not called the database will not be created.

NOTE: If Init() is called elsewhere, the state database will be deleted and recreated. This is not recommended to be used as a purge since database migrations must be applied every time it is called. Although it will work, this can be slower than using the inbuilt PURGE#> command.

Using State

Create a MoleculeState object and call the DatabaseOperation method. Pass the command string as a parameter. This method will return the string result. See the callbacks section for possible results returned.

NOTE it is highly recommended that you create a wrapper around State that can create (and keep consistent) the database operation calls.

Cleanup

State will clean up after itself during each application startup. If you wish to delete the state data at application exit, just delete the MoleculeStateData.db file from the user's temporary director.

What can State store

State can store any value in string form, this includes serialized objects. The backing store for State is an SQLite database, which supports BLOB data.

NOTE any blob data stored in state after exiting the application will be deleted on the next init.

Contribution

If you wish to contribute to this library, please feel free. This was a quick project but has been a very valuable state storage system for MoleculeSoftware applications. Adaptations and updates are welcome.