diff --git a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/DBMigrationEngine.java b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/DBMigrationEngine.java
index 47fc3491f06aca9ff36b71e7d3abe9442c216b50..812fda0a20924eca74f26c779edcf082660f0cc1 100644
--- a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/DBMigrationEngine.java
+++ b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/DBMigrationEngine.java
@@ -44,7 +44,11 @@ public class DBMigrationEngine
private final ISqlScriptExecutor scriptExecutor;
-
+ /**
+ * Creates an instance for the specified DAO factory and SQL script provider.
+ *
+ * @param shouldCreateFromScratch If <code>true</code> the database should be dropped and created from scratch.
+ */
public DBMigrationEngine(IDAOFactory daoFactory, ISqlScriptProvider scriptProvider, boolean shouldCreateFromScratch)
{
adminDAO = daoFactory.getDatabaseDAO();
@@ -54,6 +58,12 @@ public class DBMigrationEngine
this.shouldCreateFromScratch = shouldCreateFromScratch;
}
+ /**
+ * Create or migrate database to the specified version.
+ *
+ * @throws EnvironmentFailureException if creation/migration failed because of some missing scripts or an
+ * inconsistent database.
+ */
public void migrateTo(String version)
{
if (shouldCreateFromScratch)
@@ -66,6 +76,7 @@ public class DBMigrationEngine
return;
}
LogEntry entry = logDAO.getLastEntry();
+ // TODO 2007-06-19, Franz-Josef Elmer: check not null and run status
String databaseVersion = entry.getVersion();
if (version.equals(databaseVersion))
{
diff --git a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/IDAOFactory.java b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/IDAOFactory.java
index 085dbbfefe656681112c45aff87ace9b1e4f3355..cbaf2a4fd496e2637891905051851a6af91e2632 100644
--- a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/IDAOFactory.java
+++ b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/IDAOFactory.java
@@ -23,9 +23,18 @@ package ch.systemsx.cisd.dbmigration;
*/
public interface IDAOFactory
{
+ /**
+ * Returns an Data Access Object for administration of the database.
+ */
public IDatabaseAdminDAO getDatabaseDAO();
+ /**
+ * Returns an executor of SQL scripts.
+ */
public ISqlScriptExecutor getSqlScriptExecutor();
+ /**
+ * Returns the DAO for the database version log.
+ */
public IDatabaseVersionLogDAO getDatabaseVersionLogDAO();
}
diff --git a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/IDatabaseAdminDAO.java b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/IDatabaseAdminDAO.java
index fa4b0b5ffea1a4116d71f8c912ff85ce83d30d39..a68f99884b1cbe2fc335db9e75606ded2520a51e 100644
--- a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/IDatabaseAdminDAO.java
+++ b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/IDatabaseAdminDAO.java
@@ -17,19 +17,34 @@
package ch.systemsx.cisd.dbmigration;
/**
- * Interface for creating/dropping a database.
+ * Interface for administration of a database.
*
* @author Franz-Josef Elmer
*/
public interface IDatabaseAdminDAO
{
+ /**
+ * Returns the owner of the database to be created/dropped.
+ */
public String getOwner();
+ /**
+ * Returns the name of the database to be created/dropped.
+ */
public String getDatabaseName();
+ /**
+ * Creates the owner/user.
+ */
public void createOwner();
+ /**
+ * Creates the database.
+ */
public void createDatabase();
+ /**
+ * Drops the database.
+ */
public void dropDatabase();
}
diff --git a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/IDatabaseVersionLogDAO.java b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/IDatabaseVersionLogDAO.java
index eb67e09dbe76707fb0d9dff74d7b609aff8f6dd4..48323f6cd221e42b839b36502ea0f5e2599d8b6b 100644
--- a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/IDatabaseVersionLogDAO.java
+++ b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/IDatabaseVersionLogDAO.java
@@ -24,16 +24,45 @@ package ch.systemsx.cisd.dbmigration;
*/
public interface IDatabaseVersionLogDAO
{
+ /**
+ * Returns <code>true</code> if the database instance with database version log can be connected.
+ */
public boolean canConnectToDatabase();
+ /**
+ * Creates the table DATABASE_VERSION_LOG.
+ */
public void createTable();
+ /**
+ * Returns the last log entry found.
+ */
public LogEntry getLastEntry();
+ /**
+ * Inserts a new entry into the version log with {@link LogEntry.RunStatus#START}.
+ *
+ * @param version Version of the database after creation/migration.
+ * @param moduleName Name of the module/script to be applied.
+ * @param moduleCode Script code.
+ */
public void logStart(String version, String moduleName, String moduleCode);
+ /**
+ * Update log entry specified by version and module name to {@link LogEntry.RunStatus#SUCCESS}.
+ *
+ * @param version Version of the database after creation/migration.
+ * @param moduleName Name of the successfully applied module/script.
+ */
public void logSuccess(String version, String moduleName);
+ /**
+ * Update log entry specified by version and module name to {@link LogEntry.RunStatus#FAILED}.
+ *
+ * @param version Version of the database after creation/migration.
+ * @param moduleName Name of the failed module/script.
+ * @param runException Exception causing the failure.
+ */
public void logFailure(String version, String moduleName, Throwable runException);
}
diff --git a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/ISqlScriptExecutor.java b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/ISqlScriptExecutor.java
index 965696d5168034f39ecde95f0375749672bc3921..8ad74cd9cf35e739ea94153911bf44d228d94209 100644
--- a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/ISqlScriptExecutor.java
+++ b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/ISqlScriptExecutor.java
@@ -23,5 +23,8 @@ package ch.systemsx.cisd.dbmigration;
*/
public interface ISqlScriptExecutor
{
+ /**
+ * Executes the specified SQL script.
+ */
public void execute(String sqlScript);
}
diff --git a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/LogEntry.java b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/LogEntry.java
index 88fa1fc78e82915a53ee9004ca3446315e9d2d27..6ee226ec71359f4f20d6e7df555a8f7efa09ab57 100644
--- a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/LogEntry.java
+++ b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/LogEntry.java
@@ -19,12 +19,13 @@ package ch.systemsx.cisd.dbmigration;
import java.util.Date;
/**
- * Log entry of DATABASE_VERSION_LOG
+ * Log entry of DATABASE_VERSION_LOG.
*
* @author Franz-Josef Elmer
*/
public class LogEntry
{
+ /** Run status of an entry. */
public enum RunStatus {START, SUCCESS, FAILED, UNKNOWN}
private String version;
diff --git a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/PostgreSQLAdminDAO.java b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/PostgreSQLAdminDAO.java
index 7dd57e508a250faeed085cfd56434e58bd8d56eb..35264138170ac1e5f1891f84ab1a98169e8563e2 100644
--- a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/PostgreSQLAdminDAO.java
+++ b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/PostgreSQLAdminDAO.java
@@ -32,6 +32,13 @@ public class PostgreSQLAdminDAO extends SimpleJdbcDaoSupport implements IDatabas
private final String owner;
private final String database;
+ /**
+ * Creates an instance.
+ *
+ * @param dataSource Data source able to create/drop the specified database.
+ * @param owner Owner to be created if it doesn't exist.
+ * @param database Name of the database.
+ */
public PostgreSQLAdminDAO(DataSource dataSource, String owner, String database)
{
this.owner = owner;
diff --git a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/PostgreSQLDAOFactory.java b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/PostgreSQLDAOFactory.java
index 6be1d8b2c4269ad53625ee204a9c37c52abc3da6..7ddb68ff9f4060a4c42260b11e9f3f7b0d87030c 100644
--- a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/PostgreSQLDAOFactory.java
+++ b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/PostgreSQLDAOFactory.java
@@ -29,6 +29,9 @@ public class PostgreSQLDAOFactory implements IDAOFactory
private final ISqlScriptExecutor sqlScriptExecutor;
private final IDatabaseVersionLogDAO databaseVersionLogDAO;
+ /**
+ * Creates an instance based on the specified configuration context.
+ */
public PostgreSQLDAOFactory(DatabaseConfigurationContext context)
{
databaseDAO = new PostgreSQLAdminDAO(context.getAdminDataSource(), context.getOwner(), context.getDatabaseName());
diff --git a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/SqlScriptProvider.java b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/SqlScriptProvider.java
index 2aaee7136b234f4b214b207df60af72095000feb..07d95de337164bf2338941c93bf9002945f5d2d3 100644
--- a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/SqlScriptProvider.java
+++ b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/SqlScriptProvider.java
@@ -25,7 +25,9 @@ import ch.systemsx.cisd.common.logging.LogFactory;
import ch.systemsx.cisd.common.utilities.FileUtilities;
/**
- * Implementation of {@link ISqlScriptProvider} based on files in classpath or working directory.
+ * Implementation of {@link ISqlScriptProvider} based on files in classpath or working directory. This provider tries
+ * first to load a resource. If this isn't successful the provider tries to look for files relative to the
+ * working directory.
*
* @author Franz-Josef Elmer
*/
@@ -39,23 +41,45 @@ public class SqlScriptProvider implements ISqlScriptProvider
private final String schemaScriptFolder;
private final String dataScriptFolder;
+ /**
+ * Creates an instance for the specified script folders. They are either resource folders or folders
+ * relative to the working directory.
+ *
+ * @param schemaScriptFolder Folder of schema and migration scripts.
+ * @param dataScriptFolder Folder of data scripts.
+ */
public SqlScriptProvider(String schemaScriptFolder, String dataScriptFolder)
{
this.schemaScriptFolder = schemaScriptFolder;
this.dataScriptFolder = dataScriptFolder;
}
+ /**
+ * Returns the data script for the specified version.
+ * The name of the script is expected to be
+ * <pre><data script folder>/<version>/data-<version>.sql</pre>
+ */
public Script getDataScript(String version)
{
return loadScript(dataScriptFolder + "/" + version, "data-" + version + SQL_FILE_TYPE);
}
+ /**
+ * Returns the migration script for the specified versions.
+ * The name of the script is expected to be
+ * <pre><schema script folder>/migration/migration-<fromVersion>-<toVersion>.sql</pre>
+ */
public Script getMigrationScript(String fromVersion, String toVersion)
{
String scriptName = "migration-" + fromVersion + "-" + toVersion + SQL_FILE_TYPE;
return loadScript(schemaScriptFolder + "/migration", scriptName);
}
+ /**
+ * Returns the schmea script for the specified version.
+ * The name of the script is expected to be
+ * <pre><schema script folder>/<version>/schema-<version>.sql</pre>
+ */
public Script getSchemaScript(String version)
{
return loadScript(schemaScriptFolder + "/" + version, "schema-" + version + SQL_FILE_TYPE);