HDFS-14837. Review of Block.java. Contributed by David Mollitor.

hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/protocol/Block.java

@@ -17,21 +17,32 @@
  */
 package org.apache.hadoop.hdfs.protocol;
 
-import java.io.*;
+import java.io.DataInput;
+import java.io.DataOutput;
+import java.io.File;
+import java.io.IOException;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+import javax.annotation.Nonnull;
+
 import org.apache.hadoop.classification.InterfaceAudience;
 import org.apache.hadoop.classification.InterfaceStability;
-import org.apache.hadoop.io.*;
+import org.apache.hadoop.io.Writable;
+import org.apache.hadoop.io.WritableFactories;
+import org.apache.hadoop.io.WritableFactory;
 
-import javax.annotation.Nonnull;
-
-/**************************************************
- * A Block is a Hadoop FS primitive, identified by a
- * long.
+/**
+ * A Block is a Hadoop FS primitive, identified by its block ID (a long). A
+ * block also has an accompanying generation stamp. A generation stamp is a
+ * monotonically increasing 8-byte number for each block that is maintained
+ * persistently by the NameNode. However, for the purposes of this class, two
+ * Blocks are considered equal iff they have the same block ID.
  *
- **************************************************/
+ * @see Block#equals(Object)
+ * @see Block#hashCode()
+ * @see Block#compareTo(Block)
+ */
 @InterfaceAudience.Private
 @InterfaceStability.Evolving
 public class Block implements Writable, Comparable<Block> {
@@ -119,8 +130,7 @@ public class Block implements Writable, Comparable<Block> {
     this.numBytes = len;
     this.generationStamp = genStamp;
   }
-  /**
-   */
+
   public long getBlockId() {
     return blockId;
   }
@@ -130,17 +140,21 @@ public class Block implements Writable, Comparable<Block> {
   }
 
   /**
+   * Get the block name. The format of the name is in the format:
+   * <p>
+   * blk_1, blk_2, blk_3, etc.
+   * </p>
+   *
+   * @return the block name
    */
   public String getBlockName() {
-    return new StringBuilder().append(BLOCK_FILE_PREFIX)
-        .append(blockId).toString();
+    return BLOCK_FILE_PREFIX + blockId;
   }
 
-  /**
-   */
   public long getNumBytes() {
     return numBytes;
   }
+
   public void setNumBytes(long len) {
     this.numBytes = len;
   }
@@ -161,28 +175,33 @@ public class Block implements Writable, Comparable<Block> {
    * @return the string representation of the block
    */
   public static String toString(final Block b) {
-    StringBuilder sb = new StringBuilder();
-    sb.append(BLOCK_FILE_PREFIX).
-       append(b.blockId).append("_").
-       append(b.generationStamp);
-    return sb.toString();
+    return new StringBuilder(BLOCK_FILE_PREFIX)
+        .append(b.blockId)
+        .append('_')
+        .append(b.generationStamp)
+        .toString();
   }
 
   /**
+   * Get the block name. The format of the name is in the format:
+   * <p>
+   * blk_block-id_generation, blk_1_1, blk_1_2, blk_2_1, etc.
+   * </p>
+   *
+   * @return the full block name
    */
   @Override
   public String toString() {
-    return toString(this);
+    return Block.toString(this);
   }
 
   public void appendStringTo(StringBuilder sb) {
     sb.append(BLOCK_FILE_PREFIX)
       .append(blockId)
-      .append("_")
+      .append('_')
       .append(getGenerationStamp());
   }
 
-
   /////////////////////////////////////
   // Writable
   /////////////////////////////////////
@@ -223,32 +242,74 @@ public class Block implements Writable, Comparable<Block> {
     this.generationStamp = in.readLong();
   }
 
-  @Override // Comparable
+  /**
+   * Compares this Block with the specified Block for order. Returns a negative
+   * integer, zero, or a positive integer as this Block is less than, equal to,
+   * or greater than the specified Block. Blocks are ordered based on their
+   * block ID.
+   *
+   * @param b the Block to be compared
+   * @return a negative integer, zero, or a positive integer as this Block is
+   *         less than, equal to, or greater than the specified Block.
+   */
+  @Override
   public int compareTo(@Nonnull Block b) {
-    return blockId < b.blockId ? -1 :
-        blockId > b.blockId ? 1 : 0;
+    return Long.compare(blockId, b.blockId);
   }
 
-  @Override // Object
-  public boolean equals(Object o) {
-    return this == o || o instanceof Block && compareTo((Block) o) == 0;
+  /**
+   * Indicates whether some Block is "equal to" this one. Two blocks are
+   * considered equal if they have the same block ID.
+   *
+   * @param obj the reference object with which to compare.
+   * @return true if this Block is the same as the argument; false otherwise.
+   */
+  @Override
+  public boolean equals(Object obj) {
+    if (this == obj) {
+      return true;
+    }
+    if (!(obj instanceof Block)) {
+      return false;
+    }
+    Block other = (Block) obj;
+    return (blockId == other.blockId);
   }
 
   /**
-   * @return true if the two blocks have the same block ID and the same
-   * generation stamp, or if both blocks are null.
+   * Returns a hash code value for the Block. The hash code adheres to the
+   * general contract of hashCode. If two Blocks are equal according to the
+   * equals(Object) method, then calling the hashCode method on each of the two
+   * blocks produce the same integer result.
+   *
+   * @return a hash code value for this block
+   * @see Block#equals(Object)
    */
-  public static boolean matchingIdAndGenStamp(Block a, Block b) {
-    if (a == b) return true; // same block, or both null
-    // only one null
-    return !(a == null || b == null) &&
-        a.blockId == b.blockId &&
-        a.generationStamp == b.generationStamp;
+  @Override
+  public int hashCode() {
+    return Long.hashCode(blockId);
   }
 
-  @Override // Object
-  public int hashCode() {
-    //GenerationStamp is IRRELEVANT and should not be used here
-    return (int)(blockId^(blockId>>>32));
+  /**
+   * A helper function to determine if two blocks are equal, based on the block
+   * ID and the generation stamp. This is a different equalities check than the
+   * default behavior of the Block class. Two blocks are considered equal by
+   * this function iff the two blocks have the same block ID and the same
+   * generation stamp, or if both blocks are null.
+   *
+   * @param a an object
+   * @param b an object to be compared with {@code a} for equality
+   * @return {@code true} if the blocks are deeply equal to each other and
+   *         {@code false} otherwise
+   * @see Block
+   */
+  public static boolean matchingIdAndGenStamp(Block a, Block b) {
+    if (a == b) {
+      return true;
+    } else if (a == null || b == null) {
+      return false;
+    } else {
+      return a.blockId == b.blockId && a.generationStamp == b.generationStamp;
+    }
   }
 }