issue #288

This change allows links behind certain rels to always be wrapped by an array regardless of cardinality.

Author: vivin

readme.md

@@ -306,6 +306,35 @@ Note that now the prefix `ex:` automatically appears before all rels which are n
 
 Since the purpose of the `CurieProvider` API is to allow for automatic curie creation, you can define only one `CurieProvider` bean per application scope.
 
+## Controlling the representation of links in HAL
+Links behind a link-relation in HAL are serialized into a link-object if there is only one link, and into an array of link-objects if there is more than one link. Sometimes it is desirable to always serialize links behind certain link-relations into an array, regardless of whether there is one link or many. You can do this with with the `HalMultipleLinkRels` class:
+
+```java
+@Configuration
+@EnableWebMvc
+@EnableHypermediaSupport(type= {HypermediaType.HAL})
+public class Config {
+
+  @Bean
+  public HalMultipleLinkRels halMultipleLinkRels() {
+    return new HalMultipleLinkRels("order");
+  }
+}
+```
+
+Now, regardless of whether there is one link or many links behind the `order` rel, the link will always be wrapped inside an array:
+
+```java
+{
+  _links: {
+    self: { href: "http://myhost/person/1" },
+    "order": [
+        { href: "http://myhost/person/1/orders/1" }
+    ]
+  }
+}
+```
+
 ## Traverson
 
 As of version 0.11 Spring HATEOAS provides an API for client side service traversal inspired by the [Traverson](https://blog.codecentric.de/en/2013/11/traverson/) JavaScript library.

src/main/java/org/springframework/hateoas/config/HypermediaSupportBeanDefinitionRegistrar.java

@@ -5,7 +5,7 @@
  * 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
+ *	  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,
@@ -52,6 +52,7 @@
 import org.springframework.hateoas.core.EvoInflectorRelProvider;
 import org.springframework.hateoas.hal.CurieProvider;
 import org.springframework.hateoas.hal.HalLinkDiscoverer;
+import org.springframework.hateoas.hal.HalMultipleLinkRels;
 import org.springframework.hateoas.hal.Jackson2HalModule;
 import org.springframework.hateoas.mvc.TypeConstrainedMappingJackson2HttpMessageConverter;
 import org.springframework.http.converter.HttpMessageConverter;
@@ -281,11 +282,12 @@ private List<HttpMessageConverter<?>> potentiallyRegisterModule(List<HttpMessage
 			}
 
 			CurieProvider curieProvider = getCurieProvider(beanFactory);
+			HalMultipleLinkRels halMultipleLinkRels = getHalMultipleLinkRels(beanFactory);
 			RelProvider relProvider = beanFactory.getBean(DELEGATING_REL_PROVIDER_BEAN_NAME, RelProvider.class);
 			ObjectMapper halObjectMapper = beanFactory.getBean(HAL_OBJECT_MAPPER_BEAN_NAME, ObjectMapper.class);
 
 			halObjectMapper.registerModule(new Jackson2HalModule());
-			halObjectMapper.setHandlerInstantiator(new Jackson2HalModule.HalHandlerInstantiator(relProvider, curieProvider));
+			halObjectMapper.setHandlerInstantiator(new Jackson2HalModule.HalHandlerInstantiator(relProvider, curieProvider, halMultipleLinkRels));
 
 			MappingJackson2HttpMessageConverter halConverter = new TypeConstrainedMappingJackson2HttpMessageConverter(
 					ResourceSupport.class);
@@ -306,5 +308,13 @@ private static CurieProvider getCurieProvider(BeanFactory factory) {
 				return null;
 			}
 		}
+
+		private static HalMultipleLinkRels getHalMultipleLinkRels(BeanFactory factory) {
+			try {
+				return factory.getBean(HalMultipleLinkRels.class);
+			} catch(NoSuchBeanDefinitionException e) {
+				return null;
+			}
+		}
 	}
 }

src/main/java/org/springframework/hateoas/hal/HalMultipleLinkRels.java

@@ -0,0 +1,32 @@
+package org.springframework.hateoas.hal;
+
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Set;
+
+/**
+ * Class to maintain relations whose links must always be serialized as an array regardless of cardinality.
+ *
+ * In HAL, if there is only one link behind a rel, it can be serialized directly into a link object; otherwise
+ * the links behind the rel are serialized into an array of link objects.
+ *
+ * However, the HAL specification says that links behind certain rels can always be represented as an array
+ * regardless of cardinality. This class helps you do that. If a rel is specified here, links under it will
+ * always be serialized into an array across all resources.
+ *
+ * @author Vivin Paliath
+ */
+public class HalMultipleLinkRels {
+
+	private final Set<String> rels;
+
+	public HalMultipleLinkRels(String... rels) {
+		this.rels = new HashSet<String>(Arrays.asList(rels));
+	}
+
+	public Set<String> getRels() {
+		return Collections.unmodifiableSet(rels);
+	}
+}

src/main/java/org/springframework/hateoas/hal/Jackson2HalModule.java

@@ -5,7 +5,7 @@
  * 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
+ *	  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,
@@ -110,16 +110,18 @@ public static class HalLinkListSerializer extends ContainerSerializer<List<Link>
 
 		private final BeanProperty property;
 		private final CurieProvider curieProvider;
+		private final HalMultipleLinkRels halMultipleLinkRels;
 
-		public HalLinkListSerializer(CurieProvider curieProvider) {
-			this(null, curieProvider);
+		public HalLinkListSerializer(CurieProvider curieProvider, HalMultipleLinkRels halMultipleLinkRels) {
+			this(null, curieProvider, halMultipleLinkRels);
 		}
 
-		public HalLinkListSerializer(BeanProperty property, CurieProvider curieProvider) {
+		public HalLinkListSerializer(BeanProperty property, CurieProvider curieProvider, HalMultipleLinkRels halMultipleLinkRels) {
 
 			super(List.class, false);
 			this.property = property;
 			this.curieProvider = curieProvider;
+			this.halMultipleLinkRels = halMultipleLinkRels;
 		}
 
 		/*
@@ -167,7 +169,7 @@ public void serialize(List<Link> value, JsonGenerator jgen, SerializerProvider p
 			JavaType mapType = typeFactory.constructMapType(HashMap.class, keyType, valueType);
 
 			MapSerializer serializer = MapSerializer.construct(new String[] {}, mapType, true, null,
-					provider.findKeySerializer(keyType, null), new OptionalListJackson2Serializer(property), null);
+					provider.findKeySerializer(keyType, null), new OptionalListJackson2Serializer(property, halMultipleLinkRels), null);
 
 			serializer.serialize(sortedLinks, jgen, provider);
 		}
@@ -179,7 +181,7 @@ public void serialize(List<Link> value, JsonGenerator jgen, SerializerProvider p
 		@Override
 		public JsonSerializer<?> createContextual(SerializerProvider provider, BeanProperty property)
 				throws JsonMappingException {
-			return new HalLinkListSerializer(property, curieProvider);
+			return new HalLinkListSerializer(property, curieProvider, halMultipleLinkRels);
 		}
 
 		/*
@@ -320,21 +322,24 @@ public static class OptionalListJackson2Serializer extends ContainerSerializer<O
 
 		private final BeanProperty property;
 		private final Map<Class<?>, JsonSerializer<Object>> serializers;
+		private final HalMultipleLinkRels halMultipleLinkRels;
 
 		public OptionalListJackson2Serializer() {
-			this(null);
+			this(null, new HalMultipleLinkRels());
 		}
 
 		/**
-		 * Creates a new {@link OptionalListJackson2Serializer} using the given {@link BeanProperty}.
-		 * 
+		 * Creates a new {@link OptionalListJackson2Serializer} using the given {@link BeanProperty} and
+		 * {@link HalMultipleLinkRels}.
+		 *
 		 * @param property
 		 */
-		public OptionalListJackson2Serializer(BeanProperty property) {
+		public OptionalListJackson2Serializer(BeanProperty property, HalMultipleLinkRels halMultipleLinkRels) {
 
 			super(List.class, false);
 			this.property = property;
 			this.serializers = new HashMap<Class<?>, JsonSerializer<Object>>();
+			this.halMultipleLinkRels = halMultipleLinkRels;
 		}
 
 		/*
@@ -361,6 +366,18 @@ public void serialize(Object value, JsonGenerator jgen, SerializerProvider provi
 			}
 
 			if (list.size() == 1) {
+				Object element = list.get(0);
+				if(element instanceof Link) {
+					Link link = (Link) element;
+					if(halMultipleLinkRels.getRels().contains(link.getRel())) {
+						jgen.writeStartArray();
+						serializeContents(list.iterator(), jgen, provider);
+						jgen.writeEndArray();
+
+						return;
+					}
+				}
+
 				serializeContents(list.iterator(), jgen, provider);
 				return;
 			}
@@ -443,7 +460,7 @@ public boolean isEmpty(Object arg0) {
 		@Override
 		public JsonSerializer<?> createContextual(SerializerProvider provider, BeanProperty property)
 				throws JsonMappingException {
-			return new OptionalListJackson2Serializer(property);
+			return new OptionalListJackson2Serializer(property, halMultipleLinkRels);
 		}
 	}
 
@@ -598,15 +615,19 @@ public static class HalHandlerInstantiator extends HandlerInstantiator {
 		private final Map<Class<?>, Object> instanceMap = new HashMap<Class<?>, Object>();
 
 		public HalHandlerInstantiator(RelProvider resolver, CurieProvider curieProvider) {
-			this(resolver, curieProvider, true);
+			this(resolver, curieProvider, new HalMultipleLinkRels(), true);
+		}
+
+		public HalHandlerInstantiator(RelProvider resolver, CurieProvider curieProvider, HalMultipleLinkRels halMultipleLinkRels) {
+			this(resolver, curieProvider, halMultipleLinkRels, true);
 		}
 
-		public HalHandlerInstantiator(RelProvider resolver, CurieProvider curieProvider, boolean enforceEmbeddedCollections) {
+		public HalHandlerInstantiator(RelProvider resolver, CurieProvider curieProvider, HalMultipleLinkRels halMultipleLinkRels, boolean enforceEmbeddedCollections) {
 
 			Assert.notNull(resolver, "RelProvider must not be null!");
 			this.instanceMap.put(HalResourcesSerializer.class, new HalResourcesSerializer(resolver, curieProvider,
 					enforceEmbeddedCollections));
-			this.instanceMap.put(HalLinkListSerializer.class, new HalLinkListSerializer(curieProvider));
+			this.instanceMap.put(HalLinkListSerializer.class, new HalLinkListSerializer(curieProvider, halMultipleLinkRels));
 		}
 
 		private Object findInstance(Class<?> type) {

src/test/java/org/springframework/hateoas/hal/Jackson2HalIntegrationTest.java

@@ -5,7 +5,7 @@
  * 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
+ *	  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,
@@ -50,6 +50,7 @@
 public class Jackson2HalIntegrationTest extends AbstractJackson2MarshallingIntegrationTest {
 
 	static final String SINGLE_LINK_REFERENCE = "{\"_links\":{\"self\":{\"href\":\"localhost\"}}}";
+	static final String SINGLE_LINK_ARRAY_REFERENCE = "{\"_links\":{\"multiple\":[{\"href\":\"localhost\"}]}}";
 	static final String LIST_LINK_REFERENCE = "{\"_links\":{\"self\":[{\"href\":\"localhost\"},{\"href\":\"localhost2\"}]}}";
 
 	static final String SIMPLE_EMBEDDED_RESOURCE_REFERENCE = "{\"_links\":{\"self\":{\"href\":\"localhost\"}},\"_embedded\":{\"content\":[\"first\",\"second\"]}}";
@@ -109,6 +110,16 @@ public void rendersMultipleLinkAsArray() throws Exception {
 		assertThat(write(resourceSupport), is(LIST_LINK_REFERENCE));
 	}
 
+	@Test
+	public void rendersSingleLinkAsArrayWhenConfigured() throws Exception {
+		mapper.setHandlerInstantiator(new HalHandlerInstantiator(new AnnotationRelProvider(), null, new HalMultipleLinkRels("multiple")));
+
+		ResourceSupport resourceSupport = new ResourceSupport();
+		resourceSupport.add(new Link("localhost").withRel("multiple"));
+
+		assertThat(write(resourceSupport), is(SINGLE_LINK_ARRAY_REFERENCE));
+	}
+
 	@Test
 	public void deserializeMultipleLinks() throws Exception {