3 namespace Org\Mxchange\CoreFramework\Handler\Filesystem;
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\Middleware\Debug\DebugMiddleware;
12 use Org\Mxchange\CoreFramework\Traits\Streamer\File\Input\FileInputStreamerTrait;
13 use Org\Mxchange\CoreFramework\Traits\Streamer\File\Output\FileOutputStreamerTrait;
16 use \InvalidArgumentException;
20 * This is a file IO handler. It handles reading from and writing to files.
21 * Missing paths in writing process will be automatically created.
23 * @author Roland Haeder <webmaster@shipsimu.org>
25 * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
26 * @license GNU GPL 3.0 or any newer version
27 * @link http://www.shipsimu.org
29 * This program is free software: you can redistribute it and/or modify
30 * it under the terms of the GNU General Public License as published by
31 * the Free Software Foundation, either version 3 of the License, or
32 * (at your option) any later version.
34 * This program is distributed in the hope that it will be useful,
35 * but WITHOUT ANY WARRANTY; without even the implied warranty of
36 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
37 * GNU General Public License for more details.
39 * You should have received a copy of the GNU General Public License
40 * along with this program. If not, see <http://www.gnu.org/licenses/>.
42 class FileIoHandler extends BaseMiddleware implements IoHandler {
44 use FileInputStreamerTrait;
45 use FileOutputStreamerTrait;
48 * An instance of this class
50 private static $selfInstance = NULL;
53 * Protected constructor
57 private function __construct () {
58 // Call parent constructor
59 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: CONSTRUCTED!');
60 parent::__construct(__CLASS__);
63 self::$selfInstance = $this;
66 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
70 * Creates an instance of this class and prepares the IO system. This is
71 * being done by setting the default file IO class
73 * @return $ioHandlerInstance A prepared instance of FilIoHandler
75 public static final function createFileIoHandler () {
77 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: CALLED!');
78 $ioHandlerInstance = new FileIoHandler();
80 // Set the *real* file IO instances (both the same)
81 $ioHandlerInstance->setInputStreamerInstance(ObjectFactory::createObjectByConfiguredName('file_input_class'));
82 $ioHandlerInstance->setOutputStreamerInstance(ObjectFactory::createObjectByConfiguredName('file_output_class'));
85 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-IO-HANDLER: ioHandlerInstance=%s - EXIT!', $ioHandlerInstance->__toString()));
86 return $ioHandlerInstance;
90 * Getter for an instance of this class
92 * @return $selfInstance An instance of this class
94 public static final function getSelfInstance () {
96 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-IO-HANDLER: Returning self::selfInstance[]=%s - EXIT!', gettype(self::$selfInstance)));
97 return self::$selfInstance;
101 * Saves streamed (that are mostly serialized objects) data to files or
104 * @param $infoInstance An instance of a SplFileInfo class
105 * @param $dataArray Array containing the compressor's extension and streamed data
107 * @throws UnsupportedOperationException If this method is called
109 public function saveFile (SplFileInfo $infoInstance, array $dataArray) {
110 // Trace message for logging parameters
111 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-IO-HANDLER: infoInstance.pathname=%s,dataArray()=%d - CALLED!', $infoInstance->getPathname(), count($dataArray)));
112 throw new UnsupportedOperationException([$this, __FUNCTION__], FrameworkInterface::EXCEPTION_UNSPPORTED_OPERATION);
116 * Saves a file with data by using the current output stream
118 * @param $infoInstance An instance of a SplFileInfo class
119 * @param $dataStream File data stream
120 * @param $objectInstance An instance of a FrameworkInterface class (default: NULL)
122 * @throws InvalidArgumentException If a parameter has an invalid value
124 public function saveStreamToFile (SplFileInfo $infoInstance, string $dataStream, FrameworkInterface $objectInstance = NULL) {
126 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-IO-HANDLER: infoInstance=%s,dataStream()=%d,objectInstance[]=%s - CALLED!', $infoInstance->__toString(), strlen($dataStream), gettype($objectInstance)));
127 if (empty($dataStream)) {
129 throw new InvalidArgumentException('Parameter "dataStream" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
132 // Default is this array
133 $className = $this->__toString();
135 // Is the object instance set?
136 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('FILE-IO-HANDLER: className=%s - BEFORE!', $className));
137 if ($objectInstance instanceof FrameworkInterface) {
139 $className = $objectInstance->__toString();
142 // Send the infoInstance and data array to the output handler
143 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('FILE-IO-HANDLER: className=%s - AFTER!', $className));
144 $this->getOutputStreamerInstance()->saveFile($infoInstance, [
150 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
153 /** Loads data from a file over the input handler
155 * @param $infoInstance An instance of a SplFileInfo class
156 * @return $array Array with the file contents
158 public function loadFileContents (SplFileInfo $infoInstance) {
159 // Read from the input handler
160 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-IO-HANDLER: infoInstance=%s - CALLED!', $infoInstance->__toString()));
161 return $this->getInputStreamerInstance()->loadFileContents($infoInstance);
165 * Determines seek position
167 * @return $seekPosition Current seek position
170 public function determineSeekPosition () {
172 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: CALLED!');
173 DebugMiddleware::getSelfInstance()->partialStub();
176 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
180 * Seek to given offset (default) or other possibilities as fseek() gives.
182 * @param $offset Offset to seek to (or used as "base" for other seeks)
183 * @param $whence Added to offset (default: only use offset to seek to)
185 * @throws InvalidArgumentException If a parameter has an invalid value
187 public function seek (int $offset, int $whence = SEEK_SET) {
189 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-IO-HANDLER: offset=%d,whence=%d - CALLED!', $offset, $whence));
192 throw new InvalidArgumentException('Parameter "offset" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
195 // @TODO Unfinished work
196 DebugMiddleware::getSelfInstance()->partialStub('offset=' . $offset . ',whence=' . $whence);
199 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
205 * @return $size Size (in bytes) of file
208 public function size () {
209 // @TODO: Unfinished method:
210 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: CALLED!');
211 DebugMiddleware::getSelfInstance()->partialStub();
214 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
218 * "Getter" for seek position
220 * @return $seekPosition Current seek position
223 public function getPosition () {
224 // @TODO: Unfinished method:
225 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: CALLED!');
226 DebugMiddleware::getSelfInstance()->partialStub();
229 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');