add javadoc

Author: KeeProMise

hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/router/async/AsyncErasureCoding.java

@@ -44,6 +44,12 @@
 import static org.apache.hadoop.hdfs.server.federation.router.async.utils.AsyncUtil.asyncApply;
 import static org.apache.hadoop.hdfs.server.federation.router.async.utils.AsyncUtil.asyncReturn;
 
+/**
+ * Provides asynchronous operations for erasure coding in HDFS Federation.
+ * This class extends {@link org.apache.hadoop.hdfs.server.federation.router.ErasureCoding}
+ * and overrides its methods to perform erasure coding operations in a non-blocking manner,
+ * allowing for concurrent execution and improved performance.
+ */
 public class AsyncErasureCoding extends ErasureCoding {
   /** RPC server to receive client calls. */
   private final RouterRpcServer rpcServer;
@@ -59,6 +65,16 @@ public AsyncErasureCoding(RouterRpcServer server) {
     this.namenodeResolver = this.rpcClient.getNamenodeResolver();
   }
 
+  /**
+   * Asynchronously get an array of all erasure coding policies.
+   * This method checks the operation category and then invokes the
+   * getErasureCodingPolicies method concurrently across all namespaces.
+   * <p>
+   * The results are merged and returned as an array of ErasureCodingPolicyInfo.
+   *
+   * @return Array of ErasureCodingPolicyInfo.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public ErasureCodingPolicyInfo[] getErasureCodingPolicies()
       throws IOException {
@@ -76,6 +92,16 @@ public ErasureCodingPolicyInfo[] getErasureCodingPolicies()
     return asyncReturn(ErasureCodingPolicyInfo[].class);
   }
 
+  /**
+   * Asynchronously get the erasure coding codecs available.
+   * This method checks the operation category and then invokes the
+   * getErasureCodingCodecs method concurrently across all namespaces.
+   * <p>
+   * The results are merged into a single map of codec names to codec properties.
+   *
+   * @return Map of erasure coding codecs.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public Map<String, String> getErasureCodingCodecs() throws IOException {
     rpcServer.checkOperation(NameNode.OperationCategory.READ);
@@ -103,6 +129,17 @@ public Map<String, String> getErasureCodingCodecs() throws IOException {
     return asyncReturn(Map.class);
   }
 
+  /**
+   * Asynchronously add an array of erasure coding policies.
+   * This method checks the operation category and then invokes the
+   * addErasureCodingPolicies method concurrently across all namespaces.
+   * <p>
+   * The results are merged and returned as an array of AddErasureCodingPolicyResponse.
+   *
+   * @param policies Array of erasure coding policies to add.
+   * @return Array of AddErasureCodingPolicyResponse.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public AddErasureCodingPolicyResponse[] addErasureCodingPolicies(
       ErasureCodingPolicy[] policies) throws IOException {
@@ -123,6 +160,17 @@ public AddErasureCodingPolicyResponse[] addErasureCodingPolicies(
     return asyncReturn(AddErasureCodingPolicyResponse[].class);
   }
 
+  /**
+   * Asynchronously get the erasure coding policy for a given source path.
+   * This method checks the operation category and then invokes the
+   * getErasureCodingPolicy method sequentially for the given path.
+   * <p>
+   * The result is returned as an ErasureCodingPolicy object.
+   *
+   * @param src Source path to get the erasure coding policy for.
+   * @return ErasureCodingPolicy for the given path.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public ErasureCodingPolicy getErasureCodingPolicy(String src)
       throws IOException {
@@ -142,6 +190,17 @@ public ErasureCodingPolicy getErasureCodingPolicy(String src)
     return asyncReturn(ErasureCodingPolicy.class);
   }
 
+  /**
+   * Asynchronously get the EC topology result for the given policies.
+   * This method checks the operation category and then invokes the
+   * getECTopologyResultForPolicies method concurrently across all namespaces.
+   * <p>
+   * The results are merged and the first unsupported result is returned.
+   *
+   * @param policyNames Array of policy names to check.
+   * @return ECTopologyVerifierResult for the policies.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public ECTopologyVerifierResult getECTopologyResultForPolicies(
       String[] policyNames) throws IOException {
@@ -168,6 +227,16 @@ public ECTopologyVerifierResult getECTopologyResultForPolicies(
     return asyncReturn(ECTopologyVerifierResult.class);
   }
 
+  /**
+   * Asynchronously get the erasure coding block group statistics.
+   * This method checks the operation category and then invokes the
+   * getECBlockGroupStats method concurrently across all namespaces.
+   * <p>
+   * The results are merged and returned as an ECBlockGroupStats object.
+   *
+   * @return ECBlockGroupStats for the erasure coding block groups.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public ECBlockGroupStats getECBlockGroupStats() throws IOException {
     rpcServer.checkOperation(NameNode.OperationCategory.READ);

hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/router/async/AsyncQuota.java

@@ -35,6 +35,12 @@
 import static org.apache.hadoop.hdfs.server.federation.router.async.utils.AsyncUtil.asyncApply;
 import static org.apache.hadoop.hdfs.server.federation.router.async.utils.AsyncUtil.asyncReturn;
 
+/**
+ * Provides asynchronous operations for managing quotas in HDFS Federation.
+ * This class extends {@link org.apache.hadoop.hdfs.server.federation.router.Quota}
+ * and overrides its methods to perform quota operations in a non-blocking manner,
+ * allowing for concurrent execution and improved performance.
+ */
 public class AsyncQuota extends Quota {
 
   /** RPC server to receive client calls. */

hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/router/async/RouterAsyncCacheAdmin.java

@@ -47,6 +47,17 @@ public RouterAsyncCacheAdmin(RouterRpcServer server) {
     super(server);
   }
 
+  /**
+   * Asynchronously adds a new cache directive with the given path and flags.
+   * This method invokes the addCacheDirective method concurrently across all
+   * namespaces, and returns the first response as a long value representing the
+   * directive ID.
+   *
+   * @param path The cache directive path.
+   * @param flags The cache flags.
+   * @return The ID of the newly added cache directive.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public long addCacheDirective(
       CacheDirectiveInfo path, EnumSet<CacheFlag> flags) throws IOException {
@@ -56,6 +67,17 @@ public long addCacheDirective(
     return asyncReturn(Long.class);
   }
 
+  /**
+   * Asynchronously lists cache directives based on the provided previous ID and filter.
+   * This method invokes the listCacheDirectives method concurrently across all
+   * namespaces, and returns the first response as a BatchedEntries object containing
+   * the cache directive entries.
+   *
+   * @param prevId The previous ID from which to start listing.
+   * @param filter The filter to apply to the cache directives.
+   * @return BatchedEntries of cache directive entries.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public BatchedEntries<CacheDirectiveEntry> listCacheDirectives(
       long prevId, CacheDirectiveInfo filter) throws IOException {
@@ -66,6 +88,16 @@ public BatchedEntries<CacheDirectiveEntry> listCacheDirectives(
     return asyncReturn(BatchedEntries.class);
   }
 
+  /**
+   * Asynchronously lists cache pools starting from the provided key.
+   * This method invokes the listCachePools method concurrently across all namespaces,
+   * and returns the first response as a BatchedEntries object containing the cache
+   * pool entries.
+   *
+   * @param prevKey The previous key from which to start listing.
+   * @return BatchedEntries of cache pool entries.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public BatchedEntries<CachePoolEntry> listCachePools(String prevKey) throws IOException {
     invokeListCachePools(prevKey);

hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/router/async/RouterAsyncSnapshot.java

@@ -63,6 +63,16 @@ public RouterAsyncSnapshot(RouterRpcServer server) {
     this.namenodeResolver = rpcServer.getNamenodeResolver();
   }
 
+  /**
+   * Asynchronously creates a snapshot with the given root and name.
+   * This method checks the operation category and then invokes the createSnapshot
+   * method concurrently across all namespaces, returning the first successful response.
+   *
+   * @param snapshotRoot The root path of the snapshot.
+   * @param snapshotName The name of the snapshot.
+   * @return The path of the created snapshot.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public String createSnapshot(String snapshotRoot, String snapshotName) throws IOException {
     rpcServer.checkOperation(NameNode.OperationCategory.WRITE);
@@ -95,6 +105,15 @@ public String createSnapshot(String snapshotRoot, String snapshotName) throws IO
     return asyncReturn(String.class);
   }
 
+  /**
+   * Asynchronously get an array of snapshottable directory listings.
+   * This method checks the operation category and then invokes the
+   * getSnapshottableDirListing method concurrently across all namespaces, merging
+   * the results into a single array.
+   *
+   * @return Array of SnapshottableDirectoryStatus.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public SnapshottableDirectoryStatus[] getSnapshottableDirListing() throws IOException {
     rpcServer.checkOperation(NameNode.OperationCategory.READ);
@@ -109,6 +128,16 @@ public SnapshottableDirectoryStatus[] getSnapshottableDirListing() throws IOExce
     return asyncReturn(SnapshottableDirectoryStatus[].class);
   }
 
+  /**
+   * Asynchronously get an array of snapshot listings for the given snapshot root.
+   * This method checks the operation category and then invokes the
+   * getSnapshotListing method, either sequentially or concurrently based on the
+   * configuration, and returns the merged results.
+   *
+   * @param snapshotRoot The root path of the snapshots.
+   * @return Array of SnapshotStatus.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public SnapshotStatus[] getSnapshotListing(String snapshotRoot) throws IOException {
     rpcServer.checkOperation(NameNode.OperationCategory.READ);
@@ -151,6 +180,18 @@ public SnapshotStatus[] getSnapshotListing(String snapshotRoot) throws IOExcepti
     return asyncReturn(SnapshotStatus[].class);
   }
 
+  /**
+   * Asynchronously get a snapshot diff report for the given root and snapshot names.
+   * This method checks the operation category and then invokes the
+   * getSnapshotDiffReport method, either sequentially or concurrently based on the
+   * configuration, and returns the result.
+   *
+   * @param snapshotRoot The root path of the snapshot.
+   * @param earlierSnapshotName The name of the earlier snapshot.
+   * @param laterSnapshotName The name of the later snapshot.
+   * @return SnapshotDiffReport for the snapshots.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public SnapshotDiffReport getSnapshotDiffReport(
       String snapshotRoot, String earlierSnapshotName,
@@ -175,6 +216,20 @@ public SnapshotDiffReport getSnapshotDiffReport(
     }
   }
 
+  /**
+   * Asynchronously get a snapshot diff report listing for the given root and snapshot names.
+   * This method checks the operation category and then invokes the
+   * getSnapshotDiffReportListing method, either sequentially or concurrently based
+   * on the configuration, and returns the result.
+   *
+   * @param snapshotRoot The root path of the snapshot.
+   * @param earlierSnapshotName The name of the earlier snapshot.
+   * @param laterSnapshotName The name of the later snapshot.
+   * @param startPath The starting path for the diff report.
+   * @param index The index for the diff report listing.
+   * @return SnapshotDiffReportListing for the snapshots.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public SnapshotDiffReportListing getSnapshotDiffReportListing(
       String snapshotRoot, String earlierSnapshotName, String laterSnapshotName,

hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/router/async/RouterAsyncStoragePolicy.java

@@ -31,6 +31,11 @@
 
 import static org.apache.hadoop.hdfs.server.federation.router.async.utils.AsyncUtil.asyncReturn;
 
+/**
+ * Module that implements all the asynchronous RPC calls in
+ * {@link org.apache.hadoop.hdfs.protocol.ClientProtocol} related to
+ * Storage Policy in the {@link RouterRpcServer}.
+ */
 public class RouterAsyncStoragePolicy extends RouterStoragePolicy {
   /** RPC server to receive client calls. */
   private final RouterRpcServer rpcServer;
@@ -43,6 +48,15 @@ public RouterAsyncStoragePolicy(RouterRpcServer server) {
     this.rpcClient = this.rpcServer.getRPCClient();
   }
 
+  /**
+   * Asynchronously get the storage policy for a given path.
+   * This method checks the operation category and then invokes the
+   * getStoragePolicy method sequentially for the given path.
+   *
+   * @param path The path for which to retrieve the storage policy.
+   * @return The BlockStoragePolicy for the given path.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public BlockStoragePolicy getStoragePolicy(String path)
       throws IOException {
@@ -57,6 +71,14 @@ public BlockStoragePolicy getStoragePolicy(String path)
     return asyncReturn(BlockStoragePolicy.class);
   }
 
+  /**
+   * Asynchronously get an array of all available storage policies.
+   * This method checks the operation category and then invokes the
+   * getStoragePolicies method across all available namespaces.
+   *
+   * @return An array of BlockStoragePolicy.
+   * @throws IOException If an I/O error occurs.
+   */
   @Override
   public BlockStoragePolicy[] getStoragePolicies() throws IOException {
     rpcServer.checkOperation(NameNode.OperationCategory.READ);

hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/router/async/RouterAsyncUserProtocol.java

@@ -67,6 +67,7 @@ public RouterAsyncUserProtocol(RouterRpcServer server) {
 
   /**
    * Asynchronously refresh user to group mappings.
+   *
    * @throws IOException  raised on errors performing I/O.
    */
   @Override
@@ -86,6 +87,7 @@ public void refreshUserToGroupsMappings() throws IOException {
 
   /**
    * Asynchronously refresh superuser proxy group list.
+   *
    * @throws IOException  raised on errors performing I/O.
    */
   @Override
@@ -105,6 +107,7 @@ public void refreshSuperUserGroupsConfiguration() throws IOException {
 
   /**
    * Asynchronously get the groups which are mapped to the given user.
+   *
    * @param user The user to get the groups for.
    * @return The set of groups the user belongs to.
    * @throws IOException raised on errors performing I/O.