Polishing

See gh-3

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

@@ -54,14 +54,21 @@ public class RequestInput {
 	private final List<BiFunction<ExecutionInput, ExecutionInput.Builder, ExecutionInput>> executionInputConfigurers = new ArrayList<>();
 
 
+	/**
+	 * Create an instance.
+	 * @param query the query, mutation, or subscription for the request
+	 * @param operationName an optional, explicit name assigned to the query
+	 * @param  variables variables by which the query is parameterized
+	 * @param locale the locale associated with the request, if any
+	 */
 	public RequestInput(
-			String query, @Nullable String operationName, @Nullable Map<String, Object> vars,
+			String query, @Nullable String operationName, @Nullable Map<String, Object> variables,
 			@Nullable Locale locale) {
 
 		Assert.notNull(query, "'query' is required");
 		this.query = query;
 		this.operationName = operationName;
-		this.variables = ((vars != null) ? vars : Collections.emptyMap());
+		this.variables = ((variables != null) ? variables : Collections.emptyMap());
 		this.locale = locale;
 	}
 
@@ -72,18 +79,16 @@ public class RequestInput {
 	}
 
 	/**
-	 * Return the query name extracted from the request. This is guaranteed to
-	 * be a non-empty string.
-	 * @return the query name
+	 * Return the query, mutation, or subscription for the request.
+	 * @return the query, a non-empty string.
 	 */
 	public String getQuery() {
 		return this.query;
 	}
 
 	/**
-	 * Return the operation name extracted from the request or {@code null} if
-	 * not provided.
-	 * @return the operation name or {@code null}
+	 * Return the explicitly assigned name for the query.
+	 * @return the operation name or {@code null}.
 	 */
 	@Nullable
 	public String getOperationName() {
@@ -91,17 +96,16 @@ public class RequestInput {
 	}
 
 	/**
-	 * Return the variables that can be referenced via $syntax extracted from
-	 * the request body or a {@code null} if not provided.
-	 * @return the request variables or {@code null}
+	 * Return values for variable referenced within the query via $syntax.
+	 * @return a map of variables, or an empty map.
 	 */
 	public Map<String, Object> getVariables() {
 		return this.variables;
 	}
 
 	/**
-	 * Return the locale associated with the request, if available.
-	 * @return the locale of {@code null}
+	 * Return the locale associated with the request.
+	 * @return the locale of {@code null}.
 	 */
 	@Nullable
 	public Locale getLocale() {

spring-graphql/src/main/java/org/springframework/graphql/web/WebInput.java

@@ -31,9 +31,10 @@ import org.springframework.web.util.UriComponents;
 import org.springframework.web.util.UriComponentsBuilder;
 
 /**
- * Container for the input of a GraphQL query over HTTP. The input includes the
- * {@link UriComponents URL} and the headers of the request, as well as the query name,
- * operation name, and variables from the request body.
+ * Container for the input of a GraphQL request over HTTP or WebSocket, including
+ * the URL and HTTP headers, along with the query, operation name, and variables
+ * from the body of the request. For WebSocket, the URL and HTTP headers  are
+ * those of the WebSocket handshake request.
  *
  * @author Rossen Stoyanchev
  * @since 1.0.0
@@ -48,10 +49,10 @@ public class WebInput extends RequestInput {
 
 	/**
 	 * Create an instance.
-	 * @param uri the url for the HTTP request, or WebSocket handshake
+	 * @param uri the URL for the HTTP request or WebSocket handshake
 	 * @param headers the HTTP request headers
 	 * @param body the content of the request deserialized from JSON
-	 * @param locale the locale associated with the request, if any
+	 * @param locale the locale from the HTTP request, if any
 	 * @param id an identifier for the GraphQL request, e.g. a subscription id for
 	 * correlating request and response messages, or it could be an id associated with the
 	 * underlying request/connection id, if available
@@ -78,29 +79,23 @@ public class WebInput extends RequestInput {
 
 
 	/**
-	 * Return the URI of the HTTP request including {@link UriComponents#getQueryParams()
-	 * URL query parameters}.
-	 * @return the HTTP request URI
+	 * Return the URL for the HTTP request or WebSocket handshake.
 	 */
 	public UriComponents getUri() {
 		return this.uri;
 	}
 
 	/**
-	 * Return the headers of the request.
-	 * @return the HTTP request headers
+	 * Return the HTTP headers of the request or WebSocket handshake.
 	 */
 	public HttpHeaders getHeaders() {
 		return this.headers;
 	}
 
 	/**
-	 * Return the identifier for the request, which may be a subscription id for
-	 * correlating request and response messages, or the underlying request or connection
-	 * id, when available, or otherwise it's an
-	 * {@link ObjectUtils#identityToString(Object) identity} hash based this
-	 * {@code WebInput} instance.
-	 * @return the HTTP request identifier
+	 * Return an identifier for the request. This is useful to correlate
+	 * request and response messages on a multiplexed connection.
+	 * @see <a href="https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md">GraphQL over WebSocket Protocol</a>
 	 */
 	public String getId() {
 		return this.id;

spring-graphql/src/main/java/org/springframework/graphql/web/WebInterceptor.java

@@ -36,6 +36,7 @@ import org.springframework.util.Assert;
  *
  * @author Rossen Stoyanchev
  * @since 1.0.0
+ * @see WebSocketInterceptor
  */
 public interface WebInterceptor {
 
@@ -53,8 +54,8 @@ public interface WebInterceptor {
 
 	/**
 	 * Return a composed {@link WebInterceptor} that invokes the current
-	 * interceptor first and then the one one passed in.
-	 * @param interceptor the interceptor to compose the current one with
+	 * interceptor first and then the one that is passed in.
+	 * @param interceptor the interceptor to delegate to after "this" interceptor
 	 * @return the composed WebInterceptor
 	 */
 	default WebInterceptor andThen(WebInterceptor interceptor) {