Rename ArgumentValue to FieldValue

Prior to this commit, `ArgumentValue<T>` would mainly focus on the
server-side support with the binding of arguments on Controller methods.

With the introduction of this feature on the client in gh-1174, this
commit reconsiders both the `ArgumentValue<T>` name and its package
location to reflect the broader support.

This commit deprecates `ArgumentValue<T>` in favor of `FieldValue<T>`
with similar support.

Closes gh-1187

Author: bclozel

spring-graphql-docs/modules/ROOT/pages/controllers.adoc

@@ -143,11 +143,11 @@ See xref:controllers.adoc#controllers.schema-mapping.argument[`@Argument`].
 
 See xref:controllers.adoc#controllers.schema-mapping.argument[`@Argument`].
 
-| `ArgumentValue`
+| `FieldValue`
 | 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 xref:controllers.adoc#controllers.schema-mapping.argument-value[`ArgumentValue`].
+See xref:controllers.adoc#controllers.schema-mapping.field-value[`FieldValue`].
 
 | `@Arguments`
 | For access to all field arguments bound to a higher-level, typed Object.
@@ -403,8 +403,8 @@ specified in the annotation, or to the parameter name. For access to the full ar
 map, please use xref:controllers.adoc#controllers.schema-mapping.arguments[`@Arguments`] instead.
 
 
-[[controllers.schema-mapping.argument-value]]
-=== `ArgumentValue`
+[[controllers.schema-mapping.field-value]]
+=== `FieldValue`
 
 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
@@ -414,7 +414,7 @@ there is no way to make such a distinction, because you would get `null` or an e
 `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,
+`FieldValue` 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.
@@ -427,7 +427,7 @@ For example:
 	public class BookController {
 
 		@MutationMapping
-		public void addBook(ArgumentValue<BookInput> bookInput) {
+		public void addBook(FieldValue<BookInput> bookInput) {
 			if (!bookInput.isOmitted()) {
 				BookInput value = bookInput.value();
 				// ...
@@ -436,7 +436,7 @@ For example:
 	}
 ----
 
-`ArgumentValue` is also supported as a field within the object structure of an `@Argument`
+`FieldValue` 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.
 

spring-graphql/src/main/java/org/springframework/graphql/FieldValue.java

@@ -0,0 +1,172 @@
+/*
+ * Copyright 2020-2025 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;
+
+
+import java.util.Optional;
+import java.util.function.Consumer;
+
+import org.springframework.lang.Nullable;
+import org.springframework.util.Assert;
+import org.springframework.util.ObjectUtils;
+
+/**
+ * Simple container for GraphQL field values that indicates if the field
+ * value is present, provided but set to {@literal "null"} or omitted altogether.
+ *
+ * <p>In the case of GraphQL mutations, clients send an Input Object with several fields;
+ * the server must understand the difference between a field being absent
+ * (the existing value should be left as-is) and a field set to {@literal "null"}
+ * (the existing value must be set to {@literal "null"}). {@code FieldValue<T>}
+ * helps to make this distinction.
+ *
+ * <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>
+ *
+ * @param <T> the type of value contained
+ * @author Rossen Stoyanchev
+ * @author Brian Clozel
+ * @since 1.4.0
+ * @see <a href="http://spec.graphql.org/October2021/#sec-Input-Objects">Input Object</a>
+ * @see <a href="http://spec.graphql.org/October2021/#sec-Non-Null.Nullable-vs-Optional">Nullable vs Optional</a>
+ */
+public final class FieldValue<T> {
+
+	private static final FieldValue<?> EMPTY = new FieldValue<>(null, false);
+
+	private static final FieldValue<?> OMITTED = new FieldValue<>(null, true);
+
+
+	@Nullable
+	private final T value;
+
+	private final boolean omitted;
+
+
+	private FieldValue(@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 present in the input but the value was {@code null},
+	 * and {@code false} otherwise.
+	 */
+	public boolean isEmpty() {
+		return !this.omitted && 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);
+	}
+
+	/**
+	 * If a value is present, performs the given action with the value, otherwise does nothing.
+	 * @param action the action to be performed, if a value is present
+	 */
+	public void ifPresent(Consumer<? super T> action) {
+		Assert.notNull(action, "Action is required");
+		if (this.value != null) {
+			action.accept(this.value);
+		}
+	}
+
+	@Override
+	public boolean equals(Object other) {
+		// This covers EMPTY and OMITTED constant
+		if (this == other) {
+			return true;
+		}
+		if (!(other instanceof FieldValue<?> 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;
+	}
+
+	@Override
+	public String toString() {
+		if (this.isOmitted()) {
+			return "FieldValue{omitted}";
+		}
+		return "FieldValue{value=" + this.value + "'}'";
+	}
+
+	/**
+	 * Static factory method for an argument value that was provided, even if
+	 * it was set to {@literal "null}.
+	 * @param <T> the type of value
+	 * @param value the value to hold in the instance
+	 */
+	@SuppressWarnings("unchecked")
+	public static <T> FieldValue<T> ofNullable(@Nullable T value) {
+		return (value != null) ? new FieldValue<>(value, false) : (FieldValue<T>) EMPTY;
+	}
+
+	/**
+	 * Static factory method for an argument value that was omitted.
+	 * @param <T> the type of value
+	 */
+	@SuppressWarnings("unchecked")
+	public static <T> FieldValue<T> omitted() {
+		return (FieldValue<T>) OMITTED;
+	}
+
+}

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

@@ -18,10 +18,8 @@
 
 
 import java.util.Optional;
-import java.util.function.Consumer;
 
 import org.springframework.lang.Nullable;
-import org.springframework.util.Assert;
 import org.springframework.util.ObjectUtils;
 
 /**
@@ -46,7 +44,9 @@
  * @author Rossen Stoyanchev
  * @since 1.1.0
  * @see <a href="http://spec.graphql.org/October2021/#sec-Non-Null.Nullable-vs-Optional">Nullable vs Optional</a>
+ * @deprecated since 1.4.0 in favor of {@link org.springframework.graphql.FieldValue}.
  */
+@Deprecated(since = "1.4.0", forRemoval = true)
 public final class ArgumentValue<T> {
 
 	private static final ArgumentValue<?> EMPTY = new ArgumentValue<>(null, false);
@@ -73,15 +73,6 @@ public boolean isPresent() {
 		return (this.value != null);
 	}
 
-	/**
-	 * Return {@code true} if the input value was present in the input but the value was {@code null},
-	 * and {@code false} otherwise.
-	 * @since 1.4.0
-	 */
-	public boolean isEmpty() {
-		return !this.omitted && 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
@@ -106,18 +97,6 @@ public Optional<T> asOptional() {
 		return Optional.ofNullable(this.value);
 	}
 
-	/**
-	 * If a value is present, performs the given action with the value, otherwise does nothing.
-	 * @param action the action to be performed, if a value is present
-	 * @since 1.4.0
-	 */
-	public void ifPresent(Consumer<? super T> action) {
-		Assert.notNull(action, "Action is required");
-		if (this.value != null) {
-			action.accept(this.value);
-		}
-	}
-
 	@Override
 	public boolean equals(Object other) {
 		// This covers EMPTY and OMITTED constant

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

@@ -40,6 +40,7 @@
 import org.springframework.core.convert.ConversionService;
 import org.springframework.core.convert.TypeDescriptor;
 import org.springframework.data.util.DirectFieldAccessFallbackBeanWrapper;
+import org.springframework.graphql.FieldValue;
 import org.springframework.lang.Nullable;
 import org.springframework.util.ClassUtils;
 import org.springframework.util.ReflectionUtils;
@@ -67,13 +68,15 @@
  *
  * <p>The binder supports {@link Optional} as a wrapper around any Object or
  * scalar value in the target Object structure. In addition, it also supports
- * {@link ArgumentValue} as a wrapper that indicates whether a given input
- * argument was omitted rather than set to the {@literal "null"} literal.
+ * {@link org.springframework.graphql.FieldValue} as a wrapper that indicates
+ * whether a given input argument was omitted rather than set to the
+ * {@literal "null"} literal.
  *
  * @author Brian Clozel
  * @author Rossen Stoyanchev
  * @since 1.0.0
  */
+@SuppressWarnings("removal")
 public class GraphQlArgumentBinder {
 
 	@Nullable
@@ -115,7 +118,7 @@ private static SimpleTypeConverter initTypeConverter(@Nullable ConversionService
 	 * @param name the name of an argument, or {@code null} to use the full map
 	 * @param targetType the type of Object to create
 	 * @return the created Object, possibly wrapped in {@link Optional} or in
-	 * {@link ArgumentValue}, or {@code null} if there is no value
+	 * {@link org.springframework.graphql.FieldValue}, or {@code null} if there is no value
 	 * @throws BindException containing one or more accumulated errors from
 	 * matching and/or converting arguments to the target Object
 	 */
@@ -175,8 +178,9 @@ private Object bindRawValue(
 
 		boolean isOptional = (targetClass == Optional.class);
 		boolean isArgumentValue = (targetClass == ArgumentValue.class);
+		boolean isFieldValue = (targetClass == FieldValue.class);
 
-		if (isOptional || isArgumentValue) {
+		if (isOptional || isArgumentValue || isFieldValue) {
 			targetType = targetType.getNested(2);
 			targetClass = targetType.resolve();
 		}
@@ -202,6 +206,9 @@ else if (rawValue instanceof Map) {
 		else if (isArgumentValue) {
 			value = (isOmitted ? ArgumentValue.omitted() : ArgumentValue.ofNullable(value));
 		}
+		else if (isFieldValue) {
+			value = (isOmitted ? FieldValue.omitted() : FieldValue.ofNullable(value));
+		}
 
 		return value;
 	}

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

@@ -61,6 +61,7 @@
 import org.springframework.core.ResolvableType;
 import org.springframework.core.annotation.AnnotatedElementUtils;
 import org.springframework.data.domain.ScrollPosition;
+import org.springframework.graphql.FieldValue;
 import org.springframework.graphql.data.ArgumentValue;
 import org.springframework.graphql.data.GraphQlArgumentBinder;
 import org.springframework.graphql.data.method.HandlerMethod;
@@ -488,10 +489,12 @@ public ResolvableType getReturnType() {
 		}
 
 		@Override
+		@SuppressWarnings("removal")
 		public Map<String, ResolvableType> getArguments() {
 
 			Predicate<MethodParameter> argumentPredicate = (p) ->
-					(p.getParameterAnnotation(Argument.class) != null || p.getParameterType() == ArgumentValue.class);
+					(p.getParameterAnnotation(Argument.class) != null || p.getParameterType() == ArgumentValue.class ||
+							p.getParameterType() == FieldValue.class);
 
 			return Arrays.stream(this.mappingInfo.getHandlerMethod().getMethodParameters())
 					.filter(argumentPredicate)