atg.service.lockmanager

Class ClientLockManager

java.lang.Object

atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

atg.nucleus.GenericService

atg.service.lockmanager.ClientLockManager

All Implemented Interfaces:

atg.core.logging.Logging, atg.core.logging.TraceLogging, atg.naming.AbsoluteNameable, NameContextBindingListener, NameContextElement, atg.naming.NameContextParentable, NameResolver, AdminableService, atg.nucleus.Configured, ApplicationLogging, atg.nucleus.logging.ApplicationLoggingSender, atg.nucleus.logging.TraceApplicationLogging, VariableArgumentApplicationLogging, ComponentNameResolver, Service, ServiceListener, java.lang.Runnable, java.util.EventListener

public class ClientLockManager
extends GenericService
implements java.lang.Runnable

The ClientLockManager class exposes functionality that allows site-wide coordination of locks across a set of participating processes. For it to function, you require an instance of a ServerLockManager running on the network and you need to configure the ClientLockManager with the server's IP address and port number.

The ClientLockManager has a single socket connection to the lock server that it uses to send and receive messages. It has a polling thread that reads incoming messages and processes them waking up clients etc. You directly call methods on this object to obtain and release locks.

Keys for locks must be serializable and must implement hashCode and equals methods which are preserved across serialization.

Note that there is a "failover" for a lock server - when a lock server goes down the client tries to connect to another backup server (if configured). If both the client and the backup server go down, the ClientLockManager switches to a local mode that guarantees locks only from within the local process run locally. Servers are connected to each other via sockets and they decide between themselves which one is primary and which one is a backup at run time based on their IP addresses. They try to establish a connection with each other at specified time intervals (otherServerPollInterval property). When a backup server cannot connect to the primary server it assumes that it should become the primary itself. It waits a specified time interval (waitTimeBeforeSwitchingFromBackup property) to allow locks that were held by another server to be released by clients, and then starts accepting new requests from clients.

To use a "failover" lock server, LockServerAddress and LockServerPort properties of a lock client have to be configured with an array of two addresses/ports pointing to two separate lock servers.

The status code for the Acquire Lock methods indicates whether the lock is obtained globally or localy.

The global timeout/interrupt feature allows ClientLockManager to interrupt and release locks that are held for a long period of time. It can be used to timeout the ownership of locks in cases when a lock owner cannot release them in a timely fashion. This situation may occur, for example, when a thread that owns the locks hangs for some reason. In order for a lock held by an owner to be timed out two conditions should be true: - Lock owner must implement InterruptibleLockOwner interface. - Time passed since the lock was acquired by a ClientLockManager should be greater than a specified time interval timeoutLockIntervalSecs. ClientLockManager runs a separate thread that checks all the locks for the conditions above and if a lock satisfies both conditions it calls the InterruptibleLockOwner.interrupt() method and then releases the lock. Note that if timeoutLockIntervalSecs is set to 0 (default value) ClientLockManager will not run the check, so there is no additional overhead in this case.

There is one other subtle feature of the ClientLockManager. When you release a lock, you have the option of releasing the lock on the server or retaining lock ownership on the client process. If you release the lock on the server, the next Acquire Lock call must go to the server again to obtain ownership. If you retain lock ownership in the client process, subsequent calls to acquire the lock for the same key can return without communicating with the server. If you do not release lock ownership, be aware that both the client and server will retain data structures for that key until you explicitly call the giveUpOwnership method. Also, if you want to be notified when your process loses ownership of a given lock, you can register for a lock ownership listener using the addLockOwnershipListener method. The SQL Repository uses this facility to invalidate caches of a given item when a lock is required in a different JVM.

The ClientLockManager can be used to implement locking on a local process only by setting the UseLockServer property to false. If you do this, be sure no one else is using the same local server instance and expecting it to do cross process locking.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CLASS_VERSION Class version string

Fields inherited from class atg.nucleus.GenericService

SERVICE_INFO_KEY

Fields inherited from interface atg.nucleus.logging.TraceApplicationLogging

DEFAULT_LOG_TRACE_STATUS

Fields inherited from interface atg.nucleus.logging.ApplicationLogging

DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS

Constructor Summary

Constructors

Constructor and Description
ClientLockManager()

Method Summary

Methods

Modifier and Type	Method and Description
boolean	acquireReadLock(java.io.Serializable pKey) Acquires the lock for the key that is passed in.
boolean	acquireReadLock(java.io.Serializable pKey, java.lang.Object pOwner) Acquires the lock for the key that is passed in.
boolean	acquireReadLock(java.io.Serializable pKey, java.lang.Object pOwner, long pTimeout) Acquires the lock for the key that is passed in.
boolean	acquireWriteLock(java.io.Serializable pKey) Acquires the lock for the key that is passed in.
boolean	acquireWriteLock(java.io.Serializable pKey, java.lang.Object pOwner) Acquires the lock for the key that is passed in.
boolean	acquireWriteLock(java.io.Serializable pKey, java.lang.Object pOwner, long pTimeout) Acquires the lock for the key that is passed in.
void	addLockOwnershipListener(atg.service.lockmanager.LockOwnershipListener pListener) Adds a listener for lock ownership events.
void	closeSocket() Closes the socket and all streams
boolean	convertReadToWrite(java.io.Serializable pKey) Use this when the you currently have a read lock and need a write lock for the same key.
boolean	convertReadToWrite(java.io.Serializable pKey, java.lang.Object pOwner) Use this when the you currently have a read lock and need a write lock for the same key.
protected javax.servlet.Servlet	createAdminServlet() Displays current client lock manager state.
void	doStartService() This is called after a Service has been created, placed into the naming hierarchy, and initialized with its configured property values.
void	doStopService() This is called when a Service is required to shut down.
boolean	getCheckForDeadlocks()
long	getConnectTimeout()
java.net.InetAddress	getLocalAddress()
int	getLocalPort()
atg.service.lockmanager.LockOwnerTable	getLockOwnerTable()
int	getLockOwnerTableSize() Returns the number of lock owners we are currently storing in the table.
java.net.InetAddress[]	getLockServerAddress()
int[]	getLockServerPort()
long	getLockTimeout()
boolean	getLogWarningWhenUnavailable()
int	getSequenceNum() The sequence number is incremented each time a connection is broken or reestablished to a lock server.
java.net.InetAddress	getServerSocketInetAddress() Get the socket inet address for the socket to the server, if any.
int	getServerSocketPort() Get the port number for the socket to the server, if any.
int	getTimeoutLockIntervalSecs()
boolean	getUseLockServer()
int	getWarnIntervalSecs()
void	giveUpOwnership(java.io.Serializable pKey) Call this method when it is no longer to your advantage for your process to maintain ownership of the locks for this key.
boolean	hasReadLock(java.lang.String pKey, java.lang.Object pOwner) Whether the specified owner current owns the read lock for the specified key.
boolean	hasWriteLock(java.lang.String pKey, java.lang.Object pOwner) Whether the specified owner current owns the write lock for the specified key.
boolean	isAvailable()
boolean	isCropOwnerString() Returns property CropOwnerString
boolean	isEnablePerformanceMonitor()
boolean	isLocallyLocked(java.lang.Object pKey) Gives the status of a lock on a particular key for this process.
void	releaseReadLock(java.io.Serializable pKey) Releases the lock that is passed in.
void	releaseReadLock(java.io.Serializable pKey, java.lang.Object pOwner) Releases the lock that is passed in.
void	releaseReadLock(java.io.Serializable pKey, java.lang.Object pOwner, boolean pOnlyIfOwned) Releases the lock that is passed in.
void	releaseReadLock(java.io.Serializable pKey, java.lang.Object pOwner, boolean pOnlyIfOwned, boolean pKeepProcessOwnership) Releases the lock that is passed in.
void	releaseWriteLock(java.io.Serializable pKey) Releases the lock that is passed in.
void	releaseWriteLock(java.io.Serializable pKey, java.lang.Object pOwner) Releases the lock that is passed in.
void	releaseWriteLock(java.io.Serializable pKey, java.lang.Object pOwner, boolean pOnlyIfOwned) Releases the lock that is passed in.
void	releaseWriteLock(java.io.Serializable pKey, java.lang.Object pOwner, boolean pOnlyIfOwned, boolean pKeepProcessOwnership) Releases the lock that is passed in.
void	removeLockOwnershipListener(atg.service.lockmanager.LockOwnershipListener pListener) Removes a listener for lock ownership events.
void	run()
void	setCheckForDeadlocks(boolean pCheckForDeadlocks) Sets the property CheckForDeadlocks.
void	setConnectTimeout(long pConnectTimeout) Sets the property ConnectTimeout.
void	setCropOwnerString(boolean pCropOwnerString) Sets property CropOwnerString, default is true
void	setEnablePerformanceMonitor(boolean pEnablePerformanceMonitor) Allows performance monitoring for ClientLockManager to be disabled on a component basis.
void	setLocalAddress(java.net.InetAddress pLocalAddress) Sets the property LocalAddress.
void	setLocalPort(int pLocalPort) Sets the property LocalPort.
void	setLockServerAddress(java.net.InetAddress[] pLockServerAddress) Sets the property LockServerAddress.
void	setLockServerPort(int[] pLockServerPort) Sets the property LockServerPort.
void	setLockTimeout(long pLockTimeout) Sets the property LockTimeout, which is used internally to set the interval used to acquire lock timeouts.
void	setLogWarningWhenUnavailable(boolean pLogWarnings) Sets the property LogWarningWhenUnavailable.
void	setTimeoutLockIntervalSecs(int pTimeoutLockIntervalSecs) Sets the property TimeoutLockIntervalSecs.
void	setUseLockServer(boolean pUseLockServer) Sets the property UseLockServer.
void	setWarnIntervalSecs(int pWarnIntervalSecs) Sets the property WarnIntervalSecs.
protected void	updateSequenceNum() Updates the SequenceNum.

Methods inherited from class atg.nucleus.GenericService

addLogListener, getAbsoluteName, getAdminServlet, getAdminServletOutputStreamEncoding, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isAdminServletUseServletOutputStream, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, reResolveThis, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setAdminServletOutputStreamEncoding, setAdminServletUseServletOutputStream, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService

Methods inherited from class atg.nucleus.logging.VariableArgumentApplicationLoggingImpl

vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogDebugTrace, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning

Methods inherited from class java.lang.Object

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

Field Detail

CLASS_VERSION

public static java.lang.String CLASS_VERSION

Class version string

Constructor Detail

ClientLockManager

public ClientLockManager()

Method Detail

setWarnIntervalSecs

public void setWarnIntervalSecs(int pWarnIntervalSecs)

Sets the property WarnIntervalSecs. This is the number of seconds in between which we print out the "cache disabled" warnings.

Parameters:

pWarnIntervalSecs - new value to set

getWarnIntervalSecs

public int getWarnIntervalSecs()

Returns:

The value of the property WarnIntervalSecs.

setTimeoutLockIntervalSecs

public void setTimeoutLockIntervalSecs(int pTimeoutLockIntervalSecs)

Sets the property TimeoutLockIntervalSecs. For lock owners which implement the InterruptibleLockOwner interface, this time specifies the maximum time an owner can own a lock. When the lock is held for longer than this interval, the InterruptibleLockOwner's interrupt method is called and the lock is released automatically.

Parameters:

pTimeoutLockIntervalSecs - new value to set

getTimeoutLockIntervalSecs

public int getTimeoutLockIntervalSecs()

Returns:

The value of the property TimeoutLockIntervalSecs.

updateSequenceNum

protected void updateSequenceNum()

Updates the SequenceNum. This should be invoked when the connection status to the server changes.

getSequenceNum

public int getSequenceNum()

The sequence number is incremented each time a connection is broken or reestablished to a lock server.

Returns:

The value of the property SequenceNum.

setLockServerAddress

public void setLockServerAddress(java.net.InetAddress[] pLockServerAddress)

Sets the property LockServerAddress. This is the IP address of the lock server to connect to.

Parameters:

pLockServerAddress - new value to set

getLockServerAddress

public java.net.InetAddress[] getLockServerAddress()

Returns:

The value of the property LockServerAddress.

setLockServerPort

public void setLockServerPort(int[] pLockServerPort)

Sets the property LockServerPort. This is the port # of the lock server we connect to.

Parameters:

pLockServerPort - new value to set

getLockServerPort

public int[] getLockServerPort()

Returns:

The value of the property LockServerPort.

setLocalAddress

public void setLocalAddress(java.net.InetAddress pLocalAddress)

Sets the property LocalAddress. This is the IP address the client binds its side of the socket to (if it is not set, the default IP address is used).

Parameters:

pLocalAddress - new value to set

getLocalAddress

public java.net.InetAddress getLocalAddress()

Returns:

The value of the property LocalAddress.

setLocalPort

public void setLocalPort(int pLocalPort)

Sets the property LocalPort. This is the port number the client binds its side of the socket to. If it is not set, the system chooses an available port number.

Parameters:

pLocalPort - new value to set

getLocalPort

public int getLocalPort()

Returns:

The value of the property LocalPort.

setConnectTimeout

public void setConnectTimeout(long pConnectTimeout)

Sets the property ConnectTimeout. This is how long we wait before timing out a socket connection, and how long we wait before trying to connect again.

Parameters:

pConnectTimeout - new value to set

getConnectTimeout

public long getConnectTimeout()

Returns:

The value of the property ConnectTimeout.

setLockTimeout

public void setLockTimeout(long pLockTimeout)

Sets the property LockTimeout, which is used internally to set the interval used to acquire lock timeouts. Note that this is not a global timeout. To set a global ClientLockTimeout, set the ClientLockTimeout component on the repository.

Parameters:

pLockTimeout - new value to set

getLockTimeout

public long getLockTimeout()

Returns:

The value of the property LockTimeout.

setLogWarningWhenUnavailable

public void setLogWarningWhenUnavailable(boolean pLogWarnings)

Sets the property LogWarningWhenUnavailable. If this is true, we log a warning periodically when we are not connected to the lock server.

Parameters:

pLogWarningWhenUnavailable - new value to set

getLogWarningWhenUnavailable

public boolean getLogWarningWhenUnavailable()

Returns:

The value of the property LogWarningWhenUnavailable.

isAvailable

public boolean isAvailable()

Returns:

The value of the property Available.

setEnablePerformanceMonitor

public void setEnablePerformanceMonitor(boolean pEnablePerformanceMonitor)

Allows performance monitoring for ClientLockManager to be disabled on a component basis. If PerformanceMonitor.isEnabled() is true and #isEnablePerformanceMonitor() is true then performance monitor statistics will be recorded for this component. Performance Monitor statistics are captured per key to help identify which keys are called most frequently and which keys have the longest wait times.

isEnablePerformanceMonitor

public boolean isEnablePerformanceMonitor()

Returns:

The value of the property WarnIntervalSecs.

setUseLockServer

public void setUseLockServer(boolean pUseLockServer)

Sets the property UseLockServer. If this property is set to false, we will not try to connect to a lock server. You can use this flag=false if you want to perform locking in the local process only.

Parameters:

pUseLockServer - new value to set

getUseLockServer

public boolean getUseLockServer()

Returns:

The value of the property UseLockServer.

setCheckForDeadlocks

public void setCheckForDeadlocks(boolean pCheckForDeadlocks)

Sets the property CheckForDeadlocks. If this property is set to false, we disable deadlock detection.

Parameters:

pCheckForDeadlocks - new value to set

getCheckForDeadlocks

public boolean getCheckForDeadlocks()

Returns:

The value of the property CheckForDeadlocks.

setCropOwnerString

public void setCropOwnerString(boolean pCropOwnerString)

Sets property CropOwnerString, default is true

isCropOwnerString

public boolean isCropOwnerString()

Returns property CropOwnerString

doStartService

public void doStartService()
                    throws ServiceException

Description copied from class: GenericService

This is called after a Service has been created, placed into the naming hierarchy, and initialized with its configured property values. The Service should override this method to start any processes it requires.

Overrides:

doStartService in class GenericService

Throws:

ServiceException - if the Service had a problem starting up

doStopService

public void doStopService()
                   throws ServiceException

Description copied from class: GenericService

This is called when a Service is required to shut down. The Service should respond by stopping any processes that it has started.

Overrides:

doStopService in class GenericService

Throws:

ServiceException - if the Service had a problem shutting down

closeSocket

public void closeSocket()

Closes the socket and all streams

acquireReadLock

public boolean acquireReadLock(java.io.Serializable pKey,
                      java.lang.Object pOwner)
                        throws DeadlockException

Acquires the lock for the key that is passed in. The key must be a serializable object which properly implements the equals and hashCode methods to determine equality of two keys. The owner must be a unique value which identifies the "owner" of the lock. The owner must be the match the owner used in a release call. Often this is just Thread.currentThread() but in some cases it might make sense to acquire locks from different threads or to spread ownership across more than one thread. In this case, you just choose the identity of the owner. Note that the owner's identity is used in deadlock detection to identify which owners have which locks.

Parameters:

pKey - the key/name of the lock

Returns:

true if the lock is obtained globally, false if the lock server is unavailable and the lock is only valid for the current virtual machine. You must release the lock in either case.

Throws:

DeadlockException - is thrown if the lock could not be acquired because a deadlock was detected

hasWriteLock

public boolean hasWriteLock(java.lang.String pKey,
                   java.lang.Object pOwner)

Whether the specified owner current owns the write lock for the specified key.

Parameters:

pKey - the key/name of the lock

pOwner - the owner to check

hasReadLock

public boolean hasReadLock(java.lang.String pKey,
                  java.lang.Object pOwner)

Whether the specified owner current owns the read lock for the specified key.

Parameters:

pKey - the key/name of the lock

pOwner - the owner to check

acquireReadLock

public boolean acquireReadLock(java.io.Serializable pKey,
                      java.lang.Object pOwner,
                      long pTimeout)
                        throws DeadlockException,
                               TimeExceededException

Acquires the lock for the key that is passed in. The key must be a serializable object which properly implements the equals and hashCode methods to determine equality of two keys. The owner must be a unique value which identifies the "owner" of the lock. The owner must be the match the owner used in a release call. Often this is just Thread.currentThread() but in some cases it might make sense to acquire locks from different threads or to spread ownership across more than one thread. In this case, you just choose the identity of the owner. Note that the owner's identity is used in deadlock detection to identify which owners have which locks.

Parameters:

pKey - the key/name of the lock

pOwner - the owner for this lock

pTimeout - a value specifies the maximum time to wait for this lock. It this amount of of time expires, we throw the TimeExceededException A value of 0 means no timeout.

Returns:

true if the lock is obtained globally, false if the lock server is unavailable and the lock is only valid for the current virtual machine. You must release the lock in either case.

Throws:

DeadlockException - is thrown if the lock could not be acquired because a deadlock was detected

TimeExceededException

acquireWriteLock

public boolean acquireWriteLock(java.io.Serializable pKey,
                       java.lang.Object pOwner)
                         throws DeadlockException

Acquires the lock for the key that is passed in. The key must be a serializable object which properly implements the equals and hashCode methods to determine equality of two keys. The owner must be a unique value which identifies the "owner" of the lock. The owner must be the match the owner used in a release call. Often this is just Thread.currentThread() but in some cases it might make sense to acquire locks from different threads or to spread ownership across more than one thread. In this case, you just choose the identity of the owner. Note that the owner's identity is used in deadlock detection to identify which owners have which locks.

Parameters:

pKey - the key/name of the lock

pOwner - this is an object which identifies the owner of this lock.

Returns:

true if the lock is obtained globally, false if the lock server is unavailable and the lock is only valid for the current virtual machine. You must release the lock in either case.

Throws:

DeadlockException - is thrown if the lock could not be acquired because a deadlock was detected

acquireWriteLock

public boolean acquireWriteLock(java.io.Serializable pKey,
                       java.lang.Object pOwner,
                       long pTimeout)
                         throws DeadlockException,
                                TimeExceededException

Acquires the lock for the key that is passed in. The key must be a serializable object which properly implements the equals and hashCode methods to determine equality of two keys. The owner must be a unique value which identifies the "owner" of the lock. The owner must be the match the owner used in a release call. Often this is just Thread.currentThread() but in some cases it might make sense to acquire locks from different threads or to spread ownership across more than one thread. In this case, you just choose the identity of the owner. Note that the owner's identity is used in deadlock detection to identify which owners have which locks.

Parameters:

pKey - the key/name of the lock

pOwner - this is an object which identifies the owner of this lock.

pTimeout - a value specifies the maximum time to wait for this lock. It this amount of of time expires, we throw the TimeExceededException A value of 0 means no timeout.

Returns:

true if the lock is obtained globally, false if the lock server is unavailable and the lock is only valid for the current virtual machine. You must release the lock in either case.

Throws:

DeadlockException - is thrown if the lock could not be acquired because a deadlock was detected

TimeExceededException

acquireReadLock

public boolean acquireReadLock(java.io.Serializable pKey)
                        throws DeadlockException

Acquires the lock for the key that is passed in. This version uses the current thread's id as the owner of the lock. If you need to release this lock from a different thread, use the version of this method which takes a specific owner.

Parameters:

pKey - the key/name of the lock

Returns:

true if the lock is obtained globally, false if the lock server is unavailable and the lock is only valid for the current virtual machine. You must release the lock in either case.

Throws:

DeadlockException - is thrown if the lock could not be acquired because a deadlock was detected

acquireWriteLock

public boolean acquireWriteLock(java.io.Serializable pKey)
                         throws DeadlockException

Acquires the lock for the key that is passed in. This version uses the current thread's id as the owner of the lock. If you need to release this lock from a different thread, use the version of this method which takes a specific owner.

Parameters:

pKey - the key/name of the lock

Returns:

true if the lock is obtained globally, false if the lock server is unavailable and the lock is only valid for the current virtual machine. You must release the lock in either case.

Throws:

DeadlockException - is thrown if the lock could not be acquired because a deadlock was detected

releaseReadLock

public void releaseReadLock(java.io.Serializable pKey,
                   java.lang.Object pOwner)
                     throws LockManagerException

Releases the lock that is passed in. If other threads are waiting for the release of the lock the next thread in line will be unblocked.

Parameters:

pKey - the key to release

pOwner - the identify of the owner of this lock

Throws:

LockManagerException - is thrown if the lock was not owned by this owner.

releaseReadLock

public void releaseReadLock(java.io.Serializable pKey,
                   java.lang.Object pOwner,
                   boolean pOnlyIfOwned)
                     throws LockManagerException

Releases the lock that is passed in. If other threads are waiting for the release of the lock the next thread in line will be unblocked.

Parameters:

pKey - the key to release

pOwner - the identify of the owner of this lock

pOnlyIfOwned - if this is true, we'll try to release the lock only if the lock is already owned. In other words, we ignore the error when you try to a release a lock that is not owned.

Throws:

LockManagerException - is thrown if the lock was not owned by this owner.

releaseReadLock

public void releaseReadLock(java.io.Serializable pKey,
                   java.lang.Object pOwner,
                   boolean pOnlyIfOwned,
                   boolean pKeepProcessOwnership)
                     throws LockManagerException

Releases the lock that is passed in. If other threads are waiting for the release of the lock the next thread in line will be unblocked.

Parameters:

pKey - the key to release

pOwner - the identify of the owner of this lock

pOnlyIfOwned - if this is true, we'll try to release the lock only if the lock is already owned. In other words, we ignore the error when you try to a release a lock that is not owned.

pKeepProcessOwnership - if this is true, the ownership of the lock is held in this process until it is explicitly released with the giveUpOwnership call. Use this if you want to implement a lock that is attached to a cache of some sort. If you supply a value of true, but do not call giveUpOwnership at some point for this key, it will result in a memory leak for the server lock manager which will keep a reference to this lock.

Throws:

LockManagerException - is thrown if the lock was not owned by this owner.

releaseWriteLock

public void releaseWriteLock(java.io.Serializable pKey,
                    java.lang.Object pOwner)
                      throws LockManagerException

Releases the lock that is passed in. If other threads are waiting for the release of the lock the next thread in line will be unblocked.

Parameters:

pKey - the key to be released

Throws:

LockManagerException - is thrown if the lock fails be released

releaseWriteLock

public void releaseWriteLock(java.io.Serializable pKey,
                    java.lang.Object pOwner,
                    boolean pOnlyIfOwned)
                      throws LockManagerException

Releases the lock that is passed in. If other threads are waiting for the release of the lock the next thread in line will be unblocked.

Parameters:

pKey - the key to be released

pOwner - the identity of the owner of the lock

pOnlyIfOwned - if this is true, we'll try to release the lock only if the lock is already owned. In other words, we ignore the error when you try to a release a lock that is not owned.

Throws:

LockManagerException - is thrown if the lock fails be released

releaseWriteLock

public void releaseWriteLock(java.io.Serializable pKey,
                    java.lang.Object pOwner,
                    boolean pOnlyIfOwned,
                    boolean pKeepProcessOwnership)
                      throws LockManagerException

Releases the lock that is passed in. If other threads are waiting for the release of the lock the next thread in line will be unblocked.

Parameters:

pKey - the key to be released

pOwner - the identity of the owner of the lock

pOnlyIfOwned - if this is true, we'll try to release the lock only if the lock is already owned. In other words, we ignore the error when you try to a release a lock that is not owned.

Throws:

LockManagerException - is thrown if the lock fails be released

releaseReadLock

public void releaseReadLock(java.io.Serializable pKey)
                     throws LockManagerException

Releases the lock that is passed in. If other threads are waiting for the release of the lock the next thread in line will be unblocked.

Parameters:

pKey - the key to be released

Throws:

LockManagerException - is thrown if the lock fails be released

releaseWriteLock

public void releaseWriteLock(java.io.Serializable pKey)
                      throws LockManagerException

Releases the lock that is passed in. If other threads are waiting for the release of the lock the next thread in line will be unblocked.

Parameters:

pKey - the key to be released

Throws:

LockManagerException - is thrown if the lock fails be released

convertReadToWrite

public boolean convertReadToWrite(java.io.Serializable pKey,
                         java.lang.Object pOwner)
                           throws DeadlockException,
                                  LockManagerException

Use this when the you currently have a read lock and need a write lock for the same key. This method returns true if you are able to get the write lock before some other owner and false if another owner obtained a write lock after your read lock was released and before your write lock is acquired. If false is returned, you do not have either the read or the write lock on this key. You must reacquire them if you want them again.

Returns:

true if the conversion is successful, false if it failed.

Throws:

DeadlockException - if a deadlock would occur if you obtained the write lock.

LockManagerException - if you do not own the read lock when this call is made.

convertReadToWrite

public boolean convertReadToWrite(java.io.Serializable pKey)
                           throws DeadlockException,
                                  LockManagerException

Use this when the you currently have a read lock and need a write lock for the same key. This method returns true if you are able to get the write lock before some other owner and false if another owner obtained a write lock after your read lock was released and before your write lock is acquired. If false is returned, you do not have either the read or the write lock on this key. You must reacquire them if you want them again.

This version uses the current thread as the owner of the lock.

Returns:

true if the conversion is successful, false if it failed.

Throws:

DeadlockException - if a deadlock would occur if you obtained the write lock.

LockManagerException - if you do not own the read lock when this call is made.

giveUpOwnership

public void giveUpOwnership(java.io.Serializable pKey)

Call this method when it is no longer to your advantage for your process to maintain ownership of the locks for this key. If you remove an entry from the cache, it is probably a good idea to get rid of lock ownership at the same time for example. If you don't call this method, and you no longer have any reference to the object referred to by key, the client's lock table can grow without bounds.

isLocallyLocked

public boolean isLocallyLocked(java.lang.Object pKey)

Gives the status of a lock on a particular key for this process. Warning - if you are using a distributed lock server, this method does not take into account locks in other VMs.

Returns:

true if some owner has a lock on the given key, false otherwise

addLockOwnershipListener

public void addLockOwnershipListener(atg.service.lockmanager.LockOwnershipListener pListener)

Adds a listener for lock ownership events.

removeLockOwnershipListener

public void removeLockOwnershipListener(atg.service.lockmanager.LockOwnershipListener pListener)

Removes a listener for lock ownership events.

run

public void run()

Specified by:

run in interface java.lang.Runnable

getLockOwnerTable

public atg.service.lockmanager.LockOwnerTable getLockOwnerTable()

Returns:

The value of the property LockOwnerTable.

getLockOwnerTableSize

public int getLockOwnerTableSize()

Returns the number of lock owners we are currently storing in the table.

getServerSocketInetAddress

public java.net.InetAddress getServerSocketInetAddress()

Get the socket inet address for the socket to the server, if any.

getServerSocketPort

public int getServerSocketPort()

Get the port number for the socket to the server, if any. Return 0, otherwise.

createAdminServlet

protected javax.servlet.Servlet createAdminServlet()

Displays current client lock manager state.

Overrides:

createAdminServlet in class GenericService