## Apache Zeta Components Manual :: Docs For Class ezcCacheStorageMemory

### Cache::ezcCacheStorageMemory

### Class ezcCacheStorageMemory

Base abstract class for all memory storage classes.

Abstract classes extending this class:

- ezcCacheStorageMemcache
- ezcCacheStorageApc

Implementations derived from this class and its descendants:

- ezcCacheStorageMemcachePlain
- ezcCacheStorageApcPlain
- ezcCacheStorageFileApcArray

Source for this file: /Cache/src/storage/memory.php

### Implements interfaces:

- ezcCacheStackableStorage
- ezcCacheStackMetaDataStorage

    ezcCacheStorage
       |
       --ezcCacheStorageMemory

Version: | //autogentag//

### Descendants

Child Class | Description
--- | ---
ezcCacheStorageApc | This class is a common base class for all APC based storage classes.
ezcCacheStorageMemcache | This class is a common base class for all Memcache 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 exist, 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

##### Exceptions:

Type | Description
--- | ---
`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
--- | ---
`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.
`ezcCacheStorageMemcache::__construct()` | Creates a new cache storage in the given location.

#### 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 | Whether to search for items if not found directly

##### Exceptions:

Type | Description
--- | ---
`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 exist, 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.

##### Implementation of:

Method | Description
--- | ---
`ezcCacheStackMetaDataStorage::lock()` | Acquire a lock on the storage.

#### 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 |

##### Implementation of:

Method | Description
--- | ---
`ezcCacheStackableStorage::purge()` | Purge outdated data from the storage.

#### 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.

##### Implementation of:

Method | Description
--- | ---
`ezcCacheStackableStorage::reset()` | Reset the complete storage.

#### 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 | Whether 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.

##### Implementation of:

Method | Description
--- | ---
`ezcCacheStackMetaDataStorage::restoreMetaData()` | Restores and returns the meta data struct.

#### 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 |

##### Implementation of:

Method | Description
--- | ---
`ezcCacheStackMetaDataStorage::storeMetaData()` | Stores the given meta data struct.

#### 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.

##### Implementation of:

Method | Description
--- | ---
`ezcCacheStackMetaDataStorage::unlock()` | Release a lock on the storage.

#### 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.

Documentation generated by phpDocumentor 1.4.3