Support form creation

src/main/java/org/springframework/hateoas/forms/AbstractSuggest.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2016 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.forms;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonInclude.Include;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * @see Suggest
+ */
+@JsonInclude(Include.NON_EMPTY)
+@JsonIgnoreProperties({ "type" })
+public class AbstractSuggest implements Suggest {
+
+	private final String textField;
+
+	private final String valueField;
+
+	public AbstractSuggest(String textField, String valueField) {
+		this.textField = textField;
+		this.valueField = valueField;
+	}
+
+	@Override
+	@JsonProperty("value-field")
+	public String getValueField() {
+		return valueField;
+	}
+
+	@Override
+	@JsonProperty("prompt-field")
+	public String getTextField() {
+		return textField;
+	}
+
+}

src/main/java/org/springframework/hateoas/forms/AbstractSuggestBuilder.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2016 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.forms;
+
+/**
+ * Abstract class that helps to construct {@link Suggest}
+ * @see PropertyBuilder
+ * @see TemplateBuilder
+ */
+public abstract class AbstractSuggestBuilder implements SuggestBuilder {
+
+	String textFieldName;
+
+	String valueFieldName;
+
+	@Override
+	public AbstractSuggestBuilder textField(String textFieldName) {
+		this.textFieldName = textFieldName;
+		return this;
+	}
+
+	@Override
+	public AbstractSuggestBuilder valueField(String valueFieldName) {
+		this.valueFieldName = valueFieldName;
+		return this;
+	}
+
+	@Override
+	public abstract Suggest build();
+}

src/main/java/org/springframework/hateoas/forms/EmbeddedSuggestBuilder.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2016 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.forms;
+
+import org.springframework.hateoas.forms.ValueSuggest.ValueSuggestType;
+
+/**
+ * Builds {@link ValueSuggest} of type {@link ValueSuggestType#EMBEDDED}
+ *
+ */
+public class EmbeddedSuggestBuilder<D> extends ValueSuggestBuilder<D> {
+
+	public EmbeddedSuggestBuilder(Iterable<D> values) {
+		super(values);
+	}
+
+	@Override
+	public Suggest build() {
+		return new ValueSuggest<D>(values, textFieldName, valueFieldName, ValueSuggestType.EMBEDDED);
+	}
+}

src/main/java/org/springframework/hateoas/forms/FieldNotFoundException.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2016 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.forms;
+
+/**
+ * Exception fired by {@link FieldUtils} when a class doesn't have a field of a specified name.
+ *
+ */
+public class FieldNotFoundException extends RuntimeException {
+
+	private static final long serialVersionUID = 2591233443652872298L;
+
+	private final Class<?> targetClass;
+
+	private final String field;
+
+	public FieldNotFoundException(Class<?> targetClass, String field) {
+		this.targetClass = targetClass;
+		this.field = field;
+	}
+
+	public Class<?> getTargetClass() {
+		return targetClass;
+	}
+
+	public String getField() {
+		return field;
+	}
+
+}

src/main/java/org/springframework/hateoas/forms/FieldUtils.java

@@ -0,0 +1,112 @@
+/*
+ * Copyright 2016 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.forms;
+
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+import java.util.Collection;
+import java.util.Map;
+
+import org.springframework.core.ResolvableType;
+import org.springframework.util.ReflectionUtils;
+import org.springframework.util.StringUtils;
+
+/**
+ * Utility class for searching fields of a class
+ * 
+ */
+public class FieldUtils {
+	private static final char DOT = '.';
+
+	/**
+	 * Attempt to find the {@link Class} of the {@link Field} on the supplied class by the especified path.
+	 * 
+	 * @param type
+	 * @param path may be a nested path dot separated
+	 * @return
+	 */
+	public static Class<?> findFieldClass(Class<?> type, String path) {
+		int firstDot = path.indexOf(DOT);
+		if (firstDot!=-1) {
+			String propertyName = path.substring(0, firstDot);
+			Class<?> childType = findSimpleFieldClass(type, propertyName);
+			if (childType == null) {
+				throw new FieldNotFoundException(type, propertyName);
+			}
+			return findFieldClass(childType, path.substring(firstDot + 1, path.length()));
+		}
+		else {
+			return findSimpleFieldClass(type, path);
+		}
+	}
+
+	/**
+	 * Attempt to find a {@link Field} declared in a {@link Class}. In first instance tries to find the getter
+	 * {@link Method} of supplied fieldName. If getter is not present attempts to find for declared field.
+	 * @param type
+	 * @param fieldName
+	 * @return
+	 */
+	private static Class<?> findSimpleFieldClass(Class<?> type, String fieldName) {
+
+		Method method = ReflectionUtils.findMethod(type, "get" + StringUtils.capitalize(fieldName));
+		ResolvableType resolvableType = null;
+		if (null != method) {
+			resolvableType = ResolvableType.forMethodReturnType(method);
+		}
+		else {
+			try {
+				resolvableType = ResolvableType.forField(type.getDeclaredField(fieldName));
+			}
+			catch (SecurityException e) {
+				throw new FieldNotFoundException(type, fieldName);
+			}
+			catch (NoSuchFieldException e) {
+				throw new FieldNotFoundException(type, fieldName);
+			}
+		}
+
+		return getActualType(resolvableType);
+	}
+
+	/**
+	 * Returns the {@link Class} of supplied {@link ResolvableType} considering that:
+	 * 
+	 * <ul>
+	 * <li>- if resolvableType is an array, the component type is returned</li>
+	 * <li>- if resolvableType is a {@link Collection}, generic parameter class is returned</li>
+	 * <li>- if resolvableType is a {@link Map}, {@link NotSupportedException} is returned</li>
+	 * <li>- otherwise resolvableType raw class is returned</li>
+	 * </ul>
+	 * 
+	 * @param resolvableType
+	 * @return
+	 */
+	private static Class<?> getActualType(ResolvableType resolvableType) {
+		if (resolvableType.isArray()) {
+			return resolvableType.getComponentType().resolve();
+		}
+		else if (resolvableType.asCollection() != ResolvableType.NONE) {
+			return resolvableType.getGeneric(0).resolve();
+		}
+		else if (resolvableType.asMap() != ResolvableType.NONE) {
+			throw new NotSupportedException(resolvableType.resolve() + " is not supported");
+		}
+		else {
+			return resolvableType.resolve();
+		}
+	}
+}

src/main/java/org/springframework/hateoas/forms/Form.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2016 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.forms;
+
+import org.springframework.web.bind.annotation.RequestBody;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonInclude.Include;
+
+/**
+ * HAL-FORMS {@link Template} that contains the argument marked as {@link RequestBody}
+ */
+@JsonIgnoreProperties({ "body", "href", "rel" })
+@JsonInclude(Include.NON_EMPTY)
+public class Form extends Template {
+
+	private static final long serialVersionUID = -933494757445089955L;
+
+	private Object body;
+
+	public Form() {
+	}
+
+	public Form(String href, String rel) {
+		super(href, rel);
+	}
+
+	public void setBody(Object body) {
+		this.body = body;
+	}
+
+	public Object getBody() {
+		return body;
+	}
+}

src/main/java/org/springframework/hateoas/forms/FormBuilderFactory.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2016 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.forms;
+
+import java.lang.reflect.Method;
+
+import org.springframework.hateoas.core.DummyInvocationUtils;
+import org.springframework.hateoas.mvc.ControllerFormBuilder;
+
+public interface FormBuilderFactory<T extends TemplateBuilder> {
+	/**
+	 * Returns a {@link ControllerFormBuilder} pointing to the URI mapped to the given {@link Method} and expanding this
+	 * mapping using the given parameters.
+	 * 
+	 * @param method must not be {@literal null}.
+	 * @param parameters
+	 * @return
+	 */
+	T formTo(Method method, Object... parameters);
+
+	/**
+	 * Returns a {@link ControllerFormBuilder} pointing to the URI mapped to the given {@link Method} assuming it was
+	 * invoked on an object of the given type.
+	 * 
+	 * @param type must not be {@literal null}.
+	 * @param method must not be {@literal null}.
+	 * @param parameters
+	 * @return
+	 */
+	T formTo(Class<?> type, Method method, Object... parameters);
+
+	/**
+	 * Returns a {@link ControllerFormBuilder} pointing to the URI mapped to the method the result is handed into this
+	 * method. Use {@link DummyInvocationUtils#methodOn(Class, Object...)} to obtain a dummy instance of a controller to
+	 * record a dummy method invocation on. See {@link HalFormsLinkBuilder#linkTo(Object)} for an example.
+	 * 
+	 * @see ControllerLinkBuilder#linkTo(Object)
+	 * @param methodInvocationResult must not be {@literal null}.
+	 * @return
+	 */
+	T formTo(Object methodInvocationResult);
+}