<?php
/**
 * Database backend class for storing objects in locally created files.
 *
 * This class serializes objects and saves them to local files.
 *
 * @author		Roland Haeder <webmaster@mxchange.org>
 * @version		0.3.0
 * @copyright	Copyright(c) 2007, 2008 Roland Haeder, this is free software
 * @license		GNU GPL 3.0 or any newer version
 * @link 		http://www.mxchange.org
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
class LocalFileDatabase extends BaseDatabaseFrontend implements DatabaseFrontendInterface {
	/**
	 * Save path for "file database"
	 */
	private $savePath = "";

	/**
	 * The file's extension
	 */
	private $fileExtension = "serialized";

	/**
	 * The last read file's name
	 */
	private $lastFile = "";

	/**
	 * The last read file's content including header information
	 */
	private $lastContents = array();

	/**
	 * The private constructor. Do never instance from outside!
	 * You need to set a local file path. The class will then validate it.
	 *
	 * @return	void
	 */
	private function __construct() {
		// Call parent constructor
		parent::constructor(__CLASS__);

		// Set description
		$this->setPartDescr("Dateidatenbankschicht");

		// Create unique ID
		$this->createUniqueID();

		// Clean up a little
		$this->removeSystemArray();
	}

	/**
	 * Create an object of LocalFileDatabase and set the save path for local files.
	 * This method also validates the given file path.
	 *
	 * @param		$savePath					The local file path string
	 * @param		$ioInstance				The input/output handler. This
	 *									should be FileIOHandler
	 * @return	$dbInstance				An instance of LocalFileDatabase
	 * @throws	SavePathIsEmptyException		If the given save path is an
	 *									empty string
	 * @throws	SavePathIsNoDirectoryException	If the save path is no
	 *										path (e.g. a file)
	 * @throws	SavePathReadProtectedException	If the save path is read-
	 *										protected
	 * @throws	SavePathWriteProtectedException	If the save path is write-
	 *										protected
	 */
	public final static function createLocalFileDatabase ($savePath, FileIOHandler $ioInstance) {
		// Get an instance
		$dbInstance = new LocalFileDatabase();

		if (empty($savePath)) {
			// Empty string
			throw new SavePathIsEmptyException($dbInstance, self::EXCEPTION_UNEXPECTED_EMPTY_STRING);
		} elseif (!is_dir($savePath)) {
			// Is not a dir
			throw new SavePathIsNoDirectoryException($savePath, self::EXCEPTION_INVALID_PATH_NAME);
		} elseif (!is_readable($savePath)) {
			// Path not readable
			throw new SavePathReadProtectedException($savePath, self::EXCEPTION_READ_PROTECED_PATH);
		} elseif (!is_writeable($savePath)) {
			// Path not writeable
			throw new SavePathWriteProtectedException($savePath, self::EXCEPTION_WRITE_PROTECED_PATH);
		}

		// Debug output
		if (defined('DEBUG_DATABASE')) $dbInstance->getDebugInstance()->output(sprintf("[%s:] Es werden lokale Dateien zum Speichern von Objekten verwendet.<br />\n",
			$dbInstance->__toString()
		));

		// Set save path and IO instance
		$dbInstance->setSavePath($savePath);
		$dbInstance->setFileIOInstance($ioInstance);

		// Return database instance
		return $dbInstance;
	}

	/**
	 * Setter for save path
	 *
	 * @param		$savePath		The local save path where we shall put our serialized classes
	 * @return	void
	 */
	public final function setSavePath ($savePath) {
		// Secure string
		$savePath = (string) $savePath;

		// Debug message
		if ((defined('DEBUG_DATABASE')) || (defined('DEBUG_ALL'))) $this->getDebugInstance()->output(sprintf("[%s:] Lokaler Speicherpfad <strong>%s</strong> wird verwendet.<br />\n",
			$this->__toString(),
			$savePath
		));

		// Set save path
		$this->savePath = $savePath;
	}

	/**
	 * Getter for save path
	 *
	 * @return	$savePath		The local save path where we shall put our serialized classes
	 */
	public final function getSavePath () {
		return $this->savePath;
	}

	/**
	 * Saves a given object to the local file system by serializing and
	 * transparently compressing it
	 *
	 * @param		$object				The object we shall save to the local file system
	 * @return	void
	 * @throws	NullPointerException	If the object instance is null
	 * @throws	NoObjectException		If the parameter $object is not
	 *								an object
	 */
	public final function saveObject ($object) {
		// Some tests on the parameter...
		if (is_null($object)) {
			// Is null, throw exception
			throw new NullPointerException($object, self::EXCEPTION_IS_NULL_POINTER);
		} elseif (!is_object($object)) {
			// Is not an object, throw exception
			throw new NoObjectException($object, self::EXCEPTION_IS_NO_OBJECT);
		} elseif (!method_exists($object, '__toString')) {
			// A highly required method was not found... :-(
			throw new MissingMethodException(array($object, '__toString'), self::EXCEPTION_MISSING_METHOD);
		}

		// Debug message
		if ((defined('DEBUG_DATABASE')) || (defined('DEBUG_ALL'))) $this->getDebugInstance()->output(sprintf("[%s:] Das Objekt <strong>%s</strong> soll in eine lokale Datei gespeichert werden.<br />\n",
			$this->__toString(),
			$object->__toString()
		));

		// Get a string containing the serialized object. We cannot exchange
		// $this and $object here because $object does not need to worry
		// about it's limitations... ;-)
		$serialized = $this->serializeObject($object);

		// Debug message
		if ((defined('DEBUG_DATABASE')) || (defined('DEBUG_ALL'))) $this->getDebugInstance()->output(sprintf("[%s:] Das Objekt <strong>%s</strong> ist nach der Serialisierung <strong>%s</strong> Byte gross.<br />\n",
			$this->__toString(),
			$object->__toString(),
			strlen($serialized)
		));

		// Get a path name plus file name and append the extension
		$fqfn = $this->getSavePath() . $object->getPathFileNameFromObject() . "." . $this->getFileExtension();

		// Save the file to disc we don't care here if the path is there,
		// this must be done in later methods.
		$this->getFileIOInstance()->saveFile($fqfn, array($this->getCompressorChannel()->getCompressorExtension(), $serialized));
	}

	/**
	 * Get a serialized string from the given object
	 *
	 * @param		$object		The object we want to serialize and transparently
	 *						compress
	 * @return	$serialized	A string containing the serialzed/compressed object
	 * @see		ObjectLimits	An object holding limition information
	 * @see		SerializationContainer	A special container class for e.g.
	 *								attributes from limited objects
	 */
	private function serializeObject ($object) {
		// If there is no limiter instance we serialize the whole object
		// otherwise only in the limiter object (ObjectLimits) specified
		// attributes summarized in a special container class
		if ($this->getLimitInstance() === null) {
			// Serialize the whole object. This tribble call is the reason
			// why we need a fall-back implementation in CompressorChannel
			// of the methods compressStream() and decompressStream().
			$serialized = $this->getCompressorChannel()->getCompressor()->compressStream(serialize($object));
		} else {
			// Serialize only given attributes in a special container
			$container = SerializationContainer::createSerializationContainer($this->getLimitInstance(), $object);

			// Serialize the container
			$serialized = $this->getCompressorChannel()->getCompressor()->compressStream(serialize($container));
		}

		// Return the serialized object string
		return $serialized;
	}

	/**
	 * Analyses if a unique ID has already been used or not by search in the
	 * local database folder.
	 *
	 * @param		$uniqueID		A unique ID number which shall be checked
	 *						before it will be used
	 * @param		$inConstructor	If we got called in a de/con-structor or
	 *						from somewhere else
	 * @return	$isUnused		true	= The unique ID was not found in the database,
	 *						false = It is already in use by an other object
	 * @throws	NoArrayCreatedException	If explode() fails to create an array
	 * @throws	InvalidArrayCountException	If the array contains less or
	 *									more than two elements
	 */
	public function isUniqueIdUsed ($uniqueID, $inConstructor = false) {
		// Currently not used... ;-)
		$isUsed = false;

		// Split the unique ID up in path and file name
		$pathFile = explode("@", $uniqueID);

		// Are there two elements? Index 0 is the path, 1 the file name + global extension
		if (!is_array($pathFile)) {
			// No array found
			if ($inConstructor) {
				return false;
			} else {
				throw new NoArrayCreatedException(array($this, "pathFile"), self::EXCEPTION_ARRAY_EXPECTED);
			}
		} elseif (count($pathFile) != 2) {
			// Invalid ID returned!
			if ($inConstructor) {
				return false;
			} else {
				throw new InvalidArrayCountException(array($this, "pathFile", count($pathFile), 2), self::EXCEPTION_ARRAY_HAS_INVALID_COUNT);
			}
		}

		// Create full path name
		$pathName = $this->getSavePath() . $pathFile[0];

		// Check if the file is there with a file handler
		if ($inConstructor) {
			// No exceptions in constructors and destructors!
			$dirInstance = FrameworkDirectoryPointer::createFrameworkDirectoryPointer($pathName, true);

			// Has an object being created?
			if (!is_object($dirInstance)) return false;
		} else {
			// Outside a constructor
			try {
				$dirInstance = FrameworkDirectoryPointer::createFrameworkDirectoryPointer($pathName);
			} catch (PathIsNoDirectoryException $e) {
				// Okay, path not found
				return false;
			}
		}

		// Initialize the search loop
		$isValid = false;
		while ($dataFile = $dirInstance->readDirectoryExcept(array(".", ".."))) {
			// Generate FQFN for testing
			$fqfn = sprintf("%s/%s", $pathName, $dataFile);
			$this->setLastFile($fqfn);

			// Get instance for file handler
			$inputHandler = $this->getFileIOInstance();

			// Try to read from it. This makes it sure that the file is
			// readable and a valid database file
			$this->setLastFileContents($inputHandler->loadFileContents($fqfn));

			// Extract filename (= unique ID) from it
			$ID = substr(basename($fqfn), 0, -(strlen($this->getFileExtension()) + 1));

			// Is this the required unique ID?
			if ($ID == $pathFile[1]) {
				// Okay, already in use!
				$isUsed = true;
			}
		}

		// Close the directory handler
		$dirInstance->closeDirectory();

		// Now the same for the file...
		return $isUsed;
	}

	/**
	 * Setter for the last read file
	 *
	 * @param		$fqfn	The FQFN of the last read file
	 * @return	void
	 */
	private final function setLastFile ($fqfn) {
		// Cast string
		$fqfn = (string) $fqfn;
		$this->lastFile = $fqfn;
	}

	/**
	 * Getter for last read file
	 *
	 * @return	$lastFile		The last read file's name with full path
	 */
	public final function getLastFile () {
		return $this->lastFile;
	}

	/**
	 * Setter for contents of the last read file
	 *
	 * @param		$contents		An array with header and data elements
	 * @return	void
	 */
	private final function setLastFileContents ($contents) {
		// Cast array
		$contents = (array) $contents;
		$this->lastContents = $contents;
	}

	/**
	 * Getter for last read file's content as an array
	 *
	 * @return	$lastContent	The array with elements 'header' and 'data'.
	 */
	public final function getLastContents () {
		return $this->lastContents;
	}

	/**
	 * Get cached (last fetched) data from the local file database
	 *
	 * @param		$uniqueID		The ID number for looking up the data
	 * @return	$object		The restored object from the maybe compressed
	 *						serialized data
	 * @throws	MismatchingCompressorsException	If the compressor from
	 *										the loaded file
	 *										mismatches with the
	 *										current used one.
	 * @throws	NullPointerException			If the restored object
	 *										is null
	 * @throws	NoObjectException				If the restored "object"
	 *										is not an object instance
	 * @throws	MissingMethodException			If the required method
	 *										toString() is missing
	 */
	public final function getObjectFromCachedData ($uniqueID) {
		// Get instance for file handler
		$inputHandler = $this->getFileIOInstance();

		// Get last file's name and contents
		$fqfn = $this->repairFQFN($this->getLastFile(), $uniqueID);
		$contents = $this->repairContents($this->getLastContents(), $fqfn);

		// Let's decompress it. First we need the instance
		$compressInstance = $this->getCompressorChannel();

		// Is the compressor's extension the same as the one from the data?
		if ($compressInstance->getCompressorExtension() != $contents['header'][0]) {
			/**
			 * @todo	For now we abort here but later we need to make this a little more dynamic.
			 */
			throw new MismatchingCompressorsException(array($this, $contents['header'][0], $fqfn, $compressInstance->getCompressorExtension()), self::EXCEPTION_MISMATCHING_COMPRESSORS);
		}

		// Decompress the data now
		$serialized = $compressInstance->getCompressor()->decompressStream($contents['data']);

		// And unserialize it...
		$object = unserialize($serialized);

		// This must become a valid object, so let's check it...
		if (is_null($object)) {
			// Is null, throw exception
			throw new NullPointerException($object, self::EXCEPTION_IS_NULL_POINTER);
		} elseif (!is_object($object)) {
			// Is not an object, throw exception
			throw new NoObjectException($object, self::EXCEPTION_IS_NO_OBJECT);
		} elseif (!method_exists($object, '__toString')) {
			// A highly required method was not found... :-(
			throw new MissingMethodException(array($object, '__toString'), self::EXCEPTION_MISSING_METHOD);
		}

		// And return the object
		return $object;
	}

	/**
	 * Private method for re-gathering (repairing) the FQFN
	 *
	 * @param		$fqfn		The current FQFN we shall validate
	 * @param		$uniqueID		The unique ID number
	 * @return	$fqfn		The repaired FQFN when it is empty
	 * @throws	NoArrayCreatedException		If explode() has not
	 *									created an array
	 * @throws	InvalidArrayCountException	If the array count is not
	 *									as the expected
	 */
	private function repairFQFN ($fqfn, $uniqueID) {
		// Cast both strings
		$fqfn     = (string) $fqfn;
		$uniqueID = (string) $uniqueID;

		// Is there pre-cached data available?
		if (empty($fqfn)) {
			// Split the unique ID up in path and file name
			$pathFile = explode("@", $uniqueID);

			// Are there two elements? Index 0 is the path, 1 the file name + global extension
			if (!is_array($pathFile)) {
				// No array found
				throw new NoArrayCreatedException(array($this, "pathFile"), self::EXCEPTION_ARRAY_EXPECTED);
			} elseif (count($pathFile) != 2) {
				// Invalid ID returned!
				throw new InvalidArrayCountException(array($this, "pathFile", count($pathFile), 2), self::EXCEPTION_ARRAY_HAS_INVALID_COUNT);
			}

			// Create full path name
			$pathName = $this->getSavePath() . $pathFile[0];

			// Nothing cached, so let's create a FQFN first
			$fqfn = sprintf("%s/%s.%s", $pathName, $pathFile[1], $this->getFileExtension());
			$this->setLastFile($fqfn);
		}

		// Return repaired FQFN
		return $fqfn;
	}

	/**
	 * Private method for re-gathering the contents of a given file
	 *
	 * @param		$contents		The (maybe) already cached contents as an array
	 * @param		$fqfn		The current FQFN we shall validate
	 * @return	$contents		The repaired contents from the given file
	 */
	private function repairContents ($contents, $fqfn) {
		// Is there some content and header (2 indexes) in?
		if ((!is_array($contents)) || (count($contents) != 2) || (!isset($contents['header'])) || (!isset($contents['data']))) {
			// No content found so load the file again
			$contents = $inputHandler->loadFileContents($fqfn);

			// And remember all data for later usage
			$this->setLastContents($contents);
		}

		// Return the repaired contents
		return $contents;
	}

	/* DUMMY */ public final function loadObject () {}
}

// [EOF]
?>