#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/java/org/springframework/hateoas/Affordance.java

@@ -0,0 +1,38 @@
+/*
+ * 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.Map;
+
+/**
+ * Abstract representation of an action a link is able to take. Web frameworks must provide concrete implementation.
+ *
+ * Affordances must include: an HTTP verb, a method name, required?, and a listing of possible properties and their types.
+ *
+ * @author Greg Turnquist
+ */
+public interface Affordance {
+
+	String getVerb();
+
+	String getMethodName();
+
+	boolean isRequired();
+
+	Map<String, Class<?>> getProperties();
+
+	String getUri();
+}

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

@@ -23,6 +23,7 @@
 import lombok.experimental.Wither;
 
 import java.io.Serializable;
+import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
@@ -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,31 @@ public Link withSelfRel() {
 		return withRel(Link.REL_SELF);
 	}
 
+	/**
+	 * Creates 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.href, this.rel, newAffordances);
+	}
+
+	public Link withAffordances(List<Affordance> affordances) {
+
+		List<Affordance> newAffordances = new ArrayList<Affordance>();
+		newAffordances.addAll(this.affordances);
+		newAffordances.addAll(affordances);
+
+		return new Link(this.href, this.rel, newAffordances);
+	}
+
+
 	/**
 	 * Returns the variable names contained in the template.
 	 * 

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

@@ -34,4 +34,12 @@ 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 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
@@ -43,7 +52,8 @@
 @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 +68,54 @@
 	 * 
 	 * @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(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]);
+		}
 	}
 }

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

@@ -55,6 +55,8 @@
 import org.springframework.hateoas.hal.CurieProvider;
 import org.springframework.hateoas.hal.HalLinkDiscoverer;
 import org.springframework.hateoas.hal.Jackson2HalModule;
+import org.springframework.hateoas.hal.forms.HalFormsLinkDiscoverer;
+import org.springframework.hateoas.hal.forms.Jackson2HalFormsModule;
 import org.springframework.hateoas.mvc.TypeConstrainedMappingJackson2HttpMessageConverter;
 import org.springframework.http.converter.HttpMessageConverter;
 import org.springframework.http.converter.json.Jackson2ObjectMapperFactoryBean;
@@ -81,6 +83,7 @@ class HypermediaSupportBeanDefinitionRegistrar implements ImportBeanDefinitionRe
 	private static final String DELEGATING_REL_PROVIDER_BEAN_NAME = "_relProvider";
 	private static final String LINK_DISCOVERER_REGISTRY_BEAN_NAME = "_linkDiscovererRegistry";
 	private static final String HAL_OBJECT_MAPPER_BEAN_NAME = "_halObjectMapper";
+	private static final String HAL_FORMS_OBJECT_MAPPER_BEAN_NAME = "_halFormsObjectMapper";
 	private static final String MESSAGE_SOURCE_BEAN_NAME = "linkRelationMessageSource";
 
 	private static final boolean JACKSON2_PRESENT = ClassUtils.isPresent("com.fasterxml.jackson.databind.ObjectMapper",
@@ -113,18 +116,11 @@ public void registerBeanDefinitions(AnnotationMetadata metadata, BeanDefinitionR
 		}
 
 		if (types.contains(HypermediaType.HAL)) {
+			registerHypermediaComponents(metadata, registry, HAL_OBJECT_MAPPER_BEAN_NAME);
+		}
 
-			if (JACKSON2_PRESENT) {
-
-				BeanDefinitionBuilder halQueryMapperBuilder = rootBeanDefinition(ObjectMapper.class);
-				registerSourcedBeanDefinition(halQueryMapperBuilder, metadata, registry, HAL_OBJECT_MAPPER_BEAN_NAME);
-
-				BeanDefinitionBuilder customizerBeanDefinition = rootBeanDefinition(DefaultObjectMapperCustomizer.class);
-				registerSourcedBeanDefinition(customizerBeanDefinition, metadata, registry);
-
-				BeanDefinitionBuilder builder = rootBeanDefinition(Jackson2ModuleRegisteringBeanPostProcessor.class);
-				registerSourcedBeanDefinition(builder, metadata, registry);
-			}
+		if (types.contains(HypermediaType.HAL_FORMS)) {
+			registerHypermediaComponents(metadata, registry, HAL_FORMS_OBJECT_MAPPER_BEAN_NAME);
 		}
 
 		if (!types.isEmpty()) {
@@ -143,6 +139,21 @@ public void registerBeanDefinitions(AnnotationMetadata metadata, BeanDefinitionR
 		registerRelProviderPluginRegistryAndDelegate(registry);
 	}
 
+	private static void registerHypermediaComponents(AnnotationMetadata metadata, BeanDefinitionRegistry registry, String objectMapperBeanName) {
+
+		if (JACKSON2_PRESENT) {
+
+			BeanDefinitionBuilder queryMapperBuilder = rootBeanDefinition(ObjectMapper.class);
+			registerSourcedBeanDefinition(queryMapperBuilder, metadata, registry, objectMapperBeanName);
+
+			BeanDefinitionBuilder customizerBeanDefinition = rootBeanDefinition(DefaultObjectMapperCustomizer.class);
+			registerSourcedBeanDefinition(customizerBeanDefinition, metadata, registry);
+
+			BeanDefinitionBuilder builder = rootBeanDefinition(Jackson2ModuleRegisteringBeanPostProcessor.class);
+			registerSourcedBeanDefinition(builder, metadata, registry);
+		}
+	}
+
 	/**
 	 * Registers bean definitions for a {@link PluginRegistry} to capture {@link RelProvider} instances. Wraps the
 	 * registry into a {@link DelegatingRelProvider} bean definition backed by the registry.
@@ -188,6 +199,9 @@ private AbstractBeanDefinition getLinkDiscovererBeanDefinition(HypermediaType ty
 			case HAL:
 				definition = new RootBeanDefinition(HalLinkDiscoverer.class);
 				break;
+			case HAL_FORMS:
+				definition = new RootBeanDefinition(HalFormsLinkDiscoverer.class);
+				break;
 			default:
 				throw new IllegalStateException(String.format("Unsupported hypermedia type %s!", type));
 		}
@@ -283,22 +297,45 @@ private List<HttpMessageConverter<?>> potentiallyRegisterModule(List<HttpMessage
 
 			CurieProvider curieProvider = getCurieProvider(beanFactory);
 			RelProvider relProvider = beanFactory.getBean(DELEGATING_REL_PROVIDER_BEAN_NAME, RelProvider.class);
-			ObjectMapper halObjectMapper = beanFactory.getBean(HAL_OBJECT_MAPPER_BEAN_NAME, ObjectMapper.class);
-			MessageSourceAccessor linkRelationMessageSource = beanFactory.getBean(MESSAGE_SOURCE_BEAN_NAME,
+
+			List<HttpMessageConverter<?>> result = new ArrayList<HttpMessageConverter<?>>(converters.size());
+
+			if (beanFactory.containsBean(HAL_OBJECT_MAPPER_BEAN_NAME)) {
+
+				ObjectMapper halObjectMapper = beanFactory.getBean(HAL_OBJECT_MAPPER_BEAN_NAME, ObjectMapper.class);
+				MessageSourceAccessor linkRelationMessageSource = beanFactory.getBean(MESSAGE_SOURCE_BEAN_NAME,
 					MessageSourceAccessor.class);
 
-			halObjectMapper.registerModule(new Jackson2HalModule());
-			halObjectMapper.setHandlerInstantiator(new Jackson2HalModule.HalHandlerInstantiator(relProvider, curieProvider,
+				halObjectMapper.registerModule(new Jackson2HalModule());
+				halObjectMapper.setHandlerInstantiator(new Jackson2HalModule.HalHandlerInstantiator(relProvider, curieProvider,
 					linkRelationMessageSource, beanFactory));
 
-			MappingJackson2HttpMessageConverter halConverter = new TypeConstrainedMappingJackson2HttpMessageConverter(
+				MappingJackson2HttpMessageConverter halConverter = new TypeConstrainedMappingJackson2HttpMessageConverter(
 					ResourceSupport.class);
-			halConverter.setSupportedMediaTypes(Arrays.asList(HAL_JSON));
-			halConverter.setObjectMapper(halObjectMapper);
+				halConverter.setSupportedMediaTypes(Arrays.asList(HAL_JSON));
+				halConverter.setObjectMapper(halObjectMapper);
+				result.add(halConverter);
+			}
+
+			if (beanFactory.containsBean(HAL_FORMS_OBJECT_MAPPER_BEAN_NAME)) {
+
+				ObjectMapper halFormsObjectMapper = beanFactory.getBean(HAL_FORMS_OBJECT_MAPPER_BEAN_NAME, ObjectMapper.class);
+				MessageSourceAccessor linkRelationMessageSource = beanFactory.getBean(MESSAGE_SOURCE_BEAN_NAME,
+					MessageSourceAccessor.class);
+
+				halFormsObjectMapper.registerModule(new Jackson2HalFormsModule());
+				halFormsObjectMapper.setHandlerInstantiator(new Jackson2HalFormsModule.HalFormsHandlerInstantiator(relProvider, curieProvider,
+					linkRelationMessageSource, true));
+
+				MappingJackson2HttpMessageConverter halFormsConverter = new TypeConstrainedMappingJackson2HttpMessageConverter(
+					ResourceSupport.class);
+				halFormsConverter.setSupportedMediaTypes(Arrays.asList(HAL_FORMS_JSON));
+				halFormsConverter.setObjectMapper(halFormsObjectMapper);
+				result.add(halFormsConverter);
+			}
 
-			List<HttpMessageConverter<?>> result = new ArrayList<HttpMessageConverter<?>>(converters.size());
-			result.add(halConverter);
 			result.addAll(converters);
+
 			return result;
 		}
 
@@ -327,14 +364,13 @@ private static class DefaultObjectMapperCustomizer implements BeanPostProcessor
 		@Override
 		public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
 
-			if (!HAL_OBJECT_MAPPER_BEAN_NAME.equals(beanName)) {
-				return bean;
+			if (HAL_OBJECT_MAPPER_BEAN_NAME.equals(beanName) || HAL_FORMS_OBJECT_MAPPER_BEAN_NAME.equals(beanName)) {
+				ObjectMapper mapper = (ObjectMapper) bean;
+				mapper.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
+				return mapper;
 			}
 
-			ObjectMapper mapper = (ObjectMapper) bean;
-			mapper.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
-
-			return mapper;
+			return bean;
 		}
 
 		/*