LD.3. The Semantics
To employ the lookup discovery service to perform discovery on its behalf, a client must first register with the lookup discovery service by invoking the register method defined in the LookupDiscoveryService interface. The register method is the only method specified by this interface.
LD.3.1. Registration Semantics
An invocation of the register method produces an object—referred to as a registration object (or simply a registration)—that is mutable. That is, the registration object contains methods through which it may be changed. Because registrations are mutable, each invocation of the register method produces a new registration object. Thus, the register method is not idempotent.
The register method may throw a RemoteException. Typically, this exception occurs when there is a communication failure between the client and the lookup discovery service. When this exception does occur, the registration may or may not have been successful.
Each registration with the lookup discovery service is persistent across restarts (or crashes) of the lookup discovery service until the lease on the registration expires or is cancelled.
The register method takes the following as arguments:
A String array, none of whose elements may be null, consisting of zero or more elements in which each element is the name of a group whose members are lookup services that the client requesting the registration wishes to be discovered via group discovery
An array of LookupLocator objects, none of whose elements may be null, consisting of zero or more elements in which each element corresponds to a specific lookup service that the client requesting the registration wishes to be discovered via locator discovery
A nonnull RemoteEventListener object which specifies the entity that will receive events notifying the registration when a lookup service of interest is discovered or discarded
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
A long value representing the amount of time (in milliseconds) for which the resources of the lookup discovery service are being requested
The register method returns an object that implements the LookupDiscoveryRegistration interface. It is through this returned object that the client interacts with the lookup discovery service. This interaction includes activities such as group and locator management, state retrieval, and discarding discovered but unavailable lookup services so that they are eligible for rediscovery (see Section LD.4.1, “The LookupDiscoveryRegistration Interface” for definition of the semantics of the methods of the LookupDiscoveryRegistration interface).
The groups argument takes a String array, none of whose elements may be null. Although it is acceptable to specify null (which is equivalent to DiscoveryGroupManagement.ALL_GROUPS) for the groups argument itself, if the argument contains one or more null elements, a NullPointerException is thrown. 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 an empty array (equivalent to DiscoveryGroupManagement.NO_GROUPS) is passed in, then no group discovery will be performed for the associated registration until the client, through the registration’s setGroups or addGroups method, changes the contents of the managed set of groups to either a non-empty set of group names or null.
The locators argument takes an array of LookupLocator objects, none of whose elements may be null. 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 the registration’s addLocators or setLocators method, changes the managed set of locators to a non-empty set of locators. Although it is acceptable to input null for the locators argument itself, if the argument contains one or more null elements, a NullPointerException is thrown.
If the register method is invoked with a set of group names and a set of locators in which either or both sets contain duplicate elements (where duplicate locators are determined by LookupLocator.equals), the invocation is equivalent to constructing this class with no duplicates in either set.
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 discovered event, to the listener associated with the registration produced by the call to register.
After initial discovery of a lookup service, the lookup discovery service will continue to monitor the group membership state reflected in the multicast announcements from that lookup service. Depending on the lookup service’s current group membership, the lookup discovery service may send either a discovered event or an event referred to as a discarded event. The conditions under which either a discovered event or a discarded event will be sent are as follows:
If the multicast announcements from an already discovered lookup service indicate that the lookup service is a member of a new group, a discovered event will be sent to the listener of each registration that has yet to receive a discovered event for that lookup service, but that has previously registered interest in the new group.
If the multicast announcements from an already discovered lookup service indicate that the lookup service has changed its group membership in such a way that the lookup service is no longer of interest to one or more of the registrations that previously registered interest in the groups of that lookup service, a discarded event will be sent to the listener of each such registration. This type of discarded event is sometimes referred to as a passive no-interest discarded event (“passive” because the lookup discovery service, rather than the client, initiated the discard process).
If the multicast announcements from an already discovered lookup service are no longer being received, a discarded event will be sent to the listener of each registration that previously registered interest in one or more of that lookup service’s member groups. This type of discarded event is sometimes referred to as a passive communication discarded event.
It is important to note that when the lookup discovery service (passively) discards a lookup service, due to group membership changes (lost interest) or unavailability (communication failure), the discarded event will be sent to only the listeners of those registrations that have previously requested that the affected lookup service be discovered through at least group discovery. That is, the listener of any registration that is interested in the affected lookup service through only locator discovery will not be sent either type of passive discarded event. This is because the semantics of the lookup discovery service assume that since the client, through the registration request, expressed no interest in discovering the lookup service through its group membership, the client must also have no interest in any group-related changes in that lookup service’s state.
A more detailed discussion of the event semantics of the lookup discovery service is presented in Section LD.3.2, “Event Semantics”.
A valid parameter must be passed as the listener argument of the register method. If a null value is input to this argument, then a NullPointerException will be thrown and the registration fails.
Note that if an indefinite exception occurs while attempting to send a discovered or discarded event to a registration’s listener, the lookup discovery service will continue to attempt to send the event until either the event is successfully delivered or the client’s lease on that registration expires. If an UnknownEventException, a bad object exception, or a bad invocation exception occurs while attempting to send a discovered or discarded event to a registration’s listener, the lookup discovery service assumes that the client is in an unknown, possibly corrupt state, and will cancel the lease on the registration and clear the registration from its managed set.
The state information maintained by the lookup discovery service includes the set of group names, locators, and listeners submitted by each client through each invocation of the register method, with duplicates eliminated. This state information contains no knowledge of the clients that register with the lookup discovery service. Thus, there is no requirement that a client identify itself during the registration process.
LD.3.2. Event Semantics
For each registration created by the lookup discovery service, an event identifier will be generated that uniquely maps the registration to the listener as well as to the registration’s managed set of groups and managed set of locators. 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.
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 subclass of RemoteEvent) to the listener corresponding to each such registration. The event sent to each listener will contain the appropriate event identifier.
Once an event signaling the discovery (by group or locator) of a desired lookup service has been sent, no other discovered events for that lookup service will be sent to a registration’s listener until the lookup service is discarded (either actively, by the client through the registration, or passively by the lookup discovery service) and then rediscovered. Note that more information about what it means for a lookup service to be discarded is presented in Section LD.3.1, “Registration Semantics” and the section of this specification titled “Discarding Lookup Services”.
If, between the time a lookup service is discarded and the time it is rediscovered, a new registration is requested having parameters indicating interest in that lookup service, upon rediscovery of the lookup service an event will also be sent to that new registration’s listener.
The sequence numbers for a given event identifier are strictly increasing (as defined in The Jini Technology Core Platform Specification, “Distributed Events”), which means that when any two such successive events have sequence numbers that differ by only a value of 1, then no events have been missed. On the other hand, when the set of received events is viewed in order, if the difference between the sequence numbers of two successive events is greater than 1, then one or more events may or may not have been missed. For example, a difference greater than 1 could occur if the lookup discovery service crashes, even if no events are lost because of the crash. When two such successive events have sequence numbers whose difference is greater than 1, there is said to be a gap between the events.
When a gap occurs between events, the local state (on the client) related to the discovered lookup services may or may not fall out of sync with the corresponding remote state maintained by the lookup discovery service. For example, if the gap corresponds to a missed event representing the (initial) discovery of a targeted lookup service, the remote state will reflect this discovery, whereas the client’s local state will not. To allow clients to identify and correct such a situation, each registration object provides a method that returns a set consisting of the proxies to the lookup services that have been discovered for that registration. With this information the client can update its local state.
When requesting a registration with the lookup discovery service, a client may also supply (as a parameter to the register method) a reference to an object, wrapped in a MarshalledObject, referred to as a handback. When the lookup discovery service sends an event to a registration’s listener, the event will also contain a reference to this handback object. The lookup discovery service will not change the handback object. That is, the handback object contained in the event sent by the lookup discovery service will be identical to the handback object registered by the client with the event mechanism.
The semantics of the object input to the handback argument are left to each client to define, although null may be input to this argument. The role of the handback object in the remote event mechanism is detailed in The Jini Technology Core Platform Specification, “Distributed Events”.
LD.3.3. Leasing Semantics
When a client registers with the lookup discovery service, it is effectively requesting a lease on the resources provided by that service. 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. That value must be positive, Lease.FOREVER, or Lease.ANY. If any other value is input to this argument, an IllegalArgumentException will be thrown. The client may obtain a reference to the Lease object granted by the lookup discovery service through the associated registration returned by the service (see Section LD.4.1, “The LookupDiscoveryRegistration Interface”).