aai-core/src/main/java/org/onap/aai/serialization/engines/query/QueryEngine.java

   1 /**
   2  * ============LICENSE_START=======================================================
   3  * org.onap.aai
   4  * ================================================================================
   5  * Copyright © 2017-2018 AT&T Intellectual Property. All rights reserved.
   6  * ================================================================================
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  *    http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  * ============LICENSE_END=========================================================
  19  */
  20 package org.onap.aai.serialization.engines.query;
  21
  22 import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversalSource;
  23 import org.apache.tinkerpop.gremlin.process.traversal.step.util.Tree;
  24 import org.apache.tinkerpop.gremlin.structure.Direction;
  25 import org.apache.tinkerpop.gremlin.structure.Edge;
  26 import org.apache.tinkerpop.gremlin.structure.Element;
  27 import org.apache.tinkerpop.gremlin.structure.Vertex;
  28 import org.onap.aai.db.props.AAIProperties;
  29 import org.onap.aai.introspection.Loader;
  30
  31 import java.util.List;
  32
  33 public abstract class QueryEngine {
  34
  35         final protected GraphTraversalSource g;
  36         protected double dbTimeMsecs = 0;
  37         /**
  38          * Instantiates a new query engine.
  39          *
  40      * @param g     graph traversal source to traverse the graph
  41          */
  42         public QueryEngine (GraphTraversalSource g) {
  43                 this.g = g;
  44         }
  45
  46         /**
  47          * Finds all the parents/grandparents/etc of the given start node.
  48          *
  49          * @param start - the start vertex whose parent chain you want
  50          * @return the list of start and start's parent, grandparent, etc, in
  51          *                      order (ie {start, parent, grandparent, etc}
  52          */
  53         public abstract List<Vertex> findParents(Vertex start);
  54
  55     /**
  56      * Finds all the parents/grandparents/etc of the given start node.
  57      *
  58      * This method should be used in place of the #findParents(Vertex)
  59      * as since the aai-uri is added the lookup for finding the parents
  60      * using the given list of aai-uri will be much faster than using
  61      * a traversal to follow a start vertex and keep repeating since
  62      * as the number of different type of edges keeps growing that call
  63      * will be more expensive than using the aai-uri's as they are fast lookup
  64      *
  65      * @param uris  - list of the uris representing the aai-uris of
  66      *                 parent, grandparent, etc
  67      * @return the list of start and start's parent, grandparent, etc, in
  68      *                  order (ie {start, parent, grandparent, etc}
  69      */
  70     public abstract List<Vertex> findParents(String [] uris);
  71
  72         /**
  73          * Finds all children, grandchildren, etc of start
  74          *
  75          * @param start the start vertex
  76          * @return the list of child/grandchild/etc vertices
  77          */
  78         public abstract List<Vertex> findAllChildren(Vertex start);
  79
  80         /**
  81          * Finds all immediate children of start (no grandchildren or so forth) of the given type
  82          * @param start - the start vertex
  83          * @param type - the desired aai-node-type
  84          * @return the list of immediate child vertices of given type
  85          */
  86         public abstract List<Vertex> findChildrenOfType(Vertex start, String type);
  87
  88         /**
  89          * Finds all immediate children of start (no grandchildren or so forth)
  90          * @param start - the start vertex
  91          * @return the list of immediate child vertices
  92          */
  93         public abstract List<Vertex> findChildren(Vertex start);
  94
  95         /**
  96          * Find all vertices that should be deleted in a cascade from a delete of start
  97          *
  98          * @param start - the start vertex
  99          * @return the list of vertices to be deleted when start is deleted
 100          */
 101         public abstract List<Vertex> findDeletable(Vertex start);
 102
 103     /**
 104      * Find all vertices that should be deleted in a cascade from a delete of start vertexes
 105      *
 106      * @param   startVertexes   Specifies the list of start vertexes
 107      *
 108      * @return  the list of vertices to be deleted when start list of vertexes is deleted
 109      */
 110     public abstract List<Vertex> findDeletable(List<Vertex> startVertexes);
 111
 112         /**
 113          * Finds the subgraph under start, including cousins as well as start's children/grandchildren/etc.
 114          * More specifically, this includes start, all its descendants, start's cousins, and start's
 115          * descendants' cousins (but not any of the cousins' cousins or descendants), and the edges
 116          * connecting them.
 117          *
 118          * @param start - the start vertex
 119          * @return - Tree containing nodes and edges of the subgraph
 120          */
 121         public Tree<Element> findSubGraph(Vertex start) {
 122                 return findSubGraph(start, AAIProperties.MAXIMUM_DEPTH, false);
 123         }
 124
 125         /**
 126          * Finds the subgraph under start, including cousins as well as start's children/grandchildren/etc.
 127          * More specifically, this includes start, all its descendants, start's cousins, and start's
 128          * descendants' cousins (but not any of the cousins' cousins or descendants), and the edges
 129          * connecting them.
 130          *
 131          * @param start - the start vertex
 132          * @param iterations - depth of the subgraph, this limits how many generations of
 133          *                                              descendants are included
 134          * @param nodeOnly - if true the subgraph will NOT include the cousins
 135          * @return Tree containing nodes and edges of the subgraph
 136          */
 137         public abstract Tree<Element> findSubGraph(Vertex start, int iterations, boolean nodeOnly);
 138
 139         /**
 140          * Find vertices of type nodeType related to start by edges of the given
 141          *  direction and label.
 142          *
 143          * @param start - the start vertex
 144          * @param direction - the direction of edges to traverse from start
 145          * @param label - the label of edges to traverse from start
 146          * @param nodeType - the node type the results should be
 147          * @return the list of related vertices
 148          */
 149         public abstract List<Vertex> findRelatedVertices(Vertex start, Direction direction, String label, String nodeType);
 150
 151         /**
 152          * Finds cousin edges connecting start to other vertices only of types defined in an old version.
 153          * The idea is that if a user is using an old version, they won't understand any new node types in
 154          * subsequent versions. Thus, revealing edges to new types will cause problems. This methods
 155          * filters any such edges out.
 156          *
 157          * @param start - the start vertex
 158          * @param loader - loader for retrieving the list of allowed node types for the desired version
 159          *                                      (version is set when the loader was instantiated)
 160          * @return list of cousin edges between start and any node types understood by the version specified in loader
 161          */
 162         public abstract List<Edge> findEdgesForVersion(Vertex start, Loader loader);
 163
 164         /**
 165          * Finds all cousins of start.
 166          *
 167          * @param start - the start vertex
 168          * @return list of start's cousin vertices
 169          */
 170         public abstract List<Vertex> findCousinVertices(Vertex start, String... labels);
 171
 172         public abstract double getDBTimeMsecs();
 173
 174 }