Add utilites and unit tests to help coverage

[aai/aai-common.git] / aai-core / src / main / java / org / onap / aai / serialization / engines / query / QueryEngine.java

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 01f11b1..5a468b7 100644 (file)
--- 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);
 
 }