From f8af05bc5318faa7c3c78e63c1cd0c827091b49e Mon Sep 17 00:00:00 2001
From: felmer <felmer>
Date: Tue, 19 Jun 2007 11:47:56 +0000
Subject: [PATCH] LMS-34 Javadoc added
SVN: 586
---
.../cisd/dbmigration/DBMigrationEngine.java | 13 ++++++++-
.../cisd/dbmigration/IDAOFactory.java | 9 ++++++
.../cisd/dbmigration/IDatabaseAdminDAO.java | 17 ++++++++++-
.../dbmigration/IDatabaseVersionLogDAO.java | 29 +++++++++++++++++++
.../cisd/dbmigration/ISqlScriptExecutor.java | 3 ++
.../systemsx/cisd/dbmigration/LogEntry.java | 3 +-
.../cisd/dbmigration/PostgreSQLAdminDAO.java | 7 +++++
.../dbmigration/PostgreSQLDAOFactory.java | 3 ++
.../cisd/dbmigration/SqlScriptProvider.java | 26 ++++++++++++++++-
9 files changed, 106 insertions(+), 4 deletions(-)
diff --git a/dbmigration/source/java/ch/systemsx/cisd/dbmigration/DBMigrationEngine.java b/dbmigration/source/java/ch/systemsx/cisd/dbmigration/DBMigrationEngine.java
index 47fc3491f06..812fda0a209 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 085dbbfefe6..cbaf2a4fd49 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 fa4b0b5ffea..a68f99884b1 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 eb67e09dbe7..48323f6cd22 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 965696d5168..8ad74cd9cf3 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 88fa1fc78e8..6ee226ec713 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 7dd57e508a2..35264138170 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 6be1d8b2c42..7ddb68ff9f4 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 2aaee7136b2..07d95de3371 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);
--
GitLab