com.sap.engine.services.applocking
Interface TableLocking

public interface TableLocking

Provides methods to lock and unlock rows in database tables. The database table belongs to the given connection. The locks may be in the context of a local transaction, a JTA transaction or an user session. All locks are removed automatically when the session/transaction ends.

See Also:

LogicalLocking

Field Summary

static java.lang.String

JNDI_NAME The name, under wich the TableLocking is bound in the jndi.

Method Summary

void	assertLifetime(byte lifetime) Deprecated. does not work for local transactions
java.lang.String	getCurrentOwner(byte lifetime) Deprecated. use getCurrentOwner(byte, Connection) instead, because does not work for local transactions
java.lang.String	getCurrentOwner(byte lifetime, java.sql.Connection connection) Returns the current owner-id, to which all locks belong.
long	getUniqueIncreasingNumber() Returns a number with the following properties: every method-call returns a higher number than the previous ones the number contains the timestamp of the central server, so this will work correctly in a distrubuted environment and also after a restart of the cluster This number can be used for every purpose, it is not locking-specific.
void	lock(byte lifetime, java.sql.Connection connection, java.lang.String tableName, java.util.Map primaryKeys, char mode) Creates a lock for a row in a table contained in the specified SQL connection.
void	lock(byte lifetime, java.sql.Connection connection, java.lang.String tableName, java.util.Map primaryKeys, char mode, int timeout) Creates a lock for a row in a table contained in the specified SQL connection.
void	unlock(byte lifetime, java.sql.Connection connection, java.lang.String tableName, java.util.Map primaryKeys, char mode) Releases a lock for a row in a table contained in the specified SQL connection.
void	unlock(byte lifetime, java.sql.Connection connection, java.lang.String tableName, java.util.Map primaryKeys, char mode, boolean asynchronous) Releases a lock for a row in a table contained in the specified SQL connection.
void	unlockAll(byte lifetime) Deprecated. use unlockAll(byte, Connection) instead, because does not work for local transactions
void	unlockAll(byte lifetime, boolean asynchronous) Deprecated. use unlockAll(byte, Connection, boolean) instead, because does not work for local transactions
void	unlockAll(byte lifetime, java.sql.Connection connection) Releases all granted locks.
void	unlockAll(byte lifetime, java.sql.Connection connection, boolean asynchronous) Releases all granted locks.

Field Detail

JNDI_NAME

public static final java.lang.String JNDI_NAME

The name, under wich the TableLocking is bound in the jndi.

Method Detail

lock

public void lock(byte lifetime,
                 java.sql.Connection connection,
                 java.lang.String tableName,
                 java.util.Map primaryKeys,
                 char mode)
          throws com.sap.engine.frame.core.locking.LockException,
                 com.sap.engine.frame.core.locking.TechnicalLockException,
                 java.lang.IllegalArgumentException

Creates a lock for a row in a table contained in the specified SQL connection. The row is identified using the argument 'primaryKeys'. This map is required to the have primary key column names as keys and the primary key column values as values. For all primary key columns in the given table, there must be an entry in the map. The value must not be null. All entries in the map must be primary key columns in the given table. There is a restriction on the java types supported, at the moment, only wrapper types of primitives types and and the string type is supported. For generic locks on columns, use the constants defined in the static class TableLocking.GenericLock. Note: The map 'primaryKeys' is required to contain values as they are returned by getter methods on java.sql.ResultSet instances, or, it must contain instances of java.lang wrapper classes in case of primitives. This method looks up a table in the catalog corresponding with the specified SQL connection.

Parameters:

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

connection - The SQL connection instance created by a data source instance which has a corresponding entry in the deployment descriptor of the DB pool. in the deployment descriptor of the DB pool.

tableName - The unqualified name of a table contained in the SQL connection.

primaryKeys - Contains primary key column names to primary key value mappings.

mode - The mode can be MODE_SHARED or MODE_EXCLUSIVE_CUMULATIVE or MODE_EXCLUSIVE_NONCUMULATIVE.

Throws:

LockException - if the lock can not be granted.

java.lang.IllegalArgumentException - if the given primary key map is illegal.

TechnicalLockException - if an technical error occurred.

lock

public void lock(byte lifetime,
                 java.sql.Connection connection,
                 java.lang.String tableName,
                 java.util.Map primaryKeys,
                 char mode,
                 int timeout)
          throws com.sap.engine.frame.core.locking.LockException,
                 com.sap.engine.frame.core.locking.TechnicalLockException,
                 java.lang.IllegalArgumentException

Creates a lock for a row in a table contained in the specified SQL connection. The row is identified using the argument 'primaryKeys'. This map is required to the have primary key column names as keys and the primary key column values as values. For all primary key columns in the given table, there must be an entry in the map. The value must not be null. All entries in the map must be primary key columns in the given table. There is a restriction on the java types supported, at the moment, only wrapper types of primitives types and and the string type is supported. For generic locks on columns, use the constants defined in the static class TableLocking.GenericLock. Note: The map 'primaryKeys' is required to contain values as they are returned by getter methods on java.sql.ResultSet instances, or, it must contain instances of java.lang wrapper classes in case of primitives. This method looks up a table in the catalog corresponding with the specified SQL connection.

Parameters:

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

connection - The SQL connection instance created by a data source instance which has a corresponding entry in the deployment descriptor of the DB pool. in the deployment descriptor of the DB pool.

tableName - The unqualified name of a table contained in the SQL connection.

primaryKeys - Contains primary key column names to primary key value mappings.

mode - The mode can be MODE_SHARED or MODE_EXCLUSIVE_CUMULATIVE or MODE_EXCLUSIVE_NONCUMULATIVE.

timeout - time period in milliseconds within this the lock will be requested several times if there is a lock collision

Throws:

LockException - if the lock can not be granted.

java.lang.IllegalArgumentException - if the given primary key map is illegal.

TechnicalLockException - if an technical error occurred.

unlock

public void unlock(byte lifetime,
                   java.sql.Connection connection,
                   java.lang.String tableName,
                   java.util.Map primaryKeys,
                   char mode)
            throws com.sap.engine.frame.core.locking.TechnicalLockException,
                   java.lang.IllegalArgumentException

Releases a lock for a row in a table contained in the specified SQL connection. The row is identified using the argument 'primaryKeys'. This map is required to the have primary key column names as keys and the primary key column values as values. For all primary key columns in the given table, there must be an entry in the map. The value must not be null. All entries in the map must be primary key columns in the given table. There is a restriction on the java types supported, at the moment, only wrapper types of primitives types and and the string type is supported. For generic locks on columns, use the constants defined in the static class TableLocking.GenericLock. By default the unlock may be done asynchronously (depends on the enqueue server configuration) Note: The map 'primaryKeys' is required to contain values as they are returned by getter methods on java.sql.ResultSet instances, or, it must contain instances of java.lang wrapper classes in case of primitives. This method looks up a table in the catalog corresponding with the specified SQL connection.

Parameters:

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

connection - The SQL connection instance created by a data source instance which has a corresponding entry in the deployment descriptor of the DB pool.

tableName - The unqualified name of a table contained in the SQL connection.

primaryKeys - Contains primary key column to primary key value mappings.

mode - The mode can be MODE_SHARED or MODE_EXCLUSIVE_CUMULATIVE or MODE_EXCLUSIVE_NONCUMULATIVE.

Throws:

java.lang.IllegalArgumentException - if the given primary key map is illegal.

TechnicalLockException - if an technical error occurred.

unlock

public void unlock(byte lifetime,
                   java.sql.Connection connection,
                   java.lang.String tableName,
                   java.util.Map primaryKeys,
                   char mode,
                   boolean asynchronous)
            throws com.sap.engine.frame.core.locking.TechnicalLockException,
                   java.lang.IllegalArgumentException

Releases a lock for a row in a table contained in the specified SQL connection. The row is identified using the argument 'primaryKeys'. This map is required to the have primary key column names as keys and the primary key column values as values. For all primary key columns in the given table, there must be an entry in the map. The value must not be null. All entries in the map must be primary key columns in the given table. There is a restriction on the java types supported, at the moment, only wrapper types of primitives types and and the string type is supported. For generic locks on columns, use the constants defined in the static class TableLocking.GenericLock. By default the unlock may be done asynchronously (depends on the enqueue server configuration) Note: The map 'primaryKeys' is required to contain values as they are returned by getter methods on java.sql.ResultSet instances, or, it must contain instances of java.lang wrapper classes in case of primitives. This method looks up a table in the catalog corresponding with the specified SQL connection.

Parameters:

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

connection - The SQL connection instance created by a data source instance which has a corresponding entry in the deployment descriptor of the DB pool.

tableName - The unqualified name of a table contained in the SQL connection.

primaryKeys - Contains primary key column to primary key value mappings.

mode - The mode can be MODE_SHARED or MODE_EXCLUSIVE_CUMULATIVE or MODE_EXCLUSIVE_NONCUMULATIVE.

asynchronous - If false, then the unlock is done synchronously.

Throws:

java.lang.IllegalArgumentException - if the given primary key map is illegal.

TechnicalLockException - if an technical error occurred.

unlockAll

public void unlockAll(byte lifetime)
               throws com.sap.engine.frame.core.locking.TechnicalLockException,
                      java.lang.IllegalArgumentException

Deprecated. use unlockAll(byte, Connection) instead, because does not work for local transactions

Releases all granted locks. By default the unlock may be done asynchronously (depends on the enqueue server configuration)

Parameters:

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

Throws:

java.lang.IllegalArgumentException - if the given lifetime map is illegal.

TechnicalLockException - if an technical error occurred.

unlockAll

public void unlockAll(byte lifetime,
                      java.sql.Connection connection)
               throws com.sap.engine.frame.core.locking.TechnicalLockException,
                      java.lang.IllegalArgumentException

Releases all granted locks. By default the unlock may be done asynchronously (depends on the enqueue server configuration)

Parameters:

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

connection - The SQL connection instance created by a data source instance

Throws:

java.lang.IllegalArgumentException - if the given lifetime map is illegal.

TechnicalLockException - if an technical error occurred. which has a corresponding entry in the deployment descriptor of the DB pool.

unlockAll

public void unlockAll(byte lifetime,
                      boolean asynchronous)
               throws com.sap.engine.frame.core.locking.TechnicalLockException,
                      java.lang.IllegalArgumentException

Deprecated. use unlockAll(byte, Connection, boolean) instead, because does not work for local transactions

Releases all granted locks. By default the unlock may be done asynchronously (depends on the enqueue server configuration)

Parameters:

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

asynchronous - If false, then the unlock is done synchronously.

Throws:

java.lang.IllegalArgumentException - if the given lifetime map is illegal.

TechnicalLockException - if an technical error occurred.

unlockAll

public void unlockAll(byte lifetime,
                      java.sql.Connection connection,
                      boolean asynchronous)
               throws com.sap.engine.frame.core.locking.TechnicalLockException,
                      java.lang.IllegalArgumentException

Releases all granted locks. By default the unlock may be done asynchronously (depends on the enqueue server configuration)

Parameters:

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

connection - The SQL connection instance created by a data source instance which has a corresponding entry in the deployment descriptor of the DB pool.

asynchronous - If false, then the unlock is done synchronously.

Throws:

java.lang.IllegalArgumentException - if the given lifetime map is illegal.

TechnicalLockException - if an technical error occurred.

assertLifetime

public void assertLifetime(byte lifetime)
                    throws com.sap.engine.frame.core.locking.TechnicalLockException,
                           java.lang.IllegalArgumentException

Deprecated. does not work for local transactions

Returns if locking is currently allowed for the given lifetime. For example LIFETIME_TRANSACTION is not possible, if there is no transaction active.

This method is typically not needed to use the locking. It is meant mainly for debugging-purposes and to support better tracing.

Parameters:

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

Throws:

java.lang.IllegalArgumentException - if the given lifetime map is illegal.

TechnicalLockException - if the lifetime is currently not allowed.

NotSupportedException - if called in a local transaction

getCurrentOwner

public java.lang.String getCurrentOwner(byte lifetime)
                                 throws com.sap.engine.frame.core.locking.TechnicalLockException,
                                        java.lang.IllegalArgumentException

Deprecated. use getCurrentOwner(byte, Connection) instead, because does not work for local transactions

Returns the current owner-id, to which all locks belong. It is dependent on the current session or the current transaction.

This method is not needed to use the locking. It is meant mainly for debugging-purposes and to support better tracing.

Parameters:

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

Throws:

java.lang.IllegalArgumentException - if the given lifetime map is illegal.

TechnicalLockException - if the lifetime is currently not allowed.

NotSupportedException - if called in a local transaction

getCurrentOwner

public java.lang.String getCurrentOwner(byte lifetime,
                                        java.sql.Connection connection)
                                 throws com.sap.engine.frame.core.locking.TechnicalLockException,
                                        java.lang.IllegalArgumentException

Returns the current owner-id, to which all locks belong. It is dependent on the current session or the current transaction.

This method is not needed to use the locking. It is meant mainly for debugging-purposes and to support better tracing.

Parameters:

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

connection - The SQL connection instance created by a data source instance which has a corresponding entry in the deployment descriptor of the DB pool.

Throws:

java.lang.IllegalArgumentException - if the given lifetime map is illegal.

TechnicalLockException - if the lifetime is currently not allowed.

getUniqueIncreasingNumber

public long getUniqueIncreasingNumber()
                               throws com.sap.engine.frame.core.locking.TechnicalLockException

Returns a number with the following properties:

• every method-call returns a higher number than the previous ones
• the number contains the timestamp of the central server, so this will work correctly in a distrubuted environment and also after a restart of the cluster

This number can be used for every purpose, it is not locking-specific.

ATTENTION: if the system-time of the central server is changed this will probably not work correctly any more.