#1508 - Convenience methods for cardinality on HalFormsOptions.

Author: odrotbohm

src/main/java/org/springframework/hateoas/mediatype/hal/forms/HalFormsOptions.java

@@ -230,7 +230,7 @@ public T withMinItems(Long minItems) {
 		 * @param maxItems must be {@literal null} or greater than zero.
 		 * @return
 		 */
-		public T withMaxItems(Long maxItems) {
+		public T withMaxItems(@Nullable Long maxItems) {
 
 			if (maxItems != null && maxItems <= 0) {
 				throw new IllegalArgumentException("maxItems has to be null or greater than zero!");
@@ -239,6 +239,60 @@ public T withMaxItems(Long maxItems) {
 			return with(promptField, valueField, minItems, maxItems);
 		}
 
+		/**
+		 * Configures the options return an optional value, i.e. cardinality [0, 1].
+		 *
+		 * @return
+		 */
+		public T optional() {
+			return withMinItems(0L).withMaxItems(1L);
+		}
+
+		/**
+		 * Configures the options return an optional collection, i.e. cardinality [0, *].
+		 *
+		 * @return
+		 */
+		public T optionalCollection() {
+			return withMinItems(0L).withMaxItems(null);
+		}
+
+		/**
+		 * Configures the options return an optional collection with a maximum number of elements, i.e. cardinality [0, n].
+		 *
+		 * @return
+		 */
+		public T optionalCollection(long maxItems) {
+			return withMinItems(0L).withMaxItems(maxItems);
+		}
+
+		/**
+		 * Configures the options return a required value, i.e. cardinality [1, 1].
+		 *
+		 * @return
+		 */
+		public T required() {
+			return withMinItems(1L).withMaxItems(1L);
+		}
+
+		/**
+		 * Configures the options return a required collection, i.e. cardinality [1, *].
+		 *
+		 * @return
+		 */
+		public T requiredCollection() {
+			return withMinItems(1L).withMaxItems(null);
+		}
+
+		/**
+		 * Configures the options return a required collection with a maximum number of items, i.e. cardinality [1, n].
+		 *
+		 * @return
+		 */
+		public T requiredCollection(long maxItems) {
+			return withMinItems(1L).withMaxItems(maxItems);
+		}
+
 		/**
 		 * Create a new concrete {@link AbstractHalFormsOptions}
 		 *

src/test/java/org/springframework/hateoas/mediatype/hal/forms/HalFormsTemplateBuilderUnitTest.java

@@ -18,11 +18,14 @@
 import static org.assertj.core.api.Assertions.*;
 
 import lombok.Getter;
+import lombok.Value;
 
 import java.util.Arrays;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
+import java.util.function.Function;
+import java.util.stream.Stream;
 
 import javax.validation.constraints.Max;
 import javax.validation.constraints.Min;
@@ -31,16 +34,21 @@
 
 import org.hibernate.validator.constraints.Length;
 import org.hibernate.validator.constraints.Range;
+import org.junit.jupiter.api.DynamicTest;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestFactory;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.CsvSource;
 import org.springframework.hateoas.Link;
 import org.springframework.hateoas.LinkRelation;
 import org.springframework.hateoas.RepresentationModel;
 import org.springframework.hateoas.mediatype.Affordances;
 import org.springframework.hateoas.mediatype.MessageResolver;
+import org.springframework.hateoas.mediatype.hal.forms.HalFormsOptions.AbstractHalFormsOptions;
+import org.springframework.hateoas.mediatype.hal.forms.HalFormsOptions.Inline;
 import org.springframework.http.HttpMethod;
 import org.springframework.http.MediaType;
+import org.springframework.lang.Nullable;
 
 /**
  * @author Oliver Drotbohm
@@ -182,6 +190,20 @@ void rendersRegisteredSuggest() {
 				});
 	}
 
+	@TestFactory
+	Stream<DynamicTest> expressesCardinalityOnOptions() {
+
+		Stream<Cardinality> stream = Stream.of( //
+				Cardinality.of("optional", AbstractHalFormsOptions::optional, 0L, 1L), //
+				Cardinality.of("optionalCollection", AbstractHalFormsOptions::optionalCollection, 0L, null), //
+				Cardinality.of("optionalCollection(n)", it -> it.optionalCollection(5L), 0L, 5L), //
+				Cardinality.of("required", AbstractHalFormsOptions::required, 1L, 1L), //
+				Cardinality.of("requiredCollection", AbstractHalFormsOptions::requiredCollection, 1L, null), //
+				Cardinality.of("requiredCollection(n)", it -> it.requiredCollection(5L), 1L, 5L));
+
+		return DynamicTest.stream(stream, Cardinality::toString, Cardinality::verify);
+	}
+
 	@Getter
 	static class PatternExample extends RepresentationModel<PatternExample> {
 
@@ -215,4 +237,28 @@ static class Payload {
 		@Range(min = 8, max = 10) //
 		Integer range;
 	}
+
+	@Value(staticConstructor = "of")
+	static class Cardinality {
+
+		String title;
+		Function<AbstractHalFormsOptions<?>, AbstractHalFormsOptions<?>> mapper;
+		Long expectedMin;
+		@Nullable Long expectedMax;
+
+		void verify() {
+
+			Inline inline = HalFormsOptions.inline();
+			HalFormsOptions result = mapper.apply(inline);
+
+			assertThat(result.getMinItems()).isEqualTo(expectedMin);
+			assertThat(result.getMaxItems()).isEqualTo(expectedMax);
+		}
+
+		@Override
+		public String toString() {
+			return String.format("Calling HalFormsOptions.%s() configures minItems to %s and maxItems to %s.", //
+					title, expectedMin, expectedMax);
+		}
+	}
 }