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