org.liquidsite.util.db
Class DatabaseConnector

java.lang.Object
  org.liquidsite.util.db.DatabaseConnector

Direct Known Subclasses:

MySQLDatabaseConnector

public class DatabaseConnector

extends java.lang.Object

A database connector. The database connector manages all connections to the database, pooling resources as desired. By default connection pooling is not used, but is may be activated by modifying the pool size.

Field Summary

static long	DEFAULT_CONNECTION_TIMEOUT The default connection timeout in milliseconds.
static int	DEFAULT_QUERY_TIMEOUT The default query timeout in seconds.

Constructor Summary

DatabaseConnector(java.lang.String url)
Creates a new database connector.

DatabaseConnector(java.lang.String url, java.util.Properties properties)
Creates a new database connector.

Method Summary

DatabaseResults	execute(DatabaseQuery query) Executes a database query or statement.
void	execute(java.io.File file) Executes a set of SQL statements from a file.
DatabaseConnection	getConnection() Returns a database connection.
long	getConnectionTimeout() Returns the database connection expiration timeout.
int	getPoolSize() Returns the maximum database connection pool size.
java.util.Properties	getProperties() Returns the database connector properties.
java.lang.String	getProperty(java.lang.String name) Returns a specified database connector property.
java.lang.String	getUrl() Returns the JDBC database URL.
static void	loadDriver(java.lang.String driver) Loads the specified JDBC database driver.
void	loadFunctions(java.io.File file) Loads a set of database functions.
void	returnConnection(DatabaseConnection con) Disposes of a database connection.
void	setConnectionTimeout(long timeout) Sets the database connection expiration timeout.
void	setPoolSize(int size) Sets the maximum database connection pool size.
void	setProperty(java.lang.String name, java.lang.String value) Sets the specified database connector property.
java.lang.String	toString() Returns a string representation of this object.
void	update() Updates the connection pool.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CONNECTION_TIMEOUT

public static final long DEFAULT_CONNECTION_TIMEOUT

The default connection timeout in milliseconds. By default this is set to 14400000 ms (4 h).

See Also:

Constant Field Values

DEFAULT_QUERY_TIMEOUT

public static final int DEFAULT_QUERY_TIMEOUT

The default query timeout in seconds. By default this is set to 5 seconds.

See Also:

DatabaseConnection.setQueryTimeout(int), Constant Field Values

Constructor Detail

DatabaseConnector

public DatabaseConnector(java.lang.String url)

Creates a new database connector. This connector properties will initially be empty.

Parameters:

url - the JDBC database URL

DatabaseConnector

public DatabaseConnector(java.lang.String url,
                         java.util.Properties properties)

Creates a new database connector.

Parameters:

url - the JDBC database URL

properties - the JDBC database properties

Method Detail

loadDriver

public static void loadDriver(java.lang.String driver)
                       throws DatabaseConnectionException

Loads the specified JDBC database driver. This method must be called once before attempting to connect with the specified driver. Calling this method several times has no effect.

Parameters:

driver - the fully qualified classname

Throws:

DatabaseConnectionException - if the class couldn't be found or loaded correctly

toString

public java.lang.String toString()

Returns a string representation of this object.

Returns:

a string representation of this object

getUrl

public java.lang.String getUrl()

Returns the JDBC database URL.

Returns:

the JDBC database URL

getProperty

public java.lang.String getProperty(java.lang.String name)

Returns a specified database connector property.

Parameters:

name - the property name

Returns:

the property value, or null if not found

getProperties

public java.util.Properties getProperties()

Returns the database connector properties.

Returns:

the database properties

setProperty

public void setProperty(java.lang.String name,
                        java.lang.String value)

Sets the specified database connector property.

Parameters:

name - the property name

value - the property value

getConnectionTimeout

public long getConnectionTimeout()

Returns the database connection expiration timeout. If this value is negative the database connections will never expire.

Returns:

the connection expiration timeout (in milliseconds), or a negative value for unlimited

See Also:

setConnectionTimeout(long), DEFAULT_CONNECTION_TIMEOUT

setConnectionTimeout

public void setConnectionTimeout(long timeout)

Sets the database connection expiration timeout. If this value is negative the database connections will never expire. By modifying this value already open connections may be caused to expire.

Parameters:

timeout - the new connection timeout (in milliseconds), or a negative value for unlimited

See Also:

getConnectionTimeout()

getPoolSize

public int getPoolSize()

Returns the maximum database connection pool size. By default no connection pooling is used, and the pool size is therefore zero (0). A new connection pool is created the first time the setPoolSize() method is called.

Returns:

the database connection pool size

See Also:

setPoolSize(int)

setPoolSize

public void setPoolSize(int size)

Sets the maximum database connection pool size. The first time this method is called, a new database connection pool is created. The pool minimum size and timeout will be set to default values.

Parameters:

size - the new maximum connection pool size

See Also:

getPoolSize()

getConnection

public DatabaseConnection getConnection()
                                 throws DatabaseConnectionException

Returns a database connection. This method will either create a new connection, or return a previous connection from the connection pool (if one exists). All connections returned by this method must be disposed of by calling the returnConnection() method.

Returns:

a database connection

Throws:

DatabaseConnectionException - if a database connection couldn't be established

See Also:

returnConnection(org.liquidsite.util.db.DatabaseConnection)

returnConnection

public void returnConnection(DatabaseConnection con)

Disposes of a database connection. This method will either return the connection to the connection pool, or close the connection, depending on if a pool exists or not.

Parameters:

con - the database connection

See Also:

getConnection()

loadFunctions

public void loadFunctions(java.io.File file)
                   throws java.io.FileNotFoundException,
                          java.io.IOException

Loads a set of database functions. The functions are stored in a normal properties file, with the value being the SQL code.

Parameters:

file - the file containing the functions

Throws:

java.io.FileNotFoundException - if the file couldn't be found

java.io.IOException - if the file couldn't be read properly

update

public void update()
            throws DatabaseConnectionException

Updates the connection pool. This method will step through all available database connections in the pool, removing all broken or timed out connections. The connection pool size may also be adjusted. Note that any call to this method should be made from a background thread, as this method may get stuck waiting for I/O timeouts.

Throws:

DatabaseConnectionException - if a database connection couldn't be established

execute

public DatabaseResults execute(DatabaseQuery query)
                        throws DatabaseConnectionException,
                               DatabaseException

Executes a database query or statement.

Parameters:

query - the database query

Returns:

the database query results, or null for database statements

Throws:

DatabaseConnectionException - if a database connection couldn't be established

DatabaseException - if the query or statement couldn't be executed correctly

execute

public void execute(java.io.File file)
             throws java.io.FileNotFoundException,
                    java.io.IOException,
                    DatabaseConnectionException,
                    DatabaseException

Executes a set of SQL statements from a file. Each SQL statement must be terminated by a ';' character.

Parameters:

file - the file with SQL statements

Throws:

java.io.FileNotFoundException - if the file couldn't be found

java.io.IOException - if the file couldn't be read properly

DatabaseConnectionException - if a database connection couldn't be established

DatabaseException - if some statement couldn't be executed correctly