Refacuring / possible WIP:

[core.git] / framework / main / classes / iterator / file / class_FileIterator.php

diff --git a/framework/main/classes/iterator/file/class_FileIterator.php b/framework/main/classes/iterator/file/class_FileIterator.php
index 0163ffed79afa326e269fa4a0fa3d4dc65575f1d..50a69ed9e322b2cb6e8441baf1fb67976c976009 100644 (file)
--- a/framework/main/classes/iterator/file/class_FileIterator.php
+++ b/framework/main/classes/iterator/file/class_FileIterator.php
@@ -11,6 +11,7 @@ use Org\Mxchange\CoreFramework\Traits\File\BinaryFileTrait;
 // Import SPL stuff
 use \BadMethodCallException;
 use \InvalidArgumentException;
+use \OutOfBoundsException;
 
 /**
  * A file iterator
@@ -161,14 +162,14 @@ class FileIterator extends BaseIterator implements SeekableWritableFileIterator
         * @param       $seekPosition   Seek position in file
         * @param       $whence                 Added to offset (default: only use offset to seek to)
         * @return      $status                 Status of this operation
-        * @throws      InvalidArgumentException        If a parameter is not valid
+        * @throws      OutOfBoundsException    If the position is not seekable
         */
        public function seek (int $seekPosition, int $whence = SEEK_SET) {
                // Validate parameter
                //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: seekPosition=%d,whence=%d - CALLED!', $seekPosition, $whence));
                if ($seekPosition < 0) {
                        // Throw IAE
-                       throw new InvalidArgumentException(sprintf('seekPosition=%d is not valid', $seekPosition));
+                       throw new OutOfBoundsException(sprintf('seekPosition=%d is not valid', $seekPosition));
                }
 
                // Call file instance
@@ -199,13 +200,14 @@ class FileIterator extends BaseIterator implements SeekableWritableFileIterator
         *
         * @param       $bytes  Amount of bytes to read
         * @return      $data   Data read from file
+        * @throws      OutOfBoundsException    If the position is not seekable
         */
        public function read (int $bytes = 0) {
                // Validate parameter
                //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: bytes=%d - CALLED!', $bytes));
                if ($bytes < 0) {
-                       // Throw IAE
-                       throw new InvalidArgumentException(sprintf('bytes=%d is not valid', $bytes));
+                       // Throw exception
+                       throw new OutOfBoundsException(sprintf('bytes=%d is not valid', $bytes));
                }
 
                // Call file instance
@@ -411,16 +413,17 @@ class FileIterator extends BaseIterator implements SeekableWritableFileIterator
         * @param       $data                   Data to be written
         * @param       $flushHeader    Whether to flush the header (default: flush)
         * @return      void
+        * @throws      OutOfBoundsException    If the position is not seekable
         * @throws      InvalidArgumentException        If a parameter is not valid
         */
        public function writeData (int $seekPosition, string $data, bool $flushHeader = true) {
                // Validate parameter
                //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: seekPosition=%d,data(%d)=%s,flushHeader=%d - CALLED!', $seekPosition, strlen($data), $data, intval($flushHeader)));
                if ($seekPosition < 0) {
-                       // Throw IAE
-                       throw new InvalidArgumentException(sprintf('seekPosition=%d is not valid', $seekPosition));
+                       // Throw exception
+                       throw new OutOfBoundsException(sprintf('seekPosition=%d is not valid', $seekPosition));
                } elseif (empty($data)) {
-                       // Throw it again
+                       // Throw IAE
                        throw new InvalidArgumentException('Parameter "data" is empty');
                }
 
@@ -438,6 +441,7 @@ class FileIterator extends BaseIterator implements SeekableWritableFileIterator
         * @param       $seekPosition   Seek position in file
         * @param       $dataStream             Data to be written
         * @return      mixed                   Number of writes bytes or false on error
+        * @throws      OutOfBoundsException    If the position is not seekable
         * @throws      InvalidArgumentException        If a parameter is not valid
         */
        public function writeAtPosition (int $seekPosition, string $dataStream) {
@@ -445,7 +449,7 @@ class FileIterator extends BaseIterator implements SeekableWritableFileIterator
                //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: seekPosition=%d,dataStream(%d)=%s - CALLED!', $seekPosition, strlen($dataStream), $dataStream));
                if ($seekPosition < 0) {
                        // Invalid seek position
-                       throw new InvalidArgumentException(sprintf('seekPosition=%d is not valid.', $seekPosition));
+                       throw new OutOfBoundsException(sprintf('seekPosition=%d is not valid.', $seekPosition));
                } elseif (empty($dataStream)) {
                        // Empty dataStream
                        throw new InvalidArgumentException('Parameter "dataStream" is empty');
@@ -478,24 +482,24 @@ class FileIterator extends BaseIterator implements SeekableWritableFileIterator
        /**
         * Writes given value to the file and returns a hash and gap position for it
         *
-        * @param       $groupId        Group identifier
+        * @param       $stackName      Group identifier
         * @param       $value          Value to be added to the stack
         * @return      $data           Hash and gap position
         * @throws      InvalidArgumentException        If a parameter is not valid
         */
-       public function writeValueToFile (string $groupId, $value) {
+       public function writeValueToFile (string $stackName, $value) {
                // Validate parameter
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: groupId=%s,value[]=%s - CALLED!', $groupId, gettype($value)));
-               if (empty($groupId)) {
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: stackName=%s,value[]=%s - CALLED!', $stackName, gettype($value)));
+               if (empty($stackName)) {
                        // Throw IAE
-                       throw new InvalidArgumentException('Parameter "groupId" is empty');
+                       throw new InvalidArgumentException('Parameter "stackName" is empty');
                } elseif (is_resource($value) || is_object($value)) {
                        // Resources and objects are nothing for file-based indexes (mostly)
                        throw new InvalidArgumentException(sprintf('value[]=%s is not supported by file-based indexes', gettype($value)));
                }
 
                // Call file instance
-               $data = $this->getBinaryFileInstance()->writeValueToFile($groupId, $value);
+               $data = $this->getBinaryFileInstance()->writeValueToFile($stackName, $value);
 
                // Return data
                //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: data[]=%s - EXIT!', gettype($data)));
@@ -505,17 +509,17 @@ class FileIterator extends BaseIterator implements SeekableWritableFileIterator
        /**
         * Writes given raw data to the file and returns a gap position and length
         *
-        * @param       $groupId        Group identifier
+        * @param       $stackName      Group identifier
         * @param       $hash           Hash from encoded value
         * @param       $encoded        Encoded value to be written to the file
         * @return      $data           Gap position and length of the raw data
         */
-       public function writeDataToFreeGap (string $groupId, string $hash, string $encoded) {
+       public function writeDataToFreeGap (string $stackName, string $hash, string $encoded) {
                // Validate parameter
-               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: groupId=%s,hash=%s,encoded(%d)=%s - CALLED!', $groupId, $hash, strlen($encoded), $encoded));
+               //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: stackName=%s,hash=%s,encoded(%d)=%s - CALLED!', $stackName, $hash, strlen($encoded), $encoded));
 
                // Call file instance
-               $data = $this->getBinaryFileInstance()->writeDataToFreeGap($groupId, $hash, $encoded);
+               $data = $this->getBinaryFileInstance()->writeDataToFreeGap($stackName, $hash, $encoded);
 
                // Return data
                //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: data[]=%s - EXIT!', gettype($data)));