org.opensubsystems.core.persist.db
Class DatabaseReadOperation

java.lang.Object
  org.opensubsystems.core.persist.db.DatabaseOperation
      org.opensubsystems.core.persist.db.DatabaseReadOperation

All Implemented Interfaces:

DatabaseOperations

Direct Known Subclasses:

DatabaseReadMultipleOperation, DatabaseReadSingleDataObjectOperation

public abstract class DatabaseReadOperation
extends DatabaseOperation
implements DatabaseOperations

Adapter to simplify writing of database reads, which takes care of requesting and returning connections, transaction management and exception handling. To use this adapter you just need to define anonymous class and override method performOperation to provide the actual database read. Optionally you may want to override one of the handleXXX methods to provide custom error handling. Example of method in factory which reads data using query produced by its schema public DataObject get( final int iDomainId, final int iId ) throws OSSException { DatabaseReadOperation dbop = new DatabaseReadOperation( this, m_schema.getSelectMyDataById(MyDatabaseSchema.MYDATA_COLUMNS), m_schema, dataType) { protected Object performOperation( DatabaseFactoryImpl dbfactory, Connection cntConnection, PreparedStatement pstmQuery ) throws OSSException, SQLException { pstmQuery.setInt(1, iId); pstmQuery.setInt(2, iDomainId); return DatabaseUtils.loadAtMostOneData(dbfactory, pstmQuery, "Multiple records loaded from database for domain ID " + iDomainId + " and ID " + iId); } }; return (DataObject)dbop.executeRead(); }

Version:

$Id: DatabaseReadOperation.java,v 1.11 2007/01/28 06:54:42 bastafidli Exp $

Author:

Miro Halas

Code reviewer:

Miro Halas

Code reviewed:

1.5 2006/07/25 23:57:55 jlegen

Field Summary

Fields inherited from class org.opensubsystems.core.persist.db.DatabaseOperation

m_data, m_dbschema, m_factory, m_iDataType, m_returnData, m_strQuery

Fields inherited from interface org.opensubsystems.core.persist.db.DatabaseOperations

DBOP_DELETE, DBOP_INSERT, DBOP_SELECT, DBOP_UPDATE

Constructor Summary

DatabaseReadOperation(DatabaseFactoryImpl factory)
Constructor to use when the database read doesn't require any prepared statement.

DatabaseReadOperation(DatabaseFactoryImpl factory, java.lang.String strQueryToPrepare, DatabaseSchema schema)
Copy constructor to use when database read doesn't require any prepared statement.

DatabaseReadOperation(DatabaseFactoryImpl factory, java.lang.String strQueryToPrepare, DatabaseSchema schema, int dataType)
Constructor to use when database read doesn't require any prepared statement.

Method Summary

java.lang.Object	executeRead() Method to execute database read invoking the user defined code in performOperation.
protected void	handleKnownError(OSSException exc, java.sql.Connection cntConnection, int iOperationType, int iDataType, java.lang.Object data) Override this method to provide any custom error handling for expected error, which were most likely produced by lower layer.
protected void	handleSQLException(java.sql.SQLException sqleExc, java.sql.Connection cntConnection, int iOperationType, int iDataType, java.lang.Object data) Provide custom handling of SQL Exceptions to usually detect constraint violation.
protected void	handleUnknownError(java.lang.Throwable thr, java.sql.Connection cntConnection, int iOperationType, int iDataType, java.lang.Object data) Override this method to provide any custom error handling for unexpected error, which weren't handled by lower layer.
protected java.lang.Object	performOperation(DatabaseFactoryImpl dbfactory, java.sql.Connection cntConnection, java.sql.PreparedStatement pstmStatement) Define content of this method to perform the database operation using the provided connection and optional prepared statement.
protected java.sql.PreparedStatement	prepareQuery(DatabaseFactoryImpl dbfactory, java.sql.Connection cntConnection, java.lang.String strQuery) Prepare the query if it was specified using the provided connection.

Methods inherited from class org.opensubsystems.core.persist.db.DatabaseOperation

getReturnData, setReturnData

Methods inherited from class java.lang.Object

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

Constructor Detail

DatabaseReadOperation

public DatabaseReadOperation(DatabaseFactoryImpl factory)

Constructor to use when the database read doesn't require any prepared statement.

Parameters:

factory - - factory which is executing this operation

DatabaseReadOperation

public DatabaseReadOperation(DatabaseFactoryImpl factory,
                             java.lang.String strQueryToPrepare,
                             DatabaseSchema schema,
                             int dataType)

Constructor to use when database read doesn't require any prepared statement. There are contained attributes related to handling SQL errors.

Parameters:

factory - - factory which is executing this operation

strQueryToPrepare - - query which should be used to construct prepared statement which will be passed in to executeUpdate

schema - - database schema used with this operation

dataType - - data type used with operation

DatabaseReadOperation

public DatabaseReadOperation(DatabaseFactoryImpl factory,
                             java.lang.String strQueryToPrepare,
                             DatabaseSchema schema)

Copy constructor to use when database read doesn't require any prepared statement. There are contained attributes related to handling SQL errors.

Parameters:

factory - - factory which is executing this operation

strQueryToPrepare - - query which should be used to construct prepared statement which will be passed in to executeUpdate

schema - - database schema used with this operation

Method Detail

executeRead

public java.lang.Object executeRead()
                             throws OSSException

Method to execute database read invoking the user defined code in performOperation.

Returns:

Object - data read from the database

Throws:

OSSException - - an error has occured

prepareQuery

protected java.sql.PreparedStatement prepareQuery(DatabaseFactoryImpl dbfactory,
                                                  java.sql.Connection cntConnection,
                                                  java.lang.String strQuery)
                                           throws OSSException,
                                                  java.sql.SQLException

Prepare the query if it was specified using the provided connection.

Parameters:

dbfactory - - database factory executing this operation

cntConnection - - ready to use connection to perform the database operation. No need to return this connection.

strQuery - - query to prepare, might be null or empty if there is nothing to prepare

Returns:

PreparedStatement - prepared statement for query passed in as a parameter to the constructor. If no query was passed into constructor, this will be null.

Throws:

OSSException - - an error has occured

java.sql.SQLException - - an error has occured

performOperation

protected java.lang.Object performOperation(DatabaseFactoryImpl dbfactory,
                                            java.sql.Connection cntConnection,
                                            java.sql.PreparedStatement pstmStatement)
                                     throws OSSException,
                                            java.sql.SQLException

Define content of this method to perform the database operation using the provided connection and optional prepared statement.

Parameters:

dbfactory - - database factory executing this operation

cntConnection - - ready to use connection to perform the database operation. No need to return this connection.

pstmStatement - - prepared statement for query passed in as a parameter to the constructor. No need to close this statement. If no query was passed into constructor, this will be null.

Returns:

Object - data read from the database accessible through getReturnData

Throws:

OSSException - - an error has occured

java.sql.SQLException - - an error has occured

handleSQLException

protected void handleSQLException(java.sql.SQLException sqleExc,
                                  java.sql.Connection cntConnection,
                                  int iOperationType,
                                  int iDataType,
                                  java.lang.Object data)
                           throws OSSException

Provide custom handling of SQL Exceptions to usually detect constraint violation. By default just handle it as unknown error.

Parameters:

sqleExc - - SQLException to handle

cntConnection - - ready to use connection to perform the database operation. No need to return this connection.

iOperationType - - type of the operation that caused the exception, see DatabaseOperations for possible values

iDataType - - data type the data object represents (e.g if this is type user and data is Integer, that means it is id of user object). This is one of the DataConstant constants.

data - - data object the exception is handled for

Throws:

OSSException - - properly handled exception

handleKnownError

protected void handleKnownError(OSSException exc,
                                java.sql.Connection cntConnection,
                                int iOperationType,
                                int iDataType,
                                java.lang.Object data)
                         throws OSSException

Override this method to provide any custom error handling for expected error, which were most likely produced by lower layer. The default implementation just propagates this error.

Parameters:

exc - - known error which must be handled.

cntConnection - - ready to use connection to perform the database operation. No need to return this connection.

iOperationType - - type of the operation that caused the exception, see DatabaseOperations for possible values

iDataType - - data type the data object represents (e.g if this is type user and data is Integer, that means it is id of user object). This is one of the DataConstant constants.

data - - data object the exception is handled for

Throws:

OSSException - - properly handled exception

handleUnknownError

protected void handleUnknownError(java.lang.Throwable thr,
                                  java.sql.Connection cntConnection,
                                  int iOperationType,
                                  int iDataType,
                                  java.lang.Object data)
                           throws OSSException

Override this method to provide any custom error handling for unexpected error, which weren't handled by lower layer. The default implementation wraps it in proper error.

Parameters:

thr - - throwable causing this error. This is not OSSException or a derived class.

cntConnection - - ready to use connection to perform the database operation. No need to return this connection.

iOperationType - - type of the operation that caused the exception, see DatabaseOperations for possible values

iDataType - - data type the data object represents (e.g if this is type user and data is Integer, that means it is id of user object). This is one of the DataConstant constants.

data - - data object the exception is handled for

Throws:

OSSException - - properly handled exception