public interface Leasing
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
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.
|Modifier and Type||Interface and Description|
Helper class for building lease owner identity from
|Modifier and Type||Method and Description|
Registers interest in claiming ownership of a lease for this server whenever it becomes available.
Add a LeaseLostListener.
Returns a list of the servers that have consistently missed sending heartbeats in a timely manner, AND have gone past their grace period.
Returns the identity of the server that currently owns the lease.
If the lease is owned by this server, attempts to give up ownership.
Removes the lease with leaseName from the outstanding leases set
Remove a LeaseLostListener.
Attempts to claim immediate ownership of a lease for this server.
Try to relinquish all leases owned by a given server.
boolean tryAcquire(java.lang.String leaseName) throws LeasingException
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.
void acquire(java.lang.String leaseName, LeaseObtainedListener listener) throws LeasingException
LeaseObtainedListener. Notification occurs (again) if the lease is already owned by this server.
LeasingException- if this server is already waiting to get the lease (through a previous call to lease()). Will callback via
LeaseObtainedListenerwith 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.
void release(java.lang.String leaseName) throws LeasingException
Leasing.acquire(java.lang.String, weblogic.cluster.singleton.LeaseObtainedListener)), cancels the registration. Otherwise does nothing.
LeasingException- if infrastructure problems make it impossible to access the lease.
void removeFromOutStandingLeasesSet(java.lang.String leaseName)
java.lang.String findOwner(java.lang.String leaseName) throws LeasingException
LeasingException- if infrastructure problems make it impossible to determine who owns the lease.
void addLeaseLostListener(LeaseLostListener listener)
void removeLeaseLostListener(LeaseLostListener listener)
Leasing services also include a method
Leasing.findExpiredLeases() that returns a list of all servers in the
cluster that have consistently missed sending heartbeats in a
timely manner. INVARIANT: If a server stops heartbeating
PERMANENTLY, then it will EVENTUALLY be returned
in this list, although there is no guarantee as to how long that
will take. This method might be used by a centralized control
process, such as a Cluster Master, to migrate failed servers.
void voidLeases(java.lang.String owner)
owner- Name of the server whose leases should be voided