Setting Locks with the TableLocking API

To set locks, you use the lock method of the TableLocking interface:

               public void lock(byte lifetime, 
                                 Connection connection, 
                                 String tableName, 
                                 Map primaryKeys, 
                                 char mode) 
                                 throws LockException, 
                                                TechnicalLockException,
                                                IllegalArgumentException;

            

This method can be used for setting read locks and write locks.

The first parameter lifetime specifies the validity period of the lock. As already mentioned, choose the length of the transaction as the validity period (TableLocking.LIFETIME_TRANSACTION). At the end of the transaction, the locks are then automatically released. If you choose the validity period TableLocking.LIFETIME_USERSESSION, the locks are automatically released at the end of the UserSession.

The third parameter tableName contains the name of the database table (which can be reached by using the database connection).

The fourth parameter primaryKeys is used for defining a row or a generic area. This parameter indicates which primary key columns in the database table are assigned to locking arguments in the form of a java.util.Map. The type of the locking arguments must be get/set-compatible to the JDBC type of the corresponding primary key column. If you enter a wildcard character in a locking argument, you can lock a generic area.

The last parameter mode specifies whether to request a read lock or a write lock. Locks can be requested for single rows or for generic areas of database tables. The constant TableLocking.MODE_SHARED is used to request a read lock, whereas TableLocking.MODE_EXCLUSIVE_CUMULATIVE or TableLocking.MODE_EXCLUSIVE_NONCUMULATIVE are used to request a write lock. Note: TableLocking.MODE_EXCLUSIVE_NONCUMULATIVE prevents an exclusive lock from being requested a second time in a transaction (the opposite is true for TableLocking.MODE_EXCLUSIVE_CUMULATIVE).

               Map pkMap = new HashMap();
pkMap.put("CUSTOMERID ", new Integer(4711));

try {
        locking.lock(TableLocking.LIFETIME_TRANSACTION, 
                                 connection, 
                                 "BC_CR_CUSTOMER", 
                                 pkMap, 
                                 TableLocking.MODE_EXCLUSIVE_CUMULATIVE);
} catch (TechnicalLockException ex) {
        // technical problem
} catch (LockException ex) {
        // lock not granted
}

            

Write Lock : Setting a write lock for customer 4711 in the BC_CR_CUSTOMER table

The primary key consists of the CUSTOMERID column with the JDBC type INTEGER. If a lock cannot be set, a LockException is issued.

As already mentioned, only set these locks within a transaction. Transactions are started by the begin method, ended by the commit method, and reset by the rollback method. The locks are automatically released at the end of the transaction (for commit and rollback).