org.jlf.dataMap.jdbcMap
Class JDBCDataMapper

java.lang.Object
  |
  +--org.jlf.dataMap.DataMapper
        |
        +--org.jlf.dataMap.CRUDDataMapper
              |
              +--org.jlf.dataMap.jdbcMap.JDBCDataMapper

public class JDBCDataMapper

extends CRUDDataMapper

This class is used to map DataMappedObjects to a JDBC data source/sink.

The following properties in the data location property file define how to connect to a JDBC database and also map objects to that database:

DataMapperClass tells the name of the Java class that is the data mapper for the property file (typically JDBC or XML).

ConnectionProperties is a hash table of properties to be passed in to JDBC to create a connection.

The name of the class to be data mapped prefixed to attributeAlias.{attribute name} allows you to have a different attribute name in the Java code than the column name in the database. The framework will map columns to java attribute names with this override. The name of the class to be data mapped to a JDBC data source/since prefixes the following properties:

criteriaKey.createStatement.sqlStatement specifies the SQL statement to be executed when the object is created for the first time. Specify createStatement2, createStatement3, ... to execute more than one SQL statement for a single object creation.

criteriaKey.updateStatement.sqlStatement specifies the SQL statement to be executed when the object is updated. Specify updateStatement2, updateStatement3, ... to execute more than one SQL statement for a single object update.

criteriaKey.deleteStatement.sqlStatement specifies the SQL statement to be executed when the object is deleted. Specify deleteStatement2, deleteStatement3, ... to execute more than one SQL statement for a single object delete.

In the above criteria keys, you can override the default statement from an execute statement to a query statement (in which any return values are mapped back to the object created/updated/deleted) by setting criteriaKey..isQuery=true

criteriaKey.optimisticLockingStatement.sqlStatement specifies the SQL statement to be executed when the object is to be optimistically locked. If present, this statement is a Query to be executed before an object is updated or deleted. If the query returns at least one row, the object has not been modified since it was read (use this statement to check a timestamp or set of attributes and validate the object is not dirty!).

Example Property File:

 ####################
 # This property defines the data mapping class (JDBC) for this property file
 DataMapperClass=org.jlf.dataMap.jdbcMap.JDBCDataMapper

 ####################
 # These properties define the connection

 ConnectionProperties.DriverClass=oracle.jdbc.driver.OracleDriver
 ConnectionProperties.DatabaseURL=jdbc:oracle:thin:@dbmachine:1521:dbinstance
 ConnectionProperties.user=cti
 ConnectionProperties.password=cti

 

See Also:

DataLocation, DataMapper

Field Summary

protected boolean	autoCommitCleared Holds a flag on the connection to see if it has already been placed in a state where it will not auto-commit.
protected java.sql.Connection	connection Holds a JDBC Connection to the database.
protected static java.lang.String	CRITERIA_KEY_PROPERTY_QUALIFIER
static java.lang.String	DEFAULT_CREATE_CRITERIA_KEY The default criteria key for finding a JDBC statement to create an object in the database.
static java.lang.String	DEFAULT_DELETE_CRITERIA_KEY The default criteria key for finding a JDBC statement to delete an object in the database.
static java.lang.String	DEFAULT_UPDATE_CRITERIA_KEY The default criteria key for finding a JDBC statement to update an object in the database.
static java.lang.String	JDBC_CREATE_INFO_KEY_PROPERTY The property suffix in the DataLocation to use as the create info key.
static java.lang.String	JDBC_DATABASE_URL_PROPERTY The property suffix in the DataLocation to use as the database URL to load.
static java.lang.String	JDBC_DELETE_INFO_KEY_PROPERTY The property suffix in the DataLocation to use as the delete info key.
static java.lang.String	JDBC_DRIVER_CLASS_PROPERTY The property suffix in the DataLocation to use as the Java JDBC driver to load.
static java.lang.String	JDBC_UPDATE_INFO_KEY_PROPERTY The property suffix in the DataLocation to use as the update info key.
static java.lang.String	OPTIMISTIC_LOCK_CRITERIA_KEY The criteria key for an optimistic lock check when updating/deleting a data mapped object.
protected java.sql.ResultSet	resultSet Holds a JDBC Result Set from the database.
protected static java.lang.String	SQL_STATEMENT_PROPERTY_SUFFIX
protected static java.lang.String	SQL_STATEMENT_QUERY_FLAG_PROPERTY_SUFFIX

Fields inherited from class org.jlf.dataMap.CRUDDataMapper

postCommitUpdateObjects

Fields inherited from class org.jlf.dataMap.DataMapper

dataArray, dataLocation

Constructor Summary

JDBCDataMapper()
Allow the default constructor, please use a parameterized constructor!

JDBCDataMapper(DataLocation dataLocation)
Constructs a new data mapper which references back to the DataLocation who created it.

Method Summary

protected void	clearAutoCommit() Clears auto-commit (sets to false), using a flag to keep track so it is not done more than once.
void	close() Close the connection to the JDBC data source.
protected java.util.Vector	columnsFromResultSet() Retrieves the column names from a ResultSet and places them, in order, into a Vector.
void	commitWrites() Updates objects in the postCommitUpdateObjects collection after a successful commit.
void	create(DataMappedObject dmo, Relationship relationship) This method is an abstract method that must be overridden to support object creation in the data location.
protected void	createConnection() Creates a JDBC Connection to the database driver and properties specified in the DataLocation's set of properties.
void	delete(DataMappedObject dmo, Relationship relationship) This method is an abstract method that must be overridden to support deletions of an object already created in the data location.
java.util.Vector	executeDynamicQuery(DataMappedObject dmo, java.lang.String dynamicSQLStatement) This method can be used to execute a dynamic SQL query, rather than one defined in a property file.
java.util.Vector	executeQuery(DataMappedObject dmo, java.lang.String criteriaKey, boolean updateOnly) This method is a helper method to execute a query and map the results to one or more objects.
void	executeStatement(DataMappedObject dmo, java.lang.String criteriaKey) This method is a helper method to execute a statement.
java.util.Vector	findBySearchCriteria(DataMappedObject dmo, java.lang.String criteriaKey) This method reads any number of objects from the JDBC connection according to the DataMappedObject's type and search criteria.
java.sql.Connection	getConnection() Retrieves the JDBC connection to the data source.
protected java.sql.Statement	getStatement(DataMappedObject dmo, java.lang.String criteriaKey) Retrieves a statement from the connection and configures its properties (for example, max result set rows, query timeout) according to properties found in the data location.
protected boolean	isWriteStatementAQuery(DataMappedObject dmo, java.lang.String writeStatementCriteriaKey) Checks to see if the data location has a
protected void	populateDataArray(java.util.Vector columns) Populates the internal dataArray variable from the current ResultSet row.
void	processOptimisticLock(DataMappedObject dmo) This method processes a SQL statement that checks one or more attributes of the object to see if a change has been made to the object after it was initially read (to alert of a dirty read).
protected void	processWriteStatement(DataMappedObject dmo, java.lang.String writeStatementCriteriaKey) Processes one SQL write statement (or query if need be for things like retrieving a synthetic key on create or retriving a locking timestamp create or update).
protected void	processWriteStatements(DataMappedObject dmo, java.lang.String writeKeySuffix, java.lang.String defaultWriteKeyValue) Processes a set of SQL write statements (and queries if need be for things like retrieving a synthetic key on create or retriving a locking timestamp create or update).
protected java.util.Vector	resultSetToObjects(DataMappedObject dmo) Maps a JDBC ResultSet to a set of one or more DataMappedObjects and returns them.
protected java.lang.String	retrieveWriteStatement(DataMappedObject dmo, java.lang.String writeStatementKey) Given a write statement key, checks to see if a SQL statement is available.
protected java.lang.String	retrieveWriteStatementKey(DataMappedObject dmo, java.lang.String writeKeySuffix, java.lang.String defaultWriteKeyValue) Retrieves a write statement key if one is found in the data location set of properties.
void	rollbackWrites() Rolls back the JDBC connection but doesn't clean up, as cleaning up would make it look like the transaction was properly committed.
protected java.lang.String	sqlStringForCriteria(DataMappedObject dmo, java.lang.String criteriaKey) Retrieves a SQL string from the data location, for the object and criteria key given as input.
void	update(DataMappedObject dmo, Relationship relationship) This method is an abstract method that must be overridden to support updates to objects already existing in the data location.
protected void	updateObjectFromResultSet(DataMappedObject dmo) Maps a JDBC ResultSet containing any number of update attributes to a data mapped object.

Methods inherited from class org.jlf.dataMap.CRUDDataMapper

addPostCommitUpdate, write, writeWithoutCascade

Methods inherited from class org.jlf.dataMap.DataMapper

findDataAttributeForReplacementString, getCascadedRelationships, getDataLocation, replaceAttributeParameters, setDataLocation, stringForDataAttributeReplacement

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

JDBC_DRIVER_CLASS_PROPERTY

public static final java.lang.String JDBC_DRIVER_CLASS_PROPERTY

The property suffix in the DataLocation to use as the Java JDBC driver to load.

See Also:

Constant Field Values

JDBC_DATABASE_URL_PROPERTY

public static final java.lang.String JDBC_DATABASE_URL_PROPERTY

The property suffix in the DataLocation to use as the database URL to load.

See Also:

Constant Field Values

JDBC_CREATE_INFO_KEY_PROPERTY

public static final java.lang.String JDBC_CREATE_INFO_KEY_PROPERTY

The property suffix in the DataLocation to use as the create info key.

See Also:

Constant Field Values

JDBC_UPDATE_INFO_KEY_PROPERTY

public static final java.lang.String JDBC_UPDATE_INFO_KEY_PROPERTY

The property suffix in the DataLocation to use as the update info key.

See Also:

Constant Field Values

JDBC_DELETE_INFO_KEY_PROPERTY

public static final java.lang.String JDBC_DELETE_INFO_KEY_PROPERTY

The property suffix in the DataLocation to use as the delete info key.

See Also:

Constant Field Values

DEFAULT_CREATE_CRITERIA_KEY

public static final java.lang.String DEFAULT_CREATE_CRITERIA_KEY

The default criteria key for finding a JDBC statement to create an object in the database.

See Also:

Constant Field Values

DEFAULT_UPDATE_CRITERIA_KEY

public static final java.lang.String DEFAULT_UPDATE_CRITERIA_KEY

The default criteria key for finding a JDBC statement to update an object in the database.

See Also:

Constant Field Values

DEFAULT_DELETE_CRITERIA_KEY

public static final java.lang.String DEFAULT_DELETE_CRITERIA_KEY

The default criteria key for finding a JDBC statement to delete an object in the database.

See Also:

Constant Field Values

OPTIMISTIC_LOCK_CRITERIA_KEY

public static final java.lang.String OPTIMISTIC_LOCK_CRITERIA_KEY

The criteria key for an optimistic lock check when updating/deleting a data mapped object.

See Also:

Constant Field Values

connection

protected java.sql.Connection connection

Holds a JDBC Connection to the database.

resultSet

protected java.sql.ResultSet resultSet

Holds a JDBC Result Set from the database.

autoCommitCleared

protected boolean autoCommitCleared

Holds a flag on the connection to see if it has already been placed in a state where it will not auto-commit.

CRITERIA_KEY_PROPERTY_QUALIFIER

protected static final java.lang.String CRITERIA_KEY_PROPERTY_QUALIFIER

See Also:

Constant Field Values

SQL_STATEMENT_PROPERTY_SUFFIX

protected static final java.lang.String SQL_STATEMENT_PROPERTY_SUFFIX

See Also:

Constant Field Values

SQL_STATEMENT_QUERY_FLAG_PROPERTY_SUFFIX

protected static final java.lang.String SQL_STATEMENT_QUERY_FLAG_PROPERTY_SUFFIX

See Also:

Constant Field Values

Constructor Detail

JDBCDataMapper

public JDBCDataMapper()

Allow the default constructor, please use a parameterized constructor!

JDBCDataMapper

public JDBCDataMapper(DataLocation dataLocation)

Constructs a new data mapper which references back to the DataLocation who created it.

Method Detail

createConnection

protected void createConnection()

Creates a JDBC Connection to the database driver and properties specified in the DataLocation's set of properties.

getConnection

public java.sql.Connection getConnection()

Retrieves the JDBC connection to the data source.

clearAutoCommit

protected void clearAutoCommit()

Clears auto-commit (sets to false), using a flag to keep track so it is not done more than once.

close

public void close()

Close the connection to the JDBC data source.

Specified by:

close in class DataMapper

sqlStringForCriteria

protected java.lang.String sqlStringForCriteria(DataMappedObject dmo,
                                                java.lang.String criteriaKey)

Retrieves a SQL string from the data location, for the object and criteria key given as input.

getStatement

protected java.sql.Statement getStatement(DataMappedObject dmo,
                                          java.lang.String criteriaKey)

Retrieves a statement from the connection and configures its properties (for example, max result set rows, query timeout) according to properties found in the data location.

NOTE: The Statement generated here MUST be put in a try block with a finally block to close the statement under any circumstances after it is open!

columnsFromResultSet

protected java.util.Vector columnsFromResultSet()

Retrieves the column names from a ResultSet and places them, in order, into a Vector.

populateDataArray

protected void populateDataArray(java.util.Vector columns)

Populates the internal dataArray variable from the current ResultSet row.

Parameters:

columns - A vector of column names retrieved from the current result set. I pass this in for performance, don't want to re-read the column names each time we process a result set row.

resultSetToObjects

protected java.util.Vector resultSetToObjects(DataMappedObject dmo)

Maps a JDBC ResultSet to a set of one or more DataMappedObjects and returns them.

updateObjectFromResultSet

protected void updateObjectFromResultSet(DataMappedObject dmo)

Maps a JDBC ResultSet containing any number of update attributes to a data mapped object.

Zero or one result set rows are allowed here only, an update to an object should not process multiple result set rows!

executeDynamicQuery

public java.util.Vector executeDynamicQuery(DataMappedObject dmo,
                                            java.lang.String dynamicSQLStatement)

This method can be used to execute a dynamic SQL query, rather than one defined in a property file. The dynamic SQL query, passed in as a parameter to the method, can be parameterized with {} DataAttributes just like a SQL statement defined in a property file.

executeQuery

public java.util.Vector executeQuery(DataMappedObject dmo,
                                     java.lang.String criteriaKey,
                                     boolean updateOnly)

This method is a helper method to execute a query and map the results to one or more objects. If the updateOnly flag is set to true, only one result set row will be processed on the current object only, as an update to the object. If updateOnly is set to false, the method assumes the caller wants to fully populate new objects of the same type as the data mapped object passed in.

This method looks very ugly, but not much I can do about it because of error processing. Must ensure we close all resources here in a finally block, don't want to split this across methods.

Returns:

null if updateOnly, a vector of zero or more objects of type dmo if updateOnly is false.

findBySearchCriteria

public java.util.Vector findBySearchCriteria(DataMappedObject dmo,
                                             java.lang.String criteriaKey)

This method reads any number of objects from the JDBC connection according to the DataMappedObject's type and search criteria.

Specified by:

findBySearchCriteria in class DataMapper

executeStatement

public void executeStatement(DataMappedObject dmo,
                             java.lang.String criteriaKey)

This method is a helper method to execute a statement. No result set is processed, rather, the number of rows affected by the statement are logged instead.

This method looks very ugly, but not much I can do about it because of error processing. Must ensure we close all resources here in a finally block, don't want to split this across methods.

processOptimisticLock

public void processOptimisticLock(DataMappedObject dmo)

This method processes a SQL statement that checks one or more attributes of the object to see if a change has been made to the object after it was initially read (to alert of a dirty read).

This method looks very ugly, but not much I can do about it because of error processing. Must ensure we close all resources here in a finally block, don't want to split this across methods.

Throws:

DirtyReadError - thrown when the SQL statement executed does not return 1 and only 1 row (of any number of columns)

isWriteStatementAQuery

protected boolean isWriteStatementAQuery(DataMappedObject dmo,
                                         java.lang.String writeStatementCriteriaKey)

Checks to see if the data location has a

retrieveWriteStatementKey

protected java.lang.String retrieveWriteStatementKey(DataMappedObject dmo,
                                                     java.lang.String writeKeySuffix,
                                                     java.lang.String defaultWriteKeyValue)

Retrieves a write statement key if one is found in the data location set of properties. Returns the default given as a parameter if not found.

retrieveWriteStatement

protected java.lang.String retrieveWriteStatement(DataMappedObject dmo,
                                                  java.lang.String writeStatementKey)

Given a write statement key, checks to see if a SQL statement is available. Returns it if so, else returns null.

processWriteStatement

protected void processWriteStatement(DataMappedObject dmo,
                                     java.lang.String writeStatementCriteriaKey)

Processes one SQL write statement (or query if need be for things like retrieving a synthetic key on create or retriving a locking timestamp create or update). Two properties are needed here, one is the SQL statement critiera key (with a default passed in), second is an optional parameter to override the default where the typical statement is an update statement rather than a query statement.

processWriteStatements

protected void processWriteStatements(DataMappedObject dmo,
                                      java.lang.String writeKeySuffix,
                                      java.lang.String defaultWriteKeyValue)

Processes a set of SQL write statements (and queries if need be for things like retrieving a synthetic key on create or retriving a locking timestamp create or update). The set of statements are SQL statement criteria keys, and are found by looking up the dmo object class, plus the type of write (create, update, delete). Two properties are needed, one is the SQL statement critiera key (with a default passed in), second is an optional parameter to override the default where the typical statement is an update statement rather than a query statement.

create

public void create(DataMappedObject dmo,
                   Relationship relationship)

This method is an abstract method that must be overridden to support object creation in the data location.

Specified by:

create in class CRUDDataMapper

update

public void update(DataMappedObject dmo,
                   Relationship relationship)

This method is an abstract method that must be overridden to support updates to objects already existing in the data location.

Specified by:

update in class CRUDDataMapper

delete

public void delete(DataMappedObject dmo,
                   Relationship relationship)

This method is an abstract method that must be overridden to support deletions of an object already created in the data location.

Specified by:

delete in class CRUDDataMapper

rollbackWrites

public void rollbackWrites()

Rolls back the JDBC connection but doesn't clean up, as cleaning up would make it look like the transaction was properly committed.

Overrides:

rollbackWrites in class DataMapper

See Also:

DataMapper.rollbackWrites()

commitWrites

public void commitWrites()

Updates objects in the postCommitUpdateObjects collection after a successful commit. This method should be called as a super call from subclasses after everything goes well in a commit to the specific data sink.

Overrides:

commitWrites in class CRUDDataMapper