Show TOC

Background documentationSetting Locks with the LogicalLocking API Locate this document in the navigation structure

 

In the scope of a transaction, applications can lock arbitrary objects within the namespace by invoking the lock() method of the LogicalLocking interface. There are several lock() method signatures enabling the locking of several application objects in one request, specifying a lock timeout, and so on.

In addition, each LogicalLocking instance exposes several locking related constants. Applications are intended to use them when specifying parameters for the lock() method.

Example Example

To lock one or several objects of the same type, you invoke the following method:

  1. public void lock(byte lifetime,
                 java.lang.String name,
                 java.lang.String argument,
                 char mode,
                 int timeout)
          throws com.sap.engine.frame.core.locking.LockException,                com.sap.engine.frame.core.locking.TechnicalLockException,
                 java.lang.IllegalArgumentException;
End of the code.

The lock() method has the following parameters:

  • lifetime

The lifetime parameter specifies the validity period of the lock. The possible values are LogicalLocking.LIFETIME_TRANSACTION and LogicalLocking.LIFETIME_USERSESSION. The lock is assigned to the acquiring transaction or user session respectively. Locks are removed automatically when the transaction/user session ends.

Recommendation Recommendation

We recommend that you use transactional locks (locks with a lifetime of the transaction). These locks are automatically released at the end of the transaction. Nontransactional locks with the lifetime of the user session are automatically released at the end of a UserSession (at the latest, when the user session times out).

End of the recommendation.

  • name

    The name parameter indicates the type of the object. The name string must always start with the namespace to which it belongs. If the name does not follow this convention, an IllegalArgumentException is thrown. The length of the name may be up to LogicalLocking.MAX_NAME_LENGTH characters.

  • argument

    The argument identifies the object by specifying its value. The maximum length may be up to LogicalLocking.MAX_ARGUMENT_LENGTH characters.

    Note Note

    To lock many objects at once, you use the following predefined wildcards within the name and argument:

    End of the note.

    • LogicalLocking.WILDCARD_CHARACTER_MULTI

    • LogicalLocking.WILDCARD_CHARACTER_SINGLE

  • mode

    The mode parameter supplies one of the predefined values to specify an appropriate lock type according to the agreed locking protocol. The possible values are:

    • LogicalLocking.MODE_SHARED

    • LogicalLocking.MODE_EXCLUSIVE_CUMULATIVE

    • LogicalLocking.MODE_EXCLUSIVE_NONCUMULATIVE

  • timeout

    The timeout is an optional parameter specifying a time period in milliseconds within which the lock is requested several times if there is a lock collision.

Lock() methods also provide a number of exceptions. For more information about lock method exceptions and their semantics, refer to the JavaDoc for com.sap.engine.frame.core.locking in the SAP NetWeaver Developer Studio help.