net.sourceforge.jdbdump.connect
Class DatabaseConnector

java.lang.Object
  net.sourceforge.jdbdump.connect.DatabaseConnector

Direct Known Subclasses:

MysqlConnector, PostgresqlConnector

public abstract class DatabaseConnector
extends java.lang.Object

A DatabaseConnector is an object handling connection to the database which will be backed up. It manages the Connection object, performs all queries and updates and creates a Dump object. It is the only point of entry to the database in the system, so no other object has to run any queries, updates, etc.

This is an abstract class, because it is impossible to write a single universal method which will make a complete backup of any possible database. Those parts of the backup which are characteristic only to some database engines will have to be done in specific connectors. A generic DatabaseConnector can only supply default ways of doing some backup parts, because many of them will be identical for most database types.

Connectors are created using a DatabaseConnectorFactory. A dump object uses the connector with which it was created to download the tables' data, so you may disconnect() a connector only when all the work is finished.

Example code:

 DatabaseConnectorFactory factory = DatabaseConnectorFactory.getInstance();
 String[] connectorTypes = factory.listPlugins();
 if (connectorTypes.length > 0) {
     DatabaseConnector connector = factory.createConnector(connectorTypes[0]);
     connector.connect(url, login, pass);
     Dump dump = connector.dump();
     // process the dump and its data...
     connector.disconnect();
 } else {
     // error - no connectors
 }
 

Author:

jsuder

Field Summary

protected java.sql.Connection	connection An object providing direct access to the database through JDBC.
protected java.sql.DatabaseMetaData	meta An object providing access to information about database structure, for example a list of all tables with their attributes, columns, etc.

Constructor Summary

DatabaseConnector()

Method Summary

abstract void	connect(java.lang.String url, java.lang.String user, java.lang.String pass) Opens a connection to the database, using the provided connection data.
protected void	connect(java.lang.String url, java.lang.String user, java.lang.String pass, java.lang.String driver) Opens a connection to the database, using the provided connection data and the specified JDBC driver.
abstract java.lang.String	createURL(DatabaseConnectionData data) Creates a database-specific JDBC connection url (usually, although not always, it has the form: jdbc:dbmstype://host:port/database).
void	disconnect() Closes the database connection.
abstract Dump	dump() Creates a backup of the structure of the entire database.
protected void	dumpColumn(Column column, java.sql.ResultSet rsColumns) Downloads the structure of a single table column from the database.
protected void	dumpTable(Table table) Downloads the structure of a single table from the database.
protected void	dumpTableForeignKeys(Table table) Downloads the table's foreign (imported) keys from the database.
protected void	dumpTablePrimaryKeys(Table table) Downloads the table's primary key from the database.
protected void	dumpTables(Dump dump) Downloads the structure of all tables in the database.
abstract java.lang.String[]	getTableDataLine() Downloads one record of data from the previously initialized table in database.
abstract void	initializeTableData(java.lang.String tableName) Prepares the given table for downloading its data.
static void	printResultSet(java.sql.ResultSet rs) A debugging method used to print the entire result set (all rows, all fields in them, also with field names).
abstract void	restore(Dump dump) Restores the structure of the database from a Dump object loaded from a previously created backup file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

connection

protected java.sql.Connection connection

An object providing direct access to the database through JDBC.

meta

protected java.sql.DatabaseMetaData meta

An object providing access to information about database structure, for example a list of all tables with their attributes, columns, etc.

Constructor Detail

DatabaseConnector

public DatabaseConnector()

Method Detail

connect

public abstract void connect(java.lang.String url,
                             java.lang.String user,
                             java.lang.String pass)
                      throws java.sql.SQLException,
                             java.lang.ClassNotFoundException

Opens a connection to the database, using the provided connection data.

Parameters:

url - a correct connection URL

user - user's login in the database

pass - user's password

Throws:

java.sql.SQLException - if the connection is not possible

java.lang.ClassNotFoundException - if there is a problem with loading a driver

connect

protected void connect(java.lang.String url,
                       java.lang.String user,
                       java.lang.String pass,
                       java.lang.String driver)
                throws java.sql.SQLException,
                       java.lang.ClassNotFoundException

Opens a connection to the database, using the provided connection data and the specified JDBC driver.

Parameters:

url - a correct connection URL

user - user's login in the database

pass - user's password

driver - full name of the JDBC driver class

Throws:

java.sql.SQLException - if the connection is not possible

java.lang.ClassNotFoundException - if there is a problem with loading a driver

disconnect

public void disconnect()

Closes the database connection.

dump

public abstract Dump dump()
                   throws java.sql.SQLException

Creates a backup of the structure of the entire database. It doesn't backup any data - this has to be done after the dump is created, using methods in Table class.

Returns:

a Dump object containing information about database structure

Throws:

java.sql.SQLException - if the backup process is interrupted by a critical error

restore

public abstract void restore(Dump dump)
                      throws java.sql.SQLException

Restores the structure of the database from a Dump object loaded from a previously created backup file. It doesn't restore any data - this has to be done after the dump is restored, using methods in Table class.

Parameters:

dump - a Dump object containing information about database structure

Throws:

java.sql.SQLException - if the restore process is interrupted by a critical error

createURL

public abstract java.lang.String createURL(DatabaseConnectionData data)

Creates a database-specific JDBC connection url (usually, although not always, it has the form: jdbc:dbmstype://host:port/database).

Parameters:

data - an object providing all the data necessary to open the connection

Returns:

a connection url string generated from the data

dumpTables

protected void dumpTables(Dump dump)

Downloads the structure of all tables in the database. This is a helper method which can be used by inheriting connectors in their dump() method, if they don't have any specific way of doing this.

Parameters:

dump - a dump to which the downloaded tables should be added

Throws:

java.sql.SQLException - if the backup process is interrupted by a critical error

dumpTable

protected void dumpTable(Table table)

Downloads the structure of a single table from the database. This is a helper method which can be used by inheriting connectors in their dump() method, if they don't have any specific way of doing this.

Parameters:

table - a chosen table in the dump, to which the downloaded information should be assigned

Throws:

java.sql.SQLException - if the backup process is interrupted by a critical error

dumpTablePrimaryKeys

protected void dumpTablePrimaryKeys(Table table)
                             throws java.sql.SQLException

Downloads the table's primary key from the database. This method is called in dumpTable() after it retrieves all the columns.

The way in which primary keys are specified differs between various database engines, so by default this method does nothing; if a specific DatabaseConnector wants in to work for its kind of database, it must override this method and provide its implementation.

Parameters:

table - a table which should be checked for primary keys

Throws:

java.sql.SQLException - if the backup process is interrupted by a critical error

dumpTableForeignKeys

protected void dumpTableForeignKeys(Table table)
                             throws java.sql.SQLException

Downloads the table's foreign (imported) keys from the database. This method is called in dumpTable() after it retrieves all the columns.

The way in which foreign keys are specified differs between various database engines, so by default this method does nothing; if a specific DatabaseConnector wants in to work for its kind of database, it must override this method and provide its implementation.

Parameters:

table - a table which should be checked for foreign keys

Throws:

java.sql.SQLException - if the backup process is interrupted by a critical error

dumpColumn

protected void dumpColumn(Column column,
                          java.sql.ResultSet rsColumns)
                   throws java.sql.SQLException

Downloads the structure of a single table column from the database. This method is called by dumpTable(). If a specific DatabaseConnector wants to use default dumpTables(), but needs a non-default way of handling columns (if it, for example, needs to handle in a special way some specific data types), it should override this method (the overridden version will be called by dumpTables()).

Parameters:

column - a column which should have its parameters downloaded

rsColumns - a ResultSet returned by DatabaseMetaData.getColumns(), set on this column's record

Throws:

java.sql.SQLException - if the backup process is interrupted by a critical error

printResultSet

public static void printResultSet(java.sql.ResultSet rs)
                           throws java.sql.SQLException

A debugging method used to print the entire result set (all rows, all fields in them, also with field names). It can be used e.g. to check what information can be retrieved from ResultSets returned by various DatabaseMetaData methods.

Parameters:

rs - the ResultSet to be printed

Throws:

java.sql.SQLException - if there is something wrong with the resultset

initializeTableData

public abstract void initializeTableData(java.lang.String tableName)
                                  throws java.sql.SQLException

Prepares the given table for downloading its data. That means, it runs a query like "SELECT * FROM tablename" and stores the received result set.

Parameters:

tableName - name of the table from which data should be downloaded

Throws:

java.sql.SQLException

getTableDataLine

public abstract java.lang.String[] getTableDataLine()
                                             throws java.sql.SQLException

Downloads one record of data from the previously initialized table in database.

Returns:

next record from the table, or null if there are no more records

Throws:

java.sql.SQLException - if data record can't be downloaded because of a connection error or an error in the database