inc/main/classes/database/class_BaseDatabaseWrapper.php

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