public static interface Session.SessionLock
Session locks are identified by a lock name. Lock names are arbitrary and chosen at will to suit the application. Each lock is owned by at most one session. Locks are established on demand; there is no separate operation to create or destroy a lock.
A session lock is acquired using the Session.lock(String)
method.
If no other session owns the lock, the server will assign the lock to the
calling session immediately. Otherwise, the server will record that the
session is waiting to acquire the lock. A session can call lock
more than once for a given session lock – if the lock is acquired,
all calls will complete successfully with equal SessionLocks.
If a session closes, the session locks it owns are automatically
released. A session can also release a lock
.
When a session lock is released and other sessions are waiting to acquire
the lock, the server will arbitrarily select one of the waiting sessions
and notify it that it has acquired the lock. All of the newly selected
session's pending lock
calls will complete normally. Other
sessions will continue to wait.
The Session.lock(String, SessionLockScope)
variant of this method takes
a scope parameter that provides the further option of automatically
releasing the lock when the session loses its connection to the server.
The acquisition life cycle of a session lock from the perspective of a session is shown in the following diagram.
Unlike the Lock
API, there is no
association between a lock and a thread. If a session calls this method
for a lock it already owns, the call will complete normally and
immediately with a SessionLock
that is equal to the one returned
when the lock was originally acquired. A single call to
unlock()
will release this session's claim to a lock.
A further difference to java.util.concurrent.locks.Lock
is that
lock ownership can be lost due to an independent event such as loss of
connection, and not only due to the use of the locking API by the owner.
Consequently, the session should poll using isOwned()
to check that it still owns the lock before accessing the protected
resource.
This session lock API has inherent race conditions. Even if an application is coded correctly to protect a shared resource using session locks, there may be a period where two or more sessions concurrently access the resource. The races arise for several reasons including
isOwned()
, the lock can be lost after the check has succeeded but
before the resource is accessed;
Despite this imprecision, session locks provide a useful way to coordinate session actions.
Modifier and Type | Method and Description |
---|---|
String |
getName() |
Session.SessionLockScope |
getScope()
The scope of the lock.
|
long |
getSequence()
A value that identifies the acquisition of the lock with the given
name . |
boolean |
isOwned()
Test whether the session lock is still owned.
|
CompletableFuture<Boolean> |
unlock()
Release a session lock, if owned.
|
String getName()
long getSequence()
name
. SessionLocks that are acquired later are
guaranteed to have bigger sequence values, allowing the sequence
number to be used as a fencing token.boolean isOwned()
Session.SessionLockScope getScope()
The scope determines when the lock will be released automatically.
If a session makes multiple
requests for a lock
using different scopes, and the server assigns the lock to the
session fulfilling the requests, the lock will be given the weakest
scope (UNLOCK_ON_CONNECTION_LOSS). Consequently, an individual
request can complete with a lock that has a different scope to that
requested.
Session.lock(String, SessionLockScope)
CompletableFuture<Boolean> unlock()
On completion, this session will no longer own the named session lock. If CompletableFuture completes normally, a true value indicates this session previously owned the lock and a false value indicates it did not.
If the CompletableFuture completes exceptionally, this
session does not own the session lock. Common reasons for
failure, indicated by the exception reported as the
cause
, include:
SessionClosedException
– if the session is
closed.
Session.lock(String)
Copyright © 2024 DiffusionData Ltd. All Rights Reserved.