framework/main/classes/stacker/file/class_BaseFileStack.php

   1 <?php
   2 // Own namespace
   3 namespace Org\Mxchange\CoreFramework\Stacker\Filesystem;
   4
   5 // Import framework stuff
   6 use Org\Mxchange\CoreFramework\Factory\Filesystem\Stack\FileStackIndexFactory;
   7 use Org\Mxchange\CoreFramework\Factory\ObjectFactory;
   8 use Org\Mxchange\CoreFramework\Filesystem\File\BaseBinaryFile;
   9 use Org\Mxchange\CoreFramework\Generic\UnsupportedOperationException;
  10 use Org\Mxchange\CoreFramework\Iterator\Filesystem\SeekableWritableFileIterator;
  11 use Org\Mxchange\CoreFramework\Stacker\BaseStacker;
  12
  13 // Import SPL stuff
  14 use \SplFileInfo;
  15
  16 /**
  17  * A general file-based stack class
  18  *
  19  * @author              Roland Haeder <webmaster@ship-simu.org>
  20  * @version             0.0.0
  21  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2017 Core Developer Team
  22  * @license             GNU GPL 3.0 or any newer version
  23  * @link                http://www.ship-simu.org
  24  *
  25  * This program is free software: you can redistribute it and/or modify
  26  * it under the terms of the GNU General Public License as published by
  27  * the Free Software Foundation, either version 3 of the License, or
  28  * (at your option) any later version.
  29  *
  30  * This program is distributed in the hope that it will be useful,
  31  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  32  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  33  * GNU General Public License for more details.
  34  *
  35  * You should have received a copy of the GNU General Public License
  36  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  37  */
  38 abstract class BaseFileStack extends BaseStacker {
  39         /**
  40          * Magic for this stack
  41          */
  42         const STACK_MAGIC = 'STACKv0.1';
  43
  44         /**
  45          * Name of array index for gap position
  46          */
  47         const ARRAY_INDEX_GAP_POSITION = 'gap';
  48
  49         /**
  50          * Name of array index for hash
  51          */
  52         const ARRAY_INDEX_HASH = 'hash';
  53
  54         /**
  55          * Name of array index for length of raw data
  56          */
  57         const ARRAY_INDEX_DATA_LENGTH = 'length';
  58
  59         /**
  60          * Protected constructor
  61          *
  62          * @param       $className      Name of the class
  63          * @return      void
  64          */
  65         protected function __construct ($className) {
  66                 // Call parent constructor
  67                 parent::__construct($className);
  68         }
  69
  70         /**
  71          * Reads the file header
  72          *
  73          * @return      void
  74          * @todo        To hard assertions here, better rewrite them to exceptions
  75          */
  76         public function readFileHeader () {
  77                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] CALLED!', __METHOD__, __LINE__));
  78
  79                 // First rewind to beginning as the header sits at the beginning ...
  80                 $this->getIteratorInstance()->rewind();
  81
  82                 // Then read it (see constructor for calculation)
  83                 $data = $this->getIteratorInstance()->read($this->getIteratorInstance()->getHeaderSize());
  84                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] Read %d bytes (%d wanted).', __METHOD__, __LINE__, strlen($data), $this->getIteratorInstance()->getHeaderSize()));
  85
  86                 // Have all requested bytes been read?
  87                 assert(strlen($data) == $this->getIteratorInstance()->getHeaderSize());
  88                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] Passed assert().', __METHOD__, __LINE__));
  89
  90                 // Last character must be the separator
  91                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] data(-1)=%s', __METHOD__, __LINE__, dechex(ord(substr($data, -1, 1)))));
  92                 assert(substr($data, -1, 1) == chr(BaseBinaryFile::SEPARATOR_HEADER_ENTRIES));
  93                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] Passed assert().', __METHOD__, __LINE__));
  94
  95                 // Okay, then remove it
  96                 $data = substr($data, 0, -1);
  97
  98                 // And update seek position
  99                 $this->getIteratorInstance()->updateSeekPosition();
 100
 101                 /*
 102                  * Now split it:
 103                  *
 104                  * 0 => magic
 105                  * 1 => total entries
 106                  * 2 => current seek position
 107                  */
 108                 $header = explode(chr(BaseBinaryFile::SEPARATOR_HEADER_DATA), $data);
 109
 110                 // Set header here
 111                 $this->getIteratorInstance()->setHeader($header);
 112
 113                 // Check if the array has only 3 elements
 114                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] header(%d)=%s', __METHOD__, __LINE__, count($header), print_r($header, true)));
 115                 assert(count($header) == 3);
 116                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] Passed assert().', __METHOD__, __LINE__));
 117
 118                 // Check magic
 119                 assert($header[0] == self::STACK_MAGIC);
 120                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] Passed assert().', __METHOD__, __LINE__));
 121
 122                 // Check length of count and seek position
 123                 assert(strlen($header[1]) == BaseBinaryFile::LENGTH_COUNT);
 124                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] Passed assert().', __METHOD__, __LINE__));
 125                 assert(strlen($header[2]) == BaseBinaryFile::LENGTH_POSITION);
 126                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] Passed assert().', __METHOD__, __LINE__));
 127
 128                 // Decode count and seek position
 129                 $header[1] = hex2bin($header[1]);
 130                 $header[2] = hex2bin($header[2]);
 131
 132                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] EXIT!', __METHOD__, __LINE__));
 133         }
 134
 135         /**
 136          * Flushes the file header
 137          *
 138          * @return      void
 139          */
 140         public function flushFileHeader () {
 141                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] CALLED!', __METHOD__, __LINE__));
 142
 143                 // Put all informations together
 144                 $header = sprintf('%s%s%s%s%s%s',
 145                         // Magic
 146                         self::STACK_MAGIC,
 147
 148                         // Separator magic<->count
 149                         chr(BaseBinaryFile::SEPARATOR_HEADER_DATA),
 150
 151                         // Total entries (will be zero) and pad it to 20 chars
 152                         str_pad($this->dec2hex($this->getIteratorInstance()->getCounter()), BaseBinaryFile::LENGTH_COUNT, '0', STR_PAD_LEFT),
 153
 154                         // Separator count<->seek position
 155                         chr(BaseBinaryFile::SEPARATOR_HEADER_DATA),
 156
 157                         // Position (will be zero)
 158                         str_pad($this->dec2hex($this->getIteratorInstance()->getSeekPosition(), 2), BaseBinaryFile::LENGTH_POSITION, '0', STR_PAD_LEFT),
 159
 160                         // Separator position<->entries
 161                         chr(BaseBinaryFile::SEPARATOR_HEADER_ENTRIES)
 162                 );
 163
 164                 // Write it to disk (header is always at seek position 0)
 165                 $this->getIteratorInstance()->writeData(0, $header, false);
 166
 167                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] EXIT!', __METHOD__, __LINE__));
 168         }
 169
 170         /**
 171          * Initializes this file-based stack.
 172          *
 173          * @param       $fileInfoInstance       An instance of a SplFileInfo class
 174          * @param       $type           Type of this stack (e.g. url_source for URL sources)
 175          * @return      void
 176          * @todo        Currently the stack file is not cached, please implement a memory-handling class and if enough RAM is found, cache the whole stack file.
 177          */
 178         protected function initFileStack (SplFileInfo $fileInfoInstance, $type) {
 179                 // Get a stack file instance
 180                 $fileInstance = ObjectFactory::createObjectByConfiguredName('stack_file_class', array($fileInfoInstance, $this));
 181
 182                 // Get iterator instance
 183                 $iteratorInstance = ObjectFactory::createObjectByConfiguredName('file_iterator_class', array($fileInstance));
 184
 185                 // Is the instance implementing the right interface?
 186                 assert($iteratorInstance instanceof SeekableWritableFileIterator);
 187
 188                 // Set iterator here
 189                 $this->setIteratorInstance($iteratorInstance);
 190
 191                 // Calculate header size
 192                 $this->getIteratorInstance()->setHeaderSize(
 193                         strlen(self::STACK_MAGIC) +
 194                         strlen(chr(BaseBinaryFile::SEPARATOR_HEADER_DATA)) +
 195                         BaseBinaryFile::LENGTH_COUNT +
 196                         strlen(chr(BaseBinaryFile::SEPARATOR_HEADER_DATA)) +
 197                         BaseBinaryFile::LENGTH_POSITION +
 198                         strlen(chr(BaseBinaryFile::SEPARATOR_HEADER_ENTRIES))
 199                 );
 200
 201                 // Init counters and gaps array
 202                 $this->getIteratorInstance()->initCountersGapsArray();
 203
 204                 // Is the file's header initialized?
 205                 if (!$this->getIteratorInstance()->isFileHeaderInitialized()) {
 206                         // No, then create it (which may pre-allocate the stack)
 207                         $this->getIteratorInstance()->createFileHeader();
 208
 209                         // And pre-allocate a bit
 210                         $this->getIteratorInstance()->preAllocateFile('file_stack');
 211                 } // END - if
 212
 213                 // Load the file header
 214                 $this->readFileHeader();
 215
 216                 // Count all entries in file
 217                 $this->getIteratorInstance()->analyzeFile();
 218
 219                 /*
 220                  * Get stack index instance. This can be used for faster
 221                  * "defragmentation" and startup.
 222                  */
 223                 $indexInstance = FileStackIndexFactory::createFileStackIndexInstance($fileInfoInstance, $type);
 224
 225                 // And set it here
 226                 $this->setIndexInstance($indexInstance);
 227         }
 228
 229         /**
 230          * Adds a value to given stack
 231          *
 232          * @param       $stackerName    Name of the stack
 233          * @param       $value                  Value to add to this stacker
 234          * @return      void
 235          * @throws      FullStackerException    If the stack is full
 236          */
 237         protected function addValue ($stackerName, $value) {
 238                 // Do some tests
 239                 if ($this->isStackFull($stackerName)) {
 240                         // Stacker is full
 241                         throw new FullStackerException(array($this, $stackerName, $value), self::EXCEPTION_STACKER_IS_FULL);
 242                 } // END - if
 243
 244                 // Debug message
 245                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('[' . __METHOD__ . ':' . __LINE__ . '] stackerName=' . $stackerName . ',value[' . gettype($value) . ']=' . print_r($value, true));
 246
 247                 // No objects/resources are allowed as their serialization takes to long
 248                 assert(!is_object($value));
 249                 assert(!is_resource($value));
 250
 251                 /*
 252                  * Now add the value to the file stack which returns gap position, a
 253                  * hash and length of the raw data.
 254                  */
 255                 $data = $this->getIteratorInstance()->writeValueToFile($stackerName, $value);
 256
 257                 // Add the hash and gap position to the index
 258                 $this->getIndexInstance()->addHashToIndex($stackerName, $data);
 259         }
 260
 261         /**
 262          * Get last value from named stacker
 263          *
 264          * @param       $stackerName    Name of the stack
 265          * @return      $value                  Value of last added value
 266          * @throws      EmptyStackerException   If the stack is empty
 267          */
 268         protected function getLastValue ($stackerName) {
 269                 // Is the stack not yet initialized or full?
 270                 if ($this->isStackEmpty($stackerName)) {
 271                         // Throw an exception
 272                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 273                 } // END - if
 274
 275                 // Now get the last value
 276                 /* NOISY-DEBUG: */ $this->partialStub('[' . __METHOD__ . ':' . __LINE__ . '] stackerName=' . $stackerName);
 277                 $value = NULL;
 278
 279                 // Return it
 280                 return $value;
 281         }
 282
 283         /**
 284          * Get first value from named stacker
 285          *
 286          * @param       $stackerName    Name of the stack
 287          * @return      $value                  Value of last added value
 288          * @throws      EmptyStackerException   If the stack is empty
 289          */
 290         protected function getFirstValue ($stackerName) {
 291                 // Is the stack not yet initialized or full?
 292                 if ($this->isStackEmpty($stackerName)) {
 293                         // Throw an exception
 294                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 295                 } // END - if
 296
 297                 // Now get the first value
 298                 /* NOISY-DEBUG: */ $this->partialStub('[' . __METHOD__ . ':' . __LINE__ . '] stackerName=' . $stackerName);
 299                 $value = NULL;
 300
 301                 // Return it
 302                 return $value;
 303         }
 304
 305         /**
 306          * "Pops" last entry from stack
 307          *
 308          * @param       $stackerName    Name of the stack
 309          * @return      $value                  Value "poped" from array
 310          * @throws      EmptyStackerException   If the stack is empty
 311          */
 312         protected function popLast ($stackerName) {
 313                 // Is the stack not yet initialized or full?
 314                 if ($this->isStackEmpty($stackerName)) {
 315                         // Throw an exception
 316                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 317                 } // END - if
 318
 319                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
 320                 /* NOISY-DEBUG: */ $this->partialStub('[' . __METHOD__ . ':' . __LINE__ . '] stackerName=' . $stackerName);
 321                 return NULL;
 322         }
 323
 324         /**
 325          * "Pops" first entry from stack
 326          *
 327          * @param       $stackerName    Name of the stack
 328          * @return      $value                  Value "shifted" from array
 329          * @throws      EmptyStackerException   If the named stacker is empty
 330          */
 331         protected function popFirst ($stackerName) {
 332                 // Is the stack not yet initialized or full?
 333                 if ($this->isStackEmpty($stackerName)) {
 334                         // Throw an exception
 335                         throw new EmptyStackerException(array($this, $stackerName), self::EXCEPTION_STACKER_IS_EMPTY);
 336                 } // END - if
 337
 338                 // Now, remove the last entry, we don't care about the return value here, see elseif() block above
 339                 /* NOISY-DEBUG: */ $this->partialStub('[' . __METHOD__ . ':' . __LINE__ . '] stackerName=' . $stackerName);
 340                 return NULL;
 341         }
 342
 343         /**
 344          * Checks whether the given stack is full
 345          *
 346          * @param       $stackerName    Name of the stack
 347          * @return      $isFull                 Whether the stack is full
 348          */
 349         protected function isStackFull ($stackerName) {
 350                 // File-based stacks will only run full if the disk space is low.
 351                 // @TODO Please implement this, returning false
 352                 $isFull = false;
 353
 354                 // Return result
 355                 return $isFull;
 356         }
 357
 358         /**
 359          * Checks whether the given stack is empty
 360          *
 361          * @param       $stackerName            Name of the stack
 362          * @return      $isEmpty                        Whether the stack is empty
 363          * @throws      NoStackerException      If given stack is missing
 364          */
 365         public function isStackEmpty ($stackerName) {
 366                 // So, is the stack empty?
 367                 $isEmpty = (($this->getStackCount($stackerName)) == 0);
 368
 369                 // Return result
 370                 return $isEmpty;
 371         }
 372
 373         /**
 374          * Initializes given stacker
 375          *
 376          * @param       $stackerName    Name of the stack
 377          * @param       $forceReInit    Force re-initialization
 378          * @return      void
 379          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 380          */
 381         public function initStack ($stackerName, $forceReInit = false) {
 382                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 383         }
 384
 385         /**
 386          * Initializes all stacks
 387          *
 388          * @return      void
 389          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 390          */
 391         public function initStacks (array $stacks, $forceReInit = false) {
 392                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 393         }
 394
 395         /**
 396          * Checks whether the given stack is initialized (set in array $stackers)
 397          *
 398          * @param       $stackerName    Name of the stack
 399          * @return      $isInitialized  Whether the stack is initialized
 400          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 401          */
 402         public function isStackInitialized ($stackerName) {
 403                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 404         }
 405
 406         /**
 407          * Determines whether the EOF has been reached
 408          *
 409          * @return      $isEndOfFileReached             Whether the EOF has been reached
 410          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 411          */
 412         public function isEndOfFileReached () {
 413                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 414         }
 415
 416         /**
 417          * Getter for size of given stack (array count)
 418          *
 419          * @param       $stackerName    Name of the stack
 420          * @return      $count                  Size of stack (array count)
 421          */
 422         public function getStackCount ($stackerName) {
 423                 // Now, simply return the found count value, this must be up-to-date then!
 424                 return $this->getIteratorInstance()->getCounter();
 425         }
 426
 427         /**
 428          * Calculates minimum length for one entry/block
 429          *
 430          * @return      $length         Minimum length for one entry/block
 431          */
 432         public function calculateMinimumBlockLength () {
 433                 // Calulcate it
 434                 $length =
 435                         // Length of entry group
 436                         BaseBinaryFile::LENGTH_GROUP + strlen(chr(BaseBinaryFile::SEPARATOR_GROUP_HASH)) +
 437                         // Hash + value
 438                         self::getHashLength() + strlen(chr(BaseBinaryFile::SEPARATOR_HASH_VALUE)) + 1 +
 439                         // Final separator
 440                         strlen(chr(BaseBinaryFile::SEPARATOR_ENTRIES));
 441
 442                 // Return it
 443                 return $length;
 444         }
 445
 446         /**
 447          * Initializes counter for valid entries, arrays for damaged entries and
 448          * an array for gap seek positions. If you call this method on your own,
 449          * please re-analyze the file structure. So you are better to call
 450          * analyzeFile() instead of this method.
 451          *
 452          * @return      void
 453          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 454          */
 455         public function initCountersGapsArray () {
 456                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 457         }
 458
 459         /**
 460          * Getter for header size
 461          *
 462          * @return      $totalEntries   Size of file header
 463          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 464          */
 465         public final function getHeaderSize () {
 466                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 467         }
 468
 469         /**
 470          * Setter for header size
 471          *
 472          * @param       $headerSize             Size of file header
 473          * @return      void
 474          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 475          */
 476         public final function setHeaderSize ($headerSize) {
 477                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 478         }
 479
 480         /**
 481          * Getter for header array
 482          *
 483          * @return      $totalEntries   Size of file header
 484          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 485          */
 486         public final function getHeader () {
 487                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 488         }
 489
 490         /**
 491          * Setter for header
 492          *
 493          * @param       $header         Array for a file header
 494          * @return      void
 495          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 496          */
 497         public final function setHeader (array $header) {
 498                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 499         }
 500
 501         /**
 502          * Updates seekPosition attribute from file to avoid to much access on file.
 503          *
 504          * @return      void
 505          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 506          */
 507         public function updateSeekPosition () {
 508                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 509         }
 510
 511         /**
 512          * Getter for total entries
 513          *
 514          * @return      $totalEntries   Total entries in this file
 515          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 516          */
 517         public final function getCounter () {
 518                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 519         }
 520
 521         /**
 522          * Writes data at given position
 523          *
 524          * @param       $seekPosition   Seek position
 525          * @param       $data                   Data to be written
 526          * @param       $flushHeader    Whether to flush the header (default: flush)
 527          * @return      void
 528          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 529          */
 530         public function writeData ($seekPosition, $data, $flushHeader = true) {
 531                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] seekPosition=%s,data[]=%s,flushHeader=%d', __METHOD__, __LINE__, $seekPosition, gettype($data), intval($flushHeader)));
 532                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 533         }
 534
 535         /**
 536          * Writes given value to the file and returns a hash and gap position for it
 537          *
 538          * @param       $groupId        Group identifier
 539          * @param       $value          Value to be added to the stack
 540          * @return      $data           Hash and gap position
 541          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 542          */
 543         public function writeValueToFile ($groupId, $value) {
 544                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] groupId=%s,value[%s]=%s', __METHOD__, __LINE__, $groupId, gettype($value), print_r($value, true)));
 545                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 546         }
 547
 548         /**
 549          * Searches for next suitable gap the given length of data can fit in
 550          * including padding bytes.
 551          *
 552          * @param       $length                 Length of raw data
 553          * @return      $seekPosition   Found next gap's seek position
 554          * @throws      UnsupportedOperationException   This method is not (and maybe never will be) supported
 555          */
 556         public function searchNextGap ($length) {
 557                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] length=%s', __METHOD__, __LINE__, $length));
 558                 throw new UnsupportedOperationException(array($this, __FUNCTION__, $this->getIteratorInstance()->getPointerInstance()), self::EXCEPTION_UNSPPORTED_OPERATION);
 559         }
 560
 561         /**
 562          * "Getter" for file size
 563          *
 564          * @return      $fileSize       Size of currently loaded file
 565          */
 566         public function getFileSize () {
 567                 // Call iterator's method
 568                 return $this->getIteratorInstance()->getFileSize();
 569         }
 570
 571         /**
 572          * Writes given raw data to the file and returns a gap position and length
 573          *
 574          * @param       $groupId        Group identifier
 575          * @param       $hash           Hash from encoded value
 576          * @param       $encoded        Encoded value to be written to the file
 577          * @return      $data           Gap position and length of the raw data
 578          */
 579         public function writeDataToFreeGap ($groupId, $hash, $encoded) {
 580                 // Debug message
 581                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] groupId=%s,hash=%s,encoded()=%d - CALLED!', __METHOD__, __LINE__, $groupId, $hash, strlen($encoded)));
 582
 583                 // Raw data been written to the file
 584                 $rawData = sprintf('%s%s%s%s%s',
 585                         $groupId,
 586                         BaseBinaryFile::SEPARATOR_GROUP_HASH,
 587                         hex2bin($hash),
 588                         BaseBinaryFile::SEPARATOR_HASH_VALUE,
 589                         $encoded
 590                 );
 591
 592                 // Debug message
 593                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] groupId=%s,hash=%s,rawData()=%d', __METHOD__, __LINE__, $groupId, $hash, strlen($rawData)));
 594
 595                 // Search for next free gap
 596                 $gapPosition = $this->getIteratorInstance()->searchNextGap(strlen($rawData));
 597
 598                 // Gap position cannot be smaller than header length + 1
 599                 assert($gapPosition > $this->getIteratorInstance()->getHeaderSize());
 600
 601                 // Debug message
 602                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] groupId=%s,hash=%s,gapPosition=%s', __METHOD__, __LINE__, $groupId, $hash, $gapPosition));
 603
 604                 // Then write the data at that gap
 605                 $this->getIteratorInstance()->writeData($gapPosition, $rawData);
 606
 607                 // Debug message
 608                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d:] groupId=%s,hash=%s,rawData()=%d - EXIT!', __METHOD__, __LINE__, $groupId, $hash, strlen($rawData)));
 609
 610                 // Return gap position, hash and length of raw data
 611                 return array(
 612                         self::ARRAY_INDEX_GAP_POSITION => $gapPosition,
 613                         self::ARRAY_INDEX_HASH         => $hash,
 614                         self::ARRAY_INDEX_DATA_LENGTH  => strlen($rawData)
 615                 );
 616         }
 617
 618 }