Add javadoc to new util module classes

Signed-off-by: Matilda Clerke <[email protected]>

util/src/main/java/org/hyperledger/besu/util/e2/E2BeaconState.java

@@ -14,20 +14,10 @@
  */
 package org.hyperledger.besu.util.e2;
 
-public class E2BeaconState {
-  private final byte[] beaconState;
-  private final int slot;
-
-  public E2BeaconState(final byte[] beaconState, final int slot) {
-    this.beaconState = beaconState;
-    this.slot = slot;
-  }
-
-  public byte[] getBeaconState() {
-    return beaconState;
-  }
-
-  public int getSlot() {
-    return slot;
-  }
-}
+/**
+ * Represents a beacon state in an E2 file
+ *
+ * @param beaconState The beacon state
+ * @param slot The slot number
+ */
+public record E2BeaconState(byte[] beaconState, int slot) {}

util/src/main/java/org/hyperledger/besu/util/e2/E2BlockIndex.java

@@ -16,20 +16,10 @@
 
 import java.util.List;
 
-public class E2BlockIndex {
-  private final long startingSlot;
-  private final List<Long> indexes;
-
-  public E2BlockIndex(final long startingSlot, final List<Long> indexes) {
-    this.startingSlot = startingSlot;
-    this.indexes = indexes;
-  }
-
-  public long getStartingSlot() {
-    return startingSlot;
-  }
-
-  public List<Long> getIndexes() {
-    return indexes;
-  }
-}
+/**
+ * Represents a block index in an E2 file
+ *
+ * @param startingSlot The first slot number indexed by this block index
+ * @param indexes The indexes of the blocks indexed by this block index
+ */
+public record E2BlockIndex(long startingSlot, List<Long> indexes) {}

util/src/main/java/org/hyperledger/besu/util/e2/E2ExecutionBlockBody.java

@@ -14,20 +14,10 @@
  */
 package org.hyperledger.besu.util.e2;
 
-public class E2ExecutionBlockBody {
-  private final byte[] block;
-  private final int slot;
-
-  public E2ExecutionBlockBody(final byte[] block, final int slot) {
-    this.block = block;
-    this.slot = slot;
-  }
-
-  public byte[] getBlock() {
-    return block;
-  }
-
-  public int getSlot() {
-    return slot;
-  }
-}
+/**
+ * Represents an execution block body in an E2 file
+ *
+ * @param block The execution block
+ * @param slot The slot number
+ */
+public record E2ExecutionBlockBody(byte[] block, int slot) {}

util/src/main/java/org/hyperledger/besu/util/e2/E2ExecutionBlockHeader.java

@@ -14,20 +14,10 @@
  */
 package org.hyperledger.besu.util.e2;
 
-public class E2ExecutionBlockHeader {
-  private final byte[] header;
-  private final int slot;
-
-  public E2ExecutionBlockHeader(final byte[] header, final int slot) {
-    this.header = header;
-    this.slot = slot;
-  }
-
-  public byte[] getHeader() {
-    return header;
-  }
-
-  public int getSlot() {
-    return slot;
-  }
-}
+/**
+ * Represents an execution block header in an E2 file
+ *
+ * @param header The execution block header
+ * @param slot The slot number
+ */
+public record E2ExecutionBlockHeader(byte[] header, int slot) {}

util/src/main/java/org/hyperledger/besu/util/e2/E2ExecutionBlockReceipts.java

@@ -14,20 +14,10 @@
  */
 package org.hyperledger.besu.util.e2;
 
-public class E2ExecutionBlockReceipts {
-  private final byte[] receipts;
-  private final int slot;
-
-  public E2ExecutionBlockReceipts(final byte[] receipts, final int slot) {
-    this.receipts = receipts;
-    this.slot = slot;
-  }
-
-  public byte[] getReceipts() {
-    return receipts;
-  }
-
-  public int getSlot() {
-    return slot;
-  }
-}
+/**
+ * Represents an execution block's transaction receipts in an E2 file
+ *
+ * @param receipts The execution block's transaction receipts
+ * @param slot The slot number
+ */
+public record E2ExecutionBlockReceipts(byte[] receipts, int slot) {}

util/src/main/java/org/hyperledger/besu/util/e2/E2SignedBeaconBlock.java

@@ -14,20 +14,10 @@
  */
 package org.hyperledger.besu.util.e2;
 
-public class E2SignedBeaconBlock {
-  private final byte[] signedBeaconBlock;
-  private final int slot;
-
-  public E2SignedBeaconBlock(final byte[] signedBeaconBlock, final int slot) {
-    this.signedBeaconBlock = signedBeaconBlock;
-    this.slot = slot;
-  }
-
-  public byte[] getSignedBeaconBlock() {
-    return signedBeaconBlock;
-  }
-
-  public int getSlot() {
-    return slot;
-  }
-}
+/**
+ * Represents a signed beacon block in an E2 file
+ *
+ * @param signedBeaconBlock The signed beacon block
+ * @param slot The slot number
+ */
+public record E2SignedBeaconBlock(byte[] signedBeaconBlock, int slot) {}

util/src/main/java/org/hyperledger/besu/util/e2/E2SlotIndex.java

@@ -16,20 +16,10 @@
 
 import java.util.List;
 
-public class E2SlotIndex {
-  private final long startingSlot;
-  private final List<Long> indexes;
-
-  public E2SlotIndex(final long startingSlot, final List<Long> indexes) {
-    this.startingSlot = startingSlot;
-    this.indexes = indexes;
-  }
-
-  public long getStartingSlot() {
-    return startingSlot;
-  }
-
-  public List<Long> getIndexes() {
-    return indexes;
-  }
-}
+/**
+ * Represents a slot index in an E2 file
+ *
+ * @param startingSlot The first slot number indexed by this slot index
+ * @param indexes The indexes of the slots indexed by this slot index
+ */
+public record E2SlotIndex(long startingSlot, List<Long> indexes) {}

util/src/main/java/org/hyperledger/besu/util/e2/E2StoreReaderListener.java

@@ -14,18 +14,54 @@
  */
 package org.hyperledger.besu.util.e2;
 
+/** A Listener interface for listening to an E2StoreReader */
 public interface E2StoreReaderListener {
+  /**
+   * Handles the supplied E2BeaconState
+   *
+   * @param beaconState the E2BeaconState
+   */
   void handleBeaconState(E2BeaconState beaconState);
 
+  /**
+   * Handles the supplied E2SlotIndex
+   *
+   * @param slotIndex the E2SlotIndex
+   */
   void handleSlotIndex(E2SlotIndex slotIndex);
 
+  /**
+   * Handles the supplied E2SignedBeaconBlock
+   *
+   * @param signedBeaconBlock the E2SignedBeaconBlock
+   */
   void handleSignedBeaconBlock(E2SignedBeaconBlock signedBeaconBlock);
 
+  /**
+   * Handles the supplied E2ExecutionBlockHeader
+   *
+   * @param executionBlockHeader the E2ExecutionBlockHeader
+   */
   void handleExecutionBlockHeader(E2ExecutionBlockHeader executionBlockHeader);
 
+  /**
+   * Handles the supplied E2ExecutionBlockBody
+   *
+   * @param executionBlockBody the E2ExecutionBlockBody
+   */
   void handleExecutionBlockBody(E2ExecutionBlockBody executionBlockBody);
 
+  /**
+   * Handles the supplied E2ExecutionBlockReceipts
+   *
+   * @param executionBlockReceipts the E2ExecutionBlockReceipts
+   */
   void handleExecutionBlockReceipts(E2ExecutionBlockReceipts executionBlockReceipts);
 
+  /**
+   * Handles the supplied E2BlockIndex
+   *
+   * @param blockIndex the E2BlockIndex
+   */
   void handleBlockIndex(E2BlockIndex blockIndex);
 }

util/src/main/java/org/hyperledger/besu/util/e2/E2Type.java

@@ -16,17 +16,29 @@
 
 import java.util.HexFormat;
 
+/** An enumeration of known sections of e2 store files */
 public enum E2Type {
+  /** An empty section */
   EMPTY(new byte[] {0x00, 0x00}),
+  /** A snappy compressed, SSZ encoded, signed beacon block */
   COMPRESSED_SIGNED_BEACON_BLOCK(new byte[] {0x01, 0x00}),
+  /** A snappy compressed, SSZ encoded, beacon state */
   COMPRESSED_BEACON_STATE(new byte[] {0x02, 0x00}),
+  /** A snappy compressed execution block header */
   COMPRESSED_EXECUTION_BLOCK_HEADER(new byte[] {0x03, 0x00}),
+  /** A snappy compressed execution block body */
   COMPRESSED_EXECUTION_BLOCK_BODY(new byte[] {0x04, 0x00}),
+  /** A snappy compressed list of execution block transaction receipts */
   COMPRESSED_EXECUTION_BLOCK_RECEIPTS(new byte[] {0x05, 0x00}),
+  /** The total difficulty */
   TOTAL_DIFFICULTY(new byte[] {0x06, 0x00}),
+  /** The accumulator */
   ACCUMULATOR(new byte[] {0x07, 0x00}),
+  /** A version section */
   VERSION(new byte[] {0x65, 0x32}),
+  /** An execution block index */
   BLOCK_INDEX(new byte[] {0x66, 0x32}),
+  /** A slot index */
   SLOT_INDEX(new byte[] {0x69, 0x32}),
   ;
   private final byte[] typeCode;
@@ -35,10 +47,22 @@ public enum E2Type {
     this.typeCode = typeCode;
   }
 
+  /**
+   * Gets the type code
+   *
+   * @return the type code
+   */
   public byte[] getTypeCode() {
     return typeCode;
   }
 
+  /**
+   * Gets the E2Type corresponding to the supplied typeCode
+   *
+   * @param typeCode the typeCode to find the corresponding E2Type for
+   * @return the E2Type corresponding to the supplied typeCode
+   * @throws IllegalArgumentException if there is no E2Type corresponding to the supplied typeCode
+   */
   public static E2Type getForTypeCode(final byte[] typeCode) {
     if (typeCode == null || typeCode.length != 2) {
       throw new IllegalArgumentException("typeCode must be 2 bytes");

util/src/main/java/org/hyperledger/besu/util/io/E2StoreReader.java

@@ -38,6 +38,7 @@
 import org.slf4j.LoggerFactory;
 import org.xerial.snappy.SnappyFramedInputStream;
 
+/** Reads E2 store file such a .era and .era1 */
 public class E2StoreReader {
   private static final Logger LOG = LoggerFactory.getLogger(E2StoreReader.class);
   private static final int TYPE_LENGTH = 2;
@@ -48,10 +49,24 @@ public class E2StoreReader {
 
   private final SnappyFactory snappyFactory;
 
+  /**
+   * Creates a new E2StoreReader with the supplied SnappyFactory
+   *
+   * @param snappyFactory A factory to provide objects for snappy decompression
+   */
   public E2StoreReader(final SnappyFactory snappyFactory) {
     this.snappyFactory = snappyFactory;
   }
 
+  /**
+   * Reads the entire supplied InputStream, calling appropriate methods on the supplied
+   * E2StoreReaderListener as different parts of the file are read
+   *
+   * @param inputStream The InputStream
+   * @param listener the E2StoreReaderListener
+   * @throws IOException If there are any problems reading from the InputStream, or creating and
+   *     using other streams, such as a SnappyFramedInputStream
+   */
   public void read(final InputStream inputStream, final E2StoreReaderListener listener)
       throws IOException {
     int slot = 0;

util/src/main/java/org/hyperledger/besu/util/snappy/SnappyFactory.java

@@ -19,8 +19,19 @@
 
 import org.xerial.snappy.SnappyFramedInputStream;
 
+/** A Factory for producing objects related to handling snappy compressed data */
 public class SnappyFactory {
 
+  /** Creates a SnappyFactory */
+  public SnappyFactory() {}
+
+  /**
+   * Creates a SnappyFramedInputStream reading from the supplied compressedData
+   *
+   * @param compressedData The data for the SnappyFramedInputStream to read
+   * @return a SnappyFramedInputStream reading from the supplied compressedData
+   * @throws IOException if the SnappyFramedInputStream is unable to be created
+   */
   public SnappyFramedInputStream createFramedInputStream(final byte[] compressedData)
       throws IOException {
     return new SnappyFramedInputStream(new ByteArrayInputStream(compressedData));