Requirements API

A fluent API for enforcing design contracts with automatic message generation:

✔️ Easy to use
✔️ Fast
✔️ Production-ready

To get started, add this Maven dependency:

<dependency>
  <groupId>com.github.cowwoc.requirements</groupId>
  <artifactId>java</artifactId>
  <version>9.0.0</version>
</dependency>

Usage Example

import java.util.List;
import java.util.StringJoiner;

import static com.github.cowwoc.requirements.java.DefaultJavaValidators.assumeThat;
import static com.github.cowwoc.requirements.java.DefaultJavaValidators.checkIf;
import static com.github.cowwoc.requirements.java.DefaultJavaValidators.requireThat;

public final class Cake
{
  private byte bitesTaken = 0;
  private int piecesLeft;

  public Cake(int piecesLeft)
  {
    requireThat(piecesLeft, "piecesLeft").isPositive();
    this.piecesLeft = piecesLeft;
  }

  public int eat()
  {
    ++bitesTaken;
    assert assumeThat(bitesTaken, "bitesTaken").isNotNegative().elseThrow();

    piecesLeft -= ThreadLocalRandom.current().nextInt(5);

    assert assumeThat(piecesLeft, "piecesLeft").isNotNegative().elseThrow();
    return piecesLeft;
  }

  public List<String> getFailures()
  {
    return checkIf(bitesTaken, "bitesTaken").isNotNegative().
      and(checkIf(piecesLeft, "piecesLeft").isGreaterThan(3)).
      elseGetMessages();
  }
}

If you violate a precondition:

Cake cake = new Cake(-1000);

You'll get:

java.lang.IllegalArgumentException: "piecesLeft" must be positive.
Actual: -1000

If you violate a class invariant:

Cake cake = new Cake(1_000_000);
while (true)
  cake.eat();

You'll get:

java.lang.AssertionError: "bitesTaken" may not be negative.
Actual: -128

If you violate a postcondition:

Cake cake = new Cake(100);
while (true)
  cake.eat();

You'll get:

java.lang.AssertionError: "piecesLeft" may not be negative.
Actual: -4

If you violate multiple conditions at once:

Cake cake = new Cake(1);
cake.bitesTaken = -1;
cake.piecesLeft = 2;
StringJoiner failures = new StringJoiner("\n\n");
for (String failure : cake.getFailures())
    failures.add(failure);
System.out.println(failures);

You'll get:

"bitesTaken" may not be negative.
Actual: -1

"piecesLeft" must be greater than 3.
Actual: 2

Features

This library offers the following features:

• Automatic message generation for validation failures
• Diffs provided whenever possible to highlight the differences between expected and actual values
• Clean stack-traces that remove unnecessary frames
• Zero overhead when assertions are disabled for better performance
• Multiple validation failures that report all the errors at once
• Nested validations that allow you to validate complex objects
• String diff that shows the differences between two strings
• Performant and robust

Entry Points

Designed for discovery using your favorite IDE's auto-complete feature. The main entry points are:

• requireThat(value, name) for method preconditions.
• assumeThat(value, name) for class invariants, method postconditions and private methods.
• checkIfThat(value, name) for multiple failures and customized error handling.
• JavaValidators for custom configurations.

The first three methods use a shared configuration, while JavaValidators allows you to create an independent configuration.

• requireThat() and assumeThat() throw an exception on the first validation failure.
• checkIf() returns multiple validation failures at once. It is more flexible than the others, but its syntax is more verbose.

Thrown exceptions may be configured using ConfigurationUpdater.exceptionTransformer(Function).

See the API documentation for more details.

Tips

• Use assert with assumeThat().elseThrow() for sanity checks. When assertions are disabled, the checks will get removed.
• Use checkIf().elseGetMessages() to return failure messages without throwing an exception. This is the fastest validation approach, ideal for web services.
• To enhance the clarity of failure messages, you should provide parameter names, even when they are optional. In other words, favor assumeThat(value, name) to assumeThat(value).

Third-party libraries and tools

This library supports the following third-party libraries and tools:

• guava
• IntelliJ IDEA

Licenses

• This library is licensed under the Apache License, Version 2.0
• See Third party licenses for the licenses of the dependencies
• Icons made by Flat Icons from www.flaticon.com are licensed by CC 3.0 BY