com.ibatis.db.sqlmap
Class SqlMap

java.lang.Object
  extended bycom.ibatis.db.sqlmap.SqlMap

public class SqlMap
extends java.lang.Object

The SqlMap class ties everything together. It defines the ParameterMap objects, ResultMap objects, and MappedStatements that are used in the iBATIS database layer. It is generally configured in an XML file that is loaded at run time.

Author:
clinton_begin

Field Summary
private  java.util.HashMap cacheMap
           
private  boolean cacheModelsEnabled
           
private  java.lang.String currentDataSourceName
           
private  java.util.Map dataSourceMap
           
private  boolean driverHintsEnabled
           
private  Throttle executePerConnThrottle
           
private  Throttle executeThrottle
           
private  java.lang.ThreadLocal localBatch
           
private  java.lang.ThreadLocal localTransaction
           
private  java.io.PrintWriter logWriter
           
private  java.util.Map mappedStatements
           
private  java.util.Map parameterMaps
           
private  java.util.Map resultMaps
           
private  boolean startTransactionBeforeConnection
           
private  StatementFactory statementFactory
           
private  Throttle transactionThrottle
           
private  boolean useFullyQualifiedStatementNames
           
private  boolean useGlobalTransaction
           
private  JtaTransaction userTransaction
           
private  java.lang.String userTransactionJndiName
           
 
Constructor Summary
SqlMap()
          Creates new SqlMap
 
Method Summary
 void addCache(CacheModel cache)
          Adds a (named) cache.
 void addDataSource(java.lang.String name, javax.sql.DataSource dataSource)
          Adds a named datasource to the list of available datasources
 void addExecuteListener(ExecuteListener listener)
           
 void addMappedStatement(MappedStatement mappedStatement)
          Adds a (named) MappedStatement.
 void addParameterMap(ParameterMap parameterMap)
          Adds a (named) ParameterMap.
 void addResultMap(ResultMap resultMap)
          Adds a (named) ResultMap
private  void closeConnection(java.sql.Connection connection)
           
 void commitTransaction()
          Commits the current transaction
(package private)  void decrementExecutionThrottle(java.sql.Connection conn)
           
private  void decrementTransactionThrottle()
           
 void endBatch()
          Executes a 'batch' of statements as a single transaction
 java.util.List executeQueryForList(java.lang.String statementName, java.lang.Object parameterObject)
          Executes the SQL and retuns all rows selected.
 java.util.List executeQueryForList(java.lang.String statementName, java.lang.Object parameterObject, int skipResults, int maxResults)
          Executes the SQL and retuns all rows selected.
 java.util.Map executeQueryForMap(java.lang.String statementName, java.lang.Object parameterObject, java.lang.String keyProperty)
          Executes the SQL and retuns all rows selected in a map that is keyed on the property named in the keyProperty parameter.
 java.util.Map executeQueryForMap(java.lang.String statementName, java.lang.Object parameterObject, java.lang.String keyProperty, java.lang.String valueProperty)
          Executes the SQL and retuns all rows selected in a map that is keyed on the property named in the keyProperty parameter.
 java.lang.Object executeQueryForObject(java.lang.String statementName, java.lang.Object parameterObject)
          Executes a MappedStatement that returns a single object
 java.lang.Object executeQueryForObject(java.lang.String statementName, java.lang.Object parameterObject, java.lang.Object resultObject)
          Executes a MappedStatement that returns a single object of the type of the resultObject parameter.
 PaginatedList executeQueryForPaginatedList(java.lang.String statementName, java.lang.Object parameterObject, int pageSize)
          Executes the SQL and retuns a subset of the results in a dynamic PaginatedList that can be used to automatically scroll through results from a database table.
 void executeQueryWithRowHandler(java.lang.String statementName, java.lang.Object parameterObject, RowHandler rowHandler)
          Runs a query with a custom object that gets a chance to deal with each row as it is processed.
 int executeUpdate(java.lang.String statementName, java.lang.Object parameterObject)
          Executes a update using a MappedStatement and a parameter object
 void flushCache()
          Flushes all cached objects that belong to this SqlMap
 CacheModel getCache(java.lang.String name)
          Gets a cache by name
 java.util.Iterator getCaches()
          Returns an iterator to step through the available caches for the SqlMap
private  java.sql.Connection getConnectionFromCurrentDataSource()
           
 javax.sql.DataSource getCurrentDataSource()
          Returns the current data source
 java.lang.String getCurrentDataSourceName()
          Getter for the current data source name
 java.sql.Connection getCurrentLocalConnection()
           
 java.lang.String getDataCacheStats()
           
 javax.sql.DataSource getDataSource(java.lang.String name)
          Gets a named datasource from the list of available datasources
 java.io.PrintWriter getLogWriter()
          Deprecated. Use commons-logging
 MappedStatement getMappedStatement(java.lang.String name)
          Gets a MappedStatement by name
 java.util.Iterator getMappedStatementNames()
          Returns a Iterator containing the names of the mapped statements owned by this SqlMap
 ParameterMap getParameterMap(java.lang.String name)
          Gets a ParameterMap by name
 ResultMap getResultMap(java.lang.String name)
          Gets a ResultMap by name
 java.lang.Double getStatementCacheHitRatio()
           
 int getStatementCacheSize()
          Getter for size of statement cache
 StatementFactory getStatementFactory()
          Getter for the StatementFactory
(package private)  java.sql.PreparedStatement getStatementFromBatch(MappedStatement mappedStatement)
           
 java.lang.String getUserTransactionJndiName()
           
(package private)  void incrementExecutionThrottle(java.sql.Connection conn)
           
private  void incrementTransactionThrottle()
           
 boolean isCacheModelsEnabled()
          A flag that determines whether cache models were enabled when this SqlMap was built.
 boolean isCachePreparedStatement()
          Deprecated. Use getStatementCacheSize()
 boolean isDriverHintsEnabled()
          Gets the status of whether executions should make use of driver hints for the size of result sets etc.
 boolean isInsideBatch()
          Flag indicating that we are in the middle of creating or running a batch
 boolean isStartTransactionBeforeConnection()
          When enabled (default), this property causes transactions to be retrieved within the context of a transaction.
 boolean isUseFullyQualifiedStatementNames()
          Flag to determine whether fully qualified statement names are being used.
 boolean isUseGlobalTransaction()
          Returns true if global transaction support is enabled.
 void log(java.lang.String s)
          Deprecated. Use commons-logging
(package private)  void registerStatementWithBatch(MappedStatement mappedStatement, java.sql.PreparedStatement ps)
           
private  java.sql.Connection removeCurrentLocalConnection()
           
 void rollbackTransaction()
          Rolls back the current transaction
 void setCacheModelsEnabled(boolean cacheModelsEnabled)
          This is set by the builder of the SqlMap to flag whether cache models were enabled at the time of configuration.
 void setCachePreparedStatement(boolean cachePreparedStatement)
          Deprecated. Use setStatementCacheSize(int size)
 void setCurrentDataSourceName(java.lang.String currentDataSourceName)
          Setter for the current data source
private  void setCurrentLocalConnection(java.sql.Connection connection)
           
 void setDriverHintsEnabled(boolean driverHintsEnabled)
          Sets the status of whether executions should make use of driver hints for the size of result sets etc.
 void setLogWriter(java.io.PrintWriter logWriter)
          Deprecated. Use commons-logging
 void setMaxExecute(int limit)
           
 void setMaxExecutePerConnection(int limit)
           
 void setMaxTransactions(int limit)
           
 void setStartTransactionBeforeConnection(boolean startTransactionBeforeConnection)
          When enabled (default), this property causes transactions to be retrieved within the context of a transaction.
 void setStatementCacheSize(int statementCacheSize)
          Setter for size of statement cache
 void setUseFullyQualifiedStatementNames(boolean useFullyQualifiedStatementNames)
          Sets fully qualified names or not.
 void setUseGlobalTransaction(boolean useGlobalTransaction)
          Set to true if global transactions are available and should be used.
 void setUserTransactionJndiName(java.lang.String userTransactionJndiName)
           
 void startBatch()
          Sets up a 'batch' of update statements to execute using a more efficient call to the database.
 void startTransaction()
          Starts a new transaction.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

mappedStatements

private java.util.Map mappedStatements

resultMaps

private java.util.Map resultMaps

parameterMaps

private java.util.Map parameterMaps

dataSourceMap

private java.util.Map dataSourceMap

currentDataSourceName

private java.lang.String currentDataSourceName

statementFactory

private StatementFactory statementFactory

useGlobalTransaction

private boolean useGlobalTransaction

useFullyQualifiedStatementNames

private boolean useFullyQualifiedStatementNames

driverHintsEnabled

private boolean driverHintsEnabled

cacheModelsEnabled

private boolean cacheModelsEnabled

startTransactionBeforeConnection

private boolean startTransactionBeforeConnection

userTransactionJndiName

private java.lang.String userTransactionJndiName

userTransaction

private JtaTransaction userTransaction

logWriter

private java.io.PrintWriter logWriter

localTransaction

private java.lang.ThreadLocal localTransaction

localBatch

private java.lang.ThreadLocal localBatch

cacheMap

private java.util.HashMap cacheMap

executePerConnThrottle

private Throttle executePerConnThrottle

executeThrottle

private Throttle executeThrottle

transactionThrottle

private Throttle transactionThrottle
Constructor Detail

SqlMap

public SqlMap()
Creates new SqlMap

Method Detail

setMaxExecutePerConnection

public void setMaxExecutePerConnection(int limit)

setMaxExecute

public void setMaxExecute(int limit)

setMaxTransactions

public void setMaxTransactions(int limit)

getUserTransactionJndiName

public java.lang.String getUserTransactionJndiName()

setUserTransactionJndiName

public void setUserTransactionJndiName(java.lang.String userTransactionJndiName)

getLogWriter

public java.io.PrintWriter getLogWriter()
Deprecated. Use commons-logging

Gets a PrintWriter (like System.out) to be used for logging

Returns:
A PrintWriter to be used for logging

setLogWriter

public void setLogWriter(java.io.PrintWriter logWriter)
Deprecated. Use commons-logging

Sets a PrintWriter (like System.out) to be used for logging

Parameters:
logWriter - The PrintWriter to use for logging

isStartTransactionBeforeConnection

public boolean isStartTransactionBeforeConnection()
When enabled (default), this property causes transactions to be retrieved within the context of a transaction. Most application servers behave this way. Some, such as IBM WebSphere when combined with the Oracle database driver, require the connection to be retrieved and manipulated (setAutoCommit(false)) outside of the transaction scope.

Returns:
true if enabled.

setStartTransactionBeforeConnection

public void setStartTransactionBeforeConnection(boolean startTransactionBeforeConnection)
When enabled (default), this property causes transactions to be retrieved within the context of a transaction. Most application servers behave this way. Some, such as IBM WebSphere when combined with the Oracle database driver, require the connection to be retrieved and manipulated (setAutoCommit(false)) outside of the transaction scope.

Parameters:
startTransactionBeforeConnection -

log

public void log(java.lang.String s)
Deprecated. Use commons-logging

Sends a message to the log

Parameters:
s - The message to log

isCacheModelsEnabled

public boolean isCacheModelsEnabled()
A flag that determines whether cache models were enabled when this SqlMap was built.

Returns:
true if enabled, false otherwise.

setCacheModelsEnabled

public void setCacheModelsEnabled(boolean cacheModelsEnabled)
This is set by the builder of the SqlMap to flag whether cache models were enabled at the time of configuration.

Important: Setting this property to true will not dynamically enable cache models. This will only be set by the builder at build time, as a flag to determine whether caching was enabled.

Parameters:
cacheModelsEnabled - Will be set by the builder.

isDriverHintsEnabled

public boolean isDriverHintsEnabled()
Gets the status of whether executions should make use of driver hints for the size of result sets etc. (Some drivers don't support this).

Returns:
True if driverHintsEnabled. False otherwise.

setDriverHintsEnabled

public void setDriverHintsEnabled(boolean driverHintsEnabled)
Sets the status of whether executions should make use of driver hints for the size of result sets etc. (Some drivers don't support this).


isUseGlobalTransaction

public boolean isUseGlobalTransaction()
Returns true if global transaction support is enabled.

Returns:
True if global transactions are enabled, false if transactions are to be locally controlled.

setUseGlobalTransaction

public void setUseGlobalTransaction(boolean useGlobalTransaction)
Set to true if global transactions are available and should be used. Otherwise if transactions are locally controlled, set to false.

Parameters:
useGlobalTransaction - true or false to enable or disable global transactions respectively.

isUseFullyQualifiedStatementNames

public boolean isUseFullyQualifiedStatementNames()
Flag to determine whether fully qualified statement names are being used.

Returns:
True if statement names are fully qualified (sqlMapName.statementName)

setUseFullyQualifiedStatementNames

public void setUseFullyQualifiedStatementNames(boolean useFullyQualifiedStatementNames)
Sets fully qualified names or not. NOTE: This is not a dynamic property. If you change it after the initial building of the SQL Map, changes will not be applied. This property is only valid during the building of the SQL Map.

Parameters:
useFullyQualifiedStatementNames - Set to true by SqlMap builder if statement names are fully qualified, otherwise set to false.

isCachePreparedStatement

public boolean isCachePreparedStatement()
Deprecated. Use getStatementCacheSize()

Returns:
getStatementCacheSize > 0

setCachePreparedStatement

public void setCachePreparedStatement(boolean cachePreparedStatement)
Deprecated. Use setStatementCacheSize(int size)

Parameters:
cachePreparedStatement - setStatementCacheSize(0) if false.

getStatementCacheSize

public int getStatementCacheSize()
Getter for size of statement cache

Returns:
Current size of cache

setStatementCacheSize

public void setStatementCacheSize(int statementCacheSize)
Setter for size of statement cache

Parameters:
statementCacheSize - New size for the cache

getDataCacheStats

public java.lang.String getDataCacheStats()

getStatementCacheHitRatio

public java.lang.Double getStatementCacheHitRatio()

flushCache

public void flushCache()
Flushes all cached objects that belong to this SqlMap


addExecuteListener

public void addExecuteListener(ExecuteListener listener)

addDataSource

public void addDataSource(java.lang.String name,
                          javax.sql.DataSource dataSource)
Adds a named datasource to the list of available datasources

Parameters:
name - The name of the data source
dataSource - The data source

getDataSource

public javax.sql.DataSource getDataSource(java.lang.String name)
Gets a named datasource from the list of available datasources

Parameters:
name - The name of the data source
Returns:
The datasource

getCurrentDataSource

public javax.sql.DataSource getCurrentDataSource()
Returns the current data source

Returns:
The data source

getStatementFactory

public StatementFactory getStatementFactory()
Getter for the StatementFactory

Returns:
The StatementFactory

getMappedStatement

public MappedStatement getMappedStatement(java.lang.String name)
Gets a MappedStatement by name

Parameters:
name - The name of the statement
Returns:
The MappedStatement

getMappedStatementNames

public java.util.Iterator getMappedStatementNames()
Returns a Iterator containing the names of the mapped statements owned by this SqlMap

Returns:
Iterator of mapped statement names.

addMappedStatement

public void addMappedStatement(MappedStatement mappedStatement)
Adds a (named) MappedStatement.

Parameters:
mappedStatement - The statement to add

getCache

public CacheModel getCache(java.lang.String name)
Gets a cache by name

Parameters:
name - The name of the cache to get
Returns:
The cache object

addCache

public void addCache(CacheModel cache)
Adds a (named) cache.

Parameters:
cache - The cache to add

getCaches

public java.util.Iterator getCaches()
Returns an iterator to step through the available caches for the SqlMap

Returns:
The iterator

getParameterMap

public ParameterMap getParameterMap(java.lang.String name)
Gets a ParameterMap by name

Parameters:
name - The name of the ParameterMap
Returns:
The ParameterMap

addParameterMap

public void addParameterMap(ParameterMap parameterMap)
Adds a (named) ParameterMap.

Parameters:
parameterMap - the ParameterMap to add

getResultMap

public ResultMap getResultMap(java.lang.String name)
Gets a ResultMap by name

Parameters:
name - The name of the result map
Returns:
The ResultMap

addResultMap

public void addResultMap(ResultMap resultMap)
Adds a (named) ResultMap

Parameters:
resultMap - The ResultMap to add

getCurrentDataSourceName

public java.lang.String getCurrentDataSourceName()
Getter for the current data source name

Returns:
The name of the current data source

setCurrentDataSourceName

public void setCurrentDataSourceName(java.lang.String currentDataSourceName)
Setter for the current data source

Parameters:
currentDataSourceName - The new current data source

getConnectionFromCurrentDataSource

private java.sql.Connection getConnectionFromCurrentDataSource()
                                                        throws java.sql.SQLException
Throws:
java.sql.SQLException

closeConnection

private void closeConnection(java.sql.Connection connection)
                      throws java.sql.SQLException
Throws:
java.sql.SQLException

setCurrentLocalConnection

private void setCurrentLocalConnection(java.sql.Connection connection)

getCurrentLocalConnection

public java.sql.Connection getCurrentLocalConnection()

removeCurrentLocalConnection

private java.sql.Connection removeCurrentLocalConnection()

startTransaction

public void startTransaction()
                      throws java.sql.SQLException
Starts a new transaction.

Throws:
java.sql.SQLException - If a transaction has already been started, or if a database exception is thrown.

commitTransaction

public void commitTransaction()
                       throws java.sql.SQLException
Commits the current transaction

Throws:
java.sql.SQLException - If a database exception is thrown, or no transaction is in progress

rollbackTransaction

public void rollbackTransaction()
                         throws java.sql.SQLException
Rolls back the current transaction

Throws:
java.sql.SQLException - If a database exception is thrown

executeUpdate

public int executeUpdate(java.lang.String statementName,
                         java.lang.Object parameterObject)
                  throws java.sql.SQLException
Executes a update using a MappedStatement and a parameter object

Parameters:
statementName - The name of the MappedStatement to execute
parameterObject - The parameter object used by the MappedStatement
Returns:
The number of rows updated
Throws:
java.sql.SQLException - If a transaction has not been started, or a database exception is thrown

executeQueryForObject

public java.lang.Object executeQueryForObject(java.lang.String statementName,
                                              java.lang.Object parameterObject)
                                       throws java.sql.SQLException
Executes a MappedStatement that returns a single object

Parameters:
statementName - The name of the MappedStatement
parameterObject - The parameter object used by the MappedStatement
Returns:
The object
Throws:
java.sql.SQLException - If a transaction is not in progress, or the database throws an exception

executeQueryForObject

public java.lang.Object executeQueryForObject(java.lang.String statementName,
                                              java.lang.Object parameterObject,
                                              java.lang.Object resultObject)
                                       throws java.sql.SQLException
Executes a MappedStatement that returns a single object of the type of the resultObject parameter.

Parameters:
resultObject - An object of the type to be returned
statementName - The name of the MappedStatement
parameterObject - The parameter object used by the MappedStatement
Returns:
The object
Throws:
java.sql.SQLException - If a transaction is not in progress, or the database throws an exception

executeQueryForMap

public java.util.Map executeQueryForMap(java.lang.String statementName,
                                        java.lang.Object parameterObject,
                                        java.lang.String keyProperty)
                                 throws java.sql.SQLException
Executes the SQL and retuns all rows selected in a map that is keyed on the property named in the keyProperty parameter. The value at each key will be the entire result object.

Parameters:
parameterObject - The object used to set the parameters in the SQL
keyProperty - The property of the result object to be used as the key
Returns:
A Map of beans containing the rows keyed by keyProperty
Throws:
java.sql.SQLException - If an exception occurs in the database

executeQueryForMap

public java.util.Map executeQueryForMap(java.lang.String statementName,
                                        java.lang.Object parameterObject,
                                        java.lang.String keyProperty,
                                        java.lang.String valueProperty)
                                 throws java.sql.SQLException
Executes the SQL and retuns all rows selected in a map that is keyed on the property named in the keyProperty parameter. The value at each key will be the value of the property specified in the valueProperty parameter. If valueProperty is null, the entire result object will be entered.

Parameters:
parameterObject - The object used to set the parameters in the SQL
keyProperty - The property of the result object to be used as the key
valueProperty - The property of the result object to be used as the value (or null)
Returns:
A Map of beans containing the rows keyed by keyProperty
Throws:
java.sql.SQLException - If an exception occurs in the database

executeQueryForList

public java.util.List executeQueryForList(java.lang.String statementName,
                                          java.lang.Object parameterObject)
                                   throws java.sql.SQLException
Executes the SQL and retuns all rows selected.

Parameters:
statementName - The name of the MappedStatement to execute
parameterObject - The object used to set the parameters in the SQL
Returns:
A List of beans containing the rows
Throws:
java.sql.SQLException - If an exception occurs in the database

executeQueryForList

public java.util.List executeQueryForList(java.lang.String statementName,
                                          java.lang.Object parameterObject,
                                          int skipResults,
                                          int maxResults)
                                   throws java.sql.SQLException
Executes the SQL and retuns all rows selected.

Parameters:
statementName - The name of the MappedStatement to execute
parameterObject - The object used to set the parameters in the SQL
skipResults - The number of rows to skip over
maxResults - The maximum number of rows to return
Returns:
A List of beans containing the rows
Throws:
java.sql.SQLException - If an exception occurs in the database

executeQueryForPaginatedList

public PaginatedList executeQueryForPaginatedList(java.lang.String statementName,
                                                  java.lang.Object parameterObject,
                                                  int pageSize)
                                           throws java.sql.SQLException
Executes the SQL and retuns a subset of the results in a dynamic PaginatedList that can be used to automatically scroll through results from a database table.

Parameters:
parameterObject - The object used to set the parameters in the SQL
pageSize - The maximum number of objects to store in each page
Returns:
A PaginatedList of beans containing the rows
Throws:
java.sql.SQLException - If an exception occurs in the database

executeQueryWithRowHandler

public void executeQueryWithRowHandler(java.lang.String statementName,
                                       java.lang.Object parameterObject,
                                       RowHandler rowHandler)
                                throws java.sql.SQLException
Runs a query with a custom object that gets a chance to deal with each row as it is processed.

Parameters:
statementName - The name of the MappedStatement to execute
parameterObject - The parameter object mapped the the statement
rowHandler - The custom row handler object
Throws:
java.sql.SQLException - If an exception occurs in the database

startBatch

public void startBatch()
                throws java.sql.SQLException
Sets up a 'batch' of update statements to execute using a more efficient call to the database.

Throws:
java.sql.SQLException - If the database throws an exception

endBatch

public void endBatch()
              throws java.sql.SQLException
Executes a 'batch' of statements as a single transaction

Throws:
java.sql.SQLException - If the database throws an exception

isInsideBatch

public boolean isInsideBatch()
Flag indicating that we are in the middle of creating or running a batch

Returns:
If we are in the middle of creating or running a batch

incrementTransactionThrottle

private void incrementTransactionThrottle()

decrementTransactionThrottle

private void decrementTransactionThrottle()

registerStatementWithBatch

void registerStatementWithBatch(MappedStatement mappedStatement,
                                java.sql.PreparedStatement ps)

getStatementFromBatch

java.sql.PreparedStatement getStatementFromBatch(MappedStatement mappedStatement)

incrementExecutionThrottle

void incrementExecutionThrottle(java.sql.Connection conn)

decrementExecutionThrottle

void decrementExecutionThrottle(java.sql.Connection conn)