framework/main/classes/stacker/file/fifo/class_FiFoFileStack.php

   1 <?php
   2 // Own namespace
   3 namespace Org\Mxchange\CoreFramework\Stack\File;
   4
   5 // Import framework stuff
   6 use Org\Mxchange\CoreFramework\Filesystem\Block\CalculatableBlock;
   7 use Org\Mxchange\CoreFramework\Registry\Registerable;
   8 use Org\Mxchange\CoreFramework\Stack\File\BaseFileStack;
   9 use Org\Mxchange\CoreFramework\Stack\File\StackableFile;
  10
  11 // Import SPL stuff
  12 use \InvalidArgumentException;
  13 use \OutOfBoundsException;
  14 use \SplFileInfo;
  15
  16 /**
  17  * A FiFo file-based stack
  18  *
  19  * @author              Roland Haeder <webmaster@ship-simu.org>
  20  * @version             0.0.0
  21  * @copyright   Copyright (c) 2020 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 class FiFoFileStack extends BaseFileStack implements StackableFile, CalculatableBlock, Registerable {
  39         /**
  40          * Protected constructor
  41          *
  42          * @return      void
  43          */
  44         private function __construct () {
  45                 // Call parent constructor
  46                 parent::__construct(__CLASS__);
  47         }
  48
  49         /**
  50          * Creates an instance of this class
  51          *
  52          * @param       $fileInfoInstance       An instance of a SplFileInfo class
  53          * @param       $type                   Type of this stack (e.g. url_source for URL sources)
  54          * @return      $stackInstance  An instance of a StackableFile class
  55          * @throws      InvalidArgumentException        If a parameter is invalid
  56          */
  57         public final static function createFiFoFileStack (SplFileInfo $fileInfoInstance, string $type) {
  58                 // Validate parameter
  59                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FIFO-FILE-STACK: fileInfoInstance[%s]=%s,type=%s - CALLED!', get_class($fileInfoInstance), $fileInfoInstance, $type));
  60                 if (empty($type)) {
  61                         // No empty type
  62                         throw new InvalidArgumentException('Parameter "type" is empty');
  63                 }
  64
  65                 // Get new instance
  66                 $stackInstance = new FiFoFileStack();
  67
  68                 // Init this stack
  69                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FIFO-FILE-STACK: Calling stackInstance->initFileStack([%s]=%s,%s) ...', get_class($fileInfoInstance), $fileInfoInstance, $type));
  70                 $stackInstance->initFileStack($fileInfoInstance, $type);
  71
  72                 // Return the prepared instance
  73                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FIFO-FILE-STACK: stackInstance=%s - EXIT!', $stackInstance->__toString()));
  74                 return $stackInstance;
  75         }
  76
  77         /**
  78          * Pushs a value on a named stacker
  79          *
  80          * @param       $stackerName    Name of the stack
  81          * @param       $value                  Value to push on it
  82          * @return      void
  83          * @throws      InvalidArgumentException        If a parameter is invalid
  84          * @throws      StackerFullException    If the stack is full
  85          */
  86         public function pushNamed (string $stackerName, $value) {
  87                 // Validate parameter
  88                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FIFO-FILE-STACK: stackerName=%s,value[]=%s - CALLED!', $stackerName, gettype($value)));
  89                 if (empty($stackerName)) {
  90                         // No empty stack name
  91                         throw new InvalidArgumentException('Parameter "stackerName" is empty');
  92                 } elseif (is_object($value) || is_resource($value)) {
  93                         // Those types for $value are not allowed
  94                         throw new InvalidArgumentException(sprintf('value[]=%s is not valid', gettype($value)));
  95                 }
  96
  97                 // Call the protected method
  98                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FIFO-FILE-STACK: Calling parent::addValueToStack(%s,%s) ...', $stackerName, gettype($value)));
  99                 parent::addValueToStack($stackerName, $value);
 100
 101                 // Trace message
 102                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FIFO-FILE-STACK: EXIT!');
 103         }
 104
 105         /**
 106          * 'Pops' a value from a named stacker and returns it's value
 107          *
 108          * @param       $stackerName    Name of the stack
 109          * @return      $value                  Value of the current stack entry
 110          * @throws      InvalidArgumentException        If a parameter is invalid
 111          * @throws      BadMethodCallException  If the named stacker was not found
 112          * @throws      BadMethodCallException  If the named stacker is empty
 113          */
 114         public function popNamed (string $stackerName) {
 115                 // Validate parameter
 116                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FIFO-FILE-STACK: stackerName=%s - CALLED!', $stackerName));
 117                 if (empty($stackerName)) {
 118                         // No empty stack name
 119                         throw new InvalidArgumentException('Parameter "stackerName" is empty');
 120                 }
 121
 122                 // Get the value
 123                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FIFO-FILE-STACK: this->getNamed(%s) ...', $stackerName));
 124                 $value = $this->getNamed($stackerName);
 125
 126                 // Call the protected method
 127                 parent::popFirst($stackerName);
 128
 129                 // Return the value
 130                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FIFO-FILE-STACK: value[]=%s - EXIT!', gettype($value)));
 131                 return $value;
 132         }
 133
 134         /**
 135          * Get value from named stacker
 136          *
 137          * @param       $stackerName    Name of the stack
 138          * @return      $value                  Value of last added value
 139          * @throws      InvalidArgumentException        If a parameter is invalid
 140          * @throws      BadMethodCallException  If the named stacker was not found
 141          * @throws      BadMethodCallException  If the named stacker is empty
 142          */
 143         public function getNamed (string $stackerName) {
 144                 // Validate parameter
 145                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FIFO-FILE-STACK: stackerName=%s - CALLED!', $stackerName));
 146                 if (empty($stackerName)) {
 147                         // No empty stack name
 148                         throw new InvalidArgumentException('Parameter "stackerName" is empty');
 149                 }
 150
 151                 // Call the protected method
 152                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FIFO-FILE-STACK: parent::getFirstValue(%s) ...', $stackerName));
 153                 $value = parent::getFirstValue($stackerName);
 154
 155                 // Return the value
 156                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FIFO-FILE-STACK: value[]=%s - EXIT!', gettype($value)));
 157                 return $value;
 158         }
 159
 160         /**
 161          * Seeks to given position
 162          *
 163          * @param       $seekPosition   Seek position in file
 164          * @param       $whence                 Added to offset (default: only use offset to seek to)
 165          * @return      $status                 Status of this operation
 166          * @throws      OutOfBoundsException    If the position is not seekable
 167          */
 168         public function seek (int $seekPosition, int $whence = SEEK_SET) {
 169                 // Validate parameter
 170                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FIFO-FILE-STACK: seekPosition=%d,whence=%d - CALLED!', $seekPosition, $whence));
 171                 if ($seekPosition < 0) {
 172                         // Invalid seek position
 173                         throw new OutOfBoundsException(sprintf('seekPosition=%d is not valid', $seekPosition));
 174                 }
 175
 176                 // @TODO Unfinished method or invoke inner iterator's method?
 177                 $this->partialStub('seekPosition=' . $seekPosition);
 178
 179                 // Trace message
 180                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FIFO-FILE-STACK: EXIT!');
 181         }
 182
 183         /**
 184          * Size of file stack
 185          *
 186          * @return      $size   Size (in bytes) of file
 187          */
 188         public function size () {
 189                 // Call the iterator instance
 190                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FIFO-FILE-STACK: CALLED!');
 191                 $size = $this->getIteratorInstance()->size();
 192
 193                 // Return size
 194                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FIFO-FILE-STACK: size=%d - EXIT!', $size));
 195                 return $size;
 196         }
 197
 198 }