requireX Argument Requirements

• Overview
• Requirement Methods
  • Args
  • StringArgs
  • NumericArgs
  • CollectionArgs

Overview

requireX is a set of utility methods, based on the form of the Objects.requireNonNull methods introduced in JDK 8. These utility methods continue and enhance with more capabilities to enforce requirements on method arguments. The requireX methods are organized by data types. All methods accept a first argument which is the value to check, and return the same value if the requirement is satisfied. A method accepts additional arguments if the requirement requires it. The last argument is the error message to use in the IllegalArgumentException which is thrown if the requirement is not satisfied. A null value does not satisfy the predefined methods.
A simple usage example (getters and setters are omitted for simplicity):

public class Person {
  private final String name;
  private final int age;

  public Person(String name, int age) {
    this.name = StringArgs.requireNonBlank(name, "Person name is required");
    this.age = NumericArgs.requireNonNegative(age, "Person age must be non-negative");
  }
}

Requirement Methods

Args

Requirement utility methods for any data type.

• requireSatisfies
  The main requirement method on which all other requirement methods are based. This can be used for any custom requirement (including a requirement that accepts null values).

• requireNonNull
  Similar to the Objects.requireNonNull, the main difference is that this method throws an IllegalArgumentException, whereas the method in Objects throws a NullPointerException.

StringArgs

Requirement utility methods for string values.

• requireNonBlank
  Require that a string is not blank. A string is blank if it is null, empty, or contains only white spaces.

• requireNonEmpty
  Require that a string is not empty (zero length).

• requireMatches
  Require that a string matches a given Pattern.

NumericArgs

Requirement utility methods for numeric values. All methods support the following data types: Integer, Long, Float, Double.

• requirePositive
  Require that a given value is positive (i.e. > 0)

• requireNonNegative
  Require that a given value is non-negative (i.e. >= 0)

• requireNegative
  Require that a given value is negative (i.e. < 0)

• requireNonPositive
  Require that a given value is non-positive (i.e. <= 0)

• requireGreaterThan
  Require that a given value is greater than another given value

• requireGreaterThanEquals
  Require that a given value is greater than or equals to another given value

• requireLessThan
  Require that a given value is less than another given value

• requireLessThanEquals
  Require that a given value is less than or equals to another given value

• requireNonZero
  Require that a given value is not zero (i.e. != 0)

• requireInRangeInclusive
  Require that a value is in a given range, including its borders.

• requireInRangeExclusive
  Require that a value is in a given range, excluding its borders.

• requireInRange
  Require that a value is in a given range, and specifying whether each border is included or excluded.

CollectionArgs

Requirement utility methods for collections and maps.

• requireContains
  Require that a given collection contains a specific element.

• requireContainsKey
  Require that a given map contains a specific key.

• requireContainsValue
  Require that a given map contains a specific value.

• requireExcludes
  Require that a given collection does not contain a specific element.

• requireExcludesKey
  Require that a given map does not contain a specific key.

• requireExcludesValue
  Require that a given map does not contain a specific value.

• requireMaxSize
  Require that the size of a given map or collection does not exceed a given number (i.e. size <= maxSize).

• requireEmpty
  Require that a given map or collection is empty (i.e. size == 0).

• requireMinSize
  Require that the size of a given map or collection is not below a given number (i.e. size >= minSize).

• requireNonEmpty
  Require that a given map or collection is not empty (i.e. size > 0).