Add documentation

ground-core/src/main/java/edu/berkeley/ground/api/models/RichVersionFactory.java

@@ -39,6 +39,13 @@ protected static RichVersion construct(String id,
         return new RichVersion(id, tags, structureVersionId, reference, parameters);
     }
 
+    /**
+     * Validate that the given Tags satisfy the StructureVersion's requirements.
+     *
+     * @param structureVersion the StructureVersion to check against
+     * @param tags the provided tags
+     * @throws GroundException
+     */
     protected static void checkStructureTags(StructureVersion structureVersion, Map<String, Tag> tags) throws GroundException {
         Map<String, GroundType> structureVersionAttributes = structureVersion.getAttributes();
 

ground-core/src/main/java/edu/berkeley/ground/api/models/cassandra/CassandraTagFactory.java

@@ -48,6 +48,7 @@ public Map<String, Tag> retrieveFromDatabaseById(GroundDBConnection connectionPo
         while (resultSet.next()) {
             String key = resultSet.getString("key");
 
+            // these methods will return null if the input is null, so there's no need to check
             GroundType type = GroundType.fromString(resultSet.getString("type"));
 
             String valueString = resultSet.getString("value");
@@ -71,7 +72,7 @@ public List<String> getIdsByTag(GroundDBConnection connectionPointer, String tag
 
         QueryResults resultSet;
         try {
-            resultSet = connection.equalitySelect("Tags", DBClient.SELECT_STAR, predicates);
+            resultSet = connection.equalitySelect("Tags", projections, predicates);
         } catch (EmptyResultException eer) {
             // this means that there are no tags
             return result;

ground-core/src/main/java/edu/berkeley/ground/api/models/gremlin/GremlinTagFactory.java

@@ -23,7 +23,6 @@
 import edu.berkeley.ground.exceptions.EmptyResultException;
 import edu.berkeley.ground.exceptions.GroundException;
 import org.apache.tinkerpop.gremlin.structure.Vertex;
-import org.apache.tinkerpop.gremlin.structure.VertexProperty;
 
 import java.util.*;
 
@@ -68,7 +67,7 @@ public Map<String, Tag> retrieveFromDatabaseById(GroundDBConnection connectionPo
     public List<String> getIdsByTag(GroundDBConnection connectionPointer, String tag) throws GroundException {
         GremlinConnection connection = (GremlinConnection) connectionPointer;
 
-        List<Vertex> taggedVertices = connection.getVerticesByLabel("tkey", tag);
+        List<Vertex> taggedVertices = connection.getVerticesByAttribute("tkey", tag);
 
         List<String> ids = new ArrayList<>();
         taggedVertices.forEach(vertex -> {

ground-core/src/main/java/edu/berkeley/ground/api/models/neo4j/Neo4jTagFactory.java

@@ -74,6 +74,6 @@ public List<String> getIdsByTag(GroundDBConnection connectionPointer, String tag
         List<DbDataContainer> predicates = new ArrayList<>();
         predicates.add(new DbDataContainer("tkey", GroundType.STRING, tag));
 
-        return connection.getVerticesByLabel(predicates);
+        return connection.getVerticesByAttributes(predicates);
     }
 }

ground-core/src/main/java/edu/berkeley/ground/api/models/postgres/PostgresTagFactory.java

@@ -46,6 +46,8 @@ public Map<String, Tag> retrieveFromDatabaseById(GroundDBConnection connectionPo
 
         do {
             String key = resultSet.getString(2);
+
+            // these methods will return null if the input is null, so there's no need to check
             GroundType type = GroundType.fromString(resultSet.getString(4));
 
             String valueString = resultSet.getString(3);

ground-core/src/main/java/edu/berkeley/ground/api/versions/ItemFactory.java

@@ -22,5 +22,16 @@
 public abstract class ItemFactory {
     public abstract void insertIntoDatabase(GroundDBConnection connection, String id) throws GroundException;
 
+    /**
+     * Add a new Version to this Item. The provided parentIds will be the parents of this particular
+     * version. What's provided in the default case varies based on which database we are writing
+     * into.
+     *
+     * @param connection
+     * @param itemId the id of the Item we're updating
+     * @param childId the new version's id
+     * @param parentIds the ids of the parents of the child
+     * @throws GroundException
+     */
     public abstract void update(GroundDBConnection connection, String itemId, String childId, List<String> parentIds) throws GroundException;
 }

ground-core/src/main/java/edu/berkeley/ground/api/versions/VersionHistoryDAGFactory.java

@@ -25,6 +25,16 @@ public abstract class VersionHistoryDAGFactory {
 
     public abstract <T extends Version> VersionHistoryDAG<T> retrieveFromDatabase(GroundDBConnection connection, String itemId) throws GroundException;
 
+    /**
+     * Add a new edge between parentId and childId in DAG
+     *
+     * @param connection
+     * @param dag the DAG to update
+     * @param parentId the parent's id
+     * @param childId the child's id
+     * @param itemId the id of the Item whose DAG we're updating
+     * @throws GroundException
+     */
     public abstract void addEdge(GroundDBConnection connection, VersionHistoryDAG dag, String parentId, String childId, String itemId) throws GroundException;
 
     protected static <T extends Version> VersionHistoryDAG<T> construct(String itemId) {

ground-core/src/main/java/edu/berkeley/ground/db/CassandraClient.java

@@ -21,16 +21,13 @@
 import edu.berkeley.ground.exceptions.GroundException;
 import edu.berkeley.ground.util.JGraphTUtils;
 
-import org.apache.cassandra.thrift.Cassandra;
 import org.jgrapht.*;
 import org.jgrapht.graph.DefaultEdge;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import java.util.ArrayList;
-import java.util.HashMap;
 import java.util.List;
-import java.util.Map;
 
 public class CassandraClient implements DBClient {
     private static final Logger LOGGER = LoggerFactory.getLogger(CassandraClient.class);
@@ -48,6 +45,7 @@ public CassandraClient(String host, int port, String dbName, String username, St
 
         this.keyspace = dbName;
 
+        // at startup, load all nodes & edges into JGraphT for later in-memory processing
         ResultSet resultSet = this.cluster.connect(this.keyspace).execute("select id from nodeversions;");
         this.graph = JGraphTUtils.createGraph();
 
@@ -79,6 +77,12 @@ public CassandraConnection(Session session, DirectedGraph<String, DefaultEdge> g
             this.adjacencyStatement = adjacencyStatement;
         }
 
+        /**
+         * Insert a new row into table with insertValues.
+         *
+         * @param table the table to update
+         * @param insertValues the values to put into table
+         */
         public void insert(String table, List<DbDataContainer> insertValues) {
             // hack to keep JGraphT up to date
             if (table.equals("NodeVersions")) {
@@ -135,6 +139,16 @@ public void insert(String table, List<DbDataContainer> insertValues) {
             this.session.execute(statement);
         }
 
+        /**
+         * Retrieve rows based on a set of predicates.
+         *
+         * @param table the table to query
+         * @param projection the set of columns to retrieve
+         * @param predicatesAndValues the predicates
+         * @return
+         * @throws EmptyResultException
+         * @throws GroundDBException
+         */
         public CassandraResults equalitySelect(String table, List<String> projection, List<DbDataContainer> predicatesAndValues) throws EmptyResultException, GroundDBException {
             String select = "select ";
             for (String item : projection) {
@@ -175,7 +189,7 @@ public CassandraResults equalitySelect(String table, List<String> projection, Li
         }
 
         public List<String> transitiveClosure(String nodeVersionId) throws GroundException {
-            return JGraphTUtils.iterate(this.graph, nodeVersionId);
+            return JGraphTUtils.runDFS(this.graph, nodeVersionId);
         }
 
         public List<String> adjacentNodes(String nodeVersionId, String edgeNameRegex) throws GroundException {
@@ -205,43 +219,6 @@ public void abort() throws GroundDBException {
         }
     }
 
-    private PreparedStatement prepareInsert(String table, int numFields) {
-        String insertString = "insert into " + table + "(";
-        String valuesString = "values (";
-
-        for (int i = 0 ; i < numFields ; i++) {
-            insertString += "?, ";
-            valuesString += "?, ";
-        }
-
-        insertString = insertString.substring(0, insertString.length() - 2) + ")";
-        valuesString = valuesString.substring(0, valuesString.length() - 2) + ")";
-
-        return this.cluster.connect(this.keyspace).prepare(insertString + valuesString + ";");
-    }
-
-    private PreparedStatement prepareSelect(String table, List<String> selects, List<String> predicateFields) {
-        String select = "select ";
-        for (String s : selects) {
-            select += s + ", ";
-        }
-
-        select = select.substring(0, select.length() - 2) + " from " + table;
-
-        if (predicateFields.size() > 0) {
-            select += " where ";
-
-            for (String predicateField : predicateFields) {
-                select += predicateField + " = ? and ";
-            }
-
-            select = select.substring(0, select.length() - 4);
-        }
-
-        return this.cluster.connect(this.keyspace).prepare(select + ";");
-    }
-
-
     private static void setValue(BoundStatement statement, Object value, GroundType groundType, int index) {
         switch (groundType) {
             case STRING:

ground-core/src/main/java/edu/berkeley/ground/db/DBClient.java

@@ -31,6 +31,13 @@ abstract class GroundDBConnection {
 
         public abstract void abort() throws GroundDBException;
 
+        /**
+         * Run transitive closure from nodeVersionId.
+         *
+         * @param nodeVersionId the start id
+         * @return the list of reachable ids
+         * @throws GroundException
+         */
         public abstract List<String> transitiveClosure(String nodeVersionId) throws GroundException;
     }
 }

ground-core/src/main/java/edu/berkeley/ground/db/GremlinClient.java

@@ -48,6 +48,13 @@ protected GremlinConnection(Graph graph) {
             graph.tx();
         }
 
+        /**
+         * Add a new vertex to the graph.
+         *
+         * @param label the vertex label
+         * @param attributes the vertex's attributes
+         * @return the created vertex
+         */
         public Vertex addVertex(String label, List<DbDataContainer> attributes) {
             Object[] attributesArray = new Object[(attributes.size() + 1) * 2];
             for(int i = 1; i < attributes.size() + 1; i++) {
@@ -61,6 +68,14 @@ public Vertex addVertex(String label, List<DbDataContainer> attributes) {
             return this.graph.addVertex(attributesArray);
         }
 
+        /**
+         * Add a new edge to the graph.
+         *
+         * @param label the edge label
+         * @param source the source of the edge
+         * @param destination the destination of the edge
+         * @param attributes the edge's attributes
+         */
         public void addEdge(String label, Vertex source, Vertex destination, List<DbDataContainer> attributes) {
             Object[] attributesArray = new Object[attributes.size() * 2];
             for(int i = 0; i < attributes.size(); i++) {
@@ -71,6 +86,13 @@ public void addEdge(String label, Vertex source, Vertex destination, List<DbData
             source.addEdge(label, destination, attributesArray);
         }
 
+        /**
+         * Retrieve a vertex without a label.
+         *
+         * @param predicates the predicates to check
+         * @return a vertex if one exists
+         * @throws EmptyResultException
+         */
         public Vertex getVertex(List<DbDataContainer> predicates) throws EmptyResultException {
             GraphTraversal traversal = this.graph.traversal().V();
 
@@ -85,6 +107,14 @@ public Vertex getVertex(List<DbDataContainer> predicates) throws EmptyResultExce
             throw new EmptyResultException("No matches for query.");
         }
 
+        /**
+         * Retrieve a vertex with a label.
+         *
+         * @param label the vertex label
+         * @param predicates the predicates to check
+         * @return a vertex if one exists
+         * @throws EmptyResultException
+         */
         public Vertex getVertex(String label, List<DbDataContainer> predicates) throws EmptyResultException {
             GraphTraversal traversal = this.graph.traversal().V();
 
@@ -114,7 +144,14 @@ public Edge getEdge(List<DbDataContainer> predicates) throws EmptyResultExceptio
             throw new EmptyResultException("No matches for quesry");
         }
 
-        public List<Vertex> getVerticesByLabel(String key, String value) {
+        /**
+         * Get all vertices that have a particular attribute.
+         *
+         * @param key the key of the attribute
+         * @param value the value of the attribute
+         * @return the vertices, if any exist
+         */
+        public List<Vertex> getVerticesByAttribute(String key, String value) {
             GraphTraversal traversal = this.graph.traversal().V();
             List<Vertex> vertices = new ArrayList<>();
 
@@ -123,6 +160,14 @@ public List<Vertex> getVerticesByLabel(String key, String value) {
             return vertices;
         }
 
+        /**
+         * Get all the edges with a particular label that are reachable from a particular
+         * starting vertex.
+         *
+         * @param vertex the starting point for the query
+         * @param label the edge label we are looking for
+         * @return the list of valid edges
+         */
         public List<Edge> getDescendantEdgesWithLabel(Vertex vertex, String label) {
             List<Edge> result = new ArrayList<>();
             LinkedList<Vertex> queue = new LinkedList<>();
@@ -141,6 +186,14 @@ public List<Edge> getDescendantEdgesWithLabel(Vertex vertex, String label) {
             return result;
         }
 
+        /**
+         * Get all vertices that are one edge away, where the edge connecting them has a
+         * particular label.
+         *
+         * @param vertex the vertex to start from
+         * @param edgeLabel the edge label we are looking for
+         * @return a list of adjacent vertices related by edgeLabel
+         */
         public List<Vertex> getAdjacentVerticesByEdgeLabel(Vertex vertex, String edgeLabel) {
             List<Vertex> result = new ArrayList<>();
             vertex.vertices(Direction.OUT, edgeLabel).forEachRemaining(result::add);