fix: renamed metrics member variables and javadoc

Signed-off-by: Matt Peterson <[email protected]>

server/src/main/java/com/hedera/block/server/BlockStreamService.java

@@ -107,9 +107,9 @@ public String serviceName() {
     }
 
     /**
-     * Updates the routing for the BlockStreamService. It sets up the bidirectional streaming method
-     * for publishBlockStream, server streaming method for subscribeBlockStream and a unary method
-     * for singleBlock.
+     * Updates the routing definitions for the BlockStreamService. It establishes the bidirectional
+     * streaming method for publishBlockStream, server streaming method for subscribeBlockStream and
+     * a unary method for singleBlock.
      *
      * @param routing the routing for the BlockStreamService
      */
@@ -272,7 +272,7 @@ void singleBlock(
 
                     @NonNull
                     final MetricsService metricsService = blockNodeContext.metricsService();
-                    metricsService.singleBlockRetrievedCounter.increment();
+                    metricsService.singleBlocksRetrieved.increment();
                 } else {
                     LOGGER.log(
                             System.Logger.Level.DEBUG, "Block number {0} not found", blockNumber);

server/src/main/java/com/hedera/block/server/Server.java

@@ -74,8 +74,8 @@ public static void main(final String[] args) {
                             .build();
             @NonNull
             final StreamMediator<BlockItem, ObjectEvent<SubscribeStreamResponse>> streamMediator =
-                    LiveStreamMediatorBuilder.newBuilder(blockWriter, blockNodeContext)
-                            .serviceStatus(serviceStatus)
+                    LiveStreamMediatorBuilder.newBuilder(
+                                    blockWriter, blockNodeContext, serviceStatus)
                             .build();
 
             @NonNull

server/src/main/java/com/hedera/block/server/mediator/LiveStreamMediatorBuilder.java

@@ -20,7 +20,6 @@
 import static com.hedera.block.protos.BlockStreamService.SubscribeStreamResponse;
 
 import com.hedera.block.server.ServiceStatus;
-import com.hedera.block.server.ServiceStatusImpl;
 import com.hedera.block.server.config.BlockNodeContext;
 import com.hedera.block.server.data.ObjectEvent;
 import com.hedera.block.server.persistence.storage.write.BlockWriter;
@@ -41,49 +40,43 @@
 public class LiveStreamMediatorBuilder {
 
     private final BlockWriter<BlockItem> blockWriter;
-    private ServiceStatus serviceStatus;
+    private final BlockNodeContext blockNodeContext;
+    private final ServiceStatus serviceStatus;
+
     private Map<
                     EventHandler<ObjectEvent<SubscribeStreamResponse>>,
                     BatchEventProcessor<ObjectEvent<SubscribeStreamResponse>>>
             subscribers;
-    private final BlockNodeContext blockNodeContext;
 
+    /** The initial capacity of the subscriber map. */
     private static final int SUBSCRIBER_INIT_CAPACITY = 32;
 
     private LiveStreamMediatorBuilder(
             @NonNull final BlockWriter<BlockItem> blockWriter,
-            @NonNull final BlockNodeContext blockNodeContext) {
+            @NonNull final BlockNodeContext blockNodeContext,
+            @NonNull final ServiceStatus serviceStatus) {
         this.subscribers = new ConcurrentHashMap<>(SUBSCRIBER_INIT_CAPACITY);
-        this.serviceStatus = new ServiceStatusImpl();
         this.blockWriter = blockWriter;
         this.blockNodeContext = blockNodeContext;
+        this.serviceStatus = serviceStatus;
     }
 
     /**
      * Create a new instance of the builder using the minimum required parameters.
      *
-     * @param blockWriter is required for the stream mediator to persist block items to storage
+     * @param blockWriter is required for the stream mediator to persist block items to storage.
      * @param blockNodeContext is required to provide metrics reporting mechanisms to the stream
-     *     mediator
-     * @return a new instance of the {@link LiveStreamMediatorBuilder}
+     *     mediator.
+     * @param serviceStatus is required to provide the stream mediator with access to check the
+     *     status of the server and to stop the web server if necessary.
+     * @return a new stream mediator builder configured with required parameters.
      */
     @NonNull
     public static LiveStreamMediatorBuilder newBuilder(
             @NonNull final BlockWriter<BlockItem> blockWriter,
-            @NonNull final BlockNodeContext blockNodeContext) {
-        return new LiveStreamMediatorBuilder(blockWriter, blockNodeContext);
-    }
-
-    /**
-     * Provide a non-default service status to the stream mediator.
-     *
-     * @param serviceStatus is the service status to set
-     * @return the builder
-     */
-    @NonNull
-    public LiveStreamMediatorBuilder serviceStatus(@NonNull final ServiceStatus serviceStatus) {
-        this.serviceStatus = serviceStatus;
-        return this;
+            @NonNull final BlockNodeContext blockNodeContext,
+            @NonNull final ServiceStatus serviceStatus) {
+        return new LiveStreamMediatorBuilder(blockWriter, blockNodeContext, serviceStatus);
     }
 
     /**
@@ -110,7 +103,7 @@ public LiveStreamMediatorBuilder subscribers(
      * Use the build method to construct a stream mediator to handle live stream events from a
      * producer to N consumers.
      *
-     * @return the stream mediator
+     * @return the stream mediator to handle live stream events between a producer and N consumers.
      */
     @NonNull
     public StreamMediator<BlockItem, ObjectEvent<SubscribeStreamResponse>> build() {

server/src/main/java/com/hedera/block/server/mediator/LiveStreamMediatorImpl.java

@@ -117,7 +117,7 @@ public void publish(@NonNull final BlockItem blockItem) throws IOException {
 
             // Increment the block item counter
             @NonNull final MetricsService metricsService = blockNodeContext.metricsService();
-            metricsService.liveBlockItemCounter.increment();
+            metricsService.liveBlockItems.increment();
 
             try {
                 // Persist the BlockItem
@@ -208,7 +208,7 @@ private static SubscribeStreamResponse buildEndStreamResponse() {
 
     private void updateSubscriberMetrics() {
         @NonNull final MetricsService metricsService = blockNodeContext.metricsService();
-        @NonNull final LongGauge longGauge = metricsService.subscriberGauge;
+        @NonNull final LongGauge longGauge = metricsService.subscribers;
         longGauge.set(subscribers.size());
     }
 }

server/src/main/java/com/hedera/block/server/metrics/MetricsService.java

@@ -21,6 +21,12 @@
 import com.swirlds.metrics.api.Metrics;
 import edu.umd.cs.findbugs.annotations.NonNull;
 
+/**
+ * Use member variables of this class to update metric data for the Hedera Block Node.
+ *
+ * <p>Metrics are updated by calling the appropriate method on the metric object instance. For
+ * example, to increment a counter, call {@link Counter#increment()}.
+ */
 public class MetricsService {
 
     private static final String CATEGORY = "hedera_block_node";
@@ -54,23 +60,23 @@ public class MetricsService {
     /** An example counter. */
     public final Counter exampleCounter;
 
-    public final Counter liveBlockItemCounter;
-    public final Counter blockPersistenceCounter;
-    public final Counter singleBlockRetrievedCounter;
-    public final LongGauge subscriberGauge;
+    public final Counter liveBlockItems;
+    public final Counter blocksPersisted;
+    public final Counter singleBlocksRetrieved;
+    public final LongGauge subscribers;
 
     /**
-     * Creates a new instance of {@link MetricsService}.
+     * Create singleton instance of metrics service to be used throughout the application.
      *
      * @param metrics the metrics instance
      */
     public MetricsService(@NonNull final Metrics metrics) {
         this.exampleGauge = metrics.getOrCreate(EXAMPLE_GAUGE);
         this.exampleCounter = metrics.getOrCreate(EXAMPLE_COUNTER);
 
-        this.liveBlockItemCounter = metrics.getOrCreate(LIVE_BLOCK_ITEM_COUNTER);
-        this.blockPersistenceCounter = metrics.getOrCreate(BLOCK_PERSISTENCE_COUNTER);
-        this.singleBlockRetrievedCounter = metrics.getOrCreate(SINGLE_BLOCK_RETRIEVED_COUNTER);
-        this.subscriberGauge = metrics.getOrCreate(SUBSCRIBER_GAUGE);
+        this.liveBlockItems = metrics.getOrCreate(LIVE_BLOCK_ITEM_COUNTER);
+        this.blocksPersisted = metrics.getOrCreate(BLOCK_PERSISTENCE_COUNTER);
+        this.singleBlocksRetrieved = metrics.getOrCreate(SINGLE_BLOCK_RETRIEVED_COUNTER);
+        this.subscribers = metrics.getOrCreate(SUBSCRIBER_GAUGE);
     }
 }

server/src/main/java/com/hedera/block/server/persistence/storage/Util.java

@@ -22,11 +22,15 @@
 import java.nio.file.attribute.PosixFilePermissions;
 import java.util.Set;
 
-/** Utility class for storage. */
+/** Util methods provide common functionality for the storage package. */
 public final class Util {
     private Util() {}
 
-    /** Default file permissions. Default permissions: rwxr-xr-x */
+    /**
+     * Default file permissions defines the file and directory for the storage package.
+     *
+     * <p>Default permissions are set to: rwxr-xr-x
+     */
     @NonNull
     public static final FileAttribute<Set<PosixFilePermission>> defaultPerms =
             PosixFilePermissions.asFileAttribute(

server/src/main/java/com/hedera/block/server/persistence/storage/read/BlockAsDirReaderBuilder.java

@@ -25,6 +25,11 @@
 import java.nio.file.attribute.PosixFilePermission;
 import java.util.Set;
 
+/**
+ * Use builder methods to create a {@link BlockReader} to read blocks from storage.
+ *
+ * <p>When a block reader is created, it will provide access to read blocks from storage.
+ */
 public class BlockAsDirReaderBuilder {
 
     private final String key;
@@ -36,19 +41,43 @@ private BlockAsDirReaderBuilder(@NonNull final String key, @NonNull final Config
         this.config = config;
     }
 
+    /**
+     * Creates a new block reader builder using the minimum required parameters.
+     *
+     * @param key is required to read pertinent configuration info.
+     * @param config is required to supply pertinent configuration info for the block reader to
+     *     access storage.
+     * @return a block reader builder configured with required parameters.
+     */
     @NonNull
     public static BlockAsDirReaderBuilder newBuilder(
             @NonNull final String key, @NonNull final Config config) {
         return new BlockAsDirReaderBuilder(key, config);
     }
 
+    /**
+     * Optionally, provide file permissions for the block reader to use when managing block files
+     * and directories.
+     *
+     * <p>By default, the block reader will use the permissions defined in {@link
+     * Util#defaultPerms}. This method is primarily used for testing purposes. Default values should
+     * be sufficient for production use.
+     *
+     * @param filePerms the file permissions to use when managing block files and directories.
+     * @return a block reader builder configured with required parameters.
+     */
     @NonNull
     public BlockAsDirReaderBuilder filePerms(
             @NonNull final FileAttribute<Set<PosixFilePermission>> filePerms) {
         this.filePerms = filePerms;
         return this;
     }
 
+    /**
+     * Use the build method to construct a block reader to read blocks from storage.
+     *
+     * @return a new block reader configured with the parameters provided to the builder.
+     */
     @NonNull
     public BlockReader<Block> build() {
         return new BlockAsDirReader(key, config, filePerms);

server/src/main/java/com/hedera/block/server/persistence/storage/write/BlockAsDirWriter.java

@@ -59,7 +59,7 @@ class BlockAsDirWriter implements BlockWriter<BlockItem> {
      *
      * @param key the key to use to retrieve the block node root path from the config
      * @param config the config to use to retrieve the block node root path
-     * @param blockRemover the block remover to use to remove blocks if there's an exception while
+     * @param blockRemover the block remover to use to remove blocks if there is an exception while
      *     writing a partial block
      * @param filePerms the file permissions to set on the block node root path
      * @throws IOException if an error occurs while initializing the BlockAsDirWriter
@@ -179,7 +179,7 @@ private void resetState(@NonNull final BlockItem blockItem) throws IOException {
 
         // Increment the block counter
         @NonNull final MetricsService metricsService = blockNodeContext.metricsService();
-        metricsService.blockPersistenceCounter.increment();
+        metricsService.blocksPersisted.increment();
     }
 
     private void repairPermissions(@NonNull final Path path) throws IOException {

server/src/main/java/com/hedera/block/server/persistence/storage/write/BlockAsDirWriterBuilder.java

@@ -30,6 +30,11 @@
 import java.nio.file.attribute.PosixFilePermission;
 import java.util.Set;
 
+/**
+ * Use builder methods to create a {@link BlockWriter} to write blocks to storage.
+ *
+ * <p>When a block writer is created, it will provide access to write blocks to storage.
+ */
 public class BlockAsDirWriterBuilder {
 
     private final String key;
@@ -49,6 +54,15 @@ private BlockAsDirWriterBuilder(
                 new BlockAsDirRemover(Path.of(config.get(key).asString().get()), Util.defaultPerms);
     }
 
+    /**
+     * Creates a new block writer builder using the minimum required parameters.
+     *
+     * @param key is required to read pertinent configuration info.
+     * @param config is required to supply pertinent configuration info for the block writer to
+     *     access storage.
+     * @param blockNodeContext is required to provide metrics reporting mechanisms .
+     * @return a block writer builder configured with required parameters.
+     */
     @NonNull
     public static BlockAsDirWriterBuilder newBuilder(
             @NonNull final String key,
@@ -58,19 +72,46 @@ public static BlockAsDirWriterBuilder newBuilder(
         return new BlockAsDirWriterBuilder(key, config, blockNodeContext);
     }
 
+    /**
+     * Optionally, provide file permissions for the block writer to use when managing block files
+     * and directories.
+     *
+     * <p>By default, the block writer will use the permissions defined in {@link
+     * Util#defaultPerms}. This method is primarily used for testing purposes. Default values should
+     * be sufficient for production use.
+     *
+     * @param filePerms the file permissions to use when managing block files and directories.
+     * @return a block writer builder configured with required parameters.
+     */
     @NonNull
     public BlockAsDirWriterBuilder filePerms(
             @NonNull FileAttribute<Set<PosixFilePermission>> filePerms) {
         this.filePerms = filePerms;
         return this;
     }
 
+    /**
+     * Optionally, provide a block remover to remove blocks from storage.
+     *
+     * <p>By default, the block writer will use the block remover defined in {@link
+     * BlockAsDirRemover}. This method is primarily used for testing purposes. Default values should
+     * be sufficient for production use.
+     *
+     * @param blockRemover the block remover to use when removing blocks from storage.
+     * @return a block writer builder configured with required parameters.
+     */
     @NonNull
     public BlockAsDirWriterBuilder blockRemover(@NonNull BlockRemover blockRemover) {
         this.blockRemover = blockRemover;
         return this;
     }
 
+    /**
+     * Use the build method to construct a block writer to write blocks to storage.
+     *
+     * @return a new block writer configured with the parameters provided to the builder.
+     * @throws IOException when an error occurs while persisting block items to storage.
+     */
     @NonNull
     public BlockWriter<BlockItem> build() throws IOException {
         return new BlockAsDirWriter(key, config, blockRemover, filePerms, blockNodeContext);

server/src/main/java/com/hedera/block/server/persistence/storage/write/BlockWriter.java

@@ -20,17 +20,17 @@
 import java.io.IOException;
 
 /**
- * The BlockWriter interface defines the contract for writing a block to the storage.
+ * BlockWriter defines the contract for writing block items to storage.
  *
  * @param <V> the type of the block item to write
  */
 public interface BlockWriter<V> {
 
     /**
-     * Writes the block item to the storage.
+     * Write the block item to storage.
      *
-     * @param blockItem the block item to write
-     * @throws IOException if an I/O error occurs writing the block item
+     * @param blockItem the block item to write to storage.
+     * @throws IOException when failing to write the block item to storage.
      */
     void write(@NonNull final V blockItem) throws IOException;
 }

server/src/test/java/com/hedera/block/server/BlockStreamServiceIT.java

@@ -161,8 +161,7 @@ public void testSubscribeBlockStream() throws IOException {
 
         final BlockNodeContext blockNodeContext = BlockNodeContextFactory.create();
         final var streamMediator =
-                LiveStreamMediatorBuilder.newBuilder(blockWriter, blockNodeContext)
-                        .serviceStatus(serviceStatus)
+                LiveStreamMediatorBuilder.newBuilder(blockWriter, blockNodeContext, serviceStatus)
                         .build();
 
         // Build the BlockStreamService
@@ -193,7 +192,7 @@ public void testSubscribeBlockStream() throws IOException {
         streamObserver.onNext(publishStreamRequest);
 
         // Verify the counter was incremented
-        assertEquals(1, blockNodeContext.metricsService().liveBlockItemCounter.get());
+        assertEquals(1, blockNodeContext.metricsService().liveBlockItems.get());
 
         verify(blockWriter, timeout(testTimeout).times(1)).write(blockItems.getFirst());
 
@@ -597,8 +596,7 @@ private StreamMediator<BlockItem, ObjectEvent<SubscribeStreamResponse>> buildStr
         final ServiceStatus serviceStatus = new ServiceStatusImpl();
         serviceStatus.setWebServer(webServer);
 
-        return LiveStreamMediatorBuilder.newBuilder(blockWriter, blockNodeContext)
-                .serviceStatus(serviceStatus)
+        return LiveStreamMediatorBuilder.newBuilder(blockWriter, blockNodeContext, serviceStatus)
                 .subscribers(subscribers)
                 .build();
     }