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