net.jini.core.lease

Interface Lease

public interface Lease

The Lease interface defines a type of object that is returned to the lease holder and issued by the lease grantor. Particular instances of the Lease type will be created by the grantors of a lease, and returned to the holder of the lease as part of the return value from a call that allocates a leased resource. The call that requests a leased resource will typically include a requested duration for the lease. If the request is for a particular duration, the lease grantor is required to grant a lease of no more than the requested period of time. A lease may be granted for a period of time shorter than that requested.

Since:

1.0

Author:

Sun Microsystems, Inc.

Field Summary

Fields

Modifier and Type	Field and Description
static int	ABSOLUTE The serialized form of the lease will contain the time of expiration stored as an absolute time, represented in terms of milliseconds since the beginning of the epoch.
static long	ANY Used by the requestor to indicate that there is no particular lease time desired, and that the grantor of the lease should supply a time that is most convenient for the grantor.
static int	DURATION The serialized form of the lease will convert the time of lease expiration into a duration (in milliseconds) from the time of serialization.
static long	FOREVER Used to request a lease that never expires.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canBatch(Lease lease) Returns a boolean indicating whether or not the lease given as a parameter can be batched (placed in the same LeaseMap) with the current lease.
void	cancel() Used by the lease holder to indicate that it is no longer interested in the resource or information held by the lease.
LeaseMap	createLeaseMap(long duration) Creates a Map object that can contain leases whose renewal or cancellation can be batched, and adds the current lease to that map.
long	getExpiration() Returns a long that indicates the time that the lease will expire.
int	getSerialFormat() Returns the format that will be used to serialize the lease.
void	renew(long duration) Used to renew a lease for an additional period of time, specified in milliseconds.
void	setSerialFormat(int format) Sets the format to use when serializing the lease.

Field Detail

FOREVER

static final long FOREVER

Used to request a lease that never expires.

See Also:

Constant Field Values

ANY

static final long ANY

Used by the requestor to indicate that there is no particular lease time desired, and that the grantor of the lease should supply a time that is most convenient for the grantor.

See Also:

Constant Field Values

DURATION

static final int DURATION

The serialized form of the lease will convert the time of lease expiration into a duration (in milliseconds) from the time of serialization. This form is best used when transmitting a Lease object from one address space to another (via an RMI call) where it cannot be assumed that the address spaces have synchronized clocks.

See Also:

Constant Field Values

ABSOLUTE

static final int ABSOLUTE

The serialized form of the lease will contain the time of expiration stored as an absolute time, represented in terms of milliseconds since the beginning of the epoch.

See Also:

Constant Field Values

Method Detail

getExpiration

long getExpiration()

Returns a long that indicates the time that the lease will expire. This time is represented as milliseconds from the beginning of the epoch, relative to the local clock.

Returns:

a long that indicates the time that the lease will expire

cancel

void cancel()
            throws UnknownLeaseException,
                   RemoteException

Used by the lease holder to indicate that it is no longer interested in the resource or information held by the lease. If the leased information or resource could cause a callback to the lease holder (or some other object on behalf of the lease holder), the lease grantor should not issue such a callback after the lease has been cancelled. The overall effect of a cancel call is the same as lease expiration, but instead of happening at the end of a pre-agreed duration it happens immediately.

Throws:

UnknownLeaseException - the lease being cancelled is unknown to the lease grantor

RemoteException

renew

void renew(long duration)
           throws LeaseDeniedException,
                  UnknownLeaseException,
                  RemoteException

Used to renew a lease for an additional period of time, specified in milliseconds. This duration is not added to the original lease, but is used to determine a new expiration time for the existing lease. If the renewal is granted this is reflected in value returned by getExpiration. If the renewal fails, the lease is left intact for the same duration that was in force prior to the call to renew.

Parameters:

duration - the requested duration in milliseconds

Throws:

LeaseDeniedException - the lease grantor is unable or unwilling to renew the lease

UnknownLeaseException - the lease being renewed is unknown to the lease grantor

RemoteException

setSerialFormat

void setSerialFormat(int format)

Sets the format to use when serializing the lease.

Parameters:

format - DURATION or ABSOLUTE

See Also:

getSerialFormat()

getSerialFormat

int getSerialFormat()

Returns the format that will be used to serialize the lease.

Returns:

an int representing the serial format value

See Also:

setSerialFormat(int)

createLeaseMap

LeaseMap createLeaseMap(long duration)

Creates a Map object that can contain leases whose renewal or cancellation can be batched, and adds the current lease to that map. The current lease is put in the map with the duration value given by the parameter.

Parameters:

duration - the duration to put into a Long and use as the value for the current lease in the created LeaseMap

Returns:

the created LeaseMap object

canBatch

boolean canBatch(Lease lease)

Returns a boolean indicating whether or not the lease given as a parameter can be batched (placed in the same LeaseMap) with the current lease. Whether or not two Lease objects can be batched is an implementation detail determined by the objects.

Parameters:

lease - the Lease to be evaluated

Returns:

a boolean indicating whether or not the lease given as a parameter can be batched (placed in the same LeaseMap) with the current lease