LookupDiscoveryService Requirements

 

ID

LookupDiscoveryService Requirement

Section

Comments
  1.  

Two proxy objects are equal (using the equals method) if they are proxies for the same lookup discovery service.

8.3

IF: LDSET
  1.  

An invocation of the register method produces an object — referred to as a registration object (or simply, a registration) — that is mutable.   Because the returned object is mutable, each invocation of the register method produces a new registration object.

8.4

IF: LDSIFT
  1.  

The register method may throw a RemoteException. … When this exception does occur, the registration may or may not have been successful.

 

 
  1.  

Each registration with the lookup discovery service is persistent across restarts (crashes) of the lookup discovery service, until the lease on the registration expires or is cancelled.

 

 
  1.  

The register method takes a String array, ..., consisting of zero or more names of the groups to which the desired lookup services belong

 

IF: LDSIFT

 
  1.  

The register method takes a String array, none of whose elements may be null, ...

 

IF: LDSIFT
  1.  

The register method takes a String array,… [effectively] with duplicates eliminated.

 

 
  1.  

A null value (LookupDiscovery.ALL_GROUPS) is acceptable for this argument. If the value is null, the lookup discovery service will attempt to discover all lookup services located within the multicast radius of the host on which the lookup discovery service is running.

 

IF: LDSIFT
  1.  

If an empty array (LookupDiscovery.NO_GROUPS) is passed in, then no group discovery will be performed for the associated registration until the client, through one of the registration’s methods, populates the managed set of groups.

 

 
  1.  

An array of zero or more non-null LookupLocator objects, each corresponding to a specific lookup service the client wishes to be discovered

 

IF: LDSIFT
  1.  

… with duplicates eliminated.

 

 

 
  1.  

If either the empty array or null is passed in as the locators argument, then no locator discovery will be performed for the associated registration until the client, through one of the registration’s methods, populates the managed set of locators.

 

IF: LDSIFT
  1.  

A non-null RemoteEventListener object which specifies the entity that will receive events notifying the registration of the discovery of lookup services of interest

 

IF: LDSIFT
  1.  

If a null value is input to this argument, then a NullPointerException will be thrown and the registration fails.

 

IF: LDSIFT
  1.  

Either null or an instance of MarshalledObject specifying an object that will be included in the notification event that the lookup discovery service sends to the registered listener

 

IF: LDSIFT
  1.  

A long value representing the amount of time (in milliseconds) for which the resources of the lookup discovery service are being requested

 

IF: LDSIFT
  1.  

The initial duration of the lease granted to a client by the lookup discovery service will be less than or equal to the requested duration reflected in the value input to the leaseDuration argument.

 

 
  1.  

That value must be positive, Lease.FOREVER or Lease.ANY. If any other value is input to this argument, an IllegalArgumentException will be thrown.

 

IF: LDSIFT
  1.  

The register method returns an instance of the LookupDiscoveryRegistration interface.

 

IF: LDSIFT
  1.  

Upon discovery of a lookup service, through either group discovery or locator discovery, the lookup discovery service will send an event, referred to as a discovery event, to the listener associated with the registration produced by the call to register.

 

 
  1.  

If the multicast announcements from an already-discovered lookup service indicate that the lookup service is a member of a new group, a discovery event will be sent to all registrations that have registered interest in lookup services belonging to that group.

 

 
  1.  

If the multicast announcements from an already-discovered lookup service indicate that the lookup service is no longer a member of one or more of the groups that had been reflected in previous multicast announcements, a discard event will be sent to all registrations that have registered interest in at least one of the missing groups but in none of the remaining groups.

 

 
  1.  

If the multicast announcements from an already-discovered lookup service are no longer being received, a discard event will be sent to all registrations that have registered interest in that lookup service.

 

What's the timeout? How many dropped events?
  1.  

For each registration created by the lookup discovery service, an event identifier will be generated that uniquely maps the registration to the listener and to the set of groups and locators submitted through the registration request. This event identifier is returned as a part of the returned registration object, and is unique across all other active registrations with the lookup discovery service.

 

 
  1.  

Whenever the lookup discovery service finds a lookup service matching the discovery criteria of one or more of its registrations, it sends an instance of RemoteDiscoveryEvent (a sub-class of RemoteEvent) to the listener corresponding to each such registration.

 

 
  1.  

Once an event signaling the discovery (by group or locator) of a desired lookup service has been sent, no other discovery events for that lookup service will be sent to a registration’s listener until the lookup service is discarded (through that registration) and then re-discovered.

 

Conflicts with #21?
  1.  

If, between the time a lookup service is discarded (through any registration) and the time it is re-discovered, a new registration having parameters referencing that lookup service is requested, upon re-discovery of the lookup service an event will also be sent to that new registration’s listener.

 

 
  1.  

The sequence numbers for a given event identifier are strictly increasing (as defined in the Jini™ Distributed Event Specification), which means that when any two such successive events have sequence numbers differing by only a value of 1, then no events have been missed.

 

 
  1.  

Two proxy objects are equal (using the equals method) if they are proxies for the same registration created by the same lookup discovery service.

8.5.1

IF: LDSRET
  1.  

If the client’s registration with the lookup discovery service has expired or been cancelled, then any invocation of a remote method defined in this interface will result in a NoSuchObjectException.

 

 
  1.  

The getEventRegistration method returns an EventRegistration object that encapsulates the information needed by the client to identify a notification sent by the lookup discovery service to the registration’s listener.

 

IF: LDSRLIFT
  1.  

The getLease method returns the Lease object that controls a client’s registration with the lookup discovery service. It is through the object returned by this method that the client requests the renewal or cancellation of the registration with the lookup discovery service. This method is not remote and takes no arguments.

 

IF: LDSRLIFT
  1.  

Note that the object returned by the getEventRegistration method also provides a getLease method. That method and the getLease method defined by the LookupDiscoveryRegistration interface both return the same Lease object.

 

IF: LDSRLIFT
  1.  

The getRegistrars method returns an array containing references to each lookup service that has already been discovered for the registration.

 

IF: LDSRGIFT
  1.  

The getGroups method returns an array consisting of the group names from the registration’s managed set.

 

IF: LDSRGIFT
  1.  

If the managed set of groups is empty, this method returns the empty array. .

 

IF: LDSRGIFT

 
  1.  

If there is no managed set of groups associated with the registration, then null is returned

 

IF: LDSRGIFT

 
  1.  

The getLocators method returns an array consisting of the LookupLocator objects from the registration’s managed set.

 

 
  1.  

If the managed set of locators is empty, this method returns the empty array.

 

 
  1.  

If there is no managed set of locators associated with the registration, then null is returned.

 

 
  1.  

a set of groups is represented as a String array, none of whose elements may be null.

 

IF: LDSRGIFT
  1.  

The empty set is denoted by the empty array (LookupDiscovery.NO_GROUPS),

 

IF: LDSRGIFT
  1.  

and “no set” is indicated by null (LookupDiscovery.ALL_GROUPS). No set indicates that all lookup services within the multicast radius should be discovered.

 

IF: LDSRGIFT
  1.  

Invoking any of these methods with an input set of groups that contains duplicate names is equivalent to performing the invocation with the duplicate group names removed from the input set.

 

IF: LDSRGIFT
  1.  

The addGroups method adds a set of group names to the registration’s managed set.

 

IF: LDSRGIFT
  1.  

Elements in the array that duplicate elements already in the managed set will be ignored.

 

IF: LDSRGIFT
  1.  

Once a new name has been added to the managed set, the lookup discovery service will attempt to discover all as yet undiscovered lookup services that are members of the group having that name.

 

 
  1.  

If the registration has no current managed set of groups to augment, this method throws an UnsupportedOperationException.

 

IF: LDSRGIFT
  1.  

If the parameter value is null, this method throws a NullPointerException.

 

IF: LDSRGIFT
  1.  

If the parameter value is the empty array, then the registration’s managed set of groups will not change.

 

IF: LDSRGIFT
  1.  

The setGroups method replaces all of the group names in the registration’s managed set with names from a new set.

 

IF: LDSRGIFT
  1.  

Once a new group name has been placed in the managed set, if there are lookup services belonging to that group that have already been discovered, no event will be sent to the registration’s listener for those particular lookup services. Attempts to discover all as yet undiscovered lookup services belonging to that group will continue to be made for the registration.

 

 
  1.  

If null is passed to setGroups, then the lookup discovery service will attempt to discover all as yet undiscovered lookup services located within the multicast radius and, upon discovery of any lookup service, will send to the registration’s listener an event signaling that discovery.

 

IF: LDSRGIFT
  1.  

If the parameter value is the empty array, then group discovery for the registration will cease.

 

 

 
  1.  

The removeGroups method deletes a set of group names from the registration’s managed set.

 

IF: LDSRGIFT
  1.  

If the registration has no current managed set of groups from which to remove elements, the removeGroups method throws an UnsupportedOperationException.

 

IF: LDSRGIFT
  1.  

If null is input, this method throws a NullPointerException.

 

IF: LDSRGIFT

 
  1.  

If the empty array is input, then the registration’s managed set of groups will not change.

 

IF: LDSRGIFT

 
  1.  

After a set of groups has been removed from the managed set because of an invocation of either setGroups or removeGroups, attempts to discover any lookup service that satisfies each of the following characteristics will cease to be made for the registration:

-          the lookup service is a member of one or more of the groups that was removed from the registration’s managed set, and

-          the lookup service is not a member of any group in the new managed set resulting from the invocation of setGroups or removeGroups, and

-          the lookup service does not correspond to any element in the registration’s managed set of locators.

 

 
  1.  

a set of locators is represented as an array of LookupLocator objects, none of whose elements may be null.

 

 
  1.  

Invoking any of these methods with a set of locators that contains duplicate locators (as determined by the equals method of LookupLocator) is equivalent to performing the invocation with the duplicates removed from the input set.

 

 
  1.  

The addLocators method adds a set of LookupLocator objects to the registration’s managed set.

 

 
  1.  

Elements in the input set that duplicate (using LookupLocator.equals) elements already in the managed set will be ignored.

 

 
  1.  

This method throws an UnsupportedOperationException if the registration has no managed set of locators to augment.

 

 
  1.  

If null is passed to addLocators,a NullPointerException will be thrown.

 

 
  1.  

If the empty array is the parameter value, the registration’s managed set of locators will not change.

 

 
  1.  

The setLocators method replaces all of the locators in the registration’s managed set with LookupLocator objects from a new set.

 

 
  1.  

If null is passed to setLocators,a NullPointerException will be thrown.

 

 
  1.  

If the parameter value is the empty array, all locator discovery performed by the lookup discovery service, for the registration, will cease.

 

 
  1.  

The removeLocators method deletes a set of LookupLocator objects from the registration’s managed set.

 

 
  1.  

If the registration has no managed set of locators from which to remove elements, this method throws an UnsupportedOperationException.

 

 
  1.  

If null is passed to removeLocators,a NullPointerException will be thrown.

 

 
  1.  

If the parameter value is the empty array, the registration’s managed set of locators will not change.

 

 
  1.  

Note that locator equality is determined by the equals method of LookupLocator.

 

 
  1.  

Whenever a new locator is placed in the managed set as a result of an invocation of one of the locator modification methods, and that new locator equals none of the locators corresponding to the previously discovered lookup services (across all registrations), the lookup discovery service will attempt unicast discovery of the lookup service associated with the new locator.

 

 
  1.  

If locator discovery is attempted, the discovery attempt will be repeated until…The lookup service is discovered

 

 
  1.  

If locator discovery is attempted, the discovery attempt will be repeated until…The client’s lease expires

 

 
  1.  

If locator discovery is attempted, the discovery attempt will be repeated until…The client explicitly removes the locator from the managed set

 

 
  1.  

Upon discovery of the lookup service corresponding to the new locator, or upon finding a match between the new locator and a previously discovered lookup service, an event signaling a discovery will be sent to the registration’s listener.

 

 
  1.  

Whenever an existing locator is removed from the managed set … If the lookup service has yet to be discovered for the registration, attempts to perform locator discovery of that lookup service will cease.

 

 
  1.  

Whenever an existing locator is removed from the managed set … If the lookup service has already been discovered for the registration through locator discovery, but not through group discovery, the lookup service will be discarded

 

 
  1.  

the lookup discovery service will discard a lookup service: … In response to a discard request resulting from an invocation of a registration’s discard method

 

 
  1.  

the lookup discovery service will discard a lookup service: … When a lookup service — previously discovered through locator discovery — is removed from a registration’s managed set, in response to an invocation of either the setLocators method or the removeLocators method

 

 
  1.  

the lookup discovery service will discard a lookup service: … When the multicast announcements from an already-discovered lookup service are no longer being received

 

 
  1.  

whenever the lookup discovery service discards a lookup service, it will send an event to the registration to notify it that the lookup service has been discarded.

 

 
  1.  

The discard method takes a single argument: the proxy to the lookup service to discard. This method takes no action if the parameter to this method equals none of the proxies reflected in the managed set (using proxy equality as defined in the Jini™ Lookup Service Specification).

 

 
  1.  

This means that for each of the registration’s targeted lookup services, after a lookup service is initially discovered, the lookup discovery service will not attempt to discover that lookup service again (for that registration) until that lookup service is discarded.

 

 
  1.  

That is, upon re-discovery of the lookup service, only those registrations through which this method is invoked will be notified.

 

 
  1.  

Instances of the RemoteDiscoveryEvent class are passed to the RemoteEvent listener implemented by the client and registered with the lookup discovery service.

 

 
  1.  

The isDiscarded method returns a boolean that indicates whether the event is a discovery event or a discard event.

 

 
  1.  

The getRegistrars method returns an array of ServiceRegistrar objects. The elements contained in the returned array are the proxies that correspond to lookup services that were either newly discovered, re-discovered, discarded, or had their group sets modified.

 

 
  1.  

Note that the event sequence numbers, as defined earlier in this chapter in the section titled Event Semantics, are strictly increasing — even when the information is batched.

 

 
  1.  

The getRegistrars method does not make a remote call.

 

 
  1.  

The same array is returned on multiple invocations of this method.