git.mxchange.org Git - hub.git/blob

   1 <?php
   2 // Own namespace
   3 namespace Org\Shipsimu\Hub\Database\Frontend\Node\Dht;
   4
   5 // Import application-specific stuff
   6 use Org\Shipsimu\Hub\Database\Frontend\BaseHubDatabaseFrontend;
   7 use Org\Shipsimu\Hub\Factory\Node\NodeObjectFactory;
   8 use Org\Shipsimu\Hub\Locator\Node\LocateableNode;
   9 use Org\Shipsimu\Hub\Network\Message\DeliverableMessage;
  10 use Org\Shipsimu\Hub\Network\Package\DeliverablePackage;
  11 use Org\Shipsimu\Hub\Node\BaseHubNode;
  12
  13 // Import framework stuff
  14 use Org\Mxchange\CoreFramework\Bootstrap\FrameworkBootstrap;
  15 use Org\Mxchange\CoreFramework\Criteria\Local\LocalSearchCriteria;
  16 use Org\Mxchange\CoreFramework\Criteria\Storing\StoreableCriteria;
  17 use Org\Mxchange\CoreFramework\Factory\Object\ObjectFactory;
  18 use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
  19 use Org\Mxchange\CoreFramework\Handler\DataSet\HandleableDataSet;
  20 use Org\Mxchange\CoreFramework\Registry\Registerable;
  21 use Org\Mxchange\CoreFramework\Result\Search\SearchableResult;
  22
  23 // Import SPL stuff
  24 use \BadMethodCallException;
  25 use \InvalidArgumentException;
  26
  27 /**
  28  * A database frontend for distributed hash tables
  29  *
  30  * @author              Roland Haeder <webmaster@shipsimu.org>
  31  * @version             0.0.0
  32  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2022 Hub Developer Team
  33  * @license             GNU GPL 3.0 or any newer version
  34  * @link                http://www.shipsimu.org
  35  *
  36  * This program is free software: you can redistribute it and/or modify
  37  * it under the terms of the GNU General Public License as published by
  38  * the Free Software Foundation, either version 3 of the License, or
  39  * (at your option) any later version.
  40  *
  41  * This program is distributed in the hope that it will be useful,
  42  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  43  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  44  * GNU General Public License for more details.
  45  *
  46  * You should have received a copy of the GNU General Public License
  47  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  48  */
  49 class NodeDistributedHashTableDatabaseFrontend extends BaseHubDatabaseFrontend implements NodeDhtFrontend, Registerable {
  50         /**
  51          * "Cached" results for dabase for looking for unpublished entries
  52          */
  53         private $unpublishedEntriesInstance = NULL;
  54
  55         // Constants for database table names
  56         const DB_TABLE_NODE_DHT = 'node_dht';
  57
  58         // Constants for database column names
  59         const DB_COLUMN_NODE_ID            = 'node_id';
  60         const DB_COLUMN_SESSION_ID         = 'session_id';
  61         const DB_COLUMN_EXTERNAL_ADDRESS   = 'external_address';
  62         const DB_COLUMN_PRIVATE_KEY_HASH   = 'private_key_hash';
  63         const DB_COLUMN_NODE_MODE          = 'node_mode';
  64         const DB_COLUMN_ACCEPTED_OBJECTS   = 'accepted_object_types';
  65         const DB_COLUMN_NODE_LIST          = 'node_list';
  66         const DB_COLUMN_PUBLICATION_STATUS = 'publication_status';
  67         const DB_COLUMN_ANSWER_STATUS      = 'answer_status';
  68         const DB_COLUMN_ACCEPT_BOOTSTRAP   = 'accept_bootstrap';
  69
  70         // Publication status'
  71         const PUBLICATION_STATUS_PENDING = 'PENDING';
  72
  73         // Exception codes
  74         const EXCEPTION_NODE_ALREADY_REGISTERED = 0x800;
  75         const EXCEPTION_NODE_NOT_REGISTERED     = 0x801;
  76
  77         /**
  78          * Protected constructor
  79          *
  80          * @return      void
  81          */
  82         private function __construct () {
  83                 // Call parent constructor
  84                 parent::__construct(__CLASS__);
  85         }
  86
  87         /**
  88          * Creates an instance of this database frontend by a provided user class
  89          *
  90          * @return      $frontendInstance       An instance of the created frontend class
  91          */
  92         public static final function createNodeDistributedHashTableDatabaseFrontend () {
  93                 // Get a new instance
  94                 $frontendInstance = new NodeDistributedHashTableDatabaseFrontend();
  95
  96                 // Set (primary!) table name
  97                 $frontendInstance->setTableName(self::DB_TABLE_NODE_DHT);
  98
  99                 // Get node instance
 100                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: Creating node instance ...');
 101                 $nodeInstance = NodeObjectFactory::createNodeInstance();
 102
 103                 // And set it here
 104                 $frontendInstance->setNodeInstance($nodeInstance);
 105
 106                 // Return the instance
 107                 return $frontendInstance;
 108         }
 109
 110         /**
 111          * Static getter for an array of all DHT database entries
 112          *
 113          * @return      $elements       All elements for the DHT dabase
 114          */
 115         public static final function getAllElements () {
 116                 // Create array and ...
 117                 $elements = [
 118                         self::DB_COLUMN_NODE_ID,
 119                         self::DB_COLUMN_SESSION_ID,
 120                         self::DB_COLUMN_EXTERNAL_ADDRESS,
 121                         self::DB_COLUMN_PRIVATE_KEY_HASH,
 122                         self::DB_COLUMN_NODE_MODE,
 123                         self::DB_COLUMN_ACCEPTED_OBJECTS,
 124                         self::DB_COLUMN_NODE_LIST
 125                 ];
 126
 127                 // ... return it
 128                 return $elements;
 129         }
 130
 131         /**
 132          * Prepares a search instance for given node data
 133          *
 134          * @param       $nodeData                       An array with valid node data
 135          * @return      $searchInstance         An instance of a SearchCriteria class
 136          */
 137         private function prepareSearchInstance (array $nodeData) {
 138                 // Assert on array elements
 139                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: CALLED!');
 140                 assert(isset($nodeData[self::DB_COLUMN_NODE_ID]));
 141
 142                 // Get instance
 143                 $searchInstance = ObjectFactory::createObjectByConfiguredName('search_criteria_class');
 144
 145                 // Search for node id and limit it to one entry
 146                 $searchInstance->addCriteria(self::DB_COLUMN_NODE_ID, $nodeData[self::DB_COLUMN_NODE_ID]);
 147                 $searchInstance->setLimit(1);
 148
 149                 // Return it
 150                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: EXIT!');
 151                 return $searchInstance;
 152         }
 153
 154         /**
 155          * Prepares a "local" instance of a StoreableCriteria class with all node
 156          * data for insert/update queries. This data set contains data from *this*
 157          * (local) node.
 158          *
 159          * @return      $dataSetInstance        An instance of a StoreableCriteria class
 160          */
 161         private function prepareLocalDataSetInstance () {
 162                 // Debug message
 163                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: CALLED!');
 164
 165                 // Get request instances
 166                 $requestInstance = FrameworkBootstrap::getRequestInstance();
 167
 168                 // Get a dataset instance
 169                 $dataSetInstance = ObjectFactory::createObjectByConfiguredName('dataset_criteria_class', array(self::DB_TABLE_NODE_DHT));
 170
 171                 // Set the primary key
 172                 $dataSetInstance->setUniqueKey(self::DB_COLUMN_NODE_ID);
 173
 174                 // Get Universal Node Locator and "explode" it
 175                 $locatorInstance = $this->getNodeInstance()->determineUniversalNodeLocator();
 176
 177                 // Get external UNL
 178                 $externalUnl = $locatorInstance->getExternalUnl();
 179
 180                 // Make sure both is valid
 181                 // @TODO Bad check on UNL, better use a proper validator
 182                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: externalUnl=' . $externalUnl);
 183                 assert($externalUnl !== 'invalid');
 184
 185                 // Get an array of all accepted object types
 186                 $objectList = $this->getNodeInstance()->getListFromAcceptedObjectTypes();
 187
 188                 // Make sure this is an array
 189                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: objectList()=' . count($objectList));
 190                 assert(is_array($objectList));
 191
 192                 // Add public node data
 193                 $dataSetInstance->addCriteria(self::DB_COLUMN_NODE_MODE       , $requestInstance->getRequestElement('mode'));
 194                 $dataSetInstance->addCriteria(self::DB_COLUMN_EXTERNAL_ADDRESS, $externalUnl);
 195                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: nodeInstance->nodeId=' . $this->getNodeInstance()->getNodeId());
 196                 $dataSetInstance->addCriteria(self::DB_COLUMN_NODE_ID         , $this->getNodeInstance()->getNodeId());
 197                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: nodeInstance->sessionId=' . $this->getNodeInstance()->getSessionId());
 198                 $dataSetInstance->addCriteria(self::DB_COLUMN_SESSION_ID      , $this->getNodeInstance()->getSessionId());
 199                 $dataSetInstance->addCriteria(self::DB_COLUMN_PRIVATE_KEY_HASH, $this->getNodeInstance()->getNodePrivateKeyHash());
 200                 $dataSetInstance->addCriteria(self::DB_COLUMN_ACCEPTED_OBJECTS, implode(BaseHubNode::OBJECT_LIST_SEPARATOR, $objectList));
 201                 $dataSetInstance->addCriteria(self::DB_COLUMN_ACCEPT_BOOTSTRAP, $this->translateBooleanToYesNo($this->getNodeInstance()->isAcceptingDhtBootstrap()));
 202
 203                 // Return it
 204                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: dataSetInstance=' . $dataSetInstance->__toString() . ' - EXIT!');
 205                 return $dataSetInstance;
 206         }
 207
 208         /**
 209          * Getter for result instance for unpublished entries
 210          *
 211          * @return      $unpublishedEntriesInstance             Result instance
 212          */
 213         public final function getUnpublishedEntriesInstance () {
 214                 return $this->unpublishedEntriesInstance;
 215         }
 216
 217         /**
 218          * Checks whether the local (*this*) node is registered in the DHT by
 219          * checking if the external address is found.
 220          *
 221          * @return      $isRegistered   Whether *this* node is registered in the DHT
 222          */
 223         public function isLocalNodeRegistered () {
 224                 // Get a search criteria instance
 225                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: CALLED!');
 226                 $searchInstance = ObjectFactory::createObjectByConfiguredName('search_criteria_class');
 227
 228                 // Get Universal Node Locator and "explode" it
 229                 $locatorInstance = $this->getNodeInstance()->determineUniversalNodeLocator();
 230
 231                 // Make sure the external address is set and not invalid
 232                 // @TODO Bad check on UNL, better use a proper validator
 233                 $externalUnl = $locatorInstance->getExternalUnl();
 234                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('DHT-FRONTEND: externalUnl=%s', $externalUnl));
 235                 assert($externalUnl != 'invalid');
 236
 237                 // Add Universal Node Locator/node id as criteria
 238                 $searchInstance->addCriteria(self::DB_COLUMN_EXTERNAL_ADDRESS, $externalUnl);
 239                 $searchInstance->addCriteria(self::DB_COLUMN_NODE_ID         , $this->getNodeInstance()->getNodeId());
 240                 $searchInstance->addCriteria(self::DB_COLUMN_SESSION_ID      , $this->getNodeInstance()->getSessionId());
 241                 $searchInstance->setLimit(1);
 242
 243                 // Query database and get a result instance back
 244                 $resultInstance = $this->doSelectByCriteria($searchInstance);
 245
 246                 // Cache result of if there is an entry, valid() will tell us if an entry is there
 247                 $isRegistered = $resultInstance->valid();
 248
 249                 // Return result
 250                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('DHT-FRONTEND: isRegistered=%d - EXIT!', intval($isRegistered)));
 251                 return $isRegistered;
 252         }
 253
 254         /**
 255          * Registeres the local (*this*) node with its data in the DHT.
 256          *
 257          * @return      void
 258          */
 259         public function registerLocalNode () {
 260                 // Debug message
 261                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: CALLED!');
 262
 263                 // Assert to make sure this method is called with no record in DB (the actual backend of the DHT)
 264                 assert(!$this->isLocalNodeRegistered());
 265
 266                 // Get prepared data set instance
 267                 $dataSetInstance = $this->prepareLocalDataSetInstance();
 268
 269                 // "Insert" this dataset instance completely into the database
 270                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: Invoking this->queryInsertDataSet(' . $dataSetInstance->__toString() . ') ...');
 271                 $this->queryInsertDataSet($dataSetInstance);
 272
 273                 // Debug message
 274                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: EXIT!');
 275         }
 276
 277         /**
 278          * Updates local (*this*) node's data in DHT, this is but not limited to the
 279          * session id, ip number (and/or hostname) and port number.
 280          *
 281          * @return      void
 282          * @throws      BadMethodCallException  If node is not locally registered
 283          */
 284         public function updateLocalNode () {
 285                 // Check condition
 286                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: CALLED!');
 287                 if (!$this->isLocalNodeRegistered()) {
 288                         // Not registered but methoded invoked
 289                         throw new BadMethodCallException('Node is not locally registered but method called', FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
 290                 }
 291
 292                 // Get search criteria
 293                 $searchInstance = ObjectFactory::createObjectByConfiguredName('search_criteria_class');
 294
 295                 // Search for node id and limit it to one entry
 296                 $searchInstance->addCriteria(self::DB_COLUMN_NODE_ID, $this->getNodeInstance()->getNodeId());
 297                 $searchInstance->setLimit(1);
 298
 299                 // Get a prepared dataset instance
 300                 $dataSetInstance = $this->prepareLocalDataSetInstance();
 301
 302                 // Set search instance
 303                 $dataSetInstance->setSearchInstance($searchInstance);
 304
 305                 // Update DHT database record
 306                 $this->queryUpdateDataSet($dataSetInstance);
 307
 308                 // Debug message
 309                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: EXIT!');
 310         }
 311
 312         /**
 313          * Finds a node locally by given session id
 314          *
 315          * @param       $sessionId      Session id to lookup
 316          * @return      $resultInstance         An instance of a SearchableResult class
 317          * @throws      InvalidArgumentException        If parameter $sessionId is not valid
 318          */
 319         public function findNodeLocalBySessionId (string $sessionId) {
 320                 // Validate parameter
 321                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('DHT-FRONTEND: sessionId=%s - CALLED!', $sessionId));
 322                 if (empty($sessionId)) {
 323                         // Cannot be empty
 324                         throw new InvalidArgumentException('Parameter "sessionId" is empty.');
 325                 }
 326
 327                 // Get search criteria
 328                 $searchInstance = ObjectFactory::createObjectByConfiguredName('search_criteria_class');
 329
 330                 // Search for session id and limit it to one entry
 331                 $searchInstance->addCriteria(self::DB_COLUMN_SESSION_ID, $sessionId);
 332                 $searchInstance->setLimit(1);
 333
 334                 // Query database and get a result instance back
 335                 $resultInstance = $this->doSelectByCriteria($searchInstance);
 336
 337                 // Return result instance
 338                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('DHT-FRONTEND: resultInstance->valid()=%d - EXIT!', intval($resultInstance->valid())));
 339                 return $resultInstance;
 340         }
 341
 342         /**
 343          * Finds a node locally by given UNL instance
 344          *
 345          * @param       $locatorInstance        An instance of a LocateableNode class
 346          * @return      $resultInstance         An instance of a SearchableResult class
 347          */
 348         public function findNodeLocalByLocatorInstance (LocateableNode $locatorInstance) {
 349                 // Get search criteria
 350                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('DHT-FRONTEND: locatorInstance=%s - CALLED!', $locatorInstance->__toString()));
 351                 $searchInstance = ObjectFactory::createObjectByConfiguredName('search_criteria_class');
 352
 353                 // Search for session id and limit it to one entry
 354                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('DHT-FRONTEND: externalUnl=%s', $locatorInstance->getExternalUnl()));
 355                 $searchInstance->addCriteria(self::DB_COLUMN_EXTERNAL_ADDRESS, $locatorInstance->getExternalUnl());
 356                 $searchInstance->setLimit(1);
 357
 358                 // Query database and get a result instance back
 359                 $resultInstance = $this->doSelectByCriteria($searchInstance);
 360
 361                 // Return result instance
 362                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('DHT-FRONTEND: resultInstance->valid()=%d - EXIT!', intval($resultInstance->valid())));
 363                 return $resultInstance;
 364         }
 365
 366         /**
 367          * Registeres a node by given message data.
 368          *
 369          * @param       $messageInstance        An instance of a DeliverableMessage class
 370          * @param       $handlerInstance        An instance of a HandleableDataSet class
 371          * @return      void
 372          */
 373         public function registerNodeByMessageInstance (DeliverableMessage $messageInstance, HandleableDataSet $handlerInstance) {
 374                 // Get a data set instance
 375                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: handlerInstance=' . $handlerInstance->__toString() . ' - CALLED!');
 376                 $dataSetInstance = ObjectFactory::createObjectByConfiguredName('dataset_criteria_class', array(self::DB_TABLE_NODE_DHT));
 377
 378                 // Set primary key (session id)
 379                 $dataSetInstance->setUniqueKey(self::DB_COLUMN_SESSION_ID);
 380
 381                 // Add all array elements
 382                 $handlerInstance->addArrayToDataSet($dataSetInstance, $messageInstance);
 383
 384                 // Remove 'node_list'
 385                 $dataSetInstance->unsetCriteria(self::DB_COLUMN_NODE_LIST);
 386
 387                 // Run the "INSERT" query
 388                 $this->queryInsertDataSet($dataSetInstance);
 389
 390                 // Trace message
 391                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND - EXIT!');
 392         }
 393
 394         /**
 395          * Updates an existing entry in node list
 396          *
 397          * @param       $messageInstance        An instance of a DeliverableMessage class
 398          * @param       $handlerInstance        An instance of a HandleableDataSet class
 399          * @param       $searchInstance         An instance of LocalSearchCriteria class
 400          * @return      void
 401          */
 402         public function updateNodeByMessageInstance (DeliverableMessage $messageInstance, HandleableDataSet $handlerInstance, LocalSearchCriteria $searchInstance) {
 403                 // Debug message
 404                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: CALLED!');
 405
 406                 // Get a data set instance
 407                 $dataSetInstance = ObjectFactory::createObjectByConfiguredName('dataset_criteria_class', array(self::DB_TABLE_NODE_DHT));
 408
 409                 // Add search instance
 410                 $dataSetInstance->setSearchInstance($searchInstance);
 411
 412                 // Set primary key (session id)
 413                 $dataSetInstance->setUniqueKey(self::DB_COLUMN_SESSION_ID);
 414
 415                 // Add all array elements
 416                 $handlerInstance->addArrayToDataSet($dataSetInstance, $messageInstance);
 417
 418                 // Remove 'node_list'
 419                 $dataSetInstance->unsetCriteria(self::DB_COLUMN_NODE_LIST);
 420
 421                 // Run the "UPDATE" query
 422                 $this->queryUpdateDataSet($dataSetInstance);
 423
 424                 // Debug message
 425                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: EXIT!');
 426         }
 427
 428         /**
 429          * Determines whether the given node data is already inserted in the DHT
 430          *
 431          * @param       $nodeData               An array with valid node data
 432          * @return      $isRegistered   Whether the given node data is already inserted
 433          */
 434         public function isNodeRegistered (array $nodeData) {
 435                 // Debug message
 436                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: CALLED!');
 437
 438                 // Assert on array elements
 439                 assert(isset($nodeData[self::DB_COLUMN_NODE_ID]));
 440
 441                 // Debug message
 442                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: node-id=' . $nodeData[self::DB_COLUMN_NODE_ID]);
 443
 444                 // Get search criteria
 445                 $searchInstance = $this->prepareSearchInstance($nodeData);
 446
 447                 // Query database and get a result instance back
 448                 $resultInstance = $this->doSelectByCriteria(
 449                         // Search instance
 450                         $searchInstance,
 451                         // Only look for these array elements ("keys")
 452                         array(
 453                                 self::DB_COLUMN_NODE_ID          => TRUE,
 454                                 self::DB_COLUMN_EXTERNAL_ADDRESS => TRUE
 455                         )
 456                 );
 457
 458                 // Check if there is an entry
 459                 $isRegistered = $resultInstance->valid();
 460
 461                 // Debug message
 462                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: isRegistered=' . intval($isRegistered) . ' - EXIT!');
 463
 464                 // Return registration status
 465                 return $isRegistered;
 466         }
 467
 468         /**
 469          * Registers a node with given data in the DHT. If the node is already
 470          * registered this method shall throw an exception.
 471          *
 472          * @param       $nodeData       An array with valid node data
 473          * @return      void
 474          * @throws      NodeAlreadyRegisteredException  If the node is already registered
 475          */
 476         public function registerNode (array $nodeData) {
 477                 // Debug message
 478                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: CALLED!');
 479
 480                 // Assert on array elements
 481                 assert(isset($nodeData[self::DB_COLUMN_NODE_ID]));
 482
 483                 // Is the node registered?
 484                 if ($this->isNodeRegistered($nodeData)) {
 485                         // Throw an exception
 486                         throw new NodeAlreadyRegisteredException(array($this, $nodeData), self::EXCEPTION_NODE_ALREADY_REGISTERED);
 487                 }
 488
 489                 // @TODO Unimplemented part
 490                 $this->partialStub('nodeData=' . print_r($nodeData, TRUE));
 491
 492                 // Debug message
 493                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: EXIT!');
 494         }
 495
 496         /**
 497          * Updates a node's entry in the DHT with given data. This will enrich or
 498          * just update already exsiting data. If the node is not found this method
 499          * shall throw an exception.
 500          *
 501          * @param       $nodeData       An array with valid node data
 502          * @return      void
 503          * @throws      NodeDataMissingException        If the node's data is missing
 504          */
 505         public function updateNode (array $nodeData) {
 506                 // Debug message
 507                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: nodeData=' . print_r($nodeData, TRUE));
 508                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: CALLED!');
 509
 510                 // Assert on array elements
 511                 assert(isset($nodeData[self::DB_COLUMN_NODE_ID]));
 512
 513                 // Debug message
 514                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: Updating DHT entry for node-id=' . $nodeData[self::DB_COLUMN_NODE_ID] . ' ...');
 515
 516                 // Is the node registered?
 517                 if (!$this->isNodeRegistered($nodeData)) {
 518                         // No, then throw an exception
 519                         throw new NodeDataMissingException(array($this, $nodeData), self::EXCEPTION_NODE_NOT_REGISTERED);
 520                 }
 521
 522                 // Get a search instance
 523                 $searchInstance = $this->prepareSearchInstance($nodeData);
 524
 525                 // Get a data set instance
 526                 $dataSetInstance = ObjectFactory::createObjectByConfiguredName('dataset_criteria_class', array(self::DB_TABLE_NODE_DHT));
 527
 528                 // Add search instance
 529                 $dataSetInstance->setSearchInstance($searchInstance);
 530
 531                 // Set primary key (session id)
 532                 $dataSetInstance->setUniqueKey(self::DB_COLUMN_SESSION_ID);
 533
 534                 // Add all array elements
 535                 $this->getNodeInstance()->addArrayToDataSet($dataSetInstance, $nodeData);
 536
 537                 // Remove 'node_list'
 538                 $dataSetInstance->unsetCriteria(self::DB_COLUMN_NODE_LIST);
 539
 540                 // Run the "UPDATE" query
 541                 $this->queryUpdateDataSet($dataSetInstance);
 542
 543                 // Debug message
 544                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: EXIT!');
 545         }
 546
 547         /**
 548          * Checks whether there are unpublished entries
 549          *
 550          * @return      $hasUnpublished         Whether there are unpublished entries
 551          * @todo        Add minimum/maximum age limitations
 552          */
 553         public function hasUnpublishedEntries () {
 554                 // Get search instance
 555                 $searchInstance = ObjectFactory::createObjectByConfiguredName('search_criteria_class');
 556
 557                 // Add exclusion key which is the publish status
 558                 $searchInstance->addExcludeCriteria(NodeDistributedHashTableDatabaseFrontend::DB_COLUMN_PUBLICATION_STATUS, NodeDistributedHashTableDatabaseFrontend::PUBLICATION_STATUS_PENDING);
 559
 560                 // Remember search instance
 561                 $this->setSearchInstance($searchInstance);
 562
 563                 // Run the query
 564                 $this->unpublishedEntriesInstance = $this->doSelectByCriteria($searchInstance);
 565
 566                 // Check pending entries
 567                 $hasUnpublished = $this->unpublishedEntriesInstance->valid();
 568
 569                 // Debug message
 570                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: EXIT!');
 571
 572                 // Return it
 573                 return $hasUnpublished;
 574         }
 575
 576         /**
 577          * Initializes publication of DHT entries. This does only prepare
 578          * publication. The next step is to pickup such prepared entries and publish
 579          * them by uploading to other (recently appeared) DHT members.
 580          *
 581          * @return      void
 582          * @todo        Add timestamp to dataset instance
 583          */
 584         public function initEntryPublication () {
 585                 // Debug message
 586                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: CALLED!');
 587
 588                 /*
 589                  * Make sure that hasUnpublishedEntries() has been called first by
 590                  * asserting on the "cached" object instance. This "caching" saves some
 591                  * needless queries as this method shall be called immediately after
 592                  * hasUnpublishedEntries() returns TRUE.
 593                  */
 594                 assert($this->unpublishedEntriesInstance instanceof SearchableResult);
 595
 596                 // Result is still okay?
 597                 assert($this->unpublishedEntriesInstance->valid());
 598
 599                 // Remove 'publication_status'
 600                 $this->getSearchInstance()->unsetCriteria(self::DB_COLUMN_PUBLICATION_STATUS);
 601
 602                 // Make sure all entries are marked as pending, first get a dataset instance.
 603                 $dataSetInstance = ObjectFactory::createObjectByConfiguredName('dataset_criteria_class', array(self::DB_TABLE_NODE_DHT));
 604
 605                 // Add search instance
 606                 $dataSetInstance->setSearchInstance($this->getSearchInstance());
 607
 608                 // Set primary key (node id)
 609                 $dataSetInstance->setUniqueKey(self::DB_COLUMN_NODE_ID);
 610
 611                 // Add criteria (that should be set)
 612                 $dataSetInstance->addCriteria(self::DB_COLUMN_PUBLICATION_STATUS, self::PUBLICATION_STATUS_PENDING);
 613
 614                 // Run the "UPDATE" query
 615                 $this->queryUpdateDataSet($dataSetInstance);
 616
 617                 // Debug message
 618                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: EXIT!');
 619         }
 620
 621         /**
 622          * Removes non-public data from given array.
 623          *
 624          * @param       $data   An array with possible non-public data that needs to be removed.
 625          * @return      $data   A cleaned up array with only public data.
 626          */
 627         public function removeNonPublicDataFromArray(array $data) {
 628                 // Currently call only inner method
 629                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: Invoking parent::removeNonPublicDataFromArray(data) ...');
 630                 $data = parent::removeNonPublicDataFromArray($data);
 631                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: data[]=' . gettype($data));
 632
 633                 // Return cleaned data
 634                 return $data;
 635         }
 636
 637         /**
 638          * Find recipients for given package data and exclude the sender
 639          *
 640          * @param       $packageInstance        An instance of a DeliverablePackage class
 641          * @return      $recipients                     An indexed array with DHT recipients
 642          */
 643         public function getResultFromExcludedSender (DeliverablePackage $packageInstance) {
 644                 // Debug message
 645                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: CALLED!');
 646
 647                 // Get max recipients
 648                 $maxRecipients = FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('max_dht_recipients');
 649
 650                 // First creata a search instance
 651                 $searchInstance = ObjectFactory::createObjectByConfiguredName('search_criteria_class');
 652
 653                 // Then exclude 'sender' field as the sender is the current (*this*) node
 654                 $searchInstance->addExcludeCriteria(NodeDistributedHashTableDatabaseFrontend::DB_COLUMN_SESSION_ID, $packageInstance->getSenderAddress());
 655
 656                 // Set limit to maximum DHT recipients
 657                 $searchInstance->setLimit($maxRecipients);
 658
 659                 // Get a result instance back from DHT database frontend.
 660                 $resultInstance = $this->doSelectByCriteria($searchInstance);
 661
 662                 // Debug message
 663                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: EXIT!');
 664
 665                 // Return result instance
 666                 return $resultInstance;
 667         }
 668
 669         /**
 670          * Find recopients by given key/value pair. First look for the key and if it
 671          * matches, compare the value.
 672          *
 673          * @param       $key                    Key to look for
 674          * @param       $value                  Value to compare if key matches
 675          * @return      $recipients             An indexed array with DHT recipients
 676          * @throws      InvalidArgumentException        If $key is empty
 677          */
 678         public function getResultFromKeyValue (string $key, $value) {
 679                 // Is key parameter valid?
 680                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('DHT-FRONTEND: key=%s,value[%s]=%s - CALLED!', $key, gettype($value), $value));
 681                 if (empty($key)) {
 682                         // Throw exception
 683                         throw new InvalidArgumentException('Parameter key is empty');
 684                 }
 685
 686                 // Get max recipients
 687                 $maxRecipients = FrameworkBootstrap::getConfigurationInstance()->getConfigEntry('max_dht_recipients');
 688
 689                 // First creata a search instance
 690                 $searchInstance = ObjectFactory::createObjectByConfiguredName('search_criteria_class');
 691
 692                 // Find the key/value pair
 693                 $searchInstance->addCriteria($key, $value);
 694
 695                 // Get a result instance back from DHT database frontend.
 696                 $resultInstance = $this->doSelectByCriteria($searchInstance);
 697
 698                 // Return result instance
 699                 /* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput(sprintf('DHT-FRONTEND: resultInstance=%s - EXIT!', $resultInstance->__toString()));
 700                 return $resultInstance;
 701         }
 702
 703         /**
 704          * Enable DHT bootstrap request acceptance for local node
 705          *
 706          * @return      void
 707          */
 708         public function enableAcceptDhtBootstrap () {
 709                 // Debug message
 710                 /* DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DHT-FRONTEND: Enabling DHT bootstrap requests ...');
 711
 712                 // Is the node already registered?
 713                 if ($this->isLocalNodeRegistered()) {
 714                         // Just update our record
 715                         $this->updateLocalNode();
 716                 } else {
 717                         // Register it
 718                         $this->registerLocalNode();
 719                 }
 720         }
 721
 722 }