<?php
/**
 * An interface for distributed hash tables for nodes
 *
 * @author		Roland Haeder <webmaster@shipsimu.org>
 * @version		0.0.0
 * @copyright	Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2012 Hub Developer Team
 * @license		GNU GPL 3.0 or any newer version
 * @link		http://www.shipsimu.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/>.
 */
interface NodeDhtWrapper extends DatabaseWrapper {
	/**
	 * Static getter for an array of all DHT database entries
	 *
	 * @return	$elements	All elements for the DHT dabase
	 */
	static function getAllElements ();

	/**
	 * Getter for result instance for unpublished entries
	 *
	 * @return	$unpublishedEntriesInstance		Result instance
	 */
	function getUnpublishedEntriesInstance ();

	/**
	 * Checks whether the local (*this*) node is registered in the DHT by
	 * checking if the external ip/port is found.
	 *
	 * @return	$isRegistered	Whether *this* node is registered in the DHT
	 */
	function isLocalNodeRegistered ();

	/**
	 * Registeres the local (*this*) node with its data in the DHT.
	 *
	 * @return	void
	 */
	function registerLocalNode ();

	/**
	 * Updates local (*this*) node data in DHT, this is but not limited to the
	 * session id, ip number (and/or hostname) and port number.
	 *
	 * @return	void
	 */
	function updateLocalNode ();

	/**
	 * Finds a node locally by given session id
	 *
	 * @param	$sessionId	Session id to lookup
	 * @return	$nodeData	Node data array
	 */
	function findNodeLocalBySessionId ($sessionId);

	/**
	 * Registeres a node by given message data.
	 *
	 * @param	$messageData		An array of all message data
	 * @param	$handlerInstance	An instance of a Handleable class
	 * @return	void
	 */
	function registerNodeByMessageData (array $messageData, Handleable $handlerInstance);

	/**
	 * Updates an existing entry in node list
	 *
	 * @param	$messageData		An array of all message data
	 * @param	$handlerInstance	An instance of a Handleable class
	 * @param	$searchInstance		An instance of LocalSearchCriteria class
	 * @return	void
	 */
	function updateNodeByMessageData (array $messageData, Handleable $handlerInstance, LocalSearchCriteria $searchInstance);

	/**
	 * Determines whether the given node data is already inserted in the DHT
	 *
	 * @param	$nodeData		An array with valid node data
	 * @return	$isRegistered	Whether the given node data is already inserted
	 */
	function isNodeRegistered (array $nodeData);

	/**
	 * Registers a node with given data in the DHT. If the node is already
	 * registered this method shall throw an exception.
	 *
	 * @param	$nodeData	An array with valid node data
	 * @return	void
	 * @throws	NodeAlreadyRegisteredException	If the node is already registered
	 */
	function registerNode (array $nodeData);

	/**
	 * Updates a node's entry in the DHT with given data. This will enrich or
	 * just update already exsiting data. If the node is not found this method
	 * shall throw an exception.
	 *
	 * @param	$nodeData	An array with valid node data
	 * @return	void
	 * @throws	NodeDataMissingException	If the node's data is missing
	 */
	function updateNode (array $nodeData);

	/**
	 * Checks whether there are unpublished entries
	 *
	 * @return	$hasUnpublished		Whether there are unpublished entries
	 * @todo	Add minimum/maximum age limitations
	 */
	function hasUnpublishedEntries ();

	/**
	 * Initializes publication of DHT entries. This does only prepare
	 * publication. The next step is to pickup such prepared entries and publish
	 * them by uploading to other (recently appeared) DHT members.
	 *
	 * @return	void
	 * @todo	Add timestamp to dataset instance
	 */
	function initEntryPublication ();

	/**
	 * Removes non-data from given array.
	 *
	 * @param	$data	An array with possible non-data that needs to be removed.
	 * @return	$data	A cleaned up array with only data.
	 */
	function removeNonPublicDataFromArray(array $data);

	/**
	 * Find recipients for given package data and returns it as a result instance
	 *
	 * @param	$packageData	An array of valid package data
	 * @return	$recipients		An indexed array with DHT recipients
	 */
	function getResultFromExcludedSender (array $packageData);

	/**
	 * Find recopients by given key/value pair. First look for the key and if it
	 * matches, compare the value.
	 *
	 * @param	$key			Key to look for
	 * @param	$value			Value to compare if key matches
	 * @return	$recipients		An indexed array with DHT recipients
	 */
	function getResultFromKeyValue ($key, $value);

	/**
	 * Enable DHT bootstrap request acceptance for local node
	 *
	 * @return	void
	 */
	function enableAcceptDhtBootstrap ();
}

// [EOF]
?>