`
`THE INTERFACE
`
`will not be longer. The value of the leaseDuration argument must bepositive,
`Lease. FOREVER, or Lease.ANY; otherwise, an I1legalArgumentException will
`be thrown. Two calls to the createLeaseRenewalSet method will never return
`objects that are equal. The set's lease is obtained through a method provided by
`the set.
`LeaseRenewalSet defines the interface to the sets created by the lease
`renewalservice. This interface is not a remote interface. Each implementation of
`the renewal service exports proxy objects that implement the LeaseRenewalSet
`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
`RMIremote 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 NoSuchObjectException if the set no longerexists.
`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 notinfer that the renewal service has been destroyed.
`
`package net.jini. lease;
`
`public interface LeaseRenewalSet {
`final public static long RENEWAL_FAILURE_EVENT_ID = Q;
`final public static long EXPIRATION_WARNING_EVENT_ID = 1;
`
`public void renewFor(Lease leaseToRenew,
`long desiredDuration,
`long
`renewDuration)
`throws RemoteException;
`
`public void renewFor(Lease leaseToRenew,
`long desiredDuration)
`throws RemoteException;
`
`public EventRegistration setExpirationWarningListener(
`RemoteEventListener listener,
`long
`minWarning,
`Marshal ledObject
`handback)
`throws RemoteException;
`
`public void clearExpirationWarningListener()
`throws RemoteException;
`
`206
`
`206
`
`
`
`JINI LEASE RENEWAL SERVICE SPECIFICATION, version 1.1
`
`197
`
`public EventRegistration setRenewalFai lureListener(
`RemoteEventListener listener,
`Marshal ledObject
`handback)
`throws RemoteException;
`
`public void clearRenewalFailureListener()
`throws RemoteException;
`
`public Lease remove(Lease leaseToRemove)
`throws RemoteException;
`
`public Lease[] getLeases()
`throws LeaseUnmarshalException, RemoteException;
`
`public Lease getRenewalSetLease(Q) ;
`
`} L
`
`eases can be addedto 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 1easeToRenew argumentspecifies the
`lease to be renewed. An I1legalArgumentException will be thrownif the lease
`has not
`expired and was granted by the
`renewal
`service
`itself. An
`I1legalArgumentException will also be thrownif the lease is currently a mem-
`ber of another set allocated by the same renewal service. If 1easeToRenewis
`nul], aNul1PointerException will be thrown.
`The desi redDuration parameteris the numberof millisecondsthat the client
`would like for the client lease to remainin the set. It is used to calculate the client
`lease’s desired expiration by adding desiredDuration 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 redDuration (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
`renewalfailure 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 addedtotheset 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 renewalfailure event will be generated.If the
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`207
`
`207
`
`
`
`198
`
`THE INTERFACE
`
`actual expiration time is before the current time and equalto or after the desired
`expiration time, the method will return normally, the client lease will be dropped
`from the set, and no eventwill be generated.
`A desiredDuration 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 theset,
`or the renewal service makes a renewal attemptontheclient lease that results in a
`definite exception.
`The renewDuration is the renewal duration to associate with the client lease
`(in milliseconds).
`If desiredDuration is
`exactly Long.MAX_VALUE,
`the
`renewDuration 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 I11legalArgumentException.
`Calling renewFor withalease that is equivalentto 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
`
`renewFor(leaseToRenew, desiredDuration, 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 formatif the implementation
`has access to the client lease only in marshalled form and is unable to unmarshal
`the client lease before sendingit to the client.
`Whenevera client lease gets returned to a client, its actual expiration should
`reflect either:
`
`@ The result of the last recorded successful renewal of the client lease per-
`formed by the renewalservice; or
`@ The expiration time the client lease originally had whenit was addedto the
`set, if the renewal service has been unable to successfully renew the client
`lease and recordthe 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 SERVICE SPECIFICATION, version 1.1
`
`199
`
`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 notin the set, nu11 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 methodreturnsall the client leases in the set at the time of the
`call, as an array of type Lease. If one or more of the Leasesin the array cannot be
`deserialized, a LeaseUnmarshalException is thrown.
`
`package net.jini. lease;
`
`public class LeaseUnmarshalException extends Exception {
`public LeaseUnmarshalException(
`Lease[]
`leases,
`MarshalledObject[] marshalledLeases,
`Throwable[]
`exceptions) {...}
`public LeaseUnmarshalException(
`Lease[]
`leases,
`MarshalledObject[] marshalledLeases,
`Throwable[]
`exceptions,
`String
`message) {...}
`
`public Lease[] getLeases() {...}
`public MarshalledObject[] getMarshalledLeases() {...}
`public Throwable[] getExceptions() {...}
`
`} T
`
`he leases that could be successfully deserialized will be returned by the
`getLeases methodof 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
`getMarshalledLeases method, the corresponding element of the array returned
`by the getExceptions method will hold a Throwable that indicates why the
`given lease could not be deserialized.
`Throwing a LeaseUnmarshalException represents a (possibly transient) fail-
`ure in the ability to unmarshal one or moreclientleases in the set; it does not nec-
`essarily imply anything about the state of the renewalservice or the set that threw
`the exception.
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`209
`
`209
`
`
`
`200
`
`THE INTERFACE
`
`The getRenewalSetLease method of LeaseSet returns the lease associated
`with the set itself. This method does not make a remotecall.
`
`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 numberof leases that it would
`have to manage. Since the renewal service is based on the premise that somecli-
`ents have difficulty managing their own leases, increasing the numberof 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/clear interface instead of the more common
`addListener/removeListener or addListener/lease. cancel interfaces.
`The source field of each event generated by a lease renewal service is the
`renewalset 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 renewalfailure event,
`this is the set the client lease was in whenthe 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 ofthe set the client has in its posses-
`sion, but in general it will not be the same object (that is, comparing twosets
`using == will usually return false).
`The event ID LeaseRenewalSet.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 LeaseRenewalSet .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 numberof any other renewal failure event generated bytheset.
`Two different events with the same source and event ID will have different
`sequence numberseven 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 UnknownEventException, this action will only clear the
`specific event registration. It will not cancel the lease on the renewalset or affect
`
`210
`
`210
`
`
`
`JINI LEASE RENEWAL SERVICE SPECIFICATION, version 1.1
`
`201
`
`any other event registration on the set. If the listener throws a bad object excep-
`tion, the renewal service mayclear that specific event registration; it will not clear
`any registration associated with other listeners, nor will it cancel the lease on the
`associated renewalset.
`If an event listener is replaced and one or more event delivery attempts on the
`original listener failed, implementations may choose to send someorall of these
`events to the new listener.
`Eventlisteners mayreceive notification of events that they are no longerregis-
`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 setExpirationWarningListener method of LeaseRenewalSet 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 1istener
`argumentspecifies which listener should be notified when the set’s lease is about
`to expire. The minWarning argument specifies the minimum numberof millisec-
`onds before set lease expiration that the first event delivery attempt should be
`madeby the service. The service may also make subsequent delivery attempts if
`the first and any subsequent attempts resulted in an indefinite exception. The
`minWarning argument must be zero or a positive number;
`if it
`is not, an
`I1legalArgumentException must be thrown. If the current expiration of the
`set’s lease is less than minWarning milliseconds away, the event will occur imme-
`diately (thoughit will take time to propagate to the handler).
`The handback argument to setExpirationWarningListener 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 setExpirationWarningListener methodreturns 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 removetheir
`expiration warning registration without destroying the set should use the
`clearExpirationWarningListener method described below, instead of cancel-
`ling the registration’s lease. The event ID returned with the registration will be
`LeaseRenewalSet .EXPIRATION_WARNING_EVENT_ID. The source ofthe registra-
`tion will be the set. The method will throw a Nul1PointerException if the
`listener argumentis 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 ofevent, the events sent to the new registration must be
`in the same sequenceasthe events sentto the old registration.
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`211
`
`211
`
`
`
`202
`
`THE INTERFACE
`
`The clearExpirationWarningListener method of LeaseRenewalSet
`removesthe event registration currently associated with the approaching expira-
`tion of the set’s lease. It is acceptable to call this method evenif there is no active
`registration.
`The setRenewalFailureListener method of LeaseRenewalSet allows the
`client to register for the event associated with the failure to renewaclient lease in
`the set. These events are generated whena 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 argumentspecifies the
`listenerto be notified if a client lease could not be renewed.
`The handback argument to setRenewalFai lureListener specifies an object
`that will be part of the renewal failure event notification. This mechanism is
`detailed in The Jini Technology Core Platform Specification,
`“Distributed
`Events”.
`The setRenewalFailureListener 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 theset, clients that want to just removetheir
`expiration warning registration without destroying the set should use the
`clearRenewalFailureListener method (described below) instead of cancelling
`the registration’s lease. The registration ID returned with the registration will be
`LeaseRenewalSet.RENEWAL_FAILURE_EVENT_ID. The sourceof the registration
`will be the set.The method will throw Nu11PointerException if the listener
`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 registrations are
`for the same kind of event, the events sent to the new registration must be in the
`same sequenceas the events sent to the old registration.
`The clearRenewalFailureListener method of LeaseRenewalSet removes
`the event registration currently associated with the failure to renew client leases.It
`is acceptable to call this method evenif there is no active registration.
`
`package net.jini. lease;
`
`public class ExpirationWarningEvent extends RemoteEvent {
`public ExpirationWarningEvent(
`LeaseRenewalSet
`source,
`long
`seqNum,
`{...}
`MarshalledObject handback)
`public Lease getRenewalSetLease() {...}
`
`212
`
`212
`
`
`
`JINI LEASE RENEWAL SERVICE SPECIFICATION, version 1.1
`
`203
`
`ExpirationWarningEvent objects are passed to the event handlers specified
`in calls to the LeaseRenewalSet method, setExpirationWarningListener. The
`ExpirationWarningEvent is a subclass of RemoteEvent and adds noadditional
`state. Because the source of a Expi rationWarningEvent is theset that is about to
`expire, the lease that needs to be renewed can be obtained by: calling getSource,
`casting the result
`to a LeaseRenewalSet
`and then invoking the
`set’s
`getRenewalSetLease method. The convenience method getRenewalSetLease
`in ExpirationWarningEvent uses this techniqueto retrieve the lease on theset.
`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 getExpiration
`methodof the Lease object returned by the event’s getRenewalSetLease method
`may return a different time than the getExpiration methods of other Lease
`objects granted on the sameset.
`The expiration time associated with the Lease object returned by the
`getRenewalSetLease 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 whenit wasdeliv-
`ered.
`Other aspects of the event’s state are 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.
`
`package net.jini. lease;
`
`public abstract class RenewalFailureEvent
`extends RemoteEvent
`
`{
`
`source,
`public RenewalFailureEvent(LeaseRenewalSet
`seqNum,
`long
`MarshalledObject handback) {...}
`abstract public Lease getLease()
`throws IOException, ClassNotFoundException;
`abstract public Throwable getThrowable()
`throws IOException, ClassNotFoundException;
`
`} R
`
`enewalFailureEvent objects are passed to the event handlers specified in
`calls to the LeaseRenewalSet method, setRenewalFailureListener. The
`RenewalFailureEvent is a subclass of RemoteEvent, adding two additional
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`213
`
`213
`
`
`
`204
`
`THE INTERFACE
`
`items of abstract state: the client lease that could not be renewedbefore expiration
`and the Throwable object that was thrownbythe last recorded renewalattempt(if
`any). The client lease is returned by the getLease method, and the Throwable
`object is returned by the getThrowable method. If the Throwable object is nu11,
`it can be assumed that during the time between the last-recorded, successful
`renewal (or whenthe client lease was addedto 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 renewalofthe client lease, or that it attempted a renewal
`but was unable to record the result.
`Both the getLease and getThrowable methods may throw IOException or
`ClassNotFoundException. This declaration allows implementations to delay
`unmarshalling this state until it is actually needed. Once either method of a given
`RenewalFailureEvent object returns normally, future calls on that method must
`return the same object and maynot 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
`renewalcall. Note that this time may be distorted by clock skew between hosts if
`it is currently set to use the Lease. ABSOLUTEserial format. If the Lease objectis
`using the Lease. DURATIONserial 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 renewalfailure event is generated for a given
`lease, that lease is removed from theset.
`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
`
`serialVersionUID
`
`Serialized Fields
`
`Renewal Fai lureEvent
`
`889145704195932943L
`
`none
`
`ExpirationWarningEvent
`
`-2020487536756927350L
`
`none
`
`LeaseUnmarshalException
`
`-6736107321698417489L
`
`Lease[]unmarshalledLeases
`MarshalledObject[]
`stil]lMarshalledLeases
`
`Throwable[] exceptions
`
`214
`
`214
`
`
`
`
`
`
`EM
`
`Jini Event Mailbox Service
`Specification
`
`EM.1 Introduction
`
`Ti The Jini Technology Core Platform Specification, “Distributed Events”
`states the ability to interpose third-party objects, or “agents,” into an event notifi-
`cation chain as oneofits 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 eventnotifications.
`For example, it would be impossible to send event notifications to a transient
`entity that has detacheditself from a system of Jini technology-enabled services
`and/or devices (Jini 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
`mailboxto 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
`eventnotifications 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 beyondtheini-
`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 remainderofthis specification defines the requirements, interfaces, and
`protocols of the event mailboxservice.
`
`EM.1.1 Goals and Requirements
`
`The requirements ofthe set of interfaces specified in this documentare:
`
`To define a service that is capable of storing eventnotifications on behalf of
`its clients and capable ofdelivering stored event notifications to those clients
`upon request
`To provide this service in such a waythat it can be used by entities that are
`temporarily unable or unwilling to receive event notifications
`To provide a service that complies with the policies embodied in the Jini
`technology programming model
`
`The goals of this specification are:
`
`@ To describe the event mailbox service
`
`To provide guidancein the use and deploymentof the event mailbox service
`
`EM.1.2 Other Types
`
`The types defined in the specification of the event mailbox service are in the
`net.jini.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 maybe 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 MAILBOX SERVICE SPECIFICATION, version 1.1
`
`207
`
`
`
`
`EM.2 The Interface
`
`Tue EventMai 1box 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.jini.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 1box
`{
`
`MailboxRegistration register(long leaseDuration)
`throws RemoteException, LeaseDeniedException;
`
`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 lboxRegistration object (a registration) in orderto:
`
`@ Managethe lease for this particular registration
`@ Obtain a RemoteEventListener 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 notificationsforthis
`particularregistration.
`@ Enable or disable the delivery of any stored notifications for this particular
`registration
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`217
`
`217
`
`
`
`208
`
`THE INTERFACE
`
`218
`
`218
`
`
`
`JINI EVENT MAILBOX SERVICE SPECIFICATION, 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 EventMailbox interface’s only method,
`register. Each invocation of the register method producesa new registration.
`The
`register method may
`throw a RemoteException
`or
`a
`LeaseDeniedException. Typically, a RemoteException occurs whenthere 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
`LeaseDeniedException is thrown if the event mailbox service is unable or
`unwilling to grant the registration request. It is implementation specific as to
`whetheror not subsequent attempts (with or without the same argument) are likely
`to succeed.
`Eachregistration with the event mailbox serviceis 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 I] legalArgumentException is thrown.
`Every method invocation on an event mailbox service (whether the invocation
`is directly on the service, or indirectly on a MailboxRegistration that the ser-
`vice has created) is atomic with respect to other invocations.
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`219
`
`219
`
`
`
`210
`
`THE SEMANTICS
`
`220
`
`220
`
`
`
`JINI EVENT MAILBOX SERVICE SPECIFICATION, version 1.1
`
`211
`
`
`
`
`EM.4 Supporting Interfaces and Classes
`
`implements the interface
`that
`Tue register method returns an object
`MailboxRegistration. 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 MailboxRegistration
`{
`
`Lease getLease();
`RemoteEventListener getListener();
`void enableDelivery(RemoteEventListener target)
`throws RemoteException;
`void disableDeliveryQ throws RemoteException;
`
`}
`
`The Mai lboxRegistration interface is not a remote interface. Each implementa-
`tion of the event mailbox service exports proxy objects that implementthis 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 ofthis interface may throw a RemoteException. 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
`RemoteException, the method mayor may not have successfully completed.
`Any invocation of a remote method defined in this interface will result in a
`NoSuchObjectException if the client’s registration with the event mailbox ser-
`vice has expired or has been cancelled. Note that upon receipt of a
`NoSuchObjectException, 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 JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`221
`
`221
`
`
`
`212
`
`SUPPORTING INTERFACES AND CLASSES
`
`EM.4.1 The Semantics
`
`The getLease method returns the Lease object associated with the registration.
`The client can renew or cancelthe 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 getListener method returns an object that implements the interface
`RemoteEventListener. This object, referred to as a mailbox listener, can then be
`submitted as the RemoteEventListener 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 methodis not remote and takes no arguments.
`The valid period of use for a mailboxlistener is tied to the associated registra-
`tion’s lease. A NoSuchObjectException will be thrown if an attempt is made to
`invoke the noti fy method on a mailboxlistener 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 enableDelivery method allowsa client to initiate delivery of event noti-
`fications (received on its behalf by this particular registration) to the client-speci-
`fied listener, referred to as the target listener. This method takes a single argument
`of type RemoteEventListener. Subsequent calls to this method simply replace
`the registration’s existing target listener, if any, with the specified target listener.
`Passing null as the listener argument has the sameeffect as disabling delivery
`(see below).
`Resubmitting a mailbox listener back to the same mailb