au.net.causal.maven.plugins.boxdb.db.BoxDatabase Maven / Gradle / Ivy
Show all versions of boxdb-maven-plugin Show documentation
package au.net.causal.maven.plugins.boxdb.db;
import java.io.IOException;
import java.io.Reader;
import java.net.URL;
import java.nio.file.Path;
import java.sql.Connection;
import java.sql.SQLException;
import java.time.Duration;
import java.util.concurrent.TimeoutException;
/**
* A database that runs in a container.
*/
public interface BoxDatabase
{
/**
* @return true if the container exists, false if not.
*
* @throws BoxDatabaseException if an error occurs.
*/
public boolean exists()
throws BoxDatabaseException;
/**
* @return true if the container exists and is currently running.
*
* @throws BoxDatabaseException if an error occurs.
*/
public boolean isRunning()
throws BoxDatabaseException;
/**
* Starts an already-existing container.
*
* @throws BoxDatabaseException if an error occurs.
*/
public void start()
throws BoxDatabaseException;
/**
* Stops a running container.
*
* @throws BoxDatabaseException if an error occurs.
*/
public void stop()
throws BoxDatabaseException;
/**
* Creates a container and starts it.
*
* @throws BoxDatabaseException if an error occurs.
*/
public void createAndStart()
throws BoxDatabaseException;
/**
* Deletes the container. Container must be stopped.
*
* @throws BoxDatabaseException if an error occurs.
*/
public void delete()
throws BoxDatabaseException;
/**
* Deletes any images for the box database. This clears out image caches and cleans up as much as possible.
* No containers must exist and can be running for this database.
*
* @throws BoxDatabaseException if an error occurs.
*/
public void deleteImage()
throws BoxDatabaseException;
/**
* @param targetDatabase whether to connect as admin user or database user. Admin target is typically
* used for creating databases, database target is for DDL.
*
* @return the JDBC URL to use to connect to the database.
*
* @throws BoxDatabaseException if an error occurs.
*/
public JdbcConnectionInfo jdbcConnectionInfo(DatabaseTarget targetDatabase)
throws BoxDatabaseException;
/**
* Blocks until the database has completely started up.
*
* @param maxTimeToWait the maximum time to wait. If null, potentially wait forever.
*
* @throws TimeoutException if the maximum time to wait is exceeded while waiting for startup.
* @throws BoxDatabaseException if another error occurs.
*/
public void waitUntilStarted(Duration maxTimeToWait)
throws TimeoutException, BoxDatabaseException;
/**
* Creates a JDBC connection to the database.
*
* @param targetDatabase the database target.
*
* @return a JDBC connection.
*
* @throws IOException if an I/O error occurs.
* @throws SQLException if an error occurs establishing the connection.
* @throws BoxDatabaseException if another error occurs.
*/
public Connection createJdbcConnection(DatabaseTarget targetDatabase)
throws SQLException, BoxDatabaseException, IOException;
/**
* Executes a script using JDBC.
*
*
* Scripts run via JDBC may execute a lot faster than native scripts, but may be limited in
* functionality.
*
* @param scriptReader the reader to read the JDBC script.
* @param targetDatabase the database to run the script against.
*
* @throws IOException if an I/O error occurs reading the script.
* @throws SQLException if there is an error executing the script.
* @throws BoxDatabaseException if another error occurs.
*/
public void executeJdbcScript(Reader scriptReader, DatabaseTarget targetDatabase)
throws IOException, SQLException, BoxDatabaseException;
/**
* Executes a SQL script using the database's native script executor.
*
* @param script a URL of the script to execute.
* @param targetDatabase the database to run the script against.
* @param timeout the maximum amount of time to allow to run the script. Recommendation only.
*
* @throws IOException if an I/O error occurs reading the script.
* @throws SQLException if there is an error executing the script.
* @throws BoxDatabaseException if another error occurs.
*/
public void executeScript(URL script, DatabaseTarget targetDatabase, Duration timeout)
throws IOException, SQLException, BoxDatabaseException;
/**
* Executes a SQL script read from a reader using the database's native script executor.
*
* @param scriptReader the reader to read the SQL script.
* @param targetDatabase the database to run the script against.
* @param timeout the maximum amount of time to allow to run the script. Recommendation only.
*
* @throws IOException if an I/O error occurs reading the script.
* @throws SQLException if there is an error executing the script.
* @throws BoxDatabaseException if another error occurs.
*/
public void executeScript(Reader scriptReader, DatabaseTarget targetDatabase, Duration timeout)
throws IOException, SQLException, BoxDatabaseException;
/**
* Executes a SQL command using the database's native script executor..
*
* @param sql the SQL command to execute.
* @param targetDatabase the database to run the script against.
* @param timeout the maximum amount of time to allow to run the script. Recommendation only.
*
* @throws IOException if an I/O error occurs with the script. Might occur if saving the script to temp directory.
* @throws SQLException if an error occurs executing the script.
* @throws BoxDatabaseException if another error occurs.
*/
public void executeSql(String sql, DatabaseTarget targetDatabase, Duration timeout)
throws IOException, SQLException, BoxDatabaseException;
/**
* @return the name of the container running the database.
*/
public String getName();
/**
* Creates and sets up the database so that the configuration's {@linkplain BoxConfiguration#getDatabaseName() database name},
* {@linkplain BoxConfiguration#getDatabaseUser() user name} and {@linkplain BoxConfiguration#getDatabasePassword() password}
* are set up.
*
* @throws IOException if an I/O error occurs reading scripts.
* @throws SQLException if a SQL execution error occurs.
* @throws BoxDatabaseException if another error occurs.
*/
public void configureNewDatabase()
throws IOException, SQLException, BoxDatabaseException;
/**
* @return JDBC driver information for the database.
*
* @throws BoxDatabaseException if an error occurs.
*/
public JdbcDriverInfo jdbcDriverInfo()
throws BoxDatabaseException;
/**
* Backs up the database to file.
*
* @param backupFile the file to save the backup to.
* @param backupFileTypeHint hint for the output format.
*
* @throws BoxDatabaseException if a database connectivity error occurs.
* @throws IOException if an I/O error occurs writing to the backup file.
* @throws SQLException if a backup execution error occurs.
*/
public void backup(Path backupFile, BackupFileTypeHint backupFileTypeHint)
throws BoxDatabaseException, IOException, SQLException;
/**
* Restore database from backup file. All existing data in the database is deleted.
*
* @param backupFile the backup file to restore.
*
* @throws BoxDatabaseException if a database connectivity error occurs.
* @throws IOException if an I/O error occurs reading from the backup file.
* @throws SQLException if a restore execution error occurs.
*/
public void restore(Path backupFile)
throws BoxDatabaseException, IOException, SQLException;
/**
* Restore database from a URL resource. All existing data in the database is deleted.
*
* @param backupResource the URL resource of the backup file to restore from.
*
* @throws BoxDatabaseException if a database connectivity error occurs.
* @throws IOException if an I/O error occurs reading from the backup file.
* @throws SQLException if a restore execution error occurs.
*/
public void restore(URL backupResource)
throws BoxDatabaseException, IOException, SQLException;
}