From ae6172f80e6ba013de1af87277721e3bfa650cd1 Mon Sep 17 00:00:00 2001
From: Timm Fitschen <t.fitschen@indiscale.com>
Date: Tue, 16 Jun 2020 13:46:54 +0200
Subject: [PATCH] DOC: comments for sql statements

---
 .../backend/implementation/MySQL/MySQLGetAllNames.java   | 1 +
 .../backend/implementation/MySQL/MySQLGetIDByName.java   | 6 ++++++
 .../implementation/MySQL/MySQLInsertEntityDatatype.java  | 9 +++++++++
 .../implementation/MySQL/MySQLRetrieveDatatypes.java     | 6 ++++++
 4 files changed, 22 insertions(+)

diff --git a/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLGetAllNames.java b/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLGetAllNames.java
index be7ff115..060cf9b8 100644
--- a/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLGetAllNames.java
+++ b/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLGetAllNames.java
@@ -18,6 +18,7 @@ public class MySQLGetAllNames extends MySQLTransaction implements GetAllNamesImp
     super(access);
   }
 
+  /** Retrieve tuples (EntityName, EntityRole, ACL) for all entities which have a name. */
   public static final String STMT_GET_ALL_NAMES =
       "SELECT d.value as EntityName, e.role AS EntityRole, a.acl AS ACL "
           + "FROM name_data AS d JOIN entities AS e JOIN entity_acl AS a "
diff --git a/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLGetIDByName.java b/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLGetIDByName.java
index a113020c..e9797640 100644
--- a/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLGetIDByName.java
+++ b/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLGetIDByName.java
@@ -36,11 +36,17 @@ public class MySQLGetIDByName extends MySQLTransaction implements GetIDByNameImp
     super(access);
   }
 
+  /**
+   * Resolves the (primary) name of an entity to an id. This query is not necessarily unique.
+   * Therefore {@link #STMT_AND_ROLE}, {@link #STMT_NOT_ROLE}, and {@link #STMT_LIMIT} can as
+   * additional conditions.
+   */
   public static final String STMT_GET_ID_BY_NAME =
       "Select n.entity_id AS id "
           + "FROM name_data AS n JOIN entities AS e "
           + "ON (n.domain_id=0 AND n.property_id=20 AND e.id = n.entity_id)"
           + "WHERE n.value=?";
+
   public static final String STMT_AND_ROLE = " AND e.role=?";
   public static final String STMT_NOT_ROLE = " AND e.role!='ROLE'";
   public static final String STMT_LIMIT = " LIMIT ";
diff --git a/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLInsertEntityDatatype.java b/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLInsertEntityDatatype.java
index dbc8b957..47671864 100644
--- a/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLInsertEntityDatatype.java
+++ b/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLInsertEntityDatatype.java
@@ -15,10 +15,19 @@ public class MySQLInsertEntityDatatype extends MySQLTransaction
     super(access);
   }
 
+  /**
+   * Inserts atomic data types of properties into the data_type table. Has two parameters, the
+   * property_id and the data type name.
+   */
   public static final String STMT_INSERT_ENTITY_DATATYPE =
       "INSERT INTO data_type (domain_id, entity_id, property_id, datatype) "
           + "SELECT 0, 0, ?, "
           + "( SELECT entity_id FROM name_data WHERE domain_id = 0 AND property_id = 20 AND value = ? LIMIT 1);";
+
+  /**
+   * Inserts collection data types of properties into the data_type table. Has two parameters, the
+   * property_id and the type of collection (e.g. 'LIST').
+   */
   public static final String STMT_INSERT_ENTITY_COLLECTION =
       "INSERT INTO collection_type (domain_id, entity_id, property_id, collection) "
           + "SELECT 0, 0, ?, ?;";
diff --git a/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveDatatypes.java b/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveDatatypes.java
index 91d1e97a..a8e12672 100644
--- a/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveDatatypes.java
+++ b/src/main/java/caosdb/server/database/backend/implementation/MySQL/MySQLRetrieveDatatypes.java
@@ -38,6 +38,12 @@ public class MySQLRetrieveDatatypes extends MySQLTransaction implements Retrieve
     super(access);
   }
 
+  /**
+   * Retrieve (ParentID, ParentName, ParentDescription, ParentRole, ACL) tuple which actually
+   * contains the ID, name, description, role and ACL of the datatype. The misleading names should
+   * be fixed sometimes (TODO) but this also requires to adjust the code below, which uses {@link
+   * DatabaseUtils#parseParentResultSet(ResultSet)}.
+   */
   private static final String STMT_GET_DATATYPE =
       "SELECT id AS ParentID, "
           + "(SELECT value FROM name_data WHERE domain_id = 0 AND entity_ID = e.id AND property_id = 20) AS ParentName, "
-- 
GitLab