com.aspc.locks

Class DBLogicalLock

java.lang.Object

com.aspc.DBObj.DBObject

com.aspc.locks.DBLogicalLock

All Implemented Interfaces:

SecondaryCacheGroup

public class DBLogicalLock
extends DBObject

Provides a mechanism of for allowing a record or set of records to be "locked" when a user begins to work on them.

Notes

Design

1. Screen Painter

1. A standard data entry screen will have an option to take out a logical lock when a user selects a record for editing.
2. A logical lock maybe of type "soft" or "hard". Soft locks result in a warning, Hard locks result in an error.

2. Session processing

1. When a user logs out of a session ( generally by logging in again) All locks held by that session are deleted.
   

3. Data Entry Screen

1. When a screen is opened/refreshed for a record and the screen has been marked as using logical locks (1.1), the screen will try to obtain the logical lock (4.1)
2. If the user already owns the logical lock then the transaction number for the logical lock will be check against the transaction number of the base record to make sure that no modifications have been made since the lock was taken out.
   
3. If the user doesn't own the logical lock and it is of type "soft" then the user is asked if they want to continue. If they continue a new lock will be taken out by this user and remove the previous lock
   
4. The lock's timeout value is updated each time the screen is refreshed.
   
5. When saving via the "Apply" button, we will update the lockedTransactionNr of the logical lock to reflect the current transaction number.
6. When saving via the "OK" or "Delete" buttons we will remove the logical lock record.
7. When the "Close" button is pressed we will call the server to remove the logical lock.
   
8. We need to prevent screen from being closed in other ways the best way that we can but this will always be an issue as the browser may crash or machine be turned off etc
   

4. Logical Lock

1. A user may obtain a logical lock if there is no logical locks for the required key or the lock is no longer valid.
2. A lock is no longer valid if the lock's timeout period has expired or the associated user's session has expired.
3. A soft lock maybe overridden by another user
   

Questions

1. What to do if a record has been modified after a logical lock has been taken out ? Should we just show the changes and ask if they wish to continue ? If so we would just update the lockedTransactionNr so that the warning doesn't come up again.
   

Schema

+--------------------------------+

  |      SDBDataEntryScreen        |

  +--------------------------------+

  |  lockType -> DBLogicalLockType |

  |  lockReasonId -> DBMessage     |

  +--------------------------------+

data model
THREAD MODE: MIXED, SINGLE-THREADED when called from MutableDataSource else MULTI-THREADED

Since:

4 December 2003

Author:

Nigel Leck

Nested Class Summary

Nested classes/interfaces inherited from class com.aspc.DBObj.DBObject

DBObject.DenormalizeAction

Field Summary

Fields

Modifier and Type	Field and Description
static GlobalId	DBCLASS_GID Provides a mechanism of for allowing a record or set of records to be "locked" when a user begins to work on them.
static java.lang.String	DBCLASS_NAME Provides a mechanism of for allowing a record or set of records to be "locked" when a user begins to work on them.
static java.lang.String	PARAM_IGNORE_TIMEOUT Should the isValid field/method ignore the timeout

Fields inherited from class com.aspc.DBObj.DBObject

ATTRIBUTE_MARVIN, dbClass, ds, NO_LOOP_PARAMS

Constructor Summary

Constructors

Constructor and Description
DBLogicalLock(DBClass def, DataSource dataSource) Std.

Method Summary

Modifier and Type	Method and Description
boolean	canReleaseLock(Login login) Determines if the current user has the rights to release this lock
static DBLogicalLock	create(MutableDataSource mds) Make a new instance of this class.
void	eventFieldUpdated(DBField field, java.lang.Object previous, GlobalKey previousKey, FldParams params) Additional business logic when a field is updated.
protected void	extFixUp() The extended fix up routine for known problems.
protected java.lang.Object	extGetDerivedValue(DBField field, FldParams params) Calculate the derived value for this field.
protected void	extPreValidate() clear the locks
static DBLogicalLock	findKey(DataSource ds, int key) Find the target for this class by the primary key
DBLogicalLockGroup	findLockGroup(java.lang.String... args) Group that this lock is part of.
Person	findPerson(java.lang.String... args) The person that has the lock.
DBMessage	findReasonId(java.lang.String... args) The reason that the lock was taken.
Session	findSession(java.lang.String... args) The session for which this lock was taken/valid for.
Person	findStolenBy(java.lang.String... args) The lock was stolen by this person.
DBLogicalLockType	findType(java.lang.String... args) A "stealable" lock will allow other users to steal the lock from another user, a "non_stealable" lock will produce an error if another user tries to lock the same record.
static DBLogicalLock	getCurrentLock(java.lang.String key, DataSource ds) Retrieves the current lock for the supplied key
int	getDepth(java.lang.String... args)
java.lang.String	getDisplayKey(java.lang.String... args)
int	getID(java.lang.String... args)
java.lang.String	getIdleDuration(java.lang.String... args)
java.lang.String	getLockedKey(java.lang.String... args)
long	getLockedTransactionNr(java.lang.String... args)
DBLogicalLockGroup	getLockGroup(java.lang.String... args)
java.util.Date	getOriginalTimeTaken(java.lang.String... args)
Person	getPerson(java.lang.String... args)
DBMessage	getReasonId(java.lang.String... args)
java.lang.String	getReleasedKey(java.lang.String... args)
Session	getSession(java.lang.String... args)
Person	getStolenBy(java.lang.String... args)
java.util.Date	getTimeout(java.lang.String... args)
java.util.Date	getTimeTaken(java.lang.String... args)
DBLogicalLockType	getType(java.lang.String... args)
boolean	hasTimedOut() has the lock timed out ?
static boolean	isLockedByAnother(java.lang.String key, Login login) Determines if there is already a lock but someone else has it
boolean	isReleased(java.lang.String... args)
protected boolean	isValid(FldParams params) is valid
static DBQuery<DBLogicalLock>	makeQuery(DataSource ds) Make a new QUERY for this class.
static DBLogicalLock[]	obtain(java.lang.String[] key, Session session, GlobalKey currentLockKey, MutableDataSource mds) Creates a lock for a specified key If a valid lock already exists then a DBLogicalLockException is thrown.
static DBLogicalLock	obtain(java.lang.String key, Login login, GlobalKey currentLockKey, java.lang.String duration, Session session, java.lang.String lockType, MutableDataSource ds, DBLogicalLockGroup grp) Creates a lock for a specified key If a valid lock already exists then a DBLogicalLockException is thrown.
static DBLogicalLock	obtain(java.lang.String key, Login login, GlobalKey currentLockKey, java.lang.String duration, Session session, java.lang.String lockType, MutableDataSource ds, DBLogicalLockGroup grp, int depth) Creates a lock for a specified key If a valid lock already exists then a DBLogicalLockException is thrown.
static DBLogicalLock	obtain(java.lang.String key, Session session, GlobalKey currentLockKey, MutableDataSource mds, DBLogicalLockGroup grp) Obtains a lock for a session so that it is only valid for this session The lock will default to being valid the default timeout duration
static void	release(java.lang.String key, Login login, MutableDataSource ds) Releases an existing lock.
DBLogicalLock	setDepth(int value, java.lang.String... args)
DBLogicalLock	setID(int value, java.lang.String... args)
DBLogicalLock	setLockedKey(java.lang.String value, java.lang.String... args)
DBLogicalLock	setLockedTransactionNr(long value, java.lang.String... args)
DBLogicalLock	setLockGroup(com.aspc.dal.locks.DBLogicalLockGroup value, java.lang.String... args)
DBLogicalLock	setOriginalTimeTaken(java.util.Date value, java.lang.String... args)
DBLogicalLock	setPerson(com.aspc.dal.dbobj.contact.Person value, java.lang.String... args)
DBLogicalLock	setReasonId(com.aspc.dal.message.DBMessage value, java.lang.String... args)
DBLogicalLock	setReleased(boolean value, java.lang.String... args)
DBLogicalLock	setReleasedKey(java.lang.String value, java.lang.String... args)
DBLogicalLock	setSession(com.aspc.dal.dbobj.contact.Session value, java.lang.String... args)
DBLogicalLock	setStolenBy(com.aspc.dal.dbobj.contact.Person value, java.lang.String... args)
DBLogicalLock	setTimeout(java.util.Date value, java.lang.String... args)
DBLogicalLock	setTimeTaken(java.util.Date value, java.lang.String... args)
DBLogicalLock	setType(com.aspc.dal.locks.DBLogicalLockType value, java.lang.String... args)
static DBLogicalLock	takeLock(java.lang.String key, Login login, GlobalKey currentLockKey, java.lang.String duration, Session session, java.lang.String lockType, DBLogicalLockGroup grp) Creates a lock for a specified key If a valid lock already exists then a DBLogicalLockException is thrown.
static DBLogicalLock	takeLock(java.lang.String key, Login login, GlobalKey currentLockKey, java.lang.String duration, Session session, java.lang.String lockType, DBLogicalLockGroup grp, int depth) Creates a lock for a specified key If a valid lock already exists then a DBLogicalLockException is thrown.
static DBLogicalLock[]	takeLocks(java.lang.String[] key, Session session, GlobalKey currentLockKey) Creates a lock for a specified key If a valid lock already exists then a DBLogicalLockException is thrown.
static void	update(java.lang.String key, Session session, GlobalKey currentLockKey, long transId, MutableDataSource ds) Update the details of a lock.

Methods inherited from class com.aspc.DBObj.DBObject

addReloadEventListener, archiveCheck, autoEnterCreate, calculateValue, calculateValue, calculateValue, callingRestoreByJournal, changeThreadMode, checkCreateAccess, checkDelete, checkDeleteAccess, checkModifyAccess, checkModifyAccess, checkReadAccess, clearCache, copy, copyFields, copyIncludeField, copyInwardLinks, delete, denormalizedResult, displayLogName, displayName, displayValue, doSearch, dump, equals, eventDataLoaded, extAutoEnterCreate, extCanDeleteDependantObject, extCheckCreateAccess, extCheckDeleteAccess, extCheckModifyAccess, extCheckModifyAccess, extCheckReadAccess, extCopy, extDelete, extDeleteRecord, extGetDerivedGlobalKey, extGetValue, extIsMandatory, extIsOnChange, extMarkSavePoint, extPostDeleteRecord, extPostSaveRecord, extPreDeleteRecord, extPreSaveRecord, extPreValidateDelete, extRaiseEvents, extRollbackTo, extSaveRecord, extSetValue, extUndelete, extValidateDelete, extValidateField, extValidateRecord, fetchLinkHolder, findGlobalKey, findGlobalKey, findGlobalKey, findGlobalKey, findLinkedObject, findLinkedObject, findLinkedObject, findRawData, fireEventDataLoaded, fixUp, forceLockedTransaction, getBoolean, getBoolean, getBoolean, getBoolean, getBoolean, getBoolean, getChangedFieldInfo, getChangedFields, getDate, getDate, getDate, getDate, getDate, getDefaultValue, getDisableOnChangeEvent, getDouble, getDouble, getDouble, getDouble, getDouble, getFieldDouble, getFieldInt, getFieldLong, getFieldString, getFormattedString, getFormattedString, getGlobalKey, getGlobalKey, getGlobalKey, getGlobalKey, getGlobalKey, getInt, getInt, getInt, getInt, getInt, getInt, getInwardLinkage, getKeyString, getKeyValue, getLinkedObject, getLinkedObject, getLinkedObject, getLinkedObjectByKey, getLinkedRowId, getLinkedRowId, getLinkedRowIdByData, getLinkHolder, getLockedTransaction, getLong, getLong, getLong, getLong, getLong, getLong, getMutableArrayValue, getMutableArrayValue, getOriginalKey, getOriginalValue, getOriginalValue, getProcessedValue, getPureValue, getRawData, getRawValue, getRawValue, getRowId, getRowKey, getSecondaryCacheGroupKey, getSrcLayerID, getString, getString, getString, getString, getString, getString, getValue, getValue, getValue, getValue, hasAutoChanged, hasAutoChanged, hasChanged, hasChangedByUser, hasChangedByUserField, hasChangedByUserField, hasFieldChanged, hasFieldChanged, hashCode, hasStoredResult, iCheckDeleteAccess, iCheckModifyAccess, iCheckReadAccess, iGetDenormalizedMap, iGetRawValue, iPlaceDenormalizedResult, iPostSaveOrDeleteRecord, iPreSaveOrDeleteRecord, iPreValidate, iRaiseEvents, iSaveOrDeleteRecord, isBrokenLink, isBrokenLink, isChanged, isDataCacheKnownToBeDirty, isDeleted, isEmpty, iSetValue, isForceReindex, isKeyWordField, isMandatory, isNew, isNull, isNull, isOnChange, isReindex, iValidateRecord, lastTouched, makeArchiveDataLoader, makeClone, makeDataLoader, makeDenormalizedDoc, makeLinkedArray, makeModifyAccessException, makeSearchPlan, makeWriteProvider, manualDenormalizeOnSave, markSavePoint, optLockedTransaction, registerWatchedObject, reindex, releaseDenormalized, removeReloadEventListener, restoreByJournal, rollbackTo, setBoolean, setBoolean, setBoolean, setBoolean, setDisableOnChangeEvent, setDouble, setDouble, setInt, setInt, setLong, setLong, setRawData, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, toString, touch, undelete, validateField, validateRecord, validateSubType

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

DBCLASS_NAME

public static final java.lang.String DBCLASS_NAME

Provides a mechanism of for allowing a record or set of records to be "locked" when a user begins to work on them.

See Also:

Constant Field Values

DBCLASS_GID

public static final GlobalId DBCLASS_GID

Provides a mechanism of for allowing a record or set of records to be "locked" when a user begins to work on them.

PARAM_IGNORE_TIMEOUT

public static final java.lang.String PARAM_IGNORE_TIMEOUT

Should the isValid field/method ignore the timeout

See Also:

Constant Field Values

Constructor Detail

DBLogicalLock

public DBLogicalLock(DBClass def,
                     DataSource dataSource)
              throws java.lang.Exception

Std. DBObject constructor

Parameters:

def - The class of this object

dataSource - The datasource for this object

Throws:

java.lang.Exception - A serious problem occurred

Method Detail

getID

@CheckReturnValue
public int getID(java.lang.String... args)

setID

@Nonnull
public DBLogicalLock setID(int value,
                                    java.lang.String... args)
                             throws java.lang.Exception

Throws:

java.lang.Exception

getDepth

@CheckReturnValue
public int getDepth(java.lang.String... args)

setDepth

@Nonnull
public DBLogicalLock setDepth(int value,
                                       java.lang.String... args)
                                throws java.lang.Exception

Throws:

java.lang.Exception

getDisplayKey

@CheckReturnValue
 @Nonnull
public java.lang.String getDisplayKey(java.lang.String... args)

getIdleDuration

@CheckReturnValue
 @Nonnull
public java.lang.String getIdleDuration(java.lang.String... args)

getLockGroup

@CheckReturnValue
 @Nullable
public DBLogicalLockGroup getLockGroup(java.lang.String... args)

findLockGroup

@CheckReturnValue
 @Nonnull
public final DBLogicalLockGroup findLockGroup(java.lang.String... args)
                                                                   throws NotFoundException

Group that this lock is part of. Locks that are part of a group work together to ensure that a series of objects are locked.

--> DBLogicalLockGroup (Integer, Searchable)

Parameters:

args - the optional arguments

Returns:

DBLogicalLockGroup

Throws:

NotFoundException - DBLogicalLockGroup was not found

setLockGroup

@Nonnull
public DBLogicalLock setLockGroup(com.aspc.dal.locks.DBLogicalLockGroup value,
                                           java.lang.String... args)
                                    throws java.lang.Exception

Throws:

java.lang.Exception

getLockedKey

@CheckReturnValue
 @Nonnull
public java.lang.String getLockedKey(java.lang.String... args)

setLockedKey

@Nonnull
public DBLogicalLock setLockedKey(java.lang.String value,
                                           java.lang.String... args)
                                    throws java.lang.Exception

Throws:

java.lang.Exception

getLockedTransactionNr

@CheckReturnValue
public long getLockedTransactionNr(java.lang.String... args)

setLockedTransactionNr

@Nonnull
public DBLogicalLock setLockedTransactionNr(long value,
                                                     java.lang.String... args)
                                              throws java.lang.Exception

Throws:

java.lang.Exception

getOriginalTimeTaken

@CheckReturnValue
 @Nullable
public java.util.Date getOriginalTimeTaken(java.lang.String... args)

setOriginalTimeTaken

@Nonnull
public DBLogicalLock setOriginalTimeTaken(java.util.Date value,
                                                   java.lang.String... args)
                                            throws java.lang.Exception

Throws:

java.lang.Exception

getPerson

@CheckReturnValue
 @Nullable
public Person getPerson(java.lang.String... args)

findPerson

@CheckReturnValue
 @Nonnull
public final Person findPerson(java.lang.String... args)
                                                    throws NotFoundException

The person that has the lock.

--> Person (Integer, Mandatory, Searchable)

Parameters:

args - the optional arguments

Returns:

Person

Throws:

NotFoundException - Person was not found

setPerson

@Nonnull
public DBLogicalLock setPerson(com.aspc.dal.dbobj.contact.Person value,
                                        java.lang.String... args)
                                 throws java.lang.Exception

Throws:

java.lang.Exception

getReasonId

@CheckReturnValue
 @Nullable
public DBMessage getReasonId(java.lang.String... args)

findReasonId

@CheckReturnValue
 @Nonnull
public final DBMessage findReasonId(java.lang.String... args)
                                                         throws NotFoundException

The reason that the lock was taken. This will be shown to other users trying to take the same lock.

--> DBMessage (String, Searchable)

Parameters:

args - the optional arguments

Returns:

Message

Throws:

NotFoundException - DBMessage was not found

setReasonId

@Nonnull
public DBLogicalLock setReasonId(com.aspc.dal.message.DBMessage value,
                                          java.lang.String... args)
                                   throws java.lang.Exception

Throws:

java.lang.Exception

isReleased

@CheckReturnValue
public boolean isReleased(java.lang.String... args)

setReleased

@Nonnull
public DBLogicalLock setReleased(boolean value,
                                          java.lang.String... args)
                                   throws java.lang.Exception

Throws:

java.lang.Exception

getReleasedKey

@CheckReturnValue
 @Nonnull
public java.lang.String getReleasedKey(java.lang.String... args)

setReleasedKey

@Nonnull
public DBLogicalLock setReleasedKey(java.lang.String value,
                                             java.lang.String... args)
                                      throws java.lang.Exception

Throws:

java.lang.Exception

getSession

@CheckReturnValue
 @Nullable
public Session getSession(java.lang.String... args)

findSession

@CheckReturnValue
 @Nonnull
public final Session findSession(java.lang.String... args)
                                                      throws NotFoundException

The session for which this lock was taken/valid for.

NB: A lock is only valid for an active session.

--> Session (Integer, Searchable)

Parameters:

args - the optional arguments

Returns:

Session

Throws:

NotFoundException - Session was not found

setSession

@Nonnull
public DBLogicalLock setSession(com.aspc.dal.dbobj.contact.Session value,
                                         java.lang.String... args)
                                  throws java.lang.Exception

Throws:

java.lang.Exception

getStolenBy

@CheckReturnValue
 @Nullable
public Person getStolenBy(java.lang.String... args)

findStolenBy

@CheckReturnValue
 @Nonnull
public final Person findStolenBy(java.lang.String... args)
                                                      throws NotFoundException

The lock was stolen by this person.

--> Person (Integer, Searchable)

Parameters:

args - the optional arguments

Returns:

Person

Throws:

NotFoundException - Person was not found

setStolenBy

@Nonnull
public DBLogicalLock setStolenBy(com.aspc.dal.dbobj.contact.Person value,
                                          java.lang.String... args)
                                   throws java.lang.Exception

Throws:

java.lang.Exception

getTimeTaken

@CheckReturnValue
 @Nullable
public java.util.Date getTimeTaken(java.lang.String... args)

setTimeTaken

@Nonnull
public DBLogicalLock setTimeTaken(java.util.Date value,
                                           java.lang.String... args)
                                    throws java.lang.Exception

Throws:

java.lang.Exception

getTimeout

@CheckReturnValue
 @Nullable
public java.util.Date getTimeout(java.lang.String... args)

setTimeout

@Nonnull
public DBLogicalLock setTimeout(java.util.Date value,
                                         java.lang.String... args)
                                  throws java.lang.Exception

Throws:

java.lang.Exception

getType

@CheckReturnValue
 @Nullable
public DBLogicalLockType getType(java.lang.String... args)

findType

@CheckReturnValue
 @Nonnull
public final DBLogicalLockType findType(java.lang.String... args)
                                                             throws NotFoundException

A "stealable" lock will allow other users to steal the lock from another user, a "non_stealable" lock will produce an error if another user tries to lock the same record.

--> DBLogicalLockType (String, Mandatory, Searchable)

Parameters:

args - the optional arguments

Returns:

DBLogicalLockType

Throws:

NotFoundException - DBLogicalLockType was not found

setType

@Nonnull
public DBLogicalLock setType(com.aspc.dal.locks.DBLogicalLockType value,
                                      java.lang.String... args)
                               throws java.lang.Exception

Throws:

java.lang.Exception

create

@Nonnull
 @CheckReturnValue
public static DBLogicalLock create(@Nonnull
                                                               MutableDataSource mds)
                                                        throws java.lang.Exception

Make a new instance of this class.

Parameters:

mds - the datasource

Returns:

the new record

Throws:

java.lang.Exception - an object of this class could not be created

makeQuery

@Nonnull
 @CheckReturnValue
public static DBQuery<DBLogicalLock> makeQuery(@Nonnull
                                                                           DataSource ds)
                                                                    throws NotFoundException

Make a new QUERY for this class.

Parameters:

ds - the datasource

Returns:

the new QUERY

Throws:

NotFoundException - if class could not be found

findKey

@Nonnull
 @CheckReturnValue
public static DBLogicalLock findKey(@Nonnull
                                                                DataSource ds,
                                                                int key)
                                                         throws NotFoundException,
                                                                java.lang.Exception

Find the target for this class by the primary key

Parameters:

ds - the datasource

key - the value

Returns:

the target

Throws:

NotFoundException - if target could not be found

java.lang.Exception - a serious problem

eventFieldUpdated

@OverridingMethodsMustInvokeSuper
public void eventFieldUpdated(@Nonnull
                                                                DBField field,
                                                                @Nullable
                                                                java.lang.Object previous,
                                                                @Nullable
                                                                GlobalKey previousKey,
                                                                @Nullable
                                                                FldParams params)
                                                         throws java.lang.Exception

Additional business logic when a field is updated.

Overrides:

eventFieldUpdated in class DBObject

Parameters:

field - The field updated.

previous - The previous value for this field.

previousKey - The previous key

params - The parameters used

Throws:

java.lang.Exception - A serious problem

See Also:

DBObject.eventFieldUpdated( DBField, Object, GlobalKey, FldParams)

getCurrentLock

public static DBLogicalLock getCurrentLock(java.lang.String key,
                                           DataSource ds)
                                    throws java.lang.Exception

Retrieves the current lock for the supplied key

Parameters:

key - - key of the object that lock is on

ds - - Datasource used to search for lock on

Returns:

- The lock if found otherwise NULL

Throws:

java.lang.Exception - - a serious error

isLockedByAnother

public static boolean isLockedByAnother(java.lang.String key,
                                        @Nonnull
                                        Login login)

Determines if there is already a lock but someone else has it

Parameters:

key - - key of the object that lock is on

login - - login of user

Returns:

- true if the lock exists and is locked by another user

obtain

public static DBLogicalLock obtain(java.lang.String key,
                                   Session session,
                                   GlobalKey currentLockKey,
                                   MutableDataSource mds,
                                   DBLogicalLockGroup grp)
                            throws DBLogicalLockException

Obtains a lock for a session so that it is only valid for this session The lock will default to being valid the default timeout duration

Parameters:

mds - the data source

grp - the group

key - - key of the object that lock is on

session - - session to apply lock to

currentLockKey - - Existing key. This indicates that the user thinks that they already have the lock

Returns:

- the new lock

Throws:

DBLogicalLockException - - the lock could not be obtained

takeLock

public static DBLogicalLock takeLock(java.lang.String key,
                                     Login login,
                                     GlobalKey currentLockKey,
                                     java.lang.String duration,
                                     Session session,
                                     java.lang.String lockType,
                                     DBLogicalLockGroup grp)
                              throws java.lang.Exception

Creates a lock for a specified key If a valid lock already exists then a DBLogicalLockException is thrown.

Parameters:

grp - the group

session - - session that user is logged into

key - - key of the object that lock is on

login - - login of user

currentLockKey - - Existing key. This indicates that the user thinks that they already have the lock

duration - - duration that the lock is valid for

lockType - - type of lock, i.e stealable or non-stealable

Returns:

- the new lock

Throws:

java.lang.Exception - a serious problem

takeLock

public static DBLogicalLock takeLock(java.lang.String key,
                                     Login login,
                                     GlobalKey currentLockKey,
                                     java.lang.String duration,
                                     Session session,
                                     java.lang.String lockType,
                                     DBLogicalLockGroup grp,
                                     int depth)
                              throws java.lang.Exception

Creates a lock for a specified key If a valid lock already exists then a DBLogicalLockException is thrown.

Parameters:

grp - the group

session - - session that user is logged into

key - - key of the object that lock is on

login - - login of user

currentLockKey - - Existing key. This indicates that the user thinks that they already have the lock

duration - - duration that the lock is valid for

lockType - - type of lock, i.e stealable or non-stealable

depth - - depth of lock

Returns:

- the new lock

Throws:

java.lang.Exception - a serious problem

obtain

public static DBLogicalLock obtain(java.lang.String key,
                                   Login login,
                                   GlobalKey currentLockKey,
                                   java.lang.String duration,
                                   Session session,
                                   java.lang.String lockType,
                                   MutableDataSource ds,
                                   DBLogicalLockGroup grp)
                            throws DBLogicalLockException

Creates a lock for a specified key If a valid lock already exists then a DBLogicalLockException is thrown.

Parameters:

ds - the data source

grp - the group

session - - session that user is logged into

key - - key of the object that lock is on

login - - login of user

currentLockKey - - Existing key. This indicates that the user thinks that they already have the lock

duration - - duration that the lock is valid for

lockType - - type of lock, i.e stealable or non-stealable

Returns:

- the new lock

Throws:

DBLogicalLockException - - the lock could not be obtained

obtain

public static DBLogicalLock obtain(java.lang.String key,
                                   Login login,
                                   GlobalKey currentLockKey,
                                   java.lang.String duration,
                                   Session session,
                                   java.lang.String lockType,
                                   MutableDataSource ds,
                                   DBLogicalLockGroup grp,
                                   int depth)
                            throws DBLogicalLockException

Creates a lock for a specified key If a valid lock already exists then a DBLogicalLockException is thrown.

Parameters:

ds - the data source

grp - the group

session - - session that user is logged into

key - - key of the object that lock is on

login - - login of user

currentLockKey - - Existing key. This indicates that the user thinks that they already have the lock

duration - - duration that the lock is valid for

lockType - - type of lock, i.e stealable or non-stealable

depth - - depth of lock

Returns:

- the new lock

Throws:

DBLogicalLockException - - the lock could not be obtained

takeLocks

public static DBLogicalLock[] takeLocks(java.lang.String[] key,
                                        Session session,
                                        GlobalKey currentLockKey)
                                 throws java.lang.Exception

Creates a lock for a specified key If a valid lock already exists then a DBLogicalLockException is thrown.

Parameters:

key - - a set of keys of the object that locks are on

session - - session that user is logged into

currentLockKey - - Existing key. This indicates that the user thinks that they already have the lock

Returns:

- the new lock

Throws:

java.lang.Exception - a serious problem

obtain

public static DBLogicalLock[] obtain(java.lang.String[] key,
                                     Session session,
                                     GlobalKey currentLockKey,
                                     MutableDataSource mds)
                              throws DBLogicalLockException

Creates a lock for a specified key If a valid lock already exists then a DBLogicalLockException is thrown.

Parameters:

key - - a set of keys of the object that locks are on

session - - session that user is logged into

currentLockKey - - Existing key. This indicates that the user thinks that they already have the lock

mds - - mutable datasource

Returns:

- the new lock

Throws:

DBLogicalLockException - - the lock could not be obtained

release

public static void release(java.lang.String key,
                           Login login,
                           MutableDataSource ds)
                    throws java.lang.Exception

Releases an existing lock. If a valid lock does not exist then a DBLogicalLockException is thrown.

Parameters:

ds - the datasource

key - - key of the object that lock is on

login - - login of user

Throws:

java.lang.Exception - - a serious error

canReleaseLock

public boolean canReleaseLock(Login login)

Determines if the current user has the rights to release this lock

Parameters:

login - Current login of user

Returns:

true if this user can release the lock

update

public static void update(java.lang.String key,
                          Session session,
                          GlobalKey currentLockKey,
                          long transId,
                          MutableDataSource ds)
                   throws DBLogicalLockException

Update the details of a lock. This is basically a release and and then re-obtain

Parameters:

ds - the datasource

session - - session that user it currently logged into

key - - key of the object that lock is on

currentLockKey - - Existing key. This indicates that the user thinks that they already have the lock

transId - - current transaction id on last changes for base object

Throws:

DBLogicalLockException - - a serious error

extGetDerivedValue

@CheckReturnValue
protected java.lang.Object extGetDerivedValue(@Nonnull
                                                                DBField field,
                                                                @Nullable
                                                                FldParams params)
                                                         throws java.lang.Exception

Calculate the derived value for this field.

Overrides:

extGetDerivedValue in class DBObject

Parameters:

field - The field to get

params - The parameters for this field eg. language= or default=

Returns:

The calculated value

Throws:

java.lang.Exception - A serious problem

isValid

protected boolean isValid(FldParams params)
                   throws java.lang.Exception

is valid

Parameters:

params - the field parameters

Returns:

true if valid

Throws:

java.lang.Exception - A serious problem

hasTimedOut

public boolean hasTimedOut()

has the lock timed out ?

Returns:

true if timed out

extFixUp

@OverridingMethodsMustInvokeSuper
protected void extFixUp()
                                                   throws java.lang.Exception

The extended fix up routine for known problems. This routine will be called by the method fixUp() in DBObject.

Overrides:

extFixUp in class DBObject

Throws:

java.lang.Exception - A serious problem

extPreValidate

@OverridingMethodsMustInvokeSuper
protected void extPreValidate()
                                                         throws java.lang.Exception

clear the locks

Overrides:

extPreValidate in class DBObject

Throws:

java.lang.Exception - a serious problem.