inc/main/classes/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 - 2017 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                 // Is the cache enabled?
  55                 if ($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) {
  56                         // Set the new instance
  57                         $this->cacheInstance = CacheFactory::getFactory()->createConfiguredCache();
  58                 } // END - if
  59         }
  60
  61         /**
  62          * Setter for table name
  63          *
  64          * @param       $tableName      Name of table name to set
  65          * @return      void
  66          */
  67         protected final function setTableName ($tableName) {
  68                 $this->tableName = (string) $tableName;
  69         }
  70
  71         /**
  72          * Getter for table name
  73          *
  74          * @return      $tableName      Name of table name to set
  75          */
  76         protected final function getTableName () {
  77                 return $this->tableName;
  78         }
  79
  80         /**
  81          * 'Inserts' a data set instance into a local file database folder
  82          *
  83          * @param       $dataSetInstance        A storeable data set
  84          * @param       $onlyKeys                       Only use these keys for a cache key
  85          * @return      void
  86          */
  87         protected function queryInsertDataSet (StoreableCriteria $dataSetInstance, array $onlyKeys = array()) {
  88                 // Default cache key is NULL
  89                 $cacheKey = NULL;
  90
  91                 // Is cache enabled?
  92                 if ($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) {
  93                         // First get a key suitable for our cache and extend it with this class name
  94                         $cacheKey = $this->getCacheKeyByCriteria($dataSetInstance, $onlyKeys);
  95                         //* DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: Using cache key ' . $cacheKey . ' for purging ...');
  96                 } // END - if
  97
  98                 // Does this key exists in cache?
  99                 if (($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) && ($this->cacheInstance->offsetExists($cacheKey))) {
 100                         // Purge the cache
 101                         $this->cacheInstance->purgeOffset($cacheKey);
 102                 } // END - if
 103
 104                 // Handle it over to the middleware
 105                 $this->getDatabaseInstance()->queryInsertDataSet($dataSetInstance);
 106         }
 107
 108         /**
 109          * 'Updates' a data set instance with a database layer
 110          *
 111          * @param       $dataSetInstance        A storeable data set
 112          * @param       $onlyKeys                       Only use these keys for a cache key
 113          * @return      void
 114          */
 115         protected function queryUpdateDataSet (StoreableCriteria $dataSetInstance, array $onlyKeys = array()) {
 116                 // Init cache key
 117                 $cacheKey = NULL;
 118
 119                 // Is cache enabled?
 120                 if ($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) {
 121                         // First get a key suitable for our cache and extend it with this class name
 122                         $cacheKey = $this->getCacheKeyByCriteria($dataSetInstance, $onlyKeys);
 123                         //* DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: Using cache key ' . $cacheKey . ' for purging ...');
 124                 } // END - if
 125
 126                 // Does this key exists in cache?
 127                 if (($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) && ($this->cacheInstance->offsetExists($cacheKey))) {
 128                         // Purge the cache
 129                         $this->cacheInstance->purgeOffset($cacheKey);
 130                 } // END - if
 131
 132                 // Handle it over to the middleware
 133                 $this->getDatabaseInstance()->queryUpdateDataSet($dataSetInstance);
 134         }
 135
 136         /**
 137          * Getter for index key
 138          *
 139          * @return      $indexKey       Index key
 140          */
 141         public final function getIndexKey () {
 142                 return $this->getDatabaseInstance()->getIndexKey();
 143         }
 144
 145         /**
 146          * Getter for last exception
 147          *
 148          * @return      $lastException  Last exception or NULL if none occured
 149          */
 150         public final function getLastException () {
 151                 return $this->getDatabaseInstance()->getLastException();
 152         }
 153
 154         /**
 155          * Do a "select" query on the current table with the given search criteria and
 156          * store it in cache for later usage
 157          *
 158          * @param       $criteriaInstance       An instance of a Criteria class
 159          * @param       $onlyKeys                       Only use these keys for a cache key
 160          * @return      $resultInstance         An instance of a database result class
 161          */
 162         public function doSelectByCriteria (Criteria $criteriaInstance, array $onlyKeys = array()) {
 163                 // Default cache key if cache is not enabled
 164                 $cacheKey = NULL;
 165
 166                 // Is the cache enabled?
 167                 if ($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) {
 168                         // First get a key suitable for our cache and extend it with this class name
 169                         $cacheKey = $this->getCacheKeyByCriteria($criteriaInstance, $onlyKeys);
 170                 } // END - if
 171
 172                 // Does this key exists in cache?
 173                 if (($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) && ($this->cacheInstance->offsetExists($cacheKey, BaseDatabaseBackend::RESULT_INDEX_ROWS, 1))) {
 174                         // Debug message
 175                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: Cache used for cacheKey=' . $cacheKey . ':' . print_r($this->cacheInstance->offsetGet($cacheKey), TRUE));
 176
 177                         // Then use this result
 178                         $result = $this->cacheInstance->offsetGet($cacheKey);
 179                 } else {
 180                         // Debug message
 181                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: Quering database, cacheKey=' . $cacheKey);
 182
 183                         // Now it's time to ask the database layer for this select statement
 184                         $result = $this->getDatabaseInstance()->doSelectByTableCriteria($this->getTableName(), $criteriaInstance);
 185                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: result[]=' . gettype($result));
 186
 187                         // Cache the result if not null
 188                         if (!is_null($result)) {
 189                                 // Is cache enabled?
 190                                 if ($this->getConfigInstance()->getConfigEntry('database_cache_enabled') === TRUE) {
 191                                         // A valid result has returned from the database layer
 192                                         $this->cacheInstance->offsetSet($cacheKey, $result);
 193                                 } // END - if
 194                         } else {
 195                                 // This invalid result must be wrapped
 196                                 $result = array(
 197                                         BaseDatabaseBackend::RESULT_INDEX_STATUS    => 'invalid',
 198                                         BaseDatabaseBackend::RESULT_INDEX_EXCEPTION => $this->getDatabaseInstance()->getLastException()
 199                                 );
 200                         }
 201                 }
 202
 203                 // Create an instance of a CachedDatabaseResult class with the given result
 204                 // @TODO Minor: Update above comment to e.g. BaseDatabaseResult
 205                 $resultInstance = ObjectFactory::createObjectByConfiguredName('database_result_class', array($result));
 206
 207                 // And return the instance
 208                 return $resultInstance;
 209         }
 210
 211         /**
 212          * Count the numbers of rows we shall receive
 213          *
 214          * @param       $criteriaInstance       An instance of a Criteria class
 215          * @param       $onlyKeys                       Only use these keys for a cache key
 216          * @return      $numRows                        Numbers of rows of database entries
 217          */
 218         public function doSelectCountByCriteria (Criteria $criteriaInstance, $onlyKeys = array()) {
 219                 // Total numbers is -1 so we can distinglish between failed and valid queries
 220                 $numRows = 0;
 221
 222                 // Get the result from above method
 223                 $resultInstance = $this->doSelectByCriteria($criteriaInstance, $onlyKeys);
 224
 225                 // Was that query fine?
 226                 if ($resultInstance->ifStatusIsOkay()) {
 227                         // Then get the number of rows
 228                         $numRows = $resultInstance->getAffectedRows();
 229
 230                         // Debug message
 231                         //* DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: numRows=' . $numRows);
 232                 } // END - if
 233
 234                 // Return the result
 235                 return $numRows;
 236         }
 237
 238         /**
 239          * Getter for primary key used in wrapped table
 240          *
 241          * @return      $primaryKey             Primary key used in wrapped table
 242          */
 243         public final function getPrimaryKeyValue () {
 244                 // Get the table name and a database instance and ask for it
 245                 $primaryKey = $this->getDatabaseInstance()->getPrimaryKeyOfTable($this->getTableName());
 246
 247                 // Return value
 248                 return $primaryKey;
 249         }
 250
 251         /**
 252          * Count rows of this table
 253          *
 254          * @return      $count  Count of total rows in this table
 255          */
 256         public final function countTotalRows () {
 257                 // Get the table name and a database instance and ask for it
 258                 $count = $this->getDatabaseInstance()->countTotalRows($this->getTableName());
 259
 260                 // Return value
 261                 return $count;
 262         }
 263
 264         /**
 265          * Removes non-public data from given array.
 266          *
 267          * @param       $data   An array with possible non-public data that needs to be removed.
 268          * @return      $data   A cleaned up array with only public data.
 269          */
 270         public function removeNonPublicDataFromArray (array $data) {
 271                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('WRAPPER[' . $this->__toString() . ']: Calling this->getDatabaseInstance()->removeNonPublicDataFromArray(data) ...');
 272                 $data = $this->getDatabaseInstance()->removeNonPublicDataFromArray($data);
 273
 274                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('WRAPPER[' . $this->__toString() . ']: data[]=' . gettype($data));
 275                 return $data;
 276         }
 277 }
 278
 279 // [EOF]
 280 ?>