Package rife.bld.extension.tools

Class ObjectTools

java.lang.Object
rife.bld.extension.tools.ObjectTools
@NullMarked public final class ObjectTools extends Object
Object Tools.

Unified utility methods for validating objects: emptiness-checking (arrays, collections, maps, and character sequences) and null/sign/range checks for Comparable values, including all require* guard methods.

Emptiness. Emptiness is defined for CharSequence, Collection, Map, and arrays. All other non-null objects are considered not empty. allEmpty(Object), allNotEmpty(Object), and the container-checking require* methods check containers recursively, up to 128 levels deep per branch (see MAX_NESTING_DEPTH). anyEmpty(Object) and anyNotEmpty(Object) check only the container's direct elements/entries — they do not descend into nested containers.

Map key checking: both keys and values are evaluated by emptiness predicates. Keys of non-container, non-CharSequence types (e.g. Integer, enum constants) are never considered empty, so a map with such keys never reports all keys as empty — this affects allEmpty(Object) and anyEmpty(Object).

Sign and range checks. requirePositive(Object, String), requireNegative(Object, String), and requireNonNegative(Object, String) work with any Comparable type that has a natural zero: Integer, Long, Double, Float, Short, Byte, BigInteger, and BigDecimal. For Double and Float, NaN is rejected by all three, and -0.0 is treated as equal to zero rather than negative.

Validation order: all require* methods throw NullPointerException first if the value (or, for container-checking overloads, any nested element) is null, then IllegalArgumentException if the value fails its specific check (empty, wrong sign, etc.).

For text-specific operations like blank-checking, see TextTools.

Since:
1.0
Author:
Erik C. Thauvin

  • Method Details

    • allEmpty

      public static boolean allEmpty(@Nullable Object value)
      Returns true if the value and all nested elements/entries are empty.

      For non-containers, equivalent to isEmpty(Object). For containers, returns true only if the container itself is empty, or every nested element/entry (checked recursively, see class docs) is null or empty.

      
 allEmpty(List.of());                           // true - vacuously
 allEmpty(List.of(List.of("", ""), List.of())); // true
 allEmpty(List.of("foo", "bar"));               // false
      Parameters:
      value - the value to inspect; may be null
      Returns:
      true if the value and all nested elements are null or empty
      Since:
      1.3
      API Note:
      An empty container vacuously satisfies this and returns true — the logical complement of requiring any element non-empty, not the inverse of allNotEmpty(Object) for empty containers. A null element is treated as empty.

    • allNotEmpty

      public static boolean allNotEmpty(@Nullable Object value)
      Returns true if the value and all nested elements/entries are not empty.

      For non-containers, equivalent to isNotEmpty(Object). For containers, the container itself and every nested element/entry (checked recursively, see class docs) must be not null and not empty.

      
 allNotEmpty(List.of("foo", "bar"));   // true
 allNotEmpty(List.of(List.of("")));    // false - nested element is empty
 allNotEmpty(List.of());               // false - empty container
      Parameters:
      value - the value to inspect; may be null
      Returns:
      true if the value and all nested elements are not null and not empty
      Since:
      1.3
      API Note:
      An empty container returns false — there are no non-empty elements to satisfy the condition. This is intentionally asymmetric with allEmpty(Object) for empty containers. A null element is treated as empty and causes this method to return false.

    • anyEmpty

      public static boolean anyEmpty(@Nullable Object value)
      Returns true if the value, or any of its direct elements/entries, is empty.

      For non-containers, equivalent to isEmpty(Object). For containers, only the direct elements/entries are checked — nested containers are not descended into (unlike allEmpty(Object)). See the class-level note on map key checking.

      Parameters:
      value - the value to inspect; may be null
      Returns:
      true if the value or any direct element is empty
      Since:
      1.3

    • anyNotEmpty

      public static boolean anyNotEmpty(@Nullable Object value)
      Returns true if the value, or any of its direct elements/entries, is not empty.

      For non-containers, equivalent to isNotEmpty(Object). For containers, only the direct elements/entries are checked — nested containers are not descended into (unlike allNotEmpty(Object)).

      Parameters:
      value - the value to inspect; may be null
      Returns:
      true if the value or any direct element is not empty
      Since:
      1.3

    • isEmpty

      public static boolean isEmpty(@Nullable Object value)
      Determines whether the given value is null or empty.

      For arrays, Collection, or Map, returns true only if the container itself is empty. To check elements as well, use allEmpty(Object).

      Parameters:
      value - the value to inspect; may be null
      Returns:
      true if the value is null or empty

    • isNotEmpty

      public static boolean isNotEmpty(@Nullable Object value)
      Determines whether the given value is not null and not empty.
      Parameters:
      value - the value to inspect; may be null
      Returns:
      true if the value is not null and not empty

    • requireEmpty

      @Contract("null, _ -> fail; !null, _ -> !null") @NullUnmarked public static <T extends @Nullable Object> @NonNull T requireEmpty(@Nullable T value, @NonNull String message)
      Requires the value to be empty (and, for containers, every element/entry to be empty).
      Type Parameters:
      T - the value type
      Parameters:
      value - the value to validate and return; must not be null
      message - the exception message; must not be null, empty, or blank
      Returns:
      the validated value
      Throws:
      NullPointerException - if the value or any element is null
      IllegalArgumentException - if the value is not empty
      IllegalArgumentException - if message is null, empty, or blank
      Since:
      1.3

    • requireEmpty

      @Contract("null, _ -> fail; !null, _ -> !null") @NullUnmarked public static <T extends @Nullable Object> @NonNull T requireEmpty(@Nullable T value, @NonNull Supplier<String> messageSupplier)
      Requires the value to be empty. See requireEmpty(Object, String).

      messageSupplier is invoked unconditionally, once, so its produced message is validated (non-null, non-blank) regardless of whether value passes.

      Type Parameters:
      T - the value type
      Parameters:
      value - the value to validate and return; must not be null
      messageSupplier - the supplier of the exception message; must not be null
      Returns:
      the validated value
      Throws:
      NullPointerException - if the value or any element is null
      IllegalArgumentException - if the value is not empty
      IllegalArgumentException - if messageSupplier produces a null, empty, or blank message
      Since:
      1.3

    • requireNegative

      @Contract("null, _ -> fail; !null, _ -> !null") @NullUnmarked public static <T extends @Nullable Object & Comparable<T>> @NonNull T requireNegative(@Nullable T value, @NonNull String context)
      Checks that the specified value is strictly negative. Works with any Comparable type that has a natural zero value: Integer, Long, Double, Float, Byte, Short, BigInteger, and BigDecimal.

      For Double and Float, NaN is rejected by all three require* sign-check methods, and -0.0 is treated as equal to zero rather than negative.

      Type Parameters:
      T - the type of the value, must implement Comparable
      Parameters:
      value - the value to check for negativity; must not be null
      context - the context string used in exception messages; must not be null, empty, or blank
      Returns:
      the validated value if it is less than zero
      Throws:
      NullPointerException - if value or context is null
      IllegalArgumentException - if context is empty, or blank
      IllegalArgumentException - if value is zero or positive
      IllegalArgumentException - if value is of an unsupported type
      Since:
      1.3

    • requireNegative

      @Contract("null, _ -> fail; !null, _ -> !null") @NullUnmarked public static <T extends @Nullable Object & Comparable<T>> @NonNull T requireNegative(@Nullable T value, @NonNull Supplier<String> messageSupplier)
      Checks that the specified value is strictly negative. See requireNegative(Object, String).
      Type Parameters:
      T - the type of the value, must implement Comparable
      Parameters:
      value - the value to check for negativity; must not be null
      messageSupplier - the supplier of the exception message; must not be null
      Returns:
      the validated value if it is less than zero
      Throws:
      NullPointerException - if value or messageSupplier is null
      IllegalArgumentException - if value is zero or positive
      IllegalArgumentException - if value is of an unsupported type
      Since:
      1.3

    • requireNonNegative

      @Contract("null, _ -> fail; !null, _ -> !null") @NullUnmarked public static <T extends @Nullable Object & Comparable<T>> @NonNull T requireNonNegative(@Nullable T value, @NonNull String context)
      Checks that the specified value is non-negative. See requireNegative(Object, String) for supported types.
      Type Parameters:
      T - the type of the value, must implement Comparable
      Parameters:
      value - the value to check for non-negativity; must not be null
      context - the context string used in exception messages; must not be null, empty, or blank
      Returns:
      the validated value if it is greater than or equal to zero
      Throws:
      NullPointerException - if value or context is null
      IllegalArgumentException - if context is empty, or blank
      IllegalArgumentException - if value is negative
      IllegalArgumentException - if value is of an unsupported type
      Since:
      1.3

    • requireNonNegative

      @Contract("null, _ -> fail; !null, _ -> !null") @NullUnmarked public static <T extends @Nullable Object & Comparable<T>> @NonNull T requireNonNegative(@Nullable T value, @NonNull Supplier<String> messageSupplier)
      Checks that the specified value is non-negative. See requireNonNegative(Object, String).
      Type Parameters:
      T - the type of the value, must implement Comparable
      Parameters:
      value - the value to check for non-negativity; must not be null
      messageSupplier - the supplier of the exception message; must not be null
      Returns:
      the validated value if it is greater than or equal to zero
      Throws:
      NullPointerException - if value or messageSupplier is null
      IllegalArgumentException - if value is negative
      IllegalArgumentException - if value is of an unsupported type
      Since:
      1.3

    • requireNonNull

      @Contract("null, _ -> fail; !null, _ -> !null") @NullUnmarked public static <T extends @Nullable Object> @NonNull T requireNonNull(@Nullable T value, @NonNull String context)
      Requires the value to be not null, and all elements/entries to be not null. Unlike requireNotEmpty(Object, String), empty containers are allowed as long as they contain no null elements. Nested containers are checked recursively (see class docs).
      Type Parameters:
      T - the value type
      Parameters:
      value - the value to validate and return; must not be null
      context - the context string used in exception message; must not be null, empty, or blank
      Returns:
      the validated value, never null
      Throws:
      NullPointerException - if the value is null or contains null elements
      NullPointerException - if context is null
      IllegalArgumentException - if context is empty, or blank
      Since:
      1.3

    • requireNonNull

      @Contract("null, _ -> fail; !null, _ -> !null") @NullUnmarked public static <T extends @Nullable Object> @NonNull T requireNonNull(@Nullable T value, @NonNull Supplier<String> messageSupplier)
      Requires the value to be not null, and all elements/entries to be not null. See requireNonNull(Object, String).

      Unlike the String overload, messageSupplier is invoked lazily — only when the value actually fails validation — so it is never evaluated on the success path.

      Type Parameters:
      T - the value type
      Parameters:
      value - the value to validate and return; must not be null
      messageSupplier - the supplier of the exception message; must not be null
      Returns:
      the validated value, never null
      Throws:
      NullPointerException - if the value is null or contains null elements
      NullPointerException - if messageSupplier is null
      Since:
      1.3

    • requireNotEmpty

      @Contract("null, _ -> fail; !null, _ -> !null") @NullUnmarked public static <T extends @Nullable Object> @NonNull T requireNotEmpty(@Nullable T value, @NonNull String context)
      Requires the value to be not null and not empty (and, for containers, every element/entry to be not null and not empty).

      Exception messages are constructed from context as "{context} must not be null" and "{context} must not be empty".

      Type Parameters:
      T - the value type
      Parameters:
      value - the value to validate and return; must not be null or empty
      context - the context string used in exception messages; must not be null, empty, or blank
      Returns:
      the validated value, never null or empty
      Throws:
      NullPointerException - if the value or any element is null
      IllegalArgumentException - if the value is empty
      NullPointerException - if context is null
      IllegalArgumentException - if context is empty, or blank
      Since:
      1.3

    • requireNotEmpty

      @Contract("null, _, _ -> fail; !null, _, _ -> !null") @NullUnmarked public static <T extends @Nullable Object> @NonNull T requireNotEmpty(@Nullable T value, @NonNull String nullMessage, @NonNull String emptyMessage)
      Requires the value to be not null and not empty. See requireNotEmpty(Object, String).
      Type Parameters:
      T - the value type
      Parameters:
      value - the value to validate and return; must not be null or empty
      nullMessage - the message for NullPointerException; must not be null, empty, or blank
      emptyMessage - the message for IllegalArgumentException; must not be null, empty, or blank
      Returns:
      the validated value, never null or empty
      Throws:
      NullPointerException - if the value or any element is null
      IllegalArgumentException - if the value is empty
      IllegalArgumentException - if either message is null, empty, or blank
      Since:
      1.3

    • requirePositive

      @Contract("null, _ -> fail; !null, _ -> !null") @NullUnmarked public static <T extends @Nullable Object & Comparable<T>> @NonNull T requirePositive(@Nullable T value, @NonNull String context)
      Checks that the specified value is strictly positive. See requireNegative(Object, String) for supported types.
      Type Parameters:
      T - the type of the value, must implement Comparable
      Parameters:
      value - the value to check for positivity; must not be null
      context - the context string used in exception messages; must not be null, empty, or blank
      Returns:
      the validated value if it is greater than zero
      Throws:
      NullPointerException - if value or context is null
      IllegalArgumentException - if context is empty, or blank
      IllegalArgumentException - if value is zero or negative
      IllegalArgumentException - if value is of an unsupported type
      Since:
      1.3

    • requirePositive

      @Contract("null, _ -> fail; !null, _ -> !null") @NullUnmarked public static <T extends @Nullable Object & Comparable<T>> @NonNull T requirePositive(@Nullable T value, @NonNull Supplier<String> messageSupplier)
      Checks that the specified value is strictly positive. See requirePositive(Object, String).
      Type Parameters:
      T - the type of the value, must implement Comparable
      Parameters:
      value - the value to check for positivity; must not be null
      messageSupplier - the supplier of the exception message; must not be null
      Returns:
      the validated value if it is greater than zero
      Throws:
      NullPointerException - if value or messageSupplier is null
      IllegalArgumentException - if value is zero or negative
      IllegalArgumentException - if value is of an unsupported type
      Since:
      1.3