Merge pull request #12 from cowwoc/release-10.0

Release 10.0

.github/workflows/cla.yml

@@ -27,7 +27,7 @@ jobs:
           PERSONAL_ACCESS_TOKEN: ${{ secrets.CLA_ACCESS_TOKEN }}
         with:
           path-to-signatures: 'cla/version1/signatures/cla.json'
-          path-to-document: 'https://github.com/cowwoc/requirements.java/cla/version1/cla.md' # e.g. a CLA or a DCO document
+          path-to-document: 'https://github.com/cowwoc/requirements.java/blob/master/cla/version1/cla.md' # e.g. a CLA or a DCO document
           # branch should not be protected
           branch: 'main'
           allowlist: cowwoc

.mvn/wrapper/maven-wrapper.properties

@@ -14,5 +14,5 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.6/apache-maven-3.9.6-bin.zip
-wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.2.0/maven-wrapper-3.2.0.jar
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.9/apache-maven-3.9.9-bin.zip
+wrapperUrl=https://repo.maven.apache.org/maven2/org/apache/maven/wrapper/maven-wrapper/3.3.2/maven-wrapper-3.3.2.jar

README.md

@@ -3,7 +3,7 @@
 
 # <img src="docs/checklist.svg" width=64 height=64 alt="checklist"> Requirements API
 
-[![API](https://img.shields.io/badge/api_docs-5B45D5.svg)](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/)
+[![API](https://img.shields.io/badge/api_docs-5B45D5.svg)](https://cowwoc.github.io/requirements.java/10.0/docs/api/)
 [![Changelog](https://img.shields.io/badge/changelog-A345D5.svg)](docs/Changelog.md)
 [![javascript, typescript](https://img.shields.io/badge/other%20languages-javascript,%20typescript-457FD5.svg)](../../../requirements.js)
 
@@ -32,9 +32,9 @@ To get started, add this Maven dependency:
 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;
+import static com.github.cowwoc.requirements10.java.DefaultJavaValidators.checkIf;
+import static com.github.cowwoc.requirements10.java.DefaultJavaValidators.requireThat;
+import static com.github.cowwoc.requirements10.java.DefaultJavaValidators.that;
 
 public final class Cake
 {
@@ -50,11 +50,11 @@ public final class Cake
   public int eat()
   {
     ++bitesTaken;
-    assert assumeThat(bitesTaken, "bitesTaken").isNotNegative().elseThrow();
+    assert that(bitesTaken, "bitesTaken").isNotNegative().elseThrow();
 
     piecesLeft -= ThreadLocalRandom.current().nextInt(5);
 
-    assert assumeThat(piecesLeft, "piecesLeft").isNotNegative().elseThrow();
+    assert that(piecesLeft, "piecesLeft").isNotNegative().elseThrow();
     return piecesLeft;
   }
 
@@ -77,7 +77,7 @@ You'll get:
 
 ```
 java.lang.IllegalArgumentException: "piecesLeft" must be positive.
-Actual: -1000
+actual: -1000
 ```
 
 If you violate a **class invariant**:
@@ -92,7 +92,7 @@ You'll get:
 
 ```
 java.lang.AssertionError: "bitesTaken" may not be negative.
-Actual: -128
+actual: -128
 ```
 
 If you violate a **postcondition**:
@@ -107,7 +107,7 @@ You'll get:
 
 ```
 java.lang.AssertionError: "piecesLeft" may not be negative.
-Actual: -4
+actual: -4
 ```
 
 If you violate **multiple** conditions at once:
@@ -126,10 +126,10 @@ You'll get:
 
 ```
 "bitesTaken" may not be negative.
-Actual: -1
+actual: -1
 
 "piecesLeft" must be greater than 3.
-Actual: 2
+actual: 2
 ```
 
 ## Features
@@ -152,29 +152,21 @@ This library offers the following features:
 Designed for discovery using your favorite IDE's auto-complete feature.
 The main entry points are:
 
-* [requireThat(value, name)](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements/java/DefaultJavaValidators.html#requireThat(T,java.lang.String)) for method preconditions.
-* [assumeThat(value, name)](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements/java/DefaultJavaValidators.html#assumeThat(T,java.lang.String)) for class invariants, method postconditions and private methods.
-* [checkIfThat(value, name)](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements/java/DefaultJavaValidators.html#checkIf(T,java.lang.String)) for multiple failures and customized error handling.
-* [JavaValidators](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements/java/JavaValidators.html) for custom configurations.
+* [requireThat(value, name)](https://cowwoc.github.io/requirements.java/10.0/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html#requireThat(T,java.lang.String))
+  for method preconditions.
+* [that(value, name)](https://cowwoc.github.io/requirements.java/10.0/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html#that(T,java.lang.String))
+  for [class invariants, method postconditions and private methods](docs/Features.md#assertion-support). 
+* [checkIf(value, name)](https://cowwoc.github.io/requirements.java/10.0/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements10/java/DefaultJavaValidators.html#checkIf(T,java.lang.String))
+  for multiple failures and customized error handling.
 
-The first three methods use a shared configuration, while `JavaValidators` allows you to create an independent
-configuration.
+See the [API documentation](https://cowwoc.github.io/requirements.java/10.0/docs/api/) for more details.
 
-* `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.
+## Best practices
 
-Thrown exceptions may be configured using [ConfigurationUpdater.exceptionTransformer(Function)](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/com.github.cowwoc.requirements.java/com/github/cowwoc/requirements/java/ConfigurationUpdater.html#exceptionTransformer(java.util.function.Function)).
-
-See the [API documentation](https://cowwoc.github.io/requirements.java/9.0.0/docs/api/) 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)`.
+* To enhance the clarity of failure messages, you should provide parameter names, even when they are optional.
+  In other words, favor `assert that(value, name)` over `assert that(value)`.
 
 ## Third-party libraries and tools
 

annotation/pom.xml

@@ -1,14 +1,19 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 	<modelVersion>4.0.0</modelVersion>
 	<parent>
 		<groupId>com.github.cowwoc.requirements</groupId>
 		<artifactId>root</artifactId>
-		<version>9.0.1-SNAPSHOT</version>
+		<version>10.0.0-SNAPSHOT</version>
 	</parent>
 	<artifactId>annotation</artifactId>
 	<packaging>jar</packaging>
 
+	<properties>
+		<rootBaseDir>${project.basedir}/..</rootBaseDir>
+	</properties>
+
 	<build>
 		<plugins>
 			<plugin>

annotation/src/main/java/com/github/cowwoc/requirements/annotation/CheckReturnValue.java → annotation/src/main/java/com/github/cowwoc/requirements10/annotation/CheckReturnValue.java

@@ -1,4 +1,4 @@
-package com.github.cowwoc.requirements.annotation;
+package com.github.cowwoc.requirements10.annotation;
 
 import java.lang.annotation.Target;
 

annotation/src/main/java/module-info.java

@@ -5,7 +5,8 @@
 /**
  * Annotations used by the library.
  */
-module com.github.cowwoc.requirements.annotation
+@SuppressWarnings("JavaModuleNaming")
+module com.github.cowwoc.requirements10.annotation
 {
-	exports com.github.cowwoc.requirements.annotation;
+	exports com.github.cowwoc.requirements10.annotation;
 }

benchmark/assertj/pom.xml

@@ -1,19 +1,23 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 	<modelVersion>4.0.0</modelVersion>
 	<parent>
 		<groupId>com.github.cowwoc.requirements</groupId>
 		<artifactId>benchmark</artifactId>
-		<version>9.0.1-SNAPSHOT</version>
+		<version>10.0.0-SNAPSHOT</version>
 	</parent>
 	<artifactId>benchmark.assertj</artifactId>
 	<packaging>jar</packaging>
 
+	<properties>
+		<rootBaseDir>${project.basedir}/../..</rootBaseDir>
+	</properties>
+
 	<dependencies>
 		<dependency>
 			<groupId>org.assertj</groupId>
 			<artifactId>assertj-core</artifactId>
-			<version>3.25.3</version>
 		</dependency>
 	</dependencies>
 </project>

benchmark/assertj/src/test/java/com/github/cowwoc/requirements/benchmark/assertj/AssertJTest.java → benchmark/assertj/src/test/java/com/github/cowwoc/requirements10/benchmark/assertj/AssertJTest.java

@@ -2,7 +2,7 @@
  * Copyright (c) 2017 Gili Tzabari
  * Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
  */
-package com.github.cowwoc.requirements.benchmark.assertj;
+package com.github.cowwoc.requirements10.benchmark.assertj;
 
 import org.assertj.core.api.Assertions;
 import org.assertj.core.api.SoftAssertions;
@@ -28,7 +28,7 @@
 @SuppressWarnings({"CanBeFinal", "LongLine", "FieldCanBeLocal", "FieldMayBeFinal"})
 public class AssertJTest
 {
-	private static final boolean FAST_ESTIMATE = false;
+	private static final boolean FAST_ESTIMATE = Boolean.getBoolean("FAST_ESTIMATE");
 	// Fields may not be final:
 	// https://github.com/openjdk/jmh/blob/cb3c3a90137dad781a2a37fda72dc11ebf253593/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_10_ConstantFold.java#L58
 	private String name = "map";
@@ -69,8 +69,8 @@ public void assertThatIsSuccessful(Blackhole bh)
 		bh.consume(assertThat(value).as(name + ": %s").size().
 			as("""
 				%s must be greater than %s.
-				Actual: %s
-				Actual.size: %s""", name, 3, value, value.size()).isGreaterThan(3));
+				actual: %s
+				actual.size: %s""", name, 3, value, value.size()).isGreaterThan(3));
 	}
 
 	@Benchmark

benchmark/assertj/src/test/java/module-info.java

@@ -1,9 +1,17 @@
-module com.github.cowwoc.requirements.benchmark.assertj
+/*
+ * Copyright 2019 Gili Tzabari.
+ * Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Benchmark of equivalent assertj functionality.
+ */
+@SuppressWarnings("JavaModuleNaming")
+module com.github.cowwoc.requirements10.benchmark.assertj
 {
 	requires jmh.core;
 	requires org.testng;
 	requires org.assertj.core;
 
-	exports com.github.cowwoc.requirements.benchmark.assertj to org.testng;
-	exports com.github.cowwoc.requirements.benchmark.assertj.jmh_generated to jmh.core;
+	exports com.github.cowwoc.requirements10.benchmark.assertj to org.testng;
+	exports com.github.cowwoc.requirements10.benchmark.assertj.jmh_generated to jmh.core;
 }

benchmark/assertj/src/test/resources/logback-test.xml

@@ -9,6 +9,6 @@
 		<appender-ref ref="STDOUT"/>
 	</root>
 	<logger name="org.testng" level="warn"/>
-	<logger name="com.github.cowwoc.requirements.java.internal.terminal.Terminal" level="warn"/>
-	<logger name="com.github.cowwoc.requirements.java.internal.util.Exceptions" level="warn"/>
+	<logger name="com.github.cowwoc.requirements10.java.internal.terminal.Terminal" level="warn"/>
+	<logger name="com.github.cowwoc.requirements10.java.internal.util.Exceptions" level="warn"/>
 </configuration>

benchmark/guava/pom.xml

@@ -1,14 +1,19 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 	<modelVersion>4.0.0</modelVersion>
 	<parent>
 		<groupId>com.github.cowwoc.requirements</groupId>
 		<artifactId>benchmark</artifactId>
-		<version>9.0.1-SNAPSHOT</version>
+		<version>10.0.0-SNAPSHOT</version>
 	</parent>
 	<artifactId>benchmark.guava</artifactId>
 	<packaging>jar</packaging>
 
+	<properties>
+		<rootBaseDir>${project.basedir}/../..</rootBaseDir>
+	</properties>
+
 	<dependencies>
 		<dependency>
 			<groupId>${project.groupId}</groupId>

benchmark/guava/src/test/java/com/github/cowwoc/requirements/benchmark/guava/GuavaTest.java → benchmark/guava/src/test/java/com/github/cowwoc/requirements10/benchmark/guava/GuavaTest.java

@@ -2,9 +2,9 @@
  * Copyright (c) 2017 Gili Tzabari
  * Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
  */
-package com.github.cowwoc.requirements.benchmark.guava;
+package com.github.cowwoc.requirements10.benchmark.guava;
 
-import com.github.cowwoc.requirements.guava.DefaultGuavaValidators;
+import com.github.cowwoc.requirements10.guava.DefaultGuavaValidators;
 import com.google.common.collect.HashMultimap;
 import com.google.common.collect.Multimap;
 import org.openjdk.jmh.annotations.Benchmark;
@@ -25,7 +25,7 @@
 @SuppressWarnings({"FieldCanBeLocal", "CanBeFinal", "LongLine"})
 public class GuavaTest
 {
-	private static final boolean FAST_ESTIMATE = false;
+	private static final boolean FAST_ESTIMATE = Boolean.getBoolean("FAST_ESTIMATE");
 	// Fields may not be final:
 	// https://github.com/openjdk/jmh/blob/cb3c3a90137dad781a2a37fda72dc11ebf253593/jmh-samples/src/main/java/org/openjdk/jmh/samples/JMHSample_10_ConstantFold.java#L58
 	private String name = "multimap";

benchmark/guava/src/test/java/module-info.java

@@ -1,11 +1,19 @@
-module com.github.cowwoc.requirements.benchmark.guava
+/*
+ * Copyright 2019 Gili Tzabari.
+ * Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Benchmark of the guava module.
+ */
+@SuppressWarnings("JavaModuleNaming")
+module com.github.cowwoc.requirements10.benchmark.guava
 {
 	requires jmh.core;
 	requires com.google.common;
 	requires org.testng;
-	requires com.github.cowwoc.requirements.guava;
+	requires com.github.cowwoc.requirements10.guava;
 	requires static com.google.errorprone.annotations;
 
-	exports com.github.cowwoc.requirements.benchmark.guava to org.testng;
-	exports com.github.cowwoc.requirements.benchmark.guava.jmh_generated to jmh.core;
+	exports com.github.cowwoc.requirements10.benchmark.guava to org.testng;
+	exports com.github.cowwoc.requirements10.benchmark.guava.jmh_generated to jmh.core;
 }

benchmark/guava/src/test/resources/logback-test.xml

@@ -8,5 +8,5 @@
 	<root level="debug">
 		<appender-ref ref="STDOUT"/>
 	</root>
-	<logger name="com.github.cowwoc.requirements.java.internal.terminal.Terminal" level="warn"/>
+	<logger name="com.github.cowwoc.requirements10.java.internal.terminal.Terminal" level="warn"/>
 </configuration>

benchmark/java/pom.xml

@@ -1,14 +1,19 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 	<modelVersion>4.0.0</modelVersion>
 	<parent>
 		<groupId>com.github.cowwoc.requirements</groupId>
 		<artifactId>benchmark</artifactId>
-		<version>9.0.1-SNAPSHOT</version>
+		<version>10.0.0-SNAPSHOT</version>
 	</parent>
 	<artifactId>benchmark.java</artifactId>
 	<packaging>jar</packaging>
 
+	<properties>
+		<rootBaseDir>${project.basedir}/../..</rootBaseDir>
+	</properties>
+
 	<dependencies>
 		<dependency>
 			<groupId>${project.groupId}</groupId>