Configuring and implementing locking in Java applications

You can define an optimistic, a pessimistic, or no locking strategy on each BackingMap in the WebSphere® eXtreme Scale configuration.

Before you begin

Decide which locking strategy you want to use. For more information, see Locking strategies.
You can also configure a locking strategy with the ObjectGrid descriptor XML file. For more information, see Configuring a locking strategy in the ObjectGrid descriptor XML file.

About this task

To avoid a java.lang.IllegalStateException exception, you must call the setLockStrategy method before calling the initialize or getSession methods on the ObjectGrid instance.

Procedure

Configure a locking strategy in your Java™ application.

Configure an optimistic locking strategy. Use the setLockStrategy method:

import com.ibm.websphere.objectgrid.BackingMap;
import com.ibm.websphere.objectgrid.LockStrategy;
import com.ibm.websphere.objectgrid.ObjectGrid;
import com.ibm.websphere.objectgrid.ObjectGridManagerFactory;
...
ObjectGrid og = 
	ObjectGridManagerFactory.getObjectGridManager().createObjectGrid("test");
BackingMap bm = og.defineMap("optimisticMap");
bm.setLockStrategy( LockStrategy.OPTIMISTIC );

Configure a pessimistic locking strategy. Use the setLockStrategy method:

import com.ibm.websphere.objectgrid.BackingMap;
import com.ibm.websphere.objectgrid.LockStrategy;
import com.ibm.websphere.objectgrid.ObjectGrid;
import com.ibm.websphere.objectgrid.ObjectGridManagerFactory;
...
ObjectGrid og = 
	ObjectGridManagerFactory.getObjectGridManager().createObjectGrid("test");
BackingMap bm = og.defineMap("pessimisticMap");
bm.setLockStrategy( LockStrategy.PESSIMISTIC);

Configure a no locking strategy. Use the setLockStrategy method:

Note: BackingMaps that are configured to use a no locking strategy cannot participate in a multi-partition transaction.

import com.ibm.websphere.objectgrid.BackingMap;
import com.ibm.websphere.objectgrid.LockStrategy;
import com.ibm.websphere.objectgrid.ObjectGrid;
import com.ibm.websphere.objectgrid.ObjectGridManagerFactory;
...
ObjectGrid og = 
	ObjectGridManagerFactory.getObjectGridManager().createObjectGrid("test");
BackingMap bm = og.defineMap("noLockingMap");
bm.setLockStrategy( LockStrategy.NONE);

Configure a lock timeout value.
Use the setLockTimeout method on the BackingMap instance:
```
bm.setLockTimeout( 60 );
```
The setLockTimeout method parameter is a Java primitive integer that specifies the number of seconds that eXtreme Scale waits for a lock mode to be granted. If a transaction waits longer than the lock wait timeout value configured for the BackingMap, a com.ibm.websphere.objectgrid.LockTimeoutException exception results.
If you are using a pessimistic locking strategy, you can use the lock method to lock the key in the data grid or lock the key and determine whether the value exists in the data grid.
In previous releases, you used the get and getForUpdate APIs to lock keys in the data grid. However, if you did not need data from the client, performance degraded when retrieving potentially large value objects to the client. The containsKey method does not hold any locks, so you were forced do use get and getForUpdate methods to get appropriate locks when using pessimistic locking. The lock API now gives you a containsKey method while holding the lock. See the following examples:
- The following methods lock the key in the map, returning true if the key exists, and returning false if the key does not exist.
```
boolean ObjectMap.lock(Object key, LockMode lockMode);
```
- The following method locks a list of keys in the map, returning a list of true or false values; returning true if the key exists, and returning false if the key does not exist.
```
List<Boolean> ObjectMap.lockAll(List keys, LockMode lockMode);
```
  LockMode is an enum with possible values where you can specify the keys that you want to lock:
  - SHARED, UPGRADABLE, and EXCLUSIVE
An example of setting the LockMode parameter follows:
```
session.begin();
map.lock(key, LockMode.UPGRADABLE);
map.upsert();
session.commit()
```