/**
 * A wrapper around {@link #extractProjectKeys(Traversal)} that guarantees the passed-in traversal
 * at least ends with a step that produces a {@code Map<String, Object>} when terminated.
 */
private List<String> extractProjectKeysFromMapTraversal(
    GraphTraversal<?, Map<String, Object>> traversalEndingWithMap) {
  return this.extractProjectKeys(traversalEndingWithMap);
}


/**
 * Extracts the keys of the final {@link ProjectStep} in a given {@link Traversal}.
 * 
 * <p>
 * If the traversal ends with a {@link TraversalParent}, the last child of that step is then
 * recursively processed again. This continues until either a {@link ProjectStep} is found, or an
 * exception is raised as the traversal does not end on a {@link ProjectStep}.
 * 
 * <p>
 * NB: This method assumes the traversal given ends with a {@code Map<String, Object>}, so this
 * should be validated prior to calling this method.
 * 
 * @param traversal the {@link Traversal} from which to extract the keys of the final
 *        {@link ProjectStep}
 * @return the keys of the final {@link ProjectStep} in the provided {@link Traversal}
 * @throws IllegalStateException if the final step is not a {@link ProjectStep} or a
 *         {@link TraversalParent} which can be further processed (must have only one child)
 */
private List<String> extractProjectKeys(Traversal<?, ?> traversal) throws IllegalStateException {
  Step<?, ?> end = traversal.asAdmin().clone().getEndStep();
  Preconditions.checkArgument(
      end instanceof ProjectStep || end instanceof TraversalParent,
      "Traversal must end with project step or a parent step containing a project step.");

  // If the last step is a ProjectStep, we're done.
  if (end instanceof ProjectStep) {
    return ((ProjectStep<?, ?>) end).getProjectKeys();
  }

  // Otherwise recursively find the project step if the final step is a parent step (e.g. local())
  List<Traversal.Admin<Object, Object>> childSteps = ((TraversalParent) end).getLocalChildren();
  // TODO: Should we validate all children of a parent step? If a parent takes multiple children
  // it might be a condition, so we could validate that all branches end with project()
  Preconditions.checkArgument(
      childSteps.size() == 1,
      "Encountered a final step which is a TraversalParent with more than one child. This is not yet supported.");
  return extractProjectKeys(childSteps.get(0));
}

/**
 * A wrapper around {@link #extractProjectKeys(Traversal)} that guarantees the passed-in traversal
 * at least ends with a step that produces a {@code Map<String, Object>} when terminated.
 */
private List<String> extractProjectKeysFromMapTraversal(
    GraphTraversal<?, Map<String, Object>> traversalEndingWithMap) {
  return this.extractProjectKeys(traversalEndingWithMap);
}


/**
 * Extracts the keys of the final {@link ProjectStep} in a given {@link Traversal}.
 * 
 * <p>
 * If the traversal ends with a {@link TraversalParent}, the last child of that step is then
 * recursively processed again. This continues until either a {@link ProjectStep} is found, or an
 * exception is raised as the traversal does not end on a {@link ProjectStep}.
 * 
 * <p>
 * NB: This method assumes the traversal given ends with a {@code Map<String, Object>}, so this
 * should be validated prior to calling this method.
 * 
 * @param traversal the {@link Traversal} from which to extract the keys of the final
 *        {@link ProjectStep}
 * @return the keys of the final {@link ProjectStep} in the provided {@link Traversal}
 * @throws IllegalStateException if the final step is not a {@link ProjectStep} or a
 *         {@link TraversalParent} which can be further processed (must have only one child)
 */
private List<String> extractProjectKeys(Traversal<?, ?> traversal) throws IllegalStateException {
  Step<?, ?> end = traversal.asAdmin().clone().getEndStep();
  Preconditions.checkArgument(
      end instanceof ProjectStep || end instanceof TraversalParent,
      "Traversal must end with project step or a parent step containing a project step.");

  // If the last step is a ProjectStep, we're done.
  if (end instanceof ProjectStep) {
    return ((ProjectStep<?, ?>) end).getProjectKeys();
  }

  // Otherwise recursively find the project step if the final step is a parent step (e.g. local())
  List<Traversal.Admin<Object, Object>> childSteps = ((TraversalParent) end).getLocalChildren();
  // TODO: Should we validate all children of a parent step? If a parent takes multiple children
  // it might be a condition, so we could validate that all branches end with project()
  Preconditions.checkArgument(
      childSteps.size() == 1,
      "Encountered a final step which is a TraversalParent with more than one child. This is not yet supported.");
  return extractProjectKeys(childSteps.get(0));
}