#482 - Add support for Collection+JSON media type

Introduce support for media type application/vnd.collection+json. Collection+JSON doesn't allow metadata at the top, so paging data can't be covered, however, everything else fits.

Author: gregturn

pom.xml

@@ -31,6 +31,16 @@
 			</roles>
 			<timezone>+1</timezone>
 		</developer>
+		<developer>
+			<id>gturnquist</id>
+			<name>Greg Turnquist</name>
+			<email>gturnquist(at)pivotal.io</email>
+			<organization>Pivotal, Inc.</organization>
+			<roles>
+				<role>Contributor</role>
+			</roles>
+			<timezone>-6</timezone>
+		</developer>
 	</developers>
 
 	<licenses>

readme.adoc

@@ -0,0 +1,18 @@
+= Spring HATEOAS
+
+This project provides some APIs to ease creating REST representations that follow the http://en.wikipedia.org/wiki/HATEOAS[HATEOAS] principle when working with Spring and especially Spring MVC. The core problem it tries to address is link creation and representation assembly.
+
+== Working with Spring HATEOAS
+
+Since all commits are headlined with its github issue, git will treat it as a comment. To get around this, apply the following configuration to your clone:
+
+[source]
+----
+git config core.commentchar "/"
+----
+
+== Resources
+
+* Reference documentation - http://docs.spring.io/spring-hateoas/docs/current/reference/html/[html], http://docs.spring.io/spring-hateoas/docs/current/reference/pdf/spring-hateoas-reference.pdf[pdf]
+* http://docs.spring.io/spring-hateoas/docs/current-SNAPSHOT/api/[JavaDoc]
+* https://spring.io/guides/gs/rest-hateoas/[Getting started guide]

readme.md

@@ -22,6 +22,7 @@
  * 
  * @author Oliver Gierke
  * @author Przemek Nowak
+ * @author Greg Turnquist
  */
 public class MediaTypes {
 
@@ -34,4 +35,14 @@ public class MediaTypes {
 	 * Public constant media type for {@code application/hal+json}.
 	 */
 	public static final MediaType HAL_JSON = MediaType.valueOf(HAL_JSON_VALUE);
+
+	/**
+	 * A String equivalent of {@link MediaTypes#COLLECTION_JSON}.
+	 */
+	public static final String COLLECTION_JSON_VALUE = "application/vnd.collection+json";
+
+	/**
+	 * Public constant media type for {@code application/vnd.collection+json}.
+	 */
+	public static final MediaType COLLECTION_JSON = MediaType.valueOf(COLLECTION_JSON_VALUE);
 }

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

@@ -29,6 +29,7 @@
  * A simple {@link Resource} wrapping a domain object and adding links to it.
  * 
  * @author Oliver Gierke
+ * @author Greg Turnquist
  */
 @XmlRootElement
 public class Resource<T> extends ResourceSupport {
@@ -38,7 +39,7 @@ public class Resource<T> extends ResourceSupport {
 	/**
 	 * Creates an empty {@link Resource}.
 	 */
-	Resource() {
+	protected Resource() {
 		this.content = null;
 	}
 

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

@@ -15,11 +15,11 @@
  */
 package org.springframework.hateoas.alps;
 
+import java.util.List;
+
 import lombok.Builder;
 import lombok.Value;
 
-import java.util.List;
-
 import org.springframework.hateoas.alps.Descriptor.DescriptorBuilder;
 import org.springframework.hateoas.alps.Doc.DocBuilder;
 import org.springframework.hateoas.alps.Ext.ExtBuilder;

src/main/java/org/springframework/hateoas/alps/Alps.java

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2015 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.collectionjson;
+
+import java.util.List;
+
+import lombok.Builder;
+import lombok.Data;
+import lombok.Singular;
+import lombok.Value;
+
+import org.springframework.hateoas.Link;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Representation of a Collection+JSON.
+ *
+ * @author Greg Turnquist
+ */
+@Data
+@Value
+@Builder(builderMethodName = "collectionJson")
+public class CollectionJson<T> {
+
+	private String version;
+	private String href;
+	private List<Link> links;
+	@Singular private List<Item<T>> items;
+
+	@JsonCreator
+	public CollectionJson(@JsonProperty("version") String version, @JsonProperty("href") String href,
+						  @JsonProperty("links") List<Link> links, @JsonProperty("items") List<Item<T>> items) {
+		this.version = version;
+		this.href = href;
+		this.links = links;
+		this.items = items;
+	}
+
+	public static Item.ItemBuilder item() {
+		return Item.builder();
+	}
+
+}

src/main/java/org/springframework/hateoas/collectionjson/CollectionJson.java

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2015 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.collectionjson;
+
+import org.springframework.hateoas.LinkDiscoverer;
+import org.springframework.hateoas.MediaTypes;
+import org.springframework.hateoas.core.JsonPathLinkDiscoverer;
+
+/**
+ * {@link LinkDiscoverer} implementation based on JSON Collection link structure.
+ *
+ * @author Greg Turnquist
+ */
+public class CollectionJsonLinkDiscoverer extends JsonPathLinkDiscoverer {
+
+	public CollectionJsonLinkDiscoverer() {
+		super("$.collection..links..['%s']..href", MediaTypes.COLLECTION_JSON);
+	}
+}

src/main/java/org/springframework/hateoas/collectionjson/CollectionJsonLinkDiscoverer.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2015 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.collectionjson;
+
+import java.util.List;
+
+import lombok.Data;
+import lombok.Value;
+
+import org.springframework.hateoas.Link;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Wrapper to embed a JSON Collection inside a top-level "collection" attribute.
+ *
+ * @author Greg Turnquist
+ */
+@Data
+@Value
+public class CollectionJsonWrapper<T> {
+
+	private final CollectionJson<T> collection;
+
+	public CollectionJsonWrapper(CollectionJson<T> collection) {
+		this.collection = collection;
+	}
+
+	@JsonCreator
+	public CollectionJsonWrapper(@JsonProperty("version") String version, @JsonProperty("href") String href,
+								 @JsonProperty("links") List<Link> links, @JsonProperty("items") List<Item<T>> items) {
+		this.collection = new CollectionJson(version, href, links, items);
+	}
+
+}

src/main/java/org/springframework/hateoas/collectionjson/CollectionJsonWrapper.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2015 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.springframework.hateoas.collectionjson;
+
+import java.util.List;
+
+import lombok.Builder;
+import lombok.Data;
+import lombok.Singular;
+import lombok.Value;
+
+import org.springframework.hateoas.Link;
+
+import com.fasterxml.jackson.annotation.JsonCreator;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Representation of an item in a JSON Collection.
+ *
+ * @author Greg Turnquist
+ */
+@Data
+@Value
+@Builder
+public class Item<T> {
+
+	private final String href;
+	@Singular("data") private final List<T> data;
+	private final List<Link> links;
+
+	@JsonCreator
+	public Item(@JsonProperty("href") String href, @JsonProperty("data") List<T> data,
+				@JsonProperty("links") List<Link> links) {
+
+		this.href = href;
+		this.data = data;
+		this.links = links;
+	}
+
+}