throbber
196
`
`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

This document is available on Docket Alarm but you must sign up to view it.


Or .

Accessing this document will incur an additional charge of $.

After purchase, you can access this document again without charge.

Accept $ Charge
throbber

Still Working On It

This document is taking longer than usual to download. This can happen if we need to contact the court directly to obtain the document and their servers are running slowly.

Give it another minute or two to complete, and then try the refresh button.

throbber

A few More Minutes ... Still Working

It can take up to 5 minutes for us to download a document if the court servers are running slowly.

Thank you for your continued patience.

This document could not be displayed.

We could not find this document within its docket. Please go back to the docket page and check the link. If that does not work, go back to the docket and refresh it to pull the newest information.

Your account does not support viewing this document.

You need a Paid Account to view this document. Click here to change your account type.

Your account does not support viewing this document.

Set your membership status to view this document.

With a Docket Alarm membership, you'll get a whole lot more, including:

  • Up-to-date information for this case.
  • Email alerts whenever there is an update.
  • Full text search for other cases.
  • Get email alerts whenever a new case matches your search.

Become a Member

One Moment Please

The filing “” is large (MB) and is being downloaded.

Please refresh this page in a few minutes to see if the filing has been downloaded. The filing will also be emailed to you when the download completes.

Your document is on its way!

If you do not receive the document in five minutes, contact support at support@docketalarm.com.

Sealed Document

We are unable to display this document, it may be under a court ordered seal.

If you have proper credentials to access the file, you may proceed directly to the court's system using your government issued username and password.


Access Government Site

We are redirecting you
to a mobile optimized page.





Document Unreadable or Corrupt

Refresh this Document
Go to the Docket

We are unable to display this document.

Refresh this Document
Go to the Docket