<?php
/**
 * An interface for DHTs
 *
 * @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 Distributable extends FrameworkInterface {
	/**
	 * Initializes the distributable hash table (DHT)
	 *
	 * @return	void
	 */
	function initDht ();

	/**
	 * Bootstraps the DHT by sending out a message to all available nodes
	 * (including itself). This step helps the node to get to know more nodes
	 * which can be queried later for object distribution.
	 *
	 * @return	void
	 */
	function bootstrapDht ();

	/**
	 * Updates/refreshes DHT data (e.g. status).
	 *
	 * @return	void
	 */
	function updateDhtData ();

	/**
	 * Checks whether there are unpublished entries
	 *
	 * @return	$hasUnpublished		Whether there are unpublished entries
	 */
	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
	 */
	function initEntryPublication ();

	/**
	 * Checks whether there are entries pending publication
	 *
	 * @return	$isPending	Whether there are entries pending publication
	 */
	function hasEntriesPendingPublication ();

	/**
	 * Publishes next entry found in stack. This method shall also update the
	 * corresponding dabase entry.
	 *
	 * @return	void
	 */
	function publishEntry ();

	/**
	 * Find recipients for given package data
	 *
	 * @param	$packageData	An array of valid package data
	 * @return	$recipients		An indexed array with DHT recipients
	 */
	function findRecipientsByPackageData (array $packageData);

	/**
	 * Whether the DHT has fully bootstrapped (after state 'booting')
	 *
	 * @return	$isFullyBooted	Whether the DHT is fully booted
	 */
	function hasFullyBootstrapped ();
}

// [EOF]
?>