org.kuali.kfs.module.bc.document.service
Interface LockService

All Known Implementing Classes:

LockServiceImpl

public interface LockService

This interface defines the methods that a LockService must provide. LockServiceImpl consists of methods that manage the various locks used in the Budget module. Locks are needed to serialize user updates since a BC Edoc is potentially editable by many users simultaneously and the default Optimistic locking scheme used by KFS would produce an inconsistent set of data. Accountlock controls exclusive access to the BC Edoc Positionlock controls exclusive access to a BC Position Fundinglock controls shared funding access. An associated Positionlock must exist before attempting to get a Fundinglock. Accountlock and Fundinglock are mutex. Transactionlock controls exclusive access to serialize updates to the accounting lines in the BC Edoc. A Fundinglock must exist before creating a Transactionlock. The Transactionlock lifecycle is short, required only for the duration of the accounting line update.

Method Summary

boolean	checkLockExists(BudgetConstructionLockSummary lockSummary) Helper method to check if a lock exists for the given parameters.
BCConstants.LockStatus	doUnlock(BudgetConstructionLockSummary lockSummary) Helper method to check the lock type and do the unlock with the lock summary fields.
List<BudgetConstructionHeader>	getAllAccountLocks(String lockUnivId) Retrieves all current account locks for the given user (or all locks if user is null/empty).
List<PendingBudgetConstructionAppointmentFunding>	getAllPositionFundingLocks(String lockUnivId) Retrieves all current position/funding locks for the given user (or all locks if user is null/empty).
List<BudgetConstructionHeader>	getAllTransactionLocks(String lockUnivId) Retrieves all current transaction locks for the given user (or all locks if user is null/empty).
SortedSet<BudgetConstructionFundingLock>	getFundingLocks(BudgetConstructionHeader bcHeader) This returns the set of BCFundingLocks associated with a BCHeader.
List<BudgetConstructionFundingLock>	getOrphanedFundingLocks(String lockUnivId) Retrieves all funding locks that do not have a corresponding position lock for the given user (or all locks if user is null/empty).
List<BudgetConstructionPosition>	getOrphanedPositionLocks(String lockUnivId) Retrieves all current position locks without a funding lock for the given user (or all locks if user is null/empty).
boolean	isAccountLocked(BudgetConstructionHeader bcHeader) This method checks the database for an accountlock.
boolean	isAccountLocked(PendingBudgetConstructionAppointmentFunding appointmentFunding) This method checks the database for an accountlock according to the given appointment funding.
boolean	isAccountLockedByUser(BudgetConstructionHeader budgetConstructionHeader, org.kuali.rice.kim.bo.Person person) determine whether the account lock on the given budget document is held by the the specified user
boolean	isAccountLockedByUser(String chartOfAccountsCode, String accountNumber, String subAccountNumber, Integer fiscalYear, String principalId) Checks the given user has an account lock for the given document.
boolean	isFundingLockedByUser(String chartOfAccountsCode, String accountNumber, String subAccountNumber, Integer fiscalYear, String principalId) Checks if the given user has a funding lock for the given accounting key.
boolean	isPositionFundingLockedByUser(String positionNumber, String chartOfAccountsCode, String accountNumber, String subAccountNumber, Integer fiscalYear, String principalId) Checks the given user has an position/funding lock for the given position number and accounting key.
boolean	isPositionLocked(String positionNumber, Integer fiscalYear) This checks the database for an existing positionlock
boolean	isPositionLockedByUser(String positionNumber, Integer fiscalYear, String principalId) Checks the given user has an position lock for the given position number.
boolean	isTransactionLocked(String chartOfAccountsCode, String accountNumber, String subAccountNumber, Integer fiscalYear) This checks the database for an existing transactionlock for the BC EDoc (account).
boolean	isTransactionLockedByUser(String chartOfAccountsCode, String accountNumber, String subAccountNumber, Integer fiscalYear, String principalId) Checks the given user has an transaction lock for the given document.
BudgetConstructionLockStatus	lockAccount(BudgetConstructionHeader bcHeader, String principalId) This method attempts to lock the given Account for the passed in uuid.
BudgetConstructionLockStatus	lockAccountAndCommit(BudgetConstructionHeader bcHeader, String principalId) Retrives an account lock (@see org.kuali.kfs.module.bc.document.service.LockService#lockAccount(org.kuali.kfs.module.bc.businessobject.BudgetConstructionHeader, java.lang.String) and commits the lock.
BudgetConstructionLockStatus	lockFunding(BudgetConstructionHeader bcHeader, String principalId) This method sets a funding lock associated to the header.
BudgetConstructionLockStatus	lockFunding(PendingBudgetConstructionAppointmentFunding appointmentFunding, org.kuali.rice.kim.bo.Person person) acquire a lock for the given appointment funding
List<PendingBudgetConstructionAppointmentFunding>	lockPendingBudgetConstructionAppointmentFundingRecords(List<PendingBudgetConstructionAppointmentFunding> fundingRecords, org.kuali.rice.kim.bo.Person user) Retrieves account locks for funding records, for use in the payrate import process.
BudgetConstructionLockStatus	lockPosition(BudgetConstructionPosition position, org.kuali.rice.kim.bo.Person person) acquire a lock for the given budget position
BudgetConstructionLockStatus	lockPosition(String positionNumber, Integer fiscalYear, String principalId) This locks the position, meaning it sets the position lock id field with the puid.
BudgetConstructionLockStatus	lockPositionAndActiveFunding(Integer universityFiscalYear, String positionNumber, String principalId) Locks the position record for the given key if not already locked.
BudgetConstructionLockStatus	lockTransaction(PendingBudgetConstructionAppointmentFunding appointmentFunding, org.kuali.rice.kim.bo.Person person) attemps to have a transaction lock based on the information provided by the given funding line
BudgetConstructionLockStatus	lockTransaction(String chartOfAccountsCode, String accountNumber, String subAccountNumber, Integer fiscalYear, String principalId) This attempts a transactionlock on a BC Edoc for a pUId.
BCConstants.LockStatus	unlockAccount(BudgetConstructionHeader bcHeader) This method attempts to unlock the given BudgetConstructionHeader.
void	unlockFunding(List<PendingBudgetConstructionAppointmentFunding> lockedFundings, org.kuali.rice.kim.bo.Person person) release the locks for the given appointment fundings if any
BCConstants.LockStatus	unlockFunding(PendingBudgetConstructionAppointmentFunding appointmentFunding, org.kuali.rice.kim.bo.Person person) release the lock for the given appointment funding if any
BCConstants.LockStatus	unlockFunding(String chartOfAccountsCode, String accountNumber, String subAccountNumber, Integer fiscalYear, String principalId) This removes the fundinglock for the account and user
BCConstants.LockStatus	unlockPosition(String positionNumber, Integer fiscalYear) This removes an existing positionlock
BCConstants.LockStatus	unlockPosition(String positionNumber, Integer fiscalYear, String principalId) release the locks on a positions with the given information
BCConstants.LockStatus	unlockPositionAndActiveFunding(Integer universityFiscalYear, String positionNumber, String principalId) Unlocks the position and all associated funding lines not marked as delete.
BCConstants.LockStatus	unlockPostion(BudgetConstructionPosition position, org.kuali.rice.kim.bo.Person person) release the lock for the given position if any
void	unlockPostion(List<BudgetConstructionPosition> lockedPositions, org.kuali.rice.kim.bo.Person person) release the locks for the given positions if any
void	unlockTransaction(PendingBudgetConstructionAppointmentFunding appointmentFunding, org.kuali.rice.kim.bo.Person person) attemps to unlock a transaction based on the information provided by the given funding line
BCConstants.LockStatus	unlockTransaction(String chartOfAccountsCode, String accountNumber, String subAccountNumber, Integer fiscalYear) This removes an existing transactionlock for a BC EDoc (account).

Method Detail

lockAccount

BudgetConstructionLockStatus lockAccount(BudgetConstructionHeader bcHeader,
                                         String principalId)

This method attempts to lock the given Account for the passed in uuid. Finding an exising account lock for the uuid returns success without having to relock After setting an accountlock, if any funding locks are found, it releases the accountlock and sets BCLockStatus with LockStatus.FLOCK_FOUND. Accountlocks and Fundinglocks are mutex

Parameters:

bcHeader -

principalId -

Returns:

BudgetConstructionLockStatus with lockStatus.SUCCESS, OPTIMISTIC_EX (lost optimistic lock), FLOCK_FOUND (also sets fundingLocks), BY_OTHER (also sets accountLockOwner), NO_DOOR (null bcHeader)

isAccountLocked

boolean isAccountLocked(BudgetConstructionHeader bcHeader)

This method checks the database for an accountlock. It assumes a valid bcHeader parameter

Parameters:

bcHeader -

Returns:

Returns true if locked, false if not locked or not found in the database

isAccountLocked

boolean isAccountLocked(PendingBudgetConstructionAppointmentFunding appointmentFunding)

This method checks the database for an accountlock according to the given appointment funding. It assumes a valid appointmentFunding parameter

Parameters:

appointmentFunding - the given appointment funding

Returns:

Returns true if locked, false if not locked or not found in the database

isAccountLockedByUser

boolean isAccountLockedByUser(String chartOfAccountsCode,
                              String accountNumber,
                              String subAccountNumber,
                              Integer fiscalYear,
                              String principalId)

Checks the given user has an account lock for the given document.

Parameters:

chartOfAccountsCode - - chart code of account lock

accountNumber - - account number of account lock

subAccountNumber - - sub account number of account lock

fiscalYear - - fiscal year of account lock

principalId - - lock user id

Returns:

true if locked, false if not locked or not found in the database

unlockAccount

BCConstants.LockStatus unlockAccount(BudgetConstructionHeader bcHeader)

This method attempts to unlock the given BudgetConstructionHeader.

Parameters:

bcHeader -

Returns:

LockStatus.SUCCESS, NO_DOOR (not found), OPTIMISTIC_EX (lost optimistic lock)

getFundingLocks

SortedSet<BudgetConstructionFundingLock> getFundingLocks(BudgetConstructionHeader bcHeader)

This returns the set of BCFundingLocks associated with a BCHeader. The set is sorted by the Person name

Parameters:

bcHeader -

Returns:

SortedSet

lockFunding

BudgetConstructionLockStatus lockFunding(BudgetConstructionHeader bcHeader,
                                         String principalId)

This method sets a funding lock associated to the header. It tests for an accountlock before/after to ensure there is no locking conflict. Finding an accountlock after setting a fundinglock causes the fundinglock to be released. account locks and funding locks are mutex. Finding a funding lock for the passed in uuid returns success without having to relock

Parameters:

bcHeader -

principalId -

Returns:

BudgetConstructionLockStatus with lockStatus.SUCCESS, BY_OTHER (accountlock found)

lockFunding

BudgetConstructionLockStatus lockFunding(PendingBudgetConstructionAppointmentFunding appointmentFunding,
                                         org.kuali.rice.kim.bo.Person person)

acquire a lock for the given appointment funding

Parameters:

appointmentFunding - the given appointment funding

person - the specified user

Returns:

BudgetConstructionLockStatus with lockStatus.SUCCESS, BY_OTHER (accountlock found)

unlockFunding

BCConstants.LockStatus unlockFunding(String chartOfAccountsCode,
                                     String accountNumber,
                                     String subAccountNumber,
                                     Integer fiscalYear,
                                     String principalId)

This removes the fundinglock for the account and user

Parameters:

chartOfAccountsCode -

accountNumber -

subAccountNumber -

fiscalYear -

principalId -

Returns:

LockStatus.SUCCESS, NO_DOOR (no fundinglock found)

unlockFunding

BCConstants.LockStatus unlockFunding(PendingBudgetConstructionAppointmentFunding appointmentFunding,
                                     org.kuali.rice.kim.bo.Person person)

release the lock for the given appointment funding if any

Parameters:

appointmentFunding - the given appointment funding that could have lock

person - the user who owns the lock on the given appointment funding

unlockFunding

void unlockFunding(List<PendingBudgetConstructionAppointmentFunding> lockedFundings,
                   org.kuali.rice.kim.bo.Person person)

release the locks for the given appointment fundings if any

Parameters:

lockedFundings - the given appointment fundings that could have locks

person - the user who owns the locks on the given appointment fundings

isFundingLockedByUser

boolean isFundingLockedByUser(String chartOfAccountsCode,
                              String accountNumber,
                              String subAccountNumber,
                              Integer fiscalYear,
                              String principalId)

Checks if the given user has a funding lock for the given accounting key.

Parameters:

chartOfAccountsCode - - chart code of funding lock

accountNumber - - account number of funding lock

subAccountNumber - - sub account number of funding lock

fiscalYear - - fiscal year of funding lock

principalId - - lock user id

Returns:

true if locked, false if not locked or not found in the database

lockPosition

BudgetConstructionLockStatus lockPosition(String positionNumber,
                                          Integer fiscalYear,
                                          String principalId)

This locks the position, meaning it sets the position lock id field with the puid. Finding the position already locked by the same user simply returns success.

Parameters:

positionNumber -

fiscalYear -

principalId -

Returns:

BudgetConstructionLockStatus with lockStatus.SUCCESS, OPTIMISTIC_EX (lost optimistic lock), BY_OTHER (also sets positionLockOwner), NO_DOOR (BudgetConstructionPosition found)

lockPosition

BudgetConstructionLockStatus lockPosition(BudgetConstructionPosition position,
                                          org.kuali.rice.kim.bo.Person person)

acquire a lock for the given budget position

Parameters:

position - the given position

person - the specified user

Returns:

BudgetConstructionLockStatus with lockStatus.SUCCESS, OPTIMISTIC_EX (lost optimistic lock), BY_OTHER (also sets positionLockOwner), NO_DOOR (BudgetConstructionPosition found)

isPositionLocked

boolean isPositionLocked(String positionNumber,
                         Integer fiscalYear)

This checks the database for an existing positionlock

Parameters:

positionNumber -

fiscalYear -

Returns:

true or false (not locked or BudgetConstructionPosition not found)

isPositionLockedByUser

boolean isPositionLockedByUser(String positionNumber,
                               Integer fiscalYear,
                               String principalId)

Checks the given user has an position lock for the given position number.

Parameters:

positionNumber - - position number of position record

fiscalYear - - fiscal year of position record

principalId - - lock user id

Returns:

true if locked, false if not locked or not found in the database

isPositionFundingLockedByUser

boolean isPositionFundingLockedByUser(String positionNumber,
                                      String chartOfAccountsCode,
                                      String accountNumber,
                                      String subAccountNumber,
                                      Integer fiscalYear,
                                      String principalId)

Checks the given user has an position/funding lock for the given position number and accounting key.

Parameters:

positionNumber - - position number of position record

chartOfAccountsCode - - chart code of funding lock

accountNumber - - account number of funding lock

subAccountNumber - - sub account number of funding lock

fiscalYear - - fiscal year of position and funding record

principalId - - lock user id

Returns:

true if locked, false if not locked or not found in the database

unlockPosition

BCConstants.LockStatus unlockPosition(String positionNumber,
                                      Integer fiscalYear)

This removes an existing positionlock

Parameters:

positionNumber -

fiscalYear -

Returns:

LockStatus.SUCCESS (success or already unlocked), OPTIMISTIC_EX (lost optimistic lock - unlikely), NO_DOOR (BudgetConstructionPosition not found)

unlockPosition

BCConstants.LockStatus unlockPosition(String positionNumber,
                                      Integer fiscalYear,
                                      String principalId)

release the locks on a positions with the given information

Parameters:

positionNumber - the given position number of a position

fiscalYear - the given fiscal year of a position

person - the specified user who owns the locks on the position

Returns:

LockStatus.SUCCESS (success or already unlocked), OPTIMISTIC_EX (lost optimistic lock - unlikely), NO_DOOR (BudgetConstructionPosition not found)

unlockPostion

BCConstants.LockStatus unlockPostion(BudgetConstructionPosition position,
                                     org.kuali.rice.kim.bo.Person person)

release the lock for the given position if any

Parameters:

position - the given budget construction position that could have locks

person - the specified user who owns the lock on the given position

unlockPostion

void unlockPostion(List<BudgetConstructionPosition> lockedPositions,
                   org.kuali.rice.kim.bo.Person person)

release the locks for the given positions if any

Parameters:

lockedPositions - the given budget construction positions that could have locks

person - the specified user who owns the locks on the given positions

lockTransaction

BudgetConstructionLockStatus lockTransaction(String chartOfAccountsCode,
                                             String accountNumber,
                                             String subAccountNumber,
                                             Integer fiscalYear,
                                             String principalId)

This attempts a transactionlock on a BC Edoc for a pUId. It retries based on the setting of BCConstants.maxLockRetry.

Parameters:

chartOfAccountsCode -

accountNumber -

subAccountNumber -

fiscalYear -

principalId -

Returns:

BudgetConstructionLockStatus with lockStatus.SUCCESS, OPTIMISTIC_EX (lost optimistic lock - unlikely) BY_OTHER (retries exhausted, also sets transactionLockOwner), NO_DOOR (BudgetConstructionHeader not found)

lockTransaction

BudgetConstructionLockStatus lockTransaction(PendingBudgetConstructionAppointmentFunding appointmentFunding,
                                             org.kuali.rice.kim.bo.Person person)

attemps to have a transaction lock based on the information provided by the given funding line

Parameters:

appointmentFunding - the given appointment funding

person - the specified user

isTransactionLocked

boolean isTransactionLocked(String chartOfAccountsCode,
                            String accountNumber,
                            String subAccountNumber,
                            Integer fiscalYear)

This checks the database for an existing transactionlock for the BC EDoc (account).

Parameters:

chartOfAccountsCode -

accountNumber -

subAccountNumber -

fiscalYear -

Returns:

true or false (not locked or BudgetConstructionHeader not found)

isTransactionLockedByUser

boolean isTransactionLockedByUser(String chartOfAccountsCode,
                                  String accountNumber,
                                  String subAccountNumber,
                                  Integer fiscalYear,
                                  String principalId)

Checks the given user has an transaction lock for the given document.

Parameters:

chartOfAccountsCode - - chart code of transaction lock

accountNumber - - account number of transaction lock

subAccountNumber - - sub account number of transaction lock

fiscalYear - - fiscal year of transaction lock

principalId - - lock user id

Returns:

true if locked, false if not locked or not found in the database

unlockTransaction

BCConstants.LockStatus unlockTransaction(String chartOfAccountsCode,
                                         String accountNumber,
                                         String subAccountNumber,
                                         Integer fiscalYear)

This removes an existing transactionlock for a BC EDoc (account).

Parameters:

chartOfAccountsCode -

accountNumber -

subAccountNumber -

fiscalYear -

Returns:

LockStatus.SUCCESS (success or already unlocked), OPTIMISTIC_EX (lost optimistic lock - unlikely), NO_DOOR (BudgetConstructionHeader not found)

unlockTransaction

void unlockTransaction(PendingBudgetConstructionAppointmentFunding appointmentFunding,
                       org.kuali.rice.kim.bo.Person person)

attemps to unlock a transaction based on the information provided by the given funding line

Parameters:

appointmentFunding - the given appointment funding

person - the specified user

getAllAccountLocks

List<BudgetConstructionHeader> getAllAccountLocks(String lockUnivId)

Retrieves all current account locks for the given user (or all locks if user is null/empty).

Parameters:

lockUnivId - - universal id that will be used in lock query

Returns:

budget headers that are locked

getAllTransactionLocks

List<BudgetConstructionHeader> getAllTransactionLocks(String lockUnivId)

Retrieves all current transaction locks for the given user (or all locks if user is null/empty).

Parameters:

lockUnivId - - universal id that will be used in lock query

Returns:

budget headers that are locked

getOrphanedFundingLocks

List<BudgetConstructionFundingLock> getOrphanedFundingLocks(String lockUnivId)

Retrieves all funding locks that do not have a corresponding position lock for the given user (or all locks if user is null/empty).

Parameters:

lockUnivId - - universal id that will be used in lock query

Returns:

funding locks records

getAllPositionFundingLocks

List<PendingBudgetConstructionAppointmentFunding> getAllPositionFundingLocks(String lockUnivId)

Retrieves all current position/funding locks for the given user (or all locks if user is null/empty).

Parameters:

lockUnivId - - universal id that will be used in lock query

Returns:

position/funding records that are locked.

getOrphanedPositionLocks

List<BudgetConstructionPosition> getOrphanedPositionLocks(String lockUnivId)

Retrieves all current position locks without a funding lock for the given user (or all locks if user is null/empty).

Parameters:

lockUnivId - universal id that will be used in lock query

Returns:

positions that are locked.

checkLockExists

boolean checkLockExists(BudgetConstructionLockSummary lockSummary)

Helper method to check if a lock exists for the given parameters.

Parameters:

lockSummary - - contains information about the record to unlock

Returns:

boolean true if lock exists, false otherwise

doUnlock

BCConstants.LockStatus doUnlock(BudgetConstructionLockSummary lockSummary)

Helper method to check the lock type and do the unlock with the lock summary fields.

Parameters:

lockSummary - - contains information about the record to unlock

Returns:

LockStatus.SUCCESS, NO_DOOR (not found), OPTIMISTIC_EX (lost optimistic lock)

isAccountLockedByUser

boolean isAccountLockedByUser(BudgetConstructionHeader budgetConstructionHeader,
                              org.kuali.rice.kim.bo.Person person)

determine whether the account lock on the given budget document is held by the the specified user

Parameters:

budgetConstructionHeader - the given budget document

person - the specified user

Returns:

true if the account lock on the given budget document is held by the the specified user; otherwise, false

lockPendingBudgetConstructionAppointmentFundingRecords

List<PendingBudgetConstructionAppointmentFunding> lockPendingBudgetConstructionAppointmentFundingRecords(List<PendingBudgetConstructionAppointmentFunding> fundingRecords,
                                                                                                         org.kuali.rice.kim.bo.Person user)
                                                                                                         throws BudgetConstructionLockUnavailableException

Retrieves account locks for funding records, for use in the payrate import process. Throws BudgetConstructionLockUnavailableException if new account lock is unavailable

Parameters:

fundingRecords -

user -

Returns:

Throws:

BudgetConstructionLockUnavailableException

lockAccountAndCommit

BudgetConstructionLockStatus lockAccountAndCommit(BudgetConstructionHeader bcHeader,
                                                  String principalId)

Retrives an account lock (@see org.kuali.kfs.module.bc.document.service.LockService#lockAccount(org.kuali.kfs.module.bc.businessobject.BudgetConstructionHeader, java.lang.String) and commits the lock. Used by the request import process.

Parameters:

bcHeader -

principalId -

Returns:

lockPositionAndActiveFunding

BudgetConstructionLockStatus lockPositionAndActiveFunding(Integer universityFiscalYear,
                                                          String positionNumber,
                                                          String principalId)

Locks the position record for the given key if not already locked. Then retrieves all active funding lines for the position that are not marked as delete and attempts to lock each one.

Parameters:

universityFiscalYear - budget fiscal year, primary key field for position record

positionNumber - position number, primary key field for position record

principalId - current user requesting the lock

Returns:

BudgetConstructionLockStatus indicating the status of the lock attempt. Success is returned if all lock attempts were successful, else one of the Failure status codes are returned

unlockPositionAndActiveFunding

BCConstants.LockStatus unlockPositionAndActiveFunding(Integer universityFiscalYear,
                                                      String positionNumber,
                                                      String principalId)

Unlocks the position and all associated funding lines not marked as delete.

Parameters:

universityFiscalYear - budget fiscal year, primary key field for position record

positionNumber - position number, primary key field for position record

principalId - current user requesting the unlock

Returns:

LockStatus indicating the status of the unlock attempt.