com.googlecode.fascinator.portal.services

Interface DatabaseServices

All Superinterfaces:

java.util.EventListener, org.apache.tapestry5.ioc.services.RegistryShutdownListener

All Known Implementing Classes:

DatabaseServicesImpl

public interface DatabaseServices
extends org.apache.tapestry5.ioc.services.RegistryShutdownListener

Instantiates a database used for persistence of generic data in the scripting layer, and offers utility functions for same. Can be used on multiple levels. - Access the database directly and handle all executions yourself. - Use minimal wrapping methods to handle errors trapping and minor details. - Use top level wrappers to hide all details.

Author:

Greg Pendlebury

Method Summary

Methods

Modifier and Type	Method and Description
void	bindParam(java.sql.PreparedStatement sql, int index, java.lang.Object data) Bind a parameter to a SQL statement.
java.sql.Connection	checkConnection(java.lang.String database) Return a connection to the specified database, failing if it does not exist.
void	delete(java.lang.String db, java.lang.String index, java.lang.String table, java.util.Map<java.lang.String,java.lang.Object> where) Top level wrapper for a delete statement.
void	execute(java.lang.String db, java.lang.String index, java.lang.String sql, java.util.List<java.lang.Object> fields) Top level wrapper to execute simple non-returning SQL, such as create or update statements.
void	free(java.sql.PreparedStatement sql) Free the resources for a prepared statement.
java.sql.Connection	getConnection(java.lang.String database) Return a connection to the specified database.
java.util.List<java.util.Map<java.lang.String,java.lang.String>>	getResults(java.sql.PreparedStatement sql) Parse the results of the query into a basic Java data structure.
void	insert(java.lang.String db, java.lang.String index, java.lang.String table, java.util.Map<java.lang.String,java.lang.Object> fields) Top level wrapper for an insert statement.
java.sql.PreparedStatement	prepare(java.sql.Connection db, java.lang.String index, java.lang.String sql) Prepare and return an SQL statement, filing it under the provided index.
java.util.List<java.util.Map<java.lang.String,java.lang.String>>	select(java.lang.String db, java.lang.String index, java.lang.String sql, java.util.List<java.lang.Object> fields) Top level wrapper for a select statement.

Methods inherited from interface org.apache.tapestry5.ioc.services.RegistryShutdownListener

registryDidShutdown

Method Detail

checkConnection

java.sql.Connection checkConnection(java.lang.String database)
                                    throws java.lang.Exception

Return a connection to the specified database, failing if it does not exist.

Parameters:

database - The name of the database to connect to.

Returns:

Connection The instantiated database connection or NULL.

Throws:

java.lang.Exception - if there is a connection error.

getConnection

java.sql.Connection getConnection(java.lang.String database)
                                  throws java.lang.Exception

Return a connection to the specified database. The database will be created if it does not exist.

Parameters:

database - The name of the database to connect to.

Returns:

Connection The instantiated database connection, NULL if an error occurs.

Throws:

java.lang.Exception - if there is a connection error.

prepare

java.sql.PreparedStatement prepare(java.sql.Connection db,
                                 java.lang.String index,
                                 java.lang.String sql)
                                   throws java.lang.Exception

Prepare and return an SQL statement, filing it under the provided index. Subsequent calls to this function using the same index will return the previously prepared statement.

Parameters:

db - The database connection to use.

index - The index to store the statement under.

sql - The SQL statement to prepare.

Returns:

PreparedStatement The prepared statement.

Throws:

java.lang.Exception - if there is an error.

bindParam

void bindParam(java.sql.PreparedStatement sql,
             int index,
             java.lang.Object data)
               throws java.lang.Exception

Bind a parameter to a SQL statement. All Java types should be acceptable, except NULL. Use 'IS NULL' in your SQL for this.

Parameters:

sql - The prepared statement to bind to.

index - Specifies which placeholder to bind to (starts at 1).

data - The data to bind to that placeholder.

Throws:

java.lang.Exception - if there is an error.

free

void free(java.sql.PreparedStatement sql)
          throws java.lang.Exception

Free the resources for a prepared statement. For very commonly occurring statements this is not necessarily advised since DatabaseServices tracks all statements and will free them at server shutdown. The performance gains are useful from this approach IF you use the same query routinely.

Parameters:

sql - The prepared statement to release.

Throws:

java.lang.Exception - if there is an error.

getResults

java.util.List<java.util.Map<java.lang.String,java.lang.String>> getResults(java.sql.PreparedStatement sql)
                                                                            throws java.lang.Exception

Parse the results of the query into a basic Java data structure. Users wanting the original result set should call getResultSet() directly against the prepared statement.

Parameters:

sql - The prepared statement to get the results from.

Returns:

List> A list of result rows as key/value pairs in HashMaps

Throws:

java.lang.Exception - if there is an error.

select

java.util.List<java.util.Map<java.lang.String,java.lang.String>> select(java.lang.String db,
                                                                      java.lang.String index,
                                                                      java.lang.String sql,
                                                                      java.util.List<java.lang.Object> fields)
                                                                        throws java.lang.Exception

Top level wrapper for a select statement.

Parameters:

db - The database connection to use.

index - The index to file this statement under for caching.

sql - The sql string to execute.

fields - The data to bind against placeholders. NULL is valid.

Returns:

List> A list of result rows as key/value pairs in HashMaps

Throws:

java.lang.Exception - if there is an error.

insert

void insert(java.lang.String db,
          java.lang.String index,
          java.lang.String table,
          java.util.Map<java.lang.String,java.lang.Object> fields)
            throws java.lang.Exception

Top level wrapper for an insert statement.

Parameters:

db - The database connection to use.

index - The index to file this statement under for caching.

table - The name of the table to insert into.

fields - The data to insert, a map of .

Throws:

java.lang.Exception - if there is an error.

delete

void delete(java.lang.String db,
          java.lang.String index,
          java.lang.String table,
          java.util.Map<java.lang.String,java.lang.Object> where)
            throws java.lang.Exception

Top level wrapper for a delete statement. Simple equality tests are possible for the where clause.

Parameters:

db - The database connection to use.

index - The index to file this statement under for caching.

table - The name of the table to delete.

fields - The data to use in a where clause. key/value pairs

Throws:

java.lang.Exception - if there is an error.

execute

void execute(java.lang.String db,
           java.lang.String index,
           java.lang.String sql,
           java.util.List<java.lang.Object> fields)
             throws java.lang.Exception

Top level wrapper to execute simple non-returning SQL, such as create or update statements.

Parameters:

db - The database connection to use.

index - The index to file this statement under for caching.

sql - The sql string to execute.

fields - The data to bind against placeholders. NULL is valid.

Throws:

java.lang.Exception - if there is an error.