X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=framework%2Fmain%2Finterfaces%2Fstacker%2Ffile%2Fclass_StackableFile.php;h=36ba3b7b6438ced9bec0e0b14578b3db61166cda;hb=HEAD;hp=20841767886c3489b38dfeb5df4662ecccfc1e55;hpb=8a14c547a7c7ef07bc3d67778aa4008fa17d703f;p=core.git diff --git a/framework/main/interfaces/stacker/file/class_StackableFile.php b/framework/main/interfaces/stacker/file/class_StackableFile.php index 20841767..2a08b75e 100644 --- a/framework/main/interfaces/stacker/file/class_StackableFile.php +++ b/framework/main/interfaces/stacker/file/class_StackableFile.php @@ -1,16 +1,16 @@ * @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 * @@ -28,13 +28,33 @@ use CoreFramework\Stacker\Stackable; * along with this program. If not, see . */ interface StackableFile extends Stackable { + /** + * Magic for this stack + */ + const STACK_MAGIC = 'STACKv0.1'; + + /** + * Name of array index for gap position + */ + const ARRAY_NAME_GAP_POSITION = 'gap'; + + /** + * Name of array index for hash + */ + const ARRAY_NAME_HASH = 'hash'; + + /** + * Name of array index for length of raw data + */ + const ARRAY_NAME_DATA_LENGTH = 'length'; + /** * Seeks to given position * * @param $seekPosition Seek position in file * @return $status Status of this operation */ - function seek ($seekPosition); + function seek (int $seekPosition); /** * Size of file stack @@ -43,4 +63,155 @@ interface StackableFile extends Stackable { */ function size (); + /** + * Reads the stack's file header + * + * @return void + * @todo To hard assertions here, better rewrite them to exceptions + * @throws UnexpectedValueException If header is not proper length + * @throws InvalidMagicException If a bad magic was found + */ + function readStackHeader (); + + /** + * Flushes the file header + * + * @return void + */ + function flushFileHeader (); + + /** + * Determines whether the EOF has been reached + * + * @return $isEndOfFileReached Whether the EOF has been reached + * @throws UnsupportedOperationException This method is not (and maybe never will be) supported + */ + function isEndOfFileReached (); + + /** + * Calculates minimum length for one entry/block + * + * @return $length Minimum length for one entry/block + */ + function calculateMinimumBlockLength (); + + /** + * Initializes counter for valid entries, arrays for damaged entries and + * an array for gap seek positions. If you call this method on your own, + * please re-analyze the file structure. So you are better to call + * analyzeFileStructure() instead of this method. + * + * @return void + * @throws UnsupportedOperationException This method is not (and maybe never will be) supported + */ + function initCountersGapsArray (); + + /** + * Getter for header size + * + * @return $totalEntries Size of file header + * @throws UnsupportedOperationException This method is not (and maybe never will be) supported + */ + function getHeaderSize (); + + /** + * Setter for header size + * + * @param $headerSize Size of file header + * @return void + * @throws UnsupportedOperationException This method is not (and maybe never will be) supported + */ + function setHeaderSize (int $headerSize); + + /** + * Getter for header array + * + * @return $totalEntries Size of file header + * @throws UnsupportedOperationException This method is not (and maybe never will be) supported + */ + function getHeader (); + + /** + * Setter for header + * + * @param $header Array for a file header + * @return void + * @throws UnsupportedOperationException This method is not (and maybe never will be) supported + */ + function setHeader (array $header); + + /** + * Updates seekPosition attribute from file to avoid to much access on file. + * + * @return void + * @throws UnsupportedOperationException This method is not (and maybe never will be) supported + */ + function updateSeekPosition (); + + /** + * Getter for total entries + * + * @return $totalEntries Total entries in this file + * @throws UnsupportedOperationException This method is not (and maybe never will be) supported + */ + function getCounter (); + + /** + * Writes data at given position + * + * @param $seekPosition Seek position + * @param $data Data to be written + * @param $flushHeader Whether to flush the header (default: flush) + * @return void + * @throws UnsupportedOperationException This method is not (and maybe never will be) supported + */ + function writeData (int $seekPosition, string $data, bool $flushHeader = true); + + /** + * Writes at given position by seeking to it. + * + * @param $seekPosition Seek position in file + * @param $dataStream Data to be written + * @return mixed Number of writes bytes or false on error + * @throws UnsupportedOperationException This method is not (and maybe never will be) supported + */ + function writeAtPosition (int $seekPosition, string $dataStream); + + /** + * Writes given value to the file and returns a hash and gap position for it + * + * @param $groupId Group identifier + * @param $value Value to be added to the stack + * @return $data Hash and gap position + * @throws UnsupportedOperationException This method is not (and maybe never will be) supported + */ + function writeValueToFile (string $groupId, $value); + + /** + * Searches for next suitable gap the given length of data can fit in + * including padding bytes. + * + * @param $length Length of raw data + * @return $seekPosition Found next gap's seek position + * @throws UnsupportedOperationException This method is not (and maybe never will be) supported + */ + function searchNextGap (int $length); + + /** + * "Getter" for file size + * + * @return $fileSize Size of currently loaded file + */ + function getFileSize (); + + /** + * Writes given raw data to the file and returns a gap position and length + * + * @param $groupId 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 + */ + function writeDataToFreeGap (string $groupId, string $hash, string $encoded); + }