TST und DOC

patches/patch20200710-3.0.0-rc2/versioning.sql

@@ -294,95 +294,5 @@ CREATE TABLE archive_entities (
 ) ENGINE=InnoDB;
 
 
-delimiter //
-
-DROP PROCEDURE IF EXISTS set_transaction //
-CREATE PROCEDURE set_transaction(
-    srid VARBINARY(255),
-    username VARCHAR(255),
-    realm VARCHAR(255),
-    seconds BIGINT UNSIGNED,
-    nanos INT(10) UNSIGNED)
-BEGIN
-
-    SET @SRID = srid;
-    INSERT INTO transactions (srid, username, realm, seconds, nanos)
-        VALUES (srid, username, realm, seconds, nanos);
-END //
-
-
-DROP PROCEDURE IF EXISTS setFileProperties //
-CREATE PROCEDURE setFileProperties (
-    in EntityID INT UNSIGNED,
-    in FilePath TEXT,
-    in FileSize BIGINT UNSIGNED,
-    in FileHash VARCHAR(255)
-)
-BEGIN
-    DECLARE IVersion INT UNSIGNED DEFAULT NULL;
-    IF is_feature_config("ENTITY_VERSIONING", "ENABLED") THEN
-        SELECT max(e._iversion) INTO IVersion
-            FROM entity_version AS e
-            WHERE e.entity_id = EntityID;
-
-        INSERT INTO archive_files (file_id, path, size, hash,
-                _iversion)
-            SELECT file_id, path, size, hash, IVersion AS _iversion
-            FROM files
-            WHERE file_id = EntityID;
-    END IF;
-
-    DELETE FROM files WHERE file_id = EntityID;
-
-    IF FilePath IS NOT NULL THEN
-        INSERT INTO files (file_id, path, size, hash)
-            VALUES (EntityID, FilePath, FileSize, unhex(FileHash));
-    END IF;
-
-END //
-
-
-DROP PROCEDURE IF EXISTS retrieveQueryTemplateDef //
-CREATE PROCEDURE retrieveQueryTemplateDef (
-    in EntityID INT UNSIGNED,
-    in Version VARBINARY(255))
-retrieveQueryTemplateDefBody: BEGIN
-
-    DECLARE IVersion INT UNSIGNED DEFAULT NULL;
-    DECLARE IsHead BOOLEAN DEFAULT TRUE;
-
-    IF is_feature_config("ENTITY_VERSIONING", "ENABLED") THEN
-        IF Version IS NOT NULL THEN
-            SELECT get_head_version(EntityID) = Version INTO IsHead;
-        END IF;
-
-        IF IsHead IS FALSE THEN
-            SELECT e._iversion INTO IVersion
-                FROM entity_version as e
-                WHERE e.entity_id = EntityID
-                AND e.version = Version;
-
-            IF IVersion IS NULL THEN
-                -- RETURN EARLY - Version does not exist.
-                LEAVE retrieveQueryTemplateDefBody;
-            END IF;
-
-            SELECT definition
-            FROM archive_query_template_def
-            WHERE id = EntityID
-            AND _iversion = IVersion;
-
-            LEAVE retrieveQueryTemplateDefBody;
-        END IF;
-    END IF;
-
-    SELECT definition
-    FROM query_template_def
-    WHERE id = EntityID;
-
-END //
-
-
-delimiter ;
 
 INSERT INTO feature_config (_key, _value) VALUES ("ENTITY_VERSIONING", "ENABLED");

procedures/entityVersioning.sql

@@ -22,6 +22,24 @@
 DROP PROCEDURE IF EXISTS db_2_0.insert_single_child_version;
 delimiter //
 
+/**
+ * Creates a new version record in the `entity_version` table.
+ *
+ * Parameters
+ * ----------
+ * EntityID
+ *   The id of the versioned entity.
+ * Hash
+ *   A hash of the entity. This is currently not implemented properly and only
+ *   there for future use.
+ * Version
+ *   The id of the entity version.
+ * Parent
+ *   The primary parent version's id.
+ * Transaction
+ *   The id of the transaction which created this entity version (by inserting
+ *   or updating an entity).
+ */
 CREATE PROCEDURE db_2_0.insert_single_child_version(
     in EntityID INT UNSIGNED,
     in Hash VARBINARY(255),
@@ -66,6 +84,15 @@ END;
 //
 
 DROP PROCEDURE IF EXISTS db_2_0.delete_all_entity_versions //
+
+/**
+ * Remove all records in the entity_version table for the given entity.
+ *
+ * Parameters
+ * ----------
+ * EntityID
+ *   The id of the versioned entity.
+ */
 CREATE PROCEDURE db_2_0.delete_all_entity_versions(
     in EntityID INT UNSIGNED)
 BEGIN
@@ -76,6 +103,21 @@ END;
 //
 
 DROP FUNCTION IF EXISTS db_2_0.get_iversion //
+
+/**
+ * Get the internal version id (an integer) of the (API-)version id.
+ *
+ * Parameters
+ * ----------
+ * EntityID
+ *   The entity's id.
+ * Version
+ *   The (official, externally used) version id.
+ *
+ * Returns
+ * -------
+ * The internal version id.
+ */
 CREATE FUNCTION db_2_0.get_iversion(
     EntityID INT UNSIGNED,
     Version VARBINARY(255))
@@ -93,9 +135,24 @@ END;
 
 
 DROP FUNCTION IF EXISTS db_2_0.get_primary_parent_version //
+
+/**
+ * Get the version id of the primary parent of a version.
+ *
+ * Parameters
+ * ----------
+ * EntityID
+ *   The entity id.
+ * Version
+ *   The version id.
+ *
+ * Returns
+ * -------
+ * The id of the given version's primary parent version.
+ */
 CREATE FUNCTION db_2_0.get_primary_parent_version(
-    d INT UNSIGNED,
-    v VARBINARY(255))
+    EntityID INT UNSIGNED,
+    Version VARBINARY(255))
 RETURNS VARBINARY(255)
 READS SQL DATA
 BEGIN
@@ -105,14 +162,29 @@ BEGIN
             INNER JOIN entity_version as p
             ON (e._ipparent = p._iversion
                 AND e.entity_id = p.entity_id)
-            WHERE e.entity_id = d
-                AND e.version = v
+            WHERE e.entity_id = EntityID
+                AND e.version = Version
         );
 END;
 //
 
 
 DROP FUNCTION IF EXISTS db_2_0.get_version_timestamp //
+/**
+ * Get the timestamp of a version by retrieving the timestamp of the
+ * transaction which created the version.
+ *
+ * Parameters
+ * ----------
+ * EntityID
+ *   The entity id.
+ * Version
+ *   The version id.
+ *
+ * Returns
+ * -------
+ * The versions' timestamp in <seconds-since-epoch>.<nanoseconds> format.
+ */
 CREATE FUNCTION db_2_0.get_version_timestamp(
     EntityID INT UNSIGNED,
     Version VARBINARY(255))
@@ -131,6 +203,19 @@ END;
 //
 
 DROP FUNCTION IF EXISTS db_2_0.get_head_version //
+
+/**
+ * Get the version id of the HEAD of an entity.
+ *
+ * Parameters
+ * ----------
+ * EntityID
+ *   The entity id.
+ *
+ * Returns
+ * -------
+ * The version id of the HEAD.
+ */
 CREATE FUNCTION db_2_0.get_head_version(
     EntityID INT UNSIGNED)
 RETURNS VARBINARY(255)
@@ -141,17 +226,35 @@ END;
 //
 
 
--- This implementation assumes that the distance from the head equals the
--- difference between the _iversion numbers. This will not be correct anymore,
--- as soon as branches may split and merge. Then, an tree-walk will be
--- necessary, traversing the primary parents (_pparent), will be necessary.
 DROP FUNCTION IF EXISTS db_2_0.get_head_relative //
+
+/**
+ * Get the id of a version which is specified relative to the HEAD of an
+ * entity.
+ *
+ * Parameters
+ * ----------
+ * EntityID
+ *   The entity id.
+ * Offset
+ *   Distance in the sequence of primary parents of the entity. E.g. `0` is the
+ *   HEAD itself. `1` is the primary parent of the HEAD. `2` is the primary
+ *   parent of the primary parent of the HEAD, and so on.
+ *
+ * Returns
+ * -------
+ * The version id of the HEAD.
+ */
 CREATE FUNCTION db_2_0.get_head_relative(
     EntityID INT UNSIGNED,
     Offset INT UNSIGNED)
 RETURNS VARBINARY(255)
 READS SQL DATA
 BEGIN
+    -- This implementation assumes that the distance from the head equals the
+    -- difference between the _iversion numbers. This will not be correct anymore,
+    -- as soon as branches may split and merge. Then, an tree-walk will be
+    -- necessary, traversing the primary parents (_pparent), will be necessary.
     RETURN (
         SELECT e.version
             FROM entity_version AS e
@@ -163,6 +266,20 @@ END;
 //
 
 DROP FUNCTION IF EXISTS db_2_0._get_version //
+/**
+ * The inverse function of get_iversion. Resolves the version id.
+ *
+ * Parameters
+ * ----------
+ * EntityID
+ *   The entity id.
+ * IVersion
+ *   Internal version id (integer).
+ *
+ * Returns
+ * -------
+ * The version id.
+ */
 CREATE FUNCTION db_2_0._get_version(
     EntityID INT UNSIGNED,
     IVersion INT UNSIGNED)
@@ -178,6 +295,19 @@ END;
 //
 
 DROP PROCEDURE IF EXISTS db_2_0.get_version_history //
+
+/**
+ * Select all version information of an entity.
+ *
+ * Parameters
+ * ----------
+ * EntityID
+ *   The entity id.
+ *
+ * Selects
+ * -------
+ * Tuples (child, parent, child_seconds, child_nanos). child and parent are version ids.
+ */
 CREATE PROCEDURE db_2_0.get_version_history(
     in EntityID INT UNSIGNED)
 BEGIN
@@ -194,7 +324,7 @@ BEGIN
 
     -- TODO This first SELECT statement is necessary because the second one
     -- does not return the root. However, this should be doable in one go with
-    -- a left join.
+    -- a left join instead of an inner join(?).
 
     -- retrieve branches
     UNION SELECT c.version AS child,
@@ -212,5 +342,145 @@ END;
 //
 
 
+DROP PROCEDURE IF EXISTS set_transaction //
+/**
+ * Called when a new transaction begins. Inserts the transaction metadata into
+ * the transactions table.
+ *
+ * Parameters
+ * ----------
+ * srid
+ *   The server-generated Server Request ID.
+ * username
+ *   The username of the subject who/which is responsible for the transaction.
+ * realm
+ *   The realm of the subject.
+ * seconds
+ *   Unix timestamp (seconds).
+ * nanos
+ *   Nanoseconds precision for the timestamp.
+ */
+CREATE PROCEDURE set_transaction(
+    srid VARBINARY(255),
+    username VARCHAR(255),
+    realm VARCHAR(255),
+    seconds BIGINT UNSIGNED,
+    nanos INT(10) UNSIGNED)
+BEGIN
+
+    SET @SRID = srid;
+    INSERT INTO transactions (srid, username, realm, seconds, nanos)
+        VALUES (srid, username, realm, seconds, nanos);
+END //
+
+
+
+DROP PROCEDURE IF EXISTS setFileProperties //
+/**
+ * Insert/Update file properties.
+ *
+ * If ENTITY_VERSIONING is enabled the old file properties are moved to
+ * `archive_files`.
+ *
+ * Parameters
+ * ----------
+ * EntityID
+ *   The file's id.
+ * FilePath
+ *   Path of the file in the internal file system.
+ * FileSize
+ *   Size of the file in bytes.
+ * FileHash
+ *   A Sha512 Hash of the file.
+ */
+CREATE PROCEDURE setFileProperties (
+    in EntityID INT UNSIGNED,
+    in FilePath TEXT,
+    in FileSize BIGINT UNSIGNED,
+    in FileHash VARCHAR(255)
+)
+BEGIN
+    DECLARE IVersion INT UNSIGNED DEFAULT NULL;
+    IF is_feature_config("ENTITY_VERSIONING", "ENABLED") THEN
+        SELECT max(e._iversion) INTO IVersion
+            FROM entity_version AS e
+            WHERE e.entity_id = EntityID;
+
+        INSERT INTO archive_files (file_id, path, size, hash,
+                _iversion)
+            SELECT file_id, path, size, hash, IVersion AS _iversion
+            FROM files
+            WHERE file_id = EntityID;
+    END IF;
+
+    DELETE FROM files WHERE file_id = EntityID;
+
+    IF FilePath IS NOT NULL THEN
+        INSERT INTO files (file_id, path, size, hash)
+            VALUES (EntityID, FilePath, FileSize, unhex(FileHash));
+    END IF;
+
+END //
+
+
+DROP PROCEDURE IF EXISTS retrieveQueryTemplateDef //
+
+/**
+ * Insert/Update file properties.
+ *
+ * If ENTITY_VERSIONING is enabled the old file properties are moved to
+ * `archive_files`.
+ *
+ * Parameters
+ * ----------
+ * EntityID
+ *   The QueryTemplate's id.
+ * Version
+ *   The QueryTemplate's version's id.
+ *
+ * Returns
+ * -------
+ * Tuple (definition). A CQL query string (-fragment) which defines this
+ * QueryTemplate.
+ */
+CREATE PROCEDURE retrieveQueryTemplateDef (
+    in EntityID INT UNSIGNED,
+    in Version VARBINARY(255))
+retrieveQueryTemplateDefBody: BEGIN
+
+    DECLARE IVersion INT UNSIGNED DEFAULT NULL;
+    DECLARE IsHead BOOLEAN DEFAULT TRUE;
+
+    IF is_feature_config("ENTITY_VERSIONING", "ENABLED") THEN
+        IF Version IS NOT NULL THEN
+            SELECT get_head_version(EntityID) = Version INTO IsHead;
+        END IF;
+
+        IF IsHead IS FALSE THEN
+            SELECT e._iversion INTO IVersion
+                FROM entity_version as e
+                WHERE e.entity_id = EntityID
+                AND e.version = Version;
+
+            IF IVersion IS NULL THEN
+                -- RETURN EARLY - Version does not exist.
+                LEAVE retrieveQueryTemplateDefBody;
+            END IF;
+
+            SELECT definition
+            FROM archive_query_template_def
+            WHERE id = EntityID
+            AND _iversion = IVersion;
+
+            LEAVE retrieveQueryTemplateDefBody;
+        END IF;
+    END IF;
+
+    SELECT definition
+    FROM query_template_def
+    WHERE id = EntityID;
+
+END //
+
 
 delimiter ;

tests/test_autotap.sql

@@ -2595,13 +2595,6 @@ SELECT tap.procedure_is_deterministic('_caosdb_schema_unit_tests','initBackRefer
 SELECT tap.procedure_security_type_is('_caosdb_schema_unit_tests','initBackReference','DEFINER','');
 SELECT tap.procedure_sql_data_access_is('_caosdb_schema_unit_tests','initBackReference','CONTAINS SQL','');
 
--- PROCEDURES _caosdb_schema_unit_tests.getFile
-
-SELECT tap.has_procedure('_caosdb_schema_unit_tests','getFile','');
-SELECT tap.procedure_is_deterministic('_caosdb_schema_unit_tests','getFile','NO','');
-SELECT tap.procedure_security_type_is('_caosdb_schema_unit_tests','getFile','DEFINER','');
-SELECT tap.procedure_sql_data_access_is('_caosdb_schema_unit_tests','getFile','CONTAINS SQL','');
-
 -- PROCEDURES _caosdb_schema_unit_tests.initConjunctionFilter
 
 SELECT tap.has_procedure('_caosdb_schema_unit_tests','initConjunctionFilter','');