weblogic.cluster.singleton
Interface Leasing

All Known Implementing Classes:

LeaseManager

public interface Leasing

The Leasing interface provides access to leasing services, which allow servers in the cluster to gain exclusive ownership over named entities. It is implemented by the LeaseManager. Two basic leasing modes are provided. In the "one-shot" mode, offered by Leasing.tryAcquire(java.lang.String), the caller is immediately informed whether or not the lease was claimed. If not, there is no further action. As an example, this mode might be used to attempt to claim ownership of a multi-party conversation. In this case, if the lease was not claimed, the caller might use Leasing.findOwner(java.lang.String) to find the owner and then route requests to it. In the "continuous" mode, offered by Leasing.acquire(java.lang.String, weblogic.cluster.singleton.LeaseObtainedListener), interest is registered in claiming ownership of the lease whenever it becomes available. Successful claiming of the lease is signalled through a LeaseObtainedListener. As an example, this mode might be used to ensure that (more or less) one server in the cluster takes on the role of the Cluster Master. To accomplish this, all servers register interest in claiming a lease named "ClusterMaster" and one of them wins at a time.

The reason this is called a leasing service, rather than a locking service, is that ownership is maintained through some kind of distributed heartbeat. (The LeasingBasis interface allows different implementations of heartbeating to be plugged in.) As a consequence, it is possible that process freezing or network partitioning may lead to a lease being unexpectedly lost by a server. To help prevent Split-Brain Syndrome, the leasing interface provides callbacks to listeners when the local server misses sending a heartbeat in a timely manner. INVARIANT: If ANY heartbeat was missed by the server, a HeartbeatsMissedListener callback will EVENTUALLY occur, although there is no guarantee as to how long that will take.

The assumption is that heartbeats are server-wide and that any of the leases owned by the server may have been lost when such a callback occurs. The Leasing infrastructure does not attempt to determine which leases were actually lost, since the corresponding actions may vary widely. For example, a server might shut itself down in which case no additional loading of the system should be incurred finding out exactly what happened. Alternatively, a server might use the Leasing.findOwner(java.lang.String) method to determine which of its leases were lost and handle them individually. In any case, the server must take corrective action as soon as possible when it loses a lease. Other servers will wait a grace period before claiming leases owned by a seemingly-failed server. The longer the grace period, the smaller the window during which Split-Brain Syndrome can occur.

tryAcquire

boolean tryAcquire(String leaseName)
                   throws LeasingException

Attempts to claim immediate ownership of a lease for this server. Returns true if the lease was successfully claimed or if it is already owned by the server. Returns false if the lease is owned by another server.

Throws:

LeasingException - if this server is already waiting to get the lease (through Leasing.acquire(java.lang.String, weblogic.cluster.singleton.LeaseObtainedListener)) or if there were infrastructure problems trying to get ownership.

acquire

void acquire(String leaseName,
             LeaseObtainedListener listener)
             throws LeasingException

Registers interest in claiming ownership of a lease for this server whenever it becomes available. Notification of successful claiming of the lease is provided through the LeaseObtainedListener. Notification occurs (again) if the lease is already owned by this server.

Throws:

LeasingException - if this server is already waiting to get the lease (through a previous call to lease()). Will callback via LeaseObtainedListener with an exception if there are infrastructure problems obtaining the lease. This callback will NOT cancel the interest in claiming ownership. The leaser must do so themselves via release.

release

void release(String leaseName)
             throws LeasingException

If the lease is owned by this server, attempts to give up ownership. If this server is waiting to get the lease (through Leasing.acquire(java.lang.String, weblogic.cluster.singleton.LeaseObtainedListener)), cancels the registration. Otherwise does nothing.

Throws:

LeasingException - if infrastructure problems make it impossible to access the lease.

findOwner

String findOwner(String leaseName)
                 throws LeasingException

Returns the identity of the server that currently owns the lease. Returns null if the lease is not owned. The lease is not considered to be owned if it has been claimed by a server that has missed heartbeats. This is a best-effort result in that the answer may change after the value is returned.

Throws:

LeasingException - if infrastructure problems make it impossible to determine who owns the lease.

addLeaseLostListener

void addLeaseLostListener(LeaseLostListener listener)

Add a LeaseLostListener. Called back if the local server ever loses the lease.

removeLeaseLostListener

void removeLeaseLostListener(LeaseLostListener listener)

Remove a LeaseLostListener.