com.opencloud.rhino.facilities.lock

Interface LockFacility

public interface LockFacility

Rhino extension facility which allows an RA entity to obtain distributed lock between cluster nodes.

The LockFacility is made available to an RA entity via the RA configuration properties, under the CONFIG_PROPERTY_NAME key.

Example of how access the lock facility from an RA: ``

import com.opencloud.rhino.facilities.lock.LockFacility;
import javax.slee.resource.ConfigProperties;

public class MyResourceAdapter implements ResourceAdaptor {

    public void raConfigure(ConfigProperties configProperties) {
      ...
      LockFacility lockFacility = null;
      ConfigProperties.Property property = configProperties.getProperty(LockFacility.CONFIG_PROPERTY_NAME);
      if (property != null) {
          lockFacility = (LockFacility) property.getValue();
      }
      ...
    }
    ...
}

Since:

Rhino 2.3.0

Field Summary

Fields

Modifier and Type	Field and Description
static String	CONFIG_PROPERTY_NAME

Method Summary

Modifier and Type	Method and Description
boolean	acquireExclusive(Object lockID) Attempt to acquire an exclusive lock with a default lock acquisition timeout period.
boolean	acquireExclusive(Object lockID, int timeout) Attempt to acquire an exclusive lock within a specified lock acquisition timeout period.
boolean	acquireShared(Object lockID) Attempt to acquire a shared lock with a default lock acquisition timeout period.
boolean	acquireShared(Object lockID, int timeout) Attempt to acquire a shared lock within a specified lock acquisition timeout period.
int	getLocalNodeID() Returns the node ID of the current Rhino node.
LockInfo[]	getNodeLocks() Get locks currently owned by the resource adaptor entity on this node.

Field Detail

CONFIG_PROPERTY_NAME

static final String CONFIG_PROPERTY_NAME

See Also:

Constant Field Values

Method Detail

getLocalNodeID

int getLocalNodeID()

Returns the node ID of the current Rhino node.

acquireExclusive

boolean acquireExclusive(Object lockID)
                  throws IllegalStateException,
                         IllegalArgumentException,
                         TransactionRequiredLocalException,
                         DeadlockException,
                         LockUnavailableException,
                         LockFacilityException

Attempt to acquire an exclusive lock with a default lock acquisition timeout period. The current thread must be associated with a transaction. If this method returns by successfully obtaining the lock, the lock is released when the transaction completes.

Parameters:

lockID - the id of the lock to obtain. This object must implement either Serializable or FastSerializable.

Returns:

true if the lock was obtained, false if the lock could not be obtained. Blocking acquisition attempts always return true.

Throws:

IllegalStateException - if the Rhino node is not in the primary component.

IllegalArgumentException - if the owner or lockID objects are not serialisable.

TransactionRequiredLocalException - if the current thread is not associated with a transaction.

DeadlockException - if acquiring the lock would cause a deadlock.

LockUnavailableException - if the thread’s transaction already owns the lock in this mode, or the timeout expires without acquiring the lock.

LockFacilityException - if the Rhino node leaves the primary component or some other internal error is encountered.

acquireExclusive

boolean acquireExclusive(Object lockID,
                         int timeout)
                  throws IllegalStateException,
                         IllegalArgumentException,
                         TransactionRequiredLocalException,
                         DeadlockException,
                         LockUnavailableException,
                         LockFacilityException

Attempt to acquire an exclusive lock within a specified lock acquisition timeout period. The current thread must be associated with a transaction. If this method returns by successfully obtaining the lock, the lock is released when the transaction completes

Parameters:

lockID - the id of the lock to obtain. This object must implement either Serializable or FastSerializable.

timeout - the acquistion attempt timeout period, measured in milliseconds. This must be greater than or equal to zero. A timeout of zero indicates no blocking. Any other value indicates an operation that will block until the lock is obtained, the timeout expires, or an extraordinary condition is encountered.

Returns:

true if the lock was obtained, false if the lock could not be obtained. Blocking acquisition attempts always return true.

Throws:

IllegalStateException - if the Rhino node is not in the primary component.

IllegalArgumentException - if the owner or lockID objects are not serialisable.

TransactionRequiredLocalException - if the current thread is not associated with a transaction.

DeadlockException - if acquiring the lock would cause a deadlock.

LockUnavailableException - if the thread’s transaction already owns the lock in this mode, or the timeout expires without acquiring the lock.

LockFacilityException - if the Rhino node leaves the primary component or some other internal error is encountered.

acquireShared

boolean acquireShared(Object lockID)
               throws IllegalStateException,
                      IllegalArgumentException,
                      TransactionRequiredLocalException,
                      DeadlockException,
                      LockUnavailableException,
                      LockFacilityException

Attempt to acquire a shared lock with a default lock acquisition timeout period. The current thread must be associated with a transaction. If this method returns by successfully obtaining the lock, the lock is released when the transaction completes

Parameters:

lockID - the id of the lock to obtain. This object must implement either Serializable or FastSerializable.

Returns:

true if the lock was obtained, false if the lock could not be obtained. Blocking acquisition attempts always return true.

Throws:

IllegalStateException - if the Rhino node is not in the primary component.

IllegalArgumentException - if the owner or lockID objects are not serialisable.

TransactionRequiredLocalException - if the current thread is not associated with a transaction.

DeadlockException - if acquiring the lock would cause a deadlock.

LockUnavailableException - if the thread’s transaction already owns the lock in this mode, or the timeout expires without acquiring the lock.

LockFacilityException - if the Rhino node leaves the primary component or some other internal error is encountered.

acquireShared

boolean acquireShared(Object lockID,
                      int timeout)
               throws IllegalStateException,
                      IllegalArgumentException,
                      TransactionRequiredLocalException,
                      DeadlockException,
                      LockUnavailableException,
                      LockFacilityException

Attempt to acquire a shared lock within a specified lock acquisition timeout period. The current thread must be associated with a transaction. If this method returns by successfully obtaining the lock, the lock is released when the transaction completes

Parameters:

lockID - the id of the lock to obtain. This object must implement either Serializable or FastSerializable.

timeout - the acquistion attempt timeout period, measured in milliseconds. This must be greater than or equal to zero. A timeout of zero indicates no blocking. Any other value indicates an operation that will block until the lock is obtained, the timeout expires, or an extraordinary condition is encountered.

Returns:

true if the lock was obtained, false if the lock could not be obtained. Blocking acquisition attempts always return true.

Throws:

IllegalStateException - if the Rhino node is not in the primary component.

IllegalArgumentException - if the owner or lockID objects are not serialisable.

TransactionRequiredLocalException - if the current thread is not associated with a transaction.

DeadlockException - if acquiring the lock would cause a deadlock.

LockUnavailableException - if the thread’s transaction already owns the lock in this mode, or the timeout expires without acquiring the lock.

LockFacilityException - if the Rhino node leaves the primary component or some other internal error is encountered.

getNodeLocks

LockInfo[] getNodeLocks()
                 throws IllegalStateException

Get locks currently owned by the resource adaptor entity on this node.

Returns:

an array of LockInfo objects detailing the locks currently owned by the resource adaptor entity on this node.

Throws:

IllegalStateException - if the lock manager is not in the primary component.