EM.4. Supporting Interfaces and Classes

The register method returns an object that implements the interface MailboxRegistration. It is through this interface that the client controls its registration 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 disableDelivery() throws RemoteException; 
} 

The MailboxRegistration interface is not a remote interface. Each implementation of the event mailbox service exports proxy objects that implement this interface local to the client. These proxies use an implementation-specific protocol to communicate with the remote server. All of the remote proxy methods obey normal 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 RemoteException. Typically, 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 may or 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 service 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.

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 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 registration method(s) (see The Jini Technology Core Platform Specification, “Distributed 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 registration’s lease. A NoSuchObjectException will be thrown if an attempt is made to invoke the notify method on a mailbox listener whose associated lease has terminated.

Mailbox listener references, just like their associated registrations, are persistent across server restarts or crashes until their associated registration’s lease terminates.

The enableDelivery method allows a client to initiate delivery of event notifications (received on its behalf by this particular registration) to the client-specified 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 same effect as disabling delivery (see below).

Resubmitting a mailbox listener back to the same mailbox service that generated it will result in an IllegalArgumentException being thrown. This is necessary to prevent a recursive event notification chain. Therefore, the event mailbox service must keep track of any listener objects that it generates and reject the resubmission of those objects.

Once enabled, event delivery remains enabled until it is disabled. Any events received while delivery is enabled will also be scheduled for delivery.

Event delivery guarantees with respect to exception handling, ordering, and concurrency are implementation specific and are not specified in this document. However, implementations are encouraged to support the following functionality. If an event delivery attempt produces an indefinite exception, then reasonable efforts should be made to successfully redeliver the event until the associated registration’s lease terminates. On the other hand, if an event delivery attempt pro duces a definite exception, then event delivery should be disabled for the associated registration until it is explicitly enabled again.

Also, implementations may concurrently deliver event notifications to the same target listener, which implies that events may be sent in a different order than the order in which they were originally received. Hence, it is the target listener’s responsibility to guard against potential concurrent, out-of-order event delivery.

Similarly, implementations are encouraged to support this method’s intended semantics regarding listener replacement. That is, a mailbox client can reasonably assume that listener replacement has occurred upon successful return from this method and can therefore safely unexport the previous listener object. This also implies that any in-progress delivery attempts to the previous listener are either successfully cancelled before returning from this method (blocking), or subsequently retried using the replacement listener after returning from this method (non-blocking). Note that the non-blocking case can potentially allow the previous listener to be notified after successfully returning from this method.

The disableDelivery method allows the client to cease event delivery to the existing target listener, if any. It is acceptable to call this method even if no target listener is currently enabled. This method takes no arguments.

Again, event delivery guarantees are implementation specific and are not specified in this document. Implementations are encouraged to support the method’s intended semantics regarding delivery suspension. That is, a mailbox client can reasonably assume that event delivery has been suspended upon successful return from this method and can therefore safely unexport the previously enabled listener object if desired. This also implies that any in-progress delivery attempts to the previously enabled listener are either successfully cancelled before returning from this method (blocking), or subsequently retried using the next enabled listener after returning from this method (non-blocking). Note that the non-blocking case can potentially allow the previously enabled listener to be notified after successfully returning from this method.

The event mailbox service does not normally concern itself with the attributes of the RemoteEvent s that it receives. The one circumstance about which it must concern itself is when a target listener throws an UnknownEventException during an event delivery attempt. The event mailbox service must maintain a list, on a per-registration basis, of the particular combinations of event identifier and source reference (obtained from the offending RemoteEvent object) that produced the exception. The event mailbox must then propagate an UnknownEventException back to any event generator that attempts to deliver a RemoteEvent with an identi-fier-source combination held in a registration’s unknown exception list. The service will also skip the future delivery of any stored events that have an identifier-source combination held in this list.

A registration’s unknown exception list is cleared upon re-enabling delivery with any target listener. This list is persistent across service restarts or crashes, until the associated registration’s lease terminates.

Note that the act of comparing event source objects for equality poses a security risk because source objects are potentially given references to other source objects that are currently using the mailbox. If security is a concern, then care should be taken to prevent independent event sources from obtaining information about each other.

Again, although implementation details are not specified in this document, service implementations need to carefully weigh the trade-offs of taking a particular security approach. For example, a low-security implementation could simply compare source objects using the equals method. This approach assumes well-behaved equals methods that pose no security risk. A more secure implementation might compare only source objects (using equals) that have the same codebase on the assumption that classes from the same codebase are trusted. Unfortunately, this approach will not work for services that evolve by changing their codebase (presumably to the location of the upgraded class files).

The event mailbox does not support multiple, concurrent notification targets per registration. As a result, the interface supports only a set/clear model rather than the more common add/remove model.

Event persistence guarantees are not specified in this document because no single policy can cover all the possible design trade-offs between reliability, efficiency, and performance. It is expected that operational parameters—controls for how the event mailbox deals with issues such as persistence guarantees, storage quotas, and low space behavior—will be exposed through an administration interface, which can vary across different event mailbox implementations.