framework/main/middleware/io/class_FileIoHandler.php

   1 <?php
   2 // Own namespace
   3 namespace Org\Mxchange\CoreFramework\Handler\Filesystem;
   4
   5 // Import framework stuff
   6 use Org\Mxchange\CoreFramework\Factory\Object\ObjectFactory;
   7 use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
   8 use Org\Mxchange\CoreFramework\Generic\UnsupportedOperationException;
   9 use Org\Mxchange\CoreFramework\Handler\Stream\IoHandler;
  10 use Org\Mxchange\CoreFramework\Middleware\BaseMiddleware;
  11 use Org\Mxchange\CoreFramework\Traits\Streamer\File\Input\FileInputStreamerTrait;
  12 use Org\Mxchange\CoreFramework\Traits\Streamer\File\Output\FileOutputStreamerTrait;
  13
  14 // Import SPL stuff
  15 use \InvalidArgumentException;
  16 use \SplFileInfo;
  17
  18 /**
  19  * This is a file IO handler. It handles reading from and writing to files.
  20  * Missing paths in writing process will be automatically created.
  21  *
  22  * @author              Roland Haeder <webmaster@shipsimu.org>
  23  * @version             0.0.0
  24  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
  25  * @license             GNU GPL 3.0 or any newer version
  26  * @link                http://www.shipsimu.org
  27  *
  28  * This program is free software: you can redistribute it and/or modify
  29  * it under the terms of the GNU General Public License as published by
  30  * the Free Software Foundation, either version 3 of the License, or
  31  * (at your option) any later version.
  32  *
  33  * This program is distributed in the hope that it will be useful,
  34  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  35  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  36  * GNU General Public License for more details.
  37  *
  38  * You should have received a copy of the GNU General Public License
  39  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  40  */
  41 class FileIoHandler extends BaseMiddleware implements IoHandler {
  42         // Load traits
  43         use FileInputStreamerTrait;
  44         use FileOutputStreamerTrait;
  45
  46         /**
  47          * An instance of this class
  48          */
  49         private static $selfInstance = NULL;
  50
  51         /**
  52          * Protected constructor
  53          *
  54          * @return      void
  55          */
  56         private function __construct () {
  57                 // Call parent constructor
  58                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: CONSTRUCTED!');
  59                 parent::__construct(__CLASS__);
  60
  61                 // Set own instance
  62                 self::$selfInstance = $this;
  63
  64                 // Trace message
  65                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
  66         }
  67
  68         /**
  69          * Creates an instance of this class and prepares the IO system. This is
  70          * being done by setting the default file IO class
  71          *
  72          * @return      $ioHandlerInstance      A prepared instance of FilIoHandler
  73          */
  74         public static final function createFileIoHandler () {
  75                 // Get instance
  76                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: CALLED!');
  77                 $ioHandlerInstance = new FileIoHandler();
  78
  79                 // Set the *real* file IO instances (both the same)
  80                 $ioHandlerInstance->setInputStreamerInstance(ObjectFactory::createObjectByConfiguredName('file_input_class'));
  81                 $ioHandlerInstance->setOutputStreamerInstance(ObjectFactory::createObjectByConfiguredName('file_output_class'));
  82
  83                 // Return instance
  84                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-IO-HANDLER: ioHandlerInstance=%s - EXIT!', $ioHandlerInstance->__toString()));
  85                 return $ioHandlerInstance;
  86         }
  87
  88         /**
  89          * Getter for an instance of this class
  90          *
  91          * @return      $selfInstance   An instance of this class
  92          */
  93         public static final function getSelfInstance () {
  94                 // Trace message
  95                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-IO-HANDLER: Returning self::selfInstance[]=%s - EXIT!', gettype(self::$selfInstance)));
  96                 return self::$selfInstance;
  97         }
  98
  99         /**
 100          * Saves streamed (that are mostly serialized objects) data to files or
 101          * external servers.
 102          *
 103          * @param       $infoInstance   An instance of a SplFileInfo class
 104          * @param       $dataArray      Array containing the compressor's extension and streamed data
 105          * @return      void
 106          * @throws      UnsupportedOperationException   If this method is called
 107          */
 108         public function saveFile (SplFileInfo $infoInstance, array $dataArray) {
 109                 // Trace message for logging parameters
 110                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-IO-HANDLER: infoInstance.pathname=%s,dataArray()=%d - CALLED!', $infoInstance->getPathname(), count($dataArray)));
 111                 throw new UnsupportedOperationException([$this, __FUNCTION__], FrameworkInterface::EXCEPTION_UNSPPORTED_OPERATION);
 112         }
 113
 114         /**
 115          * Saves a file with data by using the current output stream
 116          *
 117          * @param       $infoInstance           An instance of a SplFileInfo class
 118          * @param       $dataStream                     File data stream
 119          * @param       $objectInstance         An instance of a FrameworkInterface class (default: NULL)
 120          * @return      void
 121          * @throws      InvalidArgumentException        If a parameter has an invalid value
 122          */
 123         public function saveStreamToFile (SplFileInfo $infoInstance, string $dataStream, FrameworkInterface $objectInstance = NULL) {
 124                 // Check parameters
 125                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-IO-HANDLER: infoInstance=%s,dataStream()=%d,objectInstance[]=%s - CALLED!', $infoInstance->__toString(), strlen($dataStream), gettype($objectInstance)));
 126                 if (empty($dataStream)) {
 127                         // Throw IAE
 128                         throw new InvalidArgumentException('Parameter "dataStream" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 129                 }
 130
 131                 // Default is this array
 132                 $className = $this->__toString();
 133
 134                 // Is the object instance set?
 135                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('FILE-IO-HANDLER: className=%s - BEFORE!', $className));
 136                 if ($objectInstance instanceof FrameworkInterface) {
 137                         // Then use this
 138                         $className = $objectInstance->__toString();
 139                 }
 140
 141                 // Send the infoInstance and data array to the output handler
 142                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('FILE-IO-HANDLER: className=%s - AFTER!', $className));
 143                 $this->getOutputStreamerInstance()->saveFile($infoInstance, [
 144                         0 => $className,
 145                         1 => $dataStream
 146                 ]);
 147
 148                 // Trace message
 149                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
 150         }
 151
 152         /** Loads data from a file over the input handler
 153          *
 154          * @param       $infoInstance   An instance of a SplFileInfo class
 155          * @return      $array  Array with the file contents
 156          */
 157         public function loadFileContents (SplFileInfo $infoInstance) {
 158                 // Read from the input handler
 159                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-IO-HANDLER: infoInstance=%s - CALLED!', $infoInstance->__toString()));
 160                 return $this->getInputStreamerInstance()->loadFileContents($infoInstance);
 161         }
 162
 163         /**
 164          * Determines seek position
 165          *
 166          * @return      $seekPosition   Current seek position
 167          * @todo        0% done
 168          */
 169         public function determineSeekPosition () {
 170                 // Trace message
 171                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: CALLED!');
 172                 $this->partialStub();
 173
 174                 // Trace message
 175                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
 176         }
 177
 178         /**
 179          * Seek to given offset (default) or other possibilities as fseek() gives.
 180          *
 181          * @param       $offset         Offset to seek to (or used as "base" for other seeks)
 182          * @param       $whence         Added to offset (default: only use offset to seek to)
 183          * @return      void
 184          * @throws      InvalidArgumentException        If a parameter has an invalid value
 185          */
 186         public function seek (int $offset, int $whence = SEEK_SET) {
 187                 // Check parameter
 188                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-IO-HANDLER: offset=%d,whence=%d - CALLED!', $offset, $whence));
 189                 if ($offset < 0) {
 190                         // Throw IAE
 191                         throw new InvalidArgumentException('Parameter "offset" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
 192                 }
 193
 194                 // @TODO Unfinished work
 195                 $this->partialStub('offset=' . $offset . ',whence=' . $whence);
 196
 197                 // Trace message
 198                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
 199         }
 200
 201         /**
 202          * Size of file stack
 203          *
 204          * @return      $size   Size (in bytes) of file
 205          * @todo        0% done
 206          */
 207         public function size () {
 208                 // Trace message
 209                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: CALLED!');
 210
 211                 // @TODO: Unfinished method:
 212                 $this->partialStub();
 213
 214                 // Trace message
 215                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
 216         }
 217
 218         /**
 219          * "Getter" for seek position
 220          *
 221          * @return      $seekPosition   Current seek position
 222          * @todo        0% done
 223          */
 224         public function getPosition () {
 225                 // Trace message
 226                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: CALLED!');
 227
 228                 // @TODO: Unfinished method:
 229                 $this->partialStub();
 230
 231                 // Trace message
 232                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
 233         }
 234
 235 }