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\Traits\Streamer\File\Input\FileInputStreamerTrait;
12 use Org\Mxchange\CoreFramework\Traits\Streamer\File\Output\FileOutputStreamerTrait;
15 use \InvalidArgumentException;
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.
22 * @author Roland Haeder <webmaster@shipsimu.org>
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
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.
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.
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/>.
41 class FileIoHandler extends BaseMiddleware implements IoHandler {
43 use FileInputStreamerTrait;
44 use FileOutputStreamerTrait;
47 * An instance of this class
49 private static $selfInstance = NULL;
52 * Protected constructor
56 private function __construct () {
57 // Call parent constructor
58 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: CONSTRUCTED!');
59 parent::__construct(__CLASS__);
62 self::$selfInstance = $this;
65 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
69 * Creates an instance of this class and prepares the IO system. This is
70 * being done by setting the default file IO class
72 * @return $ioHandlerInstance A prepared instance of FilIoHandler
74 public static final function createFileIoHandler () {
76 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: CALLED!');
77 $ioHandlerInstance = new FileIoHandler();
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'));
84 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-IO-HANDLER: ioHandlerInstance=%s - EXIT!', $ioHandlerInstance->__toString()));
85 return $ioHandlerInstance;
89 * Getter for an instance of this class
91 * @return $selfInstance An instance of this class
93 public static final function getSelfInstance () {
95 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-IO-HANDLER: Returning self::selfInstance[]=%s - EXIT!', gettype(self::$selfInstance)));
96 return self::$selfInstance;
100 * Saves streamed (that are mostly serialized objects) data to files or
103 * @param $infoInstance An instance of a SplFileInfo class
104 * @param $dataArray Array containing the compressor's extension and streamed data
106 * @throws UnsupportedOperationException If this method is called
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);
115 * Saves a file with data by using the current output stream
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)
121 * @throws InvalidArgumentException If a parameter has an invalid value
123 public function saveStreamToFile (SplFileInfo $infoInstance, string $dataStream, FrameworkInterface $objectInstance = NULL) {
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)) {
128 throw new InvalidArgumentException('Parameter "dataStream" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
131 // Default is this array
132 $className = $this->__toString();
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) {
138 $className = $objectInstance->__toString();
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, [
149 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
152 /** Loads data from a file over the input handler
154 * @param $infoInstance An instance of a SplFileInfo class
155 * @return $array Array with the file contents
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);
164 * Determines seek position
166 * @return $seekPosition Current seek position
169 public function determineSeekPosition () {
171 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: CALLED!');
172 $this->partialStub();
175 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
179 * Seek to given offset (default) or other possibilities as fseek() gives.
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)
184 * @throws InvalidArgumentException If a parameter has an invalid value
186 public function seek (int $offset, int $whence = SEEK_SET) {
188 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('FILE-IO-HANDLER: offset=%d,whence=%d - CALLED!', $offset, $whence));
191 throw new InvalidArgumentException('Parameter "offset" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
194 // @TODO Unfinished work
195 $this->partialStub('offset=' . $offset . ',whence=' . $whence);
198 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
204 * @return $size Size (in bytes) of file
207 public function size () {
209 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: CALLED!');
211 // @TODO: Unfinished method:
212 $this->partialStub();
215 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');
219 * "Getter" for seek position
221 * @return $seekPosition Current seek position
224 public function getPosition () {
226 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: CALLED!');
228 // @TODO: Unfinished method:
229 $this->partialStub();
232 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('FILE-IO-HANDLER: EXIT!');