Docs For Class midcom_services_cache

midcom_services_cache_backend

Description

This is the base class of the MidCOM Cache backend infrastructure. It provides a general interface for the caching services by encaspulating the calls specific to the data storage interface.

Each cache database in use is encaspulated by its own instance of this service, identified by their name and the handler which controls it. The name must be unique throughout the entire server. See Namespacing below for details.

A handlers type is identified by its class name, so midcom_sercices_cache_backend_dba is the DBA handler from the original pre 2.4 MidCOM.

Inter-Process synchronization:

Backend drivers have to ensure they can be accessed concurrently to ensure Database integrity.

Resource handles:

Resource handles (for example for DBA access) should be closed if neccessary if they would block other processes. It is unknown to me if such handles would be safe to use over several requests.

Namespacing:

Eache cache database in use has a name, which must consist only of characters valid for file names on the current system. You may create any file or directory within the midcom cache directory as long as you use your name as a prefix.

If you want to stay on the safe side, only cache names using the characters matching the regex class [a-zA-Z0-9._-] should be used.

General configutation directives:

string directory: The subdirectory in the cache's base directory to use by this backend. This is automatically concatenated with the systemwide cache base directory.
string driver: The concrete class instance to create. It must match the name of a file within the backend directory. Note, that the class must also be named accordingly, the driver "dba" is searched in the file "backend/dba.php" and must be of the type "midcom_services_cache_backend_dba".
bool auto_serialize: Set this to true to enable automatic serialization on storage and/or retrieval. Disabled by default.

Located in /midcom/services/cache/backend.php (line 56)

Direct descendents

Class	Description
midcom_services_cache_backend_dba	DBA-Style flat file database caching backend.
midcom_services_cache_backend_flatfile	Simple flat file database backend. Creates a file per key.

Variable Summary

bool $_auto_serialize

string $_cache_dir

Array $_config

string $_name

bool $_open_for_reading

bool $_open_for_writing

Method Summary

midcom_services_cache_backend midcom_services_cache_backend ()

void close ()

bool exists (string $key)

string get (string $key)

void initialize (string $name, Array $config)

void open ([bool $write = false])

void put (string $key, string $data)

void remove (string $key)

void remove_all ()

void shutdown ()

void _check_cache_dir ()

void _close ()

bool _exists (string $key)

string _get (string $key)

void _on_initialize ()

void _on_shutdown ()

void _open (bool $write)

void _put (string $key, string $data)

void _remove (string $key)

void _remove_all ()

Variables

bool $_auto_serialize = false (line 93)

Set this to true if you plan to store PHP data structures rather then strings, the interface will automatically serialize/unserialize the data you store/retrieve from the database.

Configuration variable

access: protected

string $_cache_dir = null (line 84)

The base directory in which we may add files and directories within our namespace.

Configuration variable

access: protected

Array $_config = null (line 77)

Configuration key array. This is populated during initialize().

Configuration variable

access: protected

string $_name = null (line 70)

The backend instance name. This variable my not be written to after the instance has been created.

Configuration variable

access: protected

bool $_open_for_reading = false (line 112)

True, if the database has been opened for reading previously. This is also true, if we are in read-write mode, naturally.

Internal state variable

Therefore, this flag is also used for checking wether the database is open in general.

access: private

bool $_open_for_writing = false (line 119)

True, if the database has been opened for writing previously.

Internal state variable

access: private

Methods

Constructor midcom_services_cache_backend (line 128)

The constructor just initializes the empty object. The actual initialization is done by the initialize() event which does the actual configuration.

midcom_services_cache_backend midcom_services_cache_backend ()

close (line 360)

Close the database that has been opened previosly with open(). If the database is already closed, the request is ignored silently.

void close ()

exists (line 386)

Checks, wether the given key exists in the Database. If the data store has not yet been opened for reading, it will be opened automatically prior to the call, and closed automatically again afterwards.

return: Indicating existance.

bool exists (string $key)

string $key: The key to check for.

Redefined in descendants as:

midcom_services_cache_backend_flatfile::exists()

get (line 419)

Get the data accociated with the given key. If the data store has not yet been opened for reading, it will be opened automatically prior to the call, and closed automatically again afterwards.

return: The data accociated with the key.

string get (string $key)

string $key: Key to look up.

Redefined in descendants as:

midcom_services_cache_backend_flatfile::get()

initialize (line 143)

Initializes the backend by acquiring all neccessary information required for runtime.

After base class initialization, the event handler _on_initialize is called, in which all backend specific stuff should be done.

void initialize (string $name, Array $config)

string $name: The name ("identifier") of the handler instanace.
Array $config: The configuration to use.

open (line 329)

Open the database for usage. If $write is set to true, it must be opened in read/write access, otherwise read-only access is sufficient.

If the database is reopened with different access permissions then currently specified (e.g. if going from read-only to read-write), the database is closed prior to opening it again. If the permissions match the current state, nothing is done.

void open ([bool $write = false])

bool $write: True, if read/write access is required.

put (line 460)

Store the given key/value pair, any existing entry with the same key has to be silently overwritten. If the data store has not yet been opened for writing, it will be opened automatically prior to the call, and closed automatically again afterwards.

void put (string $key, string $data)

string $key: The key to store at.
string $data: The data to store.

Redefined in descendants as:

midcom_services_cache_backend_flatfile::put()

remove (line 499)

Delete the data with the given key from the database. Deleting non existant keys should fail silently. If the data store has not yet been opened for writing, it will be opened automatically prior to the call, and closed automatically again afterwards.

void remove (string $key)

string $key: The key to delete.

Redefined in descendants as:

midcom_services_cache_backend_flatfile::remove()

remove_all (line 533)

Drops the entire database and creates an empty one.

The database must not be opened by this process when this is called. If it is, it will be automatically closed prior to executing this call.

Any error condition should call midcom_application::generate_error().

void remove_all ()

Redefined in descendants as:

midcom_services_cache_backend_flatfile::remove_all()

shutdown (line 176)

Shutdown the backend. This calls the corresponding event.

void shutdown ()

_check_cache_dir (line 190)

This helper will ensure that the cache base directory is created and usable by checking it is actually a directory. If it does not exist, it will be created automatically. Errors will be handled by calling generate_error.

access: private

void _check_cache_dir ()

_close (line 255)

Close the database that has been opened previosly with _open().

Internal Data IO API method.

access: protected

void _close ()

Redefined in descendants as:

midcom_services_cache_backend_dba::_close()

_exists (line 277)

Checks, wether the given key exists in the Database.

Internal Data IO API method.

The data store is opened either read-only or read-write when this function executes.

return: Indicating existance.
access: protected

bool _exists (string $key)

string $key: The key to check for.

Redefined in descendants as:

midcom_services_cache_backend_dba::_exists()

_get (line 266)

Get the data accociated with the given key.

Internal Data IO API method.

The data store is opened either read-only or read-write when this function executes.

return: The data accociated with the key.
access: protected

string _get (string $key)

string $key: Key to look up.

Redefined in descendants as:

midcom_services_cache_backend_dba::_get()

_on_initialize (line 222)

Backend initialization

Event handler function.

Add any custom startup code here. The configuraiton variables are all initialized when this handler is called.

access: protected

void _on_initialize ()

Redefined in descendants as:

midcom_services_cache_backend_dba::_on_initialize() : This handler completes the configuration.
midcom_services_cache_backend_flatfile::_on_initialize() : This handler completes the configuration.

_on_shutdown (line 229)

Backend shutdown

Event handler function.

Called, if the backend is no longer used.

access: protected

void _on_shutdown ()

_open (line 250)

Open the database for usage. If $write is set to true, it must be opened in read/write access, otherwise read-only access is sufficient.

Internal Data IO API method.

If the database cannot be opened, midcom_application::generate_error() should be called.

The concrete subclass must track any resource handles internally, of course.

access: protected

void _open (bool $write)

bool $write: True, if read/write access is required.

Redefined in descendants as:

midcom_services_cache_backend_dba::_open() : Internal helper, which opens a handle to the DBA file in either read-only or read/write mode. The handle has to be closed by the _close() function.

_put (line 291)

Store the given key/value pair, any existing entry with the same key has to be silently overwritten.

Internal Data IO API method.

The data store is opened in read-write mode when this function executes.

Any error condition should call midcom_application::generate_error() and must close the data store before doing so.

access: protected

void _put (string $key, string $data)

string $key: The key to store at.
string $data: The data to store.

Redefined in descendants as:

midcom_services_cache_backend_dba::_put()

_remove (line 304)

Delete the data with the given key from the database.

Internal Data IO API method.

The data store is opened in read-write mode when this function executes.

Deleting non existant keys should fail silently. All other error conditions should call midcom_application::generate_error() and must close the data store before doing so.

access: protected

void _remove (string $key)

string $key: The key to delete.

Redefined in descendants as:

midcom_services_cache_backend_dba::_remove()

_remove_all (line 314)

Drops the entire database, preferrably with some kind of truncate operation.

Internal Data IO API method.

The data store will not be opened in either read-only or read-write mode when this function executes, to allow for open/truncate operations.

Any error condition should call midcom_application::generate_error().

access: protected

void _remove_all ()

Redefined in descendants as:

midcom_services_cache_backend_dba::_remove_all()

Documentation generated on Mon, 21 Nov 2005 18:12:21 +0100 by phpDocumentor 1.3.0RC3