wt.locks
Class StandardLockService

java.lang.Object
  wt.services.StandardManager
      wt.locks.StandardLockService

All Implemented Interfaces:

LockService, Manager, NetFactor, Serializable

public class StandardLockService

extends StandardManager

implements LockService, Serializable

Provides an abstraction of the standard implementation of server-side functionality as defined by the LockService interface. This class can be augmented and/or extended to enhance functionality.

As defined by the standard locking service's access control rules, when attempting to lock an object if it is not already locked and the given principal has modify access to the object then it is locked. When attempting to unlock an object if it is already locked and the given principal has administrative access, or is the given principal is the one who originally placed the lock and has modify access to the object then it is unlocked. Otherwise, an exception is thrown indicating the failure. Additionally, when a lock is placed on an object by a principal, that user or group is the only agency able to then modify the object while it's in a locked state.

Event-based processing is performed on business objects asserted as being lockable during [preparation for] database modifications and full restorations. When a business object is [prepared for] being modified in the database this class listens to a dispatched event indicating that the modify is about to commence and vetoes it if the business object is locked and the current session's principal is not the one who originally placed the lock. Otherwise, the modification is allowed to take place. So it is valid to modify a business object that's lockable if it isn't locked. When a business object is being fully restored from the database this class listens to a dispatched event indicating that the full restoration is commencing and restores the lock cookie's locker reference.

If the standard implementation is not desired then a custom implementation can extend from LockService alongside the standard implementation, and be used as the default locking service.

Use the newStandardLockService static factory method(s), not the StandardLockService constructor, to construct instances of this class. Instances must be constructed using the static factory(s), in order to ensure proper initialization of the instance.

Supported API: true

Extendable: false

See Also:

StandardManager, LockServiceEvent, wt.fc.PersistenceManagerEvent.PREPARE_FOR_MODIFICATION, wt.fc.PersistenceManagerEvent.PRE_MODIFY, wt.fc.PersistenceManagerEvent.FULL_RESTORE, Serialized Form

Field Summary

private static String	CLASSNAME
private static boolean	LEAVE_MODIFY_DATE
private static String	RESOURCE

Fields inherited from class wt.services.StandardManager

Fields inherited from interface wt.services.Manager

MANAGER_SERVICE, STARTUP_AUTOMATIC, STARTUP_MANUAL, STATUS_EMERGENCY_SHUTDOWN, STATUS_EMERGENCY_SHUTTING_DOWN, STATUS_SHUTDOWN, STATUS_SHUTDOWN_ERRORS, STATUS_SHUTDOWN_FAILURE, STATUS_SHUTTING_DOWN, STATUS_STARTED, STATUS_STARTED_ERRORS, STATUS_STARTING_UP, STATUS_STARTUP_FAILURE

Constructor Summary

StandardLockService()

Method Summary

protected void	dispatchVetoableEvent(String eventType, Lockable object) Dispatches a LockServiceEvent that includes the event type and target (i.e., Lockable object).
String	getConceptualClassname() Deprecated.
Lockable	lock(Lockable object) Defaults the note to be null, the principal to be null, which makes the principal the session's user, and invokes the main lock method.
Lockable	lock(Lockable object, String note) Defaults the principal to be null, which makes the principal the session's user, and invokes the main lock method.
Lockable	lock(Lockable object, WTPrincipalReference locker) Defaults the note to be null and invokes the main lock method.
Lockable	lock(Lockable object, WTPrincipalReference locker, String note) Provides server-side functionality for the locking of business objects.
static StandardLockService	newStandardLockService() Default factory for the class.
protected void	performStartupProcess() Overrides the startup process specific to the locking service to provide custom startup for event subscription.
void	registerEvents(ManagerService manager) Overrides the registration of all applicable locking service events with the service manager.
protected void	restoreLock(Lockable object) Restores the locker of the lockable object's lock.
Lockable	unlock(Lockable object) Defaults the principal to be null, which makes the principal the session's user, and invokes the main unlock method.
Lockable	unlock(Lockable object, WTPrincipalReference locker) Provides server-side functionality for releasing a business object's lock.
protected void	validateLock(Lockable object) Vetoes a database modify if the object has been locked and if the current session's principal is not the one who placed the lock.

Methods inherited from class wt.services.StandardManager

emergencyShutdown, emergencyShutdownComplete, emergencyShuttingDown, getClassInfo, getManagerService, getManagerStatus, getName, getStartupType, init, initialize, initialize, isStarted, newStandardManager, newStandardManager, performEmergencyShutdownProcess, performShutdownProcess, setManagerService, shutdown, shutdownFailure, shutdownSuccess, shuttingDown, started, startedErrors, startingUp, startup, startupFailure, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

RESOURCE

private static final String RESOURCE

See Also:

Constant Field Values

CLASSNAME

private static final String CLASSNAME

LEAVE_MODIFY_DATE

private static final boolean LEAVE_MODIFY_DATE

See Also:

Constant Field Values

Constructor Detail

StandardLockService

public StandardLockService()

Method Detail

getConceptualClassname

public String getConceptualClassname()

Deprecated.

Returns the conceptual (modeled) name for the class.

Supported API: false

Specified by:

getConceptualClassname in interface NetFactor

Overrides:

getConceptualClassname in class StandardManager

Returns:

String

registerEvents

public void registerEvents(ManagerService manager)

Overrides the registration of all applicable locking service events with the service manager.

Supported API: false

Specified by:

registerEvents in interface Manager

Overrides:

registerEvents in class StandardManager

Parameters:

manager -

dispatchVetoableEvent

protected void dispatchVetoableEvent(String eventType,
                                     Lockable object)
                              throws WTException,
                                     WTPropertyVetoException

Dispatches a LockServiceEvent that includes the event type and target (i.e., Lockable object).

Supported API: false

Parameters:

eventType - The name of the PersistentManagerEvent type.

object - The target of the persistable operation.

Throws:

WTException

WTPropertyVetoException

performStartupProcess

protected void performStartupProcess()
                              throws ManagerException

Overrides the startup process specific to the locking service to provide custom startup for event subscription. During subscription an anonymous inner class adapter is created per subscription to handle each specific event of interest.

Supported API: false

Overrides:

performStartupProcess in class StandardManager

Throws:

ManagerException

validateLock

protected void validateLock(Lockable object)
                     throws WTException,
                            LockException

Vetoes a database modify if the object has been locked and if the current session's principal is not the one who placed the lock.

Supported API: false

Parameters:

object -

Throws:

WTException

LockException

restoreLock

protected void restoreLock(Lockable object)
                    throws WTException,
                           LockException

Restores the locker of the lockable object's lock.

Supported API: false

Parameters:

object -

Throws:

WTException

LockException

newStandardLockService

public static StandardLockService newStandardLockService()
                                                  throws WTException

Default factory for the class.

Supported API: false

Returns:

StandardLockService

Throws:

WTException

lock

public Lockable lock(Lockable object,
                     WTPrincipalReference locker,
                     String note)
              throws WTException,
                     LockException,
                     WTPropertyVetoException,
                     PersistenceException

Provides server-side functionality for the locking of business objects. This type of lock is a logical mechanism to restrict concurrent access, not a database lock. If the given principal is null then the current session's principal is used as the locker. When a lock is placed on an object by a principal, that user or group is typically the only agency able to then modify the object.

However, if an object is lockable but has not yet been locked, then any agency has unrestricted access to the object until it has been locked.

Supported API: true

Specified by:

lock in interface LockService

Parameters:

object -

locker -

note -

Returns:

Lockable

Throws:

WTException

LockException

WTPropertyVetoException

PersistenceException

lock

public Lockable lock(Lockable object,
                     WTPrincipalReference locker)
              throws WTException,
                     LockException,
                     WTPropertyVetoException,
                     PersistenceException

Defaults the note to be null and invokes the main lock method.

Supported API: true

Specified by:

lock in interface LockService

Parameters:

object -

locker -

Returns:

Lockable

Throws:

WTException

LockException

WTPropertyVetoException

PersistenceException

See Also:

LockService.lock(Lockable,WTPrincipalReference,String)

lock

public Lockable lock(Lockable object,
                     String note)
              throws WTException,
                     LockException,
                     WTPropertyVetoException,
                     PersistenceException

Defaults the principal to be null, which makes the principal the session's user, and invokes the main lock method.

Supported API: true

Specified by:

lock in interface LockService

Parameters:

object -

note -

Returns:

Lockable

Throws:

WTException

LockException

WTPropertyVetoException

PersistenceException

See Also:

LockService.lock(Lockable,WTPrincipalReference,String)

lock

public Lockable lock(Lockable object)
              throws WTException,
                     LockException,
                     WTPropertyVetoException,
                     PersistenceException

Defaults the note to be null, the principal to be null, which makes the principal the session's user, and invokes the main lock method.

Supported API: true

Specified by:

lock in interface LockService

Parameters:

object -

Returns:

Lockable

Throws:

WTException

LockException

WTPropertyVetoException

PersistenceException

See Also:

LockService.lock(Lockable,WTPrincipalReference,String)

unlock

public Lockable unlock(Lockable object,
                       WTPrincipalReference locker)
                throws WTException,
                       LockException,
                       WTPropertyVetoException,
                       PersistenceException

Provides server-side functionality for releasing a business object's lock. If the given principal is null then the current session's principal is used as the locker. When a lock is released off of an object, its access becomes unrestricted.

Supported API: true

Specified by:

unlock in interface LockService

Parameters:

object -

locker -

Returns:

Lockable

Throws:

WTException

LockException

WTPropertyVetoException

PersistenceException

unlock

public Lockable unlock(Lockable object)
                throws WTException,
                       LockException,
                       WTPropertyVetoException,
                       PersistenceException

Defaults the principal to be null, which makes the principal the session's user, and invokes the main unlock method.

Supported API: true

Specified by:

unlock in interface LockService

Parameters:

object -

Returns:

Lockable

Throws:

WTException

LockException

WTPropertyVetoException

PersistenceException

See Also:

LockService.unlock(Lockable,WTPrincipalReference)