Jini Event Mailbox Service Specification

A Collection of Jini Technology Helper Utilities and Services Specifications

Version 2.0

EM - Jini^TM Event Mailbox Service Specification

EM.1 Introduction

The Jini^TM Distributed Events Specification states the ability to interpose third-party objects, or "agents," into an event notification chain as one of its design goals. This specification also describes a notification 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^TM technology-enabled services and/or devices (Jini system). In such a situation an entity could employ the services 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. Similarly, 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 initially 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 (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:

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

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

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 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.jini.event package. This specification assumes knowledge of the Jini Distributed Events Specification and the Jini Distributed Leasing Specification. 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
EM.2 The Interface

The EventMailbox 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 interface; 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^TM Remote Method Invocation (Java RMI) interface semantics and can therefore be implemented directly using Java 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 EventMailbox
{
    MailboxRegistration register(long leaseDuration)
        throws RemoteException, LeaseDeniedException;
}
Event mailbox clients wishing to use the mailbox service first register themselves with the service using the register method. Clients then use the methods of the returned MailboxRegistration object (a registration) in order to:

Manage the 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 notifications for this particular registration.

Enable or disable the delivery of any stored notifications for this particular registration

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 produces a new registration.

The register method may throw a RemoteException or a 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 LeaseDeniedException 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 duration value must be positive (except for the special value of Lease.ANY). Otherwise, an IllegalArgumentException 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 service has created) is atomic with respect to other invocations.

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 Java RMI interface semantics and can therefore be implemented using Java 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 Distributed Leasing Specification). 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 Distributed Events Specification). 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 exception that indicates future attempts might be successful (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 produces an exception that indicates future attempts will be unsuccessful (a definite exception), then event delivery should be disabled for the associated registration until it is explicitly enabled again.

The algorithm used to classify exceptions as definite or indefinite is implementation specific.

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 RemoteEvents 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 identifier-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 may pose a security risk because source objects are potentially given references to other source objects that are currently using the same mailbox. If security is a concern, then care should be taken to prevent independent event sources from obtaining information about each other, for example by using a separate mailbox for each source.

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.

EM.5 The Interface

The PullEventMailbox defines the interface to the pull event mailbox service (the mailbox service). Through this interface, other Jini technology-enabled services and clients may request that event notification management be performed on their behalf. This interface belongs to the net.jini.event package. This interface is not a remote interface; 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 RMI interface semantics and can therefore be implemented directly using Java RMI. Two proxy objects are equal (using the equals method) if they are proxies for the same mailbox service.
package net.jini.event;

public interface PullEventMailbox extends EventMailbox 
{
    MailboxPullRegistration pullRegister(long leaseDuration)
        throws RemoteException, LeaseDeniedException;
}
Clients wishing to use the mailbox service first register themselves with the service using the pullRegister method. Clients then use the methods of the returned MailboxPullRegistration object (a registration) to:

Manage the 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 event notifications on behalf of this particular registration.
Synchronously or asynchronously collect any event notifications stored by this particular registration.

EM.6 The Semantics

To employ the mailbox service, a client must first register with the mailbox service by invoking the pullRegister method. Each invocation of the pullRegister method produces a new registration object. Each registration is persistent across restarts or crashes of the mailbox service until the registration's lease expires or is canceled.
The pullRegister method takes a single parameter of type long that represents the requested initial lease duration for the registration, in milliseconds. This duration value must be positive (except for the special value of Lease.ANY). Otherwise, an IllegalArgumentException is thrown.
The pullRegister method may throw a RemoteException or a 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 LeaseDeniedException is thrown if the mailbox service is unable or unwilling to grant the registration request. If LeaseDeniedException is thrown, it is implementation specific as to whether or not subsequent attempts (with the same or a different argument value) are likely to succeed.
Every method invocation on a mailbox service (whether the invocation is directly on the service, or indirectly on a registration that the service has created) is atomic with respect to other invocations.
EM.7 Supporting Interfaces and Classes

The pullRegister method returns an object that implements the MailboxPullRegistration interface. It is through this interface that the client controls its registration and notification management with the mailbox service.
package net.jini.event;

public interface MailboxPullRegistration extends 
    MailboxRegistration 
{
    RemoteEventIterator getRemoteEvents() 
        throws RemoteException;
    void addUnknownEvents(Collection unknownEvents)
        throws RemoteException;
}
public interface RemoteEventIterator 
{
    RemoteEvent next(long timeout)
        throws RemoteException, InvalidIteratorException;
    void close() throws InvalidIteratorException;
}
public class InvalidIteratorException extends Exception
{
    public InvalidIteratorException(String reason);
    public InvalidIteratorException();
}
The MailboxPullRegistration and the RemoteEventIterator interfaces are not remote interfaces. Each implementation of the mailbox service exports proxy objects that implement these interfaces locally to the client. These proxies use an implementation-specific protocol to communicate with the remote server. All of the remote proxy methods obey normal Java RMI interface semantics and can therefore be implemented using Java RMI. Two proxy objects are equal (using the equals method) if they are proxies for the same registration, created by the same mailbox service.
Each remote method of these interfaces may throw a RemoteException. Typically, this exception occurs when there is a communication failure between the client and the 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 mailbox service has expired or has been canceled. Note that upon receipt of a NoSuchObjectException, the client can assume that the registration no longer exists; the client cannot assume that the mailbox service itself no longer exists.
EM.7.1 The Semantics

The getRemoteEvents method returns a RemoteEventIterator object (an iterator) associated with the registration. The client can retrieve event notifications (received on its behalf by this particular registration) from the mailbox service through the iterator returned by this method.
Each invocation of the getRemoteEvents method produces a new iterator. Each new iterator will invalidate all previous iterators produced by the same registration. An invalidated iterator's methods must eventually throw an InvalidIteratorException to indicate this condition.
Calling getRemoteEvents also effectively calls disableDelivery for the associated registration. This will disable the registration's associated target listener, if any. Conversely, calling enableDelivery will, in turn, invalidate any existing iterators produced by the same registration.
If the combination of the event identifier and the event generator's object reference obtained from an event object is not one in which the mailbox client has registered an interest, an UnknownEventException should be propagated back to the event generator. This is accomplished by calling addUnknownEvents with a collection of unknown events. The effects of modifying the collection of unknown events during a call to addUnknownEvents are undefined.
The mailbox service will maintain a list of unknown events, on a per-registration basis, with the particular combinations of event identifier and source reference (obtained from the provided event objects). The mailbox should then propagate an UnknownEventException back to any event generator that attempts to deliver an event with an identifier-source combination held in a registration's unknown exception list. The valid iterator associated with the registration should also eventually 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 persistent across service restarts or crashes, until the associated registration's lease terminates or is cleared by subsequent calls to either enableDelivery or getRemoteEvents.
RemoteEventIterator's next method returns either an event from the registration's set of events (event set) or null if the event set is empty. This method takes a single argument of type long, which is the maximum time, in milliseconds, to wait for an event to become available in the event set. This argument must be a non-negative number or an IllegalArgumentException will be thrown. An iterator will not redeliver an event once it has been successfully returned from that iterator.
In general, events may be transferred to the client during or after the getRemoteEvents call. If there are InvocationConstraints associated with the getRemoteEvents call, then all of the events returned by next will be transferred in a way that meets those constraints. In particular, any constraints associated with the next method are ignored. The next method may return events after the associated registration lease has expired.
The next method may throw an InvalidIteratorException. An InvalidIteratorException is thrown if enableDelivery was subsequently called for this registration, a new iterator was subsequently generated for this registration, or the iterator was closed. Subsequent invocations (with the same or different argument value) will also fail with the same exception once an iterator throws InvalidIteratorException.
Calling close ends all event processing being performed by the iterator and invalidates the iterator. Subsequent iterator method invocations will also throw InvalidIteratorException. Any additional termination semantics must be defined by the implementation class itself.
EM.8 History

Version Description

v1.0 Initial release of this specification.

v2.0 Added "pull" semantics to mailbox specification (sections EM.5 through EM.8)
Changed titles for former "Core" specifications

License

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Version	Description
v1.0	Initial release of this specification.
v2.0	Added "pull" semantics to mailbox specification (sections EM.5 through EM.8) Changed titles for former "Core" specifications

Spec Index

A Collection of Jini Technology Helper Utilities and Services Specifications

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

EM - JiniTM Event Mailbox Service Specification

EM.1 Introduction

EM.1.1 Goals and Requirements

EM.1.2 Other Types

EM.2 The Interface

EM.3 The Semantics

EM.4 Supporting Interfaces and Classes

EM.4.1 The Semantics

EM.5 The Interface

EM.6 The Semantics

EM.7 Supporting Interfaces and Classes

EM.7.1 The Semantics

EM.8 History

License

EM - Jini^TM Event Mailbox Service Specification