|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object atg.nucleus.logging.VariableArgumentApplicationLoggingImpl atg.nucleus.GenericService atg.service.lockmanager.ClientLockManager
public class ClientLockManager
The client lock manager 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 client lock manager has a single socket connection to the lock server which it uses to send and receive messages. It has a polling thread which 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 client tries to connect to another backup server (if configured), if both of then do down , the client lock manager switches to a local mode where guarantees locks only from within the local process. 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 prperty). 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, which 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 properies of a lock clinet have to be configured with array of two adresses/ports pointing to two separate lock servers.
The status code for the acquire lock methods indicates whether the lock is obtained globally or localy.
Global timeout/interrupt feature allows client lock manager 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 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 client lock manager should be greater than a specified time interval timeoutLockIntervalSecs. Client lock manager is running a separate thread that checks all the locks for the conditions above and if a lock satisfy both conditions it calls InterruptibleLockOwner.interrupt() method and then releases the lock. Note that if timeoutLockIntervalSecs is set to 0 (default value) client lock manager 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 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 | |
---|---|
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 | |
---|---|
ClientLockManager()
|
Method Summary | |
---|---|
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. |
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. |
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. |
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.logging.VariableArgumentApplicationLoggingImpl |
---|
vlogDebug, vlogDebug, vlogDebug, vlogDebug, 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 |
---|
public static java.lang.String CLASS_VERSION
Constructor Detail |
---|
public ClientLockManager()
Method Detail |
---|
public void setWarnIntervalSecs(int pWarnIntervalSecs)
pWarnIntervalSecs
- new value to setpublic int getWarnIntervalSecs()
public void setTimeoutLockIntervalSecs(int pTimeoutLockIntervalSecs)
pTimeoutLockIntervalSecs
- new value to setpublic int getTimeoutLockIntervalSecs()
protected void updateSequenceNum()
public int getSequenceNum()
public void setLockServerAddress(java.net.InetAddress[] pLockServerAddress)
pLockServerAddress
- new value to setpublic java.net.InetAddress[] getLockServerAddress()
public void setLockServerPort(int[] pLockServerPort)
pLockServerPort
- new value to setpublic int[] getLockServerPort()
public void setLocalAddress(java.net.InetAddress pLocalAddress)
pLocalAddress
- new value to setpublic java.net.InetAddress getLocalAddress()
public void setLocalPort(int pLocalPort)
pLocalPort
- new value to setpublic int getLocalPort()
public void setConnectTimeout(long pConnectTimeout)
pConnectTimeout
- new value to setpublic long getConnectTimeout()
public void setLockTimeout(long pLockTimeout)
pLockTimeout
- new value to setpublic long getLockTimeout()
public void setLogWarningWhenUnavailable(boolean pLogWarnings)
pLogWarningWhenUnavailable
- new value to setpublic boolean getLogWarningWhenUnavailable()
public boolean isAvailable()
public void setEnablePerformanceMonitor(boolean pEnablePerformanceMonitor)
public boolean isEnablePerformanceMonitor()
public void setUseLockServer(boolean pUseLockServer)
pUseLockServer
- new value to setpublic boolean getUseLockServer()
public void setCheckForDeadlocks(boolean pCheckForDeadlocks)
pCheckForDeadlocks
- new value to setpublic boolean getCheckForDeadlocks()
public void setCropOwnerString(boolean pCropOwnerString)
public boolean isCropOwnerString()
public void doStartService() throws ServiceException
GenericService
doStartService
in class GenericService
ServiceException
- if the Service had a problem starting uppublic void closeSocket()
public boolean acquireReadLock(java.io.Serializable pKey, java.lang.Object pOwner) throws DeadlockException
pKey
- the key/name of the lock
DeadlockException
- is thrown if the lock could not be acquired
because a deadlock was detectedpublic boolean hasWriteLock(java.lang.String pKey, java.lang.Object pOwner)
pKey
- the key/name of the lockpOwner
- the owner to checkpublic boolean hasReadLock(java.lang.String pKey, java.lang.Object pOwner)
pKey
- the key/name of the lockpOwner
- the owner to checkpublic boolean acquireReadLock(java.io.Serializable pKey, java.lang.Object pOwner, long pTimeout) throws DeadlockException, TimeExceededException
pKey
- the key/name of the lockpOwner
- the owner for this lockpTimeout
- 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.
DeadlockException
- is thrown if the lock could not be acquired
because a deadlock was detected
TimeExceededException
public boolean acquireWriteLock(java.io.Serializable pKey, java.lang.Object pOwner) throws DeadlockException
pKey
- the key/name of the lockpOwner
- this is an object which identifies the owner of this lock.
DeadlockException
- is thrown if the lock could not be acquired
because a deadlock was detectedpublic boolean acquireWriteLock(java.io.Serializable pKey, java.lang.Object pOwner, long pTimeout) throws DeadlockException, TimeExceededException
pKey
- the key/name of the lockpOwner
- 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.
DeadlockException
- is thrown if the lock could not be acquired
because a deadlock was detected
TimeExceededException
public boolean acquireReadLock(java.io.Serializable pKey) throws DeadlockException
pKey
- the key/name of the lock
DeadlockException
- is thrown if the lock could not be acquired
because a deadlock was detectedpublic boolean acquireWriteLock(java.io.Serializable pKey) throws DeadlockException
pKey
- the key/name of the lock
DeadlockException
- is thrown if the lock could not be acquired
because a deadlock was detectedpublic void releaseReadLock(java.io.Serializable pKey, java.lang.Object pOwner) throws LockManagerException
pKey
- the key to releasepOwner
- the identify of the owner of this lock
LockManagerException
- is thrown if the lock was not owned
by this owner.public void releaseReadLock(java.io.Serializable pKey, java.lang.Object pOwner, boolean pOnlyIfOwned) throws LockManagerException
pKey
- the key to releasepOwner
- the identify of the owner of this lockpOnlyIfOwned
- 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.
LockManagerException
- is thrown if the lock was not owned
by this owner.public void releaseReadLock(java.io.Serializable pKey, java.lang.Object pOwner, boolean pOnlyIfOwned, boolean pKeepProcessOwnership) throws LockManagerException
pKey
- the key to releasepOwner
- the identify of the owner of this lockpOnlyIfOwned
- 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.
LockManagerException
- is thrown if the lock was not owned
by this owner.public void releaseWriteLock(java.io.Serializable pKey, java.lang.Object pOwner) throws LockManagerException
pKey
- the key to be released
LockManagerException
- is thrown if the lock fails be releasedpublic void releaseWriteLock(java.io.Serializable pKey, java.lang.Object pOwner, boolean pOnlyIfOwned) throws LockManagerException
pKey
- the key to be releasedpOwner
- the identity of the owner of the lockpOnlyIfOwned
- 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.
LockManagerException
- is thrown if the lock fails be releasedpublic void releaseWriteLock(java.io.Serializable pKey, java.lang.Object pOwner, boolean pOnlyIfOwned, boolean pKeepProcessOwnership) throws LockManagerException
pKey
- the key to be releasedpOwner
- the identity of the owner of the lockpOnlyIfOwned
- 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.
LockManagerException
- is thrown if the lock fails be releasedpublic void releaseReadLock(java.io.Serializable pKey) throws LockManagerException
pKey
- the key to be released
LockManagerException
- is thrown if the lock fails be releasedpublic void releaseWriteLock(java.io.Serializable pKey) throws LockManagerException
pKey
- the key to be released
LockManagerException
- is thrown if the lock fails be releasedpublic boolean convertReadToWrite(java.io.Serializable pKey, java.lang.Object pOwner) throws DeadlockException, LockManagerException
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.public boolean convertReadToWrite(java.io.Serializable pKey) throws DeadlockException, LockManagerException
This version uses the current thread as the owner of the lock.
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.public void giveUpOwnership(java.io.Serializable pKey)
public boolean isLocallyLocked(java.lang.Object pKey)
public void addLockOwnershipListener(atg.service.lockmanager.LockOwnershipListener pListener)
public void removeLockOwnershipListener(atg.service.lockmanager.LockOwnershipListener pListener)
public void run()
run
in interface java.lang.Runnable
public atg.service.lockmanager.LockOwnerTable getLockOwnerTable()
public int getLockOwnerTableSize()
protected javax.servlet.Servlet createAdminServlet()
createAdminServlet
in class GenericService
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |