Add support for checking if an argument was omitted

Closes gh-518

Author: rstoyanchev

spring-graphql-docs/src/docs/asciidoc/index.adoc

@@ -1272,14 +1272,19 @@ Schema mapping handler methods can have any of the following method arguments:
 | For access to a named field argument bound to a higher-level, typed Object.
 See <<controllers-schema-mapping-argument>>.
 
-| `@Arguments`
-| For access to all field arguments bound to a higher-level, typed Object.
-See <<controllers-schema-mapping-arguments>>.
-
 | `@Argument Map<String, Object>`
 | For access to the raw map of arguments, where `@Argument` does not have a
 `name` attribute.
 
+| `ArgumentValue`
+| For access to a named field argument bound to a higher-level, typed Object along
+with a flag to indicate if the input argument was omitted vs set to `null`.
+See <<controllers-schema-mapping-argument-value>>.
+
+| `@Arguments`
+| For access to all field arguments bound to a higher-level, typed Object.
+See <<controllers-schema-mapping-arguments>>.
+
 | `@Arguments Map<String, Object>`
 | For access to the raw map of arguments.
 
@@ -1330,7 +1335,6 @@ Schema mapping handler methods can return:
   For this to work, `AnnotatedControllerConfigurer` must be configured with an `Executor`.
 
 
-
 [[controllers-schema-mapping-argument]]
 ==== `@Argument`
 
@@ -1377,6 +1381,43 @@ You can use `@Argument` with a `Map<String, Object>` argument, to obtain the raw
 all argument values. The name attribute on `@Argument` must not be set.
 
 
+[[controllers-schema-mapping-argument-value]]
+==== `ArgumentValue`
+
+By default, input arguments in GraphQL are nullable and optional, which means an argument
+can be set to the `null` literal, or not provided at all. This distinction is useful for
+partial updates with a mutation where the underlying data may also be, either set to
+`null` or not changed at all accordingly. When using <<controllers-schema-mapping-argument>>
+there is no way to make such a distinction, because you would get `null` or an empty
+`Optional` in both cases.
+
+If you want to know not whether a value was not provided at all, you can declare an
+`ArgumentValue` method parameter, which is a simple container for the resulting value,
+along with a flag to indicate whether the input argument was omitted altogether. You
+can use this instead of `@Argument`, in which case the argument name is determined from
+the method parameter name, or together with `@Argument` to specify the argument name.
+
+For example:
+
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+	@Controller
+	public class BookController {
+
+		@MutationMapping
+		public void addBook(ArgumentValue<BookInput> bookInput) {
+			if (!bookInput.isOmitted) {
+				BookInput value = bookInput.value();
+				// ...
+			}
+		}
+	}
+----
+
+`ArgumentValue` is also supported as a field within the object structure of an `@Argument`
+method parameter, either initialized via a constructor argument or via a setter, including
+as a field of an object nested at any level below the top level object.
+
 
 [[controllers-schema-mapping-arguments]]
 ==== `@Arguments`

spring-graphql/src/main/java/org/springframework/graphql/data/ArgumentValue.java

@@ -0,0 +1,132 @@
+/*
+ * Copyright 2002-2022 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
+ *
+ *      https://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.graphql.data;
+
+
+import java.util.Optional;
+
+import org.springframework.lang.Nullable;
+import org.springframework.util.ObjectUtils;
+
+/**
+ * Simple container for the value from binding a GraphQL argument to a higher
+ * level Object, along with a flag to indicate whether the input argument was
+ * omitted altogether, as opposed to provided but set to the {@literal "null"}
+ * literal.
+ *
+ * <p>Supported in one of the following places:
+ * <ul>
+ * <li>On a controller method parameter, either instead of
+ * {@link org.springframework.graphql.data.method.annotation.Argument @Argument}
+ * in which case the argument name is determined from the method parameter name,
+ * or together with {@code @Argument} to specify the argument name.
+ * <li>As a field within the object structure of an {@code @Argument} method
+ * parameter, either initialized via a constructor argument or a setter,
+ * including as a field of an object nested at any level below the top level
+ * object.
+ * </ul>
+ *
+ * @author Rossen Stoyanchev
+ * @param <T> the type of value contained
+ * @since 1.1
+ * @see <a href="http://spec.graphql.org/October2021/#sec-Non-Null.Nullable-vs-Optional">Nullable vs Optional</a>
+ */
+public final class ArgumentValue<T> {
+
+	private static final ArgumentValue<?> OMITTED = new ArgumentValue<>(null, false);
+
+
+	@Nullable
+	private final T value;
+
+	private final boolean omitted;
+
+
+	private ArgumentValue(@Nullable T value, boolean omitted) {
+		this.value = value;
+		this.omitted = omitted;
+	}
+
+
+	/**
+	 * Return {@code true} if a non-null value is present, and {@code false} otherwise.
+	 */
+	public boolean isPresent() {
+		return (this.value != null);
+	}
+
+	/**
+	 * Return {@code true} if the input value was omitted altogether from the
+	 * input, and {@code false} if it was provided, but possibly set to the
+	 * {@literal "null"} literal.
+	 */
+	public boolean isOmitted() {
+		return this.omitted;
+	}
+
+	/**
+	 * Return the contained value, or {@code null}.
+	 */
+	@Nullable
+	public T value() {
+		return this.value;
+	}
+
+	/**
+	 * Return the contained value as a nullable {@link Optional}.
+	 */
+	public Optional<T> asOptional() {
+		return Optional.ofNullable(this.value);
+	}
+
+	@Override
+	public boolean equals(Object other) {
+		// This covers OMITTED constant
+		if (this == other) {
+			return true;
+		}
+		if (!(other instanceof ArgumentValue<?> otherValue)) {
+			return false;
+		}
+		return ObjectUtils.nullSafeEquals(this.value, otherValue.value);
+	}
+
+	@Override
+	public int hashCode() {
+		int result = ObjectUtils.nullSafeHashCode(this.value);
+		result = 31 * result + Boolean.hashCode(this.omitted);
+		return result;
+	}
+
+
+	/**
+	 * Static factory method for an argument value that was provided, even if
+	 * it was set to {@literal "null}.
+	 * @param value the value to hold in the instance
+	 */
+	public static <T> ArgumentValue<T> ofNullable(@Nullable T value) {
+		return new ArgumentValue<>(value, false);
+	}
+
+	/**
+	 * Static factory method for an argument value that was omitted.
+	 */
+	@SuppressWarnings("unchecked")
+	public static <T> ArgumentValue<T> omitted() {
+		return (ArgumentValue<T>) OMITTED;
+	}
+
+}

spring-graphql/src/main/java/org/springframework/graphql/data/GraphQlArgumentBinder.java

@@ -121,12 +121,13 @@ public Object bind(
 			DataFetchingEnvironment environment, @Nullable String name, ResolvableType targetType)
 			throws BindException {
 
-		Object rawValue = (name != null ?
-				environment.getArgument(name) : environment.getArguments());
+		Object rawValue = (name != null ? environment.getArgument(name) : environment.getArguments());
+		boolean isOmitted = (name != null && !environment.getArguments().containsKey(name));
 
 		ArgumentsBindingResult bindingResult = new ArgumentsBindingResult(targetType);
 
-		Object value = bindRawValue("$", rawValue, targetType, targetType.resolve(Object.class), bindingResult);
+		Object value = bindRawValue(
+				"$", rawValue, isOmitted, targetType, targetType.resolve(Object.class), bindingResult);
 
 		if (bindingResult.hasErrors()) {
 			throw new BindException(bindingResult);
@@ -142,6 +143,8 @@ public Object bind(
 	 * {@code "$"} if binding the top level Object; possibly indexed if binding
 	 * to a Collection element or to a Map value.
 	 * @param rawValue the raw argument value (Collection, Map, or scalar)
+	 * @param isOmitted whether the value with the given name was not provided
+	 * at all, as opposed to provided but set to the {@literal "null"} literal
 	 * @param targetType the type of Object to create
 	 * @param targetClass the resolved class from the targetType
 	 * @param bindingResult for keeping track of the nested path and errors
@@ -153,12 +156,13 @@ public Object bind(
 	@SuppressWarnings({"ConstantConditions", "unchecked"})
 	@Nullable
 	private Object bindRawValue(
-			String name, @Nullable Object rawValue, ResolvableType targetType, Class<?> targetClass,
-			ArgumentsBindingResult bindingResult) {
+			String name, @Nullable Object rawValue, boolean isOmitted,
+			ResolvableType targetType, Class<?> targetClass, ArgumentsBindingResult bindingResult) {
 
 		boolean isOptional = (targetClass == Optional.class);
+		boolean isArgumentValue = (targetClass == ArgumentValue.class);
 
-		if (isOptional) {
+		if (isOptional || isArgumentValue) {
 			targetType = targetType.getNested(2);
 			targetClass = targetType.resolve();
 		}
@@ -178,7 +182,14 @@ else if (rawValue instanceof Map) {
 					rawValue : convertValue(name, rawValue, targetClass, bindingResult));
 		}
 
-		return (isOptional ? Optional.ofNullable(value) : value);
+		if (isOptional) {
+			value = Optional.ofNullable(value);
+		}
+		else if (isArgumentValue) {
+			value = (isOmitted ? ArgumentValue.omitted() : ArgumentValue.ofNullable(value));
+		}
+
+		return value;
 	}
 
 	private Collection<?> bindCollection(
@@ -198,7 +209,7 @@ private Collection<?> bindCollection(
 		int index = 0;
 		for (Object rawValue : rawCollection) {
 			String indexedName = name + "[" + index++ + "]";
-			collection.add(bindRawValue(indexedName, rawValue, elementType, elementClass, bindingResult));
+			collection.add(bindRawValue(indexedName, rawValue, false, elementType, elementClass, bindingResult));
 		}
 
 		return collection;
@@ -242,7 +253,7 @@ private Map<?, Object> bindMapToMap(
 		for (Map.Entry<String, Object> entry : rawMap.entrySet()) {
 			String key = entry.getKey();
 			String indexedName = name + "[" + key + "]";
-			map.put(key, bindRawValue(indexedName, entry.getValue(), valueType, valueClass, bindingResult));
+			map.put(key, bindRawValue(indexedName, entry.getValue(), false, valueType, valueClass, bindingResult));
 		}
 
 		return map;
@@ -258,8 +269,9 @@ private Object bindMapToObjectViaConstructor(
 
 		for (int i = 0; i < paramNames.length; i++) {
 			String name = paramNames[i];
+			boolean isOmitted = !rawMap.containsKey(name);
 			ResolvableType paramType = ResolvableType.forConstructorParameter(constructor, i);
-			args[i] = bindRawValue(name, rawMap.get(name), paramType, paramTypes[i], bindingResult);
+			args[i] = bindRawValue(name, rawMap.get(name), isOmitted, paramType, paramTypes[i], bindingResult);
 		}
 
 		try {
@@ -288,7 +300,7 @@ private Object bindMapToObjectViaSetters(
 				continue;
 			}
 			Object value = bindRawValue(
-					key, entry.getValue(), type.getResolvableType(), type.getType(), bindingResult);
+					key, entry.getValue(), false, type.getResolvableType(), type.getType(), bindingResult);
 			try {
 				if (value != null) {
 					beanWrapper.setPropertyValue(key, value);
@@ -313,7 +325,7 @@ private <T> T convertValue(
 		Object value = null;
 		try {
 			TypeConverter converter = (this.typeConverter != null ? this.typeConverter : new SimpleTypeConverter());
-			value = converter.convertIfNecessary(rawValue, (Class<?>) type, TypeDescriptor.valueOf(type));
+			value = converter.convertIfNecessary(rawValue, (Class<?>) type);
 		}
 		catch (TypeMismatchException ex) {
 			bindingResult.pushNestedPath(name);

spring-graphql/src/main/java/org/springframework/graphql/data/method/annotation/support/ArgumentMethodArgumentResolver.java

@@ -19,21 +19,35 @@
 
 import org.springframework.core.MethodParameter;
 import org.springframework.core.ResolvableType;
+import org.springframework.graphql.data.ArgumentValue;
 import org.springframework.graphql.data.GraphQlArgumentBinder;
 import org.springframework.graphql.data.method.HandlerMethodArgumentResolver;
 import org.springframework.graphql.data.method.annotation.Argument;
 import org.springframework.util.Assert;
 import org.springframework.util.StringUtils;
 
 /**
- * Resolver for {@link Argument @Argument} annotated method parameters, obtained
- * via {@link DataFetchingEnvironment#getArgument(String)} and converted to the
- * declared type of the method parameter.
+ * Resolver for a method parameter that is annotated with
+ * {@link Argument @Argument}. The specified raw argument value is obtained via
+ * {@link DataFetchingEnvironment#getArgument(String)} and bound to a higher
+ * level object, via {@link GraphQlArgumentBinder}, to match the target method
+ * parameter type.
+ *
+ * <p>This resolver also supports wrapping the target object with
+ * {@link ArgumentValue} if the application wants to differentiate between an
+ * input argument that was set to {@code null} vs not provided at all. When
+ * this wrapper type is used, the annotation is optional, and the name of the
+ * argument is derived from the method parameter name.
+ *
+ * <p>An {@link ArgumentValue} can also be nested within the object structure
+ * of an {@link Argument @Argument}-annotated method parameter.
  *
  * @author Rossen Stoyanchev
  * @author Brian Clozel
  * @since 1.0.0
- * @see Argument
+ * @see org.springframework.graphql.data.method.annotation.Argument
+ * @see org.springframework.graphql.data.method.annotation.Arguments
+ * @see org.springframework.graphql.data.GraphQlArgumentBinder
  */
 public class ArgumentMethodArgumentResolver implements HandlerMethodArgumentResolver {
 
@@ -48,7 +62,8 @@ public ArgumentMethodArgumentResolver(GraphQlArgumentBinder argumentBinder) {
 
 	@Override
 	public boolean supportsParameter(MethodParameter parameter) {
-		return (parameter.getParameterAnnotation(Argument.class) != null);
+		return (parameter.getParameterAnnotation(Argument.class) != null ||
+				parameter.getParameterType() == ArgumentValue.class);
 	}
 
 	@Override
@@ -59,15 +74,21 @@ public Object resolveArgument(MethodParameter parameter, DataFetchingEnvironment
 	}
 
 	static String getArgumentName(MethodParameter parameter) {
-		Argument annotation = parameter.getParameterAnnotation(Argument.class);
-		Assert.state(annotation != null, "Expected @Argument annotation");
-		if (StringUtils.hasText(annotation.name())) {
-			return annotation.name();
+		Argument argument = parameter.getParameterAnnotation(Argument.class);
+		if (argument != null) {
+			if (StringUtils.hasText(argument.name())) {
+				return argument.name();
+			}
+		}
+		else if (parameter.getParameterType() != ArgumentValue.class) {
+			throw new IllegalStateException("Expected @Argument annotation");
 		}
+
 		String parameterName = parameter.getParameterName();
 		if (parameterName != null) {
 			return parameterName;
 		}
+
 		throw new IllegalArgumentException(
 				"Name for argument of type [" + parameter.getNestedParameterType().getName() +
 						"] not specified, and parameter name information not found in class file either.");