net.loadbang.sql
Class Database

java.lang.Object
  net.loadbang.sql.Database

Direct Known Subclasses:

HSQL_DB, MySQL_DB

public class Database
extends java.lang.Object

This is a connection to a database, with some intelligence to support callbacks and understand Max Atoms. Subclasses provide access to actual databases (HSQLDB, MySQL, ...). This class is regarded as abstract, although there's no obvious reason why it cannot be used directly; it doesn't make any abstract calls downstream.

Author:

Nick Rothwell, nick@cassiel.com / nick@loadbang.net

Nested Class Summary

static interface

Database.ConnectionCallback<T> An inner interface for connection callbacks.

Constructor Summary

Database(java.lang.String driver, java.lang.String url, java.lang.String user, java.lang.String password)
Constructor: set up a database connector.

Method Summary

void	close() Close the connection.
void	open() Open a connection to the database.
java.util.List<com.cycling74.max.Atom[]>	query(java.lang.String sql) Simple query method, without any prepared statement support, returning the results as a list of Atom arrays.
int	update(java.lang.String sql) Simple update method, without any prepared statement support.
<T> T	withConnection(Database.ConnectionCallback<T> callback) Execute a callback on the connection; useful for prepared statements.

Methods inherited from class java.lang.Object

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

Constructor Detail

Database

public Database(java.lang.String driver,
                java.lang.String url,
                java.lang.String user,
                java.lang.String password)
         throws SetupException

Constructor: set up a database connector.

Throws:

SetupException - if there is some problem finding the JDBC driver

Method Detail

open

public void open()
          throws SetupException

Open a connection to the database.

Throws:

SetupException

update

public int update(java.lang.String sql)
           throws OperationException

Simple update method, without any prepared statement support. Although HSQLDB is thread-safe, this probably doesn't extend to multi-threaded use of a connection - hence, this method is synchronised.

Parameters:

sql - the SQL string

Returns:

the number of rows updated

Throws:

OperationException - on any SQL error

query

public java.util.List<com.cycling74.max.Atom[]> query(java.lang.String sql)
                                               throws OperationException

Simple query method, without any prepared statement support, returning the results as a list of Atom arrays. Although HSQLDB is thread-safe, this probably doesn't extend to multi-threaded use of a connection - hence, this method is synchronised.

Parameters:

sql - the SQL string

Returns:

a List of Atom arrays

Throws:

OperationException - on any SQL error

withConnection

public <T> T withConnection(Database.ConnectionCallback<T> callback)
                 throws OperationException

Execute a callback on the connection; useful for prepared statements. Note: we haven't synchronized this method (since that might break behaviour of the callback), but access to our database connection should be synchronized.

Type Parameters:

T - the type of object to be returned by a query (use Object for update calls)

Parameters:

callback - the callback object

Returns:

the result of the callback body

Throws:

OperationException - if the callback throws this exception

close

public void close()

Close the connection.