Apache Zeta Components Manual :: File Source for base_replacement_strategy.php

Source for file base_replacement_strategy.php

Documentation is available at base_replacement_strategy.php

  1. <?php
  2. /**
  3.  * File containing the abstract ezcCacheStackBaseReplacementStrategy class.
  4.  *
  5.  * Licensed to the Apache Software Foundation (ASF) under one
  6.  * or more contributor license agreements.  See the NOTICE file
  7.  * distributed with this work for additional information
  8.  * regarding copyright ownership.  The ASF licenses this file
  9.  * to you under the Apache License, Version 2.0 (the
  10.  * "License"); you may not use this file except in compliance
  11.  * with the License.  You may obtain a copy of the License at
  12.  * 
  13.  *   http://www.apache.org/licenses/LICENSE-2.0
  14.  * 
  15.  * Unless required by applicable law or agreed to in writing,
  16.  * software distributed under the License is distributed on an
  17.  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  18.  * KIND, either express or implied.  See the License for the
  19.  * specific language governing permissions and limitations
  20.  * under the License.
  21.  *
  22.  * @package Cache
  23.  * @version //autogentag//
  24.  * @license http://www.apache.org/licenses/LICENSE-2.0 Apache License, Version 2.0
  25.  * @filesource
  26.  */
  27.  
  28. /**
  29.  * Base class for LRU and LFU replacement strategies.
  30.  *
  31.  * This class implements the LRU and LFU replacement strategies generically.
  32.  *
  33.  * <ul>
  34.  *  <li>{@link ezcCacheStackLruReplacementStrategy}</li>
  35.  *  <li>{@link ezcCacheStackLfuReplacementStrategy}</li>
  36.  * </ul>
  37.  * are both only wrappers around this class, which implement a different {@link }
  38.  * checkMetaData()}, since both strategies use different meta data structures.
  39.  *
  40.  * The (normally abstract static) method
  41.  *  checkMetaData( ezcCacheStackMetaData $metaData );
  42.  * must also be implemented by deriving classes. It must check if the given
  43.  * $metaData is an instance of the correct class. In other cases, an {@link }
  44.  * ezcCacheInvalidMetaDataException} must be throwen.
  45.  *
  46.  * For more information on replacement strategies please refer to {@see 
  47.  * http://en.wikipedia.org/wiki/Cache_algorithms}.
  48.  *
  49.  * @package Cache
  50.  * @version //autogen//
  51.  *
  52.  * @access private
  53.  */
  54. abstract class ezcCacheStackBaseReplacementStrategy implements ezcCacheStackReplacementStrategy
  55. {
  56.     /**
  57.      * Stores the given $itemData in the storage given in $conf.
  58.      *
  59.      * This method stores the given $itemData assigned to $itemId and
  60.      * optionally $itemAttributes in the {@link ezcCacheStackableStorage} given
  61.      * in $conf. In case the storage has reached the $itemLimit defined in
  62.      * $conf, it must be freed according to $freeRate {@link }
  63.      * ezcCacheStackStorageConfiguration}.
  64.      *
  65.      * The freeing of items from the storage must first happen via {@link }
  66.      * ezcCacheStackableStorage::purge()}, which removes outdated items from
  67.      * the storage and returns the affected IDs. In case this does not last to
  68.      * free the desired number of items, the replacement strategy specific
  69.      * algorithm for freeing takes effect.
  70.      *
  71.      * After the necessary freeing process has been performed, the item is
  72.      * stored in the storage and the $metaData is updated accordingly.
  73.      *
  74.      * @param ezcCacheStackStorageConfiguration $conf 
  75.      * @param ezcCacheStackMetaData $metaData 
  76.      * @param string $itemId 
  77.      * @param mixed $itemData 
  78.      * @param array(string=>string) $itemAttributes 
  79.      */
  80.     public static function store(
  81.         ezcCacheStackStorageConfiguration $conf,
  82.         ezcCacheStackMetaData $metaData,
  83.         $itemId,
  84.         $itemData,
  85.         $itemAttributes array()
  86.     )
  87.     {
  88.         if !$metaData->hasItem$conf->id$itemId )
  89.              && $metaData->reachedItemLimit$conf->id$conf->itemLimit ) )
  90.         {
  91.             self::freeData(
  92.                 $conf,
  93.                 $metaData,
  94.                 // Number of items to remove, round() returns float
  95.                 (int) round$conf->freeRate $conf->itemLimit )
  96.             );
  97.         }
  98.         $conf->storage->store(
  99.             $itemId$itemData$itemAttributes
  100.         );
  101.         $metaData->addItem$conf->id$itemId );
  102.     }
  103.  
  104.     /**
  105.      * Frees $freeNum number of item slots in $storage.
  106.      *
  107.      * This method first purges outdated items from the storage inside
  108.      * $conf using {@link ezcCacheStackableStorage::purge()}.
  109.      * If this does not free $freeNum items, least recently used items
  110.      * (determined from {@link ezcCacheStackMetaData}) will be removed from the
  111.      * storage using {@link ezcCacheStackableStorage::delete()}.
  112.      * 
  113.      * @param ezcCacheStackStorageConfiguration $conf 
  114.      * @param ezcCacheStackMetaData $metaData 
  115.      * @param int $freeNum 
  116.      */
  117.     private static function freeData(
  118.         ezcCacheStackStorageConfiguration $conf,
  119.         ezcCacheStackMetaData $metaData,
  120.         $freeNum
  121.     )
  122.     {
  123.         $purgedIds $conf->storage->purge();
  124.         // Unset purged items in meta data
  125.         foreach $purgedIds as $purgedId )
  126.         {
  127.             $metaData->removeItem$conf->id$purgedId );
  128.         }
  129.         $freeNum $freeNum count$purgedIds );
  130.  
  131.         // Not enough items have been purged, remove manually
  132.         if $freeNum )
  133.         {
  134.             $purgeOrder $metaData->getReplacementItems();
  135.             foreach $purgeOrder as $id => $replacementData )
  136.             {
  137.                 // Purge only if available in the current storage
  138.                 if $metaData->hasItem$conf->id$id ) )
  139.                 {
  140.                     // Purge all items with this ID, no matter which
  141.                     // attributes, therefore: $search = true.
  142.                     $deletedIds $conf->storage->delete$idnulltrue );
  143.                     $metaData->removeItem$conf->id$id );
  144.  
  145.                     // Purged enough?
  146.                     if --$freeNum == )
  147.                     {
  148.                         break;
  149.                     }
  150.                 }
  151.             }
  152.         }
  153.     }
  154.  
  155.     /**
  156.      * Restores the data with the given $dataId from the storage given in $conf.
  157.      *
  158.      * This method takes care of restoring the item with ID $itemId and
  159.      * optionally $itemAttributes from the {@link ezcCacheStackableStorage}
  160.      * given in $conf. The parameters $itemId, $itemAttributes and $search are
  161.      * forwarded to {@link ezcCacheStackableStorage::restore()}, the returned
  162.      * value (item data on successful restore, otherwise false) are returned by
  163.      * this method.
  164.      *
  165.      * The method must take care that the restore process is reflected in
  166.      * $metaData according to the spcific replacement strategy implementation.
  167.      *
  168.      * @param ezcCacheStackStorageConfiguration $conf 
  169.      * @param ezcCacheStackMetaData $metaData 
  170.      * @param string $itemId 
  171.      * @param array(string=>string) $itemAttributes 
  172.      * @param bool $search 
  173.      *
  174.      * @return mixed Restored data or false.
  175.      * @throws ezcCacheInvalidMetaDataException
  176.      *          if the given $metaData is not processable by this replacement
  177.      *          strategy.
  178.      */
  179.     public static function restore(
  180.         ezcCacheStackStorageConfiguration $conf,
  181.         ezcCacheStackMetaData $metaData,
  182.         $itemId,
  183.         $itemAttributes array(),
  184.         $search false
  185.     )
  186.     {
  187.         $item $conf->storage->restore(
  188.             $itemId,
  189.             $itemAttributes,
  190.             $search
  191.         );
  192.  
  193.         // Update item meta data
  194.         if $item === false )
  195.         {
  196.             // Item has been purged / got outdated
  197.             $metaData->removeItem$conf->id$itemId );
  198.         }
  199.         else
  200.         {
  201.             // Updates the use time
  202.             $metaData->addItem$conf->id$itemId );
  203.         }
  204.         return $item;
  205.     }
  206.  
  207.     /**
  208.      * Deletes the data with the given $itemId from the given $storage.
  209.      *
  210.      * This method takes care about deleting the item identified by $itemId and
  211.      * optionally $itemAttributes from the {@link ezcCacheStackableStorage}
  212.      * give in $conf. The parameters $itemId, $itemAttributes and $search are
  213.      * therefore forwarded to {@link ezcCacheStackableStorage::delete()}. This
  214.      * method returns a list of all item IDs that have been deleted by the
  215.      * call. The method reflects these changes in $metaData.
  216.      *
  217.      * @param ezcCacheStackStorageConfiguration $conf 
  218.      * @param ezcCacheStackMetaData $metaData 
  219.      * @param string $itemId 
  220.      * @param array(string=>string) $itemAttributes 
  221.      * @param bool $search 
  222.      *
  223.      * @return array(string) Deleted item IDs.
  224.      * @throws ezcCacheInvalidMetaDataException
  225.      *          if the given $metaData is not processable by this replacement
  226.      *          strategy.
  227.      */
  228.     public static function delete(
  229.         ezcCacheStackStorageConfiguration $conf,
  230.         ezcCacheStackMetaData $metaData,
  231.         $itemId,
  232.         $itemAttributes array(),
  233.         $search false
  234.     )
  235.     {
  236.         $deletedIds $conf->storage->delete(
  237.             $itemId,
  238.             $itemAttributes,
  239.             $search
  240.         );
  241.  
  242.         // Possibly deleted multiple items
  243.         foreach $deletedIds as $id )
  244.         {
  245.             $metaData->removeItem$conf->id$id );
  246.         }
  247.         return $deletedIds;
  248.     }
  249.  
  250.     /**
  251.      * Pseudo implementation.
  252.      *
  253.      * This method would normally be declared abstract. However, PHP does not
  254.      * allow abstract static methods.
  255.      *
  256.      * Deriving classes must check inside this method, if the given $metaData
  257.      * is appropriate for them. If not, an {@link }
  258.      * ezcCacheInvalidMetaDataException} must be throwen.
  259.      * 
  260.      * @param ezcCacheStackMetaData $metaData 
  261.      *
  262.      * @throws ezcCacheInvalidMetaDataException
  263.      *          if the given $metaData is not processable by this replacement
  264.      *          strategy.
  265.      */
  266. /*   abstract protected static function checkMetaData( ezcCacheStackMetaData $metaData ) */
  267. }
  268.  
  269. ?>
Documentation generated by phpDocumentor 1.4.3