Path

ez components / documentation / api reference / 2008.2 / cache

eZ Components 2008.2

Cache: ezcCacheStorageMemory

[ Tutorial ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcCacheStorageMemory

Base abstract class for all memory storage classes. [source]

Implemented Interfaces

Abstract classes extending this class: Implementations derived from this class and its descendants:

Parents

ezcCacheStorage
   |
   --ezcCacheStorageMemory

Descendents

Child Class Description
ezcCacheStorageMemcache This class is a common base class for all Memcache based storage classes.
ezcCacheStorageApc This class is a common base class for all APC based storage classes.

Member Variables

protected ezcCacheMemoryBackend $backend
Holds the memory backend object which communicates with the memory handler (Memcache, APC).
protected string $backendName
Holds the name of the memory backend.
protected array(mixed) $registry = array()
Holds the registry.
protected string $registryName
Holds the name of the registry.
protected array(mixed) $searchRegistry = array()
Holds the search registry.

Inherited Member Variables

From ezcCacheStorage:
protected  ezcCacheStorage::$properties

Method Summary

public ezcCacheStorageMemory __construct( $location, [$options = array()] )
Creates a new cache storage in the given location.
protected int calcLifetime( $identifier, [$dataObject = false] )
Calculates the lifetime remaining for a cache object.
public int countDataItems( [$id = null], [$attributes = array()] )
Returns the number of items in the cache matching a certain criteria.
public void delete( [$id = null], [$attributes = array()], [$search = false] )
Deletes the data associated with $id or $attributes from the cache.
protected void fetchSearchRegistry( [$requireFresh = false] )
Fetches the search registry from the backend or creates it if empty.
protected string generateAttrStr( [$attributes = array()] )
Generates a string from the $attributes array.
public string generateIdentifier( $id, [$attributes = null] )
Generates the storage internal identifier from ID and attributes.
public int getRemainingLifetime( $id, [$attributes = array()] )
Returns the time in seconds which remains for a cache object, before it gets outdated. In case the cache object is already outdated or does not exists, this method returns 0.
public void lock( )
Acquire a lock on the storage.
public array(string) purge( [$limit = null] )
Purge outdated data from the storage.
protected void registerIdentifier( [$id = null], [$attributes = array()], [$identifier = null] )
Registers an identifier to facilitate searching.
public void reset( )
Reset the complete storage.
public mixed restore( $id, [$attributes = array()], [$search = false] )
Restores the data from the cache.
public ezcCacheStackMetaData restoreMetaData( )
Restores and returns the meta data struct.
protected array(mixed) search( [$id = null], [$attributes = array()] )
Searches the storage for data defined by ID and/or attributes.
public string store( $id, $data, [$attributes = array()] )
Stores data to the cache storage under the key $id.
public void storeMetaData( $metaData )
Stores the given meta data struct.
protected void storeSearchRegistry( )
Stores the search registry in the backend.
public void unlock( )
Release a lock on the storage.
protected void unRegisterIdentifier( [$id = null], [$attributes = array()], [$identifier = null], [$delayStore = false] )
Un-registers a previously registered identifier.
protected void validateLocation( )
Checks if the location property is valid.

Inherited Methods

From ezcCacheStorage :
public ezcCacheStorage ezcCacheStorage::__construct()
Creates a new cache storage in the given location.
public abstract int ezcCacheStorage::countDataItems()
Return the number of items in the cache matching a certain criteria.
public abstract void ezcCacheStorage::delete()
Delete data from the cache.
public string ezcCacheStorage::getLocation()
Returns the location.
public ezcCacheStorageOptions ezcCacheStorage::getOptions()
Return the currently set options.
public abstract int ezcCacheStorage::getRemainingLifetime()
Returns the time ( in seconds ) that remains for a cache object, before it gets outdated. In case the cache object is already outdated or does not exists, this method returns 0.
public abstract mixed ezcCacheStorage::restore()
Restore data from the cache.
public void ezcCacheStorage::setOptions()
Set new options.
public abstract string ezcCacheStorage::store()
Store data to the cache storage.
protected abstract void ezcCacheStorage::validateLocation()
Checks if the location property is valid.

Methods

__construct

ezcCacheStorageMemory __construct( string $location, [ $options = array()] )
Creates a new cache storage in the given location.
Options can contain the 'ttl' (Time-To-Live). Specific implementations can have additional options.

Parameters

Name Type Description
$location string Path to the cache location. Null for memory-based storage and an existing writeable path for file or memory/file storage.
$options array(string=>string) Options for the cache

Throws

ClassDescription
ezcBasePropertyNotFoundException If you tried to set a non-existent option value. The accepted options depend on the ezcCacheStorage implementation and may vary.

Redefinition of

Method Description
ezcCacheStorage::__construct() Creates a new cache storage in the given location.

Redefined in descendants as

Method Description
ezcCacheStorageMemcache::__construct() Creates a new cache storage in the given location.
ezcCacheStorageApc::__construct() Creates a new cache storage in the given location.
ezcCacheStorageFileApcArray::__construct() Creates a new cache storage in the given location. The location in case of this storage class must a valid file system directory.

calcLifetime

int calcLifetime( string $identifier, [bool $dataObject = false] )
Calculates the lifetime remaining for a cache object.
In case the TTL options is set to true, this method always returns 1.

Parameters

Name Type Description
$identifier string The memcache identifier
$dataObject bool The optional data object for which to calculate the lifetime

Redefined in descendants as

Method Description
ezcCacheStorageFileApcArray::calcLifetime() Calculates the lifetime remaining for a cache object.

countDataItems

int countDataItems( [string $id = null], [array(string=>string) $attributes = array()] )
Returns the number of items in the cache matching a certain criteria.
This method determines if cache data described by the given ID and/or attributes exists. It returns the number of cache data items found.

Parameters

Name Type Description
$id string The item ID
$attributes array(string=>string) Attributes describing the data

Redefinition of

Method Description
ezcCacheStorage::countDataItems() Return the number of items in the cache matching a certain criteria.

delete

void delete( [string $id = null], [array(string=>string) $attributes = array()], [bool $search = false] )
Deletes the data associated with $id or $attributes from the cache.
Additional attributes provided will matched additionally. This can give you an immense speed improvement against just searching for ID (see ezcCacheStorage::restore()).
If you only provide attributes for deletion of cache data, all cache data matching these attributes will be purged.

Parameters

Name Type Description
$id string The item ID to purge
$attributes array(string=>string) Attributes describing the data to restore
$search bool Wheather to search for items if not found directly

Throws

ClassDescription
ezcBaseFilePermissionException If an already existsing cache file could not be unlinked. This exception means most likely that your cache directory has been corrupted by external influences (file permission change).

Redefinition of

Method Description
ezcCacheStorage::delete() Delete data from the cache.

Redefined in descendants as

Method Description
ezcCacheStorageFileApcArray::delete() Deletes the data associated with $id or $attributes from the cache.

fetchSearchRegistry

void fetchSearchRegistry( [bool $requireFresh = false] )
Fetches the search registry from the backend or creates it if empty.

Parameters

Name Type Description
$requireFresh bool To create a new search registry or not

generateAttrStr

string generateAttrStr( [array(string=>string) $attributes = array()] )
Generates a string from the $attributes array.

Parameters

Name Type Description
$attributes array(string=>string) Attributes describing the data

generateIdentifier

string generateIdentifier( string $id, [array(string=>string) $attributes = null] )
Generates the storage internal identifier from ID and attributes.

Parameters

Name Type Description
$id string The ID
$attributes array(string=>string) Attributes describing the data

getRemainingLifetime

int getRemainingLifetime( string $id, [array(string=>string) $attributes = array()] )
Returns the time in seconds which remains for a cache object, before it gets outdated. In case the cache object is already outdated or does not exists, this method returns 0.

Parameters

Name Type Description
$id string The item ID
$attributes array(string=>string) Attributes describing the data

Redefinition of

Method Description
ezcCacheStorage::getRemainingLifetime() Returns the time ( in seconds ) that remains for a cache object, before it gets outdated. In case the cache object is already outdated or does not exists, this method returns 0.

lock

void lock( )
Acquire a lock on the storage.
This method acquires a lock on the storage. If locked, the storage must block all other method calls until the lock is freed again using ezcCacheStackMetaDataStorage::unlock(). Methods that are called within the request that successfully acquired the lock must succeed as usual.

purge

array(string) purge( [int $limit = null] )
Purge outdated data from the storage.
This method purges outdated data from the cache. If $limit is given, a maximum of $limit items is purged. Otherwise all outdated items are purged. The method returns an array containing the IDs of all cache items that have been purged.

Parameters

Name Type Description
$limit int  

registerIdentifier

void registerIdentifier( [string $id = null], [array $attributes = array()], [string $identifier = null] )
Registers an identifier to facilitate searching.

Parameters

Name Type Description
$id string ID for the cache item
$attributes array Attributes for the cache item
$identifier string Identifier generated for the cache item

reset

void reset( )
Reset the complete storage.
This method resets the complete cache storage. All content (including content stored with the ezcCacheStackMetaDataStorage interfacer) must be deleted and the cache storage must appear as if it has just newly been created.

restore

mixed restore( string $id, [array(string=>string) $attributes = array()], [bool $search = false] )
Restores the data from the cache.
During access to cached data the caches are automatically expired. This means, that the ezcCacheStorageMemory object checks before returning the data if it's still actual. If the cache has expired, data will be deleted and false is returned.
You should always provide the attributes you assigned, although the cache storages must be able to find a cache ID even without them. BEWARE: Finding cache data only by ID can be much slower than finding it by ID and attributes.

Parameters

Name Type Description
$id string The item ID to restore
$attributes array(string=>string) Attributes describing the data to restore
$search bool Wheather to search for items if not found directly

Redefinition of

Method Description
ezcCacheStorage::restore() Restore data from the cache.

Redefined in descendants as

Method Description
ezcCacheStorageFileApcArray::restore() Restores the data from the cache.

restoreMetaData

ezcCacheStackMetaData restoreMetaData( )
Restores and returns the meta data struct.
This method fetches the meta data stored in the storage and returns the according struct of type ezcCacheStackMetaData. The meta data must be stored inside the storage, but should not be visible as normal cache items to the user.

search

array(mixed) search( [string $id = null], [array(string=>string) $attributes = array()] )
Searches the storage for data defined by ID and/or attributes.

Parameters

Name Type Description
$id string The item ID
$attributes array(string=>string) Attributes describing the data

store

string store( string $id, mixed $data, [array(string=>string) $attributes = array()] )
Stores data to the cache storage under the key $id.
The type of cache data which is expected by an ezcCacheStorageMemory implementation depends on the backend. In most cases strings and arrays will be accepted, in some rare cases only strings might be accepted.
Using attributes you can describe your cache data further. This allows you to deal with multiple cache data at once later. Some ezcCacheStorageMemory implementations also use the attributes for storage purposes. Attributes form some kind of "extended ID".

Parameters

Name Type Description
$id string Unique identifier for the data
$data mixed The data to store
$attributes array(string=>string) Attributes describing the cached data

Redefinition of

Method Description
ezcCacheStorage::store() Store data to the cache storage.

Redefined in descendants as

Method Description
ezcCacheStorageFileApcArray::store() Stores data to the cache storage.

storeMetaData

void storeMetaData( ezcCacheStackMetaData $metaData )
Stores the given meta data struct.
This method stores the given $metaData inside the storage. The data must be stored with the same mechanism that the storage itself uses. However, it should not be stored as a normal cache item, if possible, to avoid accedental user manipulation.

Parameters

Name Type Description
$metaData ezcCacheStackMetaData  

storeSearchRegistry

void storeSearchRegistry( )
Stores the search registry in the backend.

unlock

void unlock( )
Release a lock on the storage.
This method releases the lock of the storage, that has been acquired via ezcCacheStackMetaDataStorage::lock(). After this method has been called, blocked method calls (including calls to lock()) can suceed again.

unRegisterIdentifier

void unRegisterIdentifier( [string $id = null], [array $attributes = array()], [string $identifier = null], [bool $delayStore = false] )
Un-registers a previously registered identifier.

Parameters

Name Type Description
$id string ID for the cache item
$attributes array Attributes for the cache item
$identifier string Identifier generated for the cache item
$delayStore bool Delays the storing of the updated search registry

validateLocation

void validateLocation( )
Checks if the location property is valid.

Redefinition of

Method Description
ezcCacheStorage::validateLocation() Checks if the location property is valid.

Redefined in descendants as

Method Description
ezcCacheStorageFileApcArray::validateLocation() Checks the path in the location property exists, and is read-/writable. It throws an exception if not.

Last updated: Mon, 05 Jan 2009