Module com.github.cowwoc.requirements10.guava
Package com.github.cowwoc.requirements10.guava

Class DefaultGuavaValidators

java.lang.Object
com.github.cowwoc.requirements10.guava.DefaultGuavaValidators
public final class DefaultGuavaValidators extends Object
Creates validators for the Guava API.

There are three kinds of validators:

  • requireThat() for method preconditions.
  • assert that() for class invariants, and method postconditions.
  • checkIf() for returning multiple validation failures.

Thread Safety: This class is thread-safe.

  • Method Details

    • requireThat

      public static <K, V, T extends Multimap<K, V>> MultimapValidator<T,K,V> requireThat(T value, String name)
      Validates the state of a Multimap.

      The returned validator throws an exception immediately if a validation fails.

      Type Parameters:
      K - the type of keys in the Multimap
      V - the type of values in the Multimap
      T - the type of the Multimap
      Parameters:
      value - the value
      name - the name of the value
      Returns:
      a validator for the value
      Throws:
      NullPointerException - if name is null
      IllegalArgumentException - if name contains whitespace, or is empty

    • that

      public static <K, V, T extends Multimap<K, V>> MultimapValidator<T,K,V> that(T value, String name)
      Validates the state of a Multimap.

      The returned validator captures exceptions on validation failure rather than throwing them immediately. The exceptions are converted into an AssertionError and can be retrieved or thrown once the validation completes. Exceptions unrelated to validation failures are thrown immediately.

      This method is intended to be used with the assert keyword, like so: assert that(value, name).

      Type Parameters:
      K - the type of keys in the map
      V - the type of values in the map
      T - the type of the Multimap
      Parameters:
      value - the value
      name - the name of the value
      Returns:
      a validator for the value
      Throws:
      NullPointerException - if name is null
      IllegalArgumentException - if name contains whitespace or is empty

    • that

      public static <K, V, T extends Multimap<K, V>> MultimapValidator<T,K,V> that(T value)
      Validates the state of a Multimap. Validation failures only throw AssertionError.
      Type Parameters:
      K - the type of keys in the map
      V - the type of values in the map
      T - the type of the Multimap
      Parameters:
      value - the value
      Returns:
      a validator for the value

    • checkIf

      public static <K, V, T extends Multimap<K, V>> MultimapValidator<T,K,V> checkIf(T value, String name)
      Validates the state of a Multimap.

      The returned validator captures exceptions on validation failure rather than throwing them immediately. These exceptions can be retrieved or thrown once the validation completes. Exceptions unrelated to validation failures are thrown immediately.

      Type Parameters:
      K - the type of keys in the Multimap
      V - the type of values in the Multimap
      T - the type of the Multimap
      Parameters:
      value - the value
      name - the name of the value
      Returns:
      a validator for the value
      Throws:
      NullPointerException - if name is null
      IllegalArgumentException - if name contains whitespace or is empty

    • checkIf

      public static <K, V, T extends Multimap<K, V>> MultimapValidator<T,K,V> checkIf(T value)
      Validates the state of a Multimap.

      The returned validator captures exceptions on validation failure rather than throwing them immediately. These exceptions can be retrieved or thrown once the validation completes. Exceptions unrelated to validation failures are thrown immediately.

      Type Parameters:
      K - the type of keys in the Multimap
      V - the type of values in the Multimap
      T - the type of the Multimap
      Parameters:
      value - the value
      Returns:
      a validator for the value

    • getContext

      public static Map<String,Optional<Object>> getContext()
      Returns the contextual information for validators created out by this factory. The contextual information is a map of key-value pairs that can provide more details about validation failures. For example, if the message is "Password may not be empty" and the map contains the key-value pair {"username": "john.smith"}, the exception message would be: 

      Password may not be empty
username: john.smith

      Note that values are wrapped in an Optional because modern maps do not support null values.

      Returns:
      an unmodifiable map from each entry's name to its value

    • withContext

      public static GuavaValidators withContext(Object value, String name)
      Sets the contextual information for validators created by this factory.

      This method adds contextual information to exception messages. The contextual information is stored as key-value pairs in a map. Values set by this method may be overridden by ValidatorComponent.withContext(Object, String)}.

      Parameters:
      value - the value of the entry
      name - the name of an entry
      Returns:
      the underlying validator factory
      Throws:
      NullPointerException - if name is null
      IllegalArgumentException - if name:
      • contains whitespace
      • is empty
      • is already in use by the value being validated or the validator context

    • removeContext

      public static GuavaValidators removeContext(String name)
      Removes the contextual information of validators created by this factory.
      Parameters:
      name - the parameter name
      Returns:
      the underlying validator factory
      Throws:
      NullPointerException - if name is null
      IllegalArgumentException - if name:
      • contains whitespace
      • is empty

    • globalConfiguration

      public static GlobalConfiguration globalConfiguration()
      Returns the global configuration shared by all validators.

      NOTE: Updating this configuration affects existing and new validators.

      Returns:
      the global configuration updater