Added some comments and tidy-up SchemaVersionDAO class

Author: hhandoko

src/main/java/com/builtamont/cassandra/migration/internal/dbsupport/SchemaVersionDAO.java

@@ -34,6 +34,9 @@
 
 import static com.datastax.driver.core.querybuilder.QueryBuilder.eq;
 
+/**
+ * Schema migrations table Data Access Object.
+ */
 // TODO: Convert to Kotlin code... Some challenges with Mockito mocking :)
 public class SchemaVersionDAO {
 
@@ -46,14 +49,22 @@ public class SchemaVersionDAO {
     private CachePrepareStatement cachePs;
     private ConsistencyLevel consistencyLevel;
 
+    /**
+     * Creates a new schema version DAO.
+     *
+     * @param session The Cassandra session connection to use to execute the migration.
+     * @param keyspace The Cassandra keyspace to connect to.
+     * @param tableName The Cassandra migration version table name.
+     */
     public SchemaVersionDAO(Session session, Keyspace keyspace, String tableName) {
         this.session = session;
         this.keyspace = keyspace;
         this.tableName = tableName;
         this.cachePs = new CachePrepareStatement(session);
-        //If running on a single host, don't force ConsistencyLevel.ALL
-        this.consistencyLevel =
-                session.getCluster().getMetadata().getAllHosts().size() > 1 ? ConsistencyLevel.ALL :  ConsistencyLevel.ONE;
+
+        // If running on a single host, don't force ConsistencyLevel.ALL
+        boolean isClustered = session.getCluster().getMetadata().getAllHosts().size() > 1;
+        this.consistencyLevel = isClustered ? ConsistencyLevel.ALL : ConsistencyLevel.ONE;
     }
 
     public String getTableName() {
@@ -64,6 +75,9 @@ public Keyspace getKeyspace() {
         return this.keyspace;
     }
 
+    /**
+     * Create schema migration version table if it does not exists.
+     */
     public void createTablesIfNotExist() {
         if (tablesExist()) {
             return;
@@ -97,6 +111,11 @@ public void createTablesIfNotExist() {
         session.execute(statement);
     }
 
+    /**
+     * Check if schema migration version table has already been created.
+     *
+     * @return {@code true} if schema migration version table exists in the keyspace.
+     */
     public boolean tablesExist() {
         boolean schemaVersionTableExists = false;
         boolean schemaVersionCountsTableExists = false;
@@ -135,18 +154,29 @@ public boolean tablesExist() {
         return schemaVersionTableExists && schemaVersionCountsTableExists;
     }
 
+    /**
+     * Add applied migration record into the schema migration version table.
+     *
+     * @param appliedMigration The applied migration.
+     */
     public void addAppliedMigration(AppliedMigration appliedMigration) {
         createTablesIfNotExist();
 
         MigrationVersion version = appliedMigration.getVersion();
 
         int versionRank = calculateVersionRank(version);
         PreparedStatement statement = cachePs.prepare(
-                "INSERT INTO " + keyspace.getName() + "." + tableName +
-                        " (version_rank, installed_rank, version, description, type, script, checksum, installed_on," +
-                        "  installed_by, execution_time, success)" +
-                        " VALUES" +
-                        " (?, ?, ?, ?, ?, ?, ?, dateOf(now()), ?, ?, ?);"
+                "INSERT INTO " + keyspace.getName() + "." + tableName + "(" +
+                        "  version_rank, installed_rank, version," +
+                        "  description, type, script," +
+                        "  checksum, installed_on, installed_by," +
+                        "  execution_time, success" +
+                        ") VALUES (" +
+                        "  ?, ?, ?," +
+                        "  ?, ?, ?," +
+                        "  ?, dateOf(now()), ?," +
+                        "  ?, ?" +
+                        ");"
         );
 
         statement.setConsistencyLevel(this.consistencyLevel);
@@ -166,7 +196,7 @@ public void addAppliedMigration(AppliedMigration appliedMigration) {
     }
 
     /**
-     * Retrieve the applied migrations from the metadata table.
+     * Retrieve the applied migrations from the schema migration version table.
      *
      * @return The applied migrations.
      */
@@ -209,8 +239,8 @@ public List<AppliedMigration> findAppliedMigrations() {
             ));
         }
 
-        //order by version_rank not necessary here as it eventually gets saved in TreeMap that uses natural ordering
-
+        // NOTE: Order by `version_rank` not necessary here, as it eventually gets saved in TreeMap
+        //       that uses natural ordering
         return resultsList;
     }
 
@@ -263,11 +293,16 @@ public List<AppliedMigration> findAppliedMigrations(MigrationType... migrationTy
             }
         }
 
-        //order by version_rank not necessary here as it eventually gets saved in TreeMap that uses natural ordering
-
+        // NOTE: Order by `version_rank` not necessary here, as it eventually gets saved in TreeMap
+        //       that uses natural ordering
         return resultsList;
     }
 
+    /**
+     * Check if the keyspace has applied migrations.
+     *
+     * @return {@code true} if the keyspace has applied migrations.
+     */
     public boolean hasAppliedMigrations() {
         if (!tablesExist()) {
             return false;
@@ -284,6 +319,13 @@ public boolean hasAppliedMigrations() {
         return !filteredMigrations.isEmpty();
     }
 
+    /**
+     * Add a baseline version marker.
+     *
+     * @param baselineVersion The baseline version.
+     * @param baselineDescription the baseline version description.
+     * @param user The user's username executing the baselining.
+     */
     public void addBaselineMarker(final MigrationVersion baselineVersion, final String baselineDescription, final String user) {
         addAppliedMigration(
             new AppliedMigration(
@@ -299,16 +341,28 @@ public void addBaselineMarker(final MigrationVersion baselineVersion, final Stri
         );
     }
 
+    /**
+     * Get the baseline marker's applied migration.
+     *
+     * @return The baseline marker's applied migration.
+     */
     public AppliedMigration getBaselineMarker() {
         List<AppliedMigration> appliedMigrations = findAppliedMigrations(MigrationType.BASELINE);
         return appliedMigrations.isEmpty() ? null : appliedMigrations.get(0);
     }
 
+    /**
+     * Check if schema migration version table has a baseline marker.
+     *
+     * @return {@code true} if the schema migration version table has a baseline marker.
+     */
     public boolean hasBaselineMarker() {
         if (!tablesExist()) {
             return false;
         }
+
         createTablesIfNotExist();
+
         return !findAppliedMigrations(MigrationType.BASELINE).isEmpty();
     }
 
@@ -321,14 +375,19 @@ private int calculateInstalledRank() {
         Statement statement = new SimpleStatement(
                 "UPDATE " + keyspace.getName() + "." + tableName + COUNTS_TABLE_NAME_SUFFIX +
                         " SET count = count + 1" +
-                        "WHERE name = 'installed_rank';");
+                        " WHERE name = 'installed_rank'" +
+                        ";");
+
         session.execute(statement);
+
         Select select = QueryBuilder
                 .select("count")
                 .from(tableName + COUNTS_TABLE_NAME_SUFFIX);
         select.where(eq("name", "installed_rank"));
+
         select.setConsistencyLevel(this.consistencyLevel);
         ResultSet result = session.execute(select);
+
         return (int) result.one().getLong("count");
     }
 
@@ -344,6 +403,7 @@ private int calculateVersionRank(MigrationVersion version) {
                 .column("version")
                 .column("version_rank")
                 .from(keyspace.getName(), tableName);
+
         statement.setConsistencyLevel(this.consistencyLevel);
         ResultSet versionRows = session.execute(statement);
 
@@ -362,7 +422,8 @@ private int calculateVersionRank(MigrationVersion version) {
         PreparedStatement preparedStatement = cachePs.prepare(
                 "UPDATE " + keyspace.getName() + "." + tableName +
                         " SET version_rank = ?" +
-                        " WHERE version = ?;");
+                        " WHERE version = ?" +
+                        ";");
 
         for (int i = 0; i < migrationVersions.size(); i++) {
             if (version.compareTo(migrationVersions.get(i)) < 0) {
@@ -381,6 +442,9 @@ private int calculateVersionRank(MigrationVersion version) {
         return migrationVersions.size() + 1;
     }
 
+    /**
+     * Schema migration (transient) metadata.
+     */
     class MigrationMetaHolder {
         private int versionRank;