org.eclipse.persistence.internal.databaseaccess

Class DatabaseAccessor

java.lang.Object

org.eclipse.persistence.internal.databaseaccess.DatasourceAccessor

org.eclipse.persistence.internal.databaseaccess.DatabaseAccessor

All Implemented Interfaces:

java.lang.Cloneable, Accessor

public class DatabaseAccessor
extends DatasourceAccessor

INTERNAL: DatabaseAccessor is private to EclipseLink. It encapsulates low level database operations (such as executing SQL and reading data by row). Database accessor defines a protocol by which EclipseLink may invoke these operations.

DatabaseAccessor also defines a single reference through which all configuration dependent behavior may be invoked.

DabaseAccessor implements the following behavior.

• Connect and disconnect from the database.
• Execute SQL statements on the database, returning results.
• Handle auto-commit and transactions.

DatabaseAccessor dispatches the following protocols to its platform reference.

• Provision of database platform specific type names.

DatabaseAccessor dispatches the following protocols to the schema object.

• Creation and deletion of schema objects.

Since:

TOPLink/Java 1.0

See Also:

DatabasePlatform

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	shouldUseDynamicStatements PERF: Backdoor to disabling dynamic statements.

Fields inherited from class org.eclipse.persistence.internal.databaseaccess.DatasourceAccessor

READ_STATEMENTS_COUNT_PROPERTY, readStatementsCount, shouldCheckConnection, STOREDPROCEDURE_STATEMENTS_COUNT_PROPERTY, storedProcedureStatementsCount, WRITE_STATEMENTS_COUNT_PROPERTY, writeStatementsCount

Constructor Summary

Constructors

Constructor and Description
DatabaseAccessor()

Method Summary

Modifier and Type	Method and Description
java.sql.Statement	allocateDynamicStatement(java.sql.Connection connection) Allocate a statement for dynamic SQL execution.
void	basicBeginTransaction(AbstractSession session) Begin a transaction on the database.
void	basicCommitTransaction(AbstractSession session) Commit a transaction on the database.
java.lang.Object	basicExecuteCall(Call call, AbstractRecord translationRow, AbstractSession session) Execute the call.
void	basicRollbackTransaction(AbstractSession session) Rollback a transaction on the database.
AbstractRecord	buildOutputRow(java.sql.CallableStatement statement, DatabaseCall call, AbstractSession session) Build a row from the output parameters of a sp call.
java.util.Vector	buildSortedFields(java.util.Vector fields, java.sql.ResultSet resultSet, AbstractSession session) Return the field sorted in the correct order corresponding to the result set.
void	clearStatementCache(AbstractSession session) Flush the statement cache.
java.lang.Object	clone() Clone the accessor.
void	closeConnection() Close the accessor's connection.
void	closeCursor(java.sql.ResultSet resultSet, AbstractSession session) Close the result set of the cursored stream.
void	closeDatasourceConnection() Close the connection.
void	closeStatement(java.sql.Statement statement, AbstractSession session, DatabaseCall call) INTERNAL: Closes a PreparedStatement (which is supposed to close it's current resultSet).
void	commitTransaction(AbstractSession session) Commit a transaction on the database.
AbstractRecord	cursorRetrieveNextRow(java.util.Vector fields, java.sql.ResultSet resultSet, AbstractSession session) Advance the result set and return a Record populated with values from the next valid row in the result set.
AbstractRecord	cursorRetrievePreviousRow(java.util.Vector fields, java.sql.ResultSet resultSet, AbstractSession session) Advance the result set and return a DatabaseRow populated with values from the next valid row in the result set.
void	disconnect(AbstractSession session) Disconnect from the datasource.
java.lang.Object	executeCall(Call call, AbstractRecord translationRow, AbstractSession session) Execute the call.
java.lang.Integer	executeDirectNoSelect(java.sql.Statement statement, DatabaseCall call, AbstractSession session) Execute the statement.
java.sql.ResultSet	executeSelect(DatabaseCall call, java.sql.Statement statement, AbstractSession session) Execute the statement.
void	flushSelectCalls(AbstractSession session) Execute any deferred select calls stored in the LOBValueWriter instance.
BatchWritingMechanism	getActiveBatchWritingMechanism() INTERNAL: This method is used internally to return the active batch writing mechanism to batch the statement
java.util.Vector	getColumnInfo(java.lang.String catalog, java.lang.String schema, java.lang.String tableName, java.lang.String columnName, AbstractSession session) Get a description of table columns available in a catalog.
java.sql.Connection	getConnection() Return the receiver's connection to its data source.
java.sql.DatabaseMetaData	getConnectionMetaData() return the cached metaData
LOBValueWriter	getLOBWriter() Return the LOBValueWriter instance.
java.lang.Object	getObject(java.sql.ResultSet resultSet, DatabaseField field, java.sql.ResultSetMetaData metaData, int columnNumber, DatabasePlatform platform, boolean optimizeData, AbstractSession session) Return an object retrieved from resultSet with the getObject() method.
DatabasePlatform	getPlatform() Return the platform.
java.util.Vector	getTableInfo(java.lang.String catalog, java.lang.String schema, java.lang.String tableName, java.lang.String[] types, AbstractSession session) Get a description of tables available in a catalog.
boolean	isDatasourceConnected() Return true if the receiver is currently connected to a data source.
boolean	isDynamicStatementInUse() Return the cached statement for dynamic SQL execution is in use.
java.sql.Statement	prepareStatement(DatabaseCall call, AbstractSession session) Prepare the SQL statement for the call.
java.sql.Statement	prepareStatement(DatabaseCall call, AbstractSession session, boolean unwrapConnection) Prepare the SQL statement for the call.
DatabaseException	processExceptionForCommError(AbstractSession session, java.sql.SQLException exception, Call call) This method is used to process an SQL exception and determine if the exception should be passed on for further processing.
java.lang.Object	processResultSet(java.sql.ResultSet resultSet, DatabaseCall call, java.sql.Statement statement, AbstractSession session) Fetch all the rows from the result set.
void	releaseStatement(java.sql.Statement statement, java.lang.String sqlString, DatabaseCall call, AbstractSession session) Release the statement through closing it or putting it back in the statement cache.
void	rollbackTransaction(AbstractSession session) Rollback a transaction on the database.
void	setActiveBatchWritingMechanismToDynamicSQL() INTERNAL: This method is used to set the active Batch Mechanism on the accessor
void	setActiveBatchWritingMechanismToParameterizedSQL() INTERNAL: This method is used to set the active Batch Mechanism on the accessor
void	setDatasourcePlatform(DatasourcePlatform platform) Set the platform.
void	setIsDynamicStatementInUse(boolean isDynamicStatementInUse) Set if the cached statement for dynamic SQL execution is in use.
void	setShouldUseThreadCursors(boolean shouldUseThreadCursors) Set if thread cursors should be used for fetch the result row.
boolean	shouldUseThreadCursors() Return if thread cursors should be used for fetch the result row.
java.lang.String	toString()
void	writesCompleted(AbstractSession session) This method will be called after a series of writes have been issued to mark where a particular set of writes has completed.

Methods inherited from class org.eclipse.persistence.internal.databaseaccess.DatasourceAccessor

beginTransaction, closeJTSConnection, connect, createCustomizer, decrementCallCount, getCallCount, getDatasourceConnection, getDatasourcePlatform, getLogin, getPool, getReadStatementsCount, getSequencingCallback, getStoredProcedureStatementsCount, getWriteStatementsCount, incrementCallCount, isConnected, isInTransaction, isValid, reestablishConnection, releaseCustomizer, releaseCustomizer, reset, setIsValid, setPool, usesExternalConnectionPooling, usesExternalTransactionController

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

shouldUseDynamicStatements

public static boolean shouldUseDynamicStatements

PERF: Backdoor to disabling dynamic statements. Reverts to old prepared statement usage if set.

Constructor Detail

DatabaseAccessor

public DatabaseAccessor()

Method Detail

flushSelectCalls

public void flushSelectCalls(AbstractSession session)

Execute any deferred select calls stored in the LOBValueWriter instance. This method will typically be called by the CallQueryMechanism object. Bug 2804663.

Specified by:

flushSelectCalls in interface Accessor

Overrides:

flushSelectCalls in class DatasourceAccessor

See Also:

LOBValueWriter, DatasourceCallQueryMechanism.insertObject()

getLOBWriter

public LOBValueWriter getLOBWriter()

Return the LOBValueWriter instance. Lazily initialize the instance. Bug 2804663.

See Also:

LOBValueWriter

allocateDynamicStatement

public java.sql.Statement allocateDynamicStatement(java.sql.Connection connection)
                                            throws java.sql.SQLException

Allocate a statement for dynamic SQL execution. Either return the cached dynamic statement, or a new statement. This statement must be released after execution.

Throws:

java.sql.SQLException

isDynamicStatementInUse

public boolean isDynamicStatementInUse()

Return the cached statement for dynamic SQL execution is in use. Used to handle concurrency for the dynamic statement, this method must only be called from within a synchronized method/block.

setDatasourcePlatform

public void setDatasourcePlatform(DatasourcePlatform platform)

Set the platform. This should be set to the session's platform, not the connections which may not be configured correctly.

Overrides:

setDatasourcePlatform in class DatasourceAccessor

setIsDynamicStatementInUse

public void setIsDynamicStatementInUse(boolean isDynamicStatementInUse)

Set if the cached statement for dynamic SQL execution is in use. Used to handle concurrency for the dynamic statement.

basicBeginTransaction

public void basicBeginTransaction(AbstractSession session)
                           throws DatabaseException

Begin a transaction on the database. This means toggling the auto-commit option.

Throws:

DatabaseException

buildOutputRow

public AbstractRecord buildOutputRow(java.sql.CallableStatement statement,
                                     DatabaseCall call,
                                     AbstractSession session)
                              throws DatabaseException

Build a row from the output parameters of a sp call.

Throws:

DatabaseException

buildSortedFields

public java.util.Vector buildSortedFields(java.util.Vector fields,
                                          java.sql.ResultSet resultSet,
                                          AbstractSession session)
                                   throws DatabaseException

Return the field sorted in the correct order corresponding to the result set. This is used for cursored selects where custom sql was provided. If the fields passed in are null, this means that the field are not known and should be built from the column names. This case occurs for DataReadQuery's.

Throws:

DatabaseException

clearStatementCache

public void clearStatementCache(AbstractSession session)

Flush the statement cache. Each statement must first be closed.

clone

public java.lang.Object clone()

Clone the accessor.

Specified by:

clone in interface Accessor

Overrides:

clone in class DatasourceAccessor

closeCursor

public void closeCursor(java.sql.ResultSet resultSet,
                        AbstractSession session)
                 throws DatabaseException

Close the result set of the cursored stream.

Throws:

DatabaseException

closeStatement

public void closeStatement(java.sql.Statement statement,
                           AbstractSession session,
                           DatabaseCall call)
                    throws java.sql.SQLException

INTERNAL: Closes a PreparedStatement (which is supposed to close it's current resultSet). Factored out to simplify coding and handle exceptions.

Throws:

java.sql.SQLException

commitTransaction

public void commitTransaction(AbstractSession session)
                       throws DatabaseException

Commit a transaction on the database. First flush any batched statements.

Specified by:

commitTransaction in interface Accessor

Overrides:

commitTransaction in class DatasourceAccessor

Throws:

DatabaseException

basicCommitTransaction

public void basicCommitTransaction(AbstractSession session)
                            throws DatabaseException

Commit a transaction on the database. This means toggling the auto-commit option.

Throws:

DatabaseException

cursorRetrieveNextRow

public AbstractRecord cursorRetrieveNextRow(java.util.Vector fields,
                                            java.sql.ResultSet resultSet,
                                            AbstractSession session)
                                     throws DatabaseException

Advance the result set and return a Record populated with values from the next valid row in the result set. Intended solely for cursored stream support.

Throws:

DatabaseException

cursorRetrievePreviousRow

public AbstractRecord cursorRetrievePreviousRow(java.util.Vector fields,
                                                java.sql.ResultSet resultSet,
                                                AbstractSession session)
                                         throws DatabaseException

Advance the result set and return a DatabaseRow populated with values from the next valid row in the result set. Intended solely for scrollable cursor support.

Throws:

DatabaseException

closeDatasourceConnection

public void closeDatasourceConnection()
                               throws DatabaseException

Close the connection.

Throws:

DatabaseException

disconnect

public void disconnect(AbstractSession session)
                throws DatabaseException

Disconnect from the datasource. Added for bug 3046465 to ensure the statement cache is cleared

Specified by:

disconnect in interface Accessor

Overrides:

disconnect in class DatasourceAccessor

Throws:

DatabaseException

closeConnection

public void closeConnection()

Close the accessor's connection. This is used only for external connection pooling when it is intended for the connection to be reconnected in the future.

Specified by:

closeConnection in interface Accessor

Overrides:

closeConnection in class DatasourceAccessor

executeCall

public java.lang.Object executeCall(Call call,
                                    AbstractRecord translationRow,
                                    AbstractSession session)
                             throws DatabaseException

Execute the call. The execution can differ slightly depending on the type of call. The call may be parameterized where the arguments are in the translation row. The row will be empty if there are no parameters.

Specified by:

executeCall in interface Accessor

Overrides:

executeCall in class DatasourceAccessor

Returns:

depending of the type either the row count, row or vector of rows.

Throws:

DatabaseException

basicExecuteCall

public java.lang.Object basicExecuteCall(Call call,
                                         AbstractRecord translationRow,
                                         AbstractSession session)
                                  throws DatabaseException

Execute the call. The execution can differ slightly depending on the type of call. The call may be parameterized where the arguments are in the translation row. The row will be empty if there are no parameters.

Returns:

depending of the type either the row count, row or vector of rows.

Throws:

DatabaseException

processResultSet

public java.lang.Object processResultSet(java.sql.ResultSet resultSet,
                                         DatabaseCall call,
                                         java.sql.Statement statement,
                                         AbstractSession session)
                                  throws java.sql.SQLException

Fetch all the rows from the result set.

Throws:

java.sql.SQLException

executeDirectNoSelect

public java.lang.Integer executeDirectNoSelect(java.sql.Statement statement,
                                               DatabaseCall call,
                                               AbstractSession session)
                                        throws DatabaseException

Execute the statement.

Throws:

DatabaseException

executeSelect

public java.sql.ResultSet executeSelect(DatabaseCall call,
                                        java.sql.Statement statement,
                                        AbstractSession session)
                                 throws java.sql.SQLException

Execute the statement.

Throws:

java.sql.SQLException

getActiveBatchWritingMechanism

public BatchWritingMechanism getActiveBatchWritingMechanism()

INTERNAL: This method is used internally to return the active batch writing mechanism to batch the statement

getColumnInfo

public java.util.Vector getColumnInfo(java.lang.String catalog,
                                      java.lang.String schema,
                                      java.lang.String tableName,
                                      java.lang.String columnName,
                                      AbstractSession session)
                               throws DatabaseException

Get a description of table columns available in a catalog.

Only column descriptions matching the catalog, schema, table and column name criteria are returned. They are ordered by TABLE_SCHEM, TABLE_NAME and ORDINAL_POSITION.

Each column description has the following columns:

1. TABLE_CAT String => table catalog (may be null)
2. TABLE_SCHEM String => table schema (may be null)
3. TABLE_NAME String => table name
4. COLUMN_NAME String => column name
5. DATA_TYPE short => SQL type from java.sql.Types
6. TYPE_NAME String => Data source dependent type name
7. COLUMN_SIZE int => column size. For char or date types this is the maximum number of characters, for numeric or decimal types this is precision.
8. BUFFER_LENGTH is not used.
9. DECIMAL_DIGITS int => the number of fractional digits
10. NUM_PREC_RADIX int => Radix (typically either 10 or 2)
11. NULLABLE int => is NULL allowed?
    • columnNoNulls - might not allow NULL values
    • columnNullable - definitely allows NULL values
    • columnNullableUnknown - nullability unknown
12. REMARKS String => comment describing column (may be null)
13. COLUMN_DEF String => default value (may be null)
14. SQL_DATA_TYPE int => unused
15. SQL_DATETIME_SUB int => unused
16. CHAR_OCTET_LENGTH int => for char types the maximum number of bytes in the column
17. ORDINAL_POSITION int => index of column in table (starting at 1)
18. IS_NULLABLE String => "NO" means column definitely does not allow NULL values; "YES" means the column might allow NULL values. An empty string means nobody knows.

Specified by:

getColumnInfo in interface Accessor

Overrides:

getColumnInfo in class DatasourceAccessor

Parameters:

catalog - a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria

schemaPattern - a schema name pattern; "" retrieves those without a schema

tableNamePattern - a table name pattern

columnNamePattern - a column name pattern

Returns:

a Vector of DatabaseRows.

Throws:

DatabaseException

getConnection

public java.sql.Connection getConnection()
                                  throws DatabaseException

Return the receiver's connection to its data source. A connection is used to execute queries on, and retrieve data from, a data source.

Specified by:

getConnection in interface Accessor

Overrides:

getConnection in class DatasourceAccessor

Throws:

DatabaseException

See Also:

Connection

getPlatform

public DatabasePlatform getPlatform()

Return the platform.

getConnectionMetaData

public java.sql.DatabaseMetaData getConnectionMetaData()
                                                throws java.sql.SQLException

return the cached metaData

Throws:

java.sql.SQLException

getObject

public java.lang.Object getObject(java.sql.ResultSet resultSet,
                                  DatabaseField field,
                                  java.sql.ResultSetMetaData metaData,
                                  int columnNumber,
                                  DatabasePlatform platform,
                                  boolean optimizeData,
                                  AbstractSession session)
                           throws DatabaseException

Return an object retrieved from resultSet with the getObject() method. Optimize the get for certain type to avoid double conversion. NOTE: This method handles a virtual machine error thrown when retrieving times & dates from Oracle or Sybase.

Throws:

DatabaseException

getTableInfo

public java.util.Vector getTableInfo(java.lang.String catalog,
                                     java.lang.String schema,
                                     java.lang.String tableName,
                                     java.lang.String[] types,
                                     AbstractSession session)
                              throws DatabaseException

Get a description of tables available in a catalog.

Only table descriptions matching the catalog, schema, table name and type criteria are returned. They are ordered by TABLE_TYPE, TABLE_SCHEM and TABLE_NAME.

Each table description has the following columns:

1. TABLE_CAT String => table catalog (may be null)
2. TABLE_SCHEM String => table schema (may be null)
3. TABLE_NAME String => table name
4. TABLE_TYPE String => table type. Typical types are "TABLE", "VIEW", "SYSTEM TABLE", "GLOBAL TEMPORARY", "LOCAL TEMPORARY", "ALIAS", "SYNONYM".
5. REMARKS String => explanatory comment on the table

Note: Some databases may not return information for all tables.

Specified by:

getTableInfo in interface Accessor

Overrides:

getTableInfo in class DatasourceAccessor

Parameters:

catalog - a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria

schemaPattern - a schema name pattern; "" retrieves those without a schema

tableNamePattern - a table name pattern

types - a list of table types to include; null returns all types

Returns:

a Vector of DatabaseRows.

Throws:

DatabaseException

isDatasourceConnected

public boolean isDatasourceConnected()

Return true if the receiver is currently connected to a data source. Return false otherwise.

shouldUseThreadCursors

public boolean shouldUseThreadCursors()

Return if thread cursors should be used for fetch the result row. This allows the objects to be built while the rows are being fetched.

setShouldUseThreadCursors

public void setShouldUseThreadCursors(boolean shouldUseThreadCursors)

Set if thread cursors should be used for fetch the result row. This allows the objects to be built while the rows are being fetched.

prepareStatement

public java.sql.Statement prepareStatement(DatabaseCall call,
                                           AbstractSession session)
                                    throws java.sql.SQLException

Prepare the SQL statement for the call. First check if the statement is cached before building a new one. Currently the SQL string is used as the cache key, this may have to be switched if it becomes a performance problem.

Throws:

java.sql.SQLException

prepareStatement

public java.sql.Statement prepareStatement(DatabaseCall call,
                                           AbstractSession session,
                                           boolean unwrapConnection)
                                    throws java.sql.SQLException

Prepare the SQL statement for the call. First check if the statement is cached before building a new one.

Parameters:

unwrapConnection - boolean flag set to true to unwrap the connection before preparing the statement in the case of a parameterized call.

Throws:

java.sql.SQLException

processExceptionForCommError

public DatabaseException processExceptionForCommError(AbstractSession session,
                                                      java.sql.SQLException exception,
                                                      Call call)

This method is used to process an SQL exception and determine if the exception should be passed on for further processing. If the Exception was communication based then a DatabaseException will be return. If the method did not process the message of it was not a comm failure then null will be returned.

releaseStatement

public void releaseStatement(java.sql.Statement statement,
                             java.lang.String sqlString,
                             DatabaseCall call,
                             AbstractSession session)
                      throws java.sql.SQLException

Release the statement through closing it or putting it back in the statement cache.

Throws:

java.sql.SQLException

rollbackTransaction

public void rollbackTransaction(AbstractSession session)
                         throws DatabaseException

Rollback a transaction on the database. This means toggling the auto-commit option.

Specified by:

rollbackTransaction in interface Accessor

Overrides:

rollbackTransaction in class DatasourceAccessor

Throws:

DatabaseException

basicRollbackTransaction

public void basicRollbackTransaction(AbstractSession session)
                              throws DatabaseException

Rollback a transaction on the database. This means toggling the auto-commit option.

Throws:

DatabaseException

setActiveBatchWritingMechanismToParameterizedSQL

public void setActiveBatchWritingMechanismToParameterizedSQL()

INTERNAL: This method is used to set the active Batch Mechanism on the accessor

setActiveBatchWritingMechanismToDynamicSQL

public void setActiveBatchWritingMechanismToDynamicSQL()

INTERNAL: This method is used to set the active Batch Mechanism on the accessor

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

writesCompleted

public void writesCompleted(AbstractSession session)

This method will be called after a series of writes have been issued to mark where a particular set of writes has completed. It will be called from commitTransaction and may be called from writeChanges. Its main purpose is to ensure that the batched statements have been executed

Specified by:

writesCompleted in interface Accessor

Overrides:

writesCompleted in class DatasourceAccessor