com.sap.engine.services.applocking

Interface LogicalLocking

All Superinterfaces:

com.sap.engine.frame.core.locking.LockingConstants, Remote

public interface LogicalLocking
extends com.sap.engine.frame.core.locking.LockingConstants, Remote

Provides methods similar to the LockingContext, except that the owner may not be set explicitely. Instead the owner is automatically determined by the current user-session and the current transaction (every user-session/transaction has exactly one owner assigned). Because of this every method has instead of the parameter "owner" a parameter "lifetime", which determines which of the owners shall be used.

All locks are removed automatically when the session/transaction is ends.

• A transaction ends when commit/rollback is called or when the timeout occurs, whatever comes first. Attention: transactions are not always bound to user-sessions, so if the user logs out without commit/rollback of the transaction, then the transaction may remain until the timeout occurs.
• A user-session ends, when the user logs out or when the timeout occurs, whatever comes first.

Restriction: it is not alowed to make locks for the user-session of the system-user. This is done because of security-reasons.

Restriction: the parameter 'name' must always start with the namespace, for which this instance of the LogicalLocking was created (see LogicalLockingFactory). For example if the namespace is "XY", then valid names are "XY4711", "XY0815", "XYmeier".

See Also:

LockingContext

Field Summary

Fields inherited from interface com.sap.engine.frame.core.locking.LockingConstants

FILL_CHARACTER, LIFETIME_TRANSACTION, LIFETIME_USERSESSION, MAX_ARGUMENT_LENGTH, MAX_NAME_LENGTH, MAX_OWNER_LENGTH, MAX_USER_LENGTH, MODE_CHECK_EXCLUSIVE_CUMULATIVE, MODE_CHECK_EXCLUSIVE_NONCUMULATIVE, MODE_CHECK_SHARED, MODE_EXCLUSIVE_CUMULATIVE, MODE_EXCLUSIVE_NONCUMULATIVE, MODE_OPTIMISTIC, MODE_OPTIMISTIC_TO_EXCLUSIVE, MODE_SHARED, OWNER_WILDCARD_CHARACTER, WILDCARD_CHARACTER_MULTI, WILDCARD_CHARACTER_SINGLE

Method Summary

void	assertLifetime(byte lifetime) Returns if locking is currently allowed for the given lifetime.
String	getCurrentOwner(byte lifetime) 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, String[] name, String[] argument, char[] mode) Locks several arguments, which belong to a name.
void	lock(byte lifetime, String[] name, String[] argument, char[] mode, int timeout) Locks several arguments, which belong to a name.
void	lock(byte lifetime, String name, String argument, char mode) Locks an argument, which belongs to a name.
void	lock(byte lifetime, String name, String argument, char mode, int timeout) Locks an argument, which belongs to a name.
void	unlock(byte lifetime, String[] name, String[] argument, char[] mode) Unlocks a several arguments, which belongs to a name.
void	unlock(byte lifetime, String[] name, String[] argument, char[] mode, boolean asynchronous) Unlocks a several arguments, which belongs to a name.
void	unlock(byte lifetime, String name, String argument, char mode) Unlocks an argument, which belongs to a name.
void	unlock(byte lifetime, String name, String argument, char mode, boolean asynchronous) Unlocks an argument, which belongs to a name.
void	unlockAll(byte lifetime) Unlocks all names/arguments.
void	unlockAll(byte lifetime, boolean asynchronous) Unlocks all names/arguments.

Method Detail

lock

void lock(byte lifetime,
          String name,
          String argument,
          char mode)
          throws com.sap.engine.frame.core.locking.LockException,
                 com.sap.engine.frame.core.locking.TechnicalLockException,
                 IllegalArgumentException

Locks an argument, which belongs to a name.

Parameters:

name - The name, to which the argument belongs. The maximum size is MAX_NAME_LENGTH characters.

argument - The argument which to lock. The maximum size is MAX_ARGUMENT_LENGTH characters.

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

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

Throws:

com.sap.engine.frame.core.locking.LockException - if the argument is already locked

com.sap.engine.frame.core.locking.TechnicalLockException

IllegalArgumentException

lock

void lock(byte lifetime,
          String name,
          String argument,
          char mode,
          int timeout)
          throws com.sap.engine.frame.core.locking.LockException,
                 com.sap.engine.frame.core.locking.TechnicalLockException,
                 IllegalArgumentException

Locks an argument, which belongs to a name.

Parameters:

name - The name, to which the argument belongs. The maximum size is MAX_NAME_LENGTH characters.

argument - The argument which to lock. The maximum size is MAX_ARGUMENT_LENGTH characters.

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

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

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

Throws:

com.sap.engine.frame.core.locking.LockException - if the argument is already locked

com.sap.engine.frame.core.locking.TechnicalLockException

IllegalArgumentException

lock

void lock(byte lifetime,
          String[] name,
          String[] argument,
          char[] mode)
          throws com.sap.engine.frame.core.locking.LockException,
                 com.sap.engine.frame.core.locking.TechnicalLockException,
                 IllegalArgumentException

Locks several arguments, which belong to a name.

Parameters:

name - The names, to which the argument belongs. The maximum size is MAX_NAME_LENGTH characters.

argument - The arguments which to lock. The maximum size is MAX_ARGUMENT_LENGTH characters.

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

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

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

Throws:

com.sap.engine.frame.core.locking.LockException - if the argument is already locked

com.sap.engine.frame.core.locking.TechnicalLockException

IllegalArgumentException

lock

void lock(byte lifetime,
          String[] name,
          String[] argument,
          char[] mode,
          int timeout)
          throws com.sap.engine.frame.core.locking.LockException,
                 com.sap.engine.frame.core.locking.TechnicalLockException,
                 IllegalArgumentException

Locks several arguments, which belong to a name.

Parameters:

name - The names, to which the argument belongs. The maximum size is MAX_NAME_LENGTH characters.

argument - The arguments which to lock. The maximum size is MAX_ARGUMENT_LENGTH characters.

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

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

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

Throws:

com.sap.engine.frame.core.locking.LockException - if the argument is already locked

com.sap.engine.frame.core.locking.TechnicalLockException

IllegalArgumentException

unlock

void unlock(byte lifetime,
            String name,
            String argument,
            char mode)
            throws com.sap.engine.frame.core.locking.TechnicalLockException,
                   IllegalArgumentException

Unlocks an argument, which belongs to a name. By default the unlock may be done asynchronously.

Parameters:

name - The name, to which the argument belongs. The maximum size is MAX_NAME_LENGTH characters.

argument - The argument which to unlock. The maximum size is MAX_ARGUMENT_LENGTH characters.

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

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

Throws:

com.sap.engine.frame.core.locking.TechnicalLockException

IllegalArgumentException

unlock

void unlock(byte lifetime,
            String name,
            String argument,
            char mode,
            boolean asynchronous)
            throws com.sap.engine.frame.core.locking.TechnicalLockException,
                   IllegalArgumentException

Unlocks an argument, which belongs to a name.

Parameters:

name - The name, to which the argument belongs. The maximum size is MAX_NAME_LENGTH characters.

argument - The argument which to unlock. The maximum size is MAX_ARGUMENT_LENGTH characters.

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

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

asynchronous - If true, then the unlock may be done asynchronously, otherwise it is guaranteed to be done synchronously.

Throws:

com.sap.engine.frame.core.locking.TechnicalLockException

IllegalArgumentException

unlock

void unlock(byte lifetime,
            String[] name,
            String[] argument,
            char[] mode)
            throws com.sap.engine.frame.core.locking.TechnicalLockException,
                   IllegalArgumentException

Unlocks a several arguments, which belongs to a name. By default the unlock may be done asynchronously.

Parameters:

name - The namea, to which the argument belongs. The maximum size is MAX_NAME_LENGTH characters.

argument - The argumenta which to unlock. The maximum size is MAX_ARGUMENT_LENGTH characters.

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

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

Throws:

com.sap.engine.frame.core.locking.TechnicalLockException

IllegalArgumentException

unlock

void unlock(byte lifetime,
            String[] name,
            String[] argument,
            char[] mode,
            boolean asynchronous)
            throws com.sap.engine.frame.core.locking.TechnicalLockException,
                   IllegalArgumentException

Unlocks a several arguments, which belongs to a name.

Parameters:

name - The namea, to which the argument belongs. The maximum size is MAX_NAME_LENGTH characters.

argument - The argumenta which to unlock. The maximum size is MAX_ARGUMENT_LENGTH characters.

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

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

asynchronous - If true, then the unlock may be done asynchronously, otherwise it is guaranteed to be done synchronously.

Throws:

com.sap.engine.frame.core.locking.TechnicalLockException

IllegalArgumentException

unlockAll

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

Unlocks all names/arguments. By default the unlock may be done asynchronously.

Parameters:

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

Throws:

com.sap.engine.frame.core.locking.TechnicalLockException

IllegalArgumentException

unlockAll

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

Unlocks all names/arguments.

Parameters:

lifetime - The lifetime can be either LIFETIME_TRANSACTION or LIFETIME_USERSESSION.

asynchronous - If true, then the unlock may be done asynchronously, otherwise it is guaranteed to be done synchronously.

Throws:

com.sap.engine.frame.core.locking.TechnicalLockException

IllegalArgumentException

assertLifetime

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

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:

com.sap.engine.frame.core.locking.TechnicalLockException - if the lifetime is currently not allowed.

IllegalArgumentException

getCurrentOwner

String getCurrentOwner(byte lifetime)
                       throws com.sap.engine.frame.core.locking.TechnicalLockException,
                              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.

Throws:

com.sap.engine.frame.core.locking.TechnicalLockException

IllegalArgumentException

getUniqueIncreasingNumber

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.

Throws:

com.sap.engine.frame.core.locking.TechnicalLockException

Access Rights

This class can be accessed from:

SC	DC
[sap.com] ENGINEAPI	[sap.com] applocking
[sap.com] ENGFACADE	[sap.com] tc/je/locking/api
[sap.com] CORE-TOOLS	[sap.com] com.sap.engine.client.lib