Ehcache (2.9.x)-API Developer Guide, Using Explicit Locking

About Explicit Locking

Ehcache contains an implementation which provides for explicit locking, using read and write locks.

With explicit locking, it's possible to get more control over Ehcache ' s locking behavior Apply an atomic change with guaranteed ordering across one or more keys in one or more caches. It can therefore is used as a custom alternative to XA transactions or Local transactions.

With that power comes a caution. It is possible to the create deadlocks in your own business logic using the This API.

Code Sample for Explicit Locking

The following is a simple example this shows how to use explicit locking.

String key = "123"; Foo Val=NewFoo (); Cache.acquirewritelockonkey (key);Try{cache.put (NewElement (Key, Val)); } finally{Cache.releasewritelockonkey (key);} ... sometime later String key= "123"; Cache.acquirewritelockonkey (key);Try{Object Cachedval=Cache.get (key). GetValue (); Cachedval.setsomething ("ABC"); Cache.put (NewElement (Key, Cachedval)); } finally{Cache.releasewritelockonkey (key);}

How Locking Works

A read lock does not prevent other READers from also acquiring a read lock and reading. A READ Lock cannot be obtained if there are an outstanding WRITE lock. It'll queue.

A WRITE Lock cannot is obtained while there is outstanding READ locks. It'll queue.

In each case the lock should is released after use to avoid locking problems. The lock release should is in a "finally" block.

If before each read to acquire a read lock and then before each write acquire a write lock, then an isolation level a Kin to read_committed is achieved.

The Locking API

The following methods is available on Cache and Ehcache.

/*** Acquires the proper read lock for a given cache key * *@paramkey-the Key, that retrieves a value, the want to protect via locking.*/  Public voidAcquirereadlockonkey (Object key) { This. Acquirelockonkey (Key, Locktype.read); }
/*** Acquires the proper write lock for a given cache key * *@paramkey-the Key, that retrieves a value, the want to protect via locking.*/  Public voidAcquirewritelockonkey (Object key) { This. Acquirelockonkey (key, locktype.write);}
/*** Try to get a read lock on a given key. If can ' t get it in timeout Millis * Then return a Boolean telling that it didn ' t get the lock * *@paramkey-the Key, that retrieves a value, the want to protect via locking. *@paramTimeout-millis until giveup on getting the lock *@returnwhether the lock was awarded *@throwsinterruptedexception*/  Public BooleanTryreadlockonkey (Object Key,LongTimeoutthrowsinterruptedexception {Sync s=Getlockforkey (key); returnS.trylock (Locktype.read, timeout);}
/*** Try to get a write lock on a given key. If can ' t get it in timeout Millis * Then return a Boolean telling that it didn ' t get the lock * *@paramkey-the Key, that retrieves a value, the want to protect via locking. *@paramTimeout-millis until giveup on getting the lock *@returnwhether the lock was awarded *@throwsinterruptedexception*/  Public BooleanTrywritelockonkey (Object Key,LongTimeoutthrowsinterruptedexception {Sync s=Getlockforkey (key); returnS.trylock (Locktype.write, timeout); }
/*** Release A held read lock for the passed in key * *@paramkey-the Key, that retrieves a value, the want to protect via locking.*/  Public voidReleasereadlockonkey (Object key) {Releaselockonkey (key, Locktype.read);}
/*** Release A held write lock for the passed in key * *@paramkey-the Key, that retrieves a value, the want to protect via * locking.*/  Public voidReleasewritelockonkey (Object key) {Releaselockonkey (key, locktype.write);}
/*** Returns True if a read lock for the key was held by the current thread * *@paramKey *@returntrue if a read lock for the key was held by the current thread*/ BooleanIsreadlockedbycurrentthread (Object key);
/*** Returns True if a write lock for the key was held by the current thread * *@paramKey *@returntrue if a write lock for the key was held by the current thread*/ BooleanIswritelockedbycurrentthread (Object key);

Supported topologies

Except As noted in the Locking API, the Locking API supports the standalone and distributed cache topologies. It does the replicated topology.

Ehcache (2.9.x)-API Developer Guide, Using Explicit Locking