|
|
|
Gwenhywfar Storage Framework
|
|
|
|
1. Introduction
|
|
2.Goals
|
|
2.1 Data Integrity
|
|
2.2 Multi-Client Access
|
|
2.3 Modification History
|
|
2.4 Extendability
|
|
3. Basic Plugin API
|
|
4. Simplified Plugin API
|
|
|
|
|
|
|
|
1. Introduction
|
|
===============
|
|
|
|
This folder contains generic storage code.
|
|
|
|
It is currently under heavy development, don't use it for production
|
|
systems.
|
|
|
|
It is used by some of my developing projects to provide a generic framework
|
|
for storing application data.
|
|
|
|
|
|
|
|
2.Goals
|
|
=======
|
|
|
|
2.1 Data Integrity
|
|
------------------
|
|
There is only one situation when the data can be corrupted: The last
|
|
thing in an edit session is to write the data to the actual database.
|
|
If this fails then the data might get corrupted.
|
|
However, even in this case a previous backup in conjunction with the
|
|
modification log allows to recover the database up to just before the
|
|
point of failure.
|
|
|
|
|
|
2.2 Multi-Client Access
|
|
-----------------------
|
|
The simplification layer allows for multiple clients to access the
|
|
data even simultaneously.
|
|
Therefore it supports object locks and mandatory (enforced) data
|
|
modification locks.
|
|
Editing of data is done in edit sessions:
|
|
- beginEdit
|
|
- do some modifications
|
|
- endEdit
|
|
If endEdit is not called (or is called with an argument indicating that
|
|
the edit session is to be aborted) then the changes of a session will not
|
|
be stored to the DB.
|
|
When an edit session is successfully closed all clients will be informed
|
|
about the changes via callbacks.
|
|
|
|
|
|
2.3 Modification History
|
|
------------------------
|
|
The simplification layer issues logs for every change to the database. This
|
|
log can be written by the actual database into a file.
|
|
Such a file can serve to recover from the unlikely event of a corrupted
|
|
database.
|
|
It can also be used to keep track of the authors of modifications.
|
|
|
|
|
|
2.4 Extendability
|
|
-----------------
|
|
Gwenhywfar's plugin framework is used to allow for easy extension.
|
|
Gwen already provides a plugin which stores data in files in a local
|
|
folder.
|
|
I'm currently planning on writing a network-based plugin which allows
|
|
to use a database by multiple client processes/machines concurrently.
|
|
|
|
|
|
The client interface is in st_client.h.
|
|
|
|
|
|
|
|
3. Basic Plugin API
|
|
===================
|
|
The plugin interface (i.e. to be used by plugins) is in st_storage_be.h.
|
|
It should only be used by a network-based plugin to provide the client-part.
|
|
Such a plugin needs to pass all basic functions to the real storage on the
|
|
server.
|
|
|
|
Storage plugins should rather use the Simplified Plugin API.
|
|
|
|
|
|
|
|
4. Simplified Plugin API
|
|
========================
|
|
|
|
The file smp_storage_be.h contains a simplified interface for plugins. This
|
|
interface contains all the code to reach the goals stated above while
|
|
simplifying the API for derived plugins.
|
|
|
|
Plugins using this API will just have to provide a few very simple lowlevel
|
|
functions (such as WriteType, WriteObject, ReadObject etc).
|
|
|
|
All plugins should use this API instead of the basic plugin API mentioned
|
|
above.
|
|
|
|
|
|
|
|
|