Overview | Package | Class | Use | Tree | Deprecated | Index | Help
|  | BEA Systems, Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

Method Summary
`void` | `acquire(String leaseName, LeaseObtainedListener listener)` Registers interest in claiming ownership of a lease for this server whenever it becomes available.
`void` | `addLeaseLostListener(LeaseLostListener listener)` Add a LeaseLostListener.
`String` | `findOwner(String leaseName)` Returns the identity of the server that currently owns the lease.
`void` | `release(String leaseName)` If the lease is owned by this server, attempts to give up ownership.
`void` | `removeLeaseLostListener(LeaseLostListener listener)` Remove a LeaseLostListener.
`boolean` | `tryAcquire(String leaseName)` Attempts to claim immediate ownership of a lease for this server.

Method Detail

### 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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Documentation is available at http://e-docs.bea.com/wls/docs92 Copyright 2006 BEA Systems Inc.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD