JINI LOOKUP DISCOVERY SERVICE, version 1.1
`
`1 61
`
`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 lookup service. 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 of its
`own range, but also to all of the services registered with those lookup services.
`Note that the scenario just described does not come without restrictions. 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
`lookup service having a location that either is known to 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 lookup service 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. Once a 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 JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`171
`
`171
`
`

`

`162
`
`UWRODUCHON
`
`LD.1.1 Goals and Requirements
`
`The requirements of the interfaces and classes specified in this document are:
`
`0 To define a service that not only employs the Jini discovery protocols to dis-
`cover, by way of either group association or LookupLocator‘ association,
`lookup services in which clients have registered interest, but that also noti-
`fies its clients of the discovery of those lookup services
`
`0 To provide this service in such a way that it can be used by entities that deac-
`tivate
`
`0 To comply with the policies of the Jini technology programming model
`
`The goals of this document are as follows:
`
`9 To describe the lookup discovery service
`
`9 To provide guidance in the use and deployment of services that implement
`the Lookuij scove rySe rv1' ce interface and related classes and interfaces
`
`LD.1.2 Other Types
`
`The types defined in the specification of the Lookuij scove rySe rv1' ce interface
`are in the net. j 1' nj .dj scove ry package. The following object types may be ref-
`erenced in this chapter. Whenever referenced, these object types will be refer-
`enced in unqualified form:
`
`net.
`
`net.
`
`net.
`
`net.
`
`net.
`
`net.
`
`net.
`
`net.
`
`net.
`
`.djscovery.LookupLocator
`jjnj.
`.core.
`
`COPE
`
`jjnj
`
`event . EventReg‘i stratj on
`event. RemoteEventLi stener
`
`.core.
`
`jjnj
`
`core.
`
`jjnj.
`.core.
`
`jjnj
`
`lease. Lease
`
`lookup . Se rv1' ceID
`
`jjnj.
`
`COPE
`
`.lookup.ServjceRegjstrar
`
`jjnj
`
`.djscovery.DjscoveryEvent
`
`jjnj
`
`.djscovery.DjscoveryGroupManagement
`
`jjnj
`
`.djscovery.Djscoverijstener
`
`java
`
`.jo.IOExceptjon
`
`java
`
`.rmj.Marsha11ed0bject
`
`java
`
`.rmj.NoSuchObjectExceptjon
`
`java
`
`.rmj.RemoteExceptjon
`
`java
`
`.utj1.Map
`
`172
`
`172
`
`

`

`JINI LOOKUP DISCOVERY SERVICE, version 1.1
`
`1 63
`
`
`
`
`LD.2 The Interface
`
`THE LookupDi scove ryServi ce interface defines the service—referred to as the
`lookup discovery service—previously introduced in this specification. Through
`this interface, other Jini services and clients may request that discovery processing
`be performed on their behalf. This interface belongs to the net. ji ni .di scove ry
`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 must obey 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 RemoteExcepti on , and
`
`requires only the default serialization semantics so that this interface can be
`implemented directly using Java RMI.
`
`package net .ji ni .di scovery;
`
`public interface LookupDiscoveryService {
`
`public LookupDiscoveryRegistration registerC
`
`String[] groups,
`
`LookupLocatorE]
`
`locators,
`
`RemoteEventListener listener,
`
`MarshalledObject handback,
`
`long leaseDuration)
`
`throws RemoteException;
`
`} W
`
`hen requesting a registration with the lookup discovery service, the client
`indicates the lookup services it is interested in discovering by submitting two sets
`of objects. Each set may contain zero or more elements. One set consists of the
`names of the groups whose members are lookup services the client wishes to be
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`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 managed set ofgroups and the managed set of locators, respec-
`tively. The managed set of groups associated with a particular registration con-
`tains the names of 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
`maintained in a set referred to as the managed set of lookup services (or managed
`set of registrars).
`Note that when the general term managed set is 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 employment of either the multicast discovery pro-
`tocols or the unicast discovery protocol to discover lookup services that corre-
`spond to members of the appropriate managed set.
`
`174
`
`174
`
`

`

`JINI LOOKUP DISCOVERY SERVICE, version 1.1
`
`1 65
`
`
`
`
`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 LookupDiscove ryServi ce interface. The
`
`register method is the only method specified by this interface.
`
`LD.3.1 Registration Semantics
`
`An invocation of the regi ste r method produces an obj ect—referred to as a regis—
`tration 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 RemoteExcepti on. 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
`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 registra-
`tion expires or is cancelled.
`The register method takes the following as arguments:
`
`o A St ri ng 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 mem-
`bers are lookup services that the client requesting the registration wishes to
`be discovered Via group discovery
`
`9 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 COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`175
`
`175
`
`

`

`166
`
`THE SEMANTICS
`
`9 A non-null RemoteEventLi stener object which specifies the entity that
`will receive events notifying the registration when a lookup service of inter-
`est is discovered or discarded
`
`0 Either null or an instance of Marshal l edObj ect specifying an object that
`will be included in the notification event that the lookup discovery service
`sends to the registered listener
`
`o 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
`LookupDi scove ryReg1' st ration 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.l, “The LookupDiscoveryRegistration Interface” for definition
`of the semantics of the methods of the LookupDiscoveryRegi stration 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
`D1' scove ryG roupManagement .ALL_GROU PS) for the groups argument itself, if the
`argument contains one or more null elements, a Null Po1' nterException 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
`D1" scove r'yGroupManagement . NO_GROUPS) is passed in, then no group discovery
`will be performed for the associated registration until the client, through the regis-
`tration’s setG roups or addG roups 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 associ-
`ated registration until
`the client,
`through the registration’s addLocato rs 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 Null Poi nterExcepti on 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‘ . equal 5), the invocation is equivalent
`to constructng this class with no duplicates in either set.
`
`176
`
`176
`
`

`

`JINI LOOKUP DISCOVERY SERVICE, version 1.1
`
`1 67
`
`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 discov—
`ered event, to the listener associated with the registration produced by the call to
`
`regi ste r.
`
`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
`
`which either a discovered event or a discarded event will be sent are as follows:
`
`9 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.
`
`9 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 reg-
`istrations that previously registered interest in the groups of that lookup ser-
`vice, 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).
`
`9 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) 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
`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 cli-
`ent, through the registration request, expressed no interest in discovering the
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`177
`
`177
`
`

`

`168
`
`THE SEMANTICS
`
`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 11' stener‘ argument of the regi ster
`method. If a null value is input to this argument, then a Null Po1' nterException
`will be thrown and the registration 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 successfiilly
`delivered
`or
`the
`client’s
`lease
`on
`that
`registration
`expires.
`If
`an
`Unknown EventExcepti on, 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 infor-
`mation contains no knowledge of the 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 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
`RemoteDi scove ryEvent (a subclass of RemoteEvent) to the listener correspond-
`ing 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 discov-
`ery service) and then rediscovered. Note that more information about what it
`
`178
`
`178
`
`

`

`JINI LOOKUP DISCOVERY SERVICE, version 1.1
`
`1 69
`
`means for a lookup service to 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 lookup service 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
`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 correspond-
`ing 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 infor-
`mation 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 regis-
`tered 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 Technol-
`ogy Core Platform Specification, “Distributed Events
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`179
`
`179
`
`

`

`170
`
`THE SEMANTICS
`
`LD.3.3 Leasing Semantics
`
`When a 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 leaseDu ration argu-
`ment. 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 dis-
`covery service through the associated registration returned by the service (see
`Section LD.4.l, “The LookupDiscoveryRegistration Interface”).
`
`180
`
`180
`
`

`

`JINI LOOKUP DISCOVERY SERVICE, version 1.1
`
`1 71
`
`
`
`
`LD.4 Supporting Interfaces and Classes
`
`THE lookup discovery service depends on the LookupDi scove ryRegi strati on
`interface, as well as on the concrete classes RemoteDi scove ryEvent and
`
`LookupUnmarshalException.
`
`LD.4.1 The LookupDi scove ryRegi stration Interface
`
`When a client requests a registration with the lookup discovery service, an object
`thatinqflennnfisthe LookupDiscoveryRegistration uneflhceisreuuned.ltis
`through this interface that the client manages the state of its registration with the
`lookup discovery service.
`
`package net .ji ni .di scovery;
`
`public interface LookupDiscoveryRegistration {
`
`public EventRegistration getEventRegistrationC);
`
`public Lease getLeaseC);
`
`public ServiceRegistrarE] getRegistrarsC)
`
`throws LookupUnmarshalException,
`
`RemoteException;
`
`public String[] getGroupsC) throws RemoteException;
`
`public LookupLocatorE] getLocatorsC)
`
`throws RemoteException;
`
`public void addGroupsCStringE] groups)
`
`throws RemoteException;
`
`public void setGroupsCStringE] groups)
`
`public void removeGroupsCStringE] groups)
`
`public void addLocators(LookupLocator[]
`
`locators)
`
`throws RemoteException;
`
`throws RemoteException;
`
`throws RemoteException;
`
`public void setLocators(LookupLocator[] locators)
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`181
`
`181
`
`

`

`172
`
`SUPPORTING INTERFA CES AND CLASSES
`
`throws RemoteException;
`
`public void removeLocators(LookupLocator[]
`
`locators)
`
`throws RemoteException;
`
`public void discardCServiceRegistrar registrar)
`
`throws RemoteException;
`
`with
`
`the
`
`Looku pD1' scove ryServ1' ce
`
`interface,
`
`the
`
`} A
`
`s
`
`LookupDi scove ryReg1' strat1' on 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 lookup discovery 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 unless there is an active expression of continuing interest on
`the part of the client.
`When a 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. Because of this implicit registra-
`tion with the event mechanism, the lookup discovery service “bundles” both
`resources under a single lease. When that lease expires, both discovery processing
`and event notifications will cease with respect to the registration that resulted from
`the client’s request.
`the
`handling,
`event
`and
`management
`lease
`To
`facilitate
`LookupDi scove ryReg1' st ration 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 NoSuchObj ectExcepti on. That is, any method that communicates
`with the back end server of the lookup discovery service will
`throw a
`NoSuchObjectExcepti on if the registration on which the method is invoked no
`longer exists. Note that if a client receives a NoSuchObj ectExcepti on as a result
`of an invocation of such a method, although the client can assume that the regis-
`
`182
`
`182
`
`

`

`JINI LOOKUP DISCO VERY SER VICE, version 1.1
`
`173
`
`tration no longer exists, the client cannot assume that the lookup discovery service
`itself no longer exists.
`Each remote method of this interface may throw a RemoteExcepti on. 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 methods defined 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 made eligible
`for rediscovery.
`
`The Accessor Methods
`
`The getEventRegi stration method returns an EventRegi stration 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 method also
`provides a getLease method. That method and the getLease method defined by
`the LookupDi scove ryRegi strati on interface both return the same Lease object.
`The getLease method defined here is provided as a convenience to avoid the indi-
`rection associated with the getLease method on the EventRegi st rati on object,
`as well as to avoid the overhead of making two method calls.
`The
`getRegi st rar‘s method
`returns
`a
`set of
`
`instances of
`
`the
`
`Se rvi ceRegist rar 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 element in the set will be unique with respect to all other elements in the
`set, as determined by the equals method provided by each element. The contents
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`183
`
`183
`
`

`

`174
`
`SUPPORTING INTERFA CES 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 up a registration’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 by the 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 and the states
`remain synchronized with each other; if there is a gap, events may or may not
`have been missed. Therefore, upon finding gaps in the sequence of events, the cli-
`ent can invoke this method and use the returned information to synchronize the
`local state with the remote state.
`
`To construct its return set, the getRegi st rars method retrieves from the
`
`lookup discovery service the set of lookup service proxies making up the registra-
`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
`Se rv1' ceRegi st rar interface. The lookup discovery service individually marshals
`each proxy in the set that it sends because if it were not to do so, any deserializa-
`tion failure on the set would result in an IOExcepti on, 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.
`When constructing the return set, this method attempts to unmarshal each ele-
`ment of the set of marshalled proxy objects sent by the lookup discovery service.
`When failure occurs while attempting to unmarshal any of those elements, this
`method throws an exception of type LookupUnmarsha'l Exception (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 LookupUnmarshal Exception provide the client with the fol-
`lowing useful information:
`
`o The knowledge that a problem has occurred while unmarshalling at least one
`of the elements making up the remote state of the registration’s discovered
`lookup services
`
`184
`
`184
`
`

`

`JINI LOOKUP DISCOVERY SERVICE, version 1.1
`
`1 75
`
`9 The set of proxy objects that were successfully unmarshalled by the
`getReg‘i strars method
`
`9 The set of marshalled proxy objects that could not be unmarshalled by the
`getReg‘i strars method
`
`9 The set of exceptions corresponding to 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 IOExcepti on or a
`C1 assNotFoundException (usually the more
`common of
`the
`two). A
`C1 assNotFoundExcepti on 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 clie