org.jadetower.sql
Interface SQLEvaluator

All Known Implementing Classes:
VelocitySQLEvaluator

public interface SQLEvaluator

Evaluates a query.

Query parameters should be set via the set() or setContext() methods before the query is executed. Use of context map depends on implementing class.

The calling class has responsibility of closing the connection. If a result set is retrieved, you must use the close() method to properly close all statements and result sets.


Method Summary
 void clearContext()
          clears the current query context
 void close()
          closes all prepared statements or result sets.
 java.sql.ResultSet executeQuery(java.sql.Connection dbCon)
          executes the query given the database connection.
 java.util.Collection executeQuery(java.sql.Connection dbCon, java.lang.Class bean, java.util.Map beanMap)
          Execute the query and map the result set into a Collection of beans.
 int executeUpdate(java.sql.Connection dbCon)
          Executes an INSERT, UPDATE, or DELETE query.
 java.lang.String getSQL()
          returns the SQL statement to be executed.
 boolean isSQLMutable()
          determine if SQL query is mutable
 void set(java.lang.String key, java.lang.Object value)
          sets a value in the query context
 void setContext(java.util.Map map)
          sets all context values to those supplied by the given map.
 void setSQLMutable(boolean mutable)
          sets SQL statement and context mutablility.
 

Method Detail

set

public void set(java.lang.String key,
                java.lang.Object value)
sets a value in the query context

Parameters:
key - a query context key
value - appropriate value

setContext

public void setContext(java.util.Map map)
sets all context values to those supplied by the given map. This overrides any previously set values.

Parameters:
map - a context map

getSQL

public java.lang.String getSQL()
                        throws java.sql.SQLException
returns the SQL statement to be executed. If the context is not properly set the query may not be executable

Returns:
SQL statement as a String
Throws:
java.sql.SQLException - throw if there is an error generating or retrieving the SQL statement

executeQuery

public java.sql.ResultSet executeQuery(java.sql.Connection dbCon)
                                throws java.sql.SQLException
executes the query given the database connection. Note: You must explictly close the result set. Preferrably, call SQLEvaluator.close() to close all result sets and statements.

Parameters:
dbCon - a valid JDBC database connection
Returns:
a JDBC ResultSet
Throws:
java.sql.SQLException - thrown if an error is generated while executing the query statement. This can occur when the query is invalid or when query generation fails.

executeQuery

public java.util.Collection executeQuery(java.sql.Connection dbCon,
                                         java.lang.Class bean,
                                         java.util.Map beanMap)
                                  throws java.sql.SQLException
Execute the query and map the result set into a Collection of beans. Important notes about column names to bean properties mapping: All result sets and prepared statements are properly closed.

Parameters:
dbCon - a JDBC database connection
bean - a valid Java Bean class
beanMap - a map of COLUMN names to BEAN property names. May be null.
Returns:
a Collection of beans of type "bean"
Throws:
java.sql.SQLException - thrown if an error occurs in either query generation, query execution, or result set to bean mapping. See exeception message for details on exact cause.

executeUpdate

public int executeUpdate(java.sql.Connection dbCon)
                  throws java.sql.SQLException
Executes an INSERT, UPDATE, or DELETE query.

Parameters:
dbCon - JDBC database connection
Returns:
number of rows affected
Throws:
java.sql.SQLException - thrown if error occurred during either query generation or query execution.

setSQLMutable

public void setSQLMutable(boolean mutable)
sets SQL statement and context mutablility. If set false, then upon first generation of SQL statement, the query will be persisted between calls and not regenerated, meaning updates to the context will not take effect. It essentially makes the context and query 'read only.' Default is 'true.'

Parameters:
mutable - true if context can be changed, false if context is static.

isSQLMutable

public boolean isSQLMutable()
determine if SQL query is mutable

Returns:
true if mutable. Default is 'true.'
See Also:
setSQLMutable(boolean mutable)

clearContext

public void clearContext()
clears the current query context


close

public void close()
           throws java.sql.SQLException
closes all prepared statements or result sets. This includes ResultSets returned from executeQuery(Connection dbCon)

Throws:
java.sql.SQLException - thrown if error occurs during close.


Copyright © 2003 JadeTower. All Rights Reserved.