Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: migrate preconditions to use non-null error messages #415

Merged
merged 6 commits into from
Dec 18, 2024
Merged

chore: migrate preconditions to use non-null error messages #415

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d6e3e38
partial migration
ata-nas Dec 17, 2024
c36216f
partial migration
ata-nas Dec 17, 2024
564fe3b
cleanup
ata-nas Dec 17, 2024
809c5fb
tests now support verification of default error messages
ata-nas Dec 17, 2024
3612434
fix test error messages to check for
ata-nas Dec 17, 2024
ee0e40f
addressing pr comments for javadocs
ata-nas Dec 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
200 changes: 98 additions & 102 deletions common/src/main/java/com/hedera/block/common/utils/Preconditions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,25 +16,36 @@

package com.hedera.block.common.utils;

import java.util.Objects;
import edu.umd.cs.findbugs.annotations.NonNull;

/** A utility class used to assert various preconditions. */
public final class Preconditions { // @todo(381) change the APIs to accept non-null error messages
public final class Preconditions {
private static final String DEFAULT_NOT_BLANK_MESSAGE = "The input String is required to be non-blank.";
private static final String DEFAULT_REQUIRE_POSITIVE_MESSAGE = "The input number [%d] is required to be positive.";
private static final String DEFAULT_GT_OR_EQ_MESSAGE =
"The input number [%d] is required to be greater or equal than [%d].";
private static final String DEFAULT_REQUIRE_IN_RANGE_MESSAGE =
"The input number [%d] is required to be in the range [%d, %d] boundaries included.";
private static final String DEFAULT_REQUIRE_WHOLE_MESSAGE =
"The input number [%d] is required to be a whole number.";
private static final String DEFAULT_REQUIRE_POWER_OF_TWO_MESSAGE =
"The input number [%d] is required to be a power of two.";

/**
* 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}.
jsync-swirlds marked this conversation as resolved.
Show resolved Hide resolved
*
* @param toCheck a {@link String} to be checked if is blank as defined
* above
* above
* @return the {@link String} to be checked if it is not blank as defined
* above
* above
* @throws IllegalArgumentException if the input {@link String} to be
* checked is blank
* checked is blank
jsync-swirlds marked this conversation as resolved.
Show resolved Hide resolved
*/
public static String requireNotBlank(final String toCheck) {
return requireNotBlank(toCheck, null);
return requireNotBlank(toCheck, DEFAULT_NOT_BLANK_MESSAGE);
}

/**
Expand All @@ -43,21 +54,18 @@ public static String requireNotBlank(final String toCheck) {
* {@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
* @param toCheck a {@link String} to be checked if is blank as defined
* above
* @param errorMessage the error message to be used if the precondition
* check fails, must not be {@code null}
* @return the {@link String} to be checked if it is not blank as defined
* above
* above
* @throws IllegalArgumentException if the input {@link String} to be
* checked is blank
* checked is blank
*/
public static String requireNotBlank(final String toCheck, final String errorMessage) {
public static String requireNotBlank(final String toCheck, @NonNull 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);
throw new IllegalArgumentException(errorMessage);
} else {
return toCheck;
}
Expand All @@ -70,31 +78,28 @@ public static String requireNotBlank(final String toCheck, final String errorMes
* @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
* positive
*/
public static int requirePositive(final int toCheck) {
return requirePositive(toCheck, null);
return requirePositive(toCheck, DEFAULT_REQUIRE_POSITIVE_MESSAGE);
}

/**
* 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
* @param toCheck the integer to check if it is a positive power of two
* @param errorMessage a formatted string with one decimal parameters for
* {@code toCheck}, must not be {@code null}.<br/>
* Example error message: {@code "The input number (%d) must be positive."}
* @return the number to check if it is positive
* @throws IllegalArgumentException if the input number to check is not
* positive
* @throws IllegalArgumentException if the input integer to check is not
* positive
* @see java.util.Formatter for more information on error message formatting
*/
public static int requirePositive(final int toCheck, final String errorMessage) {
public static int requirePositive(final int toCheck, @NonNull 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);
throw new IllegalArgumentException(errorMessage.formatted(toCheck));
} else {
return toCheck;
}
Expand All @@ -107,39 +112,36 @@ public static int requirePositive(final int toCheck, final String errorMessage)
* @param toCheck the long to check if it is a positive power of two
* @return the long to check if it is positive
* @throws IllegalArgumentException if the input long to check is not
* positive
* positive
*/
public static long requirePositive(final long toCheck) {
return requirePositive(toCheck, null);
return requirePositive(toCheck, DEFAULT_REQUIRE_POSITIVE_MESSAGE);
}

/**
* This method asserts a given long is a positive. A long is positive
* if it is NOT equal to zero and is greater than zero.
*
* @param toCheck the long to check if it is a positive power of two
* @param errorMessage the error message to be used in the exception if the
* input long to check is not positive, if null, a default
* message will
* be used
* @return the long to check if it is positive
* @param toCheck the long to check if it is a positive power of two
* @param errorMessage a formatted string with one decimal parameters for
* {@code toCheck}, must not be {@code null}.<br/>
* Example error message: {@code "The input number (%d) must be positive."}
jsync-swirlds marked this conversation as resolved.
Show resolved Hide resolved
* @return the number to check if it is positive
* @throws IllegalArgumentException if the input long to check is not
* positive
* positive
* @see java.util.Formatter for more information on error message formatting
*/
public static long requirePositive(final long toCheck, final String errorMessage) {
public static long requirePositive(final long toCheck, @NonNull final String errorMessage) {
if (0L >= toCheck) {
final String message = Objects.isNull(errorMessage)
? "The input long [%d] is required be positive.".formatted(toCheck)
: errorMessage;
throw new IllegalArgumentException(message);
throw new IllegalArgumentException(errorMessage.formatted(toCheck));
} else {
return toCheck;
}
}

/**
* Ensures that a given long value is greater than or equal to a specified base
* value.
* Ensures that a given long value is greater than or equal to a specified
* base value.
* If the value does not meet the requirement, an
* {@link IllegalArgumentException} is thrown.
*
Expand All @@ -152,37 +154,37 @@ public static long requirePositive(final long toCheck, final String errorMessage
* @param toTest the long value to test
* @param base the base value to compare against
* @return the input {@code toTest} if it is greater than or equal to
* {@code base}
* @throws IllegalArgumentException if {@code toTest} is less than {@code base}
* {@code base}
* @throws IllegalArgumentException if {@code toTest} is less than
* {@code base}
*/
public static long requireGreaterOrEqual(final long toTest, final long base) {
return requireGreaterOrEqual(toTest, base, null);
return requireGreaterOrEqual(toTest, base, DEFAULT_GT_OR_EQ_MESSAGE);
}

/**
* Ensures that a given long value is greater than or equal to a specified base
* value.
* Ensures that a given long value is greater than or equal to a specified
* base value.
* If the value does not meet the requirement, an
* {@link IllegalArgumentException} is thrown.
*
* @param toTest the long value to test
* @param base the base value to compare against
* @param errorMessage the error message to include in the exception if the
* check fails;
* if {@code null}, a default message is used
* @return the input {@code toTest} if it is greater than or equal to
* {@code base}
* @throws IllegalArgumentException if {@code toTest} is less than {@code base}
* @param toTest the long value to test
* @param base the base value to compare against
* @param errorMessage a formatted string with two decimal parameters for
* {@code toTest} and {@code base}, must not be {@code null}.<br/>
* Example error message: {@code "The input number (%d) must be '>=' than
* (%d)."}
* @return the number to check if it is greater than or equal to the base
* @throws IllegalArgumentException if the input long toTest is not greater
* than or equal to the base
* @see java.util.Formatter for more information on error message formatting
*/
public static long requireGreaterOrEqual(final long toTest, final long base, final String errorMessage) {
public static long requireGreaterOrEqual(final long toTest, final long base, @NonNull final String errorMessage) {
if (toTest >= base) {
return toTest;
} else {
throw new IllegalArgumentException(errorMessage.formatted(toTest, base));
}

final String message = Objects.isNull(errorMessage)
? "The input integer [%d] is required be greater or equal than [%d].".formatted(toTest, base)
: errorMessage;
throw new IllegalArgumentException(message);
}

/**
Expand All @@ -198,7 +200,7 @@ public static long requireGreaterOrEqual(final long toTest, final long base, fin
* @throws IllegalArgumentException if the input int does not pass the test
*/
public static int requireInRange(final int toCheck, final int lowerBoundary, final int upperBoundary) {
return requireInRange(toCheck, lowerBoundary, upperBoundary, null);
return requireInRange(toCheck, lowerBoundary, upperBoundary, DEFAULT_REQUIRE_IN_RANGE_MESSAGE);
}

/**
Expand All @@ -209,23 +211,22 @@ public static int requireInRange(final int toCheck, final int lowerBoundary, fin
* @param toCheck the int value to check
* @param lowerBoundary the lower boundary
* @param upperBoundary the upper boundary
* @param errorMessage the error message to be used in the exception if the
* input int to test is not within the range, if null, a default message
* will be used
* @param errorMessage a formatted string with three decimal parameters for
* {@code toTest}, {@code upperBoundary} and {@code lowerBoundary}, must not
* be {@code null}.<br/>
* Example error message: {@code "The input number (%d) must be between
* (%d) and (%d)."}
* @return the input {@code toCheck} if it is within the range (boundaries
* included)
* @throws IllegalArgumentException if the input int does not pass the test
* @see java.util.Formatter for more information on error message formatting
*/
public static int requireInRange(
final int toCheck, final int lowerBoundary, final int upperBoundary, final String errorMessage) {
final int toCheck, final int lowerBoundary, final int upperBoundary, @NonNull final String errorMessage) {
if (toCheck >= lowerBoundary && toCheck <= upperBoundary) {
return toCheck;
} else {
final String message = Objects.isNull(errorMessage)
? "The input int [%d] is required to be in the range [%d, %d] boundaries included."
.formatted(toCheck, lowerBoundary, upperBoundary)
: errorMessage;
throw new IllegalArgumentException(message);
throw new IllegalArgumentException(errorMessage.formatted(toCheck, lowerBoundary, upperBoundary));
}
}

Expand All @@ -236,33 +237,30 @@ public static int requireInRange(
* @param toCheck the long to check if it is a whole number
* @return the number to check if it is whole number
* @throws IllegalArgumentException if the input number to check is not
* positive
* positive
*/
public static long requireWhole(final long toCheck) {
return requireWhole(toCheck, null);
return requireWhole(toCheck, DEFAULT_REQUIRE_WHOLE_MESSAGE);
}

/**
* This method asserts a given long is a whole number. A long is whole
* if it is greater or equal to zero.
*
* @param toCheck the long to check if it is a whole number
* @param errorMessage the error message to be used in the exception if the
* input long to check is not a whole number, if null, a
* default message will
* be used
* @param toCheck the long to check if it is a whole number
* @param errorMessage a formatted string with one decimal parameters for
* {@code toCheck}, must not be {@code null}.<br/>
* Example error message: {@code "The input number (%d) must be whole."}
* @return the number to check if it is whole number
* @throws IllegalArgumentException if the input number to check is not
* positive
* positive
* @see java.util.Formatter for more information on error message formatting
*/
public static long requireWhole(final long toCheck, final String errorMessage) {
public static long requireWhole(final long toCheck, @NonNull final String errorMessage) {
if (toCheck >= 0) {
return toCheck;
} else {
final String message = Objects.isNull(errorMessage)
? "The input integer [%d] is required be whole.".formatted(toCheck)
: errorMessage;
throw new IllegalArgumentException(message);
throw new IllegalArgumentException(errorMessage.formatted(toCheck));
}
}

Expand All @@ -272,30 +270,28 @@ public static long requireWhole(final long toCheck, final String errorMessage) {
* @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
* power of two
*/
public static int requirePowerOfTwo(final int toCheck) {
return requirePowerOfTwo(toCheck, null);
return requirePowerOfTwo(toCheck, DEFAULT_REQUIRE_POWER_OF_TWO_MESSAGE);
}

/**
* 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
* @param toCheck the number to check if it is a power of two
* @param errorMessage a formatted string with one decimal parameter for
* {@code toCheck}, must not be {@code null}.<br/>
* Example error message: {@code "The input number (%d) must be 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
* power of two
* @see java.util.Formatter for more information on error message formatting
*/
public static int requirePowerOfTwo(final int toCheck, final String errorMessage) {
public static int requirePowerOfTwo(final int toCheck, @NonNull 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);
throw new IllegalArgumentException(errorMessage.formatted(toCheck));
} else {
return toCheck;
}
Expand Down
Loading
Loading