framework/main/classes/index/class_BaseIndex.php

   1 <?php
   2 // Own namespace
   3 namespace Org\Mxchange\CoreFramework\Index;
   4
   5 // Import framework stuff
   6 use Org\Mxchange\CoreFramework\Factory\Object\ObjectFactory;
   7 use Org\Mxchange\CoreFramework\Filesystem\File\BaseBinaryFile;
   8 use Org\Mxchange\CoreFramework\Generic\UnsupportedOperationException;
   9 use Org\Mxchange\CoreFramework\Iterator\Filesystem\SeekableWritableFileIterator;
  10 use Org\Mxchange\CoreFramework\Object\BaseFrameworkSystem;
  11 use Org\Mxchange\CoreFramework\Utils\String\StringUtils;
  12 use Org\Mxchange\CoreFramework\Traits\Iterator\IteratorTrait;
  13
  14 // Import SPL stuff
  15 use \SplFileInfo;
  16 use \UnexpectedValueException;
  17
  18 /**
  19  * A general index class
  20  *
  21  * @author              Roland Haeder <webmaster@ship-simu.org>
  22  * @version             0.0.0
  23  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2020 Core Developer Team
  24  * @license             GNU GPL 3.0 or any newer version
  25  * @link                http://www.ship-simu.org
  26  *
  27  * This program is free software: you can redistribute it and/or modify
  28  * it under the terms of the GNU General Public License as published by
  29  * the Free Software Foundation, either version 3 of the License, or
  30  * (at your option) any later version.
  31  *
  32  * This program is distributed in the hope that it will be useful,
  33  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  34  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  35  * GNU General Public License for more details.
  36  *
  37  * You should have received a copy of the GNU General Public License
  38  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  39  */
  40 abstract class BaseIndex extends BaseFrameworkSystem implements Indexable {
  41         // Load traits
  42         use IteratorTrait;
  43
  44         /**
  45          * Minimum block length
  46          */
  47         private static $minimumBlockLength = 0;
  48
  49         /**
  50          * Protected constructor
  51          *
  52          * @param       $className      Name of the class
  53          * @return      void
  54          */
  55         protected function __construct (string $className) {
  56                 // Call parent constructor
  57                 parent::__construct($className);
  58         }
  59
  60         /**
  61          * Reads the file header
  62          *
  63          * @return      void
  64          * @throws      UnexpectedValueException        If header length or count of elements is invalid
  65          */
  66         public function readFileHeader () {
  67                 // First rewind to beginning as the header sits at the beginning ...
  68                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-INDEX: CALLED!');
  69                 $this->getIteratorInstance()->rewind();
  70
  71                 // Then read it (see constructor for calculation)
  72                 $data = $this->getIteratorInstance()->read($this->getIteratorInstance()->getHeaderSize());
  73
  74                 // Have all requested bytes been read?
  75                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-INDEX: Read %d bytes (%d wanted).', strlen($data), $this->getIteratorInstance()->getHeaderSize()));
  76                 if (strlen($data) != $this->getIteratorInstance()->getHeaderSize()) {
  77                         // Invalid header length
  78                         throw new UnexpectedValueException(sprintf('data(%d)=%s is not expected length %d',
  79                                 strlen($data),
  80                                 $data,
  81                                 $this->getIteratorInstance()->getHeaderSize()
  82                         ));
  83                 } elseif (empty(trim($data, chr(0)))) {
  84                         // Empty file header
  85                         /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-INDEX: File header is empty - EXIT!');
  86                         return;
  87                 } elseif (substr($data, -1, 1) != chr(BaseBinaryFile::SEPARATOR_HEADER_ENTRIES)) {
  88                         // Bad last character
  89                         throw new UnexpectedValueException(sprintf('data=%s does not end with "%s"',
  90                                 $data,
  91                                 chr(BaseBinaryFile::SEPARATOR_HEADER_ENTRIES)
  92                         ));
  93                 }
  94
  95                 // Okay, then remove it
  96                 $data = substr($data, 0, -1);
  97
  98                 // And update seek position
  99                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-INDEX: Calling this->iteratorInstance->updateSeekPosition() ...');
 100                 $this->getIteratorInstance()->updateSeekPosition();
 101
 102                 /*
 103                  * Now split it:
 104                  *
 105                  * 0 => magic
 106                  * 1 => total entries
 107                  */
 108                 $header = explode(chr(BaseBinaryFile::SEPARATOR_HEADER_DATA), $data);
 109
 110                 // Check if the array has only 3 elements
 111                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-INDEX: header()=%d', count($header)));
 112                 //* PRINTR-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-INDEX: header(%d)=%s', count($header), print_r($header, true)));
 113                 if (count($header) != 2) {
 114                         // Bad header
 115                         throw new UnexpectedValueException(sprintf('header()=%d is not expected value 2', count($header)));
 116                 } elseif ($header[0] !== Indexable::INDEX_MAGIC) {
 117                         // Magic must be in first element
 118                         throw new UnexpectedValueException(sprintf('header[0]=%s is not the expected magic (%s)', $header[0], Indexable::INDEX_MAGIC));
 119                 } elseif (strlen($header[1]) != BaseBinaryFile::LENGTH_COUNT) {
 120                         // Length of total entries not matching
 121                         throw new UnexpectedValueException(sprintf('header[1](%d)=%s does not have expected length %d', strlen($header[1]), $header[1], BaseBinaryFile::LENGTH_COUNT));
 122                 }
 123
 124                 // Decode count
 125                 $header[1] = hex2bin($header[1]);
 126
 127                 // Set it here
 128                 $this->getIteratorInstance()->setHeader($header);
 129
 130                 // Trace message
 131                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-INDEX: EXIT!');
 132         }
 133
 134         /**
 135          * Flushes the file header
 136          *
 137          * @return      void
 138          */
 139         public function flushFileHeader () {
 140                 // Put all informations together
 141                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-INDEX: CALLED!');
 142                 $header = sprintf('%s%s%s%s',
 143                         // Magic
 144                         Indexable::INDEX_MAGIC,
 145
 146                         // Separator header data
 147                         chr(BaseBinaryFile::SEPARATOR_HEADER_DATA),
 148
 149                         // Total entries
 150                         str_pad(StringUtils::dec2hex($this->getIteratorInstance()->getCounter()), BaseBinaryFile::LENGTH_COUNT, '0', STR_PAD_LEFT),
 151
 152                         // Separator header<->entries
 153                         chr(BaseBinaryFile::SEPARATOR_HEADER_ENTRIES)
 154                 );
 155
 156                 // Write it to disk (header is always at seek position 0)
 157                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-INDEX: Calling this->iteratorInstance->writeAtPosition(0, header=%s) ...', $header));
 158                 $this->getIteratorInstance()->writeAtPosition(0, $header);
 159
 160                 // Trace message
 161                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-INDEX: EXIT!');
 162         }
 163
 164         /**
 165          * Initializes this index
 166          *
 167          * @param       $fileInfoInstance       An instance of a SplFileInfo class
 168          * @return      void
 169          * @todo        Currently the index file is not cached, please implement a memory-handling class and if enough RAM is found, cache the whole index file.
 170          */
 171         protected function initIndex (SplFileInfo $fileInfoInstance) {
 172                 // Get a file i/o pointer instance for index file
 173                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-INDEX: fileInfoInstance[%s]=%s - CALLED!', get_class($fileInfoInstance), $fileInfoInstance));
 174                 $fileInstance = ObjectFactory::createObjectByConfiguredName('index_file_class', array($fileInfoInstance, $this));
 175
 176                 // Get iterator instance
 177                 $iteratorInstance = ObjectFactory::createObjectByConfiguredName('file_iterator_class', [$fileInstance]);
 178
 179                 // Set iterator here
 180                 $this->setIteratorInstance($iteratorInstance);
 181
 182                 // Calculate header size
 183                 $headerSize = (
 184                         strlen(Indexable::INDEX_MAGIC) +
 185                         strlen(chr(BaseBinaryFile::SEPARATOR_HEADER_DATA)) +
 186                         BaseBinaryFile::LENGTH_COUNT +
 187                         strlen(chr(BaseBinaryFile::SEPARATOR_HEADER_ENTRIES))
 188                 );
 189
 190                 // Set it
 191                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-INDEX: Setting headerSize=%d ...', $headerSize));
 192                 $this->getIteratorInstance()->setHeaderSize($headerSize);
 193
 194                 // Init counters and gaps array
 195                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-INDEX: Calling this->iteratorInstance->initCountersGapsArray() ...');
 196                 $this->getIteratorInstance()->initCountersGapsArray();
 197
 198                 // Default is not created
 199                 $created = false;
 200
 201                 // Is the file's header initialized?
 202                 if (!$this->getIteratorInstance()->isFileHeaderInitialized()) {
 203                         // First pre-allocate a bit
 204                         /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-INDEX: Calling this->iteratorInstance->preAllocateFile(index) ...');
 205                         $this->getIteratorInstance()->preAllocateFile('index');
 206
 207                         // Then write file header
 208                         /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-INDEX: Calling this->iteratorInstance->createFileHeader() ...');
 209                         $this->getIteratorInstance()->createFileHeader();
 210
 211                         // Mark as freshly created
 212                         $created = true;
 213                 }
 214
 215                 // Load the file header
 216                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-INDEX: Calling this->readFileHeader() ...');
 217                 $this->readFileHeader();
 218
 219                 // Freshly created?
 220                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-INDEX: created=%d', intval($created)));
 221                 if (!$created) {
 222                         // Analyze file structure
 223                         /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-INDEX: Calling this->iteratorInstance->analyzeFileStructure() ...');
 224                         $this->getIteratorInstance()->analyzeFileStructure();
 225                 }
 226
 227                 // Trace message
 228                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-INDEX: EXIT!');
 229         }
 230
 231         /**
 232          * Calculates minimum length for one entry/block
 233          *
 234          * @return      $length         Minimum length for one entry/block
 235          */
 236         public function calculateMinimumBlockLength () {
 237                 // Is it "cached"?
 238                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-INDEX: CALLED!');
 239                 if (self::$minimumBlockLength == 0) {
 240                         // Calulcate it
 241                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('BASE-INDEX: Calculating ...');
 242                         self::$minimumBlockLength = (
 243                                 // Type
 244                                 BaseBinaryFile::LENGTH_TYPE + strlen(chr(BaseBinaryFile::SEPARATOR_TYPE_POSITION)) +
 245                                 // Position
 246                                 BaseBinaryFile::LENGTH_POSITION + strlen(chr(BaseBinaryFile::SEPARATOR_ENTRIES))
 247                         );
 248                 }
 249
 250                 // Return it
 251                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('BASE-INDEX: self::minimumBlockLength=%d - EXIT!', self::$minimumBlockLength));
 252                 return self::$minimumBlockLength;
 253         }
 254
 255         /**
 256          * Determines whether the EOF has been reached
 257          *
 258          * @return      $isEndOfFileReached             Whether the EOF has been reached
 259          * @throws      UnsupportedOperationException   If this method is called
 260          */
 261         public function isEndOfFileReached () {
 262                 throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION);
 263         }
 264
 265         /**
 266          * Initializes counter for valid entries, arrays for damaged entries and
 267          * an array for gap seek positions. If you call this method on your own,
 268          * please re-analyze the file structure. So you are better to call
 269          * analyzeFileStructure() instead of this method.
 270          *
 271          * @return      void
 272          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 273          */
 274         public function initCountersGapsArray () {
 275                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 276         }
 277
 278         /**
 279          * Getter for header size
 280          *
 281          * @return      $totalEntries   Size of file header
 282          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 283          */
 284         public final function getHeaderSize () {
 285                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 286         }
 287
 288         /**
 289          * Setter for header size
 290          *
 291          * @param       $headerSize             Size of file header
 292          * @return      void
 293          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 294          */
 295         public final function setHeaderSize (int $headerSize) {
 296                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 297         }
 298
 299         /**
 300          * Getter for header array
 301          *
 302          * @return      $totalEntries   Size of file header
 303          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 304          */
 305         public final function getHeader () {
 306                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 307         }
 308
 309         /**
 310          * Setter for header
 311          *
 312          * @param       $header         Array for a file header
 313          * @return      void
 314          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 315          */
 316         public final function setHeader (array $header) {
 317                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 318         }
 319
 320         /**
 321          * Updates seekPosition attribute from file to avoid to much access on file.
 322          *
 323          * @return      void
 324          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 325          */
 326         public function updateSeekPosition () {
 327                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 328         }
 329
 330         /**
 331          * Getter for total entries
 332          *
 333          * @return      $totalEntries   Total entries in this file
 334          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 335          */
 336         public final function getCounter () {
 337                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 338         }
 339
 340         /**
 341          * "Getter" for file size
 342          *
 343          * @return      $fileSize       Size of currently loaded file
 344          */
 345         public function getFileSize () {
 346                 // Call iterator's method
 347                 return $this->getIteratorInstance()->getFileSize();
 348         }
 349
 350         /**
 351          * Writes data at given position
 352          *
 353          * @param       $seekPosition   Seek position
 354          * @param       $data                   Data to be written
 355          * @param       $flushHeader    Whether to flush the header (default: flush)
 356          * @return      void
 357          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 358          */
 359         public function writeData (int $seekPosition, string $data, bool $flushHeader = true) {
 360                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('seekPosition=%s,data[]=%s,flushHeader=%d - CALLED!', $seekPosition, gettype($data), intval($flushHeader)));
 361                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 362         }
 363
 364         /**
 365          * Writes given value to the file and returns a hash and gap position for it
 366          *
 367          * @param       $groupId        Group identifier
 368          * @param       $value          Value to be added to the stack
 369          * @return      $data           Hash and gap position
 370          * @throws      UnsupportedOperationException   If this method is called
 371          */
 372         public function writeValueToFile (string $groupId, $value) {
 373                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('groupId=%s,value[%s]=%s - CALLED!', $groupId, gettype($value), print_r($value, true)));
 374                 throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION);
 375         }
 376
 377         /**
 378          * Writes given raw data to the file and returns a gap position and length
 379          *
 380          * @param       $groupId        Group identifier
 381          * @param       $hash           Hash from encoded value
 382          * @param       $encoded        Encoded value to be written to the file
 383          * @return      $data           Gap position and length of the raw data
 384          */
 385         public function writeDataToFreeGap (string $groupId, string $hash, string $encoded) {
 386                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('groupId=%s,hash=%s,encoded()=%d - CALLED!', $groupId, $hash, strlen($encoded)));
 387                 throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION);
 388         }
 389
 390 }