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