#833 - Changed ResourceSupport class name hierarchy.

Author: odrotbohm

etc/migrate-to-1.0.sh

@@ -38,6 +38,7 @@ FILES=`find . -name "$FILES_PATTERN"`
 EXPRESSION="s/Link\.REL_SELF/IanaLinkRelations.SELF/g;\
 s/Link\.REL_PREV/IanaLinkRelations.PREV/g;\
 s/Link\.REL_NEXT/IanaLinkRelations.NEXT/g;\
+\
 s/hateoas\.EntityLinks/hateoas.server.EntityLinks/g;\
 s/hateoas\.JsonPathLinkDiscoverer/hateoas.client.JsonPathLinkDiscoverer/g;\
 s/hateoas\.LinkBuilder/hateoas.server.LinkBuilder/g;\
@@ -47,7 +48,11 @@ s/hateoas\.MethodLinkBuilderFactory/hateoas.server.MethodLinkBuilderFactory/g;\
 s/hateoas\.RelProvider/hateoas.server.RelProvider/g;\
 s/hateoas\.ResourceAssembler/hateoas.server.ResourceAssembler/g;\
 s/hateoas\.ResourceProcessor/hateoas.server.ResourceProcessor/g;\
+s/hateoas\.VndErrors/hateoas.mediatype.vnderror.VndErrors/g;\
+s/hateoas\.VndErrors.VndError/hateoas.mediatype.vnderror.VndErrors.VndError/g;\
+\
 s/hateoas\.alps/hateoas.mediatype.alps/g;\
+\
 s/hateoas\.core\.AbstractEntityLinks/hateoas.server.core.AbstractEntityLinks/g;\
 s/hateoas\.core\.AnnotationAttribute/hateoas.server.core.AnnotationAttribute/g;\
 s/hateoas\.core\.AnnotationMappingDiscoverer/hateoas.server.core.AnnotationMappingDiscoverer/g;\
@@ -57,7 +62,9 @@ s/hateoas\.core\.EvoInflectorRelProvider/hateoas.server.core.EvoInflectorRelProv
 s/hateoas\.core\.JsonPathLinkDiscoverer/hateoas.client.JsonPathLinkDiscoverer/g;\
 s/hateoas\.core\.LinkBuilderSupport/hateoas.server.core.LinkBuilderSupport/g;\
 s/hateoas\.core\.MethodParameters/hateoas.server.core.MethodParameters/g;\
+\
 s/hateoas\.hal/hateoas.mediatype.hal/g;\
+\
 s/hateoas\.mvc\.ControllerLinkBuilder/hateoas.server.mvc.WebMvcLinkBuilder/g;\
 s/hateoas\.mvc\.ControllerLinkBuilderFactory/hateoas.server.mvc.WebMvcLinkBuilderFactory/g;\
 s/hateoas\.mvc\.HeaderLinksResponseEntity/hateoas.server.core.HeaderLinksResponseEntity/g;\
@@ -66,12 +73,35 @@ s/hateoas\.mvc\.ResourceProcessorInvokingHandlerAdapter/hateoas.server.mvc.Resou
 s/hateoas\.mvc\.TypeConstrainedMappingJackson2HttpMessageConverter/hateoas.server.mvc.TypeConstrainedMappingJackson2HttpMessageConverter/g;\
 s/hateoas\.mvc\.UriComponentsContributor/hateoas.server.mvc.UriComponentsContributor/g;\
 s/ControllerLinkBuilderFactory/WebMvcLinkBuilderFactory/g;\
-s/ControllerLinkBuilder/WebMvcLinkBuilder/g;"
+s/ControllerLinkBuilder/WebMvcLinkBuilder/g;\
+\
+s/\([^a-z]\)ResourceProcessorInvokingHandlerAdapter\([ ><,#();\.]\)/\1RepresentationModelProcessorInvokingHandlerAdapter\2/g;\
+s/\([^a-z]\)ResourceProcessorInvoker\([ ><,#();\.]\)/\1RepresentationModelProcessorInvoker\2/g;\
+s/\([^a-z]\)ResourceProcessor\([ ><,#();\.]\)/\1RepresentationModelProcessor\2/g;\
+\
+s/ ResourceAssembler / RepresentationModelAssembler /g;\
+s/\.ResourceAssembler;/.RepresentationModelAssembler;/g;\
+s/ResourceAssembler\([<#]\)/RepresentationModelAssembler\1/g;\
+s/IdentifiableResourceAssemblerSupport/IdentifiableRepresentationModelAssemblerSupport/g;\
+s/toResource(/toModel(/g;\
+s/toResources(/toCollectionModel(/g;\
+\
+s/\([^a-z]\)ResourceSupport\([ ><,#();\.]\)/\1RepresentationModel\2/g;\
+s/\([^a-z]\)PagedResources\([ ><,#();\.]\)/\1PagedModel\2/g;\
+s/\([^a-z]\)Resources\([ ><,#();\.]\)/\1CollectionModel\2/g;\
+s/\([^a-z]\)Resource\([ ><,#();\.]\)/\1EntityModel\2/g;\
+\
+s/linkForSingleResource/linkForItemResource/g;\
+s/linkToSingleResource/linkToItemResource/g;\
+"
+
+#EXPRESSION="s/[\s\.]PagedResources\([;<]\)/.PagedRepresentationModel\1/g;"
 
 for FILE in $FILES
 do
     echo "Adapting $FILE"
-    sed -i "" $EXPRESSION $FILE
+    # echo $EXPRESSION
+    sed -i "" -e "$EXPRESSION" $FILE
 done
 
 echo
@@ -81,4 +111,7 @@ echo 'If you have used link relation constants defined in Link (like Link.REL_SE
 echo 'codebase, you will have to trigger an organize imports in your IDE to make sure the'
 echo 'now referenced IanaLinkRelations gets imported.'
 echo
+echo "Also, if you were referring to core Spring's Resource type you might see invalid migrations"
+echo "as there's no way for us to differentiate that from Spring HATEOAS Resource type."
+echo
 echo 'After that, review your changes, commit and code on! \ö/'

pom.xml

@@ -563,7 +563,6 @@
 			<groupId>com.jayway.jsonpath</groupId>
 			<artifactId>json-path</artifactId>
 			<version>${jsonpath.version}</version>
-			<optional>true</optional>
 		</dependency>
 
 		<dependency>

src/main/asciidoc/migrate-to-1.0.adoc

@@ -10,13 +10,29 @@ There had been an incredible amount of feedback on it and the major version bump
 The biggest changes in package structure were driven by the introduction of a hypermedia type registration API to support additional media types in Spring HATEOAS.
 This lead to the clear separation of client and server APIs (packages named respectively) as well as media type implementations in the package `mediatype`.
 
-The easiest way to get your codebase upgraded to the new API is by using the <<migrate-to-1.0.script, migration script>>.
-Before we jump to that, here are the changes at a quick glance:
+The easiest way to get your code base upgraded to the new API is by using the <<migrate-to-1.0.script, migration script>>.
+Before we jump to that, here are the changes at a quick glance.
 
-* `ResourceSupport` now exposes a `Links` instance (over a `List<Link>`) as that exposes additional API to concatenate and merge different `Links` instances using various strategies.  
+=== Representation models
+
+The `ResourceSupport`/`Resource`/`Resources`/`PagedResources` group of classes never really felt appropriately named.
+After all, these types do not actually manifest resources but rather representation models that can be enriched with hypermedia information and affordances.
+Here's how new names map to the old ones:
+
+* `ResourceSupport` is now `RepresentationModel`
+* `Resource` is now `EntityModel`
+* `Resources` is now `CollectionModel`
+* `PagedResources` is now `PagedModel`
+
+Consequently, `ResourceAssembler` has been renamed to `RepresentationModelAssembler` and its methods `toResource(…)` and `toResources(…)` have been renamed to `toModel(…)` and `toCollectionModel(…)` respectively.
+Also the name changes have been reflected in the classes contained in `TypeReferences`.
+
+* `RepresentationModel.getLinks()` now exposes a `Links` instance (over a `List<Link>`) as that exposes additional API to concatenate and merge different `Links` instances using various strategies.
+  Also it has been turned into a self-bound generic type to allow the methods that add links to the instance return the instance itself.
 * The `LinkDiscoverer` API has been moved to the `client` package.
-* The `LinkBuilder` API has been moved to the `server` package.
+* The `LinkBuilder` and `EntityLinks` APIs have been moved to the `server` package.
 * `ControllerLinkBuilder` has been moved into `server.mvc` and deprecated to be replaced by `WebMvcLinkBuilder`.
+* `VndError` has been moved to the `mediatype.vnderror` package.
 
 [migrate-to-1.0.script]
 == The migration script

src/main/java/org/springframework/hateoas/Resources.java renamed to src/main/java/org/springframework/hateoas/CollectionModel.java

@@ -31,34 +31,34 @@
  * @author Oliver Gierke
  * @author Greg Turnquist
  */
-public class Resources<T> extends ResourceSupport implements Iterable<T> {
+public class CollectionModel<T> extends RepresentationModel<CollectionModel<T>> implements Iterable<T> {
 
 	private final Collection<T> content;
 
 	/**
-	 * Creates an empty {@link Resources} instance.
+	 * Creates an empty {@link CollectionModel} instance.
 	 */
-	protected Resources() {
+	protected CollectionModel() {
 		this(new ArrayList<>());
 	}
 
 	/**
-	 * Creates a {@link Resources} instance with the given content and {@link Link}s (optional).
+	 * Creates a {@link CollectionModel} instance with the given content and {@link Link}s (optional).
 	 *
 	 * @param content must not be {@literal null}.
-	 * @param links the links to be added to the {@link Resources}.
+	 * @param links the links to be added to the {@link CollectionModel}.
 	 */
-	public Resources(Iterable<T> content, Link... links) {
+	public CollectionModel(Iterable<T> content, Link... links) {
 		this(content, Arrays.asList(links));
 	}
 
 	/**
-	 * Creates a {@link Resources} instance with the given content and {@link Link}s.
+	 * Creates a {@link CollectionModel} instance with the given content and {@link Link}s.
 	 *
 	 * @param content must not be {@literal null}.
-	 * @param links the links to be added to the {@link Resources}.
+	 * @param links the links to be added to the {@link CollectionModel}.
 	 */
-	public Resources(Iterable<T> content, Iterable<Link> links) {
+	public CollectionModel(Iterable<T> content, Iterable<Link> links) {
 
 		Assert.notNull(content, "Content must not be null!");
 
@@ -71,23 +71,24 @@ public Resources(Iterable<T> content, Iterable<Link> links) {
 	}
 
 	/**
-	 * Creates a new {@link Resources} instance by wrapping the given domain class instances into a {@link Resource}.
+	 * Creates a new {@link CollectionModel} instance by wrapping the given domain class instances into a
+	 * {@link EntityModel}.
 	 *
 	 * @param content must not be {@literal null}.
 	 * @return
 	 */
 	@SuppressWarnings("unchecked")
-	public static <T extends Resource<S>, S> Resources<T> wrap(Iterable<S> content) {
+	public static <T extends EntityModel<S>, S> CollectionModel<T> wrap(Iterable<S> content) {
 
 		Assert.notNull(content, "Content must not be null!");
 
 		ArrayList<T> resources = new ArrayList<>();
 
 		for (S element : content) {
-			resources.add((T) new Resource<>(element));
+			resources.add((T) new EntityModel<>(element));
 		}
 
-		return new Resources<>(resources);
+		return new CollectionModel<>(resources);
 	}
 
 	/**
@@ -133,7 +134,7 @@ public boolean equals(Object obj) {
 			return false;
 		}
 
-		Resources<?> that = (Resources<?>) obj;
+		CollectionModel<?> that = (CollectionModel<?>) obj;
 
 		boolean contentEqual = this.content == null ? that.content == null : this.content.equals(that.content);
 		return contentEqual && super.equals(obj);

src/main/java/org/springframework/hateoas/Resource.java renamed to src/main/java/org/springframework/hateoas/EntityModel.java

@@ -23,39 +23,39 @@
 import com.fasterxml.jackson.annotation.JsonUnwrapped;
 
 /**
- * A simple {@link Resource} wrapping a domain object and adding links to it.
- * 
+ * A simple {@link EntityModel} wrapping a domain object and adding links to it.
+ *
  * @author Oliver Gierke
  * @author Greg Turnquist
  */
-public class Resource<T> extends ResourceSupport {
+public class EntityModel<T> extends RepresentationModel<EntityModel<T>> {
 
 	private final T content;
 
 	/**
-	 * Creates an empty {@link Resource}.
+	 * Creates an empty {@link EntityModel}.
 	 */
-	protected Resource() {
+	protected EntityModel() {
 		this.content = null;
 	}
 
 	/**
-	 * Creates a new {@link Resource} with the given content and {@link Link}s (optional).
-	 * 
+	 * Creates a new {@link EntityModel} with the given content and {@link Link}s (optional).
+	 *
 	 * @param content must not be {@literal null}.
-	 * @param links the links to add to the {@link Resource}.
+	 * @param links the links to add to the {@link EntityModel}.
 	 */
-	public Resource(T content, Link... links) {
+	public EntityModel(T content, Link... links) {
 		this(content, Arrays.asList(links));
 	}
 
 	/**
-	 * Creates a new {@link Resource} with the given content and {@link Link}s.
-	 * 
+	 * Creates a new {@link EntityModel} with the given content and {@link Link}s.
+	 *
 	 * @param content must not be {@literal null}.
-	 * @param links the links to add to the {@link Resource}.
+	 * @param links the links to add to the {@link EntityModel}.
 	 */
-	public Resource(T content, Iterable<Link> links) {
+	public EntityModel(T content, Iterable<Link> links) {
 
 		Assert.notNull(content, "Content must not be null!");
 		Assert.isTrue(!(content instanceof Collection), "Content must not be a collection! Use Resources instead!");
@@ -65,15 +65,15 @@ public Resource(T content, Iterable<Link> links) {
 
 	/**
 	 * Returns the underlying entity.
-	 * 
+	 *
 	 * @return the content
 	 */
 	@JsonUnwrapped
 	public T getContent() {
 		return content;
 	}
 
-	/* 
+	/*
 	 * (non-Javadoc)
 	 * @see org.springframework.hateoas.ResourceSupport#toString()
 	 */
@@ -82,7 +82,7 @@ public String toString() {
 		return String.format("Resource { content: %s, %s }", getContent(), super.toString());
 	}
 
-	/* 
+	/*
 	 * (non-Javadoc)
 	 * @see org.springframework.hateoas.ResourceSupport#equals(java.lang.Object)
 	 */
@@ -97,13 +97,13 @@ public boolean equals(Object obj) {
 			return false;
 		}
 
-		Resource<?> that = (Resource<?>) obj;
+		EntityModel<?> that = (EntityModel<?>) obj;
 
 		boolean contentEqual = this.content == null ? that.content == null : this.content.equals(that.content);
 		return contentEqual && super.equals(obj);
 	}
 
-	/* 
+	/*
 	 * (non-Javadoc)
 	 * @see org.springframework.hateoas.ResourceSupport#hashCode()
 	 */

src/main/java/org/springframework/hateoas/PagedResources.java renamed to src/main/java/org/springframework/hateoas/PagedModel.java

@@ -31,39 +31,41 @@
  * @author Oliver Gierke
  * @author Greg Turnquist
  */
-public class PagedResources<T> extends Resources<T> {
+public class PagedModel<T> extends CollectionModel<T> {
 
-	public static PagedResources<?> NO_PAGE = new PagedResources<>();
+	public static PagedModel<?> NO_PAGE = new PagedModel<>();
 
 	private PageMetadata metadata;
 
 	/**
 	 * Default constructor to allow instantiation by reflection.
 	 */
-	protected PagedResources() {
+	protected PagedModel() {
 		this(new ArrayList<>(), null);
 	}
 
 	/**
-	 * Creates a new {@link PagedResources} from the given content, {@link PageMetadata} and {@link Link}s (optional).
+	 * Creates a new {@link PagedModel} from the given content, {@link PageMetadata} and {@link Link}s (optional).
 	 *
 	 * @param content must not be {@literal null}.
 	 * @param metadata
 	 * @param links
 	 */
-	public PagedResources(Collection<T> content, PageMetadata metadata, Link... links) {
+	public PagedModel(Collection<T> content, PageMetadata metadata, Link... links) {
 		this(content, metadata, Arrays.asList(links));
 	}
 
 	/**
-	 * Creates a new {@link PagedResources} from the given content {@link PageMetadata} and {@link Link}s.
+	 * Creates a new {@link PagedModel} from the given content {@link PageMetadata} and {@link Link}s.
 	 *
 	 * @param content must not be {@literal null}.
 	 * @param metadata
 	 * @param links
 	 */
-	public PagedResources(Collection<T> content, PageMetadata metadata, Iterable<Link> links) {
+	public PagedModel(Collection<T> content, PageMetadata metadata, Iterable<Link> links) {
+
 		super(content, links);
+
 		this.metadata = metadata;
 	}
 
@@ -78,23 +80,23 @@ public PageMetadata getMetadata() {
 	}
 
 	/**
-	 * Factory method to easily create a {@link PagedResources} instance from a set of entities and pagination metadata.
+	 * Factory method to easily create a {@link PagedModel} instance from a set of entities and pagination metadata.
 	 *
 	 * @param content must not be {@literal null}.
 	 * @param metadata
 	 * @return
 	 */
 	@SuppressWarnings("unchecked")
-	public static <T extends Resource<S>, S> PagedResources<T> wrap(Iterable<S> content, PageMetadata metadata) {
+	public static <T extends EntityModel<S>, S> PagedModel<T> wrap(Iterable<S> content, PageMetadata metadata) {
 
 		Assert.notNull(content, "Content must not be null!");
 		ArrayList<T> resources = new ArrayList<>();
 
 		for (S element : content) {
-			resources.add((T) new Resource<>(element));
+			resources.add((T) new EntityModel<>(element));
 		}
 
-		return new PagedResources<>(resources, metadata);
+		return new PagedModel<>(resources, metadata);
 	}
 
 	/**
@@ -141,7 +143,7 @@ public boolean equals(Object obj) {
 			return false;
 		}
 
-		PagedResources<?> that = (PagedResources<?>) obj;
+		PagedModel<?> that = (PagedModel<?>) obj;
 		boolean metadataEquals = this.metadata == null ? that.metadata == null : this.metadata.equals(that.metadata);
 
 		return metadataEquals && super.equals(obj);