edu.internet2.middleware.grouperClient.jdbc
Class GcDbAccess

java.lang.Object
  extended by edu.internet2.middleware.grouperClient.jdbc.GcDbAccess

public class GcDbAccess
extends java.lang.Object

Get access to the global database connections, create a new connection, 
 and execute sql against them.

Author:
harveycg

Nested Class Summary
static class GcDbAccess.ConnectionBean
          returned from connection call
 
Constructor Summary
GcDbAccess()
           
 
Method Summary
static void accumulateQueryMillis(boolean _accumulateQueryMillis)
          If true, the map queryAndTime will be populated with the time spent in each unique query (unique by query string, not considering bind variable values) - BE SURE TO TURN THIS OFF when done debugging, this is ONLY for debugging on the desktop!Turning it off CLEARS the stats, so write it off first! Example: 1.
 GcDbAccess addBindVar(java.lang.Object _bindVar)
          Add to the list of bind variable objects, leaving any that exist there - if you use this in a transaction callback you will have to clear bindvars between calls or they will accumulate.
 GcDbAccess batchBindVars(java.util.List<java.util.List<java.lang.Object>> _batchBindVars)
          If you are executing sql as a batch statement, set the batch bind variables here.
 GcDbAccess bindVars(java.lang.Object... _bindVars)
          /** Set the list of bind variable objects, always replacing any that exist.
 GcDbAccess cacheMinutes(java.lang.Integer _cacheMinutes)
          Cache the results of a SELECT query for the allotted minutes.
<T> T
callbackCallableStatement(GcCallableStatementCallback<T> callableStatementCallback)
          Callback to get a callableStatement - commit is called if there is no exception thrown, otherwise rollback is called.
<T> T
callbackConnection(GcConnectionCallback<T> connectionCallback)
          Callback to get a connection - commit is called if there is no exception thrown, otherwise rollback is called.
<T> void
callbackEntity(java.lang.Class<T> clazz, GcEntityCallback<T> entityCallback)
          For each row of a given resultset, hydrate an object and pass it to the callback.
<T> T
callbackPreparedStatement(GcPreparedStatementCallback<T> preparedStatementCallback)
          Callback to get a preparedStatement - commit is called if there is no exception thrown, otherwise rollback is called.
<T> T
callbackResultSet(GcResultSetCallback<T> resultSetCallback)
          Callback a resultSet.
<T> T
callbackTransaction(GcTransactionCallback<T> transactionCallback)
          Use a transaction for all calls that happen within this callback.
 GcDbAccess connectionName(java.lang.String theConnectionName)
          connection name from the config file, or null for default
static java.lang.String createInString(int numberOfBindVariables)
          Create an in statement with the given number of bind variables: createInString(2) returns " (?,?) "
 void deleteFromDatabase(java.lang.Object o)
          Delete the object from the database if it has already been stored - the object should have appropriate annotations from the PersistableX annotations.
 GcDbAccess example(java.lang.Object _example)
          If selecting by example, set this and all column values will be used to create a where clause.
 int[] executeBatchSql()
          Execute some sql as a batch.
 int executeSql()
          Execute some sql.
static java.util.Map<MultiKey,GcDbQueryCache> getGcDbQueryCacheMap()
          Cached queries, exposed mostly for testing, you should not need direct access to this.
static java.util.Map<java.lang.String,GcQueryReport> getQueriesAndMillis()
          The map containing reports if they have been turned on.
 boolean isPreviouslyPersisted(java.lang.Object o)
          Whether this class has already been saved to the database, looks for a field(s) with annotation @Persistable(primaryKeyField=true), assumes that it is a number, and returns true if it is null or larger than 0.
static void loadBoundDataConversion(GcBoundDataConversion _boundDataConversion)
          This is the helper to convert data to and from Oracle, which has a default of BoundDataConversionImpl.
 GcDbAccess omitNullValuesForExample()
          If selecting by example, set this and all column values of the given example object except null values will be used to create a where clause.
 GcDbAccess primaryKey(java.lang.Object... _primaryKey)
          Set the primary key to select by.
 GcDbAccess queryTimeoutSeconds(java.lang.Integer _queryTimeoutSeconds)
          The amount of seconds that the query can run before being rolled back.
static void reportQueriesAndMillisAndTurnOffAccumulation(java.lang.String fileLocation)
          Write the stats of queries and time spent in them to a file at the given location, then stop collection stats.
<T> T
select(java.lang.Class<T> clazz)
          Select something from the database - either set sql() before calling or primaryKey()
<T> java.util.List<T>
selectList(java.lang.Class<T> clazz)
          Select something from the database - either set sql() before calling or primaryKey(...)
 java.util.List<GcCaseIgnoreHashMap> selectListMap()
          Select a map of rows from the database with column name as key and valueClass as value (should be Object if types differ) from the database - set sql() before calling Example: select first_name, last_name, middle_name from person where rownum < 3: List(0) Map key Map value first_name Fred last_name Jones middle_name Percival List(1) Map key Map value first_name Jeanette last_name Shawna middle_name Percival
<K,V> java.util.Map<K,V>
selectMap(java.lang.Class<K> keyClass, java.lang.Class<V> valueClass)
          Select a map of something from the database - set sql() before calling - this will return a map with column name and column value - this should only select one row from the database.
 GcCaseIgnoreHashMap selectMapMultipleColumnsOneRow()
          Select a map of key : column name and value : column value from the database - set sql() before calling.
<K,V> java.util.Map<K,V>
selectMapMultipleRows(java.lang.Class<K> keyClass, java.lang.Class<V> valueClass)
          Select a map of two column values from the database - set sql() before calling - the first column in the sql will be used for the map keys and the second will be used for the map values.
 GcDbAccess sql(java.lang.String _sql)
          Set the sql to use.
<T> void
storeBatchToDatabase(java.util.List<T> objects)
          Store the given objects to the database in a batch - the objects should have appropriate annotations from the PersistableX annotations.
<T> void
storeBatchToDatabase(java.util.List<T> objects, boolean omitPrimaryKeyPopulation)
          Store the given objects to the database in a batch - the objects should have appropriate annotations from the PersistableX annotations.
<T> void
storeBatchToDatabase(java.util.List<T> objects, int batchSize)
          Store the given objects to the database in a batch - the objects should have appropriate annotations from the PersistableX annotations.
<T> void
storeBatchToDatabase(java.util.List<T> objects, int batchSize, boolean omitPrimaryKeyPopulation)
          Store the given objects to the database in a batch - the objects should have appropriate annotations from the PersistableX annotations.
<T> void
storeListToDatabase(java.util.List<T> objects)
          Store the given objects to the database in one transaction - the object should have appropriate annotations from the PersistableX annotations.
<T> void
storeToDatabase(T t)
          Store the given object to the database - the object should have appropriate annotations from the PersistableX annotations.
static void transactionEnd(GcTransactionEnd transactionEnd, boolean endOnlyIfStarted)
          end a transaction
static void transactionEnd(GcTransactionEnd transactionEnd, boolean endOnlyIfStarted, java.lang.String connectionName)
          end a transaction
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

GcDbAccess

public GcDbAccess()
Method Detail

connectionName

public GcDbAccess connectionName(java.lang.String theConnectionName)
connection name from the config file, or null for default

Parameters:
theConnectionName -
Returns:
this for chaining

transactionEnd

public static void transactionEnd(GcTransactionEnd transactionEnd,
                                  boolean endOnlyIfStarted)
end a transaction

Parameters:
transactionEnd -
endOnlyIfStarted -

transactionEnd

public static void transactionEnd(GcTransactionEnd transactionEnd,
                                  boolean endOnlyIfStarted,
                                  java.lang.String connectionName)
end a transaction

Parameters:
transactionEnd -
endOnlyIfStarted -
connectionName -

loadBoundDataConversion

public static void loadBoundDataConversion(GcBoundDataConversion _boundDataConversion)
This is the helper to convert data to and from Oracle, which has a default of BoundDataConversionImpl. If you encounter errors getting and setting data from oracle to java, you may need to override the default and set your version here. Otherwise, nothing is needed.

Parameters:
_boundDataConversion - the boundDataConversion to set.

createInString

public static java.lang.String createInString(int numberOfBindVariables)
Create an in statement with the given number of bind variables: createInString(2) returns " (?,?) "

Parameters:
numberOfBindVariables - is the number of bind variables to use.
Returns:
the string.

bindVars

public GcDbAccess bindVars(java.lang.Object... _bindVars)
/** Set the list of bind variable objects, always replacing any that exist.

Parameters:
_bindVars - are the variables to add to the list.
Returns:
this.

addBindVar

public GcDbAccess addBindVar(java.lang.Object _bindVar)
Add to the list of bind variable objects, leaving any that exist there - if you use this in a transaction callback you will have to clear bindvars between calls or they will accumulate.

Parameters:
_bindVar - is the variable to add to the list.
Returns:
this.

batchBindVars

public GcDbAccess batchBindVars(java.util.List<java.util.List<java.lang.Object>> _batchBindVars)
If you are executing sql as a batch statement, set the batch bind variables here.

Parameters:
_batchBindVars - are the variables to set.
Returns:
this.

cacheMinutes

public GcDbAccess cacheMinutes(java.lang.Integer _cacheMinutes)
Cache the results of a SELECT query for the allotted minutes.
 Note that cached objects are not immutable; if you modify them you are modifying them in the cache as well.

Parameters:
_cacheMinutes - is how long to persist the object(s) in cache for after the initial selection.
Returns:
this.

sql

public GcDbAccess sql(java.lang.String _sql)
Set the sql to use.

Parameters:
_sql - is the sql to use.
Returns:
this.

omitNullValuesForExample

public GcDbAccess omitNullValuesForExample()
If selecting by example, set this and all column values of the given example object except null values will be used to create a where clause.

Returns:
this.

example

public GcDbAccess example(java.lang.Object _example)
If selecting by example, set this and all column values will be used to create a where clause.

Parameters:
_example - is the example to use.
Returns:
this.

queryTimeoutSeconds

public GcDbAccess queryTimeoutSeconds(java.lang.Integer _queryTimeoutSeconds)
The amount of seconds that the query can run before being rolled back.

Parameters:
_queryTimeoutSeconds - is the amount of seconds to set.
Returns:
this.

accumulateQueryMillis

public static void accumulateQueryMillis(boolean _accumulateQueryMillis)
If true, the map queryAndTime will be populated with the time spent in each unique query (unique by query string, not considering bind variable values) 
 - BE SURE TO TURN THIS OFF when done debugging, this is ONLY for debugging on the desktop!Turning it off CLEARS the stats, so write it off first!
 Example:
 1. DbAccess.accumulateQueryMillis(true);
 2. use application normally
 3. Get the results: Map timeSpentInQueries = 
 

Parameters:
_accumulateQueryMillis - is whether to accumulate them or not.

reportQueriesAndMillisAndTurnOffAccumulation

public static void reportQueriesAndMillisAndTurnOffAccumulation(java.lang.String fileLocation)
Write the stats of queries and time spent in them to a file at the given location, then stop collection stats. accumulateQueryMillis(true)
 must be called first to turn on debugging.

Parameters:
fileLocation - is the location of the file to write.

primaryKey

public GcDbAccess primaryKey(java.lang.Object... _primaryKey)
Set the primary key to select by.

Parameters:
_primaryKey - is the _primaryKey to use.
Returns:
this.

isPreviouslyPersisted

public boolean isPreviouslyPersisted(java.lang.Object o)
Whether this class has already been saved to the database, looks for a field(s) with annotation @Persistable(primaryKeyField=true),
 assumes that it is a number, and returns true if it is null or larger than 0.

Parameters:
o - is the object to store to the database.
Returns:
true if so.

deleteFromDatabase

public void deleteFromDatabase(java.lang.Object o)
Delete the object from the database if it has already been stored - the object should have appropriate annotations from the PersistableX annotations.

Parameters:
o - is the object to delete from the database.
See Also:
- this annotation must be placed at the class level., these annotations may be placed at the method level depending on your needs.

storeListToDatabase

public <T> void storeListToDatabase(java.util.List<T> objects)
Store the given objects to the database in one transaction - the object should have appropriate annotations from the PersistableX annotations.

Type Parameters:
T - is the type to store.
Parameters:
objects - are the object to store to the database.
See Also:
- this annotation must be placed at the class level., these annotations may be placed at the method level depending on your needs.

storeToDatabase

public <T> void storeToDatabase(T t)
Store the given object to the database - the object should have appropriate annotations from the PersistableX annotations.

Type Parameters:
T - is the type to store.
Parameters:
t - is the object to store to the database.
See Also:
- this annotation must be placed at the class level., these annotations may be placed at the method level depending on your needs.

storeBatchToDatabase

public <T> void storeBatchToDatabase(java.util.List<T> objects,
                                     int batchSize)
Store the given objects to the database in a batch - 
 the objects should have appropriate annotations from the PersistableX annotations.
 You cannot have both inserts and updates in the list of objects to store; they MUST all have the 
 same action (insert or update) being taken against them as jdbc statements supoprt mutliple
 sqls in a batch but do not support bind variables when using this capability.

Type Parameters:
T - is the type to store.
Parameters:
objects - is the list of objects to store to the database.
batchSize - is the size of the batch to insert or update in.
See Also:
- this annotation must be placed at the class level., these annotations may be placed at the method level depending on your needs.

storeBatchToDatabase

public <T> void storeBatchToDatabase(java.util.List<T> objects,
                                     int batchSize,
                                     boolean omitPrimaryKeyPopulation)
Store the given objects to the database in a batch - 
 the objects should have appropriate annotations from the PersistableX annotations.
 You cannot have both inserts and updates in the list of objects to store; they MUST all have the 
 same action (insert or update) being taken against them as jdbc statements supoprt mutliple
 sqls in a batch but do not support bind variables when using this capability.

Type Parameters:
T - is the type being stored.
Parameters:
objects - is the list of objects to store to the database.
batchSize - is the size of the batch to insert or update in.
omitPrimaryKeyPopulation - if you DON'T need primary keys populated into your objects, you can set this and save some query time since we will just set the primary key population as "some_sequence.nextval" instead of selecting it manually before storing the object.
See Also:
- this annotation must be placed at the class level., these annotations may be placed at the method level depending on your needs.

storeBatchToDatabase

public <T> void storeBatchToDatabase(java.util.List<T> objects)
Store the given objects to the database in a batch - 
 the objects should have appropriate annotations from the PersistableX annotations.
 You cannot have both inserts and updates in the list of objects to store; they MUST all have the 
 same action (insert or update) being taken against them as jdbc statements supoprt mutliple
 sqls in a batch but do not support bind variables when using this capability.

Type Parameters:
T - is the type being stored.
Parameters:
objects - is the list of objects to store to the database.
See Also:
- this annotation must be placed at the class level., these annotations may be placed at the method level depending on your needs.

storeBatchToDatabase

public <T> void storeBatchToDatabase(java.util.List<T> objects,
                                     boolean omitPrimaryKeyPopulation)
Store the given objects to the database in a batch - 
 the objects should have appropriate annotations from the PersistableX annotations.
 You cannot have both inserts and updates in the list of objects to store; they MUST all have the 
 same action (insert or update) being taken against them as jdbc statements supoprt mutliple
 sqls in a batch but do not support bind variables when using this capability.

Type Parameters:
T - is the type being stored.
Parameters:
objects - is the list of objects to store to the database.
omitPrimaryKeyPopulation - if you DON'T need primary keys populated into your objects, you can set this and save some query time since we will just set the primary key population as "some_sequence.nextval" instead of selecting it manually before storing the object.
See Also:
- this annotation must be placed at the class level., these annotations may be placed at the method level depending on your needs.

callbackEntity

public <T> void callbackEntity(java.lang.Class<T> clazz,
                               GcEntityCallback<T> entityCallback)
For each row of a given resultset, hydrate an object and pass it to the callback.

Type Parameters:
T -
Parameters:
clazz - is the type of thing passed to the entity callback.
entityCallback - is the callback object that receives this dbAccess with a session set up.

callbackTransaction

public <T> T callbackTransaction(GcTransactionCallback<T> transactionCallback)
Use a transaction for all calls that happen within this callback. Upon success with no exceptions thrown,
 commit is called automatically. Upon failure, rollback it called. You may also call dbAccess.setTransactionEnd()
 within the callback block.

Type Parameters:
T - is the type of thing being returned.
Parameters:
transactionCallback - is the callback object that receives this dbAccess with a session set up.
Returns:
the thing that you want to return.

selectMap

public <K,V> java.util.Map<K,V> selectMap(java.lang.Class<K> keyClass,
                                          java.lang.Class<V> valueClass)
Select a map of something from the database - set sql() before calling - this will return a map with column name and column value - this should only select one row from the database.

Type Parameters:
K -
V -
Parameters:
keyClass - is the class of the key.
valueClass - is the class of the value.
Returns:
the map or null if nothing is found..

selectMapMultipleRows

public <K,V> java.util.Map<K,V> selectMapMultipleRows(java.lang.Class<K> keyClass,
                                                      java.lang.Class<V> valueClass)
Select a map of two column values from the database - set sql() before calling - the first column in the sql will be used for the map keys and the second will be used for the map values.

Type Parameters:
K -
V -
Parameters:
keyClass - is the class of the key.
valueClass - is the class of the value.
Returns:
the map or null if nothing is found..

selectListMap

public java.util.List<GcCaseIgnoreHashMap> selectListMap()
Select a map of rows from the database with column name as key and valueClass as value (should be Object if types differ) from the database - set sql() before calling Example: select first_name, last_name, middle_name from person where rownum < 3: List(0) Map key Map value first_name Fred last_name Jones middle_name Percival List(1) Map key Map value first_name Jeanette last_name Shawna middle_name Percival

Returns:
the map or null if nothing is found..

selectMapMultipleColumnsOneRow

public GcCaseIgnoreHashMap selectMapMultipleColumnsOneRow()
Select a map of key : column name and value : column value from the database - set sql() before calling.
 Example: select first_name, last_name, middle_name from person:
 Map key      Map value
 first_name   Fred
 last_name    Jones
 middle_name  Percival
 

Returns:
the map or null if nothing is found..

select

public <T> T select(java.lang.Class<T> clazz)
Select something from the database - either set sql() before calling or primaryKey()

Type Parameters:
T - is the type of object that will be returned.
Parameters:
clazz - is the type of object that will be returned.
Returns:
anything.

selectList

public <T> java.util.List<T> selectList(java.lang.Class<T> clazz)
Select something from the database - either set sql() before calling or primaryKey(...)

Type Parameters:
T - is the type of object that will be returned.
Parameters:
clazz - is the type of object that will be returned.
Returns:
anything.

callbackCallableStatement

public <T> T callbackCallableStatement(GcCallableStatementCallback<T> callableStatementCallback)
Callback to get a callableStatement - commit is called if there is no exception thrown, otherwise rollback is called.

Type Parameters:
T - is what you are returning, must be a type but you can return null.
Parameters:
callableStatementCallback - is the callback object.
Returns:
whatever you return from the connection callback.

callbackPreparedStatement

public <T> T callbackPreparedStatement(GcPreparedStatementCallback<T> preparedStatementCallback)
Callback to get a preparedStatement - commit is called if there is no exception thrown, otherwise rollback is called.

Type Parameters:
T - is what you are returning, must be a type but you can return null.
Parameters:
preparedStatementCallback - is the callback object.
Returns:
whatever you return from the connection callback.

callbackConnection

public <T> T callbackConnection(GcConnectionCallback<T> connectionCallback)
Callback to get a connection - commit is called if there is no exception thrown, otherwise rollback is called.

Type Parameters:
T - is what you are returning, must be a type but you can return null.
Parameters:
connectionCallback - is the callback object.
Returns:
whatever you return from the connection callback.

callbackResultSet

public <T> T callbackResultSet(GcResultSetCallback<T> resultSetCallback)
Callback a resultSet.

Type Parameters:
T - is the type of object that will be returned.
Parameters:
resultSetCallback - is the object to callback.
Returns:
anything return from the callback object.

executeSql

public int executeSql()
Execute some sql.

Returns:
anything return from the callback object.

executeBatchSql

public int[] executeBatchSql()
Execute some sql as a batch.

Returns:
anything return from the callback object.

getGcDbQueryCacheMap

public static java.util.Map<MultiKey,GcDbQueryCache> getGcDbQueryCacheMap()
Cached queries, exposed mostly for testing, you should not need direct access to this.

Returns:
the dbQueryCacheMap

getQueriesAndMillis

public static java.util.Map<java.lang.String,GcQueryReport> getQueriesAndMillis()
The map containing reports if they have been turned on.

Returns:
the queriesAndMillis