org.wandora.modules

Class GenericDatabaseInterface

java.lang.Object

org.wandora.modules.AbstractModule

org.wandora.modules.GenericDatabaseInterface

All Implemented Interfaces:

DatabaseInterface, Module

public class GenericDatabaseInterface
extends AbstractModule
implements DatabaseInterface

A general purpose implementation of the DatabaseInterface using JDBC and thus being able to operate with many different relational databases. The connection details of the JDBC connection are given as module parameters in init with parameter names driver, connectionstring, username and password. These contain, respectively, the full class name of the JDBC driver to use, the connection string used by the driver, the user name and the password.

Author:

olli

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	GenericDatabaseInterface.GenericPreparedDatabaseStatement

Nested classes/interfaces inherited from interface org.wandora.modules.DatabaseInterface

DatabaseInterface.DatabaseConnectionListener, DatabaseInterface.PreparedDatabaseStatement, DatabaseInterface.Row, DatabaseInterface.Rows

Field Summary

Fields

Modifier and Type	Field and Description
protected org.apache.commons.dbcp.BasicDataSource	connectionPool
protected java.lang.String	connectionString
protected java.lang.String	driver
protected ListenerList<DatabaseInterface.DatabaseConnectionListener>	listeners
protected java.lang.String	password
protected java.lang.String	userName

Fields inherited from class org.wandora.modules.AbstractModule

autoStart, isInitialized, isRunning, logging, loggingModule, moduleManager

Constructor Summary

Constructors

Constructor and Description
GenericDatabaseInterface()

Method Summary

Modifier and Type	Method and Description
void	addDatabaseConnectionListener(DatabaseInterface.DatabaseConnectionListener l) Adds a database connection listener that will be notified when a database connection is established or closed.
protected void	fireDatabaseClosed()
protected void	fireDatabaseStarted()
java.lang.String	formatTimestamp(long time) Makes a time stamp value out of a milliseconds time.
java.util.Collection<Module>	getDependencies(ModuleManager manager) Returns all the modules this module depends on.
void	init(ModuleManager manager, java.util.HashMap<java.lang.String,java.lang.Object> settings) Initialises the module.
protected void	initConnectionPool()
java.lang.Object	insertAutoIncrement(java.lang.String query) Inserts a row with an auto increment field and returns the automatically assigned value.
DatabaseInterface.Rows	makeRows(java.sql.ResultSet rs)
DatabaseInterface.PreparedDatabaseStatement	prepareStatement(java.lang.String query) Prepares a statement for later execution.
DatabaseInterface.Rows	query(java.lang.String query) Executes a database query and returns the results.
void	removeDatabaseConnectionListener(DatabaseInterface.DatabaseConnectionListener l) Removes a database connection listener.
java.lang.String	sqlEscape(java.lang.String str) Escapes a string so that it can then be safely used as part of a query.
java.lang.String	sqlEscapeLen(java.lang.String str, int length) Escapes a string so that it can then be safely used as part of a query with a maximum length of the returned string.
void	start(ModuleManager manager) Starts the module.
void	stop(ModuleManager manager) Stops the module.
int	update(java.lang.String query) Executes an update statement.
int	update(java.lang.String query, DatabaseInterface.Rows[] generatedKeys)

Methods inherited from class org.wandora.modules.AbstractModule

isInitialized, isRunning, requireLogging, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.wandora.modules.Module

isInitialized, isRunning

Field Detail

listeners

protected ListenerList<DatabaseInterface.DatabaseConnectionListener> listeners

driver

protected java.lang.String driver

connectionString

protected java.lang.String connectionString

userName

protected java.lang.String userName

password

protected java.lang.String password

connectionPool

protected org.apache.commons.dbcp.BasicDataSource connectionPool

Constructor Detail

GenericDatabaseInterface

public GenericDatabaseInterface()

Method Detail

sqlEscape

public java.lang.String sqlEscape(java.lang.String str)

Description copied from interface: DatabaseInterface

Escapes a string so that it can then be safely used as part of a query.

Specified by:

sqlEscape in interface DatabaseInterface

Parameters:

str - The string to be escaped.

Returns:

The escaped string.

sqlEscapeLen

public java.lang.String sqlEscapeLen(java.lang.String str,
                                     int length)

Description copied from interface: DatabaseInterface

Escapes a string so that it can then be safely used as part of a query with a maximum length of the returned string. If the input value is longer than the maximum length, it will be truncated to fit the length limit.

Specified by:

sqlEscapeLen in interface DatabaseInterface

Parameters:

str - The string to be escaped.

length - The maximum length.

Returns:

The escaped and possibly truncated string.

formatTimestamp

public java.lang.String formatTimestamp(long time)

Description copied from interface: DatabaseInterface

Makes a time stamp value out of a milliseconds time.

Specified by:

formatTimestamp in interface DatabaseInterface

Parameters:

time - The time in milliseconds.

Returns:

The time stamp as a string.

makeRows

public DatabaseInterface.Rows makeRows(java.sql.ResultSet rs)
                                throws java.sql.SQLException

Throws:

java.sql.SQLException

query

public DatabaseInterface.Rows query(java.lang.String query)
                             throws java.sql.SQLException

Description copied from interface: DatabaseInterface

Executes a database query and returns the results.

Specified by:

query in interface DatabaseInterface

Parameters:

query - The query to execute.

Returns:

The results of the query as a Rows object (essentially an ArrayList).

Throws:

java.sql.SQLException

update

public int update(java.lang.String query)
           throws java.sql.SQLException

Description copied from interface: DatabaseInterface

Executes an update statement.

Specified by:

update in interface DatabaseInterface

Parameters:

query - The update statement to execute.

Returns:

The number of rows affected by the statement.

Throws:

java.sql.SQLException

update

public int update(java.lang.String query,
                  DatabaseInterface.Rows[] generatedKeys)
           throws java.sql.SQLException

Throws:

java.sql.SQLException

insertAutoIncrement

public java.lang.Object insertAutoIncrement(java.lang.String query)
                                     throws java.sql.SQLException

Description copied from interface: DatabaseInterface

Inserts a row with an auto increment field and returns the automatically assigned value.

Specified by:

insertAutoIncrement in interface DatabaseInterface

Parameters:

query - The insert statement.

Returns:

The automatically assigned incremented value.

Throws:

java.sql.SQLException

initConnectionPool

protected void initConnectionPool()

init

public void init(ModuleManager manager,
                 java.util.HashMap<java.lang.String,java.lang.Object> settings)
          throws ModuleException

Description copied from interface: Module

Initialises the module. After constructor, this is the first method called in the life cycle of a module. It should not perform anything time consuming or anything with notable outside side effects. It should only read the parameters and initialise the module so that it can later be started. Note that a module being initialised doesn't mean that it necessarily will ever be started.

A ModuleException may be thrown if something vital is missing from the parameters or they are not sensible. In some cases you may not want to throw an exception even if vital initialisation information is missing. If, for example, it is possible that the module is initialised in some other way between the init and the start method calls. A ModuleException may also be thrown at the start method if the module is still not initialised.

Specified by:

init in interface Module

Overrides:

init in class AbstractModule

Parameters:

manager - The module manager handling this module. You may keep a reference to it if needed.

Throws:

ModuleException

getDependencies

public java.util.Collection<Module> getDependencies(ModuleManager manager)
                                             throws ModuleException

Description copied from interface: Module

Returns all the modules this module depends on. This method will be called after init and the dependencies are allowed to depend on the parameters passed to init. The modules that this module depends on must be returned as a collection. In addition, if any required module is not present, a MissingDependencyException should be thrown. Typically you will use the requireModule and optionalModule methods of the manager to make sure that the modules exist and add them to the collection. requireModule will automatically throw the exception too if the module is not found whereas optionalModule does not.

Specified by:

getDependencies in interface Module

Overrides:

getDependencies in class AbstractModule

Parameters:

manager - The module manager handling this module.

Returns:

A collection of modules this module depends on.

Throws:

ModuleException

start

public void start(ModuleManager manager)
           throws ModuleException

Description copied from interface: Module

Starts the module. This will be called after init and getDependencies and signals that the module should now begin to perform whatever it was designed to do. This method call however should not block for long, so any time consuming tasks should be started in their own threads. You will typically get references to the required modules again in start using the findModule method of the manager and then store those references to instance variables for later use. You may throw a ModuleException if the module is not in a state where it can be started or it immediately becomes obvious that it cannot be started with the provided settings.

Specified by:

start in interface Module

Overrides:

start in class AbstractModule

Parameters:

manager - The module manager handling this module.

Throws:

ModuleException

stop

public void stop(ModuleManager manager)

Description copied from interface: Module

Stops the module. Should stop all threads used by the module, free any large data structures and perform other cleanup. It is possible that the module will be started again later with a start method call (and foregoing init and getDependencies calls). The module should be left in a state where this is possible.

Specified by:

stop in interface Module

Overrides:

stop in class AbstractModule

Parameters:

manager - The module manager handling this module.

prepareStatement

public DatabaseInterface.PreparedDatabaseStatement prepareStatement(java.lang.String query)
                                                             throws java.sql.SQLException

Description copied from interface: DatabaseInterface

Prepares a statement for later execution.

Specified by:

prepareStatement in interface DatabaseInterface

Parameters:

query - The statement to prepare.

Returns:

A PreparedDatabaseStatement object that can be ran later.

Throws:

java.sql.SQLException

addDatabaseConnectionListener

public void addDatabaseConnectionListener(DatabaseInterface.DatabaseConnectionListener l)

Description copied from interface: DatabaseInterface

Adds a database connection listener that will be notified when a database connection is established or closed.

Specified by:

addDatabaseConnectionListener in interface DatabaseInterface

removeDatabaseConnectionListener

public void removeDatabaseConnectionListener(DatabaseInterface.DatabaseConnectionListener l)

Description copied from interface: DatabaseInterface

Removes a database connection listener.

Specified by:

removeDatabaseConnectionListener in interface DatabaseInterface

fireDatabaseStarted

protected void fireDatabaseStarted()

fireDatabaseClosed

protected void fireDatabaseClosed()