#864 - Retool.

Create a basic Model interface with a subinterface called Builder.

Implement a DefaultModelBuilder that only focuses on entities and links. This allows building some of the simplest representations that are supported by all formats.

Implement a HalModelBuilder that supports the same basic operations but also includes HAL-specific embed() and previewFor() as HAL syntax sugar.

By having a basic interface, other media types are free to either A) go along with the default format, or B) implement their own implementation, with mediatype-specific operators.

Author: gregturn

src/main/java/org/springframework/hateoas/Model.java

@@ -0,0 +1,163 @@
+package org.springframework.hateoas;
+
+import org.springframework.hateoas.server.core.EmbeddedWrappers;
+
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+/**
+ * Builder for hypermedia representations.
+ *
+ * @author Greg Turnquist
+ */
+public interface Model {
+
+	/**
+	 * Helper method to create a basic {@link Builder} that will support adding entities and {@link Link}s.
+	 *
+	 * @return
+	 */
+	static Model.Builder builder() {
+		return new DefaultModelBuilder();
+	}
+
+	/**
+	 * Helper method to create a {@link HalModelBuilder} that supports basic and embedded operations.
+	 *
+	 * @return
+	 */
+	static Model.HalModelBuilder hal() {
+		return new HalModelBuilder();
+	}
+
+	/**
+	 * The contract for any hypermedia representation builder.
+	 *
+	 * @author Greg Turnquist
+	 */
+	interface Builder {
+
+		/**
+		 * Add some entity to the representation. Doesn't matter where it's a model or not.
+		 *
+		 * @param entity
+		 * @return
+		 */
+		Builder entity(Object entity);
+
+		/**
+		 * Add a {@link Link} to the representation.
+		 *
+		 * @param link
+		 * @return
+		 */
+		Builder link(Link link);
+
+		/**
+		 * Transform the collected details into a {@link RepresentationModel}.
+		 *
+		 * @return
+		 */
+		RepresentationModel<?> build();
+	}
+
+	/**
+	 * Universal {@link Builder} that assembles simple hypermedia representations with zero or more entities and a
+	 * {@link List} of {@link Link}s. Built {@link RepresentationModel} should work with any hypermedia type.
+	 *
+	 * @author Greg Turnquist
+	 */
+	public static class DefaultModelBuilder implements Builder {
+
+		private final List<Object> entities = new ArrayList<>();
+		private final List<Link> links = new ArrayList<>();
+
+		@Override
+		public Builder entity(Object entity) {
+
+			this.entities.add(entity);
+			return this;
+		}
+
+		@Override
+		public Builder link(Link link) {
+
+			this.links.add(link);
+			return this;
+		}
+
+		@Override
+		public RepresentationModel<?> build() {
+
+			if (this.entities.isEmpty()) {
+
+				return new RepresentationModel<>(this.links);
+
+			} else if (this.entities.size() == 1) {
+
+				Object content = this.entities.get(0);
+
+				if (RepresentationModel.class.isInstance(content)) {
+					return (RepresentationModel<?>) content;
+				} else {
+					return EntityModel.of(content, this.links);
+				}
+
+			} else {
+
+				return CollectionModel.of(this.entities, this.links);
+			}
+		}
+	}
+
+    /**
+     * HAL-specific {@link Builder} that assembles simple hypermedia representations with zero or more entities and a
+     * {@link List} of {@link Link}s. Built {@link RepresentationModel} is aimed at rendering HAL.
+     *
+     * @author Greg Turnquist
+     */
+	public static class HalModelBuilder implements Builder {
+
+		private static final LinkRelation NO_RELATION = LinkRelation.of("___norel___");
+
+		private final Map<LinkRelation, List<Object>> entityModels = new LinkedHashMap<>(); // maintain the original order
+		private final List<Link> links = new ArrayList<>();
+
+		@Override
+		public HalModelBuilder entity(Object entity) {
+			return embed(NO_RELATION, entity);
+		}
+
+		public HalModelBuilder embed(LinkRelation linkRelation, Object entity) {
+
+			this.entityModels.computeIfAbsent(linkRelation, r -> new ArrayList<>()).add(entity);
+			return this;
+		}
+
+		public HalModelBuilder previewFor(LinkRelation linkRelation, Object entity) {
+		    return embed(linkRelation, entity);
+        }
+
+		@Override
+		public HalModelBuilder link(Link link) {
+
+			this.links.add(link);
+			return this;
+		}
+
+		@Override
+		public RepresentationModel<?> build() {
+
+			EmbeddedWrappers wrappers = new EmbeddedWrappers(false);
+
+			return this.entityModels.keySet().stream() //
+					.flatMap(linkRelation -> this.entityModels.get(linkRelation).stream() //
+							.map(model -> wrappers.wrap(model, linkRelation))) //
+					.collect(Collectors.collectingAndThen(Collectors.toList(),
+							embeddedWrappers -> CollectionModel.of(embeddedWrappers, this.links)));
+		}
+	}
+}