It provides a general interface for the caching services by encapsulating the calls specific to the data storage interface.
Each cache database in use is encapsulated 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 necessary if they would block other processes. It is unknown to me if such handles would be safe to use over several requests.
Namespacing:
Each 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 configuration directives:
package | midcom.services |
---|
The data store is opened either read-only or read-write when this function executes.
string
The key to check for.boolean
Indicating existence.The data store is opened either read-only or read-write when this function executes.
string
Key to look up.string
$data The data associated with the key.Add any custom startup code here. The configuration variables are all initialized when this handler is called.
Called, if the backend is no longer used.
If $write is set to true, it must be opened in read/write access, otherwise read-only access is sufficient.
If the database cannot be opened, midcom_error should be thrown.
The concrete subclass must track any resource handles internally, of course.
boolean
True, if read/write access is required.The data store is opened in read-write mode when this function executes.
Any error condition should throw midcom_error and must close the data store before doing so.
string
The key to store at.string
The data to store.The data store is opened in read-write mode when this function executes.
Deleting non existent keys should fail silently. All other error conditions should throw midcom_error and must close the data store before doing so.
string
The key to delete.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 throw midcom_error
If the database is already closed, the request is ignored silently.
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.
string
The key to check for.boolean
Indicating existence.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.
string
Key to look up.string
$data The data associated with the key.After base class initialization, the event handler _on_initialize is called, in which all backend specific stuff should be done.
string
The name ("identifier") of the handler instance.array
The configuration to use.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.
boolean
True, if read/write access is required.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.
string
The key to store at.string
The data to store.Deleting non existent 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.
string
The key to delete.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 throw midcom_error.
This calls the corresponding event.
If it does not exist, it will be created automatically. Errors will be handled by midcom_error.
This is populated during initialize().
This variable my not be written to after the instance has been created.
This is also true, if we are in read-write mode, naturally.
Therefore, this flag is also used for checking whether the database is open in general.