Summary: Understanding the Lease objects and their functionality. Explains how to work with the various Lease objects within the XAP framework.

Overview

A common issue which arises for distributed applications on a network, is that there may be partial failures of the network or its components. To cope with this problem, there must be a built-in timeout mechanism for components if they have failed, or have become unreachable. The Lease model is GigaSpace's mechanism to automatically timeout a component that is no longer reachable.

Understanding the Lease Model

The essential idea behind a lease is fairly simple.

  • When creating a resource, the requestor creates the resource with a limited life span.
  • The grantor of the resource will then give access for some period of time that is no longer than that requested.
  • The period of time that is actually granted is returned to the requestor as part of the Lease object.
  • A holder of a lease can request that a Lease be renewed, or cancel the Lease at any time.
  • Successfully renewing a lease extends the time period during which the lease is in effect.
  • Cancelling the lease drops the lease immediately.

Leases can also be managed by:

  • Specifying the Lease interface constant FOREVER, requests a lease that never expires. When granted such a lease, the grantor is responsible for ensuring that the leased resource is freed when no longer needed.
  • Specifying the Lease interface constant ANY, indicates that no particular lease time is desired and that the grantor of the lease should supply a time that is most convenient for the grantor.
    GigaSpaces converts leases with ANY constant to FOREVER leases.

Space Object Lease

Leases are used for objects written to GigaSpaces cluster. All write operations in the ISpaceProxy interface support Lease functionality. Lease duration is an argument that is passed to the write operations. The write function returns an ILeaseContext object which can be used to manage the Leases.

//create the ISpaceProxy object
ISpaceProxy proxy = GetTestProxy();

MyMessage message1 = new MyMessage();

// Writes the message with 1000 millis/1 sec Lease
ILeaseContext<MyMessage> lease1 = proxy.Write(message1, 1000);     

MyMessage message2 = new MyMessage();

// Writes the message with Default Lease of Lease.FOREVER
ILeaseContext<MyMessage> lease2 = proxy.Write(message2);     

MyMessage message3 = new MyMessage();

// Writes the message with Lease of Lease.FOREVER
ILeaseContext<MyMessage> lease3 = proxy.Write(message3, Lease.FOREVER);

Getting the Lease Expiration Date

The ILease.Expiration property returns the amount of time until the space object expires. In the example below, an object is written to the space with a 10 second expiration value. It then prints the amount of time remaining until the object expires.

getExpiration Example
ISpaceProxy space = new GigaSpacesFactory.FindSpace("/./space");

// Writing object into the space with 10 seconds lease time
ILeaseContext<MyClass> o = space.Write(new MyClass(),10000);
String UID = o.getUID();
System.out.println("Current Date:"+ new Date(System.currentTimeMillis()) + " Lease Expiration Date:" + new Date(o.getExpiration()));
while(true)
{
	long expiredDue = (o.Expiration - System.currentTimeMillis())/1000 ;
	System.out.println("Object "+UID +" Expired in :" + expiredDue+ " seconds");
	if (expiredDue <= 0) break;
	Thread.sleep(1000);
}

Manually Managing Space Object Lease

The ISpaceProxy API returns the ILeaseContext after every write or update operation. Space Object Leases can be renewed or cancelled based on the applications needs.

ILeaseContext<Order> lease;

...
public void writeOrder() {
...
//Save lease from write operation
lease = space.Write(singleOrder);
...

public void cancelLease() {
...
lease.Cancel();

Another alternative to using the ILeaseContext objects is to retrieve the objects and update the Lease to desired duration.

//Retrieve all processed low priority orders and expire the lease 
Order template = new Order();

template.setType(OrderType.LOW);
template.setProcessed(true);

Order[] processedLowPriorityOrders = spaceProxy.ReadMultiple(template, 1000);

//Update the lease to expire in 1 second
space.WriteMultiple(processedLowPriorityOrders, 
                1000,				  // Update the Lease to 1 second
		UpdateModifiers.UPDATE_OR_WRITE); // Update existing object
GigaSpaces.com - Legal Notice - 3rd Party Licenses - Site Map - API Docs - Forum - Downloads - Blog - White Papers - Contact Tech Writing - Gen. by Atlassian Confluence