1f8ad0325598aa8b173eca959c41b3acdabb8a3d
[core.git] / 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 - 2013 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                 // First get a key suitable for our cache and extend it with this class name
86                 $cacheKey = $this->getCacheKeyByCriteria($dataSetInstance, $onlyKeys);
87                 //* DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: Using cache key ' . $cacheKey . ' for purging ...');
88
89                 // Does this key exists in cache?
90                 if ($this->cacheInstance->offsetExists($cacheKey)) {
91                         // Purge the cache
92                         $this->cacheInstance->purgeOffset($cacheKey);
93                 } // END - if
94
95                 // Handle it over to the middleware
96                 $this->getDatabaseInstance()->queryInsertDataSet($dataSetInstance);
97         }
98
99         /**
100          * 'Updates' a data set instance with a database layer
101          *
102          * @param       $dataSetInstance        A storeable data set
103          * @param       $onlyKeys                       Only use these keys for a cache key
104          * @return      void
105          */
106         protected function queryUpdateDataSet (StoreableCriteria $dataSetInstance, array $onlyKeys = array()) {
107                 // First get a key suitable for our cache and extend it with this class name
108                 $cacheKey = $this->getCacheKeyByCriteria($dataSetInstance, $onlyKeys);
109                 //* DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: Using cache key ' . $cacheKey . ' for purging ...');
110
111                 // Does this key exists in cache?
112                 if ($this->cacheInstance->offsetExists($cacheKey)) {
113                         // Purge the cache
114                         $this->cacheInstance->purgeOffset($cacheKey);
115                 } // END - if
116
117                 // Handle it over to the middleware
118                 $this->getDatabaseInstance()->queryUpdateDataSet($dataSetInstance);
119         }
120
121         /**
122          * Getter for index key
123          *
124          * @return      $indexKey       Index key
125          */
126         public final function getIndexKey () {
127                 return $this->getDatabaseInstance()->getIndexKey();
128         }
129
130         /**
131          * Getter for last exception
132          *
133          * @return      $lastException  Last exception or NULL if none occured
134          */
135         public final function getLastException () {
136                 return $this->getDatabaseInstance()->getLastException();
137         }
138
139         /**
140          * Do a "select" query on the current table with the given search criteria and
141          * store it in cache for later usage
142          *
143          * @param       $criteriaInstance       An instance of a Criteria class
144          * @param       $onlyKeys                       Only use these keys for a cache key
145          * @return      $resultInstance         An instance of a database result class
146          */
147         public function doSelectByCriteria (Criteria $criteriaInstance, array $onlyKeys = array()) {
148                 // First get a key suitable for our cache and extend it with this class name
149                 $cacheKey = $this->getCacheKeyByCriteria($criteriaInstance, $onlyKeys);
150
151                 // Does this key exists in cache?
152                 if ($this->cacheInstance->offsetExists($cacheKey, BaseDatabaseBackend::RESULT_INDEX_ROWS, 1)) {
153                         // Debug message
154                         /* DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: Cache used for cacheKey=' . $cacheKey . ':' . print_r($this->cacheInstance->offsetGet($cacheKey), TRUE));
155
156                         // Then use this result
157                         $result = $this->cacheInstance->offsetGet($cacheKey);
158                 } else {
159                         // Debug message
160                         /* DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: Quering database, cacheKey=' . $cacheKey);
161
162                         // Now it's time to ask the database layer for this select statement
163                         $result = $this->getDatabaseInstance()->doSelectByTableCriteria($this->getTableName(), $criteriaInstance);
164
165                         // Cache the result if not null
166                         if (!is_null($result)) {
167                                 // A valid result has returned from the database layer
168                                 $this->cacheInstance->offsetSet($cacheKey, $result);
169                         } else {
170                                 // This invalid result must be wrapped
171                                 $result = array(
172                                         BaseDatabaseBackend::RESULT_INDEX_STATUS    => 'invalid',
173                                         BaseDatabaseBackend::RESULT_INDEX_EXCEPTION => $this->getDatabaseInstance()->getLastException()
174                                 );
175                         }
176                 }
177
178                 // Create an instance of a DatabaseResult class with the given result
179                 $resultInstance = ObjectFactory::createObjectByConfiguredName('database_result_class', array($result));
180
181                 // And return the instance
182                 return $resultInstance;
183         }
184
185         /**
186          * Count the numbers of rows we shall receive
187          *
188          * @param       $criteriaInstance       An instance of a Criteria class
189          * @param       $onlyKeys                       Only use these keys for a cache key
190          * @return      $numRows                        Numbers of rows of database entries
191          */
192         public function doSelectCountByCriteria (Criteria $criteriaInstance, $onlyKeys =  array()) {
193                 // Total numbers is -1 so we can distinglish between failed and valid queries
194                 $numRows = 0;
195
196                 // Get the result from above method
197                 $resultInstance = $this->doSelectByCriteria($criteriaInstance, $onlyKeys);
198
199                 // Was that query fine?
200                 if ($resultInstance->ifStatusIsOkay()) {
201                         // Then get the number of rows
202                         $numRows = $resultInstance->getAffectedRows();
203
204                         // Debug message
205                         //* DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('BASE-WRAPPER: numRows=' . $numRows);
206                 } // END - if
207
208                 // Return the result
209                 return $numRows;
210         }
211
212         /**
213          * Getter for primary key used in wrapped table
214          *
215          * @return      $primaryKey             Primary key used in wrapped table
216          */
217         public final function getPrimaryKeyValue () {
218                 // Get the table name and a database instance and ask for it
219                 $primaryKey = $this->getDatabaseInstance()->getPrimaryKeyOfTable($this->getTableName());
220
221                 // Return value
222                 return $primaryKey;
223         }
224 }
225
226 // [EOF]
227 ?>