FileDocCategorySizeDatePackage
DatabaseAccessor.javaAPI DocGlassfish v2 API58600Tue May 22 16:54:20 BST 2007oracle.toplink.essentials.internal.databaseaccess

DatabaseAccessor

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

DatabaseAccessor also defines a single reference through which all configuration dependent behaviour 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.
see
DatabasePlatform
since
TOPLink/Java 1.0

Fields Summary
public static boolean
shouldUseDynamicStatements
PERF: Backdoor to disabling dynamic statements. Reverts to old prepared statement usage if set.
protected Hashtable
statementCache
Stores statement handles for common used prepared statements.
protected DatabaseMetaData
metaData
Cache of the connection's java.sql.DatabaseMetaData
protected LOBValueWriter
lobWriter
protected boolean
shouldUseThreadCursors
PERF: Option to allow concurrent thread processing of result sets. This allows the objects to be built while the rows are being fetched.
protected Statement
dynamicStatement
PERF: Cache the statement object for dynamic SQL execution.
protected boolean
isDynamicStatementInUse
Constructors Summary
public DatabaseAccessor()


      
        super();
        this.statementCache = new Hashtable(50);
        this.lobWriter = null;
        this.shouldUseThreadCursors = false;
        this.isDynamicStatementInUse = false;
Methods Summary
public synchronized java.sql.StatementallocateDynamicStatement()
Allocate a statement for dynamic SQL execution. Either return the cached dynamic statement, or a new statement. This statement must be released after execution.

        if (dynamicStatement == null) {
            dynamicStatement = getConnection().createStatement();
        }
        if (isDynamicStatementInUse()) {
            return getConnection().createStatement();
        }
        setIsDynamicStatementInUse(true);
        return dynamicStatement;
public voidbasicBeginTransaction(oracle.toplink.essentials.internal.sessions.AbstractSession session)
Begin a transaction on the database. This means toggling the auto-commit option.

        try {
            if (getPlatform().supportsAutoCommit()) {
                getConnection().setAutoCommit(false);
            } else {
                getPlatform().beginTransaction(this);
            }
        } catch (SQLException exception) {
            throw DatabaseException.sqlException(exception, this, session);
        }
public voidbasicCommitTransaction(oracle.toplink.essentials.internal.sessions.AbstractSession session)
Commit a transaction on the database. This means toggling the auto-commit option.

        try {
            if (getPlatform().supportsAutoCommit()) {
                getConnection().commit();
                getConnection().setAutoCommit(true);
            } else {
                getPlatform().commitTransaction(this);
            }
        } catch (SQLException exception) {
            throw DatabaseException.sqlException(exception, this, session);
        }
public java.lang.ObjectbasicExecuteCall(oracle.toplink.essentials.queryframework.Call call, oracle.toplink.essentials.internal.sessions.AbstractRecord translationRow, oracle.toplink.essentials.internal.sessions.AbstractSession session)
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.

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

        Statement statement = null;
        Object result = null;
        DatabaseCall dbCall = null;
        ResultSet resultSet = null;// only used if this is a read query
        try {
            dbCall = (DatabaseCall)call;
        } catch (ClassCastException e) {
            throw QueryException.invalidDatabaseCall(call);
        }

        // If the login is null, then this accessor has never been connected.
        if (getLogin() == null) {
            throw DatabaseException.databaseAccessorNotConnected();
        }

        try {
            incrementCallCount(session);
            if (session.shouldLog(SessionLog.FINE, SessionLog.SQL)) {// Avoid printing if no logging required.
                session.log(SessionLog.FINE, SessionLog.SQL, dbCall.getLogString(this), (Object[])null, this, false);
            }
            session.startOperationProfile(SessionProfiler.SQL_PREPARE);
            try {
                statement = dbCall.prepareStatement(this, translationRow, session);
            } finally {
                session.endOperationProfile(SessionProfiler.SQL_PREPARE);
            }

            // effectively this means that someone is executing an update type query.
            if (dbCall.isNothingReturned()) {
                result = executeNoSelect(dbCall, statement, session);
                if (dbCall.isLOBLocatorNeeded()) {
                    // add original (insert or update) call to the LOB locator
                    // Bug 2804663 - LOBValueWriter is no longer a singleton
                    getLOBWriter().addCall(dbCall);
                }
            } else if (!dbCall.getReturnsResultSet() || (dbCall.getReturnsResultSet() && dbCall.shouldBuildOutputRow())) {
                result = session.getPlatform().executeStoredProcedure(dbCall, (PreparedStatement)statement, this, session);
            } else {// not a stored procedure
                resultSet = executeSelect(dbCall, statement, session);
                if (dbCall.getFirstResult() != 0) {
                    resultSet.absolute(dbCall.getFirstResult());
                }
                ResultSetMetaData metaData = resultSet.getMetaData();
                dbCall.matchFieldOrder(resultSet, this, session);

                if (dbCall.isCursorReturned()) {
                    dbCall.setStatement(statement);
                    dbCall.setResult(resultSet);
                    return dbCall;
                }

                session.startOperationProfile(SessionProfiler.ROW_FETCH);
                try {
                    if (dbCall.isOneRowReturned()) {
                        if (resultSet.next()) {
                            if (dbCall.isLOBLocatorNeeded()) {
                                //if Oracle BLOB/CLOB field is being written, and the thin driver is used, the driver 4k
                                //limit bug prevent the call from directly writing to the table if the LOB value size exceeds 4k.
                                //Instead, a LOB locator is retrieved and value is then piped into the table through the locator.
                                // Bug 2804663 - LOBValueWriter is no longer a singleton
                                getLOBWriter().fetchLocatorAndWriteValue(dbCall, resultSet);
                            } else {
                                result = fetchRow(dbCall.getFields(), resultSet, metaData, session);
                            }
                            if (resultSet.next()) {
                                // Raise more rows event, some apps may interpret as error or warning.
                                session.getEventManager().moreRowsDetected(dbCall);
                            }
                        } else {
                            result = null;
                        }
                    } else {
                        boolean hasNext = resultSet.next();
                        Vector results = null;

                        // PERF: Optimize out simple empty case.
                        if (hasNext) {
                            if (shouldUseThreadCursors()) {
                                // If using threading return the cursored list,
                                // do not close the result or statement as the rows are being fetched by the thread.
                                return buildThreadCursoredResult(dbCall, resultSet, statement, metaData, session);
                            } else {
                                results = new Vector(20);
                                while (hasNext) {
                                    results.addElement(fetchRow(dbCall.getFields(), resultSet, metaData, session));
                                    hasNext = resultSet.next();
                                }
                            }
                        } else {
                            results = new Vector(0);
                        }
                        result = results;
                    }
                    resultSet.close();// This must be closed incase the statement is cached and not closed.
                } finally {
                    session.endOperationProfile(SessionProfiler.ROW_FETCH);
                }
            }
        } catch (SQLException exception) {
            try {// Ensure that the statement is closed, but still ensure that the real exception is thrown.
                closeStatement(statement, session);
            } catch (Exception closeException) {
            }
            throw DatabaseException.sqlException(exception, dbCall, this, session);
        } catch (RuntimeException exception) {
            try {// Ensure that the statement is closed, but still ensure that the real exception is thrown.
                closeStatement(statement, session);
            } catch (Exception closeException) {
            }
            if (exception instanceof DatabaseException) {
                ((DatabaseException)exception).setCall(dbCall);
            }
            throw exception;
        }

        // This is in seperate try block to ensure that the real exception is not masked by the close exception.
        try {
            // Allow for caching of statement, forced closes are not cache as they failed execution so are most likely bad.
            releaseStatement(statement, dbCall.getSQLString(), dbCall, session);
        } catch (SQLException exception) {
            throw DatabaseException.sqlException(exception, this, session);
        }

        return result;
public voidbasicRollbackTransaction(oracle.toplink.essentials.internal.sessions.AbstractSession session)
Rollback a transaction on the database. This means toggling the auto-commit option.

        try {
            if (getPlatform().supportsAutoCommit()) {
                getConnection().rollback();
                getConnection().setAutoCommit(true);
            } else {
                getPlatform().rollbackTransaction(this);
            }
        } catch (SQLException exception) {
            throw DatabaseException.sqlException(exception, this, session);
        }
protected voidbuildConnectLog(oracle.toplink.essentials.internal.sessions.AbstractSession session)
If logging is turned on and the JDBC implementation supports meta data then display connection info.

        try {
            // Log connection information.
            if (session.shouldLog(SessionLog.CONFIG, SessionLog.CONNECTION)) {// Avoid printing if no logging required.
                DatabaseMetaData metaData = getConnectionMetaData();
                Object[] args = { metaData.getURL(), metaData.getUserName(), metaData.getDatabaseProductName(), metaData.getDatabaseProductVersion(), metaData.getDriverName(), metaData.getDriverVersion(), Helper.cr() + "\t" };
                session.log(SessionLog.CONFIG, SessionLog.CONNECTION, "connected_user_database_driver", args, this);
            }
        } catch (SQLException exception) {
            // Some databases do not support metadata, ignore exception.
            session.warning("JDBC_driver_does_not_support_meta_data", SessionLog.CONNECTION);
        }
public oracle.toplink.essentials.internal.sessions.AbstractRecordbuildOutputRow(java.sql.CallableStatement statement, oracle.toplink.essentials.internal.databaseaccess.DatabaseCall call, oracle.toplink.essentials.internal.sessions.AbstractSession session)
Build a row from the output parameters of a sp call.

        try {
            return call.buildOutputRow(statement);
        } catch (SQLException exception) {
            throw DatabaseException.sqlException(exception, call, this, session);
        }
public java.util.VectorbuildSortedFields(java.util.Vector fields, java.sql.ResultSet resultSet, oracle.toplink.essentials.internal.sessions.AbstractSession session)
Return the field sorted in the correct order coresponding 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.

        Vector sortedFields;
        try {
            Vector columnNames = getColumnNames(resultSet, session);
            if (fields == null) {// Means fields not known.
                sortedFields = new Vector(columnNames.size());
                for (Enumeration columnNamesEnum = columnNames.elements();
                         columnNamesEnum.hasMoreElements();) {
                    sortedFields.addElement(new DatabaseField((String)columnNamesEnum.nextElement()));
                }
            } else {
                sortedFields = sortFields(fields, columnNames);
            }
        } catch (SQLException exception) {
            throw DatabaseException.sqlException(exception, this, session);
        }
        return sortedFields;
protected java.util.VectorbuildThreadCursoredResult(oracle.toplink.essentials.internal.databaseaccess.DatabaseCall dbCall, java.sql.ResultSet resultSet, java.sql.Statement statement, java.sql.ResultSetMetaData metaData, oracle.toplink.essentials.internal.sessions.AbstractSession session)

        final ThreadCursoredList results = new ThreadCursoredList(20);
        Thread thread = new Thread() {
            public void run() {
                session.startOperationProfile(SessionProfiler.ROW_FETCH);
                try {
                    // Initial next was already validated before this method is called.
                    boolean hasNext = true;
                    while (hasNext) {
                        results.addElement(fetchRow(dbCall.getFields(), resultSet, metaData, session));
                        hasNext = resultSet.next();
                    }
                    resultSet.close();// This must be closed incase the statement is cached and not closed.
                } catch (SQLException exception) {
                    try {// Ensure that the statement is closed, but still ensure that the real exception is thrown.
                        closeStatement(statement, session);
                    } catch (Exception closeException) {
                    }
                    results.throwException(DatabaseException.sqlException(exception, dbCall, DatabaseAccessor.this, session));
                } catch (RuntimeException exception) {
                    try {// Ensure that the statement is closed, but still ensure that the real exception is thrown.
                        closeStatement(statement, session);
                    } catch (Exception closeException) {
                    }
                    if (exception instanceof DatabaseException) {
                        ((DatabaseException)exception).setCall(dbCall);
                    }
                    results.throwException(exception);
                } finally {
                    session.endOperationProfile(SessionProfiler.ROW_FETCH);
                }

                // This is in seperate try block to ensure that the real exception is not masked by the close exception.
                try {
                    // Allow for caching of statement, forced closes are not cache as they failed execution so are most likely bad.
                    DatabaseAccessor.this.releaseStatement(statement, dbCall.getSQLString(), dbCall, session);
                } catch (SQLException exception) {
                    results.throwException(DatabaseException.sqlException(exception, DatabaseAccessor.this, session));
                }
                results.setIsComplete(true);
            }
        };
        thread.start();

        return results;
protected voidcheckTransactionIsolation()
Check to see if the transaction isolation needs to be set for the newly created connection. This must be done outside of a transaction. Exceptions are caught and re-thrown as TopLink exceptions.

        if ((!isInTransaction()) && (getLogin() != null) && (((DatabaseLogin)getLogin()).getTransactionIsolation() != -1)) {
            try {
                getConnection().setTransactionIsolation(((DatabaseLogin)getLogin()).getTransactionIsolation());
            } catch (java.sql.SQLException sqlEx) {
                throw DatabaseException.sqlException(sqlEx, this, null);
            }
        }
public voidclearStatementCache(oracle.toplink.essentials.internal.sessions.AbstractSession session)
Flush the statement cache. Each statement must first be closed.

        if (hasStatementCache()) {
            for (Enumeration statements = getStatementCache().elements();
                     statements.hasMoreElements();) {
                Statement statement = (Statement)statements.nextElement();
                try {
                    statement.close();
                } catch (SQLException exception) {
                    // an exception can be raised if
                    // a statement is closed twice.
                }
            }
            setStatementCache(null);
        }

        // Close cached dynamic statement.
        if (this.dynamicStatement != null) {
            try {
                this.dynamicStatement.close();
            } catch (SQLException exception) {
                // an exception can be raised if
                // a statement is closed twice.
            }
            this.dynamicStatement = null;
            this.setIsDynamicStatementInUse(false);
        }
public voidcloseConnection()
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.

        // Unfortunately do not have the session to pass, fortunately it is not used.
        clearStatementCache(null);
        super.closeConnection();
public voidcloseCursor(java.sql.ResultSet resultSet)
Close the result set of the cursored stream.

        try {
            resultSet.close();
        } catch (SQLException exception) {
            throw DatabaseException.sqlException(exception, this, null);
        }
public voidcloseDatasourceConnection()
Close the connection.

        try {
            getConnection().close();
        } catch (SQLException exception) {
            throw DatabaseException.sqlException(exception, this, null);
        }
public voidcloseStatement(java.sql.Statement statement, oracle.toplink.essentials.internal.sessions.AbstractSession session)
INTERNAL: Closes a PreparedStatment (which is supposed to close it's current resultSet). Factored out to simplify coding and handle exceptions.

        if (statement == null) {
            decrementCallCount();
            return;
        }

        try {
            session.startOperationProfile(SessionProfiler.STATEMENT_EXECUTE);
            statement.close();
        } finally {
            session.endOperationProfile(SessionProfiler.STATEMENT_EXECUTE);
            decrementCallCount();
            // If this is the cached dynamic statement, release it.
            if (statement == this.dynamicStatement) {
                this.dynamicStatement = null;
                // The dynamic statement is cached and only closed on disconnect.
                setIsDynamicStatementInUse(false);
            }
        }
public voidcommitTransaction(oracle.toplink.essentials.internal.sessions.AbstractSession session)
Commit a transaction on the database. First flush any batched statements.

        this.writesCompleted(session);
        super.commitTransaction(session);
protected voidconnect(oracle.toplink.essentials.sessions.Login login)
Connect to the database. Exceptions are caught and re-thrown as TopLink exceptions. Must set the transaction isolation.

        super.connect(login);
        checkTransactionIsolation();
public oracle.toplink.essentials.internal.sessions.AbstractRecordcursorRetrieveNextRow(java.util.Vector fields, java.sql.ResultSet resultSet, oracle.toplink.essentials.internal.sessions.AbstractSession session)
Advance the result set and return a DatabaseRow populated with values from the next valid row in the result set. Intended solely for cursored stream support.

        try {
            if (resultSet.next()) {
                return fetchRow(fields, resultSet, resultSet.getMetaData(), session);
            } else {
                return null;
            }
        } catch (SQLException exception) {
            throw DatabaseException.sqlException(exception, this, session);
        }
public oracle.toplink.essentials.internal.sessions.AbstractRecordcursorRetrievePreviousRow(java.util.Vector fields, java.sql.ResultSet resultSet, oracle.toplink.essentials.internal.sessions.AbstractSession session)
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.

        try {
            if (resultSet.previous()) {
                return fetchRow(fields, resultSet, resultSet.getMetaData(), session);
            } else {
                return null;
            }
        } catch (SQLException exception) {
            throw DatabaseException.sqlException(exception, this, session);
        }
public voiddisconnect(oracle.toplink.essentials.internal.sessions.AbstractSession session)
Disconnect from the datasource. Added for bug 3046465 to ensure the statement cache is cleared

        clearStatementCache(session);
        super.disconnect(session);
protected voidexecuteBatchedStatement(java.sql.PreparedStatement statement, oracle.toplink.essentials.internal.sessions.AbstractSession session)
Execute the TopLink dynamicly batch/concat statement.

        try {
            executeDirectNoSelect(statement, null, session);
        } catch (RuntimeException exception) {
            try {// Ensure that the statement is closed, but still ensure that the real exception is thrown.
                closeStatement(statement, session);
            } catch (SQLException closeException) {
            }

            throw exception;
        }

        // This is in seperate try block to ensure that the real exception is not masked by the close exception.
        try {
            closeStatement(statement, session);
        } catch (SQLException exception) {
            throw DatabaseException.sqlException(exception, this, session);
        }
public java.lang.ObjectexecuteCall(oracle.toplink.essentials.queryframework.Call call, oracle.toplink.essentials.internal.sessions.AbstractRecord translationRow, oracle.toplink.essentials.internal.sessions.AbstractSession session)
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.

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

        // Keep complete implementation.
        return basicExecuteCall(call, translationRow, session);
public java.lang.IntegerexecuteDirectNoSelect(java.sql.Statement statement, oracle.toplink.essentials.internal.databaseaccess.DatabaseCall call, oracle.toplink.essentials.internal.sessions.AbstractSession session)
Execute the statement.

        int rowCount = 0;

        try {
            session.startOperationProfile(SessionProfiler.STATEMENT_EXECUTE);
            if ((call != null) && call.isDynamicCall(session)) {
                rowCount = statement.executeUpdate(call.getSQLString());
            } else {
                rowCount = ((PreparedStatement)statement).executeUpdate();
            }
            if ((!getPlatform().supportsAutoCommit()) && (!isInTransaction())) {
                getPlatform().autoCommit(this);
            }
        } catch (SQLException exception) {
            if (!getPlatform().shouldIgnoreException(exception)) {
                throw DatabaseException.sqlException(exception, this, session);
            }
        } finally {
            session.endOperationProfile(SessionProfiler.STATEMENT_EXECUTE);
        }

        return new Integer(rowCount);
protected voidexecuteJDK12BatchStatement(java.sql.Statement statement, oracle.toplink.essentials.internal.databaseaccess.DatabaseCall dbCall, oracle.toplink.essentials.internal.sessions.AbstractSession session)
Execute the batched statement through the JDBC2 API.

        try {
            statement.executeBatch();
        } catch (SQLException exception) {
            try {// Ensure that the statement is closed, but still ensure that the real exception is thrown.
                closeStatement(statement, session);
            } catch (SQLException closeException) {
            }

            throw DatabaseException.sqlException(exception, this, session);
        } catch (RuntimeException exception) {
            try {// Ensure that the statement is closed, but still ensure that the real exception is thrown.
                closeStatement(statement, session);
            } catch (SQLException closeException) {
            }

            throw exception;
        }

        // This is in seperate try block to ensure that the real exception is not masked by the close exception.
        try {
            // if we are called from the ParameterizedBatchWritingMechanism then dbCall will not be null
            //and we should try an release the statement
            if (dbCall != null) {
                releaseStatement((PreparedStatement)statement, dbCall.getSQLString(), dbCall, session);
            } else {
                closeStatement(statement, session);
            }
        } catch (SQLException exception) {
            throw DatabaseException.sqlException(exception, this, session);
        }
protected java.lang.IntegerexecuteNoSelect(oracle.toplink.essentials.internal.databaseaccess.DatabaseCall call, java.sql.Statement statement, oracle.toplink.essentials.internal.sessions.AbstractSession session)
Execute the statement.

        Integer rowCount = executeDirectNoSelect(statement, call, session);

        // Allow for procs with outputs to be raised as events for error handling.
        if (call.shouldBuildOutputRow()) {
            AbstractRecord outputRow = buildOutputRow((CallableStatement)statement, call, session);
            call.getQuery().setProperty("output", outputRow);
            session.getEventManager().outputParametersDetected(outputRow, call);
        }

        return rowCount;
protected java.sql.ResultSetexecuteSelect(oracle.toplink.essentials.internal.databaseaccess.DatabaseCall call, java.sql.Statement statement, oracle.toplink.essentials.internal.sessions.AbstractSession session)
Execute the statement.

        ResultSet resultSet;

        session.startOperationProfile(SessionProfiler.STATEMENT_EXECUTE);
        try {
            if (call.isDynamicCall(session)) {
                resultSet = statement.executeQuery(call.getSQLString());
            } else {
                resultSet = ((PreparedStatement)statement).executeQuery();
            }
        } finally {
            session.endOperationProfile(SessionProfiler.STATEMENT_EXECUTE);
        }

        // Allow for procs with outputs to be raised as events for error handling.
        if (call.shouldBuildOutputRow()) {
            AbstractRecord outputRow = buildOutputRow((CallableStatement)statement, call, session);
            call.getQuery().setProperty("output", outputRow);
            session.getEventManager().outputParametersDetected(outputRow, call);
        }

        return resultSet;
protected oracle.toplink.essentials.internal.sessions.AbstractRecordfetchRow(java.util.Vector fields, java.sql.ResultSet resultSet, java.sql.ResultSetMetaData metaData, oracle.toplink.essentials.internal.sessions.AbstractSession session)
Return a new DatabaseRow.

Populate the row from the data in cursor. The fields representing the results and the order of the results are stored in fields.

NOTE: Make sure that the field name is set. An empty field name placeholder is used in the sortFields() method when the number of fields defined does not match the number of column names available on the database.

        Vector values = new Vector(fields.size());
        // PERF: Pass platform and optimize data flag.
        DatabasePlatform platform = getPlatform();
        boolean optimizeData = platform.shouldOptimizeDataConversion();
        int size = fields.size();
        for (int index = 0; index < size; index++) {
            DatabaseField field = (DatabaseField)fields.elementAt(index);
            // Field can be null for fetch groups.
            if (field != null) {
                values.add(getObject(resultSet, field, metaData, index + 1, platform, optimizeData, session));
            } else {
                values.add(null);
            }
        }

        // Row creation is optimized through sharing the same fields for the entire result set.
        return new DatabaseRecord(fields, values);
public voidflushSelectCalls(oracle.toplink.essentials.internal.sessions.AbstractSession session)
Execute any deferred select calls stored in the LOBValueWriter instance. This method will typically be called by the CallQueryMechanism object. Bug 2804663.

see
oracle.toplink.essentials.internal.helper.LOBValueWriter
see
oracle.toplink.essentials.internal.queryframework.CallQueryMechanism#insertObject()

        if (lobWriter != null) {
            lobWriter.buildAndExecuteSelectCalls(session);
        }
public java.util.VectorgetColumnInfo(java.lang.String catalog, java.lang.String schema, java.lang.String tableName, java.lang.String columnName, oracle.toplink.essentials.internal.sessions.AbstractSession session)
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.

param
catalog a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
param
schemaPattern a schema name pattern; "" retrieves those without a schema
param
tableNamePattern a table name pattern
param
columnNamePattern a column name pattern
return
a Vector of DatabaseRows.

        if (session.shouldLog(SessionLog.FINEST, SessionLog.QUERY)) {// Avoid printing if no logging required.
            Object[] args = { catalog, schema, tableName, columnName };
            session.log(SessionLog.FINEST, SessionLog.QUERY, "query_column_meta_data_with_column", args, this);
        }
        Vector result = new Vector();
        ResultSet resultSet = null;
        try {
            incrementCallCount(session);
            resultSet = getConnectionMetaData().getColumns(catalog, schema, tableName, columnName);
            Vector fields = buildSortedFields(null, resultSet, session);
            ResultSetMetaData metaData = resultSet.getMetaData();

            while (resultSet.next()) {
                result.addElement(fetchRow(fields, resultSet, metaData, session));
            }
            resultSet.close();
        } catch (SQLException sqlException) {
            try {
                if (resultSet != null) {
                    resultSet.close();
                }
            } catch (SQLException closeException) {
            }

            // Ensure that real exception is thrown.			
            throw DatabaseException.sqlException(sqlException, this, session);
        } finally {
            decrementCallCount();
        }
        return result;
protected java.util.VectorgetColumnNames(java.sql.ResultSet resultSet, oracle.toplink.essentials.internal.sessions.AbstractSession session)
Return the column names from a result sets meta data. This is required for custom SQL execution only, as generated SQL already knows the fields returned.

        ResultSetMetaData metaData = resultSet.getMetaData();
        Vector columnNames = new Vector(metaData.getColumnCount());

        for (int index = 0; index < metaData.getColumnCount(); index++) {
            // Changed the following code to use metaData#getColumnLabel() instead of metaData.getColumnName()
            // This is as required by JDBC spec to access metadata for queries using column aliases.
            // Reconsider whether to migrate this change to other versions of Toplink with older native query support
            String columnName = metaData.getColumnLabel(index + 1);
            if ((columnName == null) || columnName.equals("")) {
                columnName = "C" + (index + 1);// Some column may be unnamed.
            }

            // Force field names to upper case is set.
            if (getPlatform().shouldForceFieldNamesToUpperCase()) {
                columnName = columnName.toUpperCase();
            }
            columnNames.addElement(columnName);
        }
        return columnNames;
public java.sql.ConnectiongetConnection()
Return the receiver's connection to its data source. A connection is used to execute queries on, and retreive data from, a data source.

see
java.sql.Connection

        return (Connection)getDatasourceConnection();
public java.sql.DatabaseMetaDatagetConnectionMetaData()
return the cached metaData

        return getConnection().getMetaData();
public oracle.toplink.essentials.internal.helper.LOBValueWritergetLOBWriter()
Return the LOBValueWriter instance. Lazily initialize the instance. Bug 2804663.

see
oracle.toplink.essentials.internal.helper.LOBValueWriter

        if (lobWriter == null) {
            lobWriter = new LOBValueWriter(this);
        }
        return lobWriter;
protected java.lang.ObjectgetObject(java.sql.ResultSet resultSet, oracle.toplink.essentials.internal.helper.DatabaseField field, java.sql.ResultSetMetaData metaData, int columnNumber, oracle.toplink.essentials.internal.databaseaccess.DatabasePlatform platform, boolean optimizeData, oracle.toplink.essentials.internal.sessions.AbstractSession session)
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.

        Object value = null;
        try {
            // PERF: Cache the JDBC type in the field to avoid JDBC call.
            int type = field.sqlType;
            if (type == -1) {
                type = metaData.getColumnType(columnNumber);
                field.setSqlType(type);
            }

            if (optimizeData) {
                try {
                    value = getObjectThroughOptimizedDataConversion(resultSet, field, type, columnNumber, platform, session);
                    // Since null cannot be distighighsed from no optimization done, this is return for no-op.
                    if (value == null) {
                        return null;
                    }
                    if (value == this) {
                        value = null;
                    }
                } catch (SQLException exception) {
                    // Log the exception and try non-optimized data conversion
                    if (session.shouldLog(SessionLog.WARNING, SessionLog.SQL)) {
                        session.logThrowable(SessionLog.WARNING, SessionLog.SQL, exception);
                    }
                }
            }
            if (value == null) {
                if ((type == Types.LONGVARBINARY) && platform.usesStreamsForBinding()) {
                    //can read large binary data as a stream
                    InputStream tempInputStream;
                    tempInputStream = resultSet.getBinaryStream(columnNumber);
                    if (tempInputStream != null) {
                        try {
                            ByteArrayOutputStream tempOutputStream = new ByteArrayOutputStream();
                            int tempInt = tempInputStream.read();
                            while (tempInt != -1) {
                                tempOutputStream.write(tempInt);
                                tempInt = tempInputStream.read();
                            }
                            value = tempOutputStream.toByteArray();
                        } catch (IOException exception) {
                            throw DatabaseException.errorReadingBlobData();
                        }
                    } else {
                        value = null;
                    }
                } else {
                    value = platform.getObjectFromResultSet(resultSet, columnNumber, type);                      
                    // PERF: only perform blob check on non-optimized types.
                    // CR2943 - convert early if the type is a BLOB or a CLOB.  
                    if (isBlob(type)) {
                        value = platform.convertObject(value, ClassConstants.APBYTE);
                    }
                    if (isClob(type)) {
                        value = getPlatform().convertObject(value, ClassConstants.STRING);
                    }
                }
            }
            if (resultSet.wasNull()) {
                value = null;
            }
        } catch (SQLException exception) {
            throw DatabaseException.sqlException(exception, this, session);
        }

        return value;
protected java.lang.ObjectgetObjectThroughOptimizedDataConversion(java.sql.ResultSet resultSet, oracle.toplink.essentials.internal.helper.DatabaseField field, int type, int columnNumber, oracle.toplink.essentials.internal.databaseaccess.DatabasePlatform platform, oracle.toplink.essentials.internal.sessions.AbstractSession session)
Handle the conversion into java optimially through calling the direct type API. If the type is not one that can be optimized return null.

        Object value = this;// Means no optimization, need to distighuuish from null.
        Class fieldType = field.type;        

        // Optimize numeric values to avoid conversion into big-dec and back to primitives.
        if ((fieldType == ClassConstants.PLONG) || (fieldType == ClassConstants.LONG)) {
            value = new Long(resultSet.getLong(columnNumber));
        } else if ((type == Types.VARCHAR) || (type == Types.CHAR)) {
            // CUSTOM PATCH for oracle drivers because they don't respond to getObject() when using scrolling result sets. 
            // Chars may require blanks to be trimmed.
            value = resultSet.getString(columnNumber);
            if ((type == Types.CHAR) && (value != null) && platform.shouldTrimStrings()) {
                value = Helper.rightTrimString((String)value);
            }
        } else if ((fieldType == ClassConstants.INTEGER) || (fieldType == ClassConstants.PINT)) {
            value = new Integer(resultSet.getInt(columnNumber));
        } else if ((fieldType == ClassConstants.FLOAT) || (fieldType == ClassConstants.PFLOAT)) {
            value = new Float(resultSet.getFloat(columnNumber));
        } else if ((fieldType == ClassConstants.DOUBLE) || (fieldType == ClassConstants.PDOUBLE)) {
            value = new Double(resultSet.getDouble(columnNumber));
        } else if ((fieldType == ClassConstants.SHORT) || (fieldType == ClassConstants.PSHORT)) {
            value = new Short(resultSet.getShort(columnNumber));
        } else if (Helper.shouldOptimizeDates() && (fieldType != null) && ((type == Types.TIME) || (type == Types.DATE) || (type == Types.TIMESTAMP))) {
            // Optimize dates by avoid conversion to timestamp then back to date or time or util.date.
            String dateString = resultSet.getString(columnNumber);
            value = platform.convertObject(dateString, fieldType);
        } else if ((fieldType != null) && ((type == Types.TIME) || (type == Types.DATE) || (type == Types.TIMESTAMP))) {
            // PERF: Optimize dates by calling direct get method if type is Date or Time,
            // unfortunately the double conversion is unavoidable for Calendar and util.Date.
            if (fieldType == ClassConstants.SQLDATE) {
                value = resultSet.getDate(columnNumber);
            } else if (fieldType == ClassConstants.TIME) {
                value = resultSet.getTime(columnNumber);
            } else if (fieldType == ClassConstants.TIMESTAMP) {
                value = resultSet.getTimestamp(columnNumber);
            }
        }

        return value;
public oracle.toplink.essentials.internal.databaseaccess.DatabasePlatformgetPlatform()
Return the platform.

        return (DatabasePlatform)platform;
protected synchronized java.util.HashtablegetStatementCache()
The statement cache stores a fixed sized number of prepared statements.

        if (statementCache == null) {
            statementCache = new Hashtable(50);
        }
        return statementCache;
public java.util.VectorgetTableInfo(java.lang.String catalog, java.lang.String schema, java.lang.String tableName, java.lang.String[] types, oracle.toplink.essentials.internal.sessions.AbstractSession session)
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.

param
catalog a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria
param
schemaPattern a schema name pattern; "" retrieves those without a schema
param
tableNamePattern a table name pattern
param
types a list of table types to include; null returns all types
return
a Vector of DatabaseRows.

        if (session.shouldLog(SessionLog.FINEST, SessionLog.QUERY)) {// Avoid printing if no logging required.
            Object[] args = { catalog, schema, tableName };
            session.log(SessionLog.FINEST, SessionLog.QUERY, "query_column_meta_data", args, this);
        }
        Vector result = new Vector();
        ResultSet resultSet = null;
        try {
            incrementCallCount(session);
            resultSet = getConnectionMetaData().getTables(catalog, schema, tableName, types);
            Vector fields = buildSortedFields(null, resultSet, session);
            ResultSetMetaData metaData = resultSet.getMetaData();

            while (resultSet.next()) {
                result.addElement(fetchRow(fields, resultSet, metaData, session));
            }
            resultSet.close();
        } catch (SQLException sqlException) {
            try {
                if (resultSet != null) {
                    resultSet.close();
                }
            } catch (SQLException closeException) {
            }

            // Ensure that real exception is thrown.			
            throw DatabaseException.sqlException(sqlException, this, session);
        } finally {
            decrementCallCount();
        }
        return result;
protected booleanhasStatementCache()
Return if the accessor has any cached statements. This should be used to avoid lazy instantiation of the cache.

        return (statementCache != null) && (!statementCache.isEmpty());
private booleanisBlob(int type)
Return if the JDBC type is a binary type such as blob.

        return (type == Types.BLOB) || (type == Types.LONGVARBINARY);
private booleanisClob(int type)
Return if the JDBC type is a large character type such as clob.

        return (type == Types.CLOB) || (type == Types.LONGVARCHAR);
public booleanisDatasourceConnected()
Return true if the receiver is currently connected to a data source. Return false otherwise.

        try {
            return !getConnection().isClosed();
        } catch (SQLException exception) {
            throw DatabaseException.sqlException(exception, this, null);
        }
public booleanisDynamicStatementInUse()
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.

        return isDynamicStatementInUse;
public java.sql.StatementprepareStatement(oracle.toplink.essentials.internal.databaseaccess.DatabaseCall call, oracle.toplink.essentials.internal.sessions.AbstractSession session)
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.

        Statement statement = null;
        if (call.usesBinding(session) && call.shouldCacheStatement(session)) {
            // Check the cache by sql string, must syncronize check and removal.
            synchronized (getStatementCache()) {
                statement = (PreparedStatement)getStatementCache().get(call.getSQLString());
                if (statement != null) {
                    // Need to remove to allow concurrent statement execution.
                    getStatementCache().remove(call.getSQLString());
                }
            }
        }

        if (statement == null) {
            if (call.isCallableStatementRequired()) {
                // Callable statements are used for StoredProcedures and PLSQL blocks.
                if (call.isResultSetScrollable()) {
                    statement = getConnection().prepareCall(call.getSQLString(), call.getResultSetType(), call.getResultSetConcurrency());
                } else {
                    statement = getConnection().prepareCall(call.getSQLString());
                }
            } else if (call.isResultSetScrollable()) {
                // Scrollable statements are used for ScrollableCursors.
                statement = getConnection().prepareStatement(call.getSQLString(), call.getResultSetType(), call.getResultSetConcurrency());
            } else if (call.isDynamicCall(session)) {
                // PERF: Dynamic statements are used for dynamic SQL.
                statement = allocateDynamicStatement();
            } else {
                // Prepared statements are used if binding is used, or dynamic statements are turned off.
                statement = getConnection().prepareStatement(call.getSQLString());
            }
        }

        return statement;
protected voidreconnect(oracle.toplink.essentials.internal.sessions.AbstractSession session)
Attempt to save some of the cost associated with getting a fresh connection. Assume the DatabaseDriver has been cached, if appropriate. Note: Connections that are participating in transactions will not be refreshd.^M Added for bug 3046465 to ensure the statement cache is cleared

        clearStatementCache(session);
        super.reconnect(session);
protected voidreleaseStatement(java.sql.Statement statement, java.lang.String sqlString, oracle.toplink.essentials.internal.databaseaccess.DatabaseCall call, oracle.toplink.essentials.internal.sessions.AbstractSession session)
Release the statement through closing it or putting it back in the statement cache.

        if (call.usesBinding(session) && call.shouldCacheStatement(session)) {
            synchronized (getStatementCache()) {
                PreparedStatement preparedStatement = (PreparedStatement)statement;
                if (!getStatementCache().containsKey(sqlString)) {// May already be there by other thread.
                    preparedStatement.clearParameters();
                    if (getStatementCache().size() > getPlatform().getStatementCacheSize()) {
                        // Currently one is removed at random...
                        PreparedStatement removedStatement = (PreparedStatement)getStatementCache().remove(getStatementCache().keys().nextElement());
                        closeStatement(removedStatement, session);
                    } else {
                        decrementCallCount();
                    }
                    getStatementCache().put(sqlString, preparedStatement);
                } else {
                    // CR... Must close the statement if not cached.
                    closeStatement(statement, session);
                }
            }
        } else if (statement == this.dynamicStatement) {
            if (call.getMaxRows() > 0) { 
                statement.setMaxRows(0); 
            } 
            setIsDynamicStatementInUse(false);
            decrementCallCount();
        } else {
            closeStatement(statement, session);
        }
public synchronized voidsetIsDynamicStatementInUse(boolean isDynamicStatementInUse)
Set if the cached statement for dynamic SQL execution is in use. Used to handle concurrency for the dynamic statement.

        this.isDynamicStatementInUse = isDynamicStatementInUse;
public voidsetShouldUseThreadCursors(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.

        this.shouldUseThreadCursors = shouldUseThreadCursors;
protected voidsetStatementCache(java.util.Hashtable statementCache)
The statement cache stores a fixed sized number of prepared statements.

        this.statementCache = statementCache;
public booleanshouldUseThreadCursors()
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.

        return shouldUseThreadCursors;
protected java.util.VectorsortFields(java.util.Vector fields, java.util.Vector columnNames)
This method will sort the fields in correct order based on the column names.

        Vector sortedFields = new Vector(columnNames.size());
        Vector eligableFields = (Vector)fields.clone();// Must clone to allow removing to support the same field twice.
        Enumeration columnNamesEnum = columnNames.elements();
        boolean valueFound = false;
        while (columnNamesEnum.hasMoreElements()) {
            String columnName = (String)columnNamesEnum.nextElement();

            DatabaseField field = null;
            Enumeration fieldEnum = eligableFields.elements();
            while (fieldEnum.hasMoreElements()) {
                field = (DatabaseField)fieldEnum.nextElement();
                if (DatabasePlatform.shouldIgnoreCaseOnFieldComparisons()) {
                    if (field.getName().equalsIgnoreCase(columnName)) {
                        valueFound = true;
                        sortedFields.addElement(field);
                        break;
                    }
                } else {
                    if (field.getName().equals(columnName)) {
                        valueFound = true;
                        sortedFields.addElement(field);
                        break;
                    }
                }
            }

            if (valueFound) {
                // The eligable fields must be maintained as two field can have the same name, but different tables.
                eligableFields.removeElement(field);
            } else {
                // Need to add a place holder in case the column is not in the fiels vector
                sortedFields.addElement(new DatabaseField());
            }
            valueFound = false;
        }

        return sortedFields;
public java.lang.StringtoString()

        StringWriter writer = new StringWriter();
        writer.write("DatabaseAccessor(");
        if (isConnected()) {
            writer.write(ToStringLocalization.buildMessage("connected", (Object[])null));
        } else {
            writer.write(ToStringLocalization.buildMessage("disconnected", (Object[])null));
        }
        writer.write(")");
        return writer.toString();
public voidwritesCompleted(oracle.toplink.essentials.internal.sessions.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

        // Place holder for batch writing.