#416 - Alter ResourceAssemblerSupport.toResources to return Resources

To avoid confusion about what to return on a Spring MVC endpoint, change toResources to not return `List<D>`, but instead `Resources<D>`. This clearly ensures when used to construct Spring MVC endpoints, will return a type Spring HATEOAS will properly marshal.

Related issues: #493
Related pull requests: #572

Author: gregturn

src/main/java/org/springframework/hateoas/mvc/ResourceAssemblerSupport.java

@@ -23,7 +23,9 @@
 import org.springframework.beans.BeanUtils;
 import org.springframework.hateoas.ResourceAssembler;
 import org.springframework.hateoas.ResourceSupport;
+import org.springframework.hateoas.Resources;
 import org.springframework.util.Assert;
+import org.springframework.util.ClassUtils;
 
 /**
  * Base class to implement {@link ResourceAssembler}s. Will automate {@link ResourceSupport} instance creation and make
@@ -57,7 +59,9 @@ public ResourceAssemblerSupport(Class<?> controllerClass, Class<D> resourceType)
 	 * @see #toResource(Object)
 	 * @param entities must not be {@literal null}.
 	 * @return
+	 * @deprecated Results of this method may not render properly if returned by a Spring MVC endpoint. Cast your {@link Iterable} parameter as an {@link Object} to use the new API, which does.
 	 */
+	@Deprecated
 	public List<D> toResources(Iterable<? extends T> entities) {
 
 		Assert.notNull(entities, "Entities must not be null!");
@@ -70,6 +74,29 @@ public List<D> toResources(Iterable<? extends T> entities) {
 		return result;
 	}
 
+	/**
+	 * Converts an {@link Iterable} collection of entities into {@link Resources}. To maintain backward compatibility, using this method requires casting the {@link Iterable} input as an {@link Object}.
+	 *
+	 * TODO: Migrate from {@link Object} to {@link Iterable} when old method is removed and remove the runtime {@link ClassUtils#isAssignable(Class, Class)} check.
+	 *
+	 * @param entities
+	 * @return
+	 */
+	public Resources<D> toResources(Object entities) {
+
+		Assert.isTrue(ClassUtils.isAssignable(Iterable.class, entities.getClass()), "Entities must be Iterable!");
+		Iterable<? extends T> iterableEntities = (Iterable<? extends T>) entities;
+
+		Assert.notNull(entities, "Entities must not be null!");
+		List<D> result = new ArrayList<D>();
+
+		for (T entity : iterableEntities) {
+			result.add(toResource(entity));
+		}
+
+		return new Resources(result);
+	}
+
 	/**
 	 * Creates a new resource with a self link to the given id.
 	 * 

src/test/java/org/springframework/hateoas/mvc/IdentifiableResourceAssemblerSupportUnitTest.java

@@ -28,6 +28,7 @@
 import org.springframework.hateoas.Link;
 import org.springframework.hateoas.LinkBuilder;
 import org.springframework.hateoas.ResourceSupport;
+import org.springframework.hateoas.Resources;
 import org.springframework.hateoas.TestUtils;
 import org.springframework.web.bind.annotation.RequestMapping;
 
@@ -78,7 +79,7 @@ public void unwrapsIdentifyablesForParameters() {
 	}
 
 	@Test
-	public void convertsEntitiesToResources() {
+	public void convertsEntitiesToResourcesUsingDeprecatedSignature() {
 
 		Person first = new Person();
 		first.id = 1L;
@@ -99,6 +100,28 @@ public void convertsEntitiesToResources() {
 		assertThat(result, hasItems(firstResource, secondResource));
 	}
 
+	@Test
+	public void convertsEntitiesToResourcesUsingNewSignature() {
+
+		Person first = new Person();
+		first.id = 1L;
+		Person second = new Person();
+		second.id = 2L;
+
+		Resources<PersonResource> result = assembler.toResources((Object) Arrays.asList(first, second));
+
+		LinkBuilder builder = linkTo(PersonController.class);
+
+		PersonResource firstResource = new PersonResource();
+		firstResource.add(builder.slash(1L).withSelfRel());
+
+		PersonResource secondResource = new PersonResource();
+		secondResource.add(builder.slash(1L).withSelfRel());
+
+		assertThat(result.getContent().size(), is(2));
+		assertThat(result, hasItems(firstResource, secondResource));
+	}
+
 	@RequestMapping("/people")
 	static class PersonController {