X-Git-Url: https://git.mxchange.org/?p=core.git;a=blobdiff_plain;f=framework%2Fmain%2Fclasses%2Ffile_directories%2Fio%2Fclass_FrameworkFileInputOutputPointer.php;h=77643ecd20355bc1d0929f9ca88633e2c215d0e7;hp=1217e83a4bcd63be9ad7f935f318ea820d13a32e;hb=refs%2Fheads%2Fmaster;hpb=a60894f1d6ef33613d2d0351075aa07aa257f304 diff --git a/framework/main/classes/file_directories/io/class_FrameworkFileInputOutputPointer.php b/framework/main/classes/file_directories/io/class_FrameworkFileInputOutputPointer.php index 1217e83a..2a03a011 100644 --- a/framework/main/classes/file_directories/io/class_FrameworkFileInputOutputPointer.php +++ b/framework/main/classes/file_directories/io/class_FrameworkFileInputOutputPointer.php @@ -4,23 +4,29 @@ namespace Org\Mxchange\CoreFramework\Filesystem\Pointer; // Import framework stuff use Org\Mxchange\CoreFramework\Bootstrap\FrameworkBootstrap; -use Org\Mxchange\CoreFramework\FileSystem\BaseFileIo; -use Org\Mxchange\CoreFramework\FileSystem\FileReadProtectedException; -use Org\Mxchange\CoreFramework\FileSystem\FileWriteProtectedException; +use Org\Mxchange\CoreFramework\Filesystem\BaseFileIo; +use Org\Mxchange\CoreFramework\Filesystem\FileIoException; +use Org\Mxchange\CoreFramework\Filesystem\FileReadProtectedException; +use Org\Mxchange\CoreFramework\Filesystem\FileWriteProtectedException; use Org\Mxchange\CoreFramework\Filesystem\PathWriteProtectedException; +use Org\Mxchange\CoreFramework\Generic\FrameworkInterface; use Org\Mxchange\CoreFramework\Generic\NullPointerException; use Org\Mxchange\CoreFramework\Generic\UnsupportedOperationException; use Org\Mxchange\CoreFramework\Object\BaseFrameworkSystem; // Import SPL stuff +use \InvalidArgumentException; use \SplFileInfo; +use \SplFileObject; +use \OutOfBoundsException; +use \UnexpectedValueException; /** * A class for reading files * * @author Roland Haeder * @version 0.0.0 - * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2017 Core Developer Team + * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team * @license GNU GPL 3.0 or any newer version * @link http://www.shipsimu.org * @@ -43,7 +49,7 @@ class FrameworkFileInputOutputPointer extends BaseFileIo implements InputOutputP * * @return void */ - protected function __construct () { + private function __construct () { // Call parent constructor parent::__construct(__CLASS__); } @@ -61,6 +67,7 @@ class FrameworkFileInputOutputPointer extends BaseFileIo implements InputOutputP */ public static final function createFrameworkFileInputOutputPointer (SplFileInfo $fileInstance) { // Some pre-sanity checks... + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: fileInstance[%s]=%s - CALLED!', get_class($fileInstance), $fileInstance)); if (!FrameworkBootstrap::isReachableFilePath($fileInstance)) { // File exists but cannot be read throw new FileIoException($fileInstance, self::EXCEPTION_FILE_NOT_REACHABLE); @@ -79,10 +86,11 @@ class FrameworkFileInputOutputPointer extends BaseFileIo implements InputOutputP $fileObject = $fileInstance->openFile('c+b'); // Is it valid? - if ((is_null($fileObject)) || ($fileObject === false)) { + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: fileObject[]=%s', gettype($fileObject))); + if (!($fileObject instanceof SplFileObject)) { // Something bad happend throw new FileIoException($fileInstance->getPathname(), self::EXCEPTION_FILE_POINTER_INVALID); - } // END - if + } // Create new instance $pointerInstance = new FrameworkFileInputOutputPointer(); @@ -91,40 +99,23 @@ class FrameworkFileInputOutputPointer extends BaseFileIo implements InputOutputP $pointerInstance->setFileObject($fileObject); // Return the instance + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: pointerInstance=%s - EXIT!', $pointerInstance->__toString())); return $pointerInstance; } - /** - * Validates file pointer and throws exceptions. This method does not return - * anything (not reliable) as this method checks the file pointer and on - * case of an error it throws an exception. If this method does not throw - * any exceptions, the file pointer seems to be fine. - * - * @return void - * @throws NullPointerException If the file pointer instance - * is not set by setFileObject() - * @todo Add more checks - */ - private function validateFilePointer () { - if (is_null($this->getFileObject())) { - // Pointer not initialized - throw new NullPointerException($this, self::EXCEPTION_IS_NULL_POINTER); - } // END - if - - // All fine here - } - /** * Read 1024 bytes data from a file pointer * * @return mixed The result of fread() */ public function readFromFile () { - // Validate the pointer - $this->validateFilePointer(); - // Read data from the file pointer and return it - return $this->read(1024); + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-INPUT-OUTPUT-POINTER: CALLED!'); + $data = $this->read(1024); + + // Return data + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: data[%s]=%d - EXIT!', gettype($data), $data)); + return $data; } /** @@ -133,40 +124,70 @@ class FrameworkFileInputOutputPointer extends BaseFileIo implements InputOutputP * @param $dataStream The data stream we shall write to the file * @return mixed Number of writes bytes or false on error */ - public function writeToFile ($dataStream) { - // Validate the pointer - $this->validateFilePointer(); + public function writeToFile (string $dataStream) { + // Validate parameter + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: dataStream(%d)=%s - CALLED!', strlen($dataStream), $dataStream)); + if (empty($dataStream)) { + // Empty dataStream + throw new InvalidArgumentException('Parameter "dataStream" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT); + } + + // Get length + $length = strlen($dataStream); // Write data to the file pointer and return written bytes - return $this->getFileObject()->fwrite($dataStream, strlen($dataStream)); + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: Invoking this->fileObject->fwrite(%s,%d) ...', $dataStream, $length)); + $status = $this->getFileObject()->fwrite($dataStream, $length); + + // Return status + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: status[%s]=%d - EXIT!', gettype($status), $status)); + return $status; } /** * Writes at given position by seeking to it. * * @param $seekPosition Seek position in file - * @param $data Data to be written + * @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 ($seekPosition, $data) { - // First seek to it - $this->seek($seekPosition); + public function writeAtPosition (int $seekPosition, string $dataStream) { + // Validate parameter + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: seekPosition=%d,dataStream(%d)=%s - CALLED!', $seekPosition, strlen($dataStream), $dataStream)); + if ($seekPosition < 0) { + // Invalid seek position + throw new OutOfBoundsException(sprintf('seekPosition=%d is not valid.', $seekPosition)); + } elseif (empty($dataStream)) { + // Empty dataStream + throw new InvalidArgumentException('Parameter "dataStream" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT); + } elseif (($this->getFileSize() > 0 || $seekPosition > 0) && $this->seek($seekPosition) === -1) { + // Could not seek + throw new InvalidArgumentException(sprintf('Could not seek to seekPosition=%d', $seekPosition)); + } // Then write the data at that position - return $this->writeToFile($data); + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: Invoking this->writeToFile(%s) ...', $dataStream)); + $status = $this->writeToFile($dataStream); + + // Return status + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: status[%s]=%d - EXIT!', gettype($status), $status)); + return $status; } /** * Rewinds to the beginning of the file * - * @return $status Status of this operation + * @return void */ public function rewind () { - // Validate the pointer - $this->validateFilePointer(); + /// Rewind the pointer + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-INPUT-OUTPUT-POINTER: CALLED!'); + $this->getFileObject()->rewind(); - // Rewind the pointer - return $this->getFileObject()->rewind(); + // Trace message + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-INPUT-OUTPUT-POINTER: EXIT!'); } /** @@ -175,13 +196,25 @@ class FrameworkFileInputOutputPointer extends BaseFileIo implements InputOutputP * @param $seekPosition Seek position in file * @param $whence "Seek mode" (see http://de.php.net/fseek) * @return $status Status of this operation + * @throws OutOfBoundsException If the position is not seekable */ - public function seek ($seekPosition, $whence = SEEK_SET) { - // Validate the pointer - $this->validateFilePointer(); + public function seek (int $seekPosition, int $whence = SEEK_SET) { + // Validate parameter + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: seekPosition=%d,whence=%d - CALLED!', $seekPosition, $whence)); + if ($seekPosition < 0) { + // Invalid seek position + throw new OutOfBoundsException(sprintf('seekPosition=%d is not valid.', $seekPosition)); + } elseif ($whence < 0) { + // Invalid seek position + throw new OutOfBoundsException(sprintf('whence=%d is not valid.', $whence)); + } // Move the file pointer - return $this->getFileObject()->fseek($seekPosition, $whence); + $status = $this->getFileObject()->fseek($seekPosition, $whence); + + // Return status + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: status[%s]=%d - EXIT!', gettype($status), $status)); + return $status; } /** @@ -191,7 +224,12 @@ class FrameworkFileInputOutputPointer extends BaseFileIo implements InputOutputP */ public function readLine () { // Read whole line - return $this->read(); + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-INPUT-OUTPUT-POINTER: CALLED!'); + $data = $this->read(); + + // Return data + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: data[%s]=%s - EXIT!', gettype($data), $data)); + return $data; } /** @@ -199,13 +237,18 @@ class FrameworkFileInputOutputPointer extends BaseFileIo implements InputOutputP * * @param $bytes Amount of bytes to read * @return $data Data read from file + * @throws OutOfBoundsException If the position is not seekable */ - public function read ($bytes = NULL) { - // Validate the pointer - $this->validateFilePointer(); + public function read (int $bytes = 0) { + // Validatre parameter + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: bytes=%d - CALLED!', $bytes)); + if ($bytes < 0) { + // Bytes cannot be lesser than zero + throw new OutOfBoundsException(sprintf('bytes=%d is not valid', $bytes)); + } - // Is $bytes set? - if (is_int($bytes)) { + // Is $bytes bigger than zero? + if ($bytes > 0) { // Try to read given characters $data = $this->getFileObject()->fread($bytes); } else { @@ -214,6 +257,7 @@ class FrameworkFileInputOutputPointer extends BaseFileIo implements InputOutputP } // Then return it + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: data[%s]=%s - EXIT!', gettype($data), $data)); return $data; } @@ -225,8 +269,8 @@ class FrameworkFileInputOutputPointer extends BaseFileIo implements InputOutputP * @return void * @throws UnsupportedOperationException If this method is called */ - public function analyzeFile () { - throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION); + public function analyzeFileStructure () { + throw new UnsupportedOperationException([$this, __FUNCTION__], FrameworkInterface::EXCEPTION_UNSPPORTED_OPERATION); } /** @@ -236,7 +280,7 @@ class FrameworkFileInputOutputPointer extends BaseFileIo implements InputOutputP * @throws UnsupportedOperationException If this method is called */ public function next () { - throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION); + throw new UnsupportedOperationException([$this, __FUNCTION__], FrameworkInterface::EXCEPTION_UNSPPORTED_OPERATION); } /** @@ -247,7 +291,7 @@ class FrameworkFileInputOutputPointer extends BaseFileIo implements InputOutputP * @throws UnsupportedOperationException If this method is called */ public function valid () { - throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION); + throw new UnsupportedOperationException([$this, __FUNCTION__], FrameworkInterface::EXCEPTION_UNSPPORTED_OPERATION); } /** @@ -257,25 +301,28 @@ class FrameworkFileInputOutputPointer extends BaseFileIo implements InputOutputP * @throws UnsupportedOperationException If this method is called */ public function key () { - throw new UnsupportedOperationException(array($this, __FUNCTION__), self::EXCEPTION_UNSPPORTED_OPERATION); + throw new UnsupportedOperationException([$this, __FUNCTION__], FrameworkInterface::EXCEPTION_UNSPPORTED_OPERATION); } /** * "Getter" for file size * * @return $fileSize Size of currently loaded file + * @throws UnexpectedValueException If $fileData does not contain "size" */ public function getFileSize () { - // Check if the pointer is still valid - $this->validateFilePointer(); - // Get file's data + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-INPUT-OUTPUT-POINTER: CALLED!'); $fileData = $this->getFileObject()->fstat(); // Make sure the required array key is there - assert(isset($fileData['size'])); + if (!isset($fileData['size'])) { + // Not valid array + throw new UnexpectedValueException(sprintf('fileData=%s has no element "size"', print_r($fileData, TRUE)), FrameworkInterface::EXCEPTION_UNEXPECTED_VALUE); + } // Return size + /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-INPUT-OUTPUT-POINTER: fileData[size]=%d - EXIT!', $fileData['size'])); return $fileData['size']; }