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