‘THE IINI DISTRIBUTED LEASING SPECIFICAIYON
`
`long getExpiration();
`void cancel() throws UnknownLeaseException,
`RemoteException;
`void renewtlong duration) throws LeaseDeniedException,
`UnknownLeaseException,
`RemoteException;
`
`void setSerialFormatCint format);
`int getSerialFormat();
`
`LeaseMap createLeaseMap(long duration);
`boolean canBatch(Lease lease);
`
`} P
`
`articular instances of the Lease type will be created by the grantors of a
`lease and returned to the holder of the lease as pan of the return value from a call
`that allocates a leased resource. The actual implementation of the object, includ-
`ing the way (if any) in which the Lease object communicates with the grantor of
`the lease, is determined by the lease grantor and is hidden from the lease holder.
`The interface defines two constants that can be used when requesting a lease.
`The first, FOREVER, 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, ANY, is used by the requester
`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.
`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.
`A second pair of constants is used to determine the format used in the serial-
`ized form for a Lease object; in particular, the serialized form that is used to rep-
`resent the time at which the lease expires. If the serialized format is set to the
`value DURATION, 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 Lease object from one address space to another (such as via
`an RMI call) where it cannot be assumed that the address spaces have sufficiently
`synchronized clocks. If the serialized format is set to ABSOLUTE, the time of expi-
`ration will be stored as an absolute time, calculated in terms of milliseconds since
`the beginning of the epoch.
`The first method in the Lease interface, getExpi ration, returns a long that
`indicates the time, relative to the current clock, that the lease will expire. Follow-
`ing the usual convention in the Java programming language, this time is repre-
`sented as milliseconds from the beginning of the epoch, and can be used to
`
`_
`
`156
`
`

`
`BASIC OPERA.TIONS
`
`compare the expiration time of the lease with the result of a call to obtain the cur-
`rent time, java . l ang . System . currentT'i meM'i ll i s.
`The second method, cancel, 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 cancel 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 Unknown LeaseExcept1' on is thrown. The method can also throw
`a RemoteExcept1' on if the implementation of the method requires calling a
`remote object that is the lease holder.
`The third method, renew, 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 returnvalue; 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
`RenewFa1' led Excepti on is thrown. If a renewal fails, the lease is left intact for the
`same duration that was in force prior to the call to renew. If the lease being
`renewed is unknown to the lease grantor, an UnknownLeaseExcept'l on is thrown.
`The method can also throw a RemoteExcept1'on if the implementation of the
`method requires calling a remote object that is the lease holder.
`Two methods are concerned with the serialized format of a Lease object. The
`
`first, setserial Format, takes an integer that indicates the appropriate format to
`use when serializing the format. The current supported formats are a duration for-
`mat that 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 absolute fonnat should be used when serial-
`izing a Lease object for transmission from one machine to another; the durational
`format should be used when storing a Lease 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, get Se r1‘ al Form, returns an integer indicating the
`format that will be used to serialize the Lease object.
`The last two methods are used to aid in the batch renewal or cancellation of a
`
`group of Lease objects. The first of these, createLeaseMap, 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 will be renewed for the duration indi-
`cated by the argument to the method when all of the leases in the LeaseMap are
`renewed. The second method, batchl-H th (Lease lease), returns a boolean value
`indicating whether or not the lease given as an argument to the method can be
`
`157
`
`

`
`1:‘-:»I-1.1angsea1
`__
`
`my JINI DISTRIBUTED LEASING spscmcarron
`
`' batched (in renew and cancel calls) with the current lease. Whether or not two
`_- Lease objects can be batched is an implementation detail determined by the
`Q objects.
`2
`Three types of Exception objects are associated with the basic lease inter-
`face. All of these are used in the Lease interface itself, and two can be used by
`methods that grant access to a [eased resource.
`The RemoteExcept1' on is imported from the package java. run‘. This excep-
`tion 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 vir-
`tual machines. The full specification of this exception can be found in the Java
`Remote Method Invocation Specification.
`The UnknownLeaseExcept'ion is used to indicate that the Lease object used
`is not known to the grantor of the lease. This can occur when a lease expires, or
`5 when a copy of a lease has been cancelled by some other lease holder. This excep-
`.' tion is defined as:
`
`package net .j'in1' . core . lease;
`
`public class UnknownLeaseExcept'i on extends LeaseExcept'i on {
`public UnknownLeaseException()
`{
`super();
`
`} p
`
`}
`
`ublic UnknownLeaseException(String reason) {
`super(reason);
`
`} T
`
`he final exception defined is the LeaseDen'iedExcept1' on, which can be
`thrown by either a call to renew 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:
`
`package net.jini.ccre.lease;
`
`public cl ass Lea5eDen1'edExcept1' on extends LeaseExcept1' on {
`public LeaseDeniedException() {
`supertf);
`
`} p
`
`}
`
`ublic LeaseDen'i edExcept1' on (Stri ng reason) {
`super(reason):
`
`158
`
`

`
`BASIC OPERATIONS
`
`The LeaseExcept1' on superclass is defined as:
`
`package net. ji n'i . core. lease;
`
`public cl ass LeaseExcept'ion extends Exception {
`public Lea5eExcept1'onO {
`5uper();
`
`} p
`
`}
`
`ublic LeaseExcept1' on (St r1" ng reason) {
`super(reason);
`
`} T
`
`he final basic interface defined for leasing is that of a LeaseMap, which
`allows groups of Lease objects to be renewed or cancelled using a single opera-
`tion. The LeaseMap interface is:
`
`package net . jini . core. "I ease ;
`
`impo rt java. rmi . RemoteExcept-i on;
`
`public ‘interface LeaseMap extends java.ut'i'|.Map -[
`boolean canConta'inKey(0bject key);
`void renewA'|'l()
`throws Lease-MapExcept1'on, RemoteExcep1:1'on;
`void cance1A'|lO throws LeaseMapExcept'lon,RemoteExcept'ion;
`
`}
`
`A LeaseMap is an extension of the java. ut1'l .Map class that associates a Lease
`object with a Long. The Long is the duration for which the lease should be
`renewed whenever it is renewed. Lease objects and associated renewal durations
`can be entered and removed from a LeaseMap using the usual Map methods. An
`attempt to add a Lease object to a map containing other Lease objects for which
`Lease . canBatch would return fa'| se will cause an I'l'| egalArgumentExcept1' on
`to be thrown, as will attempts to add a key that is not a Lease object or a value that
`is not a Long.
`The first method defined in the LeaseMap interface, cancontai nl(ey, takes a
`
`Lease object as an argument and returns true if that Lease object can be added to
`the Map and false otherwise. A Lease object can be added to a Map if that Lease
`object can be renewed in a batch with the other objects in the LeaseMap. The
`requirements for this depends on the implementation of the Lease object.
`The second method, renewA'| 1, will attempt to renew all of the Lease objects
`in the LeaseMap for the duration associated with the Lease object. If all of the
`Lease objects are successfully renewed, the method will return nothing. If some
`
`159
`
`

`
`JINI DISTRIBUTED LEASING SPECIFICATION
`
`"I Lease objects fail to renew, those objects will be removed from the Leas ell-lap and
`-Win be contained in the thrown Lea5eMapExcepti on.
`The third method, cancelAll, cancels all the Lease objects in the LeaseMap.
`all cancels are successful, the method returns normally and leaves all leases in
`._the map I_f any of the Lease objects cannot be cancelled, they are removed from
`I the 1_easeMap and the operation throws a LeaseMapExcepti on.
`.The LeaseMapException class is defined as:
`
`I
`
`package net.jini .cor'e. lease;
`
`“import java.util.Map;
`
`public class LeaseMapException extends LeaseException {
`public Map exceptionMap;
`public LeaseMapException(5tring 5, Map exceptionnap) {
`super(s):
`
`this.exceptionMap = exceptionMap;
`
`}
`:Objects of type LeaseMapException contain a Map object that maps Lease
`objects (the keys) to Exception objects (the values). The Lease objects are the
`ones that could not be renewed or cancelled, and the Excepti on objects reflect the
`-- individual failures. For example, if a Leasel-1ap. renew call fails because one of
`“the leases has already expired, that lease would be taken out of the original
`LeaseMap and placed in the Map returned as part of the LeaseMapException
`object with an Unknown LeaseExcept1' on object as the corresponding value.
`
`'LE.2.3 Leasing and Time
`
`. -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.
`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.
`'
`'
`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
`
`El'1J
`
`Ii;'i1tisn'.:r_]_
`
`160
`
`

`
`SERIALIZED FORMS
`
`of many minutes is a common occurrence. Because of this, the leasing specifica-
`tion has chosen to use durations rather than absolute time.
`
`The reasoning behind such a choice is based on the observation that the accu-
`racy 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 abso-
`lute time would be much easier), that difference is not cumulative in the way
`errors in absolute time are.
`
`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 and the time at which the lease holder
`
`requested the lease, not on the duration and the time that the lease holder received
`the lease.
`
`LE.2.4 Serialized Forms
`
`Class
`
`ser-i a1 Var-s-Ionum
`
`Serialized Fields
`
`LeaseExcept'i on
`
`—7902272546257490469L all public fields
`
`Unknown LeaseExcept1' on
`
`—2921099330511429288L none
`
`Leas eDeni edExcepti on
`
`5704943735577343495L none
`
`Leas eMapExcept'E on
`
`—4854893779678486122L none
`
`161
`
`

`
`I 1-fig JINIDISTRIBUTED LEASING SPECIFICATION
`
`\v'I!EL‘-'-53;‘Ex.'Y=‘!2CIFi§fi'\‘-'A"I-El.‘-.'\i-Ji"¢'.€E§:.fi":‘.1fi'2Ii‘.'fv£*fi-=$'€\=E
`
`=
`
`7 LE.3 Example Supporting Classes
`
`..TI-IE basic Lease 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 Lease interface) and the party that receives
`the lease.
`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.
`
`l.E.3.1 A Renewal Class
`
`'
`
`-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 unde-
`termined 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.
`If the lease continues to be renewed, the lease holder doesn’t want to be both-
`
`ered 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 using the usual
`inter—add1ess space mechanisms for event notifications, by registering a listener of
`the appropriate type. This functionality can be supplied by a class with an inter-
`face like the following
`'
`
`class Leasekenew {
`LeaseRenew(Lease tokenew,
`
`"long r'enewT'i'| ,
`LeaseExp1'r'eListener' listener) {...}
`
`162
`
`

`
`A RENEWAL crass
`
`void addRenew(Lease toRenew,
`
`long renewTil,
`LeaseExpireListener listener) {m}
`long getExpirationCLease forLease)
`throws UnknownLeaseException {m}
`void setExpiration(Lease forLease,long toExpire)
`throws UnknownLeaseException {m}
`void cancel(Lease tocancel)
`throws UnknownLea5eException {m}
`void setLeaseExpireListener(Lease forLease,
`LeaseExpireListener listener)
`
`throws UnknownLeaseException {m}
`void removeLeaseExpireListener(Lease forLease)
`throws UnknownLeaseException {m}
`
`}
`
`The constructor of this class takes a Lease 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 renewT-il. This returns a LeaseRenew object, which
`will have its own thread of control that will do the lease renewals.
`Once a Leasekenew object has been created, other leases can be added to the
`set that are renewed by that object using the addkenew call. This call takes a
`Lease 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
`Leas eRe new object, leases that can be batched can be placed into a Leas eMap.
`The duration of a particular lease can be queried by a call to the method
`getExp'i ration. This method takes a Lease object and returns the time at which
`that lease will be allowed to expire by the LeaseRe new object. Note that this is dif-
`ferent from the Lease . getExpi ration method, which tells the time at which the
`lease will expire if it is not renewed. If there is no Lease object corresponding to
`the argument for this call being handled by the LeaseRenew object, an
`UnknownLeaseExcept1' on will be thrown. This can happen either when no such
`Lease has ever been given to the Leasekenew object, or when a Lease object that
`has been held has already expired or been cancelled. Notice that since this object
`is assumed to be in the same address space as the object that acquired the lease,
`we can assume that it shares the same clock with that object, and hence can use
`absolute time rather than a duration-based system.
`'
`The se'tExp1' ration method allows the caller to adjust the expiration time of
`any Lease object held by the LeaseRenew object. This method takes as arguments
`the Lease whose time of expiration is to be adjusted and the new expiration time.
`
`
`
`s'Igf«>p'«anw.L>_.|r..At..‘.:.-'—a»o-5»-....w.,M_\--............L...,..2..
`
`
`
`
`
`163
`
`

`
`EDISTR UTED srpacirrijirrbw
`
`If no lease is held by the Leasekenew object corresponding to the first argument,
`Jan Un|<nownLeaseExcepti on will be thrown.
`A call to cancel will result in the cancellation of tlie indicated Lease held by
`the LeaseRenew object. Again, if the lease has already expired on that object, an
`UnknownLeaseExcept1' on 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
`_a]1 references to the LeaseRenew object.
`The methods setLeaseExp'l reL'i stener and removeLeaseExp1' reL1' stener
`a11ow setting and unsetting the destination of an event handler associated with a
`"(Particular Lease object held by the LeaseRenew object. The handler will be called
`jf the Lease object expires before the desired duration period is completed. Note
`that one of the properties of this example is that only one LeaseExp1' reL'i stener
`_can be associated with each Lease.
`
`LE.3.2 A Renewal Service
`
`bbjects 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 deacti-
`vated without fear of losing its lease on some other resource.
`The most straightforward way of accomplishing this is to hand the Lease
`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.
`The interface to such an object might look something like:
`
`I
`
`interface LeaseRenewServ-i ce extends Remote {
`
`EventRegi strati on rene-.w(Lease toRenew,
`long renewT-il ,
`RemoteEventL'i stenter noti 'FyBeforeDrop.
`
`Marshal l ed0bj ect retu rn0nNot1' Fy)
`th rows RemoteExcept'i on ;
`vo'i d onRenewFa'i l u re(Lease toRenew,
`RemcteEventLi stente r toNot'i fy ,
`
`Marshal l edobject return0nNot1' fy)
`throws RemoteException, UnknownLeaseExcept'ion;
`
`164
`
`

`
`A RENEWAL SERVICE
`
`The first method, renew, is the request to the object to renew a particular lease on
`behalf of the caller.
`'I‘l1e Lease object
`to be renewed is passed to the
`Leaseflenewse r'v1' ce 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 synchro-
`nized clocks.
`_
`Requests to renew a Lease are themselves leased. The duration of the lease is
`requested in the duration argument to the renew method, and the actual time of the
`lease is returned as part of the EventRegi str'at1' on return value. While it might
`seem odd to lease the service of renewing other leases, this does not cause an infi-
`nite regress. It is assumed that the LeaseRenewServ1' ce will grant leases that are
`longer (perhaps significantly longer) than those in the leases that it is renewing. In
`this fashion, the Leas eRenew5erv1' ce can act as a concentrator for lease renewal
`messages.
`
`The renew method also takes as parameters a Remo1:eEventLi stener and
`Marshalledobject objects to be passed to that RemoteEventL1' stener. This is
`because part of the semantics of the renew call is to register interest in an event
`that can occur within the LeaseRenewSe rvi ce 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
`LeaseRenewServi ce object before that lease is dropped.
`The second method, onRen ewFa1' "lure, allows the client to register interest in
`the Leasekenewservice being unable to renew the Lease supplied as an argu-
`ment to the call. This call also takes a RemoteEventL'i stener object that is the
`target of the notification, and a Marshal '|edObj ect that will be passed as part of
`the notification. This allows the client to be informed if the LeaseRenewSe r'v1° ce
`
`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 Lease object
`passed into the call, which should be the same as the Lease object that was sup-
`plied in a previous invocation of the method renew. If the Lease is not known to
`the LeaseRenewServ1' ce object, an UnknownLeaseExcept1'on will be thrown.
`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
`LeaseRenewSer'v1' ce will cancel both the renewing of the lease and any event reg-
`istrations associated with that lease.
`
`165
`
`

`
`166
`
`

`
`THE JINI DISTRIBUTED EVENT SPECIFICATION defines the distributed event
`programming model used throughout the Jini architecture. These are
`
`general-purpose events that can be used by any service
`for event notifications. The event model is specifically
`A designed to aiiowfor useful thirdparties that help
`either the sender or receiver of the event. As you will
`see, the lockup service uses these events to notify
`interested parties of changes to its contents.
`
`Q
`
`167
`
`

`
`The J1ni Distributed Event
`
`Specification
`
`in .EV.1 Introduction
`
`T}LB purpose of the distributed event interfaces specified in this document is to
`allow an object in one Java virtual machine (IVM) to register interest in the occur-
`rence of some event occurring in an object in some other IVM, perhaps running on
`a different physical machine, and to receive a notification when an event of that
`kind occurs.
`
`EV.1.1 Distributed Events and Notifications
`
`Programs based on an object that is reacting to a change of state somewhere out-
`side the object are common in a single address space. Such programs are often
`used for interactive applications in which user actions are modeled as events to
`which other objects in the program react." Delivery of such local events can be
`assumed to be well ordered, very fast, predictable, and reliable. Further, the entity
`that is interested in the event can be assumed to always want to know about the
`event as soon as the event has occurred.
`The same style of progrannning is useful in distributed systems, where the
`object reacting to an event is in a difierent IVM, perhaps on a different physical
`machine, from the one on which the event occurred. Just as in the single-JVM
`case,
`the logic of such programs is often reactive, with actions occurring in
`response to some change in state that has occurred elsewhere.
`A distributed event system has a different set of characteristics and require-
`ments than a single-address-space event system. Notifications of events from
`
`168
`
`

`
`GOALS‘ AND REQUIREMENTS
`
`remote objects may arrive in different orders on different clients, or may not arrive
`at all. The time it takes for a no 'fication to arrive may belong (in comparison to
`the time for computation at either the object that generated the notification or the
`object interested in the notification). There may be occasions in which the object
`wishing the event notification does not wish to have that notification as soon as
`possible, but only on some schedule determined by the recipient. There may even
`be times when the object that registered interest in the event is not the object to
`which a notification of the event should be sen .
`Unlike the single—add.ress-space notion of an event, a distributed event cannot
`be guaranteed to be delivered in a timely fas "on. Because of the possibilities of
`network delays or failures, the notification of an event may be delayed indefinitely
`and even lost in the case of a distributed system.
`Indeed, there are times in a distributed system when the object of a notifica-
`tion may actively desire that the notification be delayed. In systems that allow
`object activation (such as is allowed by Java Remote Method Invocation (RMI) in
`the Java Development Kit, version 1.2, commonly called JDKL2), an object might
`wish to be able to find out whether an event occurred but not want that notification
`to cause an activation of the object if it is otherwise quiescent. In such cases, the
`object receiving the event might wish the notification to be delayed until the
`object requests notification delivery, or until the object has been activated for
`some other reason.
`Central to the notion of a distributed notification is the ability to place a third-
`party object between the object that generates the notification and the party that
`ultimately wishes to receive the notification. Such third parties, which can be
`strung together in arbitrary ways, allow ways of offloading notifications from
`objects, implementing various delivery guarantees, storing of notifications until
`needed or desired by a recipient, and the filtering and rerouting of notifications. In
`a distributed system in which full app "cations are made up of components assem-
`bled to produce an overall application, the third party may be more than a filter or
`storage spot for a notification; in such systems it is possible that the third party is
`the final intended destination of the notification.
`
`EV.1.2 Goals and Requirements
`
`The requirements of this set of interfaces are to:
`9 Specify an interface that can be used to send a notification of the occurrence
`
`of the event
`
`0 Specify the information that must be contained in such a notification
`
`169
`
`

`
`THE JINI DISTIRIB UTED EVENT SPECIFICATION
`
`In addition, the fact that the interfaces are designed to be used by objects in
`difierent virtual machines, perhaps separated by a network, imposes other require-
`ments. including:
`
`4» Allowing various degrees of assurance on delivery of a notification
`
`0 Support for different policies of scheduling notification
`
`o Explicitly allowing the interposition of objects that will collect, hold, filter,
`and forward notifications
`
`Notice that there is no requirement for a single interface that can be used to
`‘register interest in a particular kind of event. Given the wide variety of kinds of
`events, the way in which interest in such events can be indicated may vary from
`object to object. This document will talk about a model that lies behind the sys-
`tern's notion of such a registration, but the interfaces that are used to accomplish
`such a registration are not open to general description.
`
`'
`
`EV.1.3 Dependencies
`
`This document relies on the following other specifications:
`
`0 Java Remote Method Invocation Specification
`
`4» Jim’ Distributed Leasing Specification
`
`170
`
`

`
`"_gj1NI DISTRIBUTED EVENTSPECIFICATION
`
`.V.2 The Basic Interfaces
`
`basic interfaces you are about to see define a protocol that can be used by
`"one object to register interest in a kind of state change in another object, and to
`g-eceive a notification of an occurrence of that kind of state change, either directly
`or through some third-party, that is specified by the object at the time of registra-
`tion. The protocol is meant to be as simple as possible. No attempt is made to indi~
`cate the reliability or the timeliness of the notifications; such guarantees are not
`part of the protocol but instead are part of the implementation of the various
`objects involved.
`'
`In particular, the purpose of these interfaces is:
`
`9 To show the information needed in any method that allows registration of
`interest in the occurrence of a kind of event in an object
`
`9 To provide an example of an interface that allows the registration of interest
`in such events
`'
`
`9 To specify an interface that can be used to send a notification of the occur-
`rence of the event
`
`Implicit in the event registration and notification is the idea that events can be
`classified into kinds. Registration of interest indicates the kind of event that is of
`interest. while a notification indicates that an instance of that kind of event has
`occurred.
`
`EV.2.1 Entities Involved
`
`An event is something that happens in an object, corresponding to some change in
`the abstract state of the object. Events are abstract occurrences that are not directly
`observed outside of an object, and might not correspond to a change in the actual
`state of the object that advertises the ability to register interest in the event. How-
`ever, an object may choose to export an identification of a kind of event and allow
`other objects to indicate interest in the occurrence of events of that kind; this indi-
`
`171
`
`

`
`ENTITIES INVOLVED
`
`cates that the abstract state of the object includes the notion of this state changing.
`The information concerning what kinds of events occur within an object can be
`exported in a number of ways, including identifiers for the various events or meth-
`ods allowing registration of interest in that kind of event.
`An object is responsible for identifying the kinds of events that can occur
`within that object, allowing other objects to register interest in the occurrence of
`such events, and generating RemoteEvent objects that are sent as notifications to
`the objects that have registered interest when such events occur.
`Registration of interest is not temporally open ended but is limited to a given
`duration using the notion of a lease. Full specification of the way in which leasing
`is used is contained in the Jim‘ Distributed Leasing Specification.
`The basic, concrete objects involved in a distributed event system are:
`
`0 The object that registers interest in an event
`
`4 The object in which an event occurs (referred to as the event generator)
`
`9 The recipient of event notifications (referred to as a remote event listener)
`
`An event generator is an object that has some kinds of abstract state changes
`that might be of interest to other objects and allows other objects to register inter-
`est in those events. This is the object that will generate notifications when events
`of this kind occur, sending those notifications to the event listeners" that were indi-
`cated as targets in the calls that registered interest in that kind of event.
`A remote event listener is an obj