Module com.github.cowwoc.requirements10.java
Package com.github.cowwoc.requirements10.java

Interface Validators<S>

Type Parameters:
S - the type of the validator factory
All Known Subinterfaces:
GuavaValidators, JacksonValidators, JavaValidators
public interface Validators<S>
A factory that creates different types of validators.

There are three kinds of validators:

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

  • Method Summary

    Modifier and Type
    Method
    Description
    S
    copy()
    Returns a new factory instance with an independent configuration.
    Map<String,Optional<Object>>
    getContext()
    Returns the contextual information inherited by validators created out by this factory.
    GlobalConfiguration
    globalConfiguration()
    Returns the global configuration shared by all validators.
    S
    removeContext(String name)
    Removes the contextual information of validators created by this factory.
    S
    withContext(Object value, String name)
    Sets the contextual information for validators created by this factory.

  • Method Details

    • copy

      S copy()
      Returns a new factory instance with an independent configuration. This method is commonly used to inherit and update contextual information from the original factory before passing it into a nested operation. For example, 
       JavaValidators copy = validators.copy();
 copy.getContext().put(json.toString(), "json");
 nestedOperation(copy);
      Returns:
      a copy of this factory

    • getContext

      Map<String,Optional<Object>> getContext()
      Returns the contextual information inherited by 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

      S 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:
      this
      Throws:
      NullPointerException - if name is null
      IllegalArgumentException - if:
      • name is empty
      • name contains whitespace
      • name is already in use by the value being validated or the validator context

    • removeContext

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

    • globalConfiguration

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

      NOTE: Updating this configuration affects existing and new validators.

      Returns:
      the global configuration updater