From 9a4accaf6b803faebcc42ce20dbbd0b47a5b60ed Mon Sep 17 00:00:00 2001 From: eyedeekay Date: Sat, 7 Oct 2023 14:57:25 -0400 Subject: [PATCH] Router: more javadoc for the CM, CCR, FNDS, SNDF --- .../net/i2p/router/ClientManagerFacade.java | 4 --- .../router/client/ClientConnectionRunner.java | 11 +++++- .../net/i2p/router/client/ClientManager.java | 4 +-- .../FloodfillNetworkDatabaseSegmentor.java | 32 +++++++++-------- .../SegmentedNetworkDatabaseFacade.java | 35 ++++++++++++++----- 5 files changed, 57 insertions(+), 29 deletions(-) diff --git a/router/java/src/net/i2p/router/ClientManagerFacade.java b/router/java/src/net/i2p/router/ClientManagerFacade.java index 3d1c0f605c..3be5e9aea6 100644 --- 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 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 getPrimaryHashes(); diff --git a/router/java/src/net/i2p/router/client/ClientConnectionRunner.java b/router/java/src/net/i2p/router/client/ClientConnectionRunner.java index 959e8b70c9..640992e431 100644 --- 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 index a3fb127027..5bf2b17564 100644 --- 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 getClientFloodfillNetworkDatabaseFacades() { Set rv = new HashSet(); diff --git a/router/java/src/net/i2p/router/networkdb/kademlia/FloodfillNetworkDatabaseSegmentor.java b/router/java/src/net/i2p/router/networkdb/kademlia/FloodfillNetworkDatabaseSegmentor.java index ba1bf03088..bd42337a42 100644 --- 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 getKnownRouterData() { List rv = new ArrayList(); @@ -143,6 +143,7 @@ public List getKnownRouterData() { * List is not sorted and not shuffled. * * @since 0.9.60 + * @return non-null */ public List getFloodfillPeers() { if (_log.shouldLog(Log.DEBUG)) @@ -159,6 +160,7 @@ public List 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 getRoutersKnownToClients() { Set rv = new HashSet<>(); @@ -231,7 +233,7 @@ public Set 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 getLeasesKnownToClients() { Set rv = new HashSet<>(); @@ -247,7 +249,7 @@ public Set 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 lookupClientBySigningPublicKey(SigningPublicKey spk) { @@ -318,7 +321,7 @@ public List lookupClientBySigningPublicKey(SigningPublicKey spk) { * and the possible-multihomes netDb * * @since 0.9.60 - * + * @return non-null */ @Override public Set getSubNetDBs() { @@ -340,7 +343,8 @@ public Set 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 getClientSubNetDBs() { if (!_mainDbid.isInitialized()) @@ -358,7 +362,7 @@ private Set getClientSubNetDBs() { * list of the BlindData objects for all known clients * * @since 0.9.60 - * + * @return non-null */ @Override public List 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 index 604616838c..f80e68aaea 100644 --- a/router/java/src/net/i2p/router/networkdb/kademlia/SegmentedNetworkDatabaseFacade.java +++ b/router/java/src/net/i2p/router/networkdb/kademlia/SegmentedNetworkDatabaseFacade.java @@ -74,12 +74,14 @@ 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(); @@ -87,6 +89,7 @@ public boolean useSubDbs() { * 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(); @@ -94,6 +97,7 @@ public boolean useSubDbs() { * 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 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 getRouters() { Set rv = new HashSet<>(); @@ -145,8 +155,11 @@ public Set 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 getRoutersKnownToClients() { @@ -159,8 +172,11 @@ public Set 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 getLeasesKnownToClients() { @@ -173,7 +189,8 @@ public Set 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 lookupClientBySigningPublicKey(SigningPublicKey spk) { @@ -190,6 +208,7 @@ public List lookupClientBySigningPublicKey(SigningPublicKey spk) { /** * For console ConfigKeyringHelper * + * @return non-null * @since 0.9.60 */ public List getLocalClientsBlindData() {