Merge pull request #14 from cowwoc/v10.1

cowwoc · web-flow · commit 15be20bc7d71 · 2024-12-06T13:08:48.000-05:00
v10.1
diff --git a/.github/workflows/cla.yml b/.github/workflows/cla.yml
@@ -19,7 +19,9 @@ jobs:
       # https://github.com/contributor-assistant/github-action
       - name: "CLA Assistant Lite"
         if: (github.event.comment.body == 'recheck' || github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') || github.event_name == 'pull_request_target'
-        uses: contributor-assistant/github-action@v2.3.0
+        uses: contributor-assistant/github-action@v2.6.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           path-to-signatures: 'cla/version1/signatures/cla.json'
           path-to-document: 'https://github.com/cowwoc/requirements.java/blob/master/cla/version1/cla.md' # e.g. a CLA or a DCO document
diff --git a/LICENSE-3RD-PARTY.md b/LICENSE-3RD-PARTY.md
@@ -7,6 +7,7 @@
     * [core](https://github.com/cowwoc/pouch/core/)
     * [annotation](https://github.com/cowwoc/requirements.java/annotation/)
     * [guava](https://github.com/cowwoc/requirements.java/guava/)
+    * [jackson](https://github.com/cowwoc/requirements.java/jackson/)
     * [java](https://github.com/cowwoc/requirements.java/java/)
     * [FindBugs-jsr305](http://findbugs.sourceforge.net/)
     * [error-prone annotations](https://errorprone.info/error_prone_annotations)
diff --git a/annotation/pom.xml b/annotation/pom.xml
@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>com.github.cowwoc.requirements</groupId>
 		<artifactId>root</artifactId>
-		<version>10.1-SNAPSHOT</version>
+		<version>10.2-SNAPSHOT</version>
 	</parent>
 	<artifactId>annotation</artifactId>
 	<packaging>jar</packaging>
diff --git a/benchmark/assertj/pom.xml b/benchmark/assertj/pom.xml
@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>com.github.cowwoc.requirements</groupId>
 		<artifactId>benchmark</artifactId>
-		<version>10.1-SNAPSHOT</version>
+		<version>10.2-SNAPSHOT</version>
 	</parent>
 	<artifactId>benchmark.assertj</artifactId>
 	<packaging>jar</packaging>
diff --git a/benchmark/guava/pom.xml b/benchmark/guava/pom.xml
@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>com.github.cowwoc.requirements</groupId>
 		<artifactId>benchmark</artifactId>
-		<version>10.1-SNAPSHOT</version>
+		<version>10.2-SNAPSHOT</version>
 	</parent>
 	<artifactId>benchmark.guava</artifactId>
 	<packaging>jar</packaging>
diff --git a/benchmark/java/pom.xml b/benchmark/java/pom.xml
@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>com.github.cowwoc.requirements</groupId>
 		<artifactId>benchmark</artifactId>
-		<version>10.1-SNAPSHOT</version>
+		<version>10.2-SNAPSHOT</version>
 	</parent>
 	<artifactId>benchmark.java</artifactId>
 	<packaging>jar</packaging>
diff --git a/benchmark/pom.xml b/benchmark/pom.xml
@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>com.github.cowwoc.requirements</groupId>
 		<artifactId>root</artifactId>
-		<version>10.1-SNAPSHOT</version>
+		<version>10.2-SNAPSHOT</version>
 	</parent>
 	<artifactId>benchmark</artifactId>
 	<packaging>pom</packaging>
diff --git a/build/pom.xml b/build/pom.xml
@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>com.github.cowwoc.requirements</groupId>
 		<artifactId>root</artifactId>
-		<version>10.1-SNAPSHOT</version>
+		<version>10.2-SNAPSHOT</version>
 	</parent>
 	<artifactId>build</artifactId>
 	<description>Files related to building the project</description>
diff --git a/docs/Changelog.md b/docs/Changelog.md
@@ -2,6 +2,14 @@
 
 See https://github.com/cowwoc/requirements.java/commits/master for a full list.
 
+## Version 10.1 - 2024/12/06
+
+* Improvements
+    * When referencing to a variable number of elements, always use the plural form of a type (e.g.
+      `actual must contain X entries` even if `X` is one).
+    * Added special handling for `Collection.contains(Object)` throwing `NullPointerException` because the
+      collection does not permit null elements.
+
 ## Version 10.0 - 2024/10/31
 
 * Breaking changes:
diff --git a/guava/pom.xml b/guava/pom.xml
@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>com.github.cowwoc.requirements</groupId>
 		<artifactId>root</artifactId>
-		<version>10.1-SNAPSHOT</version>
+		<version>10.2-SNAPSHOT</version>
 	</parent>
 	<artifactId>guava</artifactId>
 	<packaging>jar</packaging>
diff --git a/jackson/pom.xml b/jackson/pom.xml
@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>com.github.cowwoc.requirements</groupId>
 		<artifactId>root</artifactId>
-		<version>10.1-SNAPSHOT</version>
+		<version>10.2-SNAPSHOT</version>
 	</parent>
 	<artifactId>jackson</artifactId>
 	<packaging>jar</packaging>
diff --git a/java/pom.xml b/java/pom.xml
@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>com.github.cowwoc.requirements</groupId>
 		<artifactId>root</artifactId>
-		<version>10.1-SNAPSHOT</version>
+		<version>10.2-SNAPSHOT</version>
 	</parent>
 	<artifactId>java</artifactId>
 	<packaging>jar</packaging>
diff --git a/java/src/main/java/com/github/cowwoc/requirements10/java/internal/message/CollectionMessages.java b/java/src/main/java/com/github/cowwoc/requirements10/java/internal/message/CollectionMessages.java
@@ -44,7 +44,7 @@ public static MessageBuilder containsSizeFailed(AbstractObjectValidator<?, ?> va
 		String name = validator.getName();
 		MessageBuilder messageBuilder = new MessageBuilder(validator,
 			quoteName(name) + " " + relationship + " " + expectedNameOrSize + " " +
-				pluralizer.nameOf(expectedSize) + ".");
+				pluralizer.nameOf(expectedSize, expectedSizeName) + ".");
 
 		validator.value.nullToInvalid().ifValid(v ->
 			messageBuilder.withContext(v, name));
@@ -80,7 +80,8 @@ public static MessageBuilder sizeIsBetweenFailed(AbstractObjectValidator<?, ?> v
 			// The size is undefined (e.g. the collection is null)
 			//
 			//  "actual" must contain [1, 3] elements
-			message.append(" must contain ").append(bounds).append(' ').append(pluralizer.nameOf(2)).append('.');
+			message.append(" must contain ").append(bounds).append(' ').
+				append(pluralizer.nameOf(2, null)).append('.');
 			return new MessageBuilder(validator, message.toString());
 		}
 
@@ -111,7 +112,7 @@ else if (actualSize >= exclusiveMaximum)
 				"actual: " + actualSize + "\n" +
 				"bounds: " + bounds);
 		}
-		message.append(pluralizer.nameOf(2)).append('.');
+		message.append(pluralizer.nameOf(2, null)).append('.');
 		return new MessageBuilder(validator, message.toString()).
 			withContext(validator.getValue(), name).
 			withContext(actualSize, actualSizeName).
@@ -206,7 +207,7 @@ public static <C extends Collection<E>, E> MessageBuilder containsAnyFailed(
 
 		String name = validator.getName();
 		MessageBuilder messageBuilder = new MessageBuilder(validator,
-			quoteName(name) + " must contain any of the " + pluralizer.nameOf(2) +
+			quoteName(name) + " must contain any of the " + pluralizer.nameOf(2, null) +
 				" present in " + expectedNameOrValue + ".");
 
 		validator.value.nullToInvalid().ifValid(v -> messageBuilder.withContext(v, name));
@@ -237,7 +238,7 @@ public static <C extends Collection<E>, E> MessageBuilder doesNotContainAnyFaile
 
 		String name = validator.getName();
 		MessageBuilder messageBuilder = new MessageBuilder(validator,
-			quoteName(name) + " may not contain any of the " + pluralizer.nameOf(2) +
+			quoteName(name) + " may not contain any of the " + pluralizer.nameOf(2, null) +
 				" present in " + unwantedNameOrValue + ".");
 
 		validator.value.nullToInvalid().ifValid(v -> messageBuilder.withContext(v, name));
@@ -274,7 +275,7 @@ public static <E> MessageBuilder containsExactlyFailed(AbstractObjectValidator<?
 		StringBuilder message = new StringBuilder(quoteName(name)).append(" must consist of the ");
 		if (expectedName != null)
 			message.append("same ");
-		message.append(pluralizer.nameOf(2)).append(' ');
+		message.append(pluralizer.nameOf(2, null)).append(' ');
 
 		String expectedNameOrValue = validator.getNameOrValue("as ", expectedName, "", expected);
 		message.append(expectedNameOrValue).append(", regardless of their order.");
@@ -311,7 +312,7 @@ public static <C extends Collection<E>, E> MessageBuilder doesNotContainExactlyF
 			append(" may not consist of the ");
 		if (unwantedName != null)
 			message.append("same ");
-		message.append(pluralizer.nameOf(2)).append(' ');
+		message.append(pluralizer.nameOf(2, null)).append(' ');
 		String unwantedNameOrValue = validator.getNameOrValue("as ", unwantedName, "", unwanted);
 		message.append(unwantedNameOrValue).append(", regardless of their order.");
 
@@ -343,7 +344,7 @@ public static <C extends Collection<E>, E> MessageBuilder containsAllFailed(
 
 		String name = validator.getName();
 		MessageBuilder messageBuilder = new MessageBuilder(validator,
-			quoteName(name) + " must contain all the " + pluralizer.nameOf(2) + " present in " +
+			quoteName(name) + " must contain all the " + pluralizer.nameOf(2, null) + " present in " +
 				expectedNameOrValue + ".");
 
 		validator.value.nullToInvalid().ifValid(v -> messageBuilder.withContext(v, name));
@@ -372,7 +373,7 @@ public static <C extends Collection<E>, E> MessageBuilder doesNotContainAllFaile
 		String unwantedNameOrValue = validator.getNameOrValue("", unwantedName, "the set ", unwanted);
 		String name = validator.getName();
 		MessageBuilder messageBuilder = new MessageBuilder(validator,
-			quoteName(name) + " may contain some, but not all, the " + pluralizer.nameOf(2) +
+			quoteName(name) + " may contain some, but not all, the " + pluralizer.nameOf(2, null) +
 				" present in " + unwantedNameOrValue + ".");
 
 		validator.value.nullToInvalid().ifValid(v -> messageBuilder.withContext(v, name));
@@ -393,7 +394,7 @@ public static <E> MessageBuilder doesNotContainDuplicatesFailed(AbstractObjectVa
 	{
 		String name = validator.getName();
 		MessageBuilder messageBuilder = new MessageBuilder(validator,
-			quoteName(name) + " may not contain any duplicate " + pluralizer.nameOf(2) + ".");
+			quoteName(name) + " may not contain any duplicate " + pluralizer.nameOf(2, null) + ".");
 		if (duplicates != null)
 			messageBuilder.withContext(duplicates, "duplicates");
 		validator.value.nullToInvalid().ifValid(v -> messageBuilder.withContext(v, name));
diff --git a/java/src/main/java/com/github/cowwoc/requirements10/java/internal/util/Pluralizer.java b/java/src/main/java/com/github/cowwoc/requirements10/java/internal/util/Pluralizer.java
@@ -12,72 +12,46 @@ public enum Pluralizer
 	/**
 	 * The names of one or more characters.
 	 */
-	CHARACTER
-		{
-			@Override
-			public String nameOf(int count)
-			{
-				if (count == 1)
-					return "character";
-				return "characters";
-			}
-		},
+	CHARACTER("character", "characters"),
 	/**
 	 * The names of one or more keys.
 	 */
-	KEY
-		{
-			@Override
-			public String nameOf(int count)
-			{
-				if (count == 1)
-					return "key";
-				return "keys";
-			}
-		},
+	KEY("key", "keys"),
 	/**
 	 * The names of one or more values.
 	 */
-	VALUE
-		{
-			@Override
-			public String nameOf(int count)
-			{
-				if (count == 1)
-					return "value";
-				return "values";
-			}
-		},
+	VALUE("value", "values"),
 	/**
 	 * The names of one or more entries.
 	 */
-	ENTRY
-		{
-			@Override
-			public String nameOf(int count)
-			{
-				if (count == 1)
-					return "entry";
-				return "entries";
-			}
-		},
+	ENTRY("entry", "entries"),
 	/**
 	 * The names of one or more elements.
 	 */
-	ELEMENT
-		{
-			@Override
-			public String nameOf(int count)
-			{
-				if (count == 1)
-					return "element";
-				return "elements";
-			}
-		};
+	ELEMENT("element", "elements");
+
+	private final String singular;
+	private final String plural;
+
+	/**
+	 * @param singular - the singular form of the element
+	 * @param plural   - the plural form of the element
+	 */
+	Pluralizer(String singular, String plural)
+	{
+		this.singular = singular;
+		this.plural = plural;
+	}
 
 	/**
 	 * @param count the number of elements
+	 * @param name  the name of the parameter containing the number of elements ({@code null} if absent)
 	 * @return the singular or plural form of the element type (in lowercase)
 	 */
-	public abstract String nameOf(int count);
+	public String nameOf(int count, String name)
+	{
+		if (count == 1 && name == null)
+			return singular;
+		return plural;
+	}
 }
diff --git a/java/src/main/java/com/github/cowwoc/requirements10/java/internal/validator/AbstractCollectionValidator.java b/java/src/main/java/com/github/cowwoc/requirements10/java/internal/validator/AbstractCollectionValidator.java
@@ -95,9 +95,26 @@ public S contains(E expected, String name)
 		return containsImpl(expected, name);
 	}
 
+	@SuppressWarnings("PMD.AvoidCatchingNPE")
 	private S containsImpl(E expected, String name)
 	{
-		if (value.validationFailed(v -> v.contains(expected)))
+		if (value.validationFailed(v ->
+		{
+			try
+			{
+				return v.contains(expected);
+			}
+			catch (NullPointerException e)
+			{
+				if (expected == null)
+				{
+					// The specified element is null, and this collection does not permit null elements
+					assert (v != null);
+					return false;
+				}
+				throw e;
+			}
+		}))
 		{
 			failOnNull();
 			addIllegalArgumentException(CollectionMessages.containsFailed(this, name, expected).toString());
@@ -119,9 +136,22 @@ public S doesNotContain(E unwanted, String name)
 		return doesNotContainImpl(unwanted, name);
 	}
 
+	@SuppressWarnings("PMD.AvoidCatchingNPE")
 	private S doesNotContainImpl(E unwanted, String name)
 	{
-		if (value.validationFailed(v -> !v.contains(unwanted)))
+		if (value.validationFailed(v ->
+		{
+			try
+			{
+				return !v.contains(unwanted);
+			}
+			catch (NullPointerException e)
+			{
+				// The specified element is null, and this collection does not permit null elements
+				assert (v != null);
+				return true;
+			}
+		}))
 		{
 			failOnNull();
 			addIllegalArgumentException(
diff --git a/pom.xml b/pom.xml
@@ -3,7 +3,7 @@
 	<modelVersion>4.0.0</modelVersion>
 	<groupId>com.github.cowwoc.requirements</groupId>
 	<artifactId>root</artifactId>
-	<version>10.1-SNAPSHOT</version>
+	<version>10.2-SNAPSHOT</version>
 	<packaging>pom</packaging>
 	<name>Requirements</name>
 	<description>A fluent API for enforcing design contracts with automatic message generation</description>
diff --git a/test/pom.xml b/test/pom.xml
@@ -4,7 +4,7 @@
 	<parent>
 		<groupId>com.github.cowwoc.requirements</groupId>
 		<artifactId>root</artifactId>
-		<version>10.1-SNAPSHOT</version>
+		<version>10.2-SNAPSHOT</version>
 	</parent>
 	<artifactId>test</artifactId>
 	<packaging>jar</packaging>
diff --git a/test/src/test/java/com/github/cowwoc/requirements10/test/java/CollectionTest.java b/test/src/test/java/com/github/cowwoc/requirements10/test/java/CollectionTest.java
