public interface LockManager
Modifier and Type | Method and Description |
---|---|
LockAdministrator |
getLockAdministrator()
Retrieve the
LockAdministrator object associated with this
LockManager instance. |
void |
lock(LockType lockType,
RecordIdentifier ident,
boolean update)
Lock or release a single database record in the current context.
|
void |
lock(LockType lockType,
RecordIdentifier ident,
boolean update,
long timeout)
Lock or release a single database record in the current context.
|
LockType |
lockTable(LockType lockType,
java.lang.String table,
boolean update)
Attempt to obtain the specified lock type on a table.
|
LockType |
queryLock(RecordIdentifier ident)
Query the lock type currently held by the current context for the
specified database record.
|
void |
setDatabase(Database database)
Set the name of the physical database with which this lock manager is associated.
|
void |
setLockListener(LockListener listener)
Register a lock listener, which will receive notifications of changes in lock status for any
record managed by this object.
|
void setDatabase(Database database)
database
- Database information object.void setLockListener(LockListener listener)
listener
- Listener to be registered or null
to deregister the current listener.LockAdministrator getLockAdministrator()
LockAdministrator
object associated with this
LockManager
instance.
To ensure a caller has suffient rights to access administrative lock functions, the implementation of this method should confirm with the administrative server before returning any lock information.
LockAdministrator
instance.void lock(LockType lockType, RecordIdentifier ident, boolean update) throws LockUnavailableException
LockType.NONE
is used to release
a record; any other lock type is used to lock a record. Specifying LockType.NONE
for a record not locked in the current context is logically a no-op, though some overhead
is required for the check, and the caller may block waiting on the lock table monitor.
Before obtaining any record lock, lockTable(LockType.SHARE, table, true)
is
invoked to acquire a share lock on the table. After releasing any record lock, lockTable(LockType.NONE, table, true)
is invoked to release that lock.
Any normal return from this method indicates the requested lock was acquired (or released) successfully. Any error will result in an exceptional return. In the event a record cannot be locked due to a conflicting lock held by another context, the current thread will block until the lock is acquired, unless the requested lock is a "no-wait" variant, in which case an exception is thrown.
This method also operates in a check-only mode (if update
is set to false
)
where it goes through the motions of obtaining the specified lock type, but does not
actually change the lock status. This is at best an unreliable check, since another
context can change the lock status as soon as the lock status monitor is released, rendering
the check stale. Nevertheless, it exists to mimic the effect of the lock type option to the
Progress can-find function.
lockType
- Type of lock to be obtained. LockType.NONE
is
used to release an existing lock, and to continue with no
lock.ident
- ID which uniquely identifies the record being locked.update
- true
if the lock state for the current record
should be updated; else false
.LockUnavailableException
- if a "no-wait" lock cannot be acquired immediately.void lock(LockType lockType, RecordIdentifier ident, boolean update, long timeout) throws LockUnavailableException, LockTimeoutException
LockType.NONE
is used to release
a record; any other lock type is used to lock a record. Specifying LockType.NONE
for a record not locked in the current context is logically a no-op, though some overhead
is required for the check, and the caller may block waiting on the lock table monitor.
Before obtaining any record lock, lockTable(LockType.SHARE, table, true)
is
invoked to acquire a share lock on the table. After releasing any record lock, lockTable(LockType.NONE, table, true)
is invoked to release that lock.
Any normal return from this method indicates the requested lock was acquired (or released) successfully. Any error or timeout will result in an exceptional return. In the event a record cannot be locked due to a conflicting lock held by another context, the current thread will block until the lock is acquired, unless either (a) the requested lock is a "no-wait" variant; or (b) a positive timeout value was provided and at least that number of milliseconds has elapsed without acquiring the lock. In either case, an exception is thrown as described below.
This method also operates in a check-only mode (if update
is set to false
)
where it goes through the motions of obtaining the specified lock type, but does not
actually change the lock status. This is at best an unreliable check, since another
context can change the lock status as soon as the lock status monitor is released, rendering
the check stale. Nevertheless, it exists to mimic the effect of the lock type option to the
Progress can-find function.
lockType
- Type of lock to be obtained. LockType.NONE
is
used to release an existing lock, and to continue with no
lock.ident
- ID which uniquely identifies the record being locked.update
- true
if the lock state for the current record
should be updated; else false
.timeout
- Positive number of milliseconds to wait before throwing LockTimeoutException
, or 0L to wait indefinitely. Ignored if a no-wait lock
variant is requested.LockUnavailableException
- if a "no-wait" lock cannot be acquired immediately.LockTimeoutException
- if a non-zero timeout was provided and the requested lock has not been acquired
by the time that period has elapsed.LockType queryLock(RecordIdentifier ident)
This method should always return the non-NO_WAIT
variants of a lock type. That is, even if the actual lock type is
LockType.EXCLUSIVE_NO_WAIT
or
LockType.SHARE_NO_WAIT
, the simpler types of
LockType.EXCLUSIVE
and LockType.SHARE
,
respectively, should be returned. The lack of a lock is required to
return LockType.NONE
rather than null
.
ident
- ID which uniquely identifies the record being queried.null
.LockType lockTable(LockType lockType, java.lang.String table, boolean update) throws LockUnavailableException
A lock currently held can be released by specifying
LockType.NONE
for the lockType
parameter.
Method returns previous lock type (so that calling code knows what to set it back to after bulk delete). The normal return of this method indicates that the lock request (or lack thereof) completed successfully, and that the current context now holds a lock of the requested type.
lockType
- Type of lock to be obtained. LockType.NONE
is used to release an
existing lock, and to continue with no lock.table
- Table name.update
- true
if the lock state for the current table should be updated;
else false
.LockUnavailableException
- if a "no-wait" lock cannot be acquired immediately.