- code cleanup

- added javadoc comments
gkesler · Dec 29, 2018 · Dec 29, 2018 · Dec 29, 2018 · Dec 30, 2018 · Dec 30, 2018
commit 48cd644fcf217fc445318821c25e8e2f8dc55dd1
diff --git a/src/main/java/graphql/execution/ExecutionStepInfoFactory.java b/src/main/java/graphql/execution/ExecutionStepInfoFactory.java
@@ -23,8 +23,7 @@ public class ExecutionStepInfoFactory {
 
     public ExecutionStepInfo newExecutionStepInfoForSubField(ExecutionContext executionContext, List<Field> sameFields, ExecutionStepInfo parentInfo) {
         Field field = sameFields.get(0);
-//        GraphQLObjectType parentType = (GraphQLObjectType) parentInfo.getUnwrappedNonNullType();
-        GraphQLObjectType parentType = (GraphQLObjectType) GraphQLTypeUtil.unwrapAll(parentInfo.getType());
+        GraphQLObjectType parentType = (GraphQLObjectType) parentInfo.getUnwrappedNonNullType();
         GraphQLFieldDefinition fieldDefinition = Introspection.getFieldDef(executionContext.getGraphQLSchema(), parentType, field.getName());
         GraphQLOutputType fieldType = fieldDefinition.getType();
         List<Argument> fieldArgs = field.getArguments();

diff --git a/src/main/java/graphql/execution3/DAGExecutionStrategy.java b/src/main/java/graphql/execution3/DAGExecutionStrategy.java
@@ -20,6 +20,7 @@
 import graphql.language.Node;
 import graphql.schema.GraphQLOutputType;
 import graphql.schema.GraphQLType;
+import graphql.schema.GraphQLTypeUtil;
 import graphql.util.DependenciesIterator;
 import graphql.util.Edge;
 import graphql.util.TriFunction;
@@ -32,6 +33,8 @@
 import java.util.List;
 import java.util.Objects;
 import java.util.concurrent.CompletableFuture;
+import java.util.function.Supplier;
+import java.util.function.UnaryOperator;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
 import org.slf4j.Logger;
@@ -48,6 +51,15 @@ public DAGExecutionStrategy (ExecutionContext executionContext) {
         this.valueFetcher = new ValueFetcher(executionContext);
     }
 
+    /**
+     * Executes a graphql request according to the schedule
+     * provided by executionPlan
+     * 
+     * @param executionPlan a {@code graphql.util.DependencyGraph} specialization that provides
+     * order of field resolution requests
+     * 
+     * @return a CompletableFuture holding the result of execution.
+     */
     @Override
     public CompletableFuture<ExecutionResult> execute(ExecutionPlan executionPlan) {
         assertNotNull(executionPlan);
@@ -146,8 +158,14 @@ private CompletableFuture<NodeVertex<Node, GraphQLType>> fetchNode (NodeVertex<N
 
         FieldVertex fieldNode = node.as(FieldVertex.class);
         List<Field> sameFields = Collections.singletonList(fieldNode.getNode());
+        ExecutionStepInfo sourceExecutionStepInfo = node.getParentExecutionStepInfo();
+        GraphQLOutputType parentType = (GraphQLOutputType)GraphQLTypeUtil.unwrapAll(sourceExecutionStepInfo.getType());
+        ExecutionStepInfo parentExecutionStepInfo = sourceExecutionStepInfo
+            .transform(builder -> builder
+                    .parentInfo(sourceExecutionStepInfo.getParent())
+                    .type(parentType));
         ExecutionStepInfo executionStepInfo = executionInfoFactory
-            .newExecutionStepInfoForSubField(executionContext, sameFields, node.getParentExecutionStepInfo());
+            .newExecutionStepInfoForSubField(executionContext, sameFields, parentExecutionStepInfo);
 
         TriFunction<FieldVertex, List<Field>, ExecutionStepInfo, CompletableFuture<List<FetchedValue>>> valuesFetcher = 
             fieldNode.isRoot() ? this::fetchRootValues : this::fetchBatchedValues;

diff --git a/src/main/java/graphql/execution3/DocumentVertex.java b/src/main/java/graphql/execution3/DocumentVertex.java
@@ -7,14 +7,11 @@
 
 import graphql.execution.ExecutionStepInfo;
 import graphql.language.Document;
-import graphql.language.Node;
 import graphql.schema.GraphQLType;
-import graphql.util.DependencyGraphContext;
 import java.util.Objects;
 
 /**
- *
- * @author gkesler
+ * ExecutionPlan Vertex created around Document node
  */
 public class DocumentVertex extends NodeVertex<Document, GraphQLType> {
     public DocumentVertex(Document node) {

diff --git a/src/main/java/graphql/execution3/Execution.java b/src/main/java/graphql/execution3/Execution.java
@@ -19,16 +19,34 @@
 import java.util.function.Function;
 import static graphql.execution3.ExecutionPlan.newExecutionPlanBuilder;
 
-/**
- *
- * @author gkesler
- */
 public class Execution {
+    /**
+     * Executes GraphQL request using {@link graphql.execution3.ExecutionStrategy} class
+     * to instantiate ExecutionStrategy
+     * 
+     * @param strategyClass     ExecutionStrategy class to instantiate
+     * @param document          root of GraphQL AST
+     * @param schema            GraphQL schema
+     * @param executionId       assigned execution id
+     * @param executionInput    input parameters, variables, etc.
+     * @return CompletableFuture that when completes holds result of this execution
+     */
     public CompletableFuture<ExecutionResult> execute (Class<? extends ExecutionStrategy> strategyClass, Document document, 
             GraphQLSchema schema, ExecutionId executionId, ExecutionInput executionInput) {
         return execute(executionContext -> newExecutionStrategy(strategyClass, executionContext), document, schema, executionId, executionInput);
     }
 
+    /**
+     * Executes GraphQL request using {@link graphql.execution3.ExecutionStrategy} class
+     * to instantiate ExecutionStrategy
+     * 
+     * @param strategyCreator   ExecutionStrategy factory
+     * @param document          root of GraphQL AST
+     * @param schema            GraphQL schema
+     * @param executionId       assigned execution id
+     * @param executionInput    input parameters, variables, etc.
+     * @return CompletableFuture that when completes holds result of this execution
+     */
     public CompletableFuture<ExecutionResult> execute (Function<? super ExecutionContext, ? extends ExecutionStrategy> strategyCreator, Document document, 
             GraphQLSchema schema, ExecutionId executionId, ExecutionInput executionInput) {
         try {
@@ -66,8 +84,8 @@ private CompletableFuture<ExecutionResult> doExecute (Function<? super Execution
     private static ExecutionStrategy newExecutionStrategy (Class<? extends ExecutionStrategy> strategyClass, ExecutionContext executionContext) {
         try {
             return strategyClass
-                    .getConstructor(ExecutionContext.class)
-                    .newInstance(executionContext);
+                .getConstructor(ExecutionContext.class)
+                .newInstance(executionContext);
         } catch (NoSuchMethodException | InstantiationException | IllegalAccessException | InvocationTargetException e) {
             throw new RuntimeException(e);
         }

diff --git a/src/main/java/graphql/execution3/ExecutionPlan.java b/src/main/java/graphql/execution3/ExecutionPlan.java
@@ -50,19 +50,33 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
-/**
- *
- * @author gkesler
- */
 class ExecutionPlan extends DependencyGraph<NodeVertex<Node, GraphQLType>> {    
+    /**
+     * Retrieves GraphQL schema associated with this execution plan
+     * 
+     * @return GraphQL schema
+     */
     public GraphQLSchema getSchema() {
         return schema;
     }
 
+    /**
+     * Retrieves GraphQL AST root Node associated with this execution plan
+     * 
+     * @return  AST root
+     */
     public Document getDocument() {
         return document;
     }
 
+    /**
+     * Locates an OperationDefinition corresponding to the specified openationName
+     * https://facebook.github.io/graphql/June2018/#sec-Executing-Requests
+     * 
+     * @param operationName name of operation to execute, could be null
+     * @return OperationDefinition for the specified operation name
+     * @throws UnknownOperationException if OperationDefinition could not be found
+     */
     public OperationDefinition getOperation (String operationName) {
         if (operationName == null && operationsByName.size() > 1)
             throw new UnknownOperationException("Must provide operation name if query contains multiple operations.");
@@ -72,14 +86,31 @@ public OperationDefinition getOperation (String operationName) {
             .orElseThrow(() -> new UnknownOperationException(String.format("Unknown operation named '%s'.", operationName)));
     }
 
+    /**
+     * Retrieves all OperationDefinitions that exist in the document keyed off 
+     * their operation names
+     * 
+     * @return a map containing OperationDefinitions
+     */
     public Map<String, OperationDefinition> getOperationsByName() {
         return Collections.unmodifiableMap(operationsByName);
     }
 
+    /**
+     * Retrieves all FragmentDefinitions that exist in the document keyed off 
+     * their fragment names
+     * 
+     * @return a map containing FragmentDefinitions
+     */
     public Map<String, FragmentDefinition> getFragmentsByName() {
         return Collections.unmodifiableMap(fragmentsByName);
     }
 
+    /**
+     * After the ExecutionPLan is built, retrieves coerced variables for the selected operation
+     * 
+     * @return variables map
+     */
     public Map<String, Object> getVariables() {
         return Collections.unmodifiableMap(variables);
     }
@@ -114,6 +145,12 @@ public synchronized void close(Collection<NodeVertex<Node, GraphQLType>> resolve
 
     }
 
+    /**
+     * Creates and initializes ExecutionContextBuilder
+     * 
+     * @param operationName selected operation name for this execution
+     * @return new ExecutionContextBuilder
+     */
     public ExecutionContextBuilder newExecutionContextBuilder (String operationName) {
         return ExecutionContextBuilder.newExecutionContextBuilder()
             .graphQLSchema(schema)
@@ -165,11 +202,25 @@ public TraversalControl visitFragmentDefinition(FragmentDefinition node, Travers
             return this;
         }
 
+        /**
+         * Adds an operation to the list of selected operations
+         * 
+         * @param operationName operation name to select
+         * @return this instance
+         * @throws {@link graphql.execution.UnknownOperationException} in case the operation is not found
+         */
         public Builder operation (String operationName) {
             operations.add(executionPlan.getOperation(operationName));
             return this;
         }
 
+        /**
+         * Stores variables for the coercion.
+         * Note! Coercion happens <b>only</b> at the time of building the execution plan
+         * 
+         * @param variables variables map
+         * @return this instance
+         */
         public Builder variables (Map<String, Object> variables) {
             executionPlan.variables = Objects.requireNonNull(variables);
             return this;
@@ -197,6 +248,12 @@ protected TraversalControl visitNode(Node node, TraverserContext<Node> context)
             });
         }
 
+        /**
+         * Builds execution plan according to the input query document,
+         * GraphQL schema, selected operations and provided variables
+         * 
+         * @return execution plan to execute the query document
+         */
         public ExecutionPlan build () {  
             Objects.requireNonNull(executionPlan.schema);
 

diff --git a/src/main/java/graphql/execution3/ExecutionPlanContext.java b/src/main/java/graphql/execution3/ExecutionPlanContext.java
@@ -10,12 +10,28 @@
 import graphql.util.DependencyGraphContext;
 import graphql.util.Edge;
 
-/**
- *
- * @author gkesler
- */
 public interface ExecutionPlanContext extends DependencyGraphContext {
+    /**
+     * A callback method called when ExecutionPlan needs to prepare edge vertices for execution.
+     * For instance, propagate &amp; transform results from source vertex to become sources in sink vertex
+     * 
+     * @param edge the edge being followed (source -- to --&gt; sink)
+     */
     void prepareResolve (Edge<? extends NodeVertex<? extends Node, ? extends GraphQLType>, ?> edge);
+    /**
+     * A callback method called when ExecutionPlan has finished resolving the edge.
+     * Resolution results are stored in the edge source vertex results
+     * Edge sink is a vertex that may accumulate the overall result.
+     * 
+     * @param edge the edge being followed
+     */
     void whenResolved (Edge<? extends NodeVertex<? extends Node, ? extends GraphQLType>, ?> edge);
+    /**
+     * A callback method called when ExecutionPlan attempts to auto resolve a vertex,
+     * i.e. without invoking external data fetcher
+     * 
+     * @param node vertex to attempt to auto resolve
+     * @return {@code true} if auto resolved, {@code false} otherwise
+     */
     boolean resolve (NodeVertex<? extends Node, ? extends GraphQLType> node);
 }
diff --git a/src/main/java/graphql/execution3/ExecutionStrategy.java b/src/main/java/graphql/execution3/ExecutionStrategy.java
@@ -8,17 +8,13 @@
 import graphql.ExecutionResult;
 import java.util.concurrent.CompletableFuture;
 
-/**
- *
- * @author gkesler
- */
 public interface ExecutionStrategy {
     /**
      * Executes a graphql request according to the schedule
      * provided by executionPlan
      * 
      * @param executionPlan a {@code graphql.util.DependencyGraph} specialization that provides
-     * order of field resolution requets
+     * order of field resolution requests
      * 
      * @return a CompletableFuture holding the result of execution.
      */

diff --git a/src/main/java/graphql/execution3/FieldVertex.java b/src/main/java/graphql/execution3/FieldVertex.java
@@ -23,8 +23,7 @@
 import java.util.Optional;
 
 /**
- *
- * @author gkesler
+ * A vertex wrapping Field AST node
  */
 public class FieldVertex extends NodeVertex<Field, GraphQLOutputType> {    
     public FieldVertex(Field node, GraphQLOutputType type, GraphQLFieldsContainer definedIn) {
@@ -74,30 +73,69 @@ public TraversalControl visitGraphQLEnumType(GraphQLEnumType node, TraverserCont
         this.inScopeOf = inScopeOf;
     }    
 
+    /**
+     * Parent container where this Field is defined
+     * 
+     * @return parent GraphQL type
+     */
     public GraphQLFieldsContainer getDefinedIn() {
         return definedIn;
     }
 
+    /**
+     * If a direct or indirect parent (source) of this vertex has alias,
+     * retrieves that aliased source.
+     * 
+     * @return aliased direct or indirect aliased source of this vertex
+     */
     public Object getInScopeOf() {
         return inScopeOf;
     }
 
+    /**
+     * Retrieves result of analysis on the kind of object this Field represents
+     * 
+     * @return analysis result of this Field
+     */
     public Kind getKind() {
         return kind;
     }
 
+    /**
+     * Retrieves cardinality of this Field
+     * 
+     * @return cardinality analysis result
+     */
     public Cardinality getCardinality() {
         return cardinality;
     }
 
+    /**
+     * Verifies if this Field value <b>must not</b> be null.
+     * If this constraint is not satisfied, the parent result is null.
+     * 
+     * @return "not null" constraint for this field
+     */
     public boolean isNotNull() {
         return notNull;
     }
 
+    /**
+     * Verifies if this Field element value (if this Field is a GraphQLList) <b>must not</b> be null.
+     * If this constraint is not satisfied, the result for the entire list is null.
+     * 
+     * @return "not null" constraint for a list item
+     */ 
     public boolean isNotNullItems() {
         return notNullItems;
     }
 
+    /**
+     * Key to store this field in the parent result
+     * https://facebook.github.io/graphql/June2018/#CollectFields()
+     * 
+     * @return response key
+     */
     public String getResponseKey () {
         return Optional
             .ofNullable(node.getAlias())

diff --git a/src/main/java/graphql/execution3/NodeEdge.java b/src/main/java/graphql/execution3/NodeEdge.java
@@ -12,8 +12,7 @@
 import java.util.function.BiConsumer;
 
 /**
- *
- * @author gkesler
+ * A specialization of Edge class used occasionally wen building ExecutionPlan
  */
 public class NodeEdge extends Edge<NodeVertex<Node, GraphQLType>, NodeEdge> {
     public <N extends NodeVertex<? extends Node, ? extends GraphQLType>> NodeEdge(N source, N sink) {