com.arsdigita.acs.db
Class Database

java.lang.Object
  |
  +--com.arsdigita.acs.db.Database

public class Database
extends Object

Wrapper class for Oracle JDBC. Opens database connections, manages connection pools, handles queries, and provides utility methods for large-object (BLOB/CLOB) operations.


Constructor Summary
Database()
          Returns a database handle for an open database connection from the connection pool.
Database(ServletContext sc)
          Returns a database handle for an open database connection from the connection pool.
 
Method Summary
(package private) static void ()
           
 void abortTransaction()
          Rolls back and aborts a transaction.
 void beginTransaction()
          Starts a transaction by turning off auto-commit mode.
static String bindObj(Object obj)
          Utility function returning an empty string if an input object is null.
 int blobDmlFile(SqlStatement sql, File f)
          Utility function for writing a file to a BLOB in the database.
 int blobDmlFile(String sql, Object[] bind, File f)
          Utility function for writing a file to a BLOB in the database.
 int clobDml(SqlStatement sqlst, String s)
          Utility function for a large string literal to a CLOB field
 int clobDmlFile(String sql, Object[] bind, File f)
          Utility function for writing a file to a CLOB in the database.
 void close()
          Returns this database handle to the connection pool.
static boolean contains(ResultSet rs, String column)
          Returns true if rs contains a column named column with a non-null value.
 int dml(SqlStatement sql)
          Executes a DML statement (insert, update, delete).
 int dml(String sql)
          Executes a DML statement (insert, update, delete) with no bind variables.
 int dml(String sql, Object[] bind)
          Executes a DML statement (insert, update, delete).
static void dumpBLOB(ResultSet rs, String name, OutputStream os)
          Dumps a BLOB's contents to an OutputStream.
 void endTransaction()
          Completes a transaction by turning on auto-commit mode.
protected  void finalize()
          Called by the garbage collector at some point after this goes out of scope.
static byte[] getBLOB(ResultSet ors, String name)
          Returns a BLOB from a ResultSet as a byte array.
static String getCLOB(ResultSet ors, String name)
          Returns a CLOB from a ResultSet as a String.
 boolean inTransaction()
          Returns true if in a transaction.
static void main(String[] args)
           
 Object plsql(SqlStatement stmt)
          Alternate form; calls plsql(stmt.getSql(), stmt.getBindValues()).
 Object plsql(SqlStatement stmt, int outType)
          Alternate form; calls plsql(stmt.getSql(), stmt.getBindValues(), outType).
 Object plsql(String sql, Object[] bind)
          Calls a SQL stored procedure, stored function, or other PL/SQL code with IN parameters but no OUT parameters.
 Object plsql(String sql, Object[] bind, int outType)
          Calls a SQL stored function, or other PL/SQL code, whose first bind variable may be is an OUT parameter returning the value of the stored procedure/function.
 ResultSet query(SqlStatement sql)
          Returns the result of a query.
 ResultSet query(String sql)
          Returns the result of a query with no bind variables.
 ResultSet query(String sql, Object[] bind)
          Returns the result of a query.
 Vector queryToList(SqlStatement stmt)
          Returns a list of Strings resulting from a single-column SQL query.
 Vector queryToList(String sql, Object[] bind)
          Returns a list of Strings resulting from a single-column SQL query.
 String queryToString(SqlStatement st)
          Returns a string result from a single-row, single-column SQL query.
 String queryToString(SqlStatement st, String defaultValue)
          Returns a string result from a single-row, single-column SQL query.
 String queryToString(String sql)
          Returns a string result from a single-row, single-column SQL query.
 String queryToString(String sql, Object[] bind)
          Returns a string result from a single-row, single-column SQL query.
 String queryToString(String sql, Object[] bind, String defaultValue)
          Returns a string result from a single-row, single-column SQL query.
 String queryToString(String sql, String defaultValue)
          Returns a string result from a single-row, single-column SQL query.
static void writeBLOB(oracle.sql.BLOB blob, File f)
          Writes a BLOB to the database from a file.
static void writeBLOB(ResultSet rs, String name, File f)
          Writes a BLOB to the database from a file.
static void writeCLOB(oracle.sql.CLOB clob, File f)
          Writes a CLOB to the database from a file.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Database

public Database()
         throws SQLException
Returns a database handle for an open database connection from the connection pool.

Database

public Database(ServletContext sc)
         throws SQLException
Returns a database handle for an open database connection from the connection pool. Stashes away a servlet context for logging.
Method Detail

static void ()

close

public void close()
           throws SQLException
Returns this database handle to the connection pool.

inTransaction

public boolean inTransaction()
                      throws SQLException
Returns true if in a transaction.

beginTransaction

public void beginTransaction()
                      throws SQLException
Starts a transaction by turning off auto-commit mode.

endTransaction

public void endTransaction()
                    throws SQLException
Completes a transaction by turning on auto-commit mode. Commits the transaction.

abortTransaction

public void abortTransaction()
                      throws SQLException
Rolls back and aborts a transaction. turns auto-commit back on.

finalize

protected void finalize()
                 throws Throwable
Called by the garbage collector at some point after this goes out of scope. Makes sure that the connection is returned to the pool.
Overrides:
finalize in class Object

query

public ResultSet query(SqlStatement sql)
                throws SQLException
Returns the result of a query.
Parameters:
sql - An object consisting of the SQL query and the bind values
Returns:
A ResultSet with the query results.

query

public ResultSet query(String sql,
                       Object[] bind)
                throws SQLException
Returns the result of a query.
Parameters:
sql - A SQL query
bind - An array of bind values
Returns:
A ResultSet with the query results.

query

public ResultSet query(String sql)
                throws SQLException
Returns the result of a query with no bind variables.
Parameters:
sql - A SQL query
Returns:
A ResultSet with the query results.

dml

public int dml(String sql)
        throws SQLException
Executes a DML statement (insert, update, delete) with no bind variables.
Parameters:
sql - A SQL query
Returns:
The number of rows affected

dml

public int dml(String sql,
               Object[] bind)
        throws SQLException
Executes a DML statement (insert, update, delete).
Parameters:
sql - A SQL query
bind - A list of bind values
Returns:
The number of rows affected

dml

public int dml(SqlStatement sql)
        throws SQLException
Executes a DML statement (insert, update, delete).
Parameters:
sql - An object containing a SQL query and a list of bind values
Returns:
The number of rows affected

plsql

public Object plsql(String sql,
                    Object[] bind,
                    int outType)
             throws SQLException
Calls a SQL stored function, or other PL/SQL code, whose first bind variable may be is an OUT parameter returning the value of the stored procedure/function.

The SQL statement will generally be of the form begin ? := stored_function(?, ?, ?); end; or begin stored_proc(?, ?) . The value returned from stored_function will be returned, or null will be returned for procedures.

Note that a stored function with no side effects (inserts/updates/deletes) may be SELECTed from dual and called as a normal query, and a stored procedure with no side effects may be executed by the dml() method. Also, DDL can often be executed by the dml() method as well.

Parameters:
sql - An object containing the SQL code
bind - A list of bind values
outType - The type of the OUT parameter (or Types.NULL if none)
Returns:
The object returned by the PL/SQL code, or null if none
See Also:
CallableStatement, java.sql.Types

plsql

public Object plsql(String sql,
                    Object[] bind)
             throws SQLException
Calls a SQL stored procedure, stored function, or other PL/SQL code with IN parameters but no OUT parameters.

Note that a stored function with no side effects (inserts/updates/deletes) may be SELECTed from dual and called as a normal query, and a stored procedure with no side effects may be executed as DML.

Parameters:
sql - An object containing the SQL code
bind - A list of bind values
Returns:
The number of rows affected
See Also:
CallableStatement, java.sql.Types

plsql

public Object plsql(SqlStatement stmt)
             throws SQLException
Alternate form; calls plsql(stmt.getSql(), stmt.getBindValues()).

plsql

public Object plsql(SqlStatement stmt,
                    int outType)
             throws SQLException
Alternate form; calls plsql(stmt.getSql(), stmt.getBindValues(), outType).

clobDml

public int clobDml(SqlStatement sqlst,
                   String s)
            throws SQLException,
                   IOException
Utility function for a large string literal to a CLOB field
Parameters:
sql - SQL insert or update, with the CLOB locator returned as an OUT parameter, as the final bind variable (e.g., ... returning clob_column into ?)

Note: Note that the SQL statement must be wrapped in a begin ... end block. This is a kludge; issuing a bare insert/update results in a "not enough bind values" error from Oracle, and trying to make the locator an IN/OUT parameter with setNull or setCLOB results in weird errors in the database driver.

sqlst - The sql statement with bind vars
s - The string to write
Returns:
the number of rows affected

blobDmlFile

public int blobDmlFile(String sql,
                       Object[] bind,
                       File f)
                throws SQLException,
                       IOException
Utility function for writing a file to a BLOB in the database.
Parameters:
sql - SQL insert or update, with the BLOB locator returned as an OUT parameter, as the final bind variable (e.g., ... returning blob_column into ?)

Note: Note that the SQL statement must be wrapped in a begin ... end block. This is a kludge; issuing a bare insert/update results in a "not enough bind values" error from Oracle, and trying to make the locator an IN/OUT parameter with setNull or setBLOB results in weird errors in the database driver.

bind - List of bind vals
f - The file to write
Returns:
the number of rows affected

blobDmlFile

public int blobDmlFile(SqlStatement sql,
                       File f)
                throws SQLException,
                       IOException
Utility function for writing a file to a BLOB in the database.
Parameters:
sql - Object including SQL insert or update and bind values, with the BLOB locator returned as an OUT parameter, as the final bind variable (e.g., ... returning blob_column into ?).

Note: Note that the SQL statement must be wrapped in a begin ... end block. This is a kludge; issuing a bare insert/update results in a "not enough bind values" error from Oracle, and trying to make the locator an IN/OUT parameter with setNull or setBLOB results in weird errors in the database driver.

f - The file to write
Returns:
the number of rows affected

clobDmlFile

public int clobDmlFile(String sql,
                       Object[] bind,
                       File f)
                throws SQLException,
                       IOException
Utility function for writing a file to a CLOB in the database.
Parameters:
sql - SQL insert or update, with the CLOB locator returned as an OUT parameter, as the final bind variable (e.g., ... returning blob_column into ?)

Note: Note that the SQL statement must be wrapped in a begin ... end block. This is a kludge; issuing a bare insert/update results in a "not enough bind values" error from Oracle, and trying to make the locator an IN/OUT parameter with setNull or setCLOB results in weird errors in the database driver.

bind - List of bind vals
f - The file to write
Returns:
the number of rows affected

queryToString

public String queryToString(String sql,
                            String defaultValue)
                     throws SQLException,
                            ACSException
Returns a string result from a single-row, single-column SQL query.
Parameters:
sql - SQL to run
defaultValue - Default if the query returns no rows
Returns:
The result of the SQL query, or default if the query returns no rows.

queryToString

public String queryToString(String sql)
                     throws SQLException,
                            ACSException
Returns a string result from a single-row, single-column SQL query. Throws ACSException if no rows are returned.
Parameters:
sql - SQL to run
Returns:
The result of the SQL query.
Throws:
ACSException -  

queryToString

public String queryToString(String sql,
                            Object[] bind)
                     throws SQLException,
                            ACSException
Returns a string result from a single-row, single-column SQL query. Throws ACSException if no rows are returned.
Parameters:
sql - SQL to run
bind - List of bind values
Returns:
The result of the SQL query.
Throws:
ACSException -  

queryToString

public String queryToString(SqlStatement st)
                     throws SQLException,
                            ACSException
Returns a string result from a single-row, single-column SQL query. Throws ACSException if no rows are returned.
Parameters:
st - Object with SQL statement and bind values
Returns:
The result of the SQL query.
Throws:
ACSException -  

queryToString

public String queryToString(SqlStatement st,
                            String defaultValue)
                     throws SQLException,
                            ACSException
Returns a string result from a single-row, single-column SQL query. Returns defaultValue if no rows are returned.
Parameters:
st - Object with SQL statement and bind values
defaultValue - Value to return if query returns no rows
Returns:
The result of the SQL query (or defaultValue if no rows returned)
Throws:
ACSException -  

queryToString

public String queryToString(String sql,
                            Object[] bind,
                            String defaultValue)
                     throws SQLException,
                            ACSException
Returns a string result from a single-row, single-column SQL query. Throws ACSException if no rows are returned and no default value is supplied.
Parameters:
sql - SQL to run
bind - List of bind values
defaultValue - Default if the query returns no rows
Returns:
The result of the SQL query, or default if the query returns no rows.

queryToList

public Vector queryToList(String sql,
                          Object[] bind)
                   throws SQLException
Returns a list of Strings resulting from a single-column SQL query.
Parameters:
sql - SQL to run
bind - List of bind values
Returns:
A list of values from the SQL query.

queryToList

public Vector queryToList(SqlStatement stmt)
                   throws SQLException
Returns a list of Strings resulting from a single-column SQL query.
Parameters:
stmt - An object containing a SQL statment and a list of bind values
Returns:
A list of values from the SQL query.

getCLOB

public static String getCLOB(ResultSet ors,
                             String name)
                      throws SQLException,
                             IOException
Returns a CLOB from a ResultSet as a String.
Parameters:
ors - The result set
name - The name of the CLOB column
Returns:
The contents of the CLOB column

getBLOB

public static byte[] getBLOB(ResultSet ors,
                             String name)
                      throws SQLException,
                             IOException
Returns a BLOB from a ResultSet as a byte array.
Parameters:
ors - The result set
name - The name of the BLOB column
Returns:
The contents of the BLOB column

writeBLOB

public static void writeBLOB(ResultSet rs,
                             String name,
                             File f)
                      throws SQLException,
                             IOException
Writes a BLOB to the database from a file.
Parameters:
rs - The result set
name - The name of the BLOB column
f - The file to fill the database BLOB with

writeBLOB

public static void writeBLOB(oracle.sql.BLOB blob,
                             File f)
                      throws SQLException,
                             IOException
Writes a BLOB to the database from a file.
Parameters:
blob - The BLOB locator
f - The file to fill the database BLOB with

writeCLOB

public static void writeCLOB(oracle.sql.CLOB clob,
                             File f)
                      throws SQLException,
                             IOException
Writes a CLOB to the database from a file.
Parameters:
blob - The CLOB locator
f - The file to fill the database CLOB with

dumpBLOB

public static void dumpBLOB(ResultSet rs,
                            String name,
                            OutputStream os)
                     throws SQLException,
                            IOException
Dumps a BLOB's contents to an OutputStream.
Parameters:
rs - The result set containing a BLOB locator
name - The name of the BLOB column
os - The output stream to write the BLOB contents to

bindObj

public static String bindObj(Object obj)
Utility function returning an empty string if an input object is null. Used primarily for binding objects from a JSP tag, since Object.toString has this nasty habit of putting the string literal "null" in place for NULL object. This behavior wreaks havoc when trying to put a null integer into the database.
Parameters:
obj - The object that for binding
Returns:
The string representation of obj, or an empty string if null

main

public static void main(String[] args)

contains

public static boolean contains(ResultSet rs,
                               String column)
Returns true if rs contains a column named column with a non-null value.