JINI LOOKUP DISCOVERY SERVICE,version 1.1
`
`161
`
`After acquiring references to the targeted lookup services, the lookup discovery
`service would pass those references to the entity, providing the entity with access
`to the services registered with each lookupservice. In this way, the entity partici-
`pates in the multicast discovery protocols through a proxy relationship with the
`lookup discovery service, gaining access not only to lookup services outside ofits
`ownrange,but also toall of the services registered with those lookup services.
`Note that the scenario just described does not come withoutrestrictions. For
`the lookup discovery service to be able to “link” an entity with lookup services in
`the way just described, the lookup discovery service must be registered with a
`lookupservice having a location that either is knownto the entity or is within the
`multicast radius of the entity. Furthermore, the lookup discovery service must be
`running on a host that is located within the multicast radius of the lookup services
`with which the entity wishes to be linked. That is, the entity must be able to find
`the lookup discovery service, and the lookup discovery service must be able to
`find the other desired lookup services.
`To address these scenarios, the lookup discovery service participates in both
`the multicast discovery protocols and the unicast discovery protocol on behalf of a
`registered discovering entity or client. This service will listen for and process mul-
`ticast announcement packets from Jini lookup services and will, until successful,
`repeatedly attempt to discover specific lookup services that the client is interested
`in finding.
`Upon discovery of a previously undiscovered lookupservice of interest, the
`lookup discovery service notifies all entities that have requested the discovery of
`that
`lookup service that such an event has occurred. The event mechanism
`employed by the lookup discovery service satisfies the requirements defined in
`The Jini Technology Core Platform Specification, “Distributed Events’’. Note that
`the entity that receives such an event notification does not have to be the client of
`the lookup discovery service; it may be a third-party event-handling service such
`as an event mailbox service. Oncea client is notified of the discovery of a lookup
`service, it is left to the client to define the semantics of how it interacts with that
`lookup service. For example, the client may wish to join the lookup service, sim-
`ply query it for other useful services, or both.
`The lookup discovery service must be implemented as a well-behaved Jini
`service and must comply with all of the policies embodied in the Jini technology
`programming model. Thus, the resources granted by this service are leased, and
`implementations of this service must adhere to the distributed leasing model for
`Jini technology as defined in The Jini Technology Core Platform Specification,
`“Distributed Leasing’’. That is, the lookup discovery service will grant its ser-
`vices for only a limited period of time without an active expression of continuing
`interest on the part of the client.
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`171
`
`171
`
`

`

`162
`
`INTRODUCTION
`
`LD.1.1 Goals and Requirements
`
`The requirements of the interfaces and classes specified in this documentare:
`
`@ To define a service that not only employsthe Jini discovery protocolsto dis-
`cover, by way of either group association or LookupLocator association,
`lookupservices in which clients have registered interest, but that also noti-
`fies its clients of the discovery of those lookup services
`To providethis service in such a waythatit can be used byentities that deac-
`tivate
`
`@ To comply with the policies of the Jini technology programming model
`
`The goals of this documentare as follows:
`
`To describe the lookup discovery service
`To provide guidance in the use and deploymentof services that implement
`the LookupDiscoveryService interface and related classes and interfaces
`
`LD.1.2. Other Types
`
`The types defined in the specification of the LookupDiscoveryService interface
`are in the net. jini.discovery package. The following object types mayberef-
`erenced in this chapter. Whenever referenced, these object types will be refer-
`enced in unqualified form:
`
`.core
`
`.discovery.LookupLocator
`.core.
`event.EventRegistration
`event .RemoteEventListener
`
`.core.
`
`net.
`
`net.
`
`net.
`
`net.
`
`net.
`
`net.
`
`net.
`
`net.
`
`net.
`
`jini
`jini
`jini
`jini
`lease.Lease
`lookup. ServiceID
`jini
`lookup.ServiceRegistrar
`jini
`. discovery .DiscoveryEvent
`jini
`. discovery .DiscoveryGroupManagement
`jini
`.discovery.DiscoveryListener
`jini
`java
`.10. IOException
`java.
`rmi .MarshalledObject
`java.
`rmi .NoSuchObjectException
`java.
`rmi .RemoteException
`java.
`util .Map
`
`.core.
`
`.core.
`
`.core.
`
`172
`
`172
`
`

`

`JINI LOOKUP DISCOVERY SERVICE,version 1.1
`
`163
`
`
`
`
`LD.2 The Interface
`
`Tue LookupDiscoveryService interface defines the service—teferredto as the
`lookup discovery service—previously introduced in this specification. Through
`this interface, other Jini services and clients may request that discovery processing
`be performedon their behalf. This interface belongs to the net. jini.discovery
`package, and any service implementing this interface must comply with the defi-
`nition of a Jini service. This interface is not a remote interface; each implementa-
`tion of this service exports a front-end proxy object that implements this interface
`local to the client, using an implementation-specific protocol to communicate with
`the actual remote server (the back end). All of the proxy methods mustobey nor-
`mal Java Remote Method Invocation (RMI) remote interface semantics except
`where explicitly noted. Two proxy objects are equal (using the equals method)if
`they are proxies for the same lookup discovery service.
`The one method defined in this interface throws a RemoteException, and
`requires only the default serialization semantics so that this interface can be
`implementeddirectly using Java RMI.
`
`package net.jini.discovery;
`
`public interface LookupDiscoveryService {
`public LookupDiscoveryRegistration register(
`String[] groups,
`locators,
`LookupLocator[]
`RemoteEventListener listener,
`MarshalledObject handback,
`long leaseDuration)
`throws RemoteException;
`
`} W
`
`hen requesting a registration with the lookup discovery service, the client
`indicates the lookup servicesit is interested in discovering by submitting twosets
`of objects. Each set may contain zero or more elements. One set consists of the
`namesof the groups whose membersare lookup services the client wishes to be
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`173
`
`173
`
`

`

`164
`
`THE INTERFACE
`
`discovered. The other set consists of LookupLocator objects, each corresponding
`to a specific lookup service the client wishes to be discovered.
`For each successful registration the lookup discovery service will manage
`both the set of group names and the set of locators submitted. These sets will be
`referred to as the managedset ofgroups and the managedset oflocators, respec-
`tively. The managed set of groups associated with a particular registration con-
`tains the namesof the groups whose members consist of lookup services that the
`client wishes to be discovered through multicast discovery. Similarly, the man-
`aged set of locators contains instances of LookupLocator, each corresponding to
`a specific lookup service that the client wishes to be discovered through unicast
`discovery. The references to the lookup services that have been discovered will be
`maintainedin a set referred to as the managedset oflookup services (or managed
`set of registrars).
`Note that when the general term managedsetis used, it should be clear from
`the context whether groups, locators, or registrars are being discussed. Further-
`more, when the term group discovery or locator discovery is used, it should be
`taken to mean, respectively, the employmentof either the multicast discovery pro-
`tocols or the unicast discovery protocol to discover lookup services that corre-
`spond to membersof the appropriate managedset.
`
`174
`
`174
`
`

`

`JINI LOOKUP DISCOVERY SERVICE,version 1.1
`
`165
`
`
`
`
`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 methodis the only methodspecified by this interface.
`
`LD.3.1 Registration Semantics
`
`An invocation of the register method produces an object—referredto as a regis-
`tration object (or simply a registration)—that is mutable. Thatis, the registration
`object contains methods through which it may be changed. Becauseregistrations
`are mutable, each invocation of the register method producesa newregistration
`object. Thus, the register method is not idempotent.
`The register method may throw a RemoteException. Typically, this excep-
`tion occurs when there is a communication failure between the client and the
`lookup discovery service. When this exception does occur, the registration may or
`maynot 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 registra-
`tion expires oris cancelled.
`The register method takes the following as arguments:
`
`@ A String array, none of whose elements may be nu11, consisting of zero or
`more elements in which each elementis the nameof a group whose mem-
`bers 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 maybe nu11,
`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 COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`175
`
`175
`
`

`

`166
`
`THE SEMANTICS
`
`@ A non-null RemoteEventListener object which specifies the entity that
`will receive events notifying the registration when a lookupservice ofinter-
`est is discovered or discarded
`
`@ Either nu11 or an instance of Marshal ledObject specifying an object that
`will be included in the notification event that the lookup discovery service
`sendsto 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
`implements
`that
`object
`an
`returns
`register method
`The
`LookupDiscoveryRegi stration 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 servicesso 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 inter-
`face).
`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 argumentitself, if the
`argument contains one or more null elements, a Nul1PointerException is
`thrown.If the value is nu11, 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 regis-
`tration’s setGroups or addGroups method, changes the contents of the managed
`set of groups to either a non-empty set of group namesor nu11.
`The locators argument takes an array of LookupLocator objects, none of
`whose elements maybe nu11. If either the empty array or nu11 is passed in as the
`locators argument, then no locator discovery will be performed for the associ-
`ated 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. Althoughit is acceptable to input nu11 for the locators argumentitself,
`if the argument contains one or more nu11 elements, a Nu11PointerException is
`thrown.
`If the register method is invoked with a set of group namesandaset 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 eitherset.
`
`176
`
`176
`
`

`

`JINI LOOKUP DISCOVERY SERVICE,version 1.1
`
`167
`
`Upondiscovery of a lookup service, through either group discovery or locator
`discovery, the lookup discovery service will send an event, referred to as a discov-
`ered event, to the listener associated with the registration produced bythe 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 cur-
`rent group membership, the lookup discovery service may send either a discov-
`ered event or an event referred to as a discarded event. The conditions under
`whicheither 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 memberof 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 changedits group membership in such a
`waythat the lookup serviceis no longerofinterest to one or more ofthe reg-
`istrations that previously registered interest in the groups of that lookupser-
`vice, a discarded event will be sent to the listener of each such registration.
`This type of discarded event is sometimesreferred to as apassive 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 eventwill be sentto the listener of
`each registration that previously registered interest in one or more ofthat
`lookup service’s membergroups. 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) dis-
`cards 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
`lookupservice be discovered throughat least group discovery. Thatis, 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 assumethat since the cli-
`ent, through the registration request, expressed no interest in discovering the
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`177
`
`177
`
`

`

`168
`
`THE SEMANTICS
`
`lookup service through its group membership,the client must also have no interest
`in any group-related changesin 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 argumentof the register
`method. If a nu11 valueis input to this argument, then a Nu11PointerException
`will be thrownandtheregistration fails.
`Note that if an indefinite exception occurs while attempting to send a discov-
`ered 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 assumesthat the client is in an unknown,
`possibly corrupt state, and will cancel the lease on the registration and clear the
`registration from its managedset.
`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 infor-
`mation contains no knowledgeofthe clients that register with the lookup discov-
`ery 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 mapsthe registration to the listener as well as to
`the registration’s managed set of groups and managedset of locators. This event
`identifier is returned as a part of the returned registration object and is unique
`acrossall other active registrations with the lookup discovery service.
`Wheneverthe 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 correspond-
`ing to each such registration. The event sent to each listener will contain the
`appropriate eventidentifier.
`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 discov-
`ery service) and then rediscovered. Note that more information about what it
`
`178
`
`178
`
`

`

`JINI LOOKUP DISCOVERY SERVICE,version 1.1
`
`169
`
`meansfor a lookupserviceto be discarded is presented in Section LD.3.1, “Regis-
`tration Semantics” and the section of this specification titled “Discarding Lookup
`Services”.
`If, between the time a lookupservice is discarded and the time it is rediscov-
`ered, 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
`numbersthat differ by only a value of 1, then no events have been missed. On the
`other hand, whentheset of received events is viewed in order, if the difference
`between the sequence numbersof 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.
`Whena gap occurs between events, the local state (on the client) related to the
`discovered lookup services may or may notfall out of sync with the correspond-
`ing remote state maintained by the lookup discovery service. For example, if the
`gap correspondsto 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 methodthat returns a set consisting of the proxies to
`the lookup services that have been discovered for that registration. With this infor-
`mation the client can updateits 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 handbackobject regis-
`tered by the client with the event mechanism.
`The semantics of the object input to the handback argumentare left to each
`client to define, although nul] may be input to this argument. The role of the
`handback object in the remote event mechanism is detailed in The Jini Technol-
`ogy Core Platform Specification, “Distributed Events”.
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`179
`
`179
`
`

`

`170
`
`THE SEMANTICS
`
`LD.3.3 Leasing Semantics
`
`Whena client registers with the lookup discovery service, it is effectively request-
`ing 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 1leaseDuration argu-
`ment. That value must be positive, Lease. FOREVER, or Lease.ANY. If any other
`value is input to this argument, an I] 1legalArgumentException will be thrown.
`The client may obtain a reference to the Lease object granted by the lookup dis-
`covery service through the associated registration returned by the service (see
`Section LD.4.1, “The LookupDiscoveryRegistration Interface”’).
`
`180
`
`180
`
`

`

`JINI LOOKUP DISCOVERY SERVICE,version 1.1
`
`171
`
`
`
`
`LD.4 Supporting Interfaces and Classes
`
`Tue lookup discovery service depends on the LookupDiscoveryRegistration
`interface, as well as on the concrete classes RemoteDiscoveryEvent and
`LookupUnmarshalException.
`
`LD.4.1 The LookupDiscoveryRegistration Interface
`
`Whena client requests a registration with the lookup discovery service, an object
`that implements the LookupDiscoveryRegistration interface is returned.It is
`through this interface that the client managesthe state of its registration with the
`lookup discovery service.
`
`package net.jini.discovery;
`
`public interface LookupDiscoveryRegistration {
`public EventRegistration getEventRegistrationQ ;
`public Lease getLease();
`public ServiceRegistrar[] getRegistrars()
`throws LookupUnmarshalException,
`RemoteException;
`public String[] getGroups() throws RemoteException;
`public LookupLocator[] getLocatorsQ
`throws RemoteException;
`public void addGroups(String[] groups)
`throws RemoteException;
`public void setGroups(String[] groups)
`throws RemoteException;
`public void removeGroups(String[] groups)
`throws RemoteException;
`public void addLocators(LookupLocator[]
`locators)
`throws RemoteException;
`public void setLocators(LookupLocator[] locators)
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`181
`
`181
`
`

`

`172
`
`SUPPORTING INTERFACES AND CLASSES
`
`throws RemoteException;
`public void removeLocators(LookupLocator[]
`locators)
`throws RemoteException;
`public void discard(ServiceRegistrar registrar)
`throws RemoteException;
`
`} A
`
`the
`interface,
`LookupDiscoveryService
`the
`with
`s
`LookupDiscoveryRegi stration interface is not a remote interface. Each imple-
`mentation of the lookup discovery service exports proxy objects that implement
`this interface local to the client, using an implementation-specific protocol to
`communicate with the actual remote server. All of the proxy methods must obey
`normal Java RMI remote interface semantics except where explicitly noted. Two
`proxy objects are equal (using the equals method) if they are proxies for the same
`registration created by the same lookupdiscovery service.
`The discovery facility of the lookup discovery service, together with its event
`mechanism, make up the set of resources clients register to use. Because the
`resources of the lookup discovery service are leased, access is granted for only a
`limited period of time unlessthere is an active expression of continuing interest on
`the part of the client.
`Whena client uses the registration process to request that a lookup discovery
`service perform discovery of a set of desired lookup services, the client is also
`registered with the service’s event mechanism. Becauseof this implicit registra-
`tion with the event mechanism, the lookup discovery service “bundles” both
`resources undera single lease. Whenthat lease expires, both discovery processing
`and eventnotifications will cease with respect to the registration that resulted from
`the client’s request.
`
`
`
`To and_event handling,_thefacilitate lease management
`
`
`LookupDiscoveryRegistration interface defines methods that allow the client
`to retrieve its event registration information. Additional methods defined by this
`interface allow the client to retrieve references to the registration’s currently dis-
`covered lookup services, as well as to modify the managed sets of groups and
`locators.
`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. That is, any method that communicates
`with the back end server of the lookup discovery service will
`throw a
`NoSuchObjectExceptionif the registration on which the method is invoked no
`longer exists. Note that if a client receives a NoSuchObjectException asa result
`of an invocation of such a method, although the client can assumethat the regis-
`
`182
`
`182
`
`

`

`JINI LOOKUP DISCOVERY SERVICE,version 1.1
`
`173
`
`tration no longerexists, the client cannot assumethat the lookup discovery service
`itself no longerexists.
`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 lookup discovery service. Whenever this exception occurs as a
`result of the invocation of one of these methods, the method may or may not have
`completed its processing successfully.
`
`LD.4.1.1 The Semantics
`
`The methodsdefined by this interface are organized into a set of accessor meth-
`ods, a set of group mutator methods, a set of locator mutator methods, and the
`discard method. Through the accessor methods, various elements of a registra-
`tion’s state can be retrieved. The mutator methods provide a mechanism for
`changing the set of groups and locators to be discovered for the registration.
`Through the discard method, a particular lookup service may be madeeligible
`for rediscovery.
`
`The Accessor Methods
`
`The getEventRegistration method returns an EventRegistration object that
`encapsulates the information the client needs to identify a notification sent by the
`lookup discovery service to the registration’s listener. This method is not remote
`and takes no arguments.
`The getLease method returns the Lease object that controls a client’s regis-
`tration with the lookup discovery service. It is through the Lease object returned
`by this method that the client requests the renewal or cancellation of the registra-
`tion with the lookup discovery service. This method is not remote and takes no
`arguments.
`Note that the object returned by the getEventRegistration methodalso
`provides a getLease method. That method and the getLease method defined by
`the LookupDiscoveryRegi stration interface both return the same Lease object.
`The getLease methoddefined here is provided as a convenienceto avoid the indi-
`rection associated with the getLease method on the EventRegistration object,
`as well as to avoid the overhead of making two methodcalls.
`the
`instances of
`The getRegistrars method
`returns
`a
`set of
`ServiceRegistrar interface. Each element in the set is a proxy to one of the
`lookup services that have already been discovered for the registration. Addition-
`ally, each elementin the set will be unique with respectto all other elements in the
`set, as determined by the equals method provided by each element. The contents
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`183
`
`183
`
`

`

`174
`
`SUPPORTING INTERFACES AND CLASSES
`
`of the set make up the current remote state of the set of lookup services discovered
`for the registration. This method returns a new array on each invocation.
`This method can be used to maintain synchronization between the set of dis-
`covered lookup services making uparegistration’s local state on the client and the
`registration’s corresponding remote state maintained by the lookup discovery ser-
`vice. The local state can become unsynchronized with the remote state when a gap
`occurs in the events received bythe registration’s listener.
`According to the event semantics of the lookup discovery service, if there is
`no gap between two sequence numbers, no events have been missed andthestates
`remain synchronized with each other; if there is a gap, events may or maynot
`have been missed. Therefore, upon finding gaps in the sequenceof events,the cli-
`ent can invoke this method and use the returned information to synchronize the
`local state with the remotestate.
`To construct its return set, the getRegistrars method retrieves from the
`lookup discovery service the set of lookup service proxies making uptheregistra-
`tion’s current remote state. When the lookup discovery service sends the
`requested set of proxies, the set is sent as a set of marshalled instances of the
`ServiceRegistrar interface. The lookup discovery service individually marshals
`each proxyin the set that it sends becauseif it were not to do so, any deserializa-
`tion failure on the set would result in an IOException, and failure would be
`declared for the whole deserialization process, not just an individual element. This
`would mean that all elements of the set sent by the lookup discovery service—
`even those that were successfully deserialized—would be unavailable to the cli-
`ent. Individually marshalling each element in the set minimizes the “all or noth-
`ing” aspect of the deserialization process, allowing the client to recover those
`proxies that can be successfully unmarshalled and to proceed with processing that
`might not be possible otherwise.
`Whenconstructing the return set, this method attempts to unmarshal eachele-
`ment of the set of marshalled proxy objects sent by the lookup discovery service.
`Whenfailure occurs while attempting to unmarshal any of those elements, this
`method throws an exception of type LookupUnmarshalException (described
`later). It is through the contents of that exception that the client can recover any
`available proxies and perform error handling related to the unavailable proxies.
`The contents of the LookupUnmarshalException provide the client with the fol-
`lowing useful information:
`
`@ The knowledgethat a problem has occurred while unmarshalling at least one
`of the elements making up the remote state of the registration’s discovered
`lookupservices
`
`184
`
`184
`
`

`

`JINI LOOKUP DISCOVERY SERVICE,version 1.1
`
`175
`
`@ The set of proxy objects that were successfully unmarshalled by the
`getRegistrars method
`
`@ The set of marshalled proxy objects that could not be unmarshalled by the
`getRegistrars method
`
`The set of exceptions correspondingto each failed attempt at unmarshalling
`
`The type of exception that occurs when attempting to unmarshal an element
`of the set sent by the lookup discovery service is typically an IOException or a
`ClassNotFoundException (usually the more
`common of
`the
`two). A
`ClassNotFoundException occurs whenever a remote object on which the mar-
`shalled proxy depends cannot be retrieved and loaded, usually because the code-
`base of one of the object’s classes or interfaces is currently “down.” To address
`this situation, the client may wish to proceed with its processing using the suc-
`cessfully unmarshalled proxies, and attempt to unmarshal the unavailable proxies
`(or re-invoke this method) at somelater time.
`throwing a
`If the getRegistrars method returns successfully without
`LookupUnmarshalException, the client is guaranteed that all marshalled proxies
`belonging to the set sent by the lookup discovery service have each been success-
`fully unmarshalled; the