Initial commit.

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

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2012 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;
+
+import java.io.Serializable;
+
+/**
+ * Interface to mark objects that are identifiable by an ID of any type.
+ * 
+ * @author Oliver Gierke
+ */
+public interface Identifiable<ID extends Serializable> {
+
+	/**
+	 * Returns the id identifying the object.
+	 * 
+	 * @return the identifier or {@literal null} if not available.
+	 */
+	ID getId();
+}

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

@@ -0,0 +1,138 @@
+/*
+ * Copyright 2012 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;
+
+import java.io.Serializable;
+
+import javax.xml.bind.annotation.XmlAttribute;
+import javax.xml.bind.annotation.XmlType;
+
+import org.springframework.util.Assert;
+
+/**
+ * Value object for links.
+ * 
+ * @author Oliver Gierke
+ */
+@XmlType(name = "link", namespace = Link.ATOM_NAMESPACE)
+public class Link implements Serializable {
+
+	private static final long serialVersionUID = -9037755944661782121L;
+
+	public static final String ATOM_NAMESPACE = "http://www.w3.org/2005/Atom";
+
+	public static final String REL_SELF = "self";
+	public static final String REL_FIRST = "first";
+	public static final String REL_PREVIOUS = "previous";
+	public static final String REL_NEXT = "next";
+	public static final String REL_LAST = "last";
+
+	@XmlAttribute
+	private String rel;
+	@XmlAttribute
+	private String href;
+
+	/**
+	 * Creates a new link to the given URI with the self rel.
+	 * 
+	 * @see #REL_SELF
+	 * @param href must not be {@literal null} or empty.
+	 */
+	public Link(String href) {
+		this(href, REL_SELF);
+	}
+
+	/**
+	 * Creates a new {@link Link} to the given URI with the given rel.
+	 * 
+	 * @param href must not be {@literal null} or empty.
+	 * @param rel must not be {@literal null} or empty.
+	 */
+	public Link(String href, String rel) {
+
+		Assert.hasText(href, "Href must not be null or empty!");
+		Assert.hasText(rel, "Rel must not be null or empty!");
+
+		this.href = href;
+		this.rel = rel;
+	}
+
+	/**
+	 * Empty constructor required by the marshalling framework.
+	 */
+	protected Link() {
+
+	}
+
+	/**
+	 * Returns the actual URI the link is pointing to.
+	 * 
+	 * @return
+	 */
+	public String getHref() {
+		return href;
+	}
+
+	/**
+	 * Returns the rel of the link.
+	 * 
+	 * @return
+	 */
+	public String getRel() {
+		return rel;
+	}
+
+	/* 
+	 * (non-Javadoc)
+	 * @see java.lang.Object#equals(java.lang.Object)
+	 */
+	@Override
+	public boolean equals(Object obj) {
+
+		if (this == obj) {
+			return true;
+		}
+
+		if (!(obj instanceof Link)) {
+			return false;
+		}
+
+		Link that = (Link) obj;
+
+		return this.href.equals(that.href) && this.rel.equals(that.rel);
+	}
+
+	/* (non-Javadoc)
+	 * @see java.lang.Object#hashCode()
+	 */
+	@Override
+	public int hashCode() {
+
+		int result = 17;
+		result += 31 * href.hashCode();
+		result += 31 * rel.hashCode();
+		return result;
+	}
+
+	/* 
+	 * (non-Javadoc)
+	 * @see java.lang.Object#toString()
+	 */
+	@Override
+	public String toString() {
+		return String.format("{ rel : %s, href : %s }", rel, href);
+	}
+}

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

@@ -0,0 +1,32 @@
+/*
+ * Copyright 2012 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;
+
+/**
+ * Interface for components that convert a domain type into an {@link ResourceSupport}.
+ * 
+ * @author Oliver Gierke
+ */
+public interface ResourceAssembler<T, D extends ResourceSupport> {
+
+	/**
+	 * Converts the given entity into an {@link ResourceSupport}.
+	 * 
+	 * @param entity
+	 * @return
+	 */
+	D toResource(T entity);
+}

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

@@ -0,0 +1,130 @@
+/*
+ * Copyright 2012 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;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+import javax.xml.bind.annotation.XmlElement;
+
+import org.springframework.util.Assert;
+
+/**
+ * Base class for DTOs to collect links.
+ * 
+ * @author Oliver Gierke
+ */
+public class ResourceSupport implements Identifiable<Link> {
+
+	@XmlElement(name = "link", namespace = Link.ATOM_NAMESPACE)
+	private List<Link> links;
+
+	public ResourceSupport() {
+		this.links = new ArrayList<Link>();
+	}
+
+	/**
+	 * Returns the {@link Link} with a rel of {@link Link#REL_SELF}.
+	 */
+	public Link getId() {
+		return getLink(Link.REL_SELF);
+	}
+
+	/**
+	 * Adds the given link to the resource.
+	 * 
+	 * @param link
+	 */
+	public void add(Link link) {
+		Assert.notNull(link, "Link must not be null!");
+		this.links.add(link);
+	}
+
+	public void add(Iterable<Link> links) {
+		Assert.notNull(links, "Given links must not be null!");
+		for (Link candidate : links) {
+			add(candidate);
+		}
+	}
+
+	public boolean hasLinks() {
+		return !this.links.isEmpty();
+	}
+
+	public boolean hasLink(String rel) {
+		return getLink(rel) != null;
+	}
+
+	public List<Link> getLinks() {
+		return Collections.unmodifiableList(links);
+	}
+
+	/**
+	 * Returns the link with the given rel.
+	 * 
+	 * @param rel
+	 * @return the link with the given rel or {@literal null} if none found.
+	 */
+	public Link getLink(String rel) {
+
+		for (Link link : links) {
+			if (link.getRel().equals(rel)) {
+				return link;
+			}
+		}
+
+		return null;
+	}
+
+	/* 
+	 * (non-Javadoc)
+	 * @see java.lang.Object#equals(java.lang.Object)
+	 */
+	@Override
+	public boolean equals(Object obj) {
+
+		if (this == obj) {
+			return true;
+		}
+
+		if (!obj.getClass().equals(this.getClass())) {
+			return false;
+		}
+
+		ResourceSupport that = (ResourceSupport) obj;
+
+		return this.links.equals(that.links);
+	}
+
+	/* 
+	 * (non-Javadoc)
+	 * @see java.lang.Object#hashCode()
+	 */
+	@Override
+	public int hashCode() {
+		return this.links.hashCode();
+	}
+
+	/* 
+	 * (non-Javadoc)
+	 * @see java.lang.Object#toString()
+	 */
+	@Override
+	public String toString() {
+		return this.links.toString();
+	}
+}

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

@@ -0,0 +1,136 @@
+/*
+ * Copyright 2012 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.mvc;
+
+import java.net.URI;
+
+import org.springframework.core.annotation.AnnotationUtils;
+import org.springframework.hateoas.Identifiable;
+import org.springframework.hateoas.Link;
+import org.springframework.util.Assert;
+import org.springframework.util.StringUtils;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.servlet.support.ServletUriComponentsBuilder;
+import org.springframework.web.util.UriComponents;
+import org.springframework.web.util.UriComponentsBuilder;
+import org.springframework.web.util.UriTemplate;
+
+/**
+ * Builder to ease building {@link Link} instances pointing to Spring MVC controllers.
+ * 
+ * @author Oliver Gierke
+ */
+public class ControllerLinkBuilder {
+
+	private final UriComponents builder;
+
+	/**
+	 * Creates a new {@link ControllerLinkBuilder}.
+	 * 
+	 * @param builder must not be {@literal null}.
+	 */
+	private ControllerLinkBuilder(UriComponentsBuilder builder) {
+		Assert.notNull(builder);
+		this.builder = builder.build();
+	}
+
+	/**
+	 * Creates a new {@link ControllerLinkBuilder} with a base of the mapping annotated to the given controller class.
+	 * 
+	 * @param controller
+	 * @return
+	 */
+	public static ControllerLinkBuilder linkTo(Class<?> controller) {
+		return linkTo(controller, new Object[0]);
+	}
+
+	public static ControllerLinkBuilder linkTo(Class<?> controller, Object... parameters) {
+
+		RequestMapping annotation = controller.getAnnotation(RequestMapping.class);
+		String[] mapping = annotation == null ? new String[0] : (String[]) AnnotationUtils.getValue(annotation);
+
+		if (mapping.length > 1) {
+			throw new IllegalStateException("Multiple controller mappings defined! Unable to build URI!");
+		}
+
+		ControllerLinkBuilder builder = new ControllerLinkBuilder(ServletUriComponentsBuilder.fromCurrentServletMapping());
+
+		if (mapping.length == 0) {
+			return builder;
+		}
+
+		UriTemplate template = new UriTemplate(mapping[0]);
+		return builder.slash(template.expand(parameters));
+	}
+
+	/**
+	 * Adds the given object's {@link String} representation as sub-resource to the current URI.
+	 * 
+	 * @param object
+	 * @return
+	 */
+	public ControllerLinkBuilder slash(Object object) {
+
+		if (object == null) {
+			return this;
+		}
+
+		String[] segments = StringUtils.tokenizeToStringArray(object.toString(), "/");
+		return new ControllerLinkBuilder(UriComponentsBuilder.fromUri(builder.toUri()).pathSegment(segments));
+	}
+
+	/**
+	 * Adds the given {@link AbstractEntity}'s id as sub-resource. Will simply return the current builder if the given
+	 * entity is {@literal null}.
+	 * 
+	 * @param identifyable
+	 * @return
+	 */
+	public ControllerLinkBuilder slash(Identifiable<?> identifyable) {
+
+		if (identifyable == null) {
+			return this;
+		}
+
+		return slash(identifyable.getId());
+	}
+
+	/**
+	 * Returns a URI resulting from the builder.
+	 * 
+	 * @return
+	 */
+	public URI toUri() {
+		return builder.encode().toUri();
+	}
+
+	public Link withRel(String rel) {
+		return new Link(this.toString(), rel);
+	}
+
+	public Link withSelfRel() {
+		return new Link(this.toString());
+	}
+
+	/*
+	 * (non-Javadoc)
+	 * @see java.lang.Object#toString()
+	 */
+	@Override
+	public String toString() {
+		return toUri().normalize().toASCIIString();
+	}
+}

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

@@ -0,0 +1,157 @@
+/*
+ * Copyright 2012 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 coimport javax.xml.bind.annotation.XmlNs;
+import javax.xml.bind.annotation.XmlSchema;
+
+
+eed 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.mvc;
+
+import static org.springframework.hateoas.mvc.ControllerLinkBuilder.*;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+import org.springframework.beans.BeanUtils;
+import org.springframework.hateoas.Identifiable;
+import org.springframework.hateoas.ResourceAssembler;
+import org.springframework.hateoas.ResourceSupport;
+import org.springframework.util.Assert;
+
+/**
+ * Base class to implement {@link ResourceAssembler}s. Will automate {@link ResourceSupport} instance creation and make
+ * sure a self-link is always added.
+ * 
+ * @author Oliver Gierke
+ */
+public abstract class ResourceAssemblerSupport<T extends Identifiable<?>, D extends ResourceSupport> implements
+		ResourceAssembler<T, D> {
+
+	public static class EntityId {
+
+		private final Object id;
+
+		public EntityId(Object id) {
+			Assert.notNull(id);
+			this.id = id;
+		}
+
+		public static EntityId id(Object object) {
+			return new EntityId(object);
+		}
+
+		@Override
+		public String toString() {
+			return this.id.toString();
+		}
+	}
+
+	private final Class<?> controllerClass;
+	private final Class<D> resourceType;
+
+	/**
+	 * Creates a new {@link ResourceAssemblerSupport} using the given controller class and resource type.
+	 * 
+	 * @param controllerClass must not be {@literal null}.
+	 * @param resourceType must not be {@literal null}.
+	 */
+	public ResourceAssemblerSupport(Class<?> controllerClass, Class<D> resourceType) {
+
+		Assert.notNull(controllerClass);
+		Assert.notNull(resourceType);
+
+		this.controllerClass = controllerClass;
+		this.resourceType = resourceType;
+	}
+
+	/**
+	 * Converts all given entities into resources.
+	 * 
+	 * @see #toResource(Object)
+	 * @param entities
+	 * @return
+	 */
+	public List<D> toResources(Iterable<? extends T> entities) {
+
+		List<D> result = new ArrayList<D>();
+
+		for (T entity : entities) {
+			result.add(toResource(entity));
+		}
+
+		return result;
+	}
+
+	/**
+	 * Creates a new resource and adds a self link to it consisting using the {@link Identifiable}'s id.
+	 * 
+	 * @param entity must not be {@literal null}.
+	 * @return
+	 */
+	protected D createResource(T entity) {
+		return createResource(entity, new Object[0]);
+	}
+
+	protected D createResource(T entity, Object... parameters) {
+		return createResource(entity, EntityId.id(entity.getId()), parameters);
+	}
+
+	/**
+	 * Creates a new resource with a self link to the given id.
+	 * 
+	 * @param entity
+	 * @param id
+	 * @return
+	 */
+	protected D createResource(T entity, EntityId id) {
+		return createResource(entity, id, new Object[0]);
+	}
+
+	protected D createResource(T entity, EntityId id, Object... parameters) {
+
+		Assert.notNull(entity);
+		Assert.notNull(id);
+
+		D instance = instantiateResource(entity);
+		instance.add(linkTo(controllerClass, unwrapIdentifyables(parameters)).slash(id).withSelfRel());
+		return instance;
+	}
+
+	/**
+	 * Extracts the ids of the given values in case they're {@link Identifiable}s. Returns all other objects as they are.
+	 * 
+	 * @param values must not be {@literal null}.
+	 * @return
+	 */
+	private Object[] unwrapIdentifyables(Object[] values) {
+
+		List<Object> result = new ArrayList<Object>(values.length);
+
+		for (Object element : Arrays.asList(values)) {
+			result.add((element instanceof Identifiable) ? ((Identifiable<?>) element).getId() : element);
+		}
+
+		return result.toArray();
+	}
+
+	/**
+	 * Instantiates the resource object. Default implementation will assume a no-arg constructor and use reflection but
+	 * can be overridden to manually set up the object instance initially (e.g. to improve performance if this becomes an
+	 * issue).
+	 * 
+	 * @param entity
+	 * @return
+	 */
+	protected D instantiateResource(T entity) {
+		return BeanUtils.instantiateClass(resourceType);
+	}
+}

src/main/java/org/springframework/hateoas/mvc/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Spring MVC helper classes to build {@link org.springframework.hateoas.Link}s and assemble 
+ * {@link org.springframework.hateoas.ResourceSupport} types.
+ */
+package org.springframework.hateoas.mvc;
+

src/main/java/org/springframework/hateoas/package-info.java

@@ -0,0 +1,9 @@
+/**
+ * Value objects to ease creating {@link org.springframework.hateoas.Link}s and link driven representations for REST webservices.
+ */
+@XmlSchema(xmlns = { @XmlNs(prefix = "atom", namespaceURI = org.springframework.hateoas.Link.ATOM_NAMESPACE) }, elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED)
+package org.springframework.hateoas;
+
+import javax.xml.bind.annotation.XmlNs;
+import javax.xml.bind.annotation.XmlSchema;
+