refactor: implement agreed upon changes based on discussion (#266)

common/src/main/java/com/hedera/block/common/utils/FileUtilities.java

@@ -97,7 +97,7 @@ public static void createFolderPathIfNotExists(
         Objects.requireNonNull(toCreate);
         Objects.requireNonNull(logLevel);
         Objects.requireNonNull(permissions);
-        StringUtilities.requireNotBlank(semanticPathName);
+        Preconditions.requireNotBlank(semanticPathName);
         if (Files.notExists(toCreate)) {
             Files.createDirectories(toCreate, permissions);
             final String logMessage = "Created [%s] at '%s'".formatted(semanticPathName, toCreate);

common/src/main/java/com/hedera/block/common/utils/MathUtilities.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright (C) 2024 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.block.common.utils;
+
+/**
+ * A utility class that deals with logic related to Mathematics.
+ */
+public final class MathUtilities {
+    /**
+     * This method checks if the given number is a power of two.
+     *
+     * @param toCheck the number to check if it is a power of two
+     * @return {@code true} if the given number is a power of two
+     */
+    public static boolean isPowerOfTwo(final int toCheck) {
+        // mathematically powers of two are always positive numbers, so if the
+        // input is negative or zero, it is not a power of two, and we do not
+        // need to trigger the second check, hence we return false immediately
+        // by short-circuiting the logical AND operation
+        return (0 < toCheck) && ((toCheck & (toCheck - 1)) == 0);
+    }
+
+    private MathUtilities() {}
+}

common/src/main/java/com/hedera/block/common/utils/Preconditions.java

@@ -0,0 +1,136 @@
+/*
+ * Copyright (C) 2024 Hedera Hashgraph, LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.hedera.block.common.utils;
+
+import java.util.Objects;
+
+/** A utility class used to assert various preconditions. */
+public final class Preconditions {
+    /**
+     * This method asserts a given {@link String} is not blank, meaning it is
+     * not {@code null} or does not contain only whitespaces as defined by
+     * {@link String#isBlank()}. If the given {@link String} is not blank, then
+     * we return it, else we throw {@link IllegalArgumentException}.
+     *
+     * @param toCheck a {@link String} to be checked if is blank as defined
+     * above
+     * @return the {@link String} to be checked if it is not blank as defined
+     * above
+     * @throws IllegalArgumentException if the input {@link String} to be
+     * checked is blank
+     */
+    public static String requireNotBlank(final String toCheck) {
+        return requireNotBlank(toCheck, null);
+    }
+
+    /**
+     * This method asserts a given {@link String} is not blank, meaning it is
+     * not {@code null} or does not contain only whitespaces as defined by
+     * {@link String#isBlank()}. If the given {@link String} is not blank, then
+     * we return it, else we throw {@link IllegalArgumentException}.
+     *
+     * @param toCheck a {@link String} to be checked if is blank as defined
+     * above
+     * @param errorMessage the error message to be used in the exception if the
+     * input {@link String} to be checked is blank, if null, a default message
+     * @return the {@link String} to be checked if it is not blank as defined
+     * above
+     * @throws IllegalArgumentException if the input {@link String} to be
+     * checked is blank
+     */
+    public static String requireNotBlank(final String toCheck, final String errorMessage) {
+        if (StringUtilities.isBlank(toCheck)) {
+            final String message =
+                    Objects.isNull(errorMessage) ? "The input String is required to be non-blank." : errorMessage;
+            throw new IllegalArgumentException(message);
+        } else {
+            return toCheck;
+        }
+    }
+
+    /**
+     * This method asserts a given integer is a positive. An integer is positive
+     * if it is NOT equal to zero and is greater than zero.
+     *
+     * @param toCheck the number to check if it is a positive power of two
+     * @return the number to check if it is positive
+     * @throws IllegalArgumentException if the input number to check is not
+     * positive
+     */
+    public static int requirePositive(final int toCheck) {
+        return requirePositive(toCheck, null);
+    }
+
+    /**
+     * This method asserts a given integer is a positive. An integer is positive
+     * if it is NOT equal to zero and is greater than zero.
+     *
+     * @param toCheck the integer to check if it is a positive power of two
+     * @param errorMessage the error message to be used in the exception if the
+     * input integer to check is not positive, if null, a default message will
+     * be used
+     * @return the number to check if it is positive
+     * @throws IllegalArgumentException if the input number to check is not
+     * positive
+     */
+    public static int requirePositive(final int toCheck, final String errorMessage) {
+        if (0 >= toCheck) {
+            final String message = Objects.isNull(errorMessage)
+                    ? "The input integer [%d] is required be positive.".formatted(toCheck)
+                    : errorMessage;
+            throw new IllegalArgumentException(message);
+        } else {
+            return toCheck;
+        }
+    }
+
+    /**
+     * This method asserts a given integer is a power of two.
+     *
+     * @param toCheck the number to check if it is a power of two
+     * @return the number to check if it is a power of two
+     * @throws IllegalArgumentException if the input number to check is not a
+     * power of two
+     */
+    public static int requirePowerOfTwo(final int toCheck) {
+        return requirePowerOfTwo(toCheck, null);
+    }
+
+    /**
+     * This method asserts a given integer is a power of two.
+     *
+     * @param toCheck the number to check if it is a power of two
+     * @param errorMessage the error message to be used in the exception if the
+     * input integer to check is not a power of two, if null, a default message
+     * will be used
+     * @return the number to check if it is a power of two
+     * @throws IllegalArgumentException if the input number to check is not a
+     * power of two
+     */
+    public static int requirePowerOfTwo(final int toCheck, final String errorMessage) {
+        if (!MathUtilities.isPowerOfTwo(toCheck)) {
+            final String message = Objects.isNull(errorMessage)
+                    ? "The input integer [%d] is required to be a power of two.".formatted(toCheck)
+                    : errorMessage;
+            throw new IllegalArgumentException(message);
+        } else {
+            return toCheck;
+        }
+    }
+
+    private Preconditions() {}
+}

common/src/main/java/com/hedera/block/common/utils/StringUtilities.java

@@ -16,26 +16,23 @@
 
 package com.hedera.block.common.utils;
 
-import edu.umd.cs.findbugs.annotations.NonNull;
 import java.util.Objects;
 
 /** A utility class that deals with logic related to Strings. */
 public final class StringUtilities {
     /**
-     * This method checks if a given {@link String} is blank, meaning if it is {@code null} or
-     * contains only whitespaces as defined by {@link String#isBlank()}. If the given {@link String}
-     * is not blank, then we return it, else we throw {@link IllegalArgumentException}.
+     * This method takes an input {@link String} and checks if it is blank.
+     * A {@link String} is considered blank if it is either {@code null} or
+     * contains only whitespace characters as defined by
+     * {@link String#isBlank()}.
      *
-     * @param toCheck a {@link String} to be checked if is blank as defined above
-     * @return the {@link String} to be checked if it is not blank as defined above
-     * @throws IllegalArgumentException if the input {@link String} to be checked is blank
+     * @param toCheck a {@link String} to check if it is blank
+     * @return {@code true} if the given {@link String} to check is either
+     * {@code null} or contains only whitespace characters, {@code false}
+     * otherwise
      */
-    public static String requireNotBlank(@NonNull final String toCheck) {
-        if (Objects.requireNonNull(toCheck).isBlank()) {
-            throw new IllegalArgumentException("A String required to be non-blank is blank.");
-        } else {
-            return toCheck;
-        }
+    public static boolean isBlank(final String toCheck) {
+        return Objects.isNull(toCheck) || toCheck.isBlank();
     }
 
     private StringUtilities() {}