3 * An interface for distributed hash tables for nodes
5 * @author Roland Haeder <webmaster@shipsimu.org>
7 * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2012 Hub Developer Team
8 * @license GNU GPL 3.0 or any newer version
9 * @link http://www.shipsimu.org
11 * This program is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation, either version 3 of the License, or
14 * (at your option) any later version.
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU General Public License for more details.
21 * You should have received a copy of the GNU General Public License
22 * along with this program. If not, see <http://www.gnu.org/licenses/>.
24 interface NodeDhtWrapper extends DatabaseWrapper {
26 * Getter for result instance for unpublished entries
28 * @return $unpublishedEntriesInstance Result instance
30 function getUnpublishedEntriesInstance ();
33 * Checks whether the local (*this*) node is registered in the DHT by
34 * checking if the external ip/port is found.
36 * @return $isRegistered Whether *this* node is registered in the DHT
38 function isLocalNodeRegistered ();
41 * Registeres the local (*this*) node with its data in the DHT.
45 function registerLocalNode ();
48 * Updates local (*this*) node data in DHT, this is but not limited to the
49 * session id, ip number (and/or hostname) and port number.
53 function updateLocalNode ();
56 * Finds a node locally by given session id
58 * @param $sessionId Session id to lookup
59 * @return $nodeData Node data array
61 function findNodeLocalBySessionId ($sessionId);
64 * Registeres a node by given message data.
66 * @param $messageData An array of all message data
67 * @param $handlerInstance An instance of a Handleable class
70 function registerNodeByMessageData (array $messageData, Handleable $handlerInstance);
73 * Updates an existing entry in node list
75 * @param $messageData An array of all message data
76 * @param $handlerInstance An instance of a Handleable class
77 * @param $searchInstance An instance of LocalSearchCriteria class
80 function updateNodeByMessageData (array $messageData, Handleable $handlerInstance, LocalSearchCriteria $searchInstance);
83 * Determines whether the given node data is already inserted in the DHT
85 * @param $nodeData An array with valid node data
86 * @return $isRegistered Whether the given node data is already inserted
88 function isNodeRegistered (array $nodeData);
91 * Registers a node with given data in the DHT. If the node is already
92 * registered this method shall throw an exception.
94 * @param $nodeData An array with valid node data
96 * @throws NodeAlreadyRegisteredException If the node is already registered
98 function registerNode (array $nodeData);
101 * Updates a node's entry in the DHT with given data. This will enrich or
102 * just update already exsiting data. If the node is not found this method
103 * shall throw an exception.
105 * @param $nodeData An array with valid node data
107 * @throws NodeDataMissingException If the node's data is missing
109 function updateNode (array $nodeData);
112 * Checks whether there are unpublished entries
114 * @return $hasUnpublished Whether there are unpublished entries
115 * @todo Add minimum/maximum age limitations
117 function hasUnpublishedEntries ();
120 * Initializes publication of DHT entries. This does only prepare
121 * publication. The next step is to pickup such prepared entries and publish
122 * them by uploading to other (recently appeared) DHT members.
125 * @todo Add timestamp to dataset instance
127 function initEntryPublication ();
130 * Removes non-public data from given array.
132 * @param $data An array with possible non-public data that needs to be removed.
133 * @return $data A cleaned up array with only public data.
135 function removeNonPublicDataFromArray (array $data);