Refine GraphQlResponseField getError()

Instead of a simple check, looking for an associated field error at or
above the field, this method now more focused on finding the reason for
a failure when the field has no value.

This allows performing a more thorough search including cases when the
field error is at, above, or even below (e.g. non-null nested field
that bubbled up), in the end falling back on request errors (e.g.
failed response without any field errors).

Also, rename ResponseField to GraphQlResponseField and move to a
top-level class.

See gh-10

Author: rstoyanchev

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

@@ -135,7 +135,7 @@ which is a strategy for loading the document for a request by file name.
 
 Once you have a <<client-graphqlclient>>, you can begin to perform requests via
 <<client-requests-retrieve, retrieve()>> or <<client-requests-execute, execute()>>
-where the former is merely a shortcut for the latter.
+where the former is only a shortcut for the latter.
 
 
 
@@ -159,50 +159,42 @@ The below retrieves and decodes the data for a query:
 			.retrieve("project") <2>
 			.toEntity(Project.class); <3>
 ----
-<1> The operation to perform
-<2> Specify a path under the "data" key in the response map
-<3> Decode the data at the path to the target type
+<1> The operation to perform.
+<2> The path under the "data" key in the response map to decode from.
+<3> Decode the data at the path to the target type.
 
-The document is a `String` that could be a literal or produced through a code generated
-request object. You can also define documents in files and use a
+The input document is a `String` that could be a literal or produced through a code
+generated request object. You can also define documents in files and use a
 <<client-requests-document-source>> to resole them by file name.
 
 The path is relative to the "data" key and uses a simple dot (".") separated notation
-for nested fields with optional array indices for list elements, e.g. `"project.name"`,
-`"project.releases[0].version"`, and so on.
+for nested fields with optional array indices for list elements, e.g. `"project.name"`
+or `"project.releases[0].version"`.
 
-Decoding can fail with `FieldAccessException` if the given path is not present in the
-response map, or when the value is `null` and there is an error for the field.
-
-By default, `FieldAccessException` is also raised on `retrieve` for partial data where
-the field value exists but nested fields may be `null` with a field error. In such
-cases, you can handle the exception to examine the errors and decide whether or how to
-decode the partial data:
+Decoding can result in `FieldAccessException` if the given path is not present, or the
+field value is `null` and has an error. `FieldAccessException` provides access to the
+response and the field:
 
 [source,java,indent=0,subs="verbatim,quotes"]
 ----
 	Mono<Project> projectMono = graphQlClient.document(document)
 			.retrieve("project")
 			.toEntity(Project.class)
 			.onErrorResume(FieldAccessException.class, ex -> {
-				ResponseField field = ex.getField();
-				// Use field to check nested field errors and/or decode
-				// Return Mono with Project or an error
+				ClientGraphQlResponse response = ex.getResponse();
+				// ...
+				GraphQlResponseField field = ex.getField();
+				// ...
 			});
 ----
 
-TIP: The GraphQL spec considers a partial response or a partial field to be valid, and
-it may be feasible to decode them. By contrast, a failed field (i.e. value not present or
-is `null` with field error) or a failed response (no "data" key) are not valid and
-attempts to decode those are always rejected.
-
 
 
 [[client-requests-execute]]
 === Execute
 
-The `retrieve` method is only a shortcut to decode from a single path to a higher level
-object. For more control and access to the response, use the `execute` method.
+`retrieve` is only a shortcut to decode from a single path in the response map. For more
+control, use the `execute` method and handle the response:
 
 For example:
 
@@ -212,17 +204,27 @@ For example:
 	Mono<Project> projectMono = graphQlClient.document(document)
 			.execute()
 			.map(response -> {
-				// Check response.isValid(), getErrors()
+				if (!response.isValid()) {
+					// Request failure... <1>
+				}
 
 				ResponseField field = response.field("project");
-				// Check field.hasValue(), getError()
-
-				return field.toEntity(Project.class)
+				if (!field.hasValue()) {
+					if (field.getError() != null) {
+						// Field failure... <2>
+					}
+					else {
+						// Optional field set to null... <3>
+					}
+				}
+
+				return field.toEntity(Project.class); <4>
 			});
 ----
-
-You can use `execute` to check response errors, obtain different fields, check their
-field errors and nested field errors, and/or decode their values.
+<1> The response does not have data, only errors
+<2> Field that is `null` and has an associated error
+<3> Field that was set to `null` by its `DataFetcher`
+<4> Decode the data at the given path
 
 
 
@@ -272,7 +274,7 @@ You can use the `GraphQlClient` <<client-graphqlclient-builder>> to customize th
 == Subscriptions
 
 For a subscription operation, call `retrieveSubscription` instead of `retrieve` to
-obtain a stream of responses rather than a single response:
+obtain a stream of responses, each decoded to a target object:
 
 [source,java,indent=0,subs="verbatim,quotes"]
 ----
@@ -281,29 +283,34 @@ obtain a stream of responses rather than a single response:
 			.toEntity(String.class);
 ----
 
-Similar to the <<client-requests-retrieve>> vs <<client-requests-execute>> choice
-for requests with a single response, the same choice is also available for subscriptions.
-For example, for more control over each response, use `executeSubscription` instead of
-`retrieveSubscription`:
+Similar to the <<client-requests-retrieve, retrieve>> vs <<client-requests-execute, execute>>
+alternatives for single response requests, the same is also available for subscriptions.
+For more control over each response, use `executeSubscription`:
 
 [source,java,indent=0,subs="verbatim,quotes"]
 ----
 	Flux<String> greetingFlux = client.document("subscription { greetings }")
 			.executeSubscription()
 			.map(response -> {
-				// Check response.isValid(), getErrors()
+				if (!response.isValid()) {
+					// Request failure...
+				}
 
-				ResponseField field = response.field("greeting");
-				// Check field.isValid(), getError()
+				ResponseField field = response.field("project");
+				if (!field.hasValue()) {
+					if (field.getError() != null) {
+						// Field failure...
+					}
+					else {
+						// Optional field set to null... <3>
+					}
+				}
 
 				return field.toEntity(String.class)
 			});
 ----
 
-
-
-Subscriptions are supported only with the <<client-websocketgraphqlclient,
-WebSocketGraphQlClient>> extension.
+NOTE: Subscriptions are supported only over <<client-websocketgraphqlclient, WebSocket>>.
 
 
 

spring-graphql/src/main/java/org/springframework/graphql/client/ClientGraphQlResponse.java

@@ -31,7 +31,7 @@
 public interface ClientGraphQlResponse extends GraphQlResponse {
 
 	/**
-	 * Return the request associated with this response.
+	 * Return the request for the response.
 	 */
 	GraphQlRequest getRequest();
 
@@ -48,10 +48,10 @@ public interface ClientGraphQlResponse extends GraphQlResponse {
 	 * </pre>
 	 * @param path relative to the "data" key
 	 * @return representation for the field with further options to inspect or
-	 * decode its value; use {@link ResponseField#hasValue()} to check if the
-	 * field actually exists and has a value.
+	 * decode its value; use {@link GraphQlResponseField#hasValue()} to check if
+	 * the field actually exists and has a value.
 	 */
-	ResponseField field(String path);
+	GraphQlResponseField field(String path);
 
 	/**
 	 * Decode the full response map to the given target type.

spring-graphql/src/main/java/org/springframework/graphql/client/DefaultClientGraphQlResponse.java

@@ -23,19 +23,13 @@
 import java.util.stream.Collectors;
 
 import org.springframework.core.ParameterizedTypeReference;
-import org.springframework.core.ResolvableType;
 import org.springframework.core.codec.Decoder;
 import org.springframework.core.codec.Encoder;
-import org.springframework.core.io.buffer.DataBuffer;
-import org.springframework.core.io.buffer.DataBufferFactory;
-import org.springframework.core.io.buffer.DefaultDataBufferFactory;
 import org.springframework.graphql.GraphQlRequest;
 import org.springframework.graphql.GraphQlResponse;
 import org.springframework.graphql.GraphQlResponseError;
 import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
-import org.springframework.util.MimeType;
-import org.springframework.util.MimeTypeUtils;
 import org.springframework.util.StringUtils;
 
 
@@ -70,13 +64,22 @@ public GraphQlRequest getRequest() {
 		return this.request;
 	}
 
+	Encoder<?> getEncoder() {
+		return this.encoder;
+	}
+
+	Decoder<?> getDecoder() {
+		return this.decoder;
+	}
+
+
 	@Override
-	public ResponseField field(String path) {
-		List<Object> dataPath = parseFieldPath(path);
-		return new DefaultField(path, dataPath, getFieldValue(dataPath), getFieldErrors(path));
+	public GraphQlResponseField field(String path) {
+		List<Object> parsedPath = parsePath(path);
+		return new DefaultGraphQlResponseField(this, path, parsedPath, getValue(parsedPath), getFieldErrors(path));
 	}
 
-	private static List<Object> parseFieldPath(String path) {
+	private static List<Object> parsePath(String path) {
 		if (!StringUtils.hasText(path)) {
 			return Collections.emptyList();
 		}
@@ -117,18 +120,18 @@ private static List<Object> parseFieldPath(String path) {
 	}
 
 	@Nullable
-	private Object getFieldValue(List<Object> fieldPath) {
+	private Object getValue(List<Object> path) {
 		Object value = (isValid() ? getData() : null);
-		for (Object segment : fieldPath) {
+		for (Object segment : path) {
 			if (value == null) {
 				return null;
 			}
 			if (segment instanceof String) {
-				Assert.isTrue(value instanceof Map, () -> "Invalid path " + fieldPath + ", data: " + getData());
+				Assert.isTrue(value instanceof Map, () -> "Invalid path " + path + ", data: " + getData());
 				value = ((Map<?, ?>) value).getOrDefault(segment, null);
 			}
 			else {
-				Assert.isTrue(value instanceof List, () -> "Invalid path " + fieldPath + ", data: " + getData());
+				Assert.isTrue(value instanceof List, () -> "Invalid path " + path + ", data: " + getData());
 				int index = (int) segment;
 				value = (index < ((List<?>) value).size() ? ((List<?>) value).get(index) : null);
 			}
@@ -163,102 +166,4 @@ public <D> D toEntity(ParameterizedTypeReference<D> type) {
 		return field("").toEntity(type);
 	}
 
-
-	/**
-	 * Default implementation of {@link ResponseField}.
-	 */
-	private class DefaultField implements ResponseField {
-
-		private final String path;
-
-		private final List<Object> parsedPath;
-
-		private final List<GraphQlResponseError> fieldErrors;
-
-		@Nullable
-		private final Object value;
-
-		public DefaultField(
-				String path, List<Object> parsedPath, @Nullable Object value, List<GraphQlResponseError> errors) {
-
-			this.path = path;
-			this.parsedPath = parsedPath;
-			this.value = value;
-			this.fieldErrors = errors;
-		}
-
-		@Override
-		public String getPath() {
-			return this.path;
-		}
-
-		@Override
-		public List<Object> getParsedPath() {
-			return this.parsedPath;
-		}
-
-		@Override
-		public boolean hasValue() {
-			return (this.value != null);
-		}
-
-		@SuppressWarnings("unchecked")
-		@Override
-		public <T> T getValue() {
-			return (T) this.value;
-		}
-
-		@Override
-		public GraphQlResponseError getError() {
-			for (GraphQlResponseError error : this.fieldErrors) {
-				if (error.getParsedPath().size() <= this.parsedPath.size()) {
-					return error;
-				}
-			}
-			return null;
-		}
-
-		@Override
-		public List<GraphQlResponseError> getErrors() {
-			return this.fieldErrors;
-		}
-
-		@Override
-		public <D> D toEntity(Class<D> entityType) {
-			return toEntity(ResolvableType.forType(entityType));
-		}
-
-		@Override
-		public <D> D toEntity(ParameterizedTypeReference<D> entityType) {
-			return toEntity(ResolvableType.forType(entityType));
-		}
-
-		@Override
-		public <D> List<D> toEntityList(Class<D> elementType) {
-			return toEntity(ResolvableType.forClassWithGenerics(List.class, elementType));
-		}
-
-		@Override
-		public <D> List<D> toEntityList(ParameterizedTypeReference<D> elementType) {
-			return toEntity(ResolvableType.forClassWithGenerics(List.class, ResolvableType.forType(elementType)));
-		}
-
-		@SuppressWarnings({"unchecked", "ConstantConditions"})
-		private <T> T toEntity(ResolvableType targetType) {
-			if (this.value == null) {
-				throw new FieldAccessException(request, DefaultClientGraphQlResponse.this, this);
-			}
-
-			DataBufferFactory bufferFactory = DefaultDataBufferFactory.sharedInstance;
-			MimeType mimeType = MimeTypeUtils.APPLICATION_JSON;
-			Map<String, Object> hints = Collections.emptyMap();
-
-			DataBuffer buffer = ((Encoder<T>) encoder).encodeValue(
-					(T) this.value, bufferFactory, ResolvableType.forInstance(this.value), mimeType, hints);
-
-			return ((Decoder<T>) decoder).decode(buffer, targetType, mimeType, hints);
-		}
-
-	}
-
 }