You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@river.apache.org by bu...@apache.org on 2010/12/24 20:54:37 UTC
svn commit: r781452 [11/17] - in
/websites/staging/river/trunk/content/river/doc/specs/html: ./ images/
Added: websites/staging/river/trunk/content/river/doc/specs/html/lease-spec.html
==============================================================================
--- websites/staging/river/trunk/content/river/doc/specs/html/lease-spec.html (added)
+++ websites/staging/river/trunk/content/river/doc/specs/html/lease-spec.html Fri Dec 24 19:54:36 2010
@@ -0,0 +1,515 @@
+<!--
+ ! Licensed to the Apache Software Foundation (ASF) under one
+ ! or more contributor license agreements. See the NOTICE file
+ ! distributed with this work for additional information
+ ! regarding copyright ownership. The ASF licenses this file
+ ! to you under the Apache License, Version 2.0 (the
+ ! "License"); you may not use this file except in compliance
+ ! with the License. You may obtain a copy of the License at
+ !
+ ! http://www.apache.org/licenses/LICENSE-2.0
+ !
+ ! Unless required by applicable law or agreed to in writing, software
+ ! distributed under the License is distributed on an "AS IS" BASIS,
+ ! WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ ! See the License for the specific language governing permissions and
+ ! limitations under the License.
+ !-->
+
+<html>
+
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<meta name="GENERATOR" content="Quadralay WebWorks Publisher 5.0.4">
+<link rel="StyleSheet" href="standard.css" type="text/css" media="screen">
+<title>Jini Distributed Leasing Specification </title>
+</head>
+
+<body bgcolor="#ffffff">
+
+<a href="#skip" title="Skip navigation bar"></a>
+<table width="90%">
+<tr>
+<td align=left><a href="../../spec-index.html">Spec Index</a></td>
+<td align=right><em>Jini Technology Core Platform Specifications</em></td>
+</tr>
+</table>
+<br clear="all">
+<a name="skip"></a>
+
+
+<hr align="left">
+<table width="90%">
+<tr>
+<td align="right" font size="4"><b>Version 1.0</b></td>
+</tr>
+</table>
+<a name="skip"></a>
+<blockquote>
+<h2 align="left">LE - Jini<font size="-1"><sup>TM</sup></font> Distributed Leasing Specification<br>
+</h2>
+<h3 class="Heading2">
+ <a name="1032977"> </a>LE.1 Introduction
+</h3>
+<p class="Body">
+ The purpose of the leasing interfaces defined in this document is to simplify and unify a particular style of programming for distributed systems and applications. This style, in which a resource is offered by one object in a distributed system and used by a second object in that system, is based on a notion of granting a use to the resource for a certain period of time that is negotiated by the two objects when access to the resource is first requested and given. Such a grant is known as a <em class="Emphasis">lease</em> and is meant to be similar to the notion of a lease used in everyday life. As in everyday life, the negotiation of a lease entails responsibilities and duties for both the grantor of the lease and the holder of the lease. Part of this specification is a detailing of these responsibilities and duties, as well as a discussion of when it is appropriate to use a lease in offering a distributed service.
+</p>
+<p class="Body">
+ <a name="997972"> </a>There is no requirement that the leasing notions defined in this document be the only time-based mechanism used in software. Leases are a part of the programmer's arsenal, and other time-based techniques such as time-to-live, ping intervals, and keep-alives can be useful in particular situations. Leasing is not meant to replace these other techniques, but rather to enhance the set of tools available to the programmer of distributed systems.
+</p>
+<h4 class="Heading3">
+ <a name="1032830"> </a>LE.1.1 Leasing and Distributed Systems
+</h4>
+<p class="Body">
+ <a name="1032831"> </a>Distributed systems differ fundamentally from non-distributed systems in that there are situations in which different parts of a cooperating group are unable to communicate, either because one of the members of the group has crashed or because the connection between the members in the group has failed. This partial failure can happen at any time and can be intermittent or long-lasting.
+</p>
+<p class="Body">
+ <a name="997965"> </a>The possibility of partial failure greatly complicates the construction of distributed systems in which components of the system that are not co-located provide resources or other services to each other. The programming model that is used most often in non-distributed computing, in which resources and services are granted until explicitly freed or given up, is open to failures caused by the inability to successfully make the explicit calls that cancel the use of the resource or system. Failure of this sort of system can result in resources never being freed, in services being delivered long after the recipient of the service has forgotten that the service was requested, and in resource consumption that can grow without bounds.
+</p>
+<p class="Body">
+ <a name="997966"> </a>To avoid these problems, we introduce the notion of a lease. Rather than granting services or resources until that grant has been explicitly cancelled by the party to which the grant was made, a leased resource or service grant is time based. When the time for the lease has expired, the service ends or the resource is freed. The time period for the lease is determined when the lease is first granted, using a request/response form of negotiation between the party wanting the lease and the lease grantor. Leases may be renewed or cancelled before they expire by the holder of the lease, but in the case of no action (or in the case of a network or participant failure), the lease simply expires. When a lease expires, both the holder of the lease and the grantor of the lease know that the service or resource has been reclaimed.
+</p>
+<p class="Body">
+ <a name="997971"> </a>Although the notion of a lease was originally brought into the system as a way of dealing with partial failure, the technique is also useful for dealing with another problem faced by distributed systems. Distributed systems tend to be long-lived. In addition, since distributed systems are often providing resources that are shared by numerous clients in an uncoordinated fashion, such systems are much more difficult to shut down for maintenance purposes than systems that reside on a single machine.
+</p>
+<p class="Body">
+ <a name="997983"> </a>As a consequence of this, distributed systems, especially those with persistent state, are prone to accumulations of outdated and unwanted information. The accumulation of such information, which can include objects stored for future use and subsequently forgotten, may be slow, but the trend is always upward. Over the (comparatively) long life of a distributed system, such unwanted information can grow without upper bound, taking up resources and compromising the performance of the overall system.
+</p>
+<p class="Body">
+ <a name="998064"> </a>A standard way of dealing with these problems is to consider the cleanup of unused resources to be a system administration task. When such resources begin to get scarce, a human administrator is given the task of finding resources that are no longer needed and deleting them. This solution, however, is error prone (since the administrator is often required to judge the use of a resource with no actual evidence about whether or not the resource is being used) and tends to happen only when resource consumption has gotten out of hand.
+</p>
+<p class="Body">
+ <a name="997984"> </a>When such resources are leased, however, this accumulation of out-of-date information does not occur, and resorting to manual cleanup methods is not needed. Information or resources that are leased remain in the system only as long as the lease for that information or resource is renewed. Thus information that is forgotten (through either program error, inadvertence, or system crash) will be deleted after some finite time. Note that this is not the same as garbage collection (although it is related in that it has to do with freeing up resources), since the information that is leased is not of the sort that would generally have any active reference to it. Rather, this is information that is stored for (possible) later retrieval but is no longer of any interest to the party that originally stored the information.
+</p>
+<p class="Body">
+ <a name="997985"> </a>This model of persistence is one that requires renewed proof of interest to maintain the persistence. Information is kept (and resources used) only as long as someone claims that the information is of interest (a claim that is shown by the act of renewing the lease). The interval for which the resource may be consumed without a proof of interest can vary, and is subject to negotiation by the party storing the information (which has expectations for how long it will be interested in the information) and the party in which the information is stored (which has requirements on how long it is willing to store something without proof that some party is interested).
+</p>
+<p class="Body">
+ <a name="997986"> </a>The notion of persistence of information is not one of storing the information on stable storage (although it encompasses that notion). Persistent information, in this case, includes any information that has a lifetime longer than the lifetime of the process in which the request for storage originates.
+</p>
+<p class="Body">
+ <a name="998069"> </a>Leasing also allows a form of programming in which the entity that reserves the information or resource is not the same as the entity that makes use of the information or resource. In such a model, a resource can be reserved (leased) by an entity on the expectation that some other entity will use the resource over some period of time. Rather than having to check back to see if the resource is used (or freed), a leased version of such a reservation allows the entity granted the lease to forget about the resource. Whether used or not, the resource will be freed when the lease has expired.
+</p>
+<p class="Body">
+ <a name="997990"> </a>Leasing such information storage introduces a programming paradigm that is an extension of the model used by most programmers today. The current model is essentially one of infinite leasing, with information being removed from persistent stores only by the active deletion of such information. Databases and filesystems are perhaps the best known exemplars of such stores--both hold any information placed in them until the information is explicitly deleted by some user or program.
+</p>
+<h4 class="Heading3">
+ <a name="997989"> </a>LE.1.2 Goals and Requirements
+</h4>
+<p class="Body">
+ <a name="1033932"> </a>The requirements of this set of interfaces are:
+</p>
+<ul>
+ <li class="SmartList1"><a name="1033933"> </a>To provide a simple way of indicating time-based resource allocation or reservation<p>
+ <li class="SmartList1"><a name="997996"> </a>To provide a uniform way of renewing and cancelling leases <p>
+ <li class="SmartList1"><a name="997997"> </a>To show common patterns of use for interfaces using this set of interfaces
+</ul>
+<p class="Body">
+ <a name="997998"> </a>The goals of this chapter are:
+</p>
+<ul>
+ <li class="SmartList1"><a name="997999"> </a>To describe the notion of a lease and show some of the applications of that notion in distributed computing<p>
+ <li class="SmartList1"><a name="998000"> </a>To show the way in which this notion is used in a distributed system<p>
+ <li class="SmartList1"><a name="998001"> </a>To indicate appropriate uses of the notion in applications built to run in a distributed environment
+</ul>
+<h3 class="Heading2">
+ <a name="1004353"> </a>LE.2 Basic Leasing Interfaces
+</h3>
+<p class="Body">
+ The basic concept of leasing is that access to a resource or the request for some action is not open ended with respect to time, but granted only for some particular interval. In general (although not always), this interval is determined by some negotiation between the object asking for the leased resource (which we will call the lease holder) and the object granting access for some period (which we will call the lease grantor).
+</p>
+<p class="Body">
+ <a name="1032916"> </a>In its most general form, a lease is used to associate a mutually agreed upon time interval with an agreement reached by two objects. The kinds of agreements that can be leased are varied and can include such things as agreements on access to an object (references), agreements for taking future action (event notifications), agreements to supplying persistent storage (file systems, JavaSpaces<font size="-1"><sup>TM</sup></font> systems), or agreements to advertise availability (naming or directory services).
+</p>
+<p class="Body">
+ <a name="1032917"> </a>While it is possible that a lease can be given that provides exclusive access to some resource, this is not required with the notion of leasing being offered here. Agreements that provide access to resources that are intrinsically sharable can have multiple concurrent lease holders. Other resources might decide to grant only exclusive leases, combining the notion of leasing with a concurrency control mechanism.
+</p>
+<h4 class="Heading3">
+ <a name="1032936"> </a>LE.2.1 Characteristics of a Lease
+</h4>
+<p class="Body">
+ <a name="1032937"> </a>There are a number of characteristics that are important for understanding what a lease is and when it is appropriate to use one. Among these characteristics are:
+</p>
+<ul>
+ <li class="SmartList1"><a name="1004359"> </a> A lease is a time period during which the grantor of the lease ensures (to the best of the grantor's abilities) that the holder of the lease will have access to some resource. The time period of the lease can be determined solely by the lease grantor, or can be a period of time that is negotiated between the holder of the lease and the grantor of the lease. Duration negotiation need not be multi-round; it often suffices for the requestor to indicate the time desired and the grantor to return the actual time of grant.<p>
+ <li class="SmartList1"><a name="1032948"> </a>During the period of a lease, a lease can be cancelled by the entity holding the lease. Such a cancellation allows the grantor of the lease to clean up any resources associated with the lease and obliges the grantor of the lease to not take any action involving the lease holder that was part of the agreement that was the subject of the lease.<p>
+ <li class="SmartList1"><a name="1032949"> </a>A lease holder can request that a lease be renewed. The renewal period can be for a different time than the original lease, and is also subject to negotiation with the grantor of the lease. The grantor may renew the lease for the requested period or a shorter period or may refuse to renew the lease at all. However, when renewing a lease the grantor cannot, unless explicitly requested to do so, shorten the duration of the lease so that it expires before it would have if it had not been renewed. A renewed lease is just like any other lease and is itself subject to renewal.<p>
+ <li class="SmartList1"><a name="1004362"> </a>A lease can expire. If a lease period has elapsed with no renewals, the lease expires, and any resources associated with the lease may be freed by the lease grantor. Both the grantor and the holder are obliged to act as though the leased agreement is no longer in force. The expiration of a lease is similar to the cancellation of a lease, except that no communication is necessary between the lease holder and the lease grantor.
+</ul>
+<p class="Body">
+ <a name="1004363"> </a>Leasing is part of a programming model for building reliable distributed applications. In particular, leasing is a way of ensuring that a uniform response to failure, forgetting, or disinterest is guaranteed, allowing agreements to be made that can then be forgotten without the possibility of unbounded resource consumption, and providing a flexible mechanism for duration-based agreement.
+</p>
+<h4 class="Heading3">
+ <a name="1004365"> </a>LE.2.2 Basic Operations
+</h4>
+<p class="Body">
+ <a name="1004366"> </a>The <code>Lease</code> interface defines a type of object that is returned to the lease holder and issued by the lease grantor. The basic interface may be extended in ways that offer more functionality, but the basic interface is:
+<pre class="Preformatted">package net.jini.core.lease;
+
+import java.rmi.RemoteException;
+
+public interface Lease {
+ long FOREVER = Long.MAX_VALUE;
+ long ANY = -1;
+
+ int DURATION = 1;
+ int ABSOLUTE = 2;
+
+ long getExpiration();
+ void cancel() throws UnknownLeaseException,
+ RemoteException;
+ void renew(long duration) throws LeaseDeniedException,
+ UnknownLeaseException,
+ RemoteException;
+ void setSerialFormat(int format);
+ int getSerialFormat();
+ LeaseMap createLeaseMap(long duration);
+ boolean canBatch(Lease lease);
+}
+</pre>
+<p class="Body">
+ <a name="1004381"> </a>Particular instances of the <code>Lease</code> 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 actual implementation of the object, including the way (if any) in which the <code>Lease</code> object communicates with the grantor of the lease, is determined by the lease grantor and is hidden from the lease holder.
+</p>
+<p class="Body">
+ <a name="1004382"> </a>The interface defines two constants that can be used when requesting a lease. The first, <code>FOREVER</code>, can be used to request a lease that never expires. When granted such a lease, the lease holder is responsible for ensuring that the leased resource is freed when no longer needed. The second constant, <code>ANY</code>, is used by the requestor to indicate 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.
+</p>
+<p class="Body">
+ <a name="1004383"> </a>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.
+</p>
+<p class="Body">
+ <a name="1034547"> </a>A second pair of constants is used to determine the format used in the serialized form for a <code>Lease</code> object; in particular, the serialized form that is used to represent the time at which the lease expires. If the serialized format is set to the value <code>DURATION</code>, the serialized form 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 <code>Lease</code> object from one address space to another (such as via an <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">RMI</span> call) where it cannot be assumed that the address spaces have sufficiently synchronized clocks. If the serialized format is set to <code>ABSOLUTE</code>, the time of expiration will be stored as an absolute time, calculated in terms of milliseconds since the beg
inning of the epoch.
+</p>
+<p class="Body">
+ <a name="1004385"> </a>The first method in the <code>Lease</code> interface, <code>getExpiration</code>, returns a <code>long</code> that indicates the time, relative to the current clock, that the lease will expire. Following the usual convention in the Java<font size="-1"><sup>TM</sup></font> programming language, this time is represented as milliseconds from the beginning of the epoch and can be used to compare the expiration time of the lease with the result of a call to obtain the current time, <code>java.lang.System.currentTimeMillis. </code>
+</p>
+<p class="Body">
+ <a name="1004386"> </a>The second method, <code>cancel</code>, can be 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 <code>cancel</code> call is the same as lease expiration, but instead of happening at the end of a pre-agreed duration, it happens immediately. If the lease being cancelled is unknown to the lease grantor, an <code>UnknownLeaseException</code> is thrown. The method can also throw a <code>RemoteException</code> if the implementation of the method requires calling a remote object that is the lease holder.
+</p>
+<p class="Body">
+ <a name="1004387"> </a>The third method, <code>renew</code>, is used to renew a lease for an additional period of time. The length of the desired renewal is given, in milliseconds, in the parameter to the call. This duration is not added to the original lease, but is used to determine a new expiration time for the existing lease. This method has no return value; if the renewal is granted, this is reflected in the lease object on which the call was made. If the lease grantor is unable or unwilling to renew the lease, a <code>LeaseDeniedException</code> is thrown. If a renewal fails, the lease is left intact for the same duration that was in force prior to the call to <code>renew</code>. If the lease being renewed is unknown to the lease grantor, an <code>UnknownLeaseException</code> is thrown. The method can also throw a <code>RemoteException</code> if the implementation of the method requires calling a remote object that is the lease holder.
+</p>
+<p class="Body">
+ <a name="1034332"> </a>As with a call that grants a lease, the duration requested in a <code>renew</code> call need not be honored by the entity granting the lease. A renewal may not be for longer than the duration requested, but the grantor may decide to renew a lease for a period of time that is shorter than the duration requested. However, the new lease cannot have a duration that is shorter than the duration remaining on the lease being renewed unless a shorter duration is specifically requested.
+</p>
+<p class="Body">
+ <a name="1004388"> </a>Two methods are concerned with the serialized format of a <code>Lease</code> object. The first, <code>setSerialFormat</code>, takes an integer that indicates the appropriate format to use when serializing the lease. The current supported formats are a duration format which stores the length of time (from the time of serialization) before the lease expires, and an absolute format, which stores the time (relative to the current clock) that the lease will expire. The duration format should be used when serializing a <code>Lease</code> object for transmission from one machine to another; the absolute format should be used when storing a <code>Lease</code> object on stable store that will be read back later by the same process or machine. The default serialization format is durational. The second method, <code>getSerialFormat</code>, returns an integer indicating the format that will be used to serialize the <code>Lease</code> object.
+</p>
+<p class="Body">
+ <a name="1034344"> </a>The last two methods are used to aid in the batch renewal or cancellation of a group of <code>Lease</code> objects. The first of these, <code>createLeaseMap</code>, creates a <code>Map</code> object that can contain leases whose renewal or cancellation can be batched and adds the current lease to that map. The current lease will be renewed for the duration indicated by the argument to the method when all of the leases in the <code>LeaseMap</code> are renewed. The second method, <code>canBatch</code>, returns a boolean value indicating whether or not the lease given as an argument to the method can be batched (in <code>renew</code> and <code>cancel</code> calls) with the current lease. Whether or not two <code>Lease</code> objects can be batched is an implementation detail determined by the objects. However, if a <code>Lease</code> object can be batched with any other <code>Lease</code> object, the set of objects that can be batched must form an equiv
alence class. That is, the <code>canBatch</code> relationship must be reflexive, symmetric, and associative. This means that, for any three <code>Lease</code> objects <code>x</code>, <code>y</code>, and <code>z</code> that return <code>true</code> for any instance of the <code>canBatch</code> call, it will be the case that:
+</p>
+<ul>
+ <li class="SmartList1"><a name="1034345"> </a><code>x.canBatch(x)</code> is <code>true</code><p>
+ <li class="SmartList1"><a name="1034346"> </a>if <code>x.canBatch(y)</code> is <code>true</code> then <code>y.canBatch(x)</code> is <code>true</code><p>
+ <li class="SmartList1"><a name="1034347"> </a>if x<code>.canBatch(y)</code> is <code>true</code> and <code>y.canBatch(z)</code> is <code>true</code>, then <code>x.canBatch(z) </code>is <code>true</code>
+</ul>
+<p class="Body">
+ <a name="1034454"> </a>In addition to the above methods, an object that implements the <code>Lease</code> interface will probably need to override the <code>equals</code> and <code>hashcode</code> methods inherited from <code>Object</code>. It is likely that such leases, while appearing as local objects, will in fact contain remote references--either explicitly copied or passed via a method call--to implementation-specific objects in the address space of the lease grantor. These local references may even include their own state (such as the expiration time of the lease) that may, over time, vary from the actual expiration time of the lease to which they refer. Two such references should evaluate as equal (and have the same <code>hashcode</code> value) when they refer to the same lease in the grantor, which will not be reflected by the default implementation of the <code>equals</code> method.
+</p>
+<p class="Body">
+ <a name="1004390"> </a>Three types of <code>Exception</code> objects are associated with the basic lease interface. All of these are used in the <code>Lease</code> interface itself, and two can be used by methods that grant access to a leased resource.
+</p>
+<p class="Body">
+ <a name="1004391"> </a>The <code>RemoteException</code> is imported from the package <code>java.rmi</code>. This exception is used to indicate a problem with any communication that might occur between the lease holder and the lease grantor if those objects are in separate virtual machines. The full specification of this exception can be found in the <em class="Emphasis">Java<font size="-1"><sup>TM</sup></font> Remote Method Invocatio</em><em class="Emphasis">n Specification.</em>
+</p>
+<p class="Body">
+ <a name="1004392"> </a>The <code>UnknownLeaseException</code> is used to indicate that the <code>Lease</code> object used is not known to the grantor of the lease. This can occur when a lease expires or when a copy of a lease has been cancelled by some other lease holder. This exception is defined as:
+<pre class="Preformatted">package net.jini.core.lease;
+
+public class UnknownLeaseException extends LeaseException {
+ public UnknownLeaseException() {
+ super();
+ }
+ public UnknownLeaseException(String reason) {
+ super(reason);
+ }
+}
+</pre>
+<p class="Body">
+ <a name="1026994"> </a>The final exception defined is the <code>LeaseDeniedException</code>, which can be thrown by either a call to <code>renew</code> or a call to an interface that grants access to a leased resource. This exception indicates that the requested lease has been denied by the resource holder. The exception is defined as:
+<pre class="Preformatted">package net.jini.core.lease;
+
+public class LeaseDeniedException extends LeaseException {
+ public LeaseDeniedException() {
+ super();
+ }
+ public LeaseDeniedException(String reason) {
+ super(reason);
+ }
+}
+</pre>
+<p class="Body">
+ <a name="1033503"> </a>The <code>LeaseException</code> superclass is defined as:
+<pre class="Preformatted">package net.jini.core.lease;
+
+public class LeaseException extends Exception {
+ public LeaseException() {
+ super();
+ }
+ public LeaseException(String reason) {
+ super(reason);
+ }
+}
+</pre>
+<p class="Body">
+ <a name="1004399"> </a>The final basic interface defined for leasing is that of a <code>LeaseMap</code>, which allows groups of <code>Lease</code> objects to be renewed or cancelled by a single operation. The <code>LeaseMap</code> interface is:
+<pre class="Preformatted">package net.jini.core.lease;
+
+import java.rmi.RemoteException;
+
+public interface LeaseMap extends java.util.Map {
+ boolean canContainKey(Object key);
+ void renewAll() throws LeaseMapException, RemoteException;
+ void cancelAll() throws LeaseMapException,RemoteException;
+}
+</pre>
+<p class="Body">
+ <a name="1034113"> </a>A <code>LeaseMap</code> is an extension of the <code>java.util.Map</code> interface that associates a <code>Lease</code> object with a <code>Long</code>. The <code>Long</code> is the duration for which the lease should be renewed whenever it is renewed. <code>Lease</code> objects and associated renewal durations can be entered and removed from a <code>LeaseMap</code> by the usual <code>Map</code> methods. An attempt to add a <code>Lease</code> object to a map containing other <code>Lease</code> objects for which <code>Lease.canBatch</code> would return <code>false</code> will cause an <code>IllegalArgumentException</code> to be thrown, as will attempts to add a key that is not a <code>Lease</code> object or a value that is not a <code>Long</code>.
+</p>
+<p class="Body">
+ <a name="1034311"> </a>The first method defined in the <code>LeaseMap</code> interface, <code>canContainKey</code>, takes a <code>Lease</code> object as an argument and returns <code>true</code> if that <code>Lease</code> object can be added to the <code>Map</code> and <code>false</code> otherwise. A <code>Lease</code> object can be added to a <code>Map</code> if that <code>Lease</code> object can be renewed in a batch with the other objects in the <code>LeaseMap</code>. The requirements for this depend on the implementation of the <code>Lease</code> object. However, if a <code>LeaseMap</code> object, <code>m</code>, contains a <code>Lease</code> object, <code>n</code>, then for some <code>Lease</code> object <code>o</code>, <code>n.canBatch(o)</code> returns <code>true</code> if and only if <code>m.canContainKey(o)</code> returns <code>true</code>.
+</p>
+<p class="Body">
+ <a name="1004408"> </a>The second method, <code>renewAll</code>, will attempt to renew all of the <code>Lease</code> objects in the <code>LeaseMap</code> for the duration associated with the <code>Lease</code> object. If all of the <code>Lease</code> objects are successfully renewed, the method will return nothing. If some <code>Lease</code> objects fail to renew, those objects will be removed from the <code>LeaseMap</code> and will be contained in the thrown <code>LeaseMapException</code>.
+</p>
+<p class="Body">
+ <a name="1033068"> </a>The third method, <code>cancelAll</code>, cancels all the <code>Lease</code> objects in the <code>LeaseMap</code>. If all cancels are successful, the method returns normally and leaves all leases in the map. If any of the <code>Lease</code> objects cannot be cancelled, they are removed from the <code>LeaseMap</code> and the operation throws a <code>LeaseMapException</code>.
+</p>
+<p class="Body">
+ <a name="1004411"> </a>The <code>LeaseMapException</code> class is defined as:
+<pre class="Preformatted">package net.jini.core.lease;
+
+import java.util.Map;
+
+public class LeaseMapException extends LeaseException {
+ public Map exceptionMap;
+ public LeaseMapException(String s, Map exceptionMap) {
+ super(s);
+ this.exceptionMap = exceptionMap;
+ }
+}
+</pre>
+<p class="Body">
+ <a name="1004418"> </a>Objects of type <code>LeaseMapException</code> contain a <code>Map</code> object that maps <code>Lease</code> objects (the keys) to <code>Exception</code> objects (the values). The <code>Lease</code> objects are the ones that could not be renewed or cancelled, and the <code>Exception</code> objects reflect the individual failures. For example, if a <code>LeaseMap.renew</code> call fails because one of the leases has already expired, that lease would be taken out of the original <code>LeaseMap</code> and placed in the <code>Map</code> returned as part of the <code>LeaseMapException</code> object with an <code>UnknownLeaseException</code> object as the corresponding value.
+</p>
+<h4 class="Heading3">
+ <a name="1004419"> </a>LE.2.3 Leasing and Time
+</h4>
+<p class="Body">
+ <a name="1004420"> </a>The duration of a lease is determined when the lease is granted (or renewed). A lease is granted for a duration rather than until some particular moment of time, since such a grant does not require that the clocks used by the client and the server be synchronized.
+</p>
+<p class="Body">
+ <a name="1004421"> </a>The difficulty of synchronizing clocks in a distributed system is well known. The problem is somewhat more tractable in the case of leases, which are expected to be for periods of minutes to months, as the accuracy of synchronization required is expected to be in terms of minutes rather than nanoseconds. Over a particular local group of machines, a time service could be used that would allow this level of synchronization.
+</p>
+<p class="Body">
+ <a name="1004422"> </a>However, leasing is expected to be used by clients and servers that are widely distributed and might not share a particular time service. In such a case, clock drift of many minutes is a common occurrence. Because of this, the leasing specification has chosen to use durations rather than absolute time.
+</p>
+<p class="Body">
+ <a name="1004423"> </a>The reasoning behind such a choice is based on the observation that the accuracy of the clocks used in the machines that make up a distributed system is matched much more closely than the clocks on those systems. While there may be minutes of difference in the notion of the absolute time held by widely separated systems, there is much less likelihood of a significant difference over the rate of change of time in those systems. While there is clearly some difference in the notion of duration between systems (if there were not, synchronization for absolute time would be much easier), that difference is not cumulative in the way errors in absolute time are.
+</p>
+<p class="Body">
+ <a name="1034585"> </a>This decision does mean that holders of leases and grantors of leases need to be aware of some of the consequences of the use of durations. In particular, the amount of time needed to communicate between the lease holder and the lease grantor, which may vary from call to call, needs to be taken into account when renewing a lease. If a lease holder is calculating the absolute time (relative to the lease holder's clock) at which to ask for a renewal, that time should be based on the sum of the duration of the lease plus the time at which the lease holder requested the lease, not on the duration plus the time at which the lease holder received the lease.
+</p>
+<h4 class="Heading3">
+ <a name="1004425"> </a>LE.2.4 Serialized Forms
+<p>
+<CENTER>
+<table border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000"
+ cellpadding="5" cellspacing="0" summary="serialized forms of the following classes ">
+ <caption></caption>
+ <tr bgcolor="#CCCCCC">
+ <th>Class<br></th>
+ <th>serialVersionUID<br></th>
+ <th>Serialized Fields<br></th>
+ </tr>
+ <tr>
+ <td><code>LeaseException</code><br></td>
+ <td>-7902272546257490469L<br></td>
+<td><em>all public fields</em></td>
+ </tr>
+ <tr>
+ <td><code>UnknownLeaseException</code><br></td>
+ <td>-2921099330511429288L<br></td>
+ <td><em>none</em></td>
+ </tr>
+ <tr>
+ <td><code>LeaseDeniedException</code><br></td>
+ <td>5704943735577343495L<br></td>
+ <td><em>none</em></td>
+ </tr>
+ <tr>
+ <td><code>LeaseMapException</code><br></td>
+ <td>-4854893779678486122L<br></td>
+ <td><em>none</em></td>
+ </tr>
+</table>
+</CENTER>
+
+
+
+</h4>
+<h3 class="Heading2">
+ <a name="1029648"> </a>LE.3 Example Supporting Classes
+</h3>
+<p class="Body">
+ The basic <code>Lease</code> interface allows leases to be granted by one object and handed to another as the result of a call that creates or provides access to some leased resource. The goal of the interface is to allow as much freedom as possible in implementation to both the party that is granting the lease (and thus is giving out the implementation that supports the <code>Lease</code> interface) and the party that receives the lease.
+</p>
+<p class="Body">
+ <a name="1029660"> </a>However, a number of classes can be supplied that can simplify the handling of leases in some common cases. We will describe examples of these supporting classes and show how these classes can be used with leased resources. Please note that complete specifications for such utilities and services do exist and may differ in some degree from these examples.
+</p>
+<h4 class="Heading3">
+ <a name="1004473"> </a>LE.3.1 A Renewal Class
+</h4>
+<p class="Body">
+ <a name="1029670"> </a>One of the common patterns with leasing is for the lease holder to request a lease with the intention of renewing the lease until it is finished with the resource. The period of time during which the resource is needed is unknown at the time of requesting the lease, so the requestor wants the lease to be renewed until an undetermined time in the future. Alternatively, the lease requestor might know how long the lease needs to be held, but the lease holder might be unwilling to grant a lease for the full period of time. Again, the pattern will be to renew the lease for some period of time.
+</p>
+<p class="Body">
+ <a name="1034501"> </a>If the lease continues to be renewed, the lease holder doesn't want to be bothered with knowing about it, but if the lease is not renewed for some reason, the lease holder wants to be notified. Such a notification can be done by using the usual inter-address space mechanisms for event notifications, by registering a listener of the appropriate type. This functionality can be supplied by a class with an interface like the following:
+<pre class="Preformatted">class LeaseRenew {
+ LeaseRenew(Lease toRenew,
+ long renewTil,
+ LeaseExpireListener listener) {...}
+ void addRenew(Lease toRenew,
+ long renewTil,
+ LeaseExpireListener listener) {...}
+ long getExpiration(Lease forLease)
+ throws UnknownLeaseException {...}
+ void setExpiration(Lease forLease,long toExpire)
+ throws UnknownLeaseException {...}
+ void cancel(Lease toCancel)
+ throws UnknownLeaseException {...}
+ void setLeaseExpireListener(Lease forLease,
+ LeaseExpireListener listener)
+ throws UnknownLeaseException {...}
+ void removeLeaseExpireListener(Lease forLease)
+ throws UnknownLeaseException {...}
+}
+</pre>
+<p class="Body">
+ <a name="1033214"> </a>The constructor of this class takes a <code>Lease</code> object, presumably returned from some call that reserved a leased resource; an initial time indicating the time until which the lease should be renewed; and an object that is to be notified if a renewal fails before the time indicated in <code>renewTil</code>. This returns a <code>LeaseRenew</code> object, which will have its own thread of control that will do the lease renewals.
+</p>
+<p class="Body">
+ <a name="1029687"> </a>Once a <code>LeaseRenew</code> object has been created, other leases can be added to the set that are renewed by that object using the <code>addRenew</code> call. This call takes a <code>Lease</code> object, an expiration time or overall duration, and a listener to be informed if the lease cannot be renewed prior to the time requested. Internally to the <code>LeaseRenew</code> object, leases that can be batched can be placed into a <code>LeaseMap</code>.
+</p>
+<p class="Body">
+ <a name="1029688"> </a>The duration of a particular lease can be queried by a call to the method <code>getExpiration</code>. This method takes a <code>Lease</code> object and returns the time at which that lease will be allowed to expire by the <code>LeaseRenew</code> object. Note that this is different from the <code>Lease.getExpiration</code> method, which tells the time at which the lease will expire if it is not renewed. If there is no <code>Lease</code> object corresponding to the argument for this call being handled by the <code>LeaseRenew</code> object, an <code>UnknownLeaseException</code> will be thrown. This can happen either when no such <code>Lease</code> has ever been given to the <code>LeaseRenew</code> object, or when a <code>Lease</code> object that has been held has already expired or been cancelled. Notice that because this object is assumed to be in the same address space as the object that acquired the lease, we can also assume that it shares the same c
lock with that object, and hence can use absolute time rather than a duration-based system.
+</p>
+<p class="Body">
+ <a name="1029689"> </a>The <code>setExpiration</code> method allows the caller to adjust the expiration time of any <code>Lease</code> object held by the <code>LeaseRenew</code> object. This method takes as arguments the <code>Lease</code> whose time of expiration is to be adjusted and the new expiration time. If no lease is held by the <code>LeaseRenew</code> object corresponding to the first argument, an <code>UnknownLeaseException</code> will be thrown.
+</p>
+<p class="Body">
+ <a name="1033231"> </a>A call to <code>cancel</code> will result in the cancellation of the indicated <code>Lease</code> held by the <code>LeaseRenew</code> object. Again, if the lease has already expired on that object, an <code>UnknownLeaseException</code> will be thrown. It is expected that a call to this method will be made if the leased resource is no longer needed, rather than just dropping all references to the <code>LeaseRenew</code> object.
+</p>
+<p class="Body">
+ <a name="1033952"> </a>The methods <code>setLeaseExpireListener</code> and <code>removeLeaseExpireListener</code> allow setting and unsetting the destination of an event handler associated with a particular <code>Lease</code> object held by the <code>LeaseRenew</code> object. The handler will be called if the <code>Lease</code> object expires before the desired duration period is completed. Note that one of the properties of this example is that only one <code>LeaseExpireListener</code> can be associated with each <code>Lease</code>.
+</p>
+<h4 class="Heading3">
+ <a name="1004481"> </a>LE.3.2 A Renewal Service
+</h4>
+<p class="Body">
+ <a name="1029863"> </a>Objects that hold a lease that needs to be renewed may themselves be activatable, and thus unable to ensure that they will be capable of renewing a lease at some particular time in the future (since they might not be active at that time). For such objects it might make sense to hand the lease renewal duty off to a service that could take care of lease renewal for the object, allowing that object to be deactivated without fear of losing its lease on some other resource.
+</p>
+<p class="Body">
+ <a name="1029893"> </a>The most straightforward way of accomplishing this is to hand the <code>Lease</code> object off to some object whose job it is to renew leases on behalf of others. This object will be remote to the objects to which it offers its service (otherwise it would be inactive when the others become inactive) but might be local to the machine; there could even be such services that are located on other machines.
+</p>
+<p class="Body">
+ <a name="1034512"> </a>The interface to such an object might look something like:
+<pre class="Preformatted">interface LeaseRenewService extends Remote {
+ EventRegistration renew(Lease toRenew,
+ long renewTil,
+ RemoteEventListenter notifyBeforeDrop,
+ MarshalledObject returnOnNotify)
+ throws RemoteException;
+ void onRenewFailure(Lease toRenew,
+ RemoteEventListenter toNotify,
+ MarshalledObject returnOnNotify)
+ throws RemoteException, UnknownLeaseException;
+}
+</pre>
+<p class="Body">
+ <a name="1029948"> </a>The first method, <code>renew</code>, is the request to the object to renew a particular lease on behalf of the caller. The <code>Lease</code> object to be renewed is passed to the <code>LeaseRenewService</code> object, along with the length of time for which the lease is to be renewed. Since we are assuming that this service might not be on the same machine as the object that acquired the original lease, we return to a duration-based time system, since we cannot assume that the two systems have synchronized clocks.
+</p>
+<p class="Body">
+ <a name="1029949"> </a>Requests to renew a <code>Lease</code> are themselves leased. The duration of the lease is requested in the duration argument to the <code>renew</code> method, and the actual time of the lease is returned as part of the <code>EventRegistration</code> return value. While it might seem odd to lease the service of renewing other leases, this does not cause an infinite regress. It is assumed that the <code>LeaseRenewService</code> will grant leases that are longer (perhaps significantly longer) than those in the leases that it is renewing. In this fashion, the <code>LeaseRenewService</code> can act as a concentrator for lease renewal messages.
+</p>
+<p class="Body">
+ <a name="1029950"> </a>The <code>renew</code> method also takes as parameters a <code>RemoteEventListener</code> and <code>MarshalledObject</code> objects to be passed to that <code>RemoteEventListener</code>. This is because part of the semantics of the <code>renew</code> call is to register interest in an event that can occur within the <code>LeaseRenewService</code> object. The registration is actually for a notification before the lease granted by the renewal service is dropped. This event notification can be directed back to the object that is the client of the renewal service, and will (if so directed) cause the object to be activated (if it is not already active). This gives the object a chance to renew the lease with the <code>LeaseRenewService</code> object before that lease is dropped.
+</p>
+<p class="Body">
+ <a name="1033965"> </a>The second method, <code>onRenewFailure</code>, allows the client to register interest in the <code>LeaseRenewService</code> being unable to renew the <code>Lease</code> supplied as an argument to the call. This call also takes a <code>RemoteEventListener</code> object that is the target of the notification and a <code>MarshalledObject</code> that will be passed as part of the notification. This allows the client to be informed if the <code>LeaseRenewService</code> is denied a lease renewal during the lease period offered to the client for such renewal. This call does not take a time period for the event registration, but instead will have the same duration as the leased renewal associated with the <code>Lease</code> object passed into the call, which should be the same as the <code>Lease</code> object that was supplied in a previous invocation of the method <code>renew</code>. If the <code>Lease</code> is not known to the <code>LeaseRenewService</co
de> object, an <code>UnknownLeaseException</code> will be thrown.
+</p>
+<p class="Body">
+ <a name="1029952"> </a>There is no need for a method allowing the cancellation of a lease renewal request. Since these requests are themselves leased, cancelling the lease with the <code>LeaseRenewService</code> will cancel both the renewing of the lease and any event registrations associated with that lease.
+</p>
+</p>
+<h3 class="Heading2">
+ <a name="43987"> </a>LE.4 History</h3>
+<p>
+<table align="center" border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000" cellpadding="5" cellspacing="0" summary="history of this specification">
+ <caption><p class="Body">
+ <a name="01887"> </a>
+</p>
+</caption>
+ <tr bgcolor="#CCCCCC">
+ <th>Version</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td valign="top">v1.0
+ </td>
+ <td>Initial release of this specification.
+</td>
+ </tr>
+</table>
+
+<h3 class="Heading2">
+ <a name="0188"> </a> License
+</h3>
+<p>
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+<ul>
+ <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
+</ul>
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+</blockquote>
+
+<hr>
+<a href="#skip" title="Skip navigation bar"></a>
+<table width="100%"><tr>
+<td align=left><a href="../../spec-index.html">Spec Index</a>
+<td align=right><em>Jini Technology Core Platform Specifications</em></td>
+</tr></table>
+<a name="skip"></a>
+
+<hr>
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+<ul>
+ <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a>
+</ul>
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+</body>
+</html>
+
+<!-- This HTML file was initially created with Quadralay WebWorks Publisher 3.5.0 -->
+<!-- by Susan Snyder -->
+<!-- Last updated: 01/27/05 -->