c6ab513e9f56bf22af0559ea62c0549bce088d6b
[core.git] / inc / classes / main / database / databases / class_LocalFileDatabase.php
1 <?php
2 /**
3  * Database backend class for storing objects in locally created files.
4  *
5  * This class serializes objects and saves them to local files.
6  *
7  * @author              Roland Haeder <webmaster@ship-simu.org>
8  * @version             0.0.0
9  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2012 Core Developer Team
10  * @license             GNU GPL 3.0 or any newer version
11  * @link                http://www.ship-simu.org
12  *
13  * This program is free software: you can redistribute it and/or modify
14  * it under the terms of the GNU General Public License as published by
15  * the Free Software Foundation, either version 3 of the License, or
16  * (at your option) any later version.
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  * GNU General Public License for more details.
22  *
23  * You should have received a copy of the GNU General Public License
24  * along with this program. If not, see <http://www.gnu.org/licenses/>.
25  */
26 class LocalFileDatabase extends BaseDatabaseBackend implements DatabaseBackendInterface {
27         // Constants for MySQL backward-compatiblity (PLEASE FIX THEM!)
28         const DB_CODE_TABLE_MISSING     = 0x100;
29         const DB_CODE_TABLE_UNWRITEABLE = 0x101;
30         const DB_CODE_DATA_FILE_CORRUPT = 0x102;
31
32         // Status results
33         const RESULT_OKAY = 'ok';
34
35         /**
36          * The file's extension
37          */
38         private $fileExtension = 'serialized';
39
40         /**
41          * The last read file's name
42          */
43         private $lastFile = '';
44
45         /**
46          * The last read file's content including header information
47          */
48         private $lastContents = array();
49
50         /**
51          * Whether the "connection is already up
52          */
53         private $alreadyConnected = false;
54
55         /**
56          * Table information array
57          */
58         private $tableInfo = array();
59
60         /**
61          * Element for index
62          */
63         private $indexKey = '__idx';
64
65         /**
66          * The protected constructor. Do never instance from outside! You need to
67          * set a local file path. The class will then validate it.
68          *
69          * @return      void
70          */
71         protected function __construct () {
72                 // Call parent constructor
73                 parent::__construct(__CLASS__);
74         }
75
76         /**
77          * Create an object of LocalFileDatabase and set the save path from
78          * configuration for local files.
79          *
80          * @return      $databaseInstance       An instance of LocalFileDatabase
81          */
82         public static final function createLocalFileDatabase () {
83                 // Get an instance
84                 $databaseInstance = new LocalFileDatabase();
85
86                 // Get a new compressor channel instance
87                 $compressorInstance = ObjectFactory::createObjectByConfiguredName('compressor_channel_class');
88
89                 // Set the compressor channel
90                 $databaseInstance->setCompressorChannel($compressorInstance);
91
92                 // Get a file IO handler
93                 $fileIoInstance = ObjectFactory::createObjectByConfiguredName('file_io_class');
94
95                 // ... and set it
96                 $databaseInstance->setFileIoInstance($fileIoInstance);
97
98                 // "Connect" to the database
99                 $databaseInstance->connectToDatabase();
100
101                 // Return database instance
102                 return $databaseInstance;
103         }
104
105         /**
106          * Setter for the last read file
107          *
108          * @param       $fqfn   The FQFN of the last read file
109          * @return      void
110          */
111         private final function setLastFile ($fqfn) {
112                 // Cast string and set it
113                 $this->lastFile = (string) $fqfn;
114         }
115
116         /**
117          * Getter for last read file
118          *
119          * @return      $lastFile       The last read file's name with full path
120          */
121         public final function getLastFile () {
122                 return $this->lastFile;
123         }
124
125         /**
126          * Setter for contents of the last read file
127          *
128          * @param               $contents       An array with header and data elements
129          * @return      void
130          */
131         private final function setLastFileContents (array $contents) {
132                 // Set array
133                 $this->lastContents = $contents;
134         }
135
136         /**
137          * Getter for last read file's content as an array
138          *
139          * @return      $lastContent    The array with elements 'header' and 'data'.
140          */
141         public final function getLastContents () {
142                 return $this->lastContents;
143         }
144
145         /**
146          * Getter for file extension
147          *
148          * @return      $fileExtension  The array with elements 'header' and 'data'.
149          */
150         public final function getFileExtension () {
151                 return $this->fileExtension;
152         }
153
154         /**
155          * Getter for index key
156          *
157          * @return      $indexKey       Index key
158          */
159         public final function getIndexKey () {
160                 return $this->indexKey;
161         }
162
163         /**
164          * Reads a local data file  and returns it's contents in an array
165          *
166          * @param       $fqfn   The FQFN for the requested file
167          * @return      $dataArray
168          */
169         private function getDataArrayFromFile ($fqfn) {
170                 // Debug message
171                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DATABASE: Reading elements from database file ' . $fqfn . ' ...');
172
173                 // Init compressed data
174                 $compressedData = $this->getFileIoInstance()->loadFileContents($fqfn);
175                 $compressedData = $compressedData['data'];
176
177                 // Close the file and throw the instance away
178                 unset($fileInstance);
179
180                 // Decompress it
181                 $serializedData = $this->getCompressorChannel()->getCompressor()->decompressStream($compressedData);
182
183                 // Unserialize it
184                 $dataArray = unserialize($serializedData);
185
186                 // Debug message
187                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DATABASE: Read ' . count($dataArray) . ' elements from database file ' . $fqfn . '.');
188
189                 // Finally return it
190                 return $dataArray;
191         }
192
193         /**
194          * Writes data array to local file
195          *
196          * @param       $fqfn           The FQFN of the local file
197          * @param       $dataArray      An array with all the data we shall write
198          * @return      void
199          */
200         private function writeDataArrayToFqfn ($fqfn, array $dataArray) {
201                 // Debug message
202                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DATABASE: Flushing ' . count($dataArray) . ' elements to database file ' . $fqfn . ' ...');
203
204                 // Serialize and compress it
205                 $compressedData = $this->getCompressorChannel()->getCompressor()->compressStream(serialize($dataArray));
206
207                 // Write data
208                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DATABASE: Writing ' . strlen($compressedData) . ' bytes ...');
209
210                 // Write this data BASE64 encoded to the file
211                 $this->getFileIoInstance()->saveFile($fqfn, $compressedData);
212
213                 // Debug message
214                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DATABASE: Flushing ' . count($dataArray) . ' elements to database file completed.');
215         }
216
217         /**
218          * Getter for table information file contents or an empty if info file was not created
219          *
220          * @param       $dataSetInstance        An instance of a database set class
221          * @return      $infoArray                      An array with all table informations
222          */
223         private function getContentsFromTableInfoFile (StoreableCriteria $dataSetInstance) {
224                 // Default content is no data
225                 $infoArray = array();
226
227                 // Create FQFN for getting the table information file
228                 $fqfn = $this->generateFqfnFromDataSet($dataSetInstance, 'info');
229
230                 // Get the file contents
231                 try {
232                         $infoArray = $this->getDataArrayFromFile($fqfn);
233                 } catch (FileIoException $e) {
234                         // Not found, so ignore it here
235                 }
236
237                 // ... and return it
238                 return $infoArray;
239         }
240
241         /**
242          * Generates an FQFN from given dataset instance and string
243          *
244          * @param       $dataSetInstance        An instance of a database set class
245          * @param       $rowName                        Name of the row
246          * @return      $fqfn                           The FQFN for this row
247          */
248         private function generateFqfnFromDataSet (Criteria $dataSetInstance, $rowName) {
249                 // This is the FQFN
250                 $fqfn = $this->getConfigInstance()->getConfigEntry('local_db_path') . $dataSetInstance->getTableName() . '/' . $rowName . '.' . $this->getFileExtension();
251
252                 // Return it
253                 return $fqfn;
254         }
255
256         /**
257          * Creates the table info file from given dataset instance
258          *
259          * @param       $dataSetInstance        An instance of a database set class
260          * @return      void
261          */
262         private function createTableInfoFile (StoreableCriteria $dataSetInstance) {
263                 // Create FQFN for creating the table information file
264                 $fqfn = $this->generateFqfnFromDataSet($dataSetInstance, 'info');
265
266                 // Get the data out from dataset in a local array
267                 $this->tableInfo[$dataSetInstance->getTableName()] = array(
268                         'primary'      => $dataSetInstance->getPrimaryKey(),
269                         'created'      => time(),
270                         'last_updated' => time()
271                 );
272
273                 // Write the data to the file
274                 $this->writeDataArrayToFqfn($fqfn, $this->tableInfo[$dataSetInstance->getTableName()]);
275         }
276
277         /**
278          * Updates the primary key information or creates the table info file if not found
279          *
280          * @param       $dataSetInstance        An instance of a database set class
281          * @return      void
282          */
283         private function updatePrimaryKey (StoreableCriteria $dataSetInstance) {
284                 // Get the information array from lower method
285                 $infoArray = $this->getContentsFromTableInfoFile($dataSetInstance);
286
287                 // Is the primary key there?
288                 if (!isset($this->tableInfo['primary'])) {
289                         // Then create the info file
290                         $this->createTableInfoFile($dataSetInstance);
291                 } elseif (($this->getConfigInstance()->getConfigEntry('db_update_primary_forced') == 'Y') && ($dataSetInstance->getPrimaryKey() != $this->tableInfo['primary'])) {
292                         // Set the array element
293                         $this->tableInfo[$dataSetInstance->getTableName()]['primary'] = $dataSetInstance->getPrimaryKey();
294
295                         // Update the entry
296                         $this->updateTableInfoFile($dataSetInstance);
297                 }
298         }
299
300         /**
301          * Makes sure that the database connection is alive
302          *
303          * @return      void
304          * @todo        Do some checks on the database directory and files here
305          */
306         public function connectToDatabase () {
307         }
308
309         /**
310          * Starts a SELECT query on the database by given return type, table name
311          * and search criteria
312          *
313          * @param       $tableName              Name of the database table
314          * @param       $criteria               Local search criteria class
315          * @return      $resultData             Result data of the query
316          * @throws      UnsupportedCriteriaException    If the criteria is unsupported
317          * @throws      SqlException                                    If an 'SQL error' occurs
318          */
319         public function querySelect ($tableName, LocalSearchCriteria $criteriaInstance) {
320                 // The result is null by any errors
321                 $resultData = NULL;
322
323                 // Create full path name
324                 $pathName = $this->getConfigInstance()->getConfigEntry('local_db_path') . $tableName . '/';
325
326                 // A 'select' query is not that easy on local files, so first try to
327                 // find the 'table' which is in fact a directory on the server
328                 try {
329                         // Get a directory pointer instance
330                         $directoryInstance = FrameworkDirectoryPointer::createFrameworkDirectoryPointer($pathName);
331
332                         // Initialize the result data, this need to be rewritten e.g. if a local file cannot be read
333                         $resultData = array(
334                                 BaseDatabaseBackend::RESULT_INDEX_STATUS => LocalfileDatabase::RESULT_OKAY,
335                                 BaseDatabaseBackend::RESULT_INDEX_ROWS   => array()
336                         );
337
338                         // Initialize limit/skip
339                         $limitFound = 0;
340                         $skipFound = 0;
341                         $idx = 1;
342
343                         // Read the directory with some exceptions
344                         while (($dataFile = $directoryInstance->readDirectoryExcept(array('.', '..', '.htaccess', '.svn', 'info.' . $this->getFileExtension()))) && (($limitFound < $criteriaInstance->getLimit()) || ($criteriaInstance->getLimit() == 0))) {
345                                 // Does the extension match?
346                                 if (substr($dataFile, -(strlen($this->getFileExtension()))) !== $this->getFileExtension()) {
347                                         // Skip this file!
348                                         continue;
349                                 } // END - if
350
351                                 // Read the file
352                                 $dataArray = $this->getDataArrayFromFile($pathName . $dataFile);
353                                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DATABASE: dataFile=' . $dataFile . ',dataArray='.print_r($dataArray,true));
354
355                                 // Is this an array?
356                                 if (is_array($dataArray)) {
357                                         // Search in the criteria with FMFW (First Matches, First Wins)
358                                         foreach ($dataArray as $key => $value) {
359                                                 // Get criteria element
360                                                 $criteria = $criteriaInstance->getCriteriaElemnent($key);
361
362                                                 // Is the criteria met or none set?
363                                                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DATABASE: criteria[' . gettype($criteria) . ']=' . $criteria . ';()=' . strlen($criteria) . ',criteriaInstance()=' . $criteriaInstance->count() . ',value(' . strlen($value) . ')=' . $value);
364                                                 if (((!is_null($criteria)) && ($criteria == $value)) || ($criteriaInstance->count() == 0))  {
365                                                         // Shall we skip this entry?
366                                                         if ($criteriaInstance->getSkip() > 0) {
367                                                                 // We shall skip some entries
368                                                                 if ($skipFound < $criteriaInstance->getSkip()) {
369                                                                         // Skip this entry
370                                                                         $skipFound++;
371                                                                         break;
372                                                                 } // END - if
373                                                         } // END - if
374
375                                                         // Set id number
376                                                         $dataArray[$this->getIndexKey()] = $idx;
377
378                                                         // Entry found!
379                                                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DATABASE: indexKey=' . $this->getIndexKey() . ',idx=' . $idx . ',dataArray=' . print_r($dataArray, true));
380                                                         $resultData[BaseDatabaseBackend::RESULT_INDEX_ROWS][] = $dataArray;
381
382                                                         // Count found entries up
383                                                         $limitFound++;
384                                                         break;
385                                                 } // END - if
386                                         } // END - foreach
387                                 } else {
388                                         // Throw an exception here
389                                         throw new SqlException(array($this, sprintf("File &#39;%s&#39; contains invalid data.", $dataFile), self::DB_CODE_DATA_FILE_CORRUPT), self::EXCEPTION_SQL_QUERY);
390                                 }
391
392                                 // Count entry up
393                                 $idx++;
394                         } // END - while
395
396                         // Close directory and throw the instance away
397                         $directoryInstance->closeDirectory();
398                         unset($directoryInstance);
399
400                         // Reset last exception
401                         $this->resetLastException();
402                 } catch (PathIsNoDirectoryException $e) {
403                         // Path not found means "table not found" for real databases...
404                         $this->setLastException($e);
405
406                         // So throw an SqlException here with faked error message
407                         throw new SqlException (array($this, sprintf("Table &#39;%s&#39; not found", $tableName), self::DB_CODE_TABLE_MISSING), self::EXCEPTION_SQL_QUERY);
408                 } catch (FrameworkException $e) {
409                         // Catch all exceptions and store them in last error
410                         $this->setLastException($e);
411                 }
412
413                 // Return the gathered result
414                 return $resultData;
415         }
416
417         /**
418          * "Inserts" a data set instance into a local file database folder
419          *
420          * @param       $dataSetInstance        A storeable data set
421          * @return      void
422          * @throws      SqlException    If an SQL error occurs
423          */
424         public function queryInsertDataSet (StoreableCriteria $dataSetInstance) {
425                 // Create full path name
426                 $fqfn = $this->generateFqfnFromDataSet($dataSetInstance, md5($dataSetInstance->getUniqueValue()));
427
428                 // Try to save the request away
429                 try {
430                         // Write the data away
431                         $this->writeDataArrayToFqfn($fqfn, $dataSetInstance->getCriteriaArray());
432
433                         // Update the primary key
434                         $this->updatePrimaryKey($dataSetInstance);
435
436                         // Reset last exception
437                         $this->resetLastException();
438                 } catch (FrameworkException $e) {
439                         // Catch all exceptions and store them in last error
440                         $this->setLastException($e);
441
442                         // Throw an SQL exception
443                         throw new SqlException(array($this, sprintf("Cannot write data to table &#39;%s&#39;, is the table created?", $dataSetInstance->getTableName()), self::DB_CODE_TABLE_UNWRITEABLE), self::EXCEPTION_SQL_QUERY);
444                 }
445         }
446
447         /**
448          * "Updates" a data set instance with a database layer
449          *
450          * @param       $dataSetInstance        A storeable data set
451          * @return      void
452          * @throws      SqlException    If an SQL error occurs
453          */
454         public function queryUpdateDataSet (StoreableCriteria $dataSetInstance) {
455                 // Create full path name
456                 $pathName = $this->getConfigInstance()->getConfigEntry('local_db_path') . $dataSetInstance->getTableName() . '/';
457
458                 // Try all the requests
459                 try {
460                         // Get a file pointer instance
461                         $directoryInstance = FrameworkDirectoryPointer::createFrameworkDirectoryPointer($pathName);
462
463                         // Initialize limit/skip
464                         $limitFound = 0;
465                         $skipFound = 0;
466
467                         // Get the criteria array from the dataset
468                         $criteriaArray = $dataSetInstance->getCriteriaArray();
469
470                         // Get search criteria
471                         $searchInstance = $dataSetInstance->getSearchInstance();
472
473                         // Read the directory with some exceptions
474                         while (($dataFile = $directoryInstance->readDirectoryExcept(array('.', '..', '.htaccess', '.svn', 'info.' . $this->getFileExtension()))) && ($limitFound < $searchInstance->getLimit())) {
475                                 // Does the extension match?
476                                 if (substr($dataFile, -(strlen($this->getFileExtension()))) !== $this->getFileExtension()) {
477                                         // Debug message
478                                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DATABASE: dataFile=' . $dataFile . ',getFileExtension()=' . $this->getFileExtension() . ' - SKIPPED!');
479                                         // Skip this file!
480                                         continue;
481                                 } // END - if
482
483                                 // Open this file for reading
484                                 $dataArray = $this->getDataArrayFromFile($pathName . $dataFile);
485                                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DATABASE: dataFile=' . $dataFile . ',dataArray='.print_r($dataArray,true));
486
487                                 // Is this an array?
488                                 if (is_array($dataArray)) {
489                                         // Search in the criteria with FMFW (First Matches, First Wins)
490                                         foreach ($dataArray as $key => $value) {
491                                                 // Get criteria element
492                                                 $criteria = $searchInstance->getCriteriaElemnent($key);
493                                                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DATABASE: dataFile=' . $dataFile . ',key=' . $key . ',criteria=' . $criteria);
494
495                                                 // Is the criteria met?
496                                                 if (((!is_null($criteria)) && ($criteria == $value)) || ($searchInstance->count() == 0))  {
497                                                         // Shall we skip this entry?
498                                                         if ($searchInstance->getSkip() > 0) {
499                                                                 // We shall skip some entries
500                                                                 if ($skipFound < $searchInstance->getSkip()) {
501                                                                         // Skip this entry
502                                                                         $skipFound++;
503                                                                         break;
504                                                                 } // END - if
505                                                         } // END - if
506
507                                                         // Entry found, so update it
508                                                         foreach ($criteriaArray as $criteriaKey => $criteriaValue) {
509                                                                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__)->debugOutput('DATABASE: criteriaKey=' . $criteriaKey . ',criteriaValue=' . $criteriaValue);
510                                                                 $dataArray[$criteriaKey] = $criteriaValue;
511                                                         } // END - foreach
512
513                                                         // Write the data to a local file
514                                                         $this->writeDataArrayToFqfn($pathName . $dataFile, $dataArray);
515
516                                                         // Count it
517                                                         $limitFound++;
518                                                         break;
519                                                 } // END - if
520                                         } // END - foreach
521                                 } // END - if
522                         } // END - while
523
524                         // Close the file pointer
525                         $directoryInstance->closeDirectory();
526
527                         // Update the primary key
528                         $this->updatePrimaryKey($dataSetInstance);
529
530                         // Reset last exception
531                         $this->resetLastException();
532                 } catch (FrameworkException $e) {
533                         // Catch all exceptions and store them in last error
534                         $this->setLastException($e);
535
536                         // Throw an SQL exception
537                         throw new SqlException(array($this, sprintf("Cannot write data to table &#39;%s&#39;, is the table created?", $dataSetInstance->getTableName()), self::DB_CODE_TABLE_UNWRITEABLE), self::EXCEPTION_SQL_QUERY);
538                 }
539         }
540
541         /**
542          * Getter for primary key of specified table or if not found null will be
543          * returned. This must be database-specific.
544          *
545          * @param       $tableName              Name of the table we need the primary key from
546          * @return      $primaryKey             Primary key column of the given table
547          */
548         public function getPrimaryKeyOfTable ($tableName) {
549                 // Default key is null
550                 $primaryKey = NULL;
551
552                 // Does the table information exist?
553                 if (isset($this->tableInfo[$tableName])) {
554                         // Then return the primary key
555                         $primaryKey = $this->tableInfo[$tableName]['primary'];
556                 } // END - if
557
558                 // Return the column
559                 return $primaryKey;
560         }
561 }
562
563 // [EOF]
564 ?>