Add utilites and unit tests to help coverage

Issue-ID: AAI-649
Change-Id: Ia855abe83692d86f4243f98ca75737c991da8976
Signed-off-by: Venkata Harish K Kajur <vk250x@att.com>

2 files changed, 83 insertions, 16 deletions

diff --git a/aai-core/src/main/java/org/onap/aai/serialization/engines/query/GraphTraversalQueryEngine.java b/aai-core/src/main/java/org/onap/aai/serialization/engines/query/GraphTraversalQueryEngine.java
index 692fd531..7efe2ea9 100644
--- a/aai-core/src/main/java/org/onap/aai/serialization/engines/query/GraphTraversalQueryEngine.java
+++ b/aai-core/src/main/java/org/onap/aai/serialization/engines/query/GraphTraversalQueryEngine.java
@@ -69,6 +69,7 @@ public class GraphTraversalQueryEngine extends QueryEngine {
 	@Override
 	public List<Vertex> findParents(Vertex start) {
 		
+		@SuppressWarnings("unchecked")
 		final GraphTraversal<Vertex, Vertex> pipe = this.g.V(start).emit(v -> true).repeat(__.union(__.inE().has(CONTAINS.toString(), OUT.toString()).outV(), __.outE().has(CONTAINS.toString(), IN.toString()).inV()));
 		return pipe.toList();
 	}
@@ -79,6 +80,7 @@ public class GraphTraversalQueryEngine extends QueryEngine {
 	@Override
 	public List<Vertex> findAllChildren(Vertex start) {
 		
+		@SuppressWarnings("unchecked")
 		GraphTraversal<Vertex, Vertex> pipe =  this.g
 				.V(start).emit(v -> true).repeat(__.union(__.outE().has(CONTAINS.toString(), OUT.toString()).inV(), __.inE().has(CONTAINS.toString(), IN.toString()).outV()));
 		
@@ -87,7 +89,12 @@ public class GraphTraversalQueryEngine extends QueryEngine {
 		
 	}
 
+	/**
+	 * {@inheritDoc}
+	 */
+	@Override
 	public List<Vertex> findChildrenOfType(Vertex start, String type) {
+		@SuppressWarnings("unchecked")
 		GraphTraversal<Vertex, Vertex> pipe =  this.g.V(start).union(
 					__.outE().has(CONTAINS.toString(), OUT.toString()).inV(),
 					__.inE().has(CONTAINS.toString(), IN.toString()).outV()
@@ -96,7 +103,12 @@ public class GraphTraversalQueryEngine extends QueryEngine {
 		return pipe.toList();
 	}
 	
+	/**
+	 * {@inheritDoc}
+	 */
+	@Override
 	public List<Vertex> findChildren(Vertex start) {
+		@SuppressWarnings("unchecked")
 		GraphTraversal<Vertex, Vertex> pipe =  this.g.V(start).union(
 					__.outE().has(CONTAINS.toString(), OUT.toString()),
 					__.inE().has(CONTAINS.toString(), IN.toString())
@@ -110,6 +122,7 @@ public class GraphTraversalQueryEngine extends QueryEngine {
 	 */
 	@Override
 	public List<Vertex> findDeletable(Vertex start) {
+		@SuppressWarnings("unchecked")
 		GraphTraversal<Vertex, Vertex> pipe = this.g
 				.V(start).emit(v -> true).repeat(
 					__.union(
diff --git a/aai-core/src/main/java/org/onap/aai/serialization/engines/query/QueryEngine.java b/aai-core/src/main/java/org/onap/aai/serialization/engines/query/QueryEngine.java
index 01f11b17..5a468b79 100644
--- a/aai-core/src/main/java/org/onap/aai/serialization/engines/query/QueryEngine.java
+++ b/aai-core/src/main/java/org/onap/aai/serialization/engines/query/QueryEngine.java
@@ -34,7 +34,7 @@ import java.util.List;
 
 public abstract class QueryEngine {
 
-	final protected GraphTraversalSource g;
+	protected final GraphTraversalSource g;
 
 	/**
 	 * Instantiates a new query engine.
@@ -46,49 +46,103 @@ public abstract class QueryEngine {
 	}
 	
 	/**
-	 * Find parents.
+	 * Finds all the parents/grandparents/etc of the given start node.
 	 *
-	 * @param start the start
-	 * @return the list
+	 * @param start - the start vertex whose parent chain you want
+	 * @return the list of start and start's parent, grandparent, etc, in
+	 * 			order (ie {start, parent, grandparent, etc} 
 	 */
 	public abstract List<Vertex> findParents(Vertex start);
 	
 	/**
-	 * Find children.
+	 * Finds all children, grandchildren, etc of start
 	 *
-	 * @param start the start
-	 * @return the list
+	 * @param start the start vertex
+	 * @return the list of child/grandchild/etc vertices
 	 */
 	public abstract List<Vertex> findAllChildren(Vertex start);
 	
+	/**
+	 * Finds all immediate children of start (no grandchildren or so forth) of the given type
+	 * @param start - the start vertex
+	 * @param type - the desired aai-node-type
+	 * @return the list of immediate child vertices of given type
+	 */
 	public abstract List<Vertex> findChildrenOfType(Vertex start, String type);
 	
+	/**
+	 * Finds all immediate children of start (no grandchildren or so forth)
+	 * @param start - the start vertex
+	 * @return the list of immediate child vertices
+	 */
 	public abstract List<Vertex> findChildren(Vertex start);
+	
 	/**
-	 * Find deletable.
+	 * Find all vertices that should be deleted in a cascade from a delete of start
 	 *
-	 * @param start the start
-	 * @return the list
+	 * @param start - the start vertex
+	 * @return the list of vertices to be deleted when start is deleted
 	 */
 	public abstract List<Vertex> findDeletable(Vertex start);
 	
+	/**
+	 * Finds the subgraph under start, including cousins as well as start's children/grandchildren/etc.
+	 * More specifically, this includes start, all its descendants, start's cousins, and start's
+	 * descendants' cousins (but not any of the cousins' cousins or descendants), and the edges
+	 * connecting them.
+	 * 
+	 * @param start - the start vertex
+	 * @return - Tree containing nodes and edges of the subgraph 
+	 */
 	public Tree<Element> findSubGraph(Vertex start) {
 		return findSubGraph(start, AAIProperties.MAXIMUM_DEPTH, false);
 	}
+	
+	/**
+	 * Finds the subgraph under start, including cousins as well as start's children/grandchildren/etc.
+	 * More specifically, this includes start, all its descendants, start's cousins, and start's
+	 * descendants' cousins (but not any of the cousins' cousins or descendants), and the edges
+	 * connecting them.
+	 * 
+	 * @param start - the start vertex
+	 * @param iterations - depth of the subgraph, this limits how many generations of 
+	 * 						descendants are included
+	 * @param nodeOnly - if true the subgraph will NOT include the cousins
+	 * @return Tree containing nodes and edges of the subgraph 
+	 */
 	public abstract Tree<Element> findSubGraph(Vertex start, int iterations, boolean nodeOnly);
+	
 	/**
-	 * Find related vertices.
+	 * Find vertices of type nodeType related to start by edges of the given
+	 *  direction and label.
 	 *
-	 * @param start the start
-	 * @param direction the direction
-	 * @param label the label
-	 * @param nodeType the node type
-	 * @return the list
+	 * @param start - the start vertex
+	 * @param direction - the direction of edges to traverse from start
+	 * @param label - the label of edges to traverse from start
+	 * @param nodeType - the node type the results should be
+	 * @return the list of related vertices
 	 */
 	public abstract List<Vertex> findRelatedVertices(Vertex start, Direction direction, String label, String nodeType);
 
+	/**
+	 * Finds cousin edges connecting start to other vertices only of types defined in an old version.
+	 * The idea is that if a user is using an old version, they won't understand any new node types in
+	 * subsequent versions. Thus, revealing edges to new types will cause problems. This methods 
+	 * filters any such edges out.
+	 * 
+	 * @param start - the start vertex
+	 * @param loader - loader for retrieving the list of allowed node types for the desired version
+	 * 					(version is set when the loader was instantiated)
+	 * @return list of cousin edges between start and any node types understood by the version specified in loader
+	 */
 	public abstract List<Edge> findEdgesForVersion(Vertex start, Loader loader);
 	
+	/**
+	 * Finds all cousins of start. 
+	 * 
+	 * @param start - the start vertex
+	 * @return list of start's cousin vertices
+	 */
 	public abstract List<Vertex> findCousinVertices(Vertex start);
 
 }