Class EmbedConnection

java.lang.Object
org.apache.derby.impl.jdbc.EmbedConnection
All Implemented Interfaces:
AutoCloseable, Connection, Wrapper, EngineConnection

public class EmbedConnection extends Object implements EngineConnection
Local implementation of Connection for a JDBC driver in the same process as the database.

There is always a single root (parent) connection. The initial JDBC connection is the root connection. A call to getCurrentConnection() or with the URL jdbc:default:connection yields a nested connection that shares the same root connection as the parent. A nested connection is implemented using this class. The nested connection copies the state of the parent connection and shares some of the same objects (e.g. ContextManager) that are shared across all nesting levels. The proxy also maintains its own state that is distinct from its parent connection (e.g. autocommit or warnings).

SYNCHRONIZATION: Just about all JDBC actions are synchronized across all connections stemming from the same root connection. The synchronization is upon the a synchronized object return by the rootConnection.

Supports

  • JDBC 4.2
See Also:
  • Field Details

    • exceptionClose

      protected static final StandardException exceptionClose
    • NO_MEM

      public static final SQLException NO_MEM
      Static exception to be thrown when a Connection request can not be fulfilled due to lack of memory. A static exception as the lack of memory would most likely cause another OutOfMemoryException and if there is not enough memory to create the OOME exception then something like the VM dying could occur. Simpler just to throw a static.
    • memoryState

      public static final LowMemory memoryState
      Low memory state object for connection requests.
    • dbMetadata

      DatabaseMetaData dbMetadata
    • tr

    • lobHashMap

      private HashMap<Integer,Object> lobHashMap
    • lobHMKey

      private int lobHMKey
    • lobReferences

      private WeakHashMap<Object,Object> lobReferences
      Map to keep track of all the lobs associated with this connection. These lobs will be cleared after the transaction is no longer valid or when connection is closed
    • lobFiles

      private HashSet<LOBFile> lobFiles
    • active

      private boolean active
    • aborting

      private boolean aborting
    • autoCommit

      boolean autoCommit
    • needCommit

      boolean needCommit
    • usingNoneAuth

      private boolean usingNoneAuth
    • connectionHoldAbility

      private int connectionHoldAbility
    • rootConnection

      final EmbedConnection rootConnection
    • topWarning

      private SQLWarning topWarning
    • factory

      private InternalDriver factory
      Factory for JDBC objects to be created.
    • applicationConnection

      private Connection applicationConnection
      The Connection object the application is using when accessing the database through this connection. In most cases this will be equal to this. When Connection pooling is being used, then it will be set to the Connection object handed to the application. It is used for the getConnection() methods of various JDBC objects.
    • resultSetId

      private int resultSetId
      An increasing counter to assign to a ResultSet on its creation. Used for ordering ResultSets returned from a procedure, always returned in order of their creation. Is maintained at the root connection.
    • connString

      private String connString
      Cached string representation of the connection id
    • OP_ENCRYPT

      private static final int OP_ENCRYPT
      See Also:
    • OP_SHUTDOWN

      private static final int OP_SHUTDOWN
      See Also:
    • OP_HARD_UPGRADE

      private static final int OP_HARD_UPGRADE
      See Also:
    • OP_REPLICATION

      private static final int OP_REPLICATION
      See Also:
    • OP_DECRYPT

      private static final int OP_DECRYPT
      See Also:
  • Constructor Details

    • EmbedConnection

      public EmbedConnection(InternalDriver driver, String url, Properties info) throws SQLException
      Throws:
      SQLException
    • EmbedConnection

      public EmbedConnection(EmbedConnection inputConnection)
      Create a new connection based off of the connection passed in. Initializes state based on input connection, and copies appropriate object pointers. This is only used for nested connections.
      Parameters:
      inputConnection - the input connection
  • Method Details

    • checkDatabaseBooted

      private void checkDatabaseBooted(Database database, String operation, String dbname) throws SQLException
      Check that a database has already been booted. Throws an exception otherwise
      Parameters:
      database - The database that should have been booted
      operation - The operation that requires that the database has already been booted, used in the exception message if not booted
      dbname - The name of the database that should have been booted, used in the exception message if not booted
      Throws:
      SQLException - thrown if database is not booted
    • createBoot

      private boolean createBoot(Properties p) throws SQLException
      Examine the attributes set provided for illegal boot combinations and determine if this is a create boot.
      Parameters:
      p - the attribute set.
      Returns:
      true iff the attribute create=true is provided. This means create a standard database. In other cases, returns false.
      Throws:
      SQLException - Throw if more than one of create, createFrom, restoreFrom and rollForwardRecoveryFrom is used simultaneously.
      Also, throw if (re)encryption is attempted with one of createFrom, restoreFrom and rollForwardRecoveryFrom.
    • handleDBNotFound

      private void handleDBNotFound() throws SQLException
      Throws:
      SQLException
    • isDropDatabase

      private boolean isDropDatabase(Properties p)
      Examines the boot properties and determines if the given attributes would entail dropping the database.
      Parameters:
      p - the attribute set
      Returns:
      true if the drop database operation is requested, false if not.
    • isCryptoBoot

      private boolean isCryptoBoot(Properties p) throws SQLException
      Examines boot properties and determines if a boot with the given attributes would entail a cryptographic operation on the database.
      Parameters:
      p - the attribute set
      Returns:
      true if a boot will perform a cryptographic operation on the database.
      Throws:
      SQLException
    • isHardUpgradeBoot

      private boolean isHardUpgradeBoot(Properties p)
      Examine boot properties and determine if a boot with the given attributes would entail a hard upgrade.
      Parameters:
      p - the attribute set
      Returns:
      true if a boot will hard upgrade the database
    • isStartReplicationSlaveBoot

      private boolean isStartReplicationSlaveBoot(Properties p)
    • isStartReplicationMasterBoot

      private boolean isStartReplicationMasterBoot(Properties p)
    • isReplicationFailover

      private boolean isReplicationFailover(Properties p)
      used to verify if the failover attribute has been set.
      Parameters:
      p - The attribute set.
      Returns:
      true if the failover attribute has been set. false otherwise.
    • isStopReplicationMasterBoot

      private boolean isStopReplicationMasterBoot(Properties p)
    • isStopReplicationSlaveBoot

      private boolean isStopReplicationSlaveBoot(Properties p)
      Examine the boot properties and determine if a boot with the given attributes should stop slave replication mode.
      Parameters:
      p - The attribute set.
      Returns:
      true if the stopSlave attribute has been set, false otherwise.
    • isInternalShutdownSlaveDatabase

      private boolean isInternalShutdownSlaveDatabase(Properties p)
      Examine the boot properties and determine if a boot with the given attributes should stop slave replication mode. A connection with this property should only be made from SlaveDatabase. Make sure to call SlaveDatabase.verifyShutdownSlave() to verify that this connection is not made from a client.
      Parameters:
      p - The attribute set.
      Returns:
      true if the shutdownslave attribute has been set, false otherwise.
    • isSet

      private static boolean isSet(Properties p, String attribute)
      Tells if the attribute/property has been set.
    • isTrue

      private static boolean isTrue(Properties p, String attribute)
      Tells if the attribute/property has the value true.
    • vetTrue

      private static boolean vetTrue(Properties p, String attribute) throws SQLException
      Returns true if the attribute exists and is set to true. Raises an exception if the attribute exists and is set to something else.
      Throws:
      SQLException
    • getReplicationOperation

      private String getReplicationOperation(Properties p) throws StandardException
      Throws:
      StandardException
    • handleStartReplicationMaster

      private void handleStartReplicationMaster(TransactionResourceImpl tr, Properties p) throws SQLException
      Throws:
      SQLException
    • handleStopReplicationMaster

      private void handleStopReplicationMaster(TransactionResourceImpl tr, Properties p) throws SQLException
      Throws:
      SQLException
    • handleStopReplicationSlave

      private void handleStopReplicationSlave(Database database, Properties p) throws StandardException, SQLException
      Stop replication slave when called from a client. Stops replication slave mode, provided that the database is in replication slave mode and has lost connection with the master database. If the connection with the master is up, the call to this method will be refused by raising an exception. The reason for refusing the stop command if the slave is connected with the master is that we cannot authenticate the user on the slave side (because the slave database has not been fully booted) whereas authentication is not a problem on the master side. If not refused, this operation will cause SlaveDatabase to call internalStopReplicationSlave
      Parameters:
      database - The database the stop slave operation will be performed on
      p - The Attribute set.
      Throws:
      StandardException - Thrown on error, if not in replication slave mode or if the network connection with the master is not down
      SQLException - Thrown if the database has not been booted or if stopSlave is performed successfully
    • internalStopReplicationSlave

      private void internalStopReplicationSlave(Database database, Properties p) throws StandardException, SQLException
      Stop replication slave when called from SlaveDatabase. Called when slave replication mode has been stopped, and all that remains is to shutdown the database. This happens if handleStopReplicationSlave has successfully requested the slave to stop, if the replication master has requested the slave to stop using the replication network, or if a fatal exception has occurred in the database.
      Parameters:
      database - The database the internal stop slave operation will be performed on
      p - The Attribute set.
      Throws:
      StandardException - Thrown on error or if not in replication slave mode
      SQLException - Thrown if the database has not been booted or if this connection was not made internally from SlaveDatabase
    • handleFailoverMaster

      private void handleFailoverMaster(TransactionResourceImpl tr) throws SQLException, StandardException
      Used to authorize and verify the privileges of the user and initiate failover.
      Parameters:
      tr - an instance of TransactionResourceImpl Links the connection to the database.
      Throws:
      StandardException - 1) If the failover succeeds, an exception is thrown to indicate that the master database was shutdown after a successful failover 2) If a failure occurs during network communication with slave.
      SQLException - 1) Thrown upon a authorization failure.
    • handleFailoverSlave

      private void handleFailoverSlave(Database database) throws SQLException
      Used to perform failover on a database in slave replication mode. Performs failover, provided that the database is in replication slave mode and has lost connection with the master database. If the connection with the master is up, the call to this method will be refused by raising an exception. The reason for refusing the failover command if the slave is connected with the master is that we cannot authenticate the user on the slave side (because the slave database has not been fully booted) whereas authentication is not a problem on the master side. If not refused, this method will apply all operations received from the master and complete the booting of the database so that it can be connected to.
      Parameters:
      database - The database the failover operation will be performed on
      Throws:
      SQLException - Thrown on error, if not in replication slave mode or if the network connection with the master is not down
    • removePhaseTwoProps

      private Properties removePhaseTwoProps(Properties p)
      Remove any encryption or upgarde properties from the given properties
      Parameters:
      p - the attribute set
      Returns:
      clone sans encryption properties
    • checkUserCredentials

      private void checkUserCredentials(boolean creatingDatabase, String dbname, Properties userInfo) throws SQLException
      Throws:
      SQLException
    • emptyCredential

      private boolean emptyCredential(String credential)

      Forbid empty or null usernames and passwords.

    • compareDatabaseNames

      private boolean compareDatabaseNames(String leftDBName, String rightDBName) throws SQLException
      Compare two user-specified database names to see if they identify the same database.
      Throws:
      SQLException
    • checkUserIsNotARole

      private void checkUserIsNotARole() throws SQLException
      If applicable, check that we don't connect with a user name that equals a role.
      Throws:
      SQLException - Will throw if the current authorization id in lcc (which is already normalized to case normal form - CNF) equals an existing role name (which is also stored in CNF).
    • checkIsDBOwner

      private void checkIsDBOwner(int operation) throws SQLException
      Check if actual authenticationId is equal to the database owner's.
      Parameters:
      operation - attempted operation which needs database owner powers
      Throws:
      SQLException - if actual authenticationId is different from authenticationId of database owner.
    • getEngineType

      public int getEngineType()
      Gets the EngineType of the connected database.
      Returns:
      0 if there is no database, the engine type otherwise. @see org.apache.derby.iapi.reference.EngineType
    • createStatement

      public final Statement createStatement() throws SQLException
      SQL statements without parameters are normally executed using Statement objects. If the same SQL statement is executed many times, it is more efficient to use a PreparedStatement JDBC 2.0 Result sets created using the returned Statement will have forward-only type, and read-only concurrency, by default.
      Specified by:
      createStatement in interface Connection
      Returns:
      a new Statement object
      Throws:
      SQLException - if a database-access error occurs.
    • createStatement

      public final Statement createStatement(int resultSetType, int resultSetConcurrency) throws SQLException
      JDBC 2.0 Same as createStatement() above, but allows the default result set type and result set concurrency type to be overridden.
      Specified by:
      createStatement in interface Connection
      Parameters:
      resultSetType - a result set type, see ResultSet.TYPE_XXX
      resultSetConcurrency - a concurrency type, see ResultSet.CONCUR_XXX
      Returns:
      a new Statement object
      Throws:
      SQLException - if a database-access error occurs.
    • createStatement

      public final Statement createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException
      JDBC 3.0 Same as createStatement() above, but allows the default result set type, result set concurrency type and result set holdability type to be overridden.
      Specified by:
      createStatement in interface Connection
      Parameters:
      resultSetType - a result set type, see ResultSet.TYPE_XXX
      resultSetConcurrency - a concurrency type, see ResultSet.CONCUR_XXX
      resultSetHoldability - a holdability type, ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT
      Returns:
      a new Statement object
      Throws:
      SQLException - if a database-access error occurs.
    • prepareStatement

      public final PreparedStatement prepareStatement(String sql) throws SQLException
      A SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times.

      Note: This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement is executed. This has no direct affect on users; however, it does affect which method throws certain SQLExceptions. JDBC 2.0 Result sets created using the returned PreparedStatement will have forward-only type, and read-only concurrency, by default.

      Specified by:
      prepareStatement in interface Connection
      Parameters:
      sql - a SQL statement that may contain one or more '?' IN parameter placeholders
      Returns:
      a new PreparedStatement object containing the pre-compiled statement
      Throws:
      SQLException - if a database-access error occurs.
    • prepareStatement

      public final PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency) throws SQLException
      JDBC 2.0 Same as prepareStatement() above, but allows the default result set type and result set concurrency type to be overridden.
      Specified by:
      prepareStatement in interface Connection
      Parameters:
      resultSetType - a result set type, see ResultSet.TYPE_XXX
      resultSetConcurrency - a concurrency type, see ResultSet.CONCUR_XXX
      Returns:
      a new PreparedStatement object containing the pre-compiled SQL statement
      Throws:
      SQLException - if a database-access error occurs.
    • prepareStatement

      public final PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException
      JDBC 3.0 Same as prepareStatement() above, but allows the default result set type, result set concurrency type and result set holdability to be overridden.
      Specified by:
      prepareStatement in interface Connection
      Parameters:
      resultSetType - a result set type, see ResultSet.TYPE_XXX
      resultSetConcurrency - a concurrency type, see ResultSet.CONCUR_XXX
      resultSetHoldability - - one of the following ResultSet constants: ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT
      Returns:
      a new PreparedStatement object containing the pre-compiled SQL statement
      Throws:
      SQLException - if a database-access error occurs.
    • prepareStatement

      public final PreparedStatement prepareStatement(String sql, int[] columnIndexes) throws SQLException
      Creates a default PreparedStatement object capable of returning the auto-generated keys designated by the given array. This array contains the indexes of the columns in the target table that contain the auto-generated keys that should be made available. This array is ignored if the SQL statement is not an INSERT statement JDBC 3.0
      Specified by:
      prepareStatement in interface Connection
      Parameters:
      sql - An SQL statement that may contain one or more ? IN parameter placeholders
      columnIndexes - An array of column indexes indicating the columns that should be returned from the inserted row or rows
      Returns:
      A new PreparedStatement object, containing the pre-compiled SQL statement, that will have the capability of returning auto-generated keys designated by the given array of column indexes
      Throws:
      SQLException - Thrown on error.
    • prepareStatement

      public final PreparedStatement prepareStatement(String sql, String[] columnNames) throws SQLException
      Creates a default PreparedStatement object capable of returning the auto-generated keys designated by the given array. This array contains the names of the columns in the target table that contain the auto-generated keys that should be returned. This array is ignored if the SQL statement is not an INSERT statement JDBC 3.0
      Specified by:
      prepareStatement in interface Connection
      Parameters:
      sql - An SQL statement that may contain one or more ? IN parameter placeholders
      columnNames - An array of column names indicating the columns that should be returned from the inserted row or rows
      Returns:
      A new PreparedStatement object, containing the pre-compiled SQL statement, that will have the capability of returning auto-generated keys designated by the given array of column names
      Throws:
      SQLException - Thrown on error.
    • prepareStatement

      public final PreparedStatement prepareStatement(String sql, int autoGeneratedKeys) throws SQLException
      Creates a default PreparedStatement object that has the capability to retieve auto-generated keys. The given constant tells the driver whether it should make auto-generated keys available for retrieval. This parameter is ignored if the SQL statement is not an INSERT statement. JDBC 3.0
      Specified by:
      prepareStatement in interface Connection
      Parameters:
      sql - A SQL statement that may contain one or more ? IN parameter placeholders
      autoGeneratedKeys - A flag indicating whether auto-generated keys should be returned
      Returns:
      A new PreparedStatement object, containing the pre-compiled SQL statement, that will have the capability of returning auto-generated keys
      Throws:
      SQLException - Feature not implemented for now.
    • prepareStatement

      private PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability, int autoGeneratedKeys, int[] columnIndexes, String[] columnNames) throws SQLException
      Throws:
      SQLException
    • prepareCall

      public final CallableStatement prepareCall(String sql) throws SQLException
      A SQL stored procedure call statement is handled by creating a CallableStatement for it. The CallableStatement provides methods for setting up its IN and OUT parameters, and methods for executing it.

      Note: This method is optimized for handling stored procedure call statements. Some drivers may send the call statement to the database when the prepareCall is done; others may wait until the CallableStatement is executed. This has no direct affect on users; however, it does affect which method throws certain SQLExceptions. JDBC 2.0 Result sets created using the returned CallableStatement will have forward-only type, and read-only concurrency, by default.

      Specified by:
      prepareCall in interface Connection
      Parameters:
      sql - a SQL statement that may contain one or more '?' parameter placeholders. Typically this statement is a JDBC function call escape string.
      Returns:
      a new CallableStatement object containing the pre-compiled SQL statement
      Throws:
      SQLException - if a database-access error occurs.
    • prepareCall

      public final CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency) throws SQLException
      JDBC 2.0 Same as prepareCall() above, but allows the default result set type and result set concurrency type to be overridden.
      Specified by:
      prepareCall in interface Connection
      Parameters:
      resultSetType - a result set type, see ResultSet.TYPE_XXX
      resultSetConcurrency - a concurrency type, see ResultSet.CONCUR_XXX
      Returns:
      a new CallableStatement object containing the pre-compiled SQL statement
      Throws:
      SQLException - if a database-access error occurs.
    • prepareCall

      public final CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException
      JDBC 3.0 Same as prepareCall() above, but allows the default result set type, result set concurrency type and result set holdability to be overridden.
      Specified by:
      prepareCall in interface Connection
      Parameters:
      resultSetType - a result set type, see ResultSet.TYPE_XXX
      resultSetConcurrency - a concurrency type, see ResultSet.CONCUR_XXX
      resultSetHoldability - - one of the following ResultSet constants: ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT
      Returns:
      a new CallableStatement object containing the pre-compiled SQL statement
      Throws:
      SQLException - if a database-access error occurs.
    • nativeSQL

      public String nativeSQL(String sql) throws SQLException
      A driver may convert the JDBC sql grammar into its system's native SQL grammar prior to sending it; nativeSQL returns the native form of the statement that the driver would have sent.
      Specified by:
      nativeSQL in interface Connection
      Parameters:
      sql - a SQL statement that may contain one or more '?' parameter placeholders
      Returns:
      the native form of this statement
      Throws:
      SQLException
    • setAutoCommit

      public void setAutoCommit(boolean autoCommit) throws SQLException
      If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by either commit() or rollback(). By default, new connections are in auto-commit mode. The commit occurs when the statement completes or the next execute occurs, whichever comes first. In the case of statements returning a ResultSet, the statement completes when the last row of the ResultSet has been retrieved or the ResultSet has been closed. In advanced cases, a single statement may return multiple results as well as output parameter values. Here the commit occurs when all results and output param values have been retrieved.
      Specified by:
      setAutoCommit in interface Connection
      Parameters:
      autoCommit - true enables auto-commit; false disables auto-commit.
      Throws:
      SQLException - if a database-access error occurs.
    • getAutoCommit

      public boolean getAutoCommit() throws SQLException
      Get the current auto-commit state.
      Specified by:
      getAutoCommit in interface Connection
      Returns:
      Current state of auto-commit mode.
      Throws:
      SQLException
      See Also:
    • commit

      public void commit() throws SQLException
      Commit makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection. This method should only be used when auto commit has been disabled.
      Specified by:
      commit in interface Connection
      Throws:
      SQLException - if a database-access error occurs.
      See Also:
    • rollback

      public void rollback() throws SQLException
      Rollback drops all changes made since the previous commit/rollback and releases any database locks currently held by the Connection. This method should only be used when auto commit has been disabled.
      Specified by:
      rollback in interface Connection
      Throws:
      SQLException - if a database-access error occurs.
      See Also:
    • close

      public void close() throws SQLException
      In some cases, it is desirable to immediately release a Connection's database and JDBC resources instead of waiting for them to be automatically released; the close method provides this immediate release.

      Note: A Connection is automatically closed when it is garbage collected. Certain fatal errors also result in a closed Connection.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Connection
      Throws:
      SQLException - if a database-access error occurs.
    • checkForTransactionInProgress

      public void checkForTransactionInProgress() throws SQLException
      Check if the transaction is active so that we cannot close down the connection. If auto-commit is on, the transaction is committed when the connection is closed, so it is always OK to close the connection in that case. Otherwise, throw an exception if a transaction is in progress.
      Throws:
      SQLException - if this transaction is active and the connection cannot be closed
    • close

      protected void close(StandardException e) throws SQLException
      Throws:
      SQLException
    • isClosed

      public final boolean isClosed()
      Tests to see if a Connection is closed.
      Specified by:
      isClosed in interface Connection
      Returns:
      true if the connection is closed; false if it's still open
    • getMetaData

      public DatabaseMetaData getMetaData() throws SQLException
      A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, etc. This information is made available through a DatabaseMetaData object.
      Specified by:
      getMetaData in interface Connection
      Returns:
      a DatabaseMetaData object for this Connection
      Throws:
      SQLException - if a database-access error occurs.
    • getHoldability

      public final int getHoldability() throws SQLException
      JDBC 3.0 Retrieves the current holdability of ResultSet objects created using this Connection object.
      Specified by:
      getHoldability in interface Connection
      Returns:
      The holdability, one of ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT
      Throws:
      SQLException
    • setHoldability

      public final void setHoldability(int holdability) throws SQLException
      JDBC 3.0 Changes the holdability of ResultSet objects created using this Connection object to the given holdability.
      Specified by:
      setHoldability in interface Connection
      Parameters:
      holdability - A ResultSet holdability constant, one of ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT
      Throws:
      SQLException
    • setReadOnly

      public final void setReadOnly(boolean readOnly) throws SQLException
      You can put a connection in read-only mode as a hint to enable database optimizations.

      Note: setReadOnly cannot be called while in the middle of a transaction.

      Specified by:
      setReadOnly in interface Connection
      Parameters:
      readOnly - true enables read-only mode; false disables read-only mode.
      Throws:
      SQLException - if a database-access error occurs.
    • isReadOnly

      public final boolean isReadOnly() throws SQLException
      Tests to see if the connection is in read-only mode.
      Specified by:
      isReadOnly in interface Connection
      Returns:
      true if connection is read-only
      Throws:
      SQLException - if a database-access error occurs.
    • setCatalog

      public void setCatalog(String catalog) throws SQLException
      A sub-space of this Connection's database may be selected by setting a catalog name. If the driver does not support catalogs it will silently ignore this request.
      Specified by:
      setCatalog in interface Connection
      Throws:
      SQLException - if a database-access error occurs.
    • getCatalog

      public String getCatalog() throws SQLException
      Return the Connection's current catalog name.
      Specified by:
      getCatalog in interface Connection
      Returns:
      the current catalog name or null
      Throws:
      SQLException - if a database-access error occurs.
    • setTransactionIsolation

      public void setTransactionIsolation(int level) throws SQLException
      You can call this method to try to change the transaction isolation level using one of the TRANSACTION_* values.

      Note: setTransactionIsolation causes the current transaction to commit if the isolation level is changed. Otherwise, if the requested isolation level is the same as the current isolation level, this method is a no-op.

      Specified by:
      setTransactionIsolation in interface Connection
      Parameters:
      level - one of the TRANSACTION_* isolation values with the exception of TRANSACTION_NONE; some databases may not support other values
      Throws:
      SQLException - if a database-access error occurs.
      See Also:
    • getTransactionIsolation

      public final int getTransactionIsolation() throws SQLException
      Get this Connection's current transaction isolation mode.
      Specified by:
      getTransactionIsolation in interface Connection
      Returns:
      the current TRANSACTION_* mode value
      Throws:
      SQLException - if a database-access error occurs.
    • getWarnings

      public final SQLWarning getWarnings() throws SQLException
      The first warning reported by calls on this Connection is returned.

      Note: Subsequent warnings will be chained to this SQLWarning.

      Specified by:
      getWarnings in interface Connection
      Returns:
      the first SQLWarning or null Synchronization note: Warnings are synchronized on nesting level
      Throws:
      SQLException
    • clearWarnings

      public final void clearWarnings() throws SQLException
      After this call, getWarnings returns null until a new warning is reported for this Connection. Synchronization node: Warnings are synchonized on nesting level
      Specified by:
      clearWarnings in interface Connection
      Throws:
      SQLException
    • setTypeMap

      public final void setTypeMap(Map map) throws SQLException
      Install a type-map object as the default type-map for this connection. JDBC 2.0 - java.util.Map requires JDK 1
      Specified by:
      setTypeMap in interface Connection
      Throws:
      SQLException - Feature not implemented for now.
    • addWarning

      public final void addWarning(SQLWarning newWarning)
      Add a warning to the current list of warnings, to follow this note from Connection.getWarnings. Note: Subsequent warnings will be chained to this SQLWarning.
      Specified by:
      addWarning in interface EngineConnection
      Parameters:
      newWarning - Warning to be added, will be chained to any existing warnings.
      See Also:
    • getDBName

      public String getDBName()
      Return the dbname for this connection.
      Returns:
      String The dbname for this connection.
    • getLanguageConnection

      public final LanguageConnectionContext getLanguageConnection()
    • checkIfClosed

      protected final void checkIfClosed() throws SQLException
      Raises an exception if the connection is closed.
      Throws:
      SQLException - if the connection is closed
    • handleException

      SQLException handleException(Throwable thrownException) throws SQLException
      Throws:
      SQLException
    • handleException

      final SQLException handleException(Throwable thrownException, boolean rollbackOnAutoCommit) throws SQLException
      Handle any type of Exception.
      • Inform the contexts of the error
      • Throw an Util based upon the thrown exception.
      REMIND: now that we know all the exceptions from our driver are Utils, would it make sense to shut down the system for unknown SQLExceptions? At present, we do not. Because this is the last stop for exceptions, it will catch anything that occurs in it and try to cleanup before re-throwing them.
      Parameters:
      thrownException - the exception
      rollbackOnAutoCommit - rollback the xact on if autocommit is on, otherwise rollback stmt but leave xact open (and continue to hold on to locks). Most of the time, this will be true, excepting operations on result sets, like getInt().
      Throws:
      SQLException
    • setInactive

      public final void setInactive()
      Close the connection when processing errors, or when closing a nested connection.

      This only marks it as closed and frees up its resources; any closing of the underlying connection or commit work is assumed to be done elsewhere. Called from EmbedConnectionContext's cleanup routine, and by proxy.close().

    • finalize

      protected void finalize() throws Throwable
      Overrides:
      finalize in class Object
      Throws:
      Throwable - standard error policy
    • needCommit

      protected void needCommit()
      if auto commit is on, remember that we need to commit the current statement.
    • commitIfNeeded

      protected void commitIfNeeded() throws SQLException
      if a commit is needed, perform it. Must have connection synchonization and context set up already.
      Throws:
      SQLException - if commit returns error
    • commitIfAutoCommit

      protected void commitIfAutoCommit() throws SQLException
      If in autocommit, then commit. Used to force a commit after a result set closes in autocommit mode. The needCommit mechanism does not work correctly as there are times with cursors (like a commit, followed by a next, followed by a close) where the system does not think it needs a commit but we need to force the commit on close. It seemed safer to just force a commit on close rather than count on keeping the needCommit flag correct for all cursor cases. Must have connection synchonization and context set up already.
      Throws:
      SQLException - if commit returns error
    • getConnectionSynchronization

      protected final Object getConnectionSynchronization()
    • setupContextStack

      protected final void setupContextStack() throws SQLException
      Install the context manager for this thread. Check connection status here.
      Throws:
      SQLException - if fails
    • restoreContextStack

      protected final void restoreContextStack() throws SQLException
      Throws:
      SQLException
    • createDatabase

      private Database createDatabase(String dbname, Properties info) throws SQLException
      Create a new database.
      Parameters:
      dbname - the database name
      info - the properties
      Returns:
      Database The newly created database or null.
      Throws:
      SQLException - if fails to create database
    • checkDatabaseCreatePrivileges

      private void checkDatabaseCreatePrivileges(String user, String dbname) throws SQLException
      Checks that a user has the system privileges to create a database. To perform this check the following policy grants are required
      • to run the encapsulated test: permission javax.security.auth.AuthPermission "doAsPrivileged";
      • to resolve relative path names: permission java.util.PropertyPermission "user.dir", "read";
      • to canonicalize path names: permission java.io.FilePermission "...", "read";
      or a SQLException will be raised detailing the cause.

      In addition, for the test to succeed

      • the given user needs to be covered by a grant: principal org.apache.derby.authentication.SystemPrincipal "..." {}
      • that lists a permission covering the database location: permission org.apache.derby.security.DatabasePermission "directory:...", "create";
      or it will fail with a SQLException detailing the cause.
      Parameters:
      user - The user to be checked for database create privileges
      dbname - the name of the database to create
      Throws:
      SQLException - if the privileges check fails
    • sleep

      private static void sleep(long millis)
      Puts the current thread to sleep.

      NOTE: This method guarantees that the thread sleeps at least millis milliseconds.

      Parameters:
      millis - milliseconds to sleep
    • stripSubSubProtocolPrefix

      public static String stripSubSubProtocolPrefix(String dbname)
      Strips any sub-sub-protocol prefix from a database name.
      Parameters:
      dbname - a database name
      Returns:
      the database name without any sub-sub-protocol prefixes
      Throws:
      NullPointerException - if dbname is null
    • bootDatabase

      private boolean bootDatabase(Properties info, boolean softAuthenticationBoot) throws Throwable
      Boot database.
      Parameters:
      info - boot properties
      softAuthenticationBoot - If true, don't fail soft upgrade due to missing features (phase one of two phased hard upgrade boot).
      Returns:
      false iff the monitor cannot handle a service of the type indicated by the protocol within the name. If that's the case then we are the wrong driver.
      Throws:
      Throwable - if anything else is wrong.
    • prepareMetaDataStatement

      PreparedStatement prepareMetaDataStatement(String sql) throws SQLException
      Throws:
      SQLException
    • getLocalDriver

      public final InternalDriver getLocalDriver()
    • getContextManager

      public final ContextManager getContextManager()
      Return the context manager for this connection.
    • filterProperties

      private Properties filterProperties(Properties inputSet)
      Filter out properties from the passed in set of JDBC attributes to remove any derby.* properties. This is to ensure that setting derby.* properties does not work this way, it's not a defined way to set such properties and could be a secuirty hole in allowing remote connections to override system, application or database settings.
      Returns:
      a new Properties set copied from the parameter but with no derby.* properties.
    • getDatabase

      protected Database getDatabase()
    • getTR

      protected final TransactionResourceImpl getTR()
    • pushConnectionContext

      private EmbedConnectionContext pushConnectionContext(ContextManager cm)
    • setApplicationConnection

      public final void setApplicationConnection(Connection applicationConnection)
    • getApplicationConnection

      public final Connection getApplicationConnection()
    • setDrdaID

      public void setDrdaID(String drdaID)
      Description copied from interface: EngineConnection
      Set the DRDA identifier for this connection.
      Specified by:
      setDrdaID in interface EngineConnection
    • isInGlobalTransaction

      public boolean isInGlobalTransaction()
      Description copied from interface: EngineConnection
      Is this a global transaction
      Specified by:
      isInGlobalTransaction in interface EngineConnection
      Returns:
      true if this is a global XA transaction
      See Also:
    • resetFromPool

      public void resetFromPool() throws SQLException
      Reset the connection before it is returned from a PooledConnection to a new application request (wrapped by a BrokeredConnection). Examples of reset covered here is dropping session temporary tables and reseting IDENTITY_VAL_LOCAL. Most JDBC level reset is handled by calling standard java.sql.Connection methods from EmbedPooledConnection.
      Specified by:
      resetFromPool in interface EngineConnection
      Throws:
      SQLException
    • xa_prepare

      public final int xa_prepare() throws SQLException
      Do not use this method directly use XATransactionState.xa_prepare instead because it also maintains/cancels the timeout task which is scheduled to cancel/rollback the global transaction.
      Returns:
      One of XATransactionController.XA_OK or XATransactionController.XA_RDONLY
      Throws:
      SQLException
    • xa_commit

      public final void xa_commit(boolean onePhase) throws SQLException
      Do not use this method directly use XATransactionState.xa_commit instead because it also maintains/cancels the timout task which is scheduled to cancel/rollback the global transaction.
      Throws:
      SQLException
    • xa_rollback

      public final void xa_rollback() throws SQLException
      Do not use this method directly use XATransactionState.xa_rollback instead because it also maintains/cancels the timout task which is scheduled to cancel/rollback the global transaction.
      Throws:
      SQLException
    • transactionIsIdle

      public final boolean transactionIsIdle()
      returns false if there is an underlying transaction and that transaction has done work. True if there is no underlying transaction or that underlying transaction is idle
    • setResultSetType

      private int setResultSetType(int resultSetType)
    • setPrepareIsolation

      public void setPrepareIsolation(int level) throws SQLException
      Set the transaction isolation level that will be used for the next prepare. Used by network server to implement DB2 style isolation levels.
      Specified by:
      setPrepareIsolation in interface EngineConnection
      Parameters:
      level - Isolation level to change to. level is the DB2 level specified in the package names which happen to correspond to our internal levels. If level == TransactionControl.UNSPECIFIED_ISOLATION, the statement won't be prepared with an isolation level.
      Throws:
      SQLException
    • getPrepareIsolation

      public int getPrepareIsolation()
      Return prepare isolation
      Specified by:
      getPrepareIsolation in interface EngineConnection
    • getResultSetOrderId

      final int getResultSetOrderId()
      Return a unique order number for a result set. A unique value is only needed if the result set is being created within procedure and thus must be using a nested connection.
    • newSQLException

      static SQLException newSQLException(String messageId, Object... args)
    • toString

      public String toString()
      Get a String representation that uniquely identifies this connection. Include the same information that is printed in the log for various trace and error messages. In Derby the "physical" connection is a LanguageConnectionContext, or LCC. The JDBC Connection is an JDBC-specific layer on top of this. Rather than create a new id here, we simply use the id of the underlying LCC. Note that this is a big aid in debugging, because much of the engine trace and log code prints the LCC id.
      Overrides:
      toString in class Object
      Returns:
      a string representation for this connection
    • createClob

      public Clob createClob() throws SQLException
      Constructs an object that implements the Clob interface. The object returned initially contains no data. The setAsciiStream, setCharacterStream and setString methods of the Clob interface may be used to add data to the Clob.
      Specified by:
      createClob in interface Connection
      Returns:
      An object that implements the Clob interface
      Throws:
      SQLException - if an object that implements the Clob interface can not be constructed, this method is called on a closed connection or a database access error occurs.
    • createBlob

      public Blob createBlob() throws SQLException
      Constructs an object that implements the Blob interface. The object returned initially contains no data. The setBinaryStream and setBytes methods of the Blob interface may be used to add data to the Blob.
      Specified by:
      createBlob in interface Connection
      Returns:
      An object that implements the Blob interface
      Throws:
      SQLException - if an object that implements the Blob interface can not be constructed, this method is called on a closed connection or a database access error occurs.
    • addLOBMapping

      public int addLOBMapping(Object LOBReference)
      Add the locator and the corresponding LOB object into the HashMap
      Parameters:
      LOBReference - The object which contains the LOB object that that is added to the HashMap.
      Returns:
      an integer that represents the locator that has been allocated to this LOB.
    • removeLOBMapping

      public void removeLOBMapping(int key)
      Remove the key(LOCATOR) from the hash table.
      Parameters:
      key - an integer that represents the locator that needs to be removed from the table.
    • getLOBMapping

      public Object getLOBMapping(int key)
      Get the LOB reference corresponding to the locator.
      Specified by:
      getLOBMapping in interface EngineConnection
      Parameters:
      key - the integer that represents the LOB locator value.
      Returns:
      the LOB Object corresponding to this locator.
    • clearLOBMapping

      private void clearLOBMapping() throws SQLException
      Clear the HashMap of all entries. Called when a commit or rollback of the transaction happens.
      Throws:
      SQLException
    • getIncLOBKey

      private int getIncLOBKey()
      Return the current locator value/ 0x800x values are not valid values as they are used to indicate the BLOB is being sent by value, so we skip those values (DERBY-3243)
      Returns:
      an integer that represents the most recent locator value.
    • addLOBReference

      void addLOBReference(Object lobReference)
      Adds an entry of the lob in WeakHashMap. These entries are used for cleanup during commit/rollback or close.
      Parameters:
      lobReference - LOB Object
    • getlobHMObj

      private HashMap<Integer,Object> getlobHMObj()
      Return the Hash Map in the root connection
      Returns:
      the HashMap that contains the locator to LOB object mapping
    • cancelRunningStatement

      public void cancelRunningStatement()
      Cancels the current running statement.
    • getCurrentSchemaName

      public String getCurrentSchemaName()
      Obtain the name of the current schema. Not part of the java.sql.Connection interface, but is accessible through the EngineConnection interface, so that the NetworkServer can get at the current schema for piggy-backing
      Specified by:
      getCurrentSchemaName in interface EngineConnection
      Returns:
      the current schema name
    • addLobFile

      void addLobFile(LOBFile lobFile)
      Add a temporary lob file to the lobFiles set. This will get closed at transaction end or removed as the lob is freed.
      Parameters:
      lobFile - LOBFile to add
    • removeLobFile

      void removeLobFile(LOBFile lobFile)
      Remove LOBFile from the lobFiles set. This will occur when the lob is freed or at transaction end if the lobFile was removed from the WeakHashMap but not finalized.
      Parameters:
      lobFile - LOBFile to remove.
    • isAborting

      public boolean isAborting()
      Return true if the connection is aborting
    • beginAborting

      protected void beginAborting()
      Begin aborting the connection
    • setSavepoint

      public Savepoint setSavepoint() throws SQLException
      Creates an unnamed savepoint in the current transaction and returns the new Savepoint object that represents it.
      Specified by:
      setSavepoint in interface Connection
      Returns:
      The new Savepoint object
      Throws:
      SQLException - if a database access error occurs or this Connection object is currently in auto-commit mode
    • setSavepoint

      public Savepoint setSavepoint(String name) throws SQLException
      Creates a savepoint with the given name in the current transaction and returns the new Savepoint object that represents it.
      Specified by:
      setSavepoint in interface Connection
      Parameters:
      name - A String containing the name of the savepoint
      Returns:
      The new Savepoint object
      Throws:
      SQLException - if a database access error occurs or this Connection object is currently in auto-commit mode
    • commonSetSavepointCode

      private Savepoint commonSetSavepointCode(String name, boolean userSuppliedSavepointName) throws SQLException
      Creates a savepoint with the given name (if it is a named savepoint else we will generate a name because Derby only supports named savepoints internally) in the current transaction and returns the new Savepoint object that represents it.
      Parameters:
      name - A String containing the name of the savepoint. Will be null if this is an unnamed savepoint
      userSuppliedSavepointName - If true means it's a named user defined savepoint.
      Returns:
      The new Savepoint object
      Throws:
      SQLException
    • rollback

      public void rollback(Savepoint savepoint) throws SQLException
      Undoes all changes made after the given Savepoint object was set. This method should be used only when auto-commit has been disabled.
      Specified by:
      rollback in interface Connection
      Parameters:
      savepoint - The Savepoint object to rollback to
      Throws:
      SQLException - if a database access error occurs, the Savepoint object is no longer valid, or this Connection object is currently in auto-commit mode
    • releaseSavepoint

      public void releaseSavepoint(Savepoint savepoint) throws SQLException
      Removes the given Savepoint object from the current transaction. Any reference to the savepoint after it has been removed will cause an SQLException to be thrown
      Specified by:
      releaseSavepoint in interface Connection
      Parameters:
      savepoint - The Savepoint object to be removed
      Throws:
      SQLException - if a database access error occurs or the given Savepoint object is not a valid savepoint in the current transaction
    • verifySavepointCommandIsAllowed

      private void verifySavepointCommandIsAllowed() throws SQLException
      Throws:
      SQLException
    • verifySavepointArg

      private void verifySavepointArg(Savepoint savepoint) throws SQLException
      Throws:
      SQLException
    • getSchema

      public String getSchema() throws SQLException
      Get the name of the current schema.
      Specified by:
      getSchema in interface Connection
      Specified by:
      getSchema in interface EngineConnection
      Throws:
      SQLException
    • setSchema

      public void setSchema(String schemaName) throws SQLException
      Set the default schema for the Connection.
      Specified by:
      setSchema in interface Connection
      Specified by:
      setSchema in interface EngineConnection
      Throws:
      SQLException
    • checkConflictingCryptoAttributes

      private void checkConflictingCryptoAttributes(Properties p) throws SQLException
      Examines the boot properties looking for conflicting cryptographic options and commands.
      Parameters:
      p - boot properties (for instance URL connection attributes)
      Throws:
      SQLException - if conflicting crypto attributes are detected
    • createArrayOf

      public Array createArrayOf(String typeName, Object[] elements) throws SQLException
      Specified by:
      createArrayOf in interface Connection
      Throws:
      SQLException
    • createNClob

      public NClob createNClob() throws SQLException
      Specified by:
      createNClob in interface Connection
      Throws:
      SQLException
    • createSQLXML

      public SQLXML createSQLXML() throws SQLException
      Specified by:
      createSQLXML in interface Connection
      Throws:
      SQLException
    • createStruct

      public Struct createStruct(String typeName, Object[] attributes) throws SQLException
      Specified by:
      createStruct in interface Connection
      Throws:
      SQLException
    • isValid

      public boolean isValid(int timeout) throws SQLException
      Checks if the connection has not been closed and is still valid. The validity is checked by checking that the connection is not closed.
      Specified by:
      isValid in interface Connection
      Parameters:
      timeout - This should be the time in seconds to wait for the database operation used to validate the connection to complete (according to the JDBC4 JavaDoc). This is currently not supported/used.
      Returns:
      true if the connection is valid, false otherwise
      Throws:
      SQLException - if the parameter value is illegal or if a database error has occurred
    • setClientInfo

      public void setClientInfo(String name, String value) throws SQLClientInfoException
      setClientInfo will always throw a SQLClientInfoException since Derby does not support any properties.
      Specified by:
      setClientInfo in interface Connection
      Parameters:
      name - a property key String
      value - a property value String
      Throws:
      SQLClientInfoException - unless both name and value are null
    • setClientInfo

      public void setClientInfo(Properties properties) throws SQLClientInfoException
      setClientInfo will throw a SQLClientInfoException unless the properties parameter is empty, since Derby does not support any properties. All the property keys in the properties parameter are added to failedProperties of the exception thrown, with REASON_UNKNOWN_PROPERTY as the value.
      Specified by:
      setClientInfo in interface Connection
      Parameters:
      properties - a Properties object with the properties to set
      Throws:
      SQLClientInfoException - unless properties parameter is null or empty
    • getClientInfo

      public String getClientInfo(String name) throws SQLException
      getClientInfo always returns a null String since Derby doesn't support ClientInfoProperties.
      Specified by:
      getClientInfo in interface Connection
      Parameters:
      name - a String value
      Returns:
      a null String value
      Throws:
      SQLException - if the connection is closed.
    • getClientInfo

      public Properties getClientInfo() throws SQLException
      getClientInfo always returns an empty Properties object since Derby doesn't support ClientInfoProperties.
      Specified by:
      getClientInfo in interface Connection
      Returns:
      an empty Properties object
      Throws:
      SQLException - if the connection is closed.
    • getTypeMap

      public final Map<String,Class<?>> getTypeMap() throws SQLException
      Returns the type map for this connection.
      Specified by:
      getTypeMap in interface Connection
      Returns:
      type map for this connection
      Throws:
      SQLException - if a database access error occurs
    • isWrapperFor

      public boolean isWrapperFor(Class<?> interfaces) throws SQLException
      Returns false unless interfaces is implemented
      Specified by:
      isWrapperFor in interface Wrapper
      Parameters:
      interfaces - a Class defining an interface.
      Returns:
      true if this implements the interface or directly or indirectly wraps an object that does.
      Throws:
      SQLException - if an error occurs while determining whether this is a wrapper for an object with the given interface.
    • unwrap

      public <T> T unwrap(Class<T> interfaces) throws SQLException
      Returns this if this class implements the interface
      Specified by:
      unwrap in interface Wrapper
      Parameters:
      interfaces - a Class defining an interface
      Returns:
      an object that implements the interface
      Throws:
      SQLException - if no object is found that implements the interface
    • abort

      public void abort(Executor executor) throws SQLException
      Specified by:
      abort in interface Connection
      Specified by:
      abort in interface EngineConnection
      Throws:
      SQLException
    • getNetworkTimeout

      public int getNetworkTimeout() throws SQLException
      Specified by:
      getNetworkTimeout in interface Connection
      Specified by:
      getNetworkTimeout in interface EngineConnection
      Throws:
      SQLException
    • setNetworkTimeout

      public void setNetworkTimeout(Executor executor, int milliseconds) throws SQLException
      Specified by:
      setNetworkTimeout in interface Connection
      Specified by:
      setNetworkTimeout in interface EngineConnection
      Throws:
      SQLException
    • getMonitor

      static ModuleFactory getMonitor()
      Privileged Monitor lookup. Must be package private so that user code can't call this entry point.
    • findService

      private static Object findService(String factoryInterface, String serviceName)
      Privileged service lookup. Must be private so that user code can't call this entry point.
    • startPersistentService

      private static boolean startPersistentService(String serviceName, Properties properties) throws StandardException
      Privileged startup. Must be private so that user code can't call this entry point.
      Throws:
      StandardException
    • createPersistentService

      private static Object createPersistentService(String factoryInterface, String serviceName, Properties properties) throws StandardException
      Privileged startup. Must be private so that user code can't call this entry point.
      Throws:
      StandardException
    • removePersistentService

      private static void removePersistentService(String name) throws StandardException
      Privileged shutdown. Must be private so that user code can't call this entry point.
      Throws:
      StandardException
    • privilegedGetLCC

      private LanguageConnectionContext privilegedGetLCC()
      Private, privileged lookup of the lcc..