JINI DISCO VERY UTILITIES SPECIFICA TION, version 1.1
`
`3 1
`
`If the managed set of groups is empty, this method will return an empty array.
`If there is no managed set of groups, then null (AL L_GROU P5) is returned, indicat-
`ing that any lookup service within range—even those that have no group aflilia-
`tion—are to be discovered.
`
`If an empty array is returned, that array is guaranteed to be referentially equal
`to the N0_GROU PS constant; that is, the array returned from that method and the
`NO_GROU PS constant can be tested for equality using the == operator.
`This method takes no arguments as input and, provided the managed set of
`groups currently exists, will return a new array upon each invocation.
`The addG roups method adds a set of group names to the managed set. The
`array input to this method contains the group names to be added to the set.
`This method throws IOExcepti on because an invocation of this method may
`result in the re-initiation of the discovery process, which can throw IOExcepti on
`when socket allocation occurs.
`
`This method throws an UnsupportedOperationException if there is no
`
`managed set of groups to augment, and it throws a NuHPoi nterException if
`nu'l'l (AL L_GROU PS) is input. If an empty array (NO_GROU P5) is input, the managed
`set of groups will not change.
`The setG roups method replaces all of the group names in the managed set
`with names from a new set. The array input to this method contains the group
`names with which to replace the current names in the managed set.
`Once a new group name has been placed in the managed set, no event will be
`sent to the entity’s listener for the lookup services belonging to that group that
`have already been discovered, although attempts to discover all (as yet) undiscov-
`ered lookup services belonging to that group will continue to be made.
`If nu'l'l
`(ALL_GROUPS) is input to setG roups, then attempts will be made to
`discover all (as yet) undiscovered lookup services located within the multicast
`radius (Section DU.3, “LookupDiscovery Utility”) of the implementation object,
`regardless of group membership.
`If an empty array (NO_GROUPS) is input to setG roups, then group discovery
`will be halted until the managed set of groups is changed—through a subsequent
`call to this method or to addG roups—to a set that is either a non-empty set of
`group names or nu11 (ALL_GROUPS).
`This method throws IOExcepti on. This is because an invocation of this
`
`method may result in the re-initiation of the discovery process, a process that can
`throw IOExcepti on when socket allocation occurs.
`
`The removeGroups method deletes a set of group names from the managed
`set of groups. The array input to this method contains the group names to be
`removed from the managed set.
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`41
`
`41
`
`

`

`32
`
`THE DISC0 VERY [MANAGEMENT INTERFA CES
`
`This method throws an UnsupportedOperationException if there is no
`
`managed set of groups from which to remove elements. If null (ALL_GROUPS) is
`input to removeGroups, a Null Poi nterException will be thrown.
`If any element of the set of groups to be removed is not contained in the man-
`aged set, removeG roups takes no action with respect to that element. If an empty
`array (N0_GROU P5) is input, the managed set of groups will not change.
`Once a new group name is added to the managed set as a result of an invoca-
`tion of either addG roups or setG roups, attempts will be made—using the multi-
`cast request protocol—to discover all (as yet) undiscovered lookup services that
`are members of that group. If there are no responses to the multicast requests, the
`implementation object will stop sending multicast requests, and will simply listen
`for multicast announcements containing the new groups of interest.
`Any already discovered lookup service that is a member of one or more of the
`groups removed from the managed set as a result of an invocation of either
`setG roups or removeG roups will be discarded and will no longer be eligible for
`discovery, but only if that lookup service satisfies both of the following condi-
`tions:
`
`9 the lookup service is not a member of any group in the new managed set that
`resulted from the invocation of setG roups or removeG roups, and
`
`c the lookup service is not currently eligible for discovery through other
`means (such as locator discovery).
`
`DU.2.5 The Di scover'yLocator'Management Interface
`
`The public methods specified by the Di scove ryLocato rManagement interface are
`as follows:
`
`package net .jini .di scovery;
`
`public interface DiscoveryLocatorManagement {
`
`public LookupLocatorE] getLocatorsO;
`
`public void addLocators(LookupLocator[]
`
`locators);
`
`public void setLocators(LookupLocator[] locators);
`
`public void removeLocators(LookupLocator[]
`
`locators);
`
`42
`
`42
`
`

`

`JINI DISCO VERY UTILITIES SPECIFICA TION, version 1.1
`
`33
`
`DU.2.5.1 The Semantics
`
`The Di scove ryLocato rManagement
`
`interface defines methods related to the
`
`management of the set of LookupLocator objects corresponding to the specific
`lookup services that are to be discovered using the unicast discovery protocol; that
`is, lookup services that are discovered by way of locator discovery. The methods
`of this interface define how an entity retrieves or modifies the managed set of
`locators to discover. Phrases such as “the locators to discover” and “discovering
`the desired locators” refer to the discovery of the lookup services that are associ-
`ated with those locators.
`
`The methods that modify the managed set of locators each take a single input
`parameter: an array of LookupLocator objects, none of whose elements may be
`null. Each of these methods throws a Null Poi nterException when at least one
`
`element of the input array is null.
`Invoking any of these methods with an input array that contains duplicate
`locators (as determined by LookupLocator' . equal 5) is equivalent to performing
`the invocation with the duplicates removed from the array.
`set of
`The getLocators method returns
`an array containing the
`LookupLocator objects in the managed set of locators; that is, the locators of the
`specific lookup services that the implementation object is currently interested in
`discovering.
`The returned set includes both the set of locators corresponding to lookup ser-
`vices that have already been discovered and the set of those that have not yet been
`discovered.
`
`If the managed set is empty, this method returns an empty array. This method
`takes no arguments as input, and returns a new array upon each invocation.
`The addLocato rs method adds a set of locators to the managed set. The array
`input to this method contains the set of LookupLocator' objects to add to the man-
`aged set.
`If null is input to addLocators, a Null Poi nterException will be thrown. If
`an empty array is input, the managed set of locators will not change.
`The set Locato rs method replaces all of the locators in the managed set with
`LookupLocator objects from a new set. The array input to this method contains
`the set of LookupLocator objects with which to replace the current locators in the
`managed set.
`If null is input to setLocators, a Null Poi nterException will be thrown.
`If an empty array is input to setLocators, then locator discovery will be
`halted until the managed set of locators is changed—through a subsequent call to
`this method or to add Locators—to a set that is non-null and non-empty.
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`43
`
`43
`
`

`

`34
`
`THE DISC0 VERY [MANAGEMENT INTERFA CES
`
`The removeLocato rs method deletes a set of locators from the managed set.
`The array input to this method contains the set of LookupLocator' objects to
`remove from the managed set.
`If nu'l'l
`is input to removeLocators, a Null Poi nterException will be
`thrown.
`
`If any element of the set of locators to remove is not contained in the managed
`set, removeLocators takes no action with respect to that element. If an empty
`array is input, the managed set of locators will not change.
`Any already discovered lookup service, corresponding to a locator that is a
`member of the set of locators removed from the managed set as a result of an invo-
`cation of either setLocators or removeLocator's, will be discarded and will no
`
`longer be eligible for discovery; but only if it is not currently eligible for discov-
`ery through other means (such as group discovery).
`
`DU.2.6 Supporting Interfaces and Classes
`
`Discovery management depends on the interfaces Di scove ryLi stener and
`Di scove ryChangeLi stener, and on the concrete class Di scove ryEvent.
`
`DU.2.6.1 The Di scover'yLi stener‘ Interface
`
`The public methods specified by the Di scoveryLi stener interface are as fol-
`lows:
`
`package net .jini .di scovery;
`
`public interface DiscoveryListener extends EventListener {
`
`pub'lic void discoveredCDiscoveryEvent e);
`
`public void discardedCDiSCOVerEVent e);
`
`When an entity employs an object that implements one or more of the discov-
`ery management interfaces to perform and manage the entity’s discovery duties,
`the entity often will want that obj ect—generally referred to as a discovery utility—
`to notify the entity when a desired lookup service is either discovered or dis-
`carded. The Di scoveryLi stener interface defines a mechanism through which
`an entity may receive such notifications from a discovery utility. When an entity
`registers interest in these notifications, an implementation of this interface must be
`provided to the discovery utility being employed. Through this registered listener,
`
`44
`
`44
`
`

`

`JINI DISCO VERY UTILITIES SPECIFICA TION, version 1.1
`
`35
`
`the entity may then receive instances of the Di scove ryEvent class, which encap-
`sulate the required information associated with the desired notifications.
`
`The Semantics
`
`The events received by listeners implementing the Di scove ryLi stener interface
`can be the result of either group discovery or locator discovery. These events con-
`tain the discovered or discarded registrars, as well as the set of member groups
`corresponding to each registrar (see the specification of the Di scoveryEvent
`class).
`The discovered method is called whenever a new lookup service is discov-
`ered or a discarded lookup service is re-discovered.
`The discarded method is called whenever a previously discovered lookup
`service is discarded because the lookup service was determined to be either
`unreachable or no longer interesting to the entity, and the discard process was ini-
`tiated by either the entity itself (an active discard) or the discovery utility
`employed by the entity (a passive discard).
`This interface makes the following concurrency guarantee. For any given lis-
`tener object that implements this interface or any sub-interface, no two methods
`(either the same two methods or different methods) defined by the interface (or
`sub-interface) can be invoked at the same time. For example, the discovered
`method must not be invoked while the invocation of another listener’s discarded
`
`method is in progress.
`
`DU.2.6.2 The Di scoveryChangeListener Interface
`
`The Di scove ryChangeLi stener interface specifies only one public method:
`
`package net .ji ni .di scovery;
`
`public interface DiscoveryChangeListener
`
`extends DiscoveryListener
`
`public void changedCDiscoveryEvent e);
`
`In addition to being notified when a desired lookup service is discovered or
`discarded, some entities may also wish to be notified when a lookup service expe-
`riences changes in its group membership. The Di scove ryChangeLi stener inter-
`face defines an extension to the Di scove ryLi stener interface, providing a
`mechanism through which an entity may receive these additional notifications—
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`45
`
`45
`
`

`

`36
`
`THE DISC0 VERY [MANAGEMENT INTERFA CES
`
`referred to as changed events. As with the Di scove ryLi stener interface, when
`an entity wishes to receive changed events in addition to discovered and discarded
`events, an implementation of this interface must be provided to the discovery util-
`ity being employed. It is through that registered listener that the entity receives the
`desired notifications encapsulated in instances of the Di scove ryEvent class.
`
`The Semantics
`
`When the entity receives a Di scoveryEvent object through an instance of the
`Di scove ryChangeLi stener interface,
`the event contains the discovered, dis-
`
`carded, or changed registrars, as well as the set of member groups corresponding
`to each registrar. In the case of a changed event, each set of groups referenced in
`the event contains the new groups in which the corresponding registrar is a mem-
`ber.
`
`The changed method is called whenever the discovery utility encounters
`changes in the set of groups in which a previously discovered lookup service is a
`member.
`
`It is important to note that instances of this interface are eligible to receive
`changed events for only those lookup services that the entity has requested be dis-
`covered by (at least) group discovery. That is, if the entity requests that only loca-
`tor discovery be used to discover a specific lookup service, the listener will
`receive no changed events for that lookup service. This is because the semantics
`of this interface assume that since the entity expressed no interest in discovering
`the lookup service through its group membership, it must also have no interest in
`any changes in that lookup service’s group membership. Thus, if an entity wishes
`to receive changed events for one or more lookup services, the entity must request
`that those lookup services be discovered by either group discovery alone, or by
`both group and locator discovery.
`
`DU.2.6.3 The Di scover'yEvent Class
`
`The public methods provided by the Di scove ryEvent class are as follows:
`
`package net . j i ni .di scovery;
`
`public class DiscoveryEvent extends EventObject {
`
`public Di scoveryEventCObject source, Map groups)
`
`{...}
`
`public DiscoveryEventCObject source,
`
`ServiceRegistrar[]
`
`regs) {...}
`
`46
`
`46
`
`

`

`JINI DISCO VERY UTILITIES SPECIFICA TION, version 1.1
`
`3 7
`
`pubh'c Map getGroupsO {...}
`
`public ServiceRegistrarE] getReg‘istrarsO {...}
`
`The D1" scove ryEvent class provides an encapsulation of event information
`that discovery utilities can use to notify an entity of the occurrence of an event
`involving one or more Se rvi ceReg1' st rar objects (lookup services) in which the
`entity has registered interest. Discovery utilities pass an instance of this class to
`the entity’s discovery listener(s) when one of the following events occurs:
`
`9 Each lookup service referenced in the event has been discovered for the first
`time, or re-discovered after having been discarded.
`
`9 Each lookup service referenced in the event has been either actively or pas-
`sively discarded.
`
`o For each lookup service referenced in the event, the set of groups in which
`the lookup service is a member has changed.
`
`The D1' scove ryEvent class is a subclass of EventObject, adding the follow-
`ing additional items of abstract state: a set of Se rv1' ceRegi st rar instances (regis-
`trars) referencing the affected lookup services, and a mapping from each of those
`registrars to their current set of member groups. Methods are defined through
`which this additional state may be retrieved upon receipt of an instance of this
`class.
`
`The Semantics
`
`The equals method for this class returns true if and only if two instances of this
`class refer to the same object. That is, x and y are equal instances of this class if
`and only if x == y has the value true.
`The constructor for this class has two forms, where both forms expect two
`input parameters. Each form of the constructor takes, as its first input parameter, a
`reference to the source of the event; that is, the discovery utility object that created
`the event instance and sent it to the entity’s listener(s) through the invocation of
`the discovered, d1' scarded, or changed method on each listener. Note that nei-
`
`ther form of the constructor makes a copy of the second parameter. That is, the
`reference input to the second parameter is shared with the invoking entity.
`Depending on the constructor employed, the second parameter is one of the
`following:
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`47
`
`47
`
`

`

`38
`
`THE DISC0 VERY [MANAGEMENT INTERFA CES
`
`o A Map instance in which each element of the map’s key set is a Se rvi ceReg—
`1'st rar instance that references one of the lookup services to be associated
`with the event being constructed. Each element of the map’s value set is a
`String array, containing the names of the groups in which the correspond-
`ing lookup service is a member.
`
`0 An array of Se rv1' ceRegi st rar instances in which each element references
`one of the lookup services to be associated with the event being constructed.
`
`It is important to note that when this form of the constructor is used to con-
`struct a Di scove ryEvent, although the resulting event contains a non—nuTl
`registrars array, the registrars-to-groups map is nul 1. Therefore, discovery
`utilities should no longer use this constructor to instantiate the events they
`send.
`
`The getG roups method returns the mapping from each registrar referenced
`by the event to the registrar’s current set of member groups. If the event was
`instantiated using the constructor whose second parameter is an array of Se r—
`v1' ceRegi strar instances, this method will return ml 1 .
`
`The returned map’s key set is made up of Se rv1' ceRegi st rar instances corre-
`sponding to the lookup services for which the event was constructed and sent.
`Each element of the returned map’s value set is a String array, containing the
`names of the member groups of the corresponding lookup service.
`On each invocation of this method, the same Map object is returned; that is, a
`copy is not made.
`an array of Servi ceRegi st rar
`The getRegi strars method returns
`instances, in which each element references one of the lookup services for which
`the event was constructed and sent.
`
`On each invocation of this method, the same array is returned; that is, a copy
`is not made.
`
`DU.2.7 Serialized Forms
`
`Class
`
`ser‘ia] VersionUID
`
`Serialized Fields
`
`DiscoveryEvent
`
`5280303374696501479L ServiceRegistrarE]
`
`regs
`
`Map groups
`
`48
`
`48
`
`

`

`JINI DISCO VERY UTILITIES SPECIFICA TION, version 1.1
`
`39
`
`
`
`
`DU.3 LookupD'i scover'y Utility
`
`IN a Jini application environment the multicast discovery protocols are often col-
`lectively referred to as multicast discovery or group discovery. The entities that
`participate in the multicast discovery protocol are a discovering entity (Jini client
`or service) and a Jini lookup service, which acts as the entity that is to be discov-
`ered. When the discovering entity starts, it uses the multicast request protocol to
`announce its interest in finding lookup services within range. After a specified
`amount of time, the entity stops sending multicast requests, and simply listens for
`multicast announcements from any lookup services within range that may be
`broadcasting their availability. Through either of these protocols, the discovering
`entity can obtain references to lookup services belonging to member group in
`which the entity is interested. For the details of the multicast discovery protocols,
`refer to the The Jini Technology Core Platform Specification, “Discovery and
`Join”.
`
`The LookupDiscove ry helper utility in the package net.jini .di scovery
`encapsulates the fiinctionality required of an entity that wishes to employ multi-
`cast discovery to discover a lookup service located within the entity’s multicast
`radius (roughly, the number of hops beyond which neither the multicast requests
`from the entity, nor the multicast announcements from the lookup service, will
`propagate). This utility provides an implementation that makes the process of
`acquiring lookup service instances, based on no information other than group
`membership, much simpler for both services and clients.
`
`DU.3.1 Other Types
`
`The types defined in the specification of the LookupDi scove ry utility class are in
`the net.j1' n1' .di scove ry package. The following additional types may also be
`referenced in this specification. Whenever referenced, these object types will be
`referenced in unqualified form:
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`49
`
`49
`
`

`

`40
`
`LookupDiscovery UTILITY
`
`net.jini.core.discovery.LookupLocator
`
`net.jini.discovery.DiscoveryManagement
`
`net.jini.discovery.DiscoveryGroupManagement
`
`net.jini.discovery.DiscoveryPermission
`
`java.io.IOException
`
`java.io.Serializable
`
`java.security.Permission
`
`DU.3.2 The Interface
`
`The public methods provided by the LookupDi scove ry class are as follows:
`
`package net . j i ni .di scovery;
`
`public cl ass LookupDi scove ry
`
`implements Di scove ryManagement,
`
`Di scove ryG roupManagement
`
`public static final String[] ALL_GROUPS
`
`public static final String[] NO_GROUPS
`
`= DiscoveryGroupManagement.ALL_GROUPS;
`
`= DiscoveryGroupManagement.NO_GROUPS;
`
`public LookupDiscoveryCString[] groups)
`
`throws IOException {m}
`
`{
`
`}
`
`DU.3.3 The Semantics
`
`The only new public method of the LookupDi scove ry helper utility class is the
`constructor. All other public methods implemented by this class are specified in
`theDiscoveryManagementandtheDiscoveryGroupManagementinfixfiwes
`
`Each instance of the LookupDiscove ry class must behave as if it operates
`independently of all other instances.
`Theequalsrnmhodforflnsckmsreuunstrueifand<nflyifpwoiHMancesof
`this class refer to the same object. That is, x and y are equal instances of this class
`if and only if x == y has the value true.
`
`50
`
`50
`
`

`

`JINI DISCO VERY UTILITIES SPECIFICA TION, version 1.1
`
`4 1
`
`For convenience, this class defines the constants AL L_GROU PS and N0_GROU PS,
`
`which represent no set and the empty set respectively. For more information on
`these constants, refer to the specification of the Di scoveryGroupManagement
`interface.
`
`The constructor of the LookupDi scove ry class takes a single input parameter:
`a String array, none of whose elements may be nu11. If at least one element of
`the input array is null, a Nu'l 'I Poi nterExcepti on is thrown.
`Constructing this class using an input array that contains duplicate group
`names is equivalent to constructing the class using an array with the duplicates
`removed.
`
`If nuH (AL L_GROU PS) is input to the constructor, then attempts will be made
`to discover all lookup services located within the current multicast radius, regard-
`less of group membership.
`Although discovery events will not be sent by this class until a listener is
`added through an invocation of the addLi stener method, discovery processing
`usually starts as soon as an instance of this class is constructed. However, if an
`empty array (N0_GROUPS)
`is passed to the constructor, discovery will not be
`started until the addG roups or setGroups method is called to change the initial
`empty set of groups to either a non-empty set, or null (ALL_GROUPS).
`The constructor can throw an IOExcepti on because the creation of a
`
`LookupDi scove ry object causes the initiation of the discovery process, a process
`that can throw IOExcepti on when socket allocation occurs.
`
`DU.3.4 Supporting Interfaces and Classes
`
`interfaces
`the
`on
`depends
`The LookupDiscove ry helper utility class
`Di scoveryManagement and Di scoveryGroupManagement, and on the concrete
`
`class Di scove ryPermi ssi on.
`
`DU.3.4.1 The Di scoveryManagement Interfaces
`
`The LookupDi scove ry class implements both the Di scoveryManagement and the
`Di scove ryGroupManagement interfaces, which together define methods related
`to the coordination and management of all group discovery processing. See
`Section DU.2, “The Discovery Management Interfaces” for more information on
`those interfaces.
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`51
`
`51
`
`

`

`42
`
`LookupD'iscovery UTILITY
`
`DU.3.4.2 Security and Multicast Discovery: The Di scoveryPermi ssion
`Class
`
`When an instance of the LookupDi scove ry class is constructed, the entity that
`creates the instance must be granted appropriate discovery permission. For exam-
`ple, if the instance of LookupDi scove ry is currently configured to discover a non-
`empty, non-nul l set of groups, then the entity that created the instance must have
`permission to attempt discovery of each of the groups in that set. If the set of
`groups to discover is null (AL L_GROU PS), then the entity must have permission to
`attempt discovery of all possible groups. If appropriate permissions are not
`granted, the constructor of LookupDi scove ry, as well as the methods addG roups
`and setGroups, will throw a java . l ang . Secu ri tyExcepti on.
`Discovery permissions are controlled in security policy files using the per-
`mission class Di scoveryPe rmi ssion. The public methods provided by the
`Di scove ryPermi ssi on class are as follows:
`
`package net .jini .di scovery;
`
`public final class DiscoveryPermission extends Permission
`
`implements Serializable
`
`{
`
`public DiscoveryPermissionCString group) {...}
`
`public DiscoveryPermissionCString group,
`
`String actions) {...}
`
`} T
`
`he Di scove ryPermi ssi on class is a subclass of Permission, adding no
`additional items of abstract state.
`
`The Semantics
`
`The equals method for this class returns true if and only if two instances of this
`class have the same group name.
`The constructor for this class has two forms: one form expecting one input
`parameter, the other form expecting two input parameters. Each form of the con-
`structor takes, as its first input parameter, a String representing one or more
`group names for which to allow discovery.
`The second parameter of the second form of the constructor is a String value
`that is currently ignored because there are no actions associated with a discovery
`permission.
`
`52
`
`52
`
`

`

`JINI DISCO VERY UTILITIES SPECIFICA TION, version 1.1
`
`43
`
`D'i scaveryPer‘m'i ssion Examples
`
`A number of examples that illustrate the use of this permission are presented.
`Note that each example represents a line in a policy file.
`
`permission net . j1'n1' .d1' scovery . D1' scoveryPermi 551' on "*";
`
`Grant the entity permission to attempt discovery of all possible groups
`
`permission net . j'in'i .d'i 5covery . D'i 5cover'yPer'm1' 55‘i on
`
`;
`
`Grant the entity permission to attempt discovery of only the “public” group
`
`permission net . j'in'i .d'i 5covery . D'i 5cover'yPer'm1' 55‘i on "foo";
`
`Grant the entity permission to attempt discovery of the group named “foo”
`
`permission net . j'in'i .d'i 5covery . D'i 5cover'yPer'm1' 55‘i on
`
`* . sun . com";
`
`Grant the entity permission to attempt discovery of all groups whose names
`end with the substring “.sun.com”
`
`Each of the above declarations grants permission to attempt discovery of one
`name. A name does not necessarily correspond to a single group. That is, the fol-
`lowing should be noted:
`
`“ J. Hn
`
`o The name
`
`grants permission to attempt discovery of all possible groups.
`
`“* . ” grants permission to attempt discovery of all
`9 A name beginning wit
`groups that match the remainder of that name; for example, the name
`"*.examp'|e.org" would match a group named "foon1y.examp1e.org"
`and also a group named "51‘. ca. example .org".
`
`9 The empty name " " denotes the public group.
`
`9 All other names are treated as individual groups and must match exactly.
`
`Finally, it is important to note that a restriction of the Java platform security
`model requires that appropriate D1' 5coveryPerm1'551'on be granted to the Jini
`technology infrastructure software codebase itself, in addition to any codebases
`that may use Jini technology infrastructure software classes.
`
`DU.3.5 Serialized Forms
`
`Class
`
`ser‘ia] VersionUID
`
`Serialized Fields
`
`D1' scove ryPe mi 551' on —3036978025008149170L none
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`53
`
`53
`
`

`

`44
`
`LookupD'iscovery UTILITY
`
`54
`
`54
`
`

`

`JINI DISCO VERY UTILITIES SPECIFICA TION, version 1.1
`
`45
`
`
`
`
`DU.4 The LookupLocator'D'i scover'y Utility
`
`DU.4.1 Overview
`
`THE The Jini Technology Core Platform Specification, “Discovery and Join”,
`states that the “unicast discovery protocol is a simple request-response protocol.”
`In a Jini application environment, the entities that participate in this protocol are a
`discovering entity (Jini client or service) and a Jini lookup service that acts as the
`entity to be discovered. The discovering entity sends unicast discovery requests to
`the lookup service, and the lookup service reacts to those requests by sending uni-
`cast discovery responses to the interested discovering entity.
`The LookupLocato rD1' scove ry helper utility (belonging to the package
`net.j1' n1' .d1' scove ry) encapsulates the functionality required of an entity that
`wishes to employ the unicast discovery protocol to discover a lookup service. This
`utility provides an implementation that makes the process of finding specific
`instances of a lookup service much simpler for both services and clients.
`Because the LookupLocator'Di scovery helper utility class will participate in
`only the unicast discovery protocol, and because the unicast discovery protocol
`imposes no restriction on the physical location of a service or client relative to a
`lookup service, this utility can be used to discover lookup services running on
`hosts that are located far from, or near to, the hosts on which the service is run-
`
`ning. This lack of a restriction on location brings with it a requirement that the
`discovering entity supply specific information about the desired lookup services to
`the LookupLocator'Di scovery utility; namely, the location of the device(s) host-
`ing each lookup service. This information is supplied through an instance of the
`LookupLocator utility, defined in The Jini Technology Core Platform Specifica—
`tion, “Discovery and Join”.
`It may be of value to note the difference between LookupLocato rD1' scove ry
`and the LookupDiscove ry helper utility for group discovery (defined earlier).
`Although both are non-remote utility classes that entities can use to discover at
`least one lookup service, the LookupLocator'Di scovery utility is designed to pro-
`vide discovery capabilities that satisfy different needs than those satisfied by the
`LookupDi scove ry utility. These two utilities differ in the following ways:
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`55
`
`55
`
`

`

`46
`
`THE LookupLocatorDiscovery UTILITY
`
`0
`
`Whereas the LookupLocatorDi scove ry utility is used to discover lookup
`services by their locators, employing the unicast discovery protocol, the
`LookupDi scove ry utility uses the multicast discovery protocols to discover
`lookup services by the groups to which the lookup services belong.
`
`Whereas the LookupLocatorDi scove ry utility requires that the discovering
`entity supply the specific location—or address—of the desired lookup ser-
`vice(s) in the form ofa LookupLocator object, the LookupDi scove ry util-
`ity imposes no such restriction on the discovering entity.
`
`Whereas the LookupLocatorDi scove ry utility can be used by a discovering
`entity to discover lookup services that are both “near” and “far,” the
`LookupDi scove ry utility can be used to discover only those lookup services
`that are located within the same multicast radius as that of the discovering
`entity.
`
`DU.4.2 Other Types
`
`The types defined in the specification of the LookupLocatorDi scovery utility
`class are in the net. jini .discove ry package. The following additional types
`may also be referenced in this specification. Whenever referenced, these object
`types will be referenced in unqualified form:
`
`net . j i ni . core . di scovery. LookupLocator
`
`net . j i ni .di scove r'y . Di scove ryManagement
`
`net . j i ni .di scove r'y . Di scove ryLocatorManagement
`
`DU.4.3 The Interface
`
`The public methods provided by the LookupLocatorDi scove ry class are as fol-
`lows:
`
`package net .jini .di scovery;
`
`pub'l i c (:1 ass LookupLocatorDi scove ry
`
`imp'l ements Di scove ryManagement
`
`Di scove ryLocato rManagement
`
`public LookupLocatorDiscovery
`
`(LookupLocatorEJ locators) {...}
`
`56
`
`56
`
`

`

`JINI DISCO VERY UTILITIES SPECIFICA TION, version 1.1
`
`47
`
`public LookupLocator‘E] getDiscoveredLocatorsO {...}
`
`public LookupLocatorE] getUndiscoveredLocatorsO {...}
`
`DU.4.4 The Semantics
`
`the LookupLocatorDi scove ry helper utility class
`Including the constructor,
`defines three new public methods. All other public methods are inherited from the
`Di scove ryManagement and Di scove ryLocatorManagement interfaces.
`
`Each instance of the LookupLocatorDiscovery class must behave as if it
`
`operates independently of all other instances.
`The equals method for this class returns true