Router: more javadoc for the CM, CCR, FNDS, SNDF

i2p · Oct 7, 2023 · 9a4acca · 9a4acca
1 parent 4d30690
commit 9a4acca
Show file tree

Hide file tree

Showing 5 changed files with 57 additions and 29 deletions.
diff --git a/router/java/src/net/i2p/router/ClientManagerFacade.java b/router/java/src/net/i2p/router/ClientManagerFacade.java
@@ -128,9 +128,7 @@ public void unregisterMetaDest(Destination dest) {}
      * This is inside the runner, so it won't be there if the runner isn't ready.
      * 
      * @param destHash destination hash associated with the client who's subDb we're looking for
-     * 
      * @return non-null FloodfillNetworkDatabaseFacade
-     * 
      * @since 0.9.60
      */
     public abstract FloodfillNetworkDatabaseFacade getClientFloodfillNetworkDatabaseFacade(Hash destHash);
@@ -139,7 +137,6 @@ public void unregisterMetaDest(Destination dest) {}
      * get all of the FloodfillNetworkDatabaseFacades for all of the clients.
      * 
      * @return non-null set of FloodfillNetworkDatabaseFacades
-     * 
      * @since 0.9.60
      */
     public abstract Set<FloodfillNetworkDatabaseFacade> getClientFloodfillNetworkDatabaseFacades();
@@ -148,7 +145,6 @@ public void unregisterMetaDest(Destination dest) {}
      * get a set of all primary hashes
      * 
      * @return non-null set of Hashes
-     * 
      * @since 0.9.60
      */
     public abstract Set<Hash> getPrimaryHashes();

diff --git a/router/java/src/net/i2p/router/client/ClientConnectionRunner.java b/router/java/src/net/i2p/router/client/ClientConnectionRunner.java
@@ -1171,9 +1171,18 @@ private boolean alreadyAccepted(MessageId id) {
     private static final int MAX_REQUEUE = 60;  // 30 sec.
 
     /**
-     * Get the FloodfillNetworkDatabaseFacade for this runner.
+     * Get the FloodfillNetworkDatabaseFacade for this runner. This is the client
+     * netDb if the router is configured to use subDbs, or the main netDb if the
+     * router is configured to use a monolithic netDb.
+     * 
+     * If neither a client netDb or the main netDb is available, it will return null.
+     * This should be impossible.
+     * If you get the  `getFloodfillNetworkDatabaseFacade is null for runner` warning,
+     * the main netDb will be returned instead. If the main netDb is null, then null
+     * will be returned.
      * 
      * @return _floodfillNetworkDatabaseFacade
+     * @since 0.9.60
      */
     public FloodfillNetworkDatabaseFacade getFloodfillNetworkDatabaseFacade() {
         if (!_context.netDbSegmentor().useSubDbs())

diff --git a/router/java/src/net/i2p/router/client/ClientManager.java b/router/java/src/net/i2p/router/client/ClientManager.java
@@ -778,7 +778,7 @@ public void messageReceived(ClientMessage msg) {
      * This is inside the runner, so it won't be there if the runner isn't ready.
      * 
      * @param destHash destination hash associated with the client who's subDb we're looking for
-     * @return 
+     * @return may be null if it does not exist
      */
     public FloodfillNetworkDatabaseFacade getClientFloodfillNetworkDatabaseFacade(Hash destHash) {
         if (destHash != null) {
@@ -795,7 +795,7 @@ public FloodfillNetworkDatabaseFacade getClientFloodfillNetworkDatabaseFacade(Ha
     /**
      * get all of the FloodfillNetworkDatabaseFacades for all of the clients.
      * 
-     * @return
+     * @return non-null
      */
     public Set<FloodfillNetworkDatabaseFacade> getClientFloodfillNetworkDatabaseFacades() {
         Set<FloodfillNetworkDatabaseFacade> rv = new HashSet<FloodfillNetworkDatabaseFacade>();

diff --git a/router/java/src/net/i2p/router/networkdb/kademlia/FloodfillNetworkDatabaseSegmentor.java b/router/java/src/net/i2p/router/networkdb/kademlia/FloodfillNetworkDatabaseSegmentor.java
@@ -83,7 +83,7 @@ public boolean useSubDbs() {
      * If the ID is null, the main database is returned.
      *
      * @param  id  the ID of the FloodfillNetworkDatabaseFacade object to retrieve
-     * @return     the FloodfillNetworkDatabaseFacade object corresponding to the ID
+     * @return     the FloodfillNetworkDatabaseFacade object corresponding to the ID or null if it does not exist.
      */
     @Override
     protected FloodfillNetworkDatabaseFacade getSubNetDB(Hash id) {
@@ -125,7 +125,7 @@ public synchronized void startup() {
      * list of the RouterInfo objects for all known peers;
      * 
      * @since 0.9.60
-     * 
+     * @return non-null
      */
     public List<RouterInfo> getKnownRouterData() {
         List<RouterInfo> rv = new ArrayList<RouterInfo>();
@@ -143,6 +143,7 @@ public List<RouterInfo> getKnownRouterData() {
      * List is not sorted and not shuffled.
      * 
      * @since 0.9.60
+     * @return non-null
      */
     public List<Hash> getFloodfillPeers() {
         if (_log.shouldLog(Log.DEBUG))
@@ -159,6 +160,7 @@ public List<Hash> getFloodfillPeers() {
      * but the client dbid is not.
      *
      * @param key The LS key for client.
+     * @return may be null
      * @since 0.9.60
      */
     @Override
@@ -171,8 +173,8 @@ public LeaseSet lookupLeaseSetHashIsClient(Hash key) {
      * if a DBID is not provided, the clients will all be checked, and the
      * first value will be used.
      * 
+     * @return may be null
      * @since 0.9.60
-     * 
      */
     //@Override
     protected LeaseSet lookupLeaseSetLocally(Hash key, Hash dbid) {
@@ -194,7 +196,7 @@ protected LeaseSet lookupLeaseSetLocally(Hash key, Hash dbid) {
      * Check if all of the known subDbs are initialized
      * 
      * @since 0.9.60
-     * 
+     * @return true if the mainNetdb and all known client netDbs are initialized
      */
     public boolean isInitialized() {
         if (_mainDbid == null)
@@ -215,7 +217,7 @@ public boolean isInitialized() {
      * list of the RouterInfo objects for all known peers known to clients(in subDbs) only
      * 
      * @since 0.9.60
-     * 
+     * @return non-null
      */
     public Set<RouterInfo> getRoutersKnownToClients() {
         Set<RouterInfo> rv = new HashSet<>();
@@ -231,7 +233,7 @@ public Set<RouterInfo> getRoutersKnownToClients() {
      * list of the LeaseSet objects for all known peers known to clients(in subDbs) only
      * 
      * @since 0.9.60
-     * 
+     * @return non-null
      */
     public Set<LeaseSet> getLeasesKnownToClients() {
         Set<LeaseSet> rv = new HashSet<>();
@@ -247,7 +249,7 @@ public Set<LeaseSet> getLeasesKnownToClients() {
      * get the main netDb, which is the one we will use if we are a floodfill
      * 
      * @since 0.9.60
-     * 
+     * @return may be null
      */
     @Override
     public FloodfillNetworkDatabaseFacade mainNetDB() {
@@ -258,7 +260,7 @@ public FloodfillNetworkDatabaseFacade mainNetDB() {
      * get the multiHome netDb, which is especially for handling multihomes
      * 
      * @since 0.9.60
-     * 
+     * @return may be null
      */
     @Override
     public FloodfillNetworkDatabaseFacade multiHomeNetDB() {
@@ -271,7 +273,7 @@ public FloodfillNetworkDatabaseFacade multiHomeNetDB() {
      * the dbid is null.
      * 
      * @since 0.9.60
-     * 
+     * @return may be null if the client netDb does not exist
      */
     @Override
     public FloodfillNetworkDatabaseFacade clientNetDB(Hash id) {
@@ -288,10 +290,11 @@ public FloodfillNetworkDatabaseFacade clientNetDB(Hash id) {
     }
 
     /**
-     * look up the dbid of the client with the given signing public key
+     * look up the dbid of the client or clients with the given signing
+     * public key
      * 
      * @since 0.9.60
-     * 
+     * @return non-null
      */
     @Override
     public List<Hash> lookupClientBySigningPublicKey(SigningPublicKey spk) {
@@ -318,7 +321,7 @@ public List<Hash> lookupClientBySigningPublicKey(SigningPublicKey spk) {
      * and the possible-multihomes netDb
      * 
      * @since 0.9.60
-     * 
+     * @return non-null
      */
     @Override
     public Set<FloodfillNetworkDatabaseFacade> getSubNetDBs() {
@@ -340,7 +343,8 @@ public Set<FloodfillNetworkDatabaseFacade> getSubNetDBs() {
      * with specific clients, unless subDbs are disabled in which case it only contains the
      * main netDB
      * 
-     * @return
+     * @since 0.9.60
+     * @return non-null
      */
     private Set<FloodfillNetworkDatabaseFacade> getClientSubNetDBs() {
         if (!_mainDbid.isInitialized())
@@ -358,7 +362,7 @@ private Set<FloodfillNetworkDatabaseFacade> getClientSubNetDBs() {
      * list of the BlindData objects for all known clients
      * 
      * @since 0.9.60
-     * 
+     * @return non-null
      */
     @Override
     public List<BlindData> getLocalClientsBlindData() {

diff --git a/router/java/src/net/i2p/router/networkdb/kademlia/SegmentedNetworkDatabaseFacade.java b/router/java/src/net/i2p/router/networkdb/kademlia/SegmentedNetworkDatabaseFacade.java
@@ -74,26 +74,30 @@ public boolean useSubDbs() {
     /**
      * Get a sub-netDb using a Hash identifier
      * 
+     * @return client subDb for hash, or null if it does not exist
      * @since 0.9.60
      */
     protected abstract FloodfillNetworkDatabaseFacade getSubNetDB(Hash dbid);
     /**
      * Get the main netDb, the one which is used if we're a floodfill
      * 
+     * @return may be null if main netDb is not initialized
      * @since 0.9.60
      */
     public abstract FloodfillNetworkDatabaseFacade mainNetDB();
     /**
      * Get the multihome netDb, the one which is used if we're a floodfill AND we
      * have a multihome address sent to us
      * 
+     * @return may be null if the multihome netDb is not initialized
      * @since 0.9.60
      */
     public abstract FloodfillNetworkDatabaseFacade multiHomeNetDB();
     /**
      * Get a client netDb for a given client Hash identifier. Will never
      * return the mainNetDB.
      * 
+     * @return may be null if the client netDb does not exist
      * @since 0.9.60
      */
     public abstract FloodfillNetworkDatabaseFacade clientNetDB(Hash dbid);
@@ -112,29 +116,35 @@ public boolean useSubDbs() {
     /**
      * Lookup the leaseSet for a given key in only client dbs.
      * 
+     * @return may be null
      * @since 0.9.60
      */
     public abstract LeaseSet lookupLeaseSetHashIsClient(Hash key);
     /**
      * Get a set of all sub-netDbs.
      * 
+     * @return all the sub netDbs including the main
      * @since 0.9.60
      */
     public abstract Set<FloodfillNetworkDatabaseFacade> getSubNetDBs();
     /**
-     * Make sure the SNDF is initialized
+     * Make sure the SNDF is initialized. This is overridden in
+     * FloodfillNetworkDatabaseSegmentor so that it will be false until
+     * *all* required subDbs are initialized.
+     * 
+     * @return true if the netDbs are initialized
+     * @since 0.9.60
      */
     public boolean isInitialized() {
         return mainNetDB().isInitialized();
     }
 
     /**
-     * list of the RouterInfo objects for all known peers in all subDbs
-     * which is mostly pointless because they should normally reject them
-     * anyway
+     * list all of the RouterInfo objects known to all of the subDbs including
+     * the main subDb.
      * 
+     * @return all of the RouterInfo objects known to all of the netDbs. non-null
      * @since 0.9.60
-     * 
      */
     public Set<RouterInfo> getRouters() {
         Set<RouterInfo> rv = new HashSet<>();
@@ -145,8 +155,11 @@ public Set<RouterInfo> getRouters() {
     }
 
     /** 
-     * Get a set of all routers known to clients, which should always be zero.
+     * list of the RouterInfo objects for all known peers in all client
+     * subDbs which is mostly pointless because they should normally reject
+     * them anyway.
      * 
+     * @return non-null all the routerInfos in all of the client netDbs *only*
      * @since 0.9.60 
      */
     public Set<RouterInfo> getRoutersKnownToClients() {
@@ -159,8 +172,11 @@ public Set<RouterInfo> getRoutersKnownToClients() {
     }
 
     /**
-     * Get a set of all leases known to all clients.
+     * Get a set of all leases known to all clients. These will be
+     * leaseSets for destinations that the clients communicate with
+     * and the leaseSet of the client itself.
      * 
+     * @return non-null. all the leaseSets known to all of the client netDbs
      * @since 0.9.60
      */
     public Set<LeaseSet> getLeasesKnownToClients() {
@@ -173,7 +189,8 @@ public Set<LeaseSet> getLeasesKnownToClients() {
     }
     /**
      * Check if the mainNetDB needs to reseed
-     *  
+     * 
+     * @return non-null.
      * @since 0.9.60 
      * */
     public ReseedChecker reseedChecker() {
@@ -182,6 +199,7 @@ public ReseedChecker reseedChecker() {
     /**
      * For console ConfigKeyringHelper
      * 
+     * @return non-null
      * @since 0.9.60
      */
     public List<Hash> lookupClientBySigningPublicKey(SigningPublicKey spk) {
@@ -190,6 +208,7 @@ public List<Hash> lookupClientBySigningPublicKey(SigningPublicKey spk) {
     /**
      * For console ConfigKeyringHelper
      * 
+     * @return non-null
      * @since 0.9.60
      */
     public List<BlindData> getLocalClientsBlindData() {