<?php
/**
 * A PackageAssembler class to assemble a package content stream fragemented
 * by PackageFragmenter back to a raw package data array.
 *
 * @author		Roland Haeder <webmaster@ship-simu.org>
 * @version		0.0.0
 * @copyright	Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2011 Hub Developer Team
 * @license		GNU GPL 3.0 or any newer version
 * @link		http://www.ship-simu.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 PackageAssembler extends BaseHubSystem implements Assembler, Registerable {
	/**
	 * Protected constructor
	 *
	 * @return	void
	 */
	protected function __construct () {
		// Call parent constructor
		parent::__construct(__CLASS__);
	}

	/**
	 * Creates an instance of this class
	 *
	 * @return	$assemblerInstance	An instance of an Assembler class
	 */
	public static final function createPackageAssembler () {
		// Get new instance
		$assemblerInstance = new PackageAssembler();

		// Return the prepared instance
		return $assemblerInstance;
	}

	/**
	 * Assembles the content from $packageContent. This method does only
	 * initialize the whole process by creating a call-back which will then
	 * itself (99.9% of all cases) "explode" the decoded data stream and add
	 * it to a chunk assembler queue.
	 *
	 * If the call-back method or this would attempt to assemble the package
	 * chunks and (maybe) re-request some chunks from the sender, this would
	 * take to much time and therefore slow down this node again.
	 *
	 * @param	$packageContent		An array with two elements: 'decoded_data' and 'error_code'
	 * @return	void
	 * @throws	UnsupportedPackageCodeHandlerException	If the package code handler is not implemented
	 */
	public function chunkPackageContent (array $packageContent) {
		// Validate the package content array again
		assert(
			(isset($packageContent[BaseRawDataHandler::PACKAGE_DECODED_DATA])) &&
			(isset($packageContent[BaseRawDataHandler::PACKAGE_ERROR_CODE]))
		);

		// Construct call-back name from package error code
		$methodName = 'handlePackageBy' . $this->convertToClassName($packageContent[BaseRawDataHandler::PACKAGE_ERROR_CODE]);

		// Abort if the call-back method is not there
		if (!method_exists($this, $methodName)) {
			// Throw an exception
			throw new UnsupportedPackageCodeHandlerException(array($this, $methodName, $packageContent), BaseListener::EXCEPTION_UNSUPPORTED_PACKAGE_CODE_HANDLER);
		} // END - if

		// Call it back
		call_user_func(array($this, $methodName), $packageContent);
	}

	/**
	 * Call-back handler to handle unhandled packages. This method "explodes"
	 * the string with the chunk separator from PackageFragmenter class, does
	 * some low checks on it and feeds it into another queue for verification
	 * and re-request for bad chunks.
	 *
	 * @param	$packageContent		An array with two elements: 'decoded_data' and 'error_code'
	 * @return	void
	 * @throws	FinalChunkVerificationException		If the final chunk does not start with 'EOP:'
	 */
	private function handlePackageByUnhandledPackage (array $packageContent) {
		/*
		 * "explode" the string from 'decoded_data' with chunk separator to
		 * get an array of chunks. These chunks must then be verified by
		 * their checksums. Also the final chunk must be handled.
		 */
		$chunks = explode(PackageFragmenter::CHUNK_SEPARATOR, $packageContent[BaseRawDataHandler::PACKAGE_DECODED_DATA]);

		// Validate final chunk
		if (!$this->isValidFinalChunk($chunks)) {
			// Last chunk is not valid
			throw new FinalChunkVerificationException(array($this, $chunks), BaseListener::EXCEPTION_FINAL_CHUNK_VERIFICATION);
		} // END - if

		// Now get a chunk handler instance
		$handlerInstance = ChunkHandlerFactory::createChunkHandlerInstance();

		// Add all chunks because the last final chunk is found
		$handlerInstance->addAllChunksWithFinal($chunks);
	}
}

// [EOF]
?>