196
`
`THE INTERFACE
`
`will not be longer. The value of the leaseDu rati on argument must be positive,
`Lease.FOREVER,orLease.ANY;oflunwvfie,an.IllegalArgumentException “dfl
`be thrown. Two calls to the createLeaseRenewal Set method will never return
`
`objects that are equal. The set's lease is obtained through a method provided by
`file set
`
`LeaseRenewal Set defines the interface to the sets created by the lease
`renewal service. This interface is not a remote interface. Each implementation of
`the renewal service exports proxy objects that implement the LeaseRenewal Set
`interface local to the client and use an implementation-specific protocol to com-
`municate with the actual remote server. All of the proxy methods obey normal
`RMI remote interface semantics except where explicitly noted. The proxy objects
`for two sets are equal (using the equals method) if they are proxies for the same
`set created by the same renewal service. Any method that communicates with the
`remote server should throw a NoSuchObj ectExcepti on if the set no longer exists.
`If a client receives a NoSuchObjectException from one of the operations on a
`lease renewal set, the client can infer that the set has been destroyed; however, it
`should not infer that the renewal service has been destroyed.
`
`package net.jini.lease;
`
`public interface LeaseRenewalSet {
`
`final public static long RENEWAL_FAILURE_EVENT_ID = 0;
`
`final public static long EXPIRATION_WARNING_EVENT_ID = 1;
`
`public void renewForCLease leaseToRenew,
`
`long desi redDuration,
`
`long
`
`renewDuration)
`
`throws RemoteExcepti on;
`
`public void renewForCLease leaseToRenew,
`
`long desi redDuration)
`
`throws RemoteExcepti on;
`
`public EventRegi strati on setExpi rati onWarni ngLi stener(
`
`RemoteEventLi stener listener,
`
`long
`
`mi nWarni ng,
`
`MarshalledObject
`
`handback)
`
`throws RemoteExcepti on;
`
`public void clearExpi rationWarningLi stenerO
`
`throws RemoteExcepti on;
`
`206
`
`206
`
`

`

`JINI LEASE RENEWAL SER VICE SPECIFICA TION, version 1.1
`
`1 97
`
`public EventRegistration setRenewal FailureListener(
`
`RemoteEventListener listener,
`
`MarshalledObject
`
`handback)
`
`throws RemoteExcepti on;
`
`public void cl earRenewal Fa1' 'I ureLi stenerO
`
`throws RemoteExcepti on;
`
`public Lease remove(Lease 'IeaseToRemove)
`
`throws RemoteExcept'i on;
`
`public Lease[] getLeasesO
`
`throws LeaseUnmarsha'l Exception, RemoteException;
`
`public Lease getRenewalSetLeaseO;
`
`} L
`
`eases can be added to the set through the renewFor methods. There are two
`forms of this method: a three-argument form and a two-argument form. The three-
`argument form will be described first. The leaseToRenew argument specifies the
`lease to be renewed. An 11 l egalArgumentExcepti on will be thrown if the lease
`
`itself. An
`service
`renewal
`expired and was granted by the
`has not
`11 1 egalArgumentExcepti on will also be thrown if the lease is currently a mem-
`ber of another set allocated by the same renewal service. If leaseToRenew is
`ml 1 , a Null Poi nterException will be thrown.
`
`The desi redDu ration parameter is the number of milliseconds that the client
`would like for the client lease to remain in the set. It is used to calculate the client
`
`lease’s desired expiration by adding desi redDu ration to the current time (as
`viewed by the service). If this causes an overflow, a desired expiration of
`Long.MAX_VALUE will be used. Unlike a lease duration, the desired duration is
`
`unilaterally specified by the client, not negotiated between the client and the ser-
`vice. Note that a negative value for desi redDu ration (including Lease . ANY) will
`result in a desired expiration that is in the past. This will cause the client lease to
`be dropped immediately from the set and will not result in an exception. A
`renewal failure event will be generated if and only if the client’s actual expiration
`is before its desired expiration.
`If the actual expiration time of the client lease being added to the set is before
`both the current time (as viewed by the renewal service) and the client lease’s
`desired expiration time, the method will return normally. However, the client lease
`will be dropped from the set, and a renewal failure event will be generated. If the
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`207
`
`207
`
`

`

`198
`
`THE INTERFACE
`
`actual expiration time is before the current time and equal to or after the desired
`expiration time, the method will return normally, the client lease will be dropped
`from the set, and no event will be generated.
`A des1' redDu ran" on of Long . MAX_VALUE does not imply that the client lease
`will remain in the set forever. The client lease will be ejected from the set if the set
`is destroyed, the client lease itself expires, the client lease is removed from the set,
`or the renewal service makes a renewal attempt on the client lease that results in a
`definite exception.
`The renewDu rati on is the renewal duration to associate with the client lease
`
`the
`exactly Long . MAX_VALU E,
`is
`If des1' redDu rati on
`(in milliseconds).
`renewDu rati on may be any positive number or Lease.ANY; otherwise it must be
`a positive number. If these requirements are not met, the renewal service will
`throw an I] l ega'l ArgumentExcepti on.
`
`Calling renewFo r with a lease that is equivalent to a client lease already in the
`set will associate the existing client lease in the set with the new desired duration
`and renew duration. The original copy of the client lease is not replaced with the
`new one. These semantics also allow renewFor‘ to be used in an idempotent fash-
`ion.
`
`The two-argument form of renewFor‘ is equivalent to
`
`renewForCleaseToRenew, desi redDuration, Lease.FOREVER)
`
`Client leases get returned to clients in a number of ways (via remove and
`getLeases calls, as components of events, etc.). The serial format of client leases
`returned to clients may be either Lease . DURATION or Lease.ABSOLUTE. In partic-
`ular it may be necessary to use the Lease .ABSOLUTE format if the implementation
`has access to the client lease only in marshalled form and is unable to unmarshal
`the client lease before sending it to the client.
`Whenever a client lease gets returned to a client, its actual expiration should
`reflect either:
`
`9 The result of the last recorded successful renewal of the client lease per-
`formed by the renewal service; or
`
`o The expiration time the client lease originally had when it was added to the
`set, if the renewal service has been unable to successfully renew the client
`lease and record the result
`
`Although it is impossible for a renewal service to guarantee that all renewal
`attempts will be recorded, persistent implementations should attempt to keep the
`interval between the renewal of a client lease and the logging of the result to a
`minimum.
`
`208
`
`208
`
`

`

`JINI LEASE RENEWAL SER VICE SPECIFICA TION, version 1.1
`
`1 99
`
`Client leases are removed from the set by using the remove method. Removal
`from the set will not cause the lease to be cancelled. The method will return the
`
`lease that is being removed. If the lease is not in the set, nul l will be returned; and
`this call will not be blocked by in-progress renewal attempts. As a result, a client
`lease removed by this method might be renewed after the method has returned.
`Implementations should keep the window where renewals of removed leases
`could occur as small as possible.
`The getLeases method returns all the client leases in the set at the time of the
`
`call, as an array of type Lease. If one or more of the Leases in the array cannot be
`deserialized, a LeaseUnmarshal Exception is thrown.
`
`package net .ji ni .lease;
`
`public class LeaseUnmarshalException extends Exception {
`
`public LeaseUnmarshal Exception(
`
`Lease[]
`
`leases,
`
`MarshalledObject[] marshalledLeases,
`
`ThrowableE]
`
`exceptions) {m}
`
`public LeaseUnmarshalExceptionC
`
`Lease[]
`
`leases,
`
`MarshalledObject[] marshalledLeases,
`
`Throwable[]
`
`exceptions,
`
`String
`
`message) {m}
`
`public Lease[] getLeasesO {...}
`
`public MarshalledObjectE] getMarshalledLeasesO {...}
`
`public ThrowableE] getExceptionsO {...}
`
`} T
`
`he leases that could be successfully deserialized will be returned by the
`getLeases method of the exception. If no leases could be deserialized, a zero-
`length array will be returned. The leases that could not be deserialized will be
`returned in the form of MarshalledObjects by the getMarshalledLeases
`method of the exception. For each element of the array returned by the
`getMarshal l ed Leases method, the corresponding element of the array returned
`by the getExceptions method will hold a Th rowable that indicates why the
`given lease could not be deserialized.
`Throwing a LeaseUnmarshal Exception represents a (possibly transient) fail-
`ure in the ability to unmarshal one or more client leases in the set; it does not nec-
`essarily imply anything about the state of the renewal service or the set that threw
`the exception.
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`209
`
`209
`
`

`

`200
`
`THE INTERFACE
`
`The getRenewal SetLease method of LeaseSet returns the lease associated
`with the set itself. This method does not make a remote call.
`
`LR.2.1 Events
`
`The lease renewal service does not support multiple simultaneous event listener
`registrations for the same kind of event. Although it would be useful in some lim-
`ited circumstances, to do so would require event registrations to be leased sepa-
`rately from the set they are associated with. For the average client of the lease
`renewal service, this ability would increase the number of leases that it would
`have to manage. Since the renewal service is based on the premise that some cli-
`ents have difficulty managing their own leases, increasing the number of leases
`that a client would need to manage could significantly complicate the implemen-
`tation of those clients. Because there can be at most one listener for each kind of
`
`event, a given set provides a set/c1 ear interface instead of the more common
`addL1' stener/removeLi stener or addL1' stener/l ease . cancel interfaces.
`
`The source field of each event generated by a lease renewal service is the
`renewal set that the event is associated with. In the case of an expiration warning
`event, this is the set that is about to expire. In the case of a renewal failure event,
`this is the set the client lease was in when the event occurred. Note that the value
`
`of the source field will in general be a copy of the set in question, the equals
`method will return true for any other copies of the set the client has in its posses-
`sion, but in general it will not be the same object (that is, comparing two sets
`using == will usually return false).
`The event ID LeaseRenewa'l Set.EXPIRATION_WARNING_EVENT_ID is used
`
`for all expiration warning events. One event ID is used because there is only one
`kind of expiration warning event. Similarly, all renewal failure events will have
`the event ID LeaseRenewa'l Set . RENEWAL_FAILURE_EVENT_ID.
`
`Because all of the expiration warning events generated by a given set will
`have the same source and event ID, the sequence number of any given expiration
`warning event generated by the set will be different from the sequence number of
`any other expiration warning event generated by the set. Similarly, the sequence
`number of any renewal failure event generated by a given set will be different
`from the sequence number of any other renewal failure event generated by the set.
`Two different events with the same source and event ID will have different
`
`sequence numbers even if different event registration were in effect when each
`event was generated.
`If a RemoteEventListener registered for a renewal failure or expiration
`warning event throws an Unknown EventExcepti on, this action will only clear the
`specific event registration. It will not cancel the lease on the renewal set or affect
`
`210
`
`210
`
`

`

`JINI LEASE RENEWAL SER VICE SPECIFICA TION, version 1.1
`
`20 1
`
`any other event registration on the set. If the listener throws a bad object excep-
`tion, the renewal service may clear that specific event registration; it will not clear
`any registration associated with other listeners, nor will it cancel the lease on the
`associated renewal set.
`
`If an event listener is replaced and one or more event delivery attempts on the
`original listener failed, implementations may choose to send some or all of these
`events to the new listener.
`
`Event listeners may receive notification of events that they are no longer regis-
`tered to receive, if those events occurred before they were unregistered. Imple-
`mentations should keep the window where such notifications could occur as small
`as possible.
`The setExpi rationWar‘m' ngL1' stener method of LeaseRenewa1 Set allows
`the client to register for notification of the approaching expiration of the set ’s
`lease. Expiration warning events are not generated for client leases. The 1 1' stene r
`argument specifies which listener should be notified when the set’s lease is about
`to expire. The m1' nWarn‘i ng argument specifies the minimum number of millisec-
`onds before set lease expiration that the first event delivery attempt should be
`made by the service. The service may also make subsequent delivery attempts if
`the first and any subsequent attempts resulted in an indefinite exception. The
`mi nWa rn1' ng argument must be zero or a positive number;
`if it
`is not, an
`I1 1 ega1ArgumentExcept1' on must be thrown. If the current expiration of the
`set’s lease is less than mi nWa rn1' ng milliseconds away, the event will occur imme-
`diately (though it will take time to propagate to the handler).
`The handback argument to setExpi rationWar‘m'ngLi stener specifies an
`object that will be part of the expiration warning event notification. This mecha-
`nism is detailed in The Jini Technology Core Platform Specification, “Distributed
`Events
`
`The setEXp'l rationWarm' ngL1' stener method returns the event registration
`for this event. The Lease object associated with the registration will be equivalent
`(in the sense of the equa1s method) to the Lease on the renewal set. Because the
`event registration shares a lease with the set, clients that want to just remove their
`expiration warning registration without destroying the set should use the
`c1earExp1' rati onWarni ngL1' stener method described below, instead of cancel-
`
`ling the registration’s lease. The event ID returned with the registration will be
`LeaseRenewa1 Set . EXPIRATION_WARNING_EVENT_ID. The source of the registra-
`tion will be the set. The method will throw a Nu11Po1'nterExcept1'on if the
`
`11' stene r argument is nu11 . If an event handler has already been specified for this
`event, the current registration is replaced with the new one. Because both registra-
`tions are for the same kind of event, the events sent to the new registration must be
`in the same sequence as the events sent to the old registration.
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`211
`
`211
`
`

`

`202
`
`THE INTERFACE
`
`The clearExpirationWarningListener
`
`rnefluxl of LeaseRenewalSet
`
`removes the event registration currently associated with the approaching expira-
`tion of the set’s lease. It is acceptable to call this method even if there is no active
`registration.
`ThesetRenewalFailureListenerrnefluxlofLeaseRenewalSetaHowsthe
`
`client to register for the event associated with the failure to renew a client lease in
`the set. These events are generated when a client lease in the set reaches its actual
`expiration before its desired expiration or when the service attempts to renew a
`client lease and gets a definite exception. The listener argument specifies the
`listener to be notified if a client lease could not be renewed.
`
`ThehandbackangnnmfitosetRenewalFailureListenerspanfiesanobfimt
`that will be part of the renewal failure event notification. This mechanism is
`detailed in The Jim' Technology Core Platform Specification,
`“Distributed
`Evenm”.
`
`The setRenewal Fai l ureLi stener method returns the event registration for
`this event. The Lease object associated with the registration will be equivalent (in
`the sense of the equals method) to the Lease on the renewal set. Because the
`event registration shares a lease with the set, clients that want to just remove their
`expiration warning registration without destroying the set should use the
`cl ea rRenewal Fai l u re Li stene r method (described below) instead of cancelling
`the registration’s lease. The registration ID returned with the registration will be
`LeaseRenewalSet.RENEWAL_FAILURE_EVENT_ID.Thesounx30ftheregfifiafion
`\vfllbetheset'ThernmhodxvfllflnoulNullPointerExceptionifthelistener
`
`argument is null . If an event handler has already been specified for this event, the
`current registration is replaced with the new one. Because both registrations are
`for the same kind of event, the events sent to the new registration must be in the
`same sequence as the events sent to the old registration.
`The cl earRenewal Fai l ureLi stener method of LeaseRenewal Set removes
`
`the event registration currently associated with the failure to renew client leases. It
`is acceptable to call this method even if there is no active registration.
`
`package net.jini.lease;
`
`public class ExpirationWarningEvent extends RemoteEvent {
`
`public ExpirationWarningEvent(
`
`LeaseRenewalSet
`
`source,
`
`long
`
`seqNum,
`
`MarshalledObject handback)
`
`{m}
`
`public Lease getRenewalSetLeaseC)
`
`{m}
`
`212
`
`212
`
`

`

`JINI LEASE RENEWAL SER VICE SPECIFICA TION, version 1.1
`
`203
`
`Expi rati onWarni ngEvent objects are passed to the event handlers specified
`incaflstotheLeaseRenewalSetrnmhod,setExpirationWarningListener.The
`
`Expi rationWarni ngEvent is a subclass of RemoteEvent and adds no additional
`
`state. Because the source of a Expi rati onWarni ngEvent is the set that is about to
`
`expire, the lease that needs to be renewed can be obtained by: calling getSou rce,
`casting the result
`to a LeaseRenewal Set
`and then invoking the
`set’s
`getRenewalSetLease nufihod.11K:convmnenceinefluxlgetRenewalSetLease
`
`in Expi rati onWarni ngEvent uses this technique to retrieve the lease on the set.
`The Lease object returned will be equivalent (in the sense of the equals method)
`to other Lease objects associated with the set but may not be the same object. One
`notable consequence of having two different objects is that the getExpi ration
`method of the Lease object returned by the event’s getRenewal SetLease method
`may return a different time than the getExpi ration methods of other Lease
`objects granted on the same set.
`The expiration time associated with the Lease object returned by the
`getRenewal Set Lease method will reflect the expiration the lease had when the
`event occurred. Renewal calls may have changed the expiration time of the under-
`lying lease between the time when the event was generated and when it was deliv-
`ered.
`
`Other aspects of the event’s state are described in The Jinz' Technology Core
`Platform Specification, “Distributed Events
`Sequence numbers for a given
`event ID are increasing. If there is no gap between two sequence numbers, no
`events have been missed; if there is a gap, events might (but might not) have been
`nfissed.
`
`package net .ji ni .lease;
`
`public abstract class RenewalFailureEvent
`extends RemoteEvent
`
`{
`
`public RenewalFailureEventCLeaseRenewalSet
`
`source,
`
`long
`
`seqNum,
`
`MarshalledObject handback)
`
`{m}
`
`abstract public Lease getLeaseC)
`
`throws IOException, ClassNotFoundException;
`
`abstract public Throwable getThrowableC)
`
`throws IOException, ClassNotFoundException;
`
`} R
`
`enewal Fail ureEvent objects are passed to the event handlers specified in
`calls to the LeaseRenewal Set method, setRenewal FailureListener. The
`
`Renewal FailureEvent is a subclass of RemoteEvent, adding two additional
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`213
`
`213
`
`

`

`204
`
`THEZNTERFACE
`
`items of abstract state: the client lease that could not be renewed before expiration
`and the Th rowab1 e object that was thrown by the last recorded renewal attempt (if
`any). The client lease is returned by the getLease method, and the Th rowab1e
`object is returned by the getTh rowab1 e method. If the Th rowab1 e object is nu11,
`it can be assumed that during the time between the last-recorded, successful
`renewal (or when the client lease was added to the set if there have been no renew-
`als) and the actual expiration time of the client lease the renewal service was
`either unable to attempt a renewal of the client lease, or that it attempted a renewal
`but was unable to record the result.
`
`Both the getLease and getTh rowab1e methods may throw IOExcepti on or
`C1 assNotFoundExcepti on. This declaration allows implementations to delay
`unmarshalling this state until it is actually needed. Once either method of a given
`Renewa1 Fa1' 1 ureEvent object returns normally, future calls on that method must
`return the same object and may not throw an exception.
`If the renewal service was able to renew the client lease and record the result
`
`before the event occurred, the expiration time of the Lease object returned by the
`event’s getLease method will reflect the result of the last-recorded successful
`
`renewal call. Note that this time may be distorted by clock skew between hosts if
`it is currently set to use the Lease.ABSOLUTE serial format. If the Lease object is
`using the Lease . DURATION serial format, and the event only unmarshals the lease
`when getLease is called, the expiration time may be distorted if a long time has
`passed between the time the event was generated by the renewal service and when
`the client called getLease. When a renewal failure event is generated for a given
`lease, that lease is removed from the set.
`
`The event’s other state is described in The Jini Technology Core Platform
`Specification, “Distributed Events
`Sequence numbers for a given event ID are
`increasing. If there is no gap between two sequence numbers, no events have
`been missed; if there is a gap, events might (but might not) have been missed.
`
`LR.2.2 Serialized Forms
`
`Class
`
`ser- 'i a1 Versi onUID
`
`Serialized Fields
`
`Renewa1Fai1ureEvent
`
`889145704195932943L
`
`none
`
`ExpirationWarningEvent
`
`-2020487536756927350L
`
`none
`
`LeaseUnmarsha1 Exception
`
`-6736107321698417489L
`
`Lease[]unmarsha11edLeases
`Marsha11ed0bject[]
`sti11Mar‘sha11edLeases
`
`Th r'owab1 e [] exceptions
`
`214
`
`214
`
`

`

`
`
`EM
`
`
`
`Jini Event Mailbox Service
`
`Specification
`
`EM.1 Introduction
`
`THE The Jim' Technology Core Platform Specification, “Distributed Events”
`states the ability to interpose third-party objects, or “agents,” into an event notifi-
`cation chain as one of its design goals. This specification also describes a notifica-
`tion mailbox object, which stores and forwards event notifications on behalf of
`other objects, as an example of a useful third-party agent. These mailbox objects
`can be particularly helpful for objects that need more control over how and when
`they receive event notifications.
`For example, it would be impossible to send event notifications to a transient
`entity that has detached itself from a system of Jini technology-enabled services
`and/or devices (Jim' system). In such a situation an entity could employ the ser-
`vices of an event mailbox to store event notifications on its behalf before leaving
`the system. Upon rejoining the Jini system, the entity could then contact the event
`mailbox to retrieve any collected events that it would otherwise have missed. Sim-
`ilarly, an entity that wishes to deactivate could use an event mailbox to collect
`event notifications on its behalf while dormant.
`
`Like other Jini technology-enabled services (Jini services), the event mailbox
`service will grant its services only for a limited period of time without an active
`expression of continuing interest. Therefore, event mailbox clients still need to
`renew their leases if they intend to maintain the mailbox’s services beyond the ini-
`tially granted lease period. Any resources (for example, remote objects or storage
`space) associated with a particular client can be freed once the client’s lease has
`expired or been cancelled. In the previous usage scenarios, it might also benefit a
`transient or deactivatable entity to employ the services of a lease renewal service
`
`205
`
`215
`
`215
`
`

`

`206
`
`INTRODUCTION
`
`(see the Jini Lease Renewal Service Specification) to help mitigate the issue of
`lease maintenance.
`
`The remainder of this specification defines the requirements, interfaces, and
`protocols of the event mailbox service.
`
`EM.1.1 Goals and Requirements
`
`The requirements of the set of interfaces specified in this document are:
`
`0 To define a service that is capable of storing event notifications on behalf of
`its clients and capable of delivering stored event notifications to those clients
`
`upon request
`
`9 To provide this service in such a way that it can be used by entities that are
`temporarily unable or unwilling to receive event notifications
`
`9 To provide a service that complies with the policies embodied in the Jini
`technology programming model
`
`The goals of this specification are:
`
`9 To describe the event mailbox service
`
`0 To provide guidance in the use and deployment of the event mailbox service
`
`EM.1.2 Other Types
`
`The types defined in the specification of the event mailbox service are in the
`net.j1'n1' .event package. This specification assumes knowledge of The Jini
`Technology Core Platform Specification, “Distributed Events” and The Jini Tech-
`nology Core Platform Specification, “Distributed Leasing”. The following object
`types may be referenced in this chapter. Whenever referenced, these object types
`will be referenced in unqualified form:
`
`java.rmi.NoSuchObjectException
`
`java.rmi.RemoteException
`
`net.jini.core.event.RemoteEvent
`
`net.jini.core.event.RemoteEventListener
`
`net.jini.core.lease.Lease
`
`net.jini.core.lease.LeaseDeniedException
`
`216
`
`216
`
`

`

`JINI EVENT MAILB0X SER VICE SPECIFICA TION, version 1. 1
`
`207
`
`
`
`
`EM.2 The Interface
`
`THE EventMai1 box defines the interface to the event mailbox service. Through
`this interface, other Jini services and clients may request that event notification
`management be performed on their behalf. This interface belongs to the
`net.j1'n1' .event package, and any service implementing this interface must
`comply with the definition of a Jini service. This interface is not a remote inter-
`face; each implementation exports a proxy object that implements this interface
`local to the client, using an implementation-specific protocol to communicate with
`the actual remote server. All of the proxy methods obey normal Java Remote
`Method Invocation (RMI) interface semantics and can therefore be implemented
`directly using RMI (except where explicitly noted). Two proxy objects are equal
`(using the equals method) if they are proxies for the same event mailbox service.
`
`package net.jini.event;
`
`public interface EventMai 1 box
`
`{
`
`MailboxRegistration registerClong leaseDurat'ion)
`
`throws RemoteExcept'i on, LeaseDen‘iedException;
`
`Event mailbox clients Wishing to use the mailbox service first register them-
`selves with the service using the register method. Clients then use the methods
`of the returned Mai 1 boxRegi st ration object (a registration) in order to:
`
`9 Manage the lease for this particular registration
`
`9 Obtain a Remote EventLi stener reference that can be registered with event
`generators (that is, objects that support event notification for changes in
`their abstract state). This listener will store any received notifications for this
`particular registration.
`
`9 Enable or disable the delivery of any stored notifications for this particular
`registration
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`217
`
`217
`
`

`

`208
`
`THE INTERFACE
`
`218
`
`218
`
`

`

`JINI EVENT MAILB0X SER VICE SPECIFICA TION, version 1. 1
`
`209
`
`
`
`
`EM.3 The Semantics
`
`TO employ the event mailbox service, a client must first register with the event
`mailbox service by invoking the EventMai 1 box interface’s only method,
`regi ste r. Each invocation of the regi ster‘ method produces a new registration.
`a
`The
`register method may
`throw a RemoteException
`or
`LeaseDeniedException. Typically, a RemoteException occurs when there is a
`communication failure between the client and the event mailbox service. If this
`
`exception does occur, the registration may or may not have been successful. A
`LeaseDeni edExcepti on is thrown if the event mailbox service is unable or
`
`unwilling to grant the registration request. It is implementation specific as to
`whether or not subsequent attempts (with or without the same argument) are likely
`to succeed.
`
`Each registration with the event mailbox service is persistent across restarts or
`crashes of the event mailbox service, until the lease on the registration expires or
`is cancelled.
`
`The register method takes a single parameter of type long that represents
`the requested initial lease duration for the registration, in milliseconds. This dura-
`tion value must be positive (except for the special value of Lease .ANY). Other-
`wise, an 11 'I egalArgumentException is thrown.
`
`Every method invocation on an event mailbox service (whether the invocation
`is directly on the service, or indirectly on a Mai 'I boxRegi st ration that the ser-
`vice has created) is atomic with respect to other invocations.
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`219
`
`219
`
`

`

`2 1 0
`
`THE SEMANTICS
`
`220
`
`220
`
`

`

`JINI EVENT MAILB0X SER VICE SPECIFICA TION, version 1. 1
`
`2 1 1
`
`
`
`
`EM.4 Supporting Interfaces and Classes
`
`implements the interface
`that
`THE register method returns an object
`Mai 1 boxRegi st ration. It is through this interface that the client controls its reg-
`istration and notification management with the event mailbox service.
`
`package net.jini.event;
`
`public interface MailboxRegi stration
`
`{
`
`}
`
`Lease getLeaseC);
`
`RemoteEventListener getListenerC);
`
`void enableDeliveryCRemoteEventListener target)
`
`throws RemoteException;
`
`void disableDeliveryC) throws RemoteException;
`
`The Mai 'I boxRegi st ration interface is not a remote interface. Each implementa-
`tion of the event mailbox service exports proxy objects that implement this inter-
`face local to the client. These proxies use an implementation-specific protocol to
`communicate with the remote server. All of the remote proxy methods obey nor-
`mal RMI interface semantics and can therefore be implemented using RMI. Two
`proxy objects are equal (using the equals method) if they are proxies for the same
`registration, created by the same event mailbox service.
`Each remote method of this interface may throw a RemoteExcepti on. Typi-
`cally, this exception occurs when there is a communication failure between the
`client and the event mailbox service. Whenever a method invocation results in a
`
`Remote Excepti on, the method may or may not have successfully completed.
`Any invocation of a remote method defined in this interface will result in a
`NoSuchObjectExcepti on if the client’s registration with the event mailbox ser-
`vice has expired or has been cancelled. Note that upon receipt of a
`NoSuchObjectExcepti on, the client can assume that the registration no longer
`exists; the client cannot assume that the event mailbox service itself no longer
`exists.
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`221
`
`221
`
`

`

`212
`
`SUPPORTING INTERFA CES AND CLASSES
`
`EM.4.1 The Semantics
`
`The getLease method returns the Lease object associated with the registration.
`The client can renew or cancel the registration with the mailbox service through
`the Lease object returned by this method (see The Jini Technology Core Platform
`Specification, “Distributed Leasing”). This method is not remote and takes no
`
`arguments.
`The getL1' stener method returns an object that implements the interface
`RemoteEventLi stener. This object, referred to as a mailbox listener, can then be
`submitted as the RemoteEventLi stener argument to an event generator’s regis-
`tration method(s) (see The Jini Technology Core Platform Specification, “Distrib-
`uted Events”). Subsequent calls to this method will return equivalent objects (in
`the equals sense). Note that mailbox listeners generated by different registrations
`will not be equal. This method is not remote and takes no arguments.
`The valid period of use for a mailbox listener is tied to the associated registra-
`tion’s lease. A NoSuchObjectExcepti on will be thrown if an attempt is made to
`invoke the notify method on a mailbox listener whose associated lease has termi-
`nated.
`
`Mailbox listener references, just like their associated registrations, are persis-
`tent across server restarts or crashes until their associated registration’s lease ter-
`minates.
`
`The enabl eDel 1