#340 - Adds new Affordances API + HAL-Forms mediatype

* Introduces new Affordances API to build links related to each other to serve other mediatypes
* Introduces HAL-Forms, which uses affordances to automatically generate HTML form data based on Spring MVC annotations.

Original pull-request: #340, #447, #581
Related issues: #503, #334

Author: gregturn

src/main/asciidoc/index.adoc

@@ -316,7 +316,7 @@ A `RelProvider` is exposed as Spring bean when using `@EnableHypermediaSupport`
 [[spis.curie-provider]]
 === CurieProvider API
 
-The http://tools.ietf.org/html/rfc5988=section-4[Web Linking RFC] describes registered and extension link relation types. Registered rels are well-known strings registered with the http://www.iana.org/assignments/link-relations/link-relations.xhtml[IANA registry of link relation types]. Extension rels can be used by applications that do not wish to register a relation type. They are a URI that uniquely identifies the relation type. The rel URI can be serialized as a compact URI or http://www.w3.org/TR/curie[Curie]. E.g. a curie `ex:persons` stands for the link relation type `http://example.com/rels/persons` if `ex` is defined as `http://example.com/rels/{rels}`. If curies are used, the base URI must be present in the response scope.
+The http://tools.ietf.org/html/rfc5988=section-4[Web Linking RFC] describes registered and extension link relation types. Registered rels are well-known strings registered with the http://www.iana.org/assignments/link-relations/link-relations.xhtml[IANA registry of link relation types]. Extension rels can be used by applications that do not wish to register a relation type. They are a URI that uniquely identifies the relation type. The rel URI can be serialized as a compact URI or http://www.w3.org/TR/curie[Curie]. E.g. a curie `ex:persons` stands for the link relation type `http://example.com/rels/persons` if `ex` is defined as `http://example.com/rels/{rel}`. If curies are used, the base URI must be present in the response scope.
 
 The rels created by the default `RelProvider` are extension relation types and as such must be URIs, which can cause a lot of overhead. The `CurieProvider` API takes care of that: it allows to define a base URI as URI template and a prefix which stands for that base URI. If a `CurieProvider` is present, the `RelProvider` prepends all rels with the curie prefix. Furthermore a `curies` link is automatically added to the HAL resource.
 

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

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2017 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.List;
+import java.util.Map;
+
+import org.springframework.http.MediaType;
+
+/**
+ * Abstract representation of an action a link is able to take. Web frameworks must provide concrete implementation.
+ *
+ * @author Greg Turnquist
+ */
+public interface Affordance {
+
+	/**
+	 * HTTP method this affordance covers. For multiple methods, add multiple {@link Affordance}s.
+	 *
+	 * @return
+	 */
+	String getHttpMethod();
+
+	/**
+	 * Name for the REST action this {@link Affordance} can take.
+	 *
+	 * @return
+	 */
+	String getName();
+
+	/**
+	 * Are the properties on this {@link Affordance} required or not? Distinguish between PUT (all required)
+	 * vs. PATCH (none required).
+	 *
+	 * @return
+	 */
+	boolean isRequired();
+
+	/**
+	 * Collection of the {@link Affordance}'s properties, mapped by {@literal name} and {@link Class}.
+	 * For example, a class Employee { String name, String role } would be mapped as:
+	 * Map(name -> java.lang.String, role -> java.lang.String)
+	 *
+	 * @return
+	 */
+	Map<String, Class<?>> getProperties();
+
+	/**
+	 * The URI of the {@link Affordance} because certain mediatypes need to list it. Other
+	 * mediatypes need to validate that the URI matches the {@literal self} link.
+	 * 
+	 * @return
+	 */
+	String getUri();
+
+	List<AffordanceModel> getAffordanceModel(MediaType mediaType);
+
+	void addAffordanceModels(MediaType mediaType, List<AffordanceModel> affordanceModels);
+}

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

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2017 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;
+
+/**
+ * Marker interface for mediatypes to build up type-specific details for an {@link Affordance}
+ * 
+ * @author Greg Turnquist
+ */
+public interface AffordanceModel {
+
+}

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

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2017 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.List;
+
+import org.springframework.hateoas.core.DummyInvocationUtils.MethodInvocation;
+import org.springframework.http.MediaType;
+import org.springframework.plugin.core.Plugin;
+
+/**
+ * @author Greg Turnquist
+ */
+public abstract class AffordanceModelFactory implements Plugin<MediaType> {
+
+	abstract public MediaType getMediaType();
+
+	abstract public List<AffordanceModel> findAffordanceModels(Affordance affordance, MethodInvocation invocationValue);
+
+	@Override
+	public boolean supports(MediaType delimiter) {
+		return delimiter != null && delimiter.equals(this.getMediaType());
+	}
+}

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

@@ -19,10 +19,10 @@
 import lombok.AllArgsConstructor;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
-import lombok.NoArgsConstructor;
 import lombok.experimental.Wither;
 
 import java.io.Serializable;
+import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
@@ -34,6 +34,7 @@
 import javax.xml.bind.annotation.XmlTransient;
 import javax.xml.bind.annotation.XmlType;
 
+import org.springframework.hateoas.core.LinkBuilderSupport;
 import org.springframework.util.Assert;
 import org.springframework.util.StringUtils;
 
@@ -48,10 +49,9 @@
  */
 @XmlType(name = "link", namespace = Link.ATOM_NAMESPACE)
 @JsonIgnoreProperties("templated")
-@NoArgsConstructor(access = AccessLevel.PROTECTED)
 @AllArgsConstructor(access = AccessLevel.PACKAGE)
 @Getter
-@EqualsAndHashCode(of = { "rel", "href", "hreflang", "media", "title", "deprecation" })
+@EqualsAndHashCode(of = { "rel", "href", "hreflang", "media", "title", "deprecation", "affordances" })
 public class Link implements Serializable {
 
 	private static final long serialVersionUID = -9037755944661782121L;
@@ -73,6 +73,7 @@ public class Link implements Serializable {
 	private @XmlAttribute @Wither String type;
 	private @XmlAttribute @Wither String deprecation;
 	private @XmlTransient @JsonIgnore UriTemplate template;
+	private @XmlTransient @JsonIgnore List<Affordance> affordances;
 
 	/**
 	 * Creates a new link to the given URI with the self rel.
@@ -108,6 +109,32 @@ public Link(UriTemplate template, String rel) {
 		this.template = template;
 		this.href = template.toString();
 		this.rel = rel;
+		this.affordances = new ArrayList<Affordance>();
+	}
+
+	public Link(String href, String rel, List<Affordance> affordances) {
+		
+		this(href, rel);
+
+		Assert.notNull(affordances, "affordances must not be null!");
+		
+		this.affordances = affordances;
+	}
+
+	/**
+	 * Empty constructor required by the marshalling framework.
+	 */
+	protected Link() {
+		this.affordances = new ArrayList<Affordance>();
+	}
+
+	/**
+	 * Returns safe copy of {@link Affordance}s.
+	 * 
+	 * @return
+	 */
+	public List<Affordance> getAffordances() {
+		return new ArrayList<Affordance>(Collections.unmodifiableCollection(this.affordances));
 	}
 
 	/**
@@ -119,6 +146,39 @@ public Link withSelfRel() {
 		return withRel(Link.REL_SELF);
 	}
 
+	/**
+	 * Create new {@link Link} with an additional {@link Affordance}.
+	 *
+	 * @param affordance
+	 * @return
+	 */
+	public Link withAffordance(Affordance affordance) {
+
+		List<Affordance> newAffordances = new ArrayList<Affordance>();
+		newAffordances.addAll(this.affordances);
+		newAffordances.add(affordance);
+
+		return new Link(this.rel, this.href, this.hreflang ,this.media, this.title, this.type,
+			this.deprecation, this.template, newAffordances);
+	}
+
+	/**
+	 * Create new {@link Link} with additional {@link Affordance}s.
+	 * 
+	 * @param affordances
+	 * @return
+	 */
+	public Link addAffordances(List<Affordance> affordances) {
+
+		List<Affordance> newAffordances = new ArrayList<Affordance>();
+		newAffordances.addAll(this.affordances);
+		newAffordances.addAll(affordances);
+
+		return new Link(this.rel, this.href, this.hreflang ,this.media, this.title, this.type,
+			this.deprecation, this.template, newAffordances);
+	}
+
+
 	/**
 	 * Returns the variable names contained in the template.
 	 * 

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

@@ -22,6 +22,7 @@
  * 
  * @author Oliver Gierke
  * @author Przemek Nowak
+ * @author Greg Turnquist
  */
 public class MediaTypes {
 
@@ -34,4 +35,15 @@ public class MediaTypes {
 	 * Public constant media type for {@code application/hal+json}.
 	 */
 	public static final MediaType HAL_JSON = MediaType.valueOf(HAL_JSON_VALUE);
+
+	/**
+	 * Public constant media type for {@code application/prs.hal-forms+json}.
+	 */
+	public static final String HAL_FORMS_JSON_VALUE = "application/prs.hal-forms+json";
+
+	/**
+	 * Public constant media type for {@code applicatino/prs.hal-forms+json}.
+	 */
+	public static final MediaType HAL_FORMS_JSON = MediaType.parseMediaType(HAL_FORMS_JSON_VALUE);
+
 }

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

@@ -20,11 +20,20 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
+
+import lombok.extern.slf4j.Slf4j;
 
 import org.springframework.context.ApplicationContext;
 import org.springframework.context.annotation.Import;
+import org.springframework.context.annotation.ImportSelector;
+import org.springframework.core.type.AnnotationMetadata;
 import org.springframework.hateoas.EntityLinks;
 import org.springframework.hateoas.LinkDiscoverer;
+import org.springframework.hateoas.hal.forms.HalFormsConfiguration;
 
 /**
  * Activates hypermedia support in the {@link ApplicationContext}. Will register infrastructure beans available for
@@ -39,11 +48,13 @@
  * @see LinkDiscoverer
  * @see EntityLinks
  * @author Oliver Gierke
+ * @author Greg Turnquist
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
 @Documented
-@Import({ HypermediaSupportBeanDefinitionRegistrar.class, HateoasConfiguration.class })
+@Import({ HypermediaSupportBeanDefinitionRegistrar.class, HateoasConfiguration.class,
+	EnableHypermediaSupport.HypermediaConfigurationImportSelector.class})
 public @interface EnableHypermediaSupport {
 
 	/**
@@ -58,14 +69,58 @@
 	 * 
 	 * @author Oliver Gierke
 	 */
-	static enum HypermediaType {
+	enum HypermediaType {
 
 		/**
 		 * HAL - Hypermedia Application Language.
 		 * 
 		 * @see http://stateless.co/hal_specification.html
 		 * @see http://tools.ietf.org/html/draft-kelly-json-hal-05
 		 */
-		HAL;
+		HAL,
+
+		/**
+		 * HAL-FORMS - Independent, backward-compatible extension of the HAL designed to add runtime FORM support
+		 * @see https://rwcbook.github.io/hal-forms/
+		 */
+		HAL_FORMS(HalFormsConfiguration.class);
+
+		private final List<Class<?>> configurations;
+
+		HypermediaType(Class<?>... configurations) {
+			this.configurations = Arrays.asList(configurations);
+		}
+	}
+
+	@Slf4j
+	class HypermediaConfigurationImportSelector implements ImportSelector {
+
+		@Override
+		public String[] selectImports(AnnotationMetadata metadata) {
+
+			Map<String, Object> attributes = metadata.getAnnotationAttributes(EnableHypermediaSupport.class.getName());
+
+			HypermediaType[] types = (HypermediaType[]) attributes.get("type");
+
+			/**
+			 * If no types are defined inside the annotation, add them all.
+			 */
+			if (types.length == 0) {
+				types = HypermediaType.values();
+			}
+
+			log.debug("Registering support for hypermedia types {} according to configuration on {}",
+				types, metadata.getClassName());
+
+			List<String> configurationNames = new ArrayList<String>();
+
+			for (HypermediaType type : types) {
+				for (Class<?> configuration : type.configurations) {
+					configurationNames.add(configuration.getName());
+				}
+			}
+
+			return configurationNames.toArray(new String[0]);
+		}
 	}
 }