`
`THE JINI DISTRIBUTED LEASING SPECIFICATION
`
`143
`
`long getExpirationC);
`void cancel 0 throws UnknownLeaseException,
`RemoteException;
`void renew(long duration) throws LeaseDeniedException,
`UnknownLeaseException,
`RemoteException:
`
`void setSerialFormatCint format);
`int getSerialFormati);
`
`LeaseMap createLeaseMap(long duration);
`boolean canBatchCLease 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 part 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
`penodtfthneshonerthanthatrequemed.
`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
`
`
`
`
`minions-aw.
`
`
`156
`
`
`
`,___——-.
`
`__
`
`144
`
`BASIC OPERATIONS
`
`compare the expiration time of the leaSe with the result of a call to obtain the cur-
`rent time, java. lang . System . currentTimeMill is .
`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 prc-agreed
`duration, it happens immediately. If the lease being cancelled is unknown to the
`lease grantor, an UnknownLeaseExcept-ion is thrown. The method can also threw
`a RemoteExcepti 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 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
`RenewFai 1 ed Exception 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 UnknownLeaseExcepti on is thrown.
`The method can also throw a RemoteExcept-ion 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, setSeri al 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 format 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, getSeri‘al Fo rm, 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, batchw-i th (Lease lease), returns a boolean value
`indicating whether or not the lease given as an argument to the method can be
`
`i
`
`
`
`157
`
`157
`
`
`
`THE JINI DISTRIBUTED LEASING SPECIFICATION
`
`I45
`
`JG
`
`f:CD
`CDin_D
`5
`
`('31)
`
`batched (in renew and cancel calls) with the current lease. Whether or not tw0
`Lease objects can be batched is an implementation detail determined by the
`Objects.
`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 leased resource.
`The RemoteException is imported from the package java. rmi . 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~
`[ual machines. The full specification of this exception can be found in the Java
`Remote Method Invocation Specification.
`The UnknownLeaseException n usedtoindnxnethatthe Leasecfljectused
`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 excep—
`tmnfimfimdmz
`
`package net.jini.core.lease;
`
`public class UnknownLeaseException extends LeaseException {
`public UnknoWnLeaseExceptionO {
`super();
`
`} p
`
`}
`
`ublic UnknownLeaseExceptionCString reason) {
`superCreason);
`
`} T
`
`he final exception defined is the LeaseDeniedException. 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.core.lease;
`
`public class LeaseDeniedException extends LeaseException {
`public LeaseDeniedExceptionO {
`superC);
`
`} p
`
`}
`
`ublic LeaseDeniedException(String reason) {
`superCreason);
`
`158
`
`158
`
`
`
`146
`
`BASIC OPERA flows
`
`The LeaseExcepti on superciass is defined as:
`
`package net. ji ni . core . l ease;
`
`public class LeaseException extends Exception {
`public LeaseExceptionO {
`super();
`
`} p
`
`}
`
`ublic LeaseExceptionCString 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.j1‘ni .core.lease;
`
`import java. rmi .RemoteException;
`
`public interface LeaseMap extends java.util.Map -[
`boolean canContainKeyCObject key);
`void renewAllO throws LeaseMapException, RemoteException;
`void cancelA'l'lO throws LeaseMapException,RemoteException;
`
`}
`
`A LeaseMap is an extension of the java. util .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'l 5e will cause an 11 l egalArgumentExcepti 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, canContainKey, takes a
`
`Lease object as an argument and returns t rue if that Lease object can be added to
`the Map and 'Fa'l se 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, renewAl 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
`
`159
`
`
`
`
`
`THE JINI DISTRIBUTED LEASING SPECIFICATION
`
`147
`
`Lease objects fail to renew, those objects will be removed from the LeaseMap and
`will be contained in the thrown LeaseMapExcepti on.
`The third method, cancelAll, cancels all the Lease objects in the LeaseMap.
`If all cancels are successful, the method returns normally and leaves all leases in
`the map. If any of the Lease objects cannot be cancelled, they are removed from
`the LeaseMap and the operation throws a LeaseMapExcepti on.
`The LeaseMapException class is defined as:
`
`package net.jini .core.lease;
`
`import java.util.Map;
`
`public class LeaseMapException extends LeaseException {
`public Map exceptionMap;
`public LeaseMapExceptionCString 5, Map exceptionMap)
`super(s);
`
`{
`
`this.exceptionMap = exceptionMap;
`
`}
`
`that maps Lease
`Objects of type LeaseMapException contain a Map object
`objects (the keys) to Exception objects (the values). The Lease objects are the
`ones that could not be renewed or cancelled, and the Exception objects reflect the
`individual failures. For example, if a LeaseMap. 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 UnknownLeaseExcepti 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
`
` Wm.wmaIMFW-mnzm
`
`
`160
`
`160
`
`
`
`] 48
`
`.S'Ema ”ZED FORMS
`
`_Y_
`
`of many minutes is a common occurrence. Because of this, the leasing specifica-
`tbnhficmmmnoumdumnmmrmmnflmnmmdumnme
`
`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.
`
`Thskdmmdmsmmnmmhdkmoflwwsmdgmmmoflmmsmmho
`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
`theleasc.
`
`LE.2.4 Serialized Forms
`
`
`
`
`
`
` Class ser‘ia'lVersionUID Serialized Fields
`
`LeaseExcepti on
`
`—790227254625749U469L all publtcfieids
`
`Unknown LeaseExcepti on
`
`—29210993305| 1429288L none
`
`LeaseDen'i edExcept‘i on
`
`5704943735577343495L none
`
`
`
`LeaseMapExcepti on 4854893779678486122L none
`
`
`
`161
`
`161
`
`
`
`:
`
`.
`
`
`
`
`
`THE HM DISTRIBUTED LEASING SPECIFICATION
`
`149
`
`
`
`LE.3 Example Supporting Classes
`
`THE 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.
`7
`
`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.
`
`LE.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 requester wants the lease to be renewed until an unde-
`termined time in the future. Alternatively, the lease requester 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.
`1f 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-address 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 LeaseRenew {
`LeaseRenew(Lease toRenew,
`
`i
`
`!
`
`;
`l
`:
`
`5
`,
`
`E
`.
`
`!
`
`i
`
`long renewT'il,
`LeaseExpir‘eListener listener) {Us}
`
`Ll":
`
`
`a:
`Fa
`
`162
`
`162
`
`
`
`
`
`150
`
`A RENEWAI, CLASS
`
`1
`
`1
`1
`
`.
`
`void addRenew£Lease toRenew,
`long renewTil,
`LeaseExpireListener listener) {m}
`long getExpiration(Lease torLease)
`throws UnknownLeaseException {m}
`void setExpirationCLease forLease.long toExpire)
`throws UnknownLeaseException {m}
`void cancel(Lea5e toCancel)
`throws UnknownLeaseException {m}
`
`void setLeaseExpireListener(Lease ForLease,
`LeaseExpireListener listener)
`throws UnknownLeaseException {m}
`void removeLeaseExpireListenerCLease 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 renewTi'l. This returns a LeaseRenew object, which
`will have its own thread of control that will do the lease renewals.
`Once a LeaseRenew object has been created, other leases can be added to the
`set that are renewed by that object using the addRenew 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
`LeaseRenew object, leases that can be batched can be placed into a LeaseMap.
`The duration of a particular lease can be queried by a call to the method
`getExpi ration. This method takes a Lease object and returns the time at which
`that lease will be allowed to expire by the LeaseRenew 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 LeaseRe new object,
`an
`UnknownLeaseExcept‘i on will be thrown. This can happen either when no such
`Lease has ever been given to the LeaseRenew 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 setExpi 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.
`
`
`
`163
`
`163
`
`
`
`
`
`
`
`
`'vz'mfyw:-x:.
`
`
`
`' THE JIM tJrsranoTEo LEASING SPECIFICATION ____
`'
`
`
`If no lease is held by the Leas eRen ew object corresponding to the first argument,
`an UnknownLeaseExcepti on will be thrown.
`A call to cancel will result in the cancellation of the indicated Lease held by
`the LeaseRenew object. Again, if the lease has already expired on that object, an
`UnknownLeaseExcepti 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
`all references to the LeaseRenew object.
`The methods setLeaseExp'i reL'i stener and removeLeaseExpi reLi stener
`allow setting and unsetting the destination of an event handler associated with a
`Particular Lease object held by the Leas eRen ew object. The handler will be called
`if the Lease object expires before the desired duration period is completed. Note
`that one of the properties Of this example is that only one LeaseExp‘i reL-i stener
`can be associated with each Lease.
`
`LE.3.2 A Renewal Service
`
`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 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:
`
`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;
`
`I '
`
`E
`l
`l
`i
`I
`
`:
`i
`
`
`
`164
`
`164
`
`
`
`
`
`152
`
`A RENEWAL SEE was
`
`The first method, renew, is the request to the object to renew a particular lease on
`behalf of the caller. The Lease object
`to be renewed is passed to the
`LeaseRenewServi 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 EventRegist ration 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 LeaseRenewServi ce will grant leases that are
`longer (perhaps significantly longer) than those in the leases that it is renewing. In
`this fashion, the LeaseRenewSe l'V'l ce can act as a concentrator for lease renewal
`messages.
`
`The renew method also takes as parameters a RemoteEventLi stener and
`Marshalledobject objects to be passed to that RemoteEventLi 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, onRenewFai 'I ure, allows the client to register interest in
`the LeaseRenewSe r‘vice being unable to renew the Lease supplied as an argu-
`ment to the call. This call also takes a RemoteEventL‘istener object that is the
`target of the notification, and a Marshal l edObject that will be passed as part of
`the notification. This allows the client to be informed if the LeaseRenewServi 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 LeaseRenewServi ce object, an UnknownLeaseExcepti 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
`LeaseRenewServi ce will cancel both the renewing of the lease and any event reg—
`istrations associated with that lease.
`
`
`
`165
`
`165
`
`
`
`153
`
`FE
`
`Panama“.
`
`166
`
`166
`
`
`
`
`
`
`
`
`E1
`
`allf
`ten
`
`21 d
`kin
`
`E‘
`
`P3":
`Sid
`1.181
`
`wt
`SIS:
`
`[hi
`CV
`
`DE
`
`(1‘6
`1'6
`
`THE JIM DISTRIBUTED EVENT SPECIFICATION defines the distributed event
`programming model used throughout the Jini architecture. These are
`
`generalipurpose events that can be used by any service
`for event notifications. The event. model is specifically
`designed to aiiowfor usefiu‘ third parties that help
`either the sender or receiver ofthe event. As you wiii
`see, the lookup service uses these events to notify
`interested parties of changes to its contents.
`
`A
`
`
`
`167
`
`167
`
`
`
`
`
`
`
` .-..-_ :..-—— , .-.\.,a.gafia e..-.._.
`
`
`
`
`
`
`
`
`
`
`
`.wminm.“.:w..-:
`
`
`
`
`
`
`
`The Jini D1str1buted Event
`Specification
`
`EV.1 Introduction
`
`THE purpose of the distributed event interfaces specified in this document is to
`allow an object in one Java virtual machine (JVM) to register interest in the occur-
`rence of some event occurring in an object in some other JVM, perhaps running on
`a different physical machine, and to receive a notification when an event of that
`kind occurs.
`
`EV.'l.l 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 facet 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 programing is useful in distributed systems, where the
`object reacting to an event is in a different JVM, 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
`
`155
`
`
`
`168
`
`168
`
`
`
`156
`
`GOA LS AND REQ UIREMENTS
`
`remote objects may arrive in different orders on different clients, or may not arrive
`at all. The time it takes for a notification to arrive may be long {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 sent.
`Unlike the single-address-space notion of an event, a distributed event cannot
`be guaranteed to be delivered in a timely fashiOn. Because of the possibilities 0f
`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 IDKl .2), 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 applications 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:
`o 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
`
`
`
`:..:w«.....-_w...V
`
`
`
`169
`
`169
`
`
`
`
`
`
`
`
`
`
`
`
`
`
`THE JINI DISTRIB UTEIJ EVENT SPECIFICATYON
`
`i
`
`In addition, the fact that the interfaces are designed to be used by Objects in
`different virtual machines, perhaps separated by a network, imposes other require-
`ments, including:
`
`4v 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 particuiar 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-
`tem‘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:
`
`O Java Remote Method Invocation Specification
`
`0 Jim' Distributed Leasing Specification
`
`
`
`“wanna...”:W‘__
`
` 'fiummm'
`
`
`
`
`
`
`
`170
`
`170
`
`
`
`
`
`EV.2 The Basic Interfaces
`
`
`
`159
`
`
`
`THE 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
`receive 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:
`
`0 To show the information needed in any method that allows registration of
`interest in the occurrence of a kind of event in an object
`
`0 To provide an example of an interface that allows the registration of interest
`in such events
`'
`
`e 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-
`
`
`
`liil!
`
`
`
`171
`
`171
`
`
`
`
`
`160
`
`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 Jini Distributed Leasing Specification.
`The basic, concrete objects involved in a distributed event system are:
`
`0 The object that registers interest in an event
`
`9 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