namespace Org\Mxchange\CoreFramework\Iterator\File;
// Import framework stuff
-use Org\Mxchange\CoreFramework\Filesystem\Block;
+use Org\Mxchange\CoreFramework\Filesystem\File\BinaryFile;
use Org\Mxchange\CoreFramework\Iterator\BaseIterator;
use Org\Mxchange\CoreFramework\Iterator\Filesystem\SeekableWritableFileIterator;
+use Org\Mxchange\CoreFramework\Traits\File\BinaryFileTrait;
+
+// Import SPL stuff
+use \BadMethodCallException;
+use \InvalidArgumentException;
/**
* A file iterator
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
class FileIterator extends BaseIterator implements SeekableWritableFileIterator {
- /**
- * An instance of a Block class
- */
- private $blockInstance = NULL;
+ // Load traits
+ use BinaryFileTrait;
/**
* Protected constructor
/**
* Creates an instance of this class
*
- * @param $pointerInstance An instance of a Block class
+ * @param $binaryFileInstance An instance of a BinaryFile class
* @return $iteratorInstance An instance of a Iterator class
*/
- public final static function createFileIterator (Block $blockInstance) {
+ public final static function createFileIterator (BinaryFile $binaryFileInstance) {
// Get new instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: binaryFileInstance=%s - CALLED!', $binaryFileInstance->__toString()));
$iteratorInstance = new FileIterator();
// Set the instance here
- /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('[%s:%d] Setting blockInstance=%s ...', __METHOD__, __LINE__, $blockInstance->__toString()));
- $iteratorInstance->setBlockInstance($blockInstance);
+ $iteratorInstance->setBinaryFileInstance($binaryFileInstance);
// Return the prepared instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: iteratorInstance=%s - EXIT!', $iteratorInstance->__toString()));
return $iteratorInstance;
}
- /**
- * Setter for Block instance
- *
- * @param $blockInstance An instance of an Block class
- * @return void
- */
- protected final function setBlockInstance (Block $blockInstance) {
- $this->blockInstance = $blockInstance;
- }
-
- /**
- * Getter for Block instance
- *
- * @return $blockInstance An instance of an Block class
- */
- public final function getBlockInstance () {
- return $this->blockInstance;
- }
-
/**
* Gets currently read data
*
* @return $current Currently read data
+ * @throws BadMethodCallException If valid() is FALSE
*/
public function current () {
- // Call block instance
- return $this->getBlockInstance()->current();
+ // Is condition given?
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ if (!$this->valid()) {
+ // Throw BMCE
+ throw new BadMethodCallException('Current key cannot be valid, forgot to invoke valid()?');
+ }
+
+ // Call file instance
+ $current = $this->getBinaryFileInstance()->current();
+
+ // Return it
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: current[]=%s - EXIT!', gettype($current)));
+ return $current;
}
/**
* Gets current seek position ("key").
*
* @return $key Current key in iteration
+ * @throws BadMethodCallException If valid() is FALSE
*/
public function key () {
- // Return it
- return $this->getBlockInstance()->determineSeekPosition();
+ // Is condition given?
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ if (!$this->valid()) {
+ // Throw BMCE
+ throw new BadMethodCallException('Current key cannot be valid, forgot to invoke valid()?');
+ }
+
+ // Get key from file instance
+ $key = $this->getBinaryFileInstance()->determineSeekPosition();
+
+ // Return key
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: key[%s]=%s - EXIT!', gettype($key), $key));
+ return $key;
}
/**
- * Advances to next "block" of bytes
+ * Advances to next "file" of bytes
*
* @return void
*/
public function next () {
- // Call block instance
- $this->getBlockInstance()->next();
+ // Call file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ $this->getBinaryFileInstance()->next();
+
+ // Trace message
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
}
/**
* @return $status Status of this operation
*/
public function rewind () {
- // Call block instance
- return $this->getBlockInstance()->rewind();
+ // Call file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ $this->getBinaryFileInstance()->rewind();
+
+ // Trace message
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
}
/**
* @return $isValid Whether the next entry is valid
*/
public function valid () {
- // Call block instance
- return $this->getBlockInstance()->valid();
+ // Call file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ $isValid = $this->getBinaryFileInstance()->valid();
+
+ // Return flag
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: isValid=%d - EXIT!', intval($isValid)));
+ return $isValid;
}
/**
* Seeks to given position
*
* @param $seekPosition Seek position in file
+ * @param $whence Added to offset (default: only use offset to seek to)
* @return $status Status of this operation
+ * @throws InvalidArgumentException If a parameter is not valid
*/
- public function seek ($seekPosition) {
- // Call block instance
- return $this->getBlockInstance()->seek($seekPosition);
+ public function seek (int $seekPosition, int $whence = SEEK_SET) {
+ // Validate parameter
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: seekPosition=%d,whence=%d - CALLED!', $seekPosition, $whence));
+ if ($seekPosition < 0) {
+ // Throw IAE
+ throw new InvalidArgumentException(sprintf('seekPosition=%d is not valid', $seekPosition));
+ }
+
+ // Call file instance
+ $status = $this->getBinaryFileInstance()->seek($seekPosition, $whence);
+
+ // Return status
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: status=%d - EXIT!', intval($status)));
+ return $status;
}
/**
* @return $size Size (in bytes) of file
*/
public function size () {
- // Call the block object
- $size = $this->getBlockInstance()->size();
+ // Call the file object
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ $size = $this->getBinaryFileInstance()->size();
- // Return result
+ // Return size
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: size=%d - EXIT!', $size));
return $size;
}
* @param $bytes Amount of bytes to read
* @return $data Data read from file
*/
- public function read ($bytes = NULL) {
- // Call block instance
- return $this->getBlockInstance()->read($bytes);
+ public function read (int $bytes = 0) {
+ // Validate parameter
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: bytes=%d - CALLED!', $bytes));
+ if ($bytes < 0) {
+ // Throw IAE
+ throw new InvalidArgumentException(sprintf('bytes=%d is not valid', $bytes));
+ }
+
+ // Call file instance
+ $data = $this->getBinaryFileInstance()->read($bytes);
+
+ // Return data
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: data[]=%s - EXIT!', gettype($data)));
+ return $data;
}
/**
*
* @return void
*/
- public function analyzeFile () {
- // Just call the block instance
- $this->getBlockInstance()->analyzeFile();
+ public function analyzeFileStructure () {
+ // Just call the file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ $this->getBinaryFileInstance()->analyzeFileStructure();
+
+ // Trace message
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
}
/**
* @return $isInitialized Whether the file header is initialized
*/
public function isFileHeaderInitialized () {
- // Just call the block instance
- return $this->getBlockInstance()->isFileHeaderInitialized();
+ // Just call the file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ $isInitialized = $this->getBinaryFileInstance()->isFileHeaderInitialized();
+
+ // Return flag
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: isInitialized=%d - EXIT!', intval($isInitialized)));
+ return $isInitialized;
}
/**
* @return void
*/
public function createFileHeader () {
- // Just call the block instance
- $this->getBlockInstance()->createFileHeader();
+ // Just call the file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ $this->getBinaryFileInstance()->createFileHeader();
+
+ // Trace message
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
}
/**
*
* @param $type Type of the file
* @return void
+ * @throws InvalidArgumentException If a parameter is not valid
*/
- public function preAllocateFile ($type) {
- // Just call the block instance
- $this->getBlockInstance()->preAllocateFile($type);
+ public function preAllocateFile (string $type) {
+ // Validate parameter
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: type=%s - CALLED!', $type));
+ if (empty($type)) {
+ // Throw IAE
+ throw new InvalidArgumentException('Parameter "type" is empty');
+ }
+
+ // Just call the file instance
+ $this->getBinaryFileInstance()->preAllocateFile($type);
+
+ // Trace message
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
}
/**
* 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
- * analyzeFile() instead of this method.
+ * analyzeFileStructure() instead of this method.
*
* @return void
*/
public function initCountersGapsArray () {
- // Call block instance
- $this->getBlockInstance()->initCountersGapsArray();
+ // Call file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ $this->getBinaryFileInstance()->initCountersGapsArray();
+
+ // Trace message
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
}
/**
* @return $totalEntries Size of file header
*/
public final function getHeaderSize () {
- // Call block instance
- return $this->getBlockInstance()->getHeaderSize();
+ // Call file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ $size = $this->getBinaryFileInstance()->getHeaderSize();
+
+ // Return size
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: size=%d - EXIT!', $size));
+ return $size;
}
/**
* @param $headerSize Size of file header
* @return void
*/
- public final function setHeaderSize ($headerSize) {
- // Call block instance
- $this->getBlockInstance()->setHeaderSize($headerSize);
+ public final function setHeaderSize (int $headerSize) {
+ // Call file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: headerSize=%d - CALLED!', $headerSize));
+ $this->getBinaryFileInstance()->setHeaderSize($headerSize);
+
+ // Trace message
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
}
/**
* Getter for header array
*
- * @return $totalEntries Size of file header
+ * @return $header Header array
*/
public final function getHeader () {
- // Call block instance
- return $this->getBlockInstance()->getHeader();
+ // Call file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ $header = $this->getBinaryFileInstance()->getHeader();
+
+ // Return it
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: header()=%d - EXIT!', count($header)));
+ return $header;
}
/**
* @return void
*/
public final function setHeader (array $header) {
- // Call block instance
- $this->getBlockInstance()->setHeader($header);
+ // Call file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: header()=%d - CALLED!', count($header)));
+ $this->getBinaryFileInstance()->setHeader($header);
+
+ // Trace message
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
}
/**
* @return void
*/
public function updateSeekPosition () {
- // Call block instance
- $this->getBlockInstance()->updateSeekPosition();
+ // Call file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ $this->getBinaryFileInstance()->updateSeekPosition();
+
+ // Trace message
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
}
/**
* @return $totalEntries Total entries in this file
*/
public final function getCounter () {
- // Call block instance
- return $this->getBlockInstance()->getCounter();
+ // Call file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ $counter = $this->getBinaryFileInstance()->getCounter();
+
+ // Return counter
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: counter=%d - EXIT!', $counter));
+ return $counter;
}
/**
* @return $fileSize Size of currently loaded file
*/
public function getFileSize () {
- // Call block instance
- return $this->getBlockInstance()->getFileSize();
+ // Call file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ $size = $this->getBinaryFileInstance()->getFileSize();
+
+ // Return size
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: size=%d - EXIT!', $size));
+ return $size;
}
/**
* @param $data Data to be written
* @param $flushHeader Whether to flush the header (default: flush)
* @return void
+ * @throws InvalidArgumentException If a parameter is not valid
*/
- public function writeData ($seekPosition, $data, $flushHeader = true) {
- // Call block instance
- $this->getBlockInstance()->writeData($seekPosition, $data, $flushHeader);
+ public function writeData (int $seekPosition, string $data, bool $flushHeader = true) {
+ // Validate parameter
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: seekPosition=%d,data(%d)=%s,flushHeader=%d - CALLED!', $seekPosition, strlen($data), $data, intval($flushHeader)));
+ if ($seekPosition < 0) {
+ // Throw IAE
+ throw new InvalidArgumentException(sprintf('seekPosition=%d is not valid', $seekPosition));
+ } elseif (empty($data)) {
+ // Throw it again
+ throw new InvalidArgumentException('Parameter "data" is empty');
+ }
+
+ // Call file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: Calling this->binaryFileInstance->writeData(%d,data()=%d,%d) ...', $seekPosition, strlen($data), intval($flushHeader)));
+ $this->getBinaryFileInstance()->writeData($seekPosition, $data, $flushHeader);
+
+ // Trace message
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: EXIT!');
+ }
+
+ /**
+ * 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 InvalidArgumentException If a parameter is not valid
+ */
+ public function writeAtPosition (int $seekPosition, string $dataStream) {
+ // Validate parameter
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: seekPosition=%d,dataStream(%d)=%s - CALLED!', $seekPosition, strlen($dataStream), $dataStream));
+ if ($seekPosition < 0) {
+ // Invalid seek position
+ throw new InvalidArgumentException(sprintf('seekPosition=%d is not valid.', $seekPosition));
+ } elseif (empty($dataStream)) {
+ // Empty dataStream
+ throw new InvalidArgumentException('Parameter "dataStream" is empty');
+ }
+
+ // Call iterated object's method
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: Calling this->binaryFileInstance->writeAtPosition(%d, %s) ...', $seekPosition, $dataStream));
+ $status = $this->getBinaryFileInstance()->writeAtPosition($seekPosition, $dataStream);
+
+ // Return status
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: status[%s]=%d - EXIT!', gettype($status), $status));
+ return $status;
}
/**
* @return $seekPosition Current seek position (stored here in object)
*/
public function getSeekPosition () {
- // Call block instance
- return $this->getBlockInstance()->getSeekPosition();
+ // Call file instance
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('FILE-ITERATOR: CALLED!');
+ $seekPosition = $this->getBinaryFileInstance()->getSeekPosition();
+
+ // Return position
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: seekPosition[%s]=%d - EXIT!', gettype($seekPosition), $seekPosition));
+ return $seekPosition;
}
/**
* @param $groupId Group identifier
* @param $value Value to be added to the stack
* @return $data Hash and gap position
+ * @throws InvalidArgumentException If a parameter is not valid
*/
- public function writeValueToFile ($groupId, $value) {
- // Call block instance
- return $this->getBlockInstance()->writeValueToFile($groupId, $value);
+ public function writeValueToFile (string $groupId, $value) {
+ // Validate parameter
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: groupId=%s,value[]=%s - CALLED!', $groupId, gettype($value)));
+ if (empty($groupId)) {
+ // Throw IAE
+ throw new InvalidArgumentException('Parameter "groupId" is empty');
+ } elseif (is_resource($value) || is_object($value)) {
+ // Resources and objects are nothing for file-based indexes (mostly)
+ throw new InvalidArgumentException(sprintf('value[]=%s is not supported by file-based indexes', gettype($value)));
+ }
+
+ // Call file instance
+ $data = $this->getBinaryFileInstance()->writeValueToFile($groupId, $value);
+
+ // Return data
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: data[]=%s - EXIT!', gettype($data)));
+ return $data;
}
/**
* @param $encoded Encoded value to be written to the file
* @return $data Gap position and length of the raw data
*/
- public function writeDataToFreeGap ($groupId, $hash, $encoded) {
- // Call block instance
- return $this->getBlockInstance()->writeDataToFreeGap($groupId, $hash, $encoded);
+ public function writeDataToFreeGap (string $groupId, string $hash, string $encoded) {
+ // Validate parameter
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: groupId=%s,hash=%s,encoded(%d)=%s - CALLED!', $groupId, $hash, strlen($encoded), $encoded));
+
+ // Call file instance
+ $data = $this->getBinaryFileInstance()->writeDataToFreeGap($groupId, $hash, $encoded);
+
+ // Return data
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: data[]=%s - EXIT!', gettype($data)));
+ return $data;
}
/**
*
* @param $length Length of raw data
* @return $seekPosition Found next gap's seek position
+ * @throws InvalidArgumentException If a parameter is invalid
*/
- public function searchNextGap ($length) {
- // Call block instance
- print $this->getBlockInstance()->__toString() . PHP_EOL;
- return $this->getBlockInstance()->searchNextGap($length);
+ public function searchNextGap (int $length) {
+ // Validate parameter
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: length=%d - CALLED!', $length));
+ if ($length <= 0) {
+ // Throw IAE
+ throw new InvalidArgumentException(sprintf('length=%d is not valid', $length));
+ }
+
+ // Call file instance
+ $seekPosition = $this->getBinaryFileInstance()->searchNextGap($length);
+
+ // Return position
+ //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('FILE-ITERATOR: seekPosition[%s]=%d - EXIT!', gettype($seekPosition), $seekPosition));
+ return $seekPosition;
}
}
projects / core.git / blobdiff