inc/classes/main/database/class_BaseDatabaseWrapper.php

   1 <?php
   2 /**
   3  * A generic database wrapper
   4  *
   5  * @author              Roland Haeder <webmaster@shipsimu.org>
   6  * @version             0.0.0
   7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2014 Core Developer Team
   8  * @license             GNU GPL 3.0 or any newer version
   9  * @link                http://www.shipsimu.org
  10  *
  11  * This program is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation, either version 3 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  23  */
  24 class BaseDatabaseWrapper extends BaseFrameworkSystem {
  25         /**
  26          * Cache instance
  27          */
  28         private $cacheInstance = NULL;
  29
  30         /**
  31          * Current table name to use
  32          */
  33         private $tableName = 'unknown';
  34
  35         /**
  36          * Protected constructor
  37          *
  38          * @return      void
  39          */
  40         protected function __construct ($class) {
  41                 // Call parent constructor
  42                 parent::__construct($class);
  43
  44                 // Initialize the cache instance
  45                 $this->initCacheInstance();
  46         }
  47
  48         /**
  49          * Initializes the cache instance with a new object
  50          *
  51          * @return      void
  52          */
  53         private final function initCacheInstance () {
  54                 // Set the new instance
  55                 $this->cacheInstance = CacheFactory::getFactory()->createConfiguredCache();
  56         }
  57
  58         /**
  59          * Setter for table name
  60          *
  61          * @param       $tableName      Name of table name to set
  62          * @return      void
  63          */
  64         protected final function setTableName ($tableName) {
  65                 $this->tableName = (string) $tableName;
  66         }
  67
  68         /**
  69          * Getter for table name
  70          *
  71          * @return      $tableName      Name of table name to set
  72          */
  73         protected final function getTableName () {
  74                 return $this->tableName;
  75         }
  76
  77         /**
  78          * 'Inserts' a data set instance into a local file database folder
  79          *
  80          * @param       $dataSetInstance        A storeable data set
  81          * @param       $onlyKeys                       Only use these keys for a cache key
  82          * @return      void
  83          */
  84         protected function queryInsertDataSet (StoreableCriteria $dataSetInstance, array $onlyKeys = array()) {
  85                 // Default cache key is NULL
  86                 $cacheKey = NULL;
  87
  88                 // Is cache enabled?
  89                 if ($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) {
  90                         // First get a key suitable for our cache and extend it with this class name
  91                         $cacheKey = $this->getCacheKeyByCriteria($dataSetInstance, $onlyKeys);
  92                         //* DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: Using cache key ' . $cacheKey . ' for purging ...');
  93                 } // END - if
  94
  95                 // Does this key exists in cache?
  96                 if (($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) && ($this->cacheInstance->offsetExists($cacheKey))) {
  97                         // Purge the cache
  98                         $this->cacheInstance->purgeOffset($cacheKey);
  99                 } // END - if
 100
 101                 // Handle it over to the middleware
 102                 $this->getDatabaseInstance()->queryInsertDataSet($dataSetInstance);
 103         }
 104
 105         /**
 106          * 'Updates' a data set instance with a database layer
 107          *
 108          * @param       $dataSetInstance        A storeable data set
 109          * @param       $onlyKeys                       Only use these keys for a cache key
 110          * @return      void
 111          */
 112         protected function queryUpdateDataSet (StoreableCriteria $dataSetInstance, array $onlyKeys = array()) {
 113                 // Init cache key
 114                 $cacheKey = NULL;
 115
 116                 // Is cache enabled?
 117                 if ($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) {
 118                         // First get a key suitable for our cache and extend it with this class name
 119                         $cacheKey = $this->getCacheKeyByCriteria($dataSetInstance, $onlyKeys);
 120                         //* DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: Using cache key ' . $cacheKey . ' for purging ...');
 121                 } // END - if
 122
 123                 // Does this key exists in cache?
 124                 if (($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) && ($this->cacheInstance->offsetExists($cacheKey))) {
 125                         // Purge the cache
 126                         $this->cacheInstance->purgeOffset($cacheKey);
 127                 } // END - if
 128
 129                 // Handle it over to the middleware
 130                 $this->getDatabaseInstance()->queryUpdateDataSet($dataSetInstance);
 131         }
 132
 133         /**
 134          * Getter for index key
 135          *
 136          * @return      $indexKey       Index key
 137          */
 138         public final function getIndexKey () {
 139                 return $this->getDatabaseInstance()->getIndexKey();
 140         }
 141
 142         /**
 143          * Getter for last exception
 144          *
 145          * @return      $lastException  Last exception or NULL if none occured
 146          */
 147         public final function getLastException () {
 148                 return $this->getDatabaseInstance()->getLastException();
 149         }
 150
 151         /**
 152          * Do a "select" query on the current table with the given search criteria and
 153          * store it in cache for later usage
 154          *
 155          * @param       $criteriaInstance       An instance of a Criteria class
 156          * @param       $onlyKeys                       Only use these keys for a cache key
 157          * @return      $resultInstance         An instance of a database result class
 158          */
 159         public function doSelectByCriteria (Criteria $criteriaInstance, array $onlyKeys = array()) {
 160                 // Default cache key if cache is not enabled
 161                 $cacheKey = NULL;
 162
 163                 // Is the cache enabled?
 164                 if ($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) {
 165                         // First get a key suitable for our cache and extend it with this class name
 166                         $cacheKey = $this->getCacheKeyByCriteria($criteriaInstance, $onlyKeys);
 167                 } // END - if
 168
 169                 // Does this key exists in cache?
 170                 if (($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) && ($this->cacheInstance->offsetExists($cacheKey, BaseDatabaseBackend::RESULT_INDEX_ROWS, 1))) {
 171                         // Debug message
 172                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: Cache used for cacheKey=' . $cacheKey . ':' . print_r($this->cacheInstance->offsetGet($cacheKey), TRUE));
 173
 174                         // Then use this result
 175                         $result = $this->cacheInstance->offsetGet($cacheKey);
 176                 } else {
 177                         // Debug message
 178                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: Quering database, cacheKey=' . $cacheKey);
 179
 180                         // Now it's time to ask the database layer for this select statement
 181                         $result = $this->getDatabaseInstance()->doSelectByTableCriteria($this->getTableName(), $criteriaInstance);
 182                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: result[]=' . gettype($result));
 183
 184                         // Cache the result if not null
 185                         if (!is_null($result)) {
 186                                 // A valid result has returned from the database layer
 187                                 $this->cacheInstance->offsetSet($cacheKey, $result);
 188                         } else {
 189                                 // This invalid result must be wrapped
 190                                 $result = array(
 191                                         BaseDatabaseBackend::RESULT_INDEX_STATUS    => 'invalid',
 192                                         BaseDatabaseBackend::RESULT_INDEX_EXCEPTION => $this->getDatabaseInstance()->getLastException()
 193                                 );
 194                         }
 195                 }
 196
 197                 // Create an instance of a DatabaseResult class with the given result
 198                 $resultInstance = ObjectFactory::createObjectByConfiguredName('database_result_class', array($result));
 199
 200                 // And return the instance
 201                 return $resultInstance;
 202         }
 203
 204         /**
 205          * Count the numbers of rows we shall receive
 206          *
 207          * @param       $criteriaInstance       An instance of a Criteria class
 208          * @param       $onlyKeys                       Only use these keys for a cache key
 209          * @return      $numRows                        Numbers of rows of database entries
 210          */
 211         public function doSelectCountByCriteria (Criteria $criteriaInstance, $onlyKeys =  array()) {
 212                 // Total numbers is -1 so we can distinglish between failed and valid queries
 213                 $numRows = 0;
 214
 215                 // Get the result from above method
 216                 $resultInstance = $this->doSelectByCriteria($criteriaInstance, $onlyKeys);
 217
 218                 // Was that query fine?
 219                 if ($resultInstance->ifStatusIsOkay()) {
 220                         // Then get the number of rows
 221                         $numRows = $resultInstance->getAffectedRows();
 222
 223                         // Debug message
 224                         //* DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: numRows=' . $numRows);
 225                 } // END - if
 226
 227                 // Return the result
 228                 return $numRows;
 229         }
 230
 231         /**
 232          * Getter for primary key used in wrapped table
 233          *
 234          * @return      $primaryKey             Primary key used in wrapped table
 235          */
 236         public final function getPrimaryKeyValue () {
 237                 // Get the table name and a database instance and ask for it
 238                 $primaryKey = $this->getDatabaseInstance()->getPrimaryKeyOfTable($this->getTableName());
 239
 240                 // Return value
 241                 return $primaryKey;
 242         }
 243
 244         /**
 245          * Removes non-public data from given array.
 246          *
 247          * @param       $data   An array with possible non-public data that needs to be removed.
 248          * @return      $data   A cleaned up array with only public data.
 249          */
 250         public function removeNonPublicDataFromArray (array $data) {
 251                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('WRAPPER[' . $this->__toString() . ']: Calling this->getDatabaseInstance()->removeNonPublicDataFromArray(data) ...');
 252                 $data = $this->getDatabaseInstance()->removeNonPublicDataFromArray($data);
 253
 254                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('WRAPPER[' . $this->__toString() . ']: data[]=' . gettype($data));
 255                 return $data;
 256         }
 257 }
 258
 259 // [EOF]
 260 ?>