JINI DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`31
`
`If the managedset of groups is empty, this method will return an empty array.
`If there is no managedset of groups, then nu11 (ALL_GROUPS)is returned, indicat-
`ing that any lookup service within range—even those that have no groupaffilia-
`tion—are to be discovered.
`If an empty array is returned, that array is guaranteedto be referentially equal
`to the NO_GROUPSconstant; that is, the array returned from that method and the
`NO_GROUPSconstant can be tested for equality using the == operator.
`This method takes no arguments as input and, provided the managedset of
`groups currently exists, will return a new array upon each invocation.
`The addGroups method adds a set of group namesto the managed set. The
`array input to this method contains the group namesto be addedtotheset.
`This method throws IOException because an invocation of this method may
`result in the re-initiation of the discovery process, which can throw IOException
`when socket allocation occurs.
`This method throws an UnsupportedOperationException if there is no
`managed set of groups to augment, and it throws a Nul1PointerException if
`nul] (ALL_GROUPS)is input. If an empty array (NO_GROUPS)is input, the managed
`set of groups will not change.
`The setGroups method replacesall 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 managedset.
`Once a new group namehasbeen placed in the managedset, 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 discoverall (as yet) undiscov-
`ered lookup services belongingto that group will continue to be made.
`If nul] (ALL_GROUPS)is input to setGroups, 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 setGroups, then group discovery
`will be halted until the managedset of groups is changed—through a subsequent
`call to this method or to addGroups—to a set that is either a non-empty set of
`group names or nul11 (ALL_GROUPS).
`This method throws IOException. This is because an invocation of this
`method mayresult in the re-initiation of the discovery process, a process that can
`throw IOException whensocketallocation occurs.
`The removeGroups methoddeletes 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 managedset.
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`41
`
`41
`
`

`

`32
`
`THE DISCOVERY MANAGEMENTINTERFACES
`
`This method throws an UnsupportedOperationException if there is no
`managed set of groups from which to remove elements. If nu11 (ALL_GROUPS)is
`input to removeGroups, a Nu11PointerException will be thrown.
`If any element of the set of groups to be removedis not contained in the man-
`aged set, removeGroups takes no action with respect to that element. If an empty
`array (NO_GROUPS)is input, the managedset of groups will not change.
`Once a new group nameis added to the managedsetas a result of an invoca-
`tion of either addGroups or setGroups, attempts will be made—using the multi-
`cast request protocol—to discoverall (as yet) undiscovered lookup services that
`are membersofthat 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 groupsofinterest.
`Anyalready discovered lookupservice that is a memberof one or moreofthe
`groups removed from the managed set as a result of an invocation of either
`setGroups or removeGroupswill be discarded and will no longer be eligible for
`discovery, but only if that lookup service satisfies both of the following condi-
`tions:
`
`@ the lookup service is not a memberof any group in the new managedsetthat
`resulted from the invocation of setGroups or removeGroups, and
`
`@ the lookup service is not currently eligible for discovery through other
`means(such as locator discovery).
`
`DU.2.5 The DiscoveryLocatorManagement Interface
`
`The public methodsspecified by the DiscoveryLocatorManagement interface are
`as follows:
`
`package net.jini.discovery;
`
`public interface DiscoveryLocatorManagement {
`public LookupLocator[] getLocators();
`locators);
`public void addLocators(LookupLocator[]
`public void setLocators(LookupLocator[] locators);
`public void removeLocators(LookupLocator[]
`locators);
`
`42
`
`42
`
`

`

`JINI DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`33
`
`DU.2.5.1 The Semantics
`
`interface defines methods related to the
`The DiscoveryLocatorManagement
`managementof the set of LookupLocator objects corresponding to the specific
`lookupservicesthat 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 methodsthat modify the managedset 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 Nu11PointerException whenat least one
`element of the input array is nu11.
`Invoking any of these methods with an input array that contains duplicate
`locators (as determined by LookupLocator.equals) is equivalent to performing
`the invocation with the duplicates removed from thearray.
`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 lookupser-
`vices that have already been discovered and the set of those that have not yet been
`discovered.
`If the managedset is empty, this method returns an empty array. This method
`takes no arguments as input, and returns a new array upon each invocation.
`The addLocators methodaddsa set of locators to the managed set. The array
`input to this method contains the set of LookupLocator objects to add to the man-
`agedset.
`If nu11 is input to addLocators, a Nul1PointerException will be thrown.If
`an empty array is input, the managedset of locators will not change.
`The setLocators method replacesall of the locators in the managedset 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
`managedset.
`If nu11 is input to setLocators, a Nul1PointerException 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 subsequentcall to
`this method or to addLocators—toa set that is non-nu11 and non-empty.
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`43
`
`43
`
`

`

`34
`
`THE DISCOVERY MANAGEMENTINTERFACES
`
`The removeLocators method deletes a set of locators from the managedset.
`The array input to this method contains the set of LookupLocator objects to
`remove from the managedset.
`If null
`is input to removeLocators, a Nul]lPointerException will be
`thrown.
`If any elementofthe set of locators to removeis not contained in the managed
`set, removeLocators takes no action with respect to that element. If an empty
`array is input, the managedset of locators will not change.
`Anyalready discovered lookup service, corresponding to a locator that is a
`memberofthe set of locators removed from the managedset as a result of an invo-
`cation of either setLocators or removeLocators, will be discarded and will no
`longer be eligible for discovery; but onlyif 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 DiscoveryListener and
`DiscoveryChangeListener, and on the concrete class DiscoveryEvent.
`
`DU.2.6.1 The DiscoveryListener Interface
`
`The public methods specified by the DiscoveryListener interface are as fol-
`lows:
`
`package net.jini.discovery;
`
`public interface DiscoveryListener extends EventListener {
`public void discovered(DiscoveryEvent e);
`public void discarded(DiscoveryEvent e);
`
`Whenanentity employs an object that implements one or more ofthe discov-
`ery managementinterfaces to perform and managethe entity’s discovery duties,
`the entity often will want that object—generally referred to as a discovery utility—
`to notify the entity when a desired lookup service is either discovered or dis-
`carded. The DiscoveryListener 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
`providedto the discovery utility being employed. Throughthis registered listener,
`
`44
`
`44
`
`

`

`JINI DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`35
`
`the entity may then receive instances of the DiscoveryEvent class, which encap-
`sulate the required information associated with the desired notifications.
`
`The Semantics
`
`The events received by listeners implementing the DiscoveryListener 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 DiscoveryEvent
`class).
`The discovered methodis called whenever a new lookupservice is discov-
`ered or a discarded lookupservice is re-discovered.
`The discarded methodis 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 wasini-
`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 givenlis-
`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 anotherlistener’s discarded
`methodis in progress.
`
`DU.2.6.2. The DiscoveryChangeListener Interface
`
`The DiscoveryChangeListener interface specifies only one public method:
`
`package net.jini.discovery;
`
`public interface DiscoveryChangeListener
`extends DiscoveryListener
`
`public void changed(DiscoveryEvent 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 DiscoveryChangeListener inter-
`face defines an extension to the DiscoveryListener interface, providing a
`mechanism through which an entity may receive these additional notifications—
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`45
`
`45
`
`

`

`36
`
`THE DISCOVERY MANAGEMENTINTERFACES
`
`referred to as changed events. As with the DiscoveryListener interface, when
`an entity wishes to receive changed events in addition to discovered and discarded
`events, an implementation of this interface must be providedto the discovery util-
`ity being employed.It is through that registered listener that the entity receives the
`desired notifications encapsulated in instances of the DiscoveryEvent class.
`
`The Semantics
`
`Whenthe entity receives a DiscoveryEvent object through an instance of the
`DiscoveryChangeListener 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
`changesin 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
`changedevents 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 assumethat since the entity expressed no interest in discovering
`the lookup service through its group membership,it must also have nointerest in
`any changesin that lookup service’s group membership. Thus, if an entity wishes
`to receive changed events for one or more lookupservices, the entity must request
`that those lookup services be discovered by either group discovery alone, or by
`both group andlocator discovery.
`
`DU.2.6.3 The DiscoveryEvent Class
`
`The public methods provided by the DiscoveryEvent class are as follows:
`
`package net.jini.discovery;
`
`{
`public class DiscoveryEvent extends EventObject
`public DiscoveryEvent(Object source, Map groups)
`public DiscoveryEvent(Object source,
`ServiceRegistrar[]
`
`regs) {...}
`
`{...}
`
`46
`
`46
`
`

`

`JINI DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`37
`
`public Map getGroups() {...}
`public ServiceRegistrar[] getRegistrars() {..}
`
`The DiscoveryEvent 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 ServiceRegistrar 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 oneof the following events occurs:
`
`@ Each lookup service referenced in the event has been discoveredforthe first
`time, or re-discovered after having been discarded.
`@ Each lookupservice referenced in the event has beeneither actively or pas-
`sively discarded.
`For each lookup service referenced in the event, the set of groups in which
`the lookup service is a memberhas changed.
`
`The DiscoveryEvent class is a subclass of EventObject, adding the follow-
`ing additional itemsof abstract state: a set of ServiceRegistrar 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 ofthis 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 ofthe 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 andsent it to the entity’s listener(s) through the invocation of
`the discovered, discarded, or changed method oneachlistener. Note that nei-
`ther form of the constructor makes a copy of the second parameter. That is, the
`reference input to the second parameteris shared with the invoking entity.
`Depending on the constructor employed, the second parameter is one of the
`following:
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`47
`
`47
`
`

`

`38
`
`THE DISCOVERY MANAGEMENTINTERFACES
`
`@ A Mapinstance in which each elementofthe map’s key set is a Servi ceReg-
`istrar instance that references one of the lookup services to be associated
`with the event being constructed. Each element of the map’s valueset is a
`String array, containing the namesof the groups in which the correspond-
`ing lookup service is a member.
`@ Anarray of ServiceRegistrar instances in which each element references
`one of the lookup servicesto 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 DiscoveryEvent, although the resulting event contains a non-nu11
`registrars array, the registrars-to-groups map is null. Therefore, discovery
`utilities should no longer use this constructor to instantiate the events they
`send.
`
`The getGroups 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 Ser-
`viceRegistrar instances, this method will return nu11.
`The returned map’s key set is made up of ServiceRegistrar instancescorre-
`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
`namesof the membergroupsof the corresponding lookupservice.
`On each invocation of this method, the same Map objectis returned; thatis, a
`copy is not made.
`an array of ServiceRegistrar
`The getRegistrars method returns
`instances, in which each element references one of the lookup services for which
`the event was constructed andsent.
`On each invocation of this method, the samearray is returned; that is, a copy
`is not made.
`
`DU.2.7 Serialized Forms
`
`Class
`
`serialVersionUID
`
`Serialized Fields
`
`DiscoveryEvent
`
`5280303374696501479L ServiceRegistrar[]
`Map groups
`
`regs
`
`48
`
`48
`
`

`

`JINI DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`39
`
`
`
`
`DU.3 LookupDiscovery Utility
`
`ly a Jini application environmentthe 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
`amountoftime, 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 LookupDiscovery helper utility in the package net.jini.discovery
`encapsulates the functionality 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 whichneither 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 andclients.
`
`DU.3.1 Other Types
`
`The types defined in the specification of the LookupDiscovery utility class are in
`the net. jini.discovery 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 JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`49
`
`49
`
`

`

`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 LookupDiscoveryclassare as follows:
`
`package net.jini.discovery;
`
`public class LookupDiscovery
`implements DiscoveryManagement,
`Di scoveryGroupManagement
`
`{
`
`}
`
`public static final String[] ALL_GROUPS
`= DiscoveryGroupManagement.ALL_GROUPS;
`public static final String[] NO_GROUPS
`= DiscoveryGroupManagement .NO_GROUPS;
`
`public LookupDiscovery(String[] groups)
`throws IOException {...}
`
`DU.3.3 The Semantics
`
`The only new public method of the LookupDiscovery helperutility class is the
`constructor. All other public methods implementedby this class are specified in
`the DiscoveryManagement and the DiscoveryGroupManagement interfaces.
`Each instance of the LookupDiscovery class must behave asif it operates
`independently ofall other instances.
`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 ofthis class
`if and only if x == y has the value true.
`
`50
`
`50
`
`

`

`JINI DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`41
`
`For convenience,this class defines the constants ALL_GROUPS and NO_GROUPS,
`which represent no set and the empty set respectively. For more information on
`these constants, refer to the specification of the DiscoveryGroupManagement
`interface.
`The constructor of the LookupDiscoveryclass 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 nul1, a Nul1PointerException is thrown.
`Constructing this class using an input array that contains duplicate group
`namesis equivalent to constructing the class using an array with the duplicates
`removed.
`If nul] (ALL_GROUPS) is input to the constructor, then attempts will be made
`to discoverall 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 addListener method, discovery processing
`usually starts as soon as an instance ofthis class is constructed. However, if an
`empty array (NO_GROUPS)
`is passed to the constructor, discovery will not be
`started until the addGroups or setGroups methodis called to change theinitial
`empty set of groups to either a non-empty set, or nul] (ALL_GROUPS).
`The constructor can throw an IOException because the creation of a
`LookupDiscovery object causes the initiation of the discovery process, a process
`that can throw IOException when socket allocation occurs.
`
`DU.3.4 Supporting Interfaces and Classes
`
`interfaces
`the
`on
`depends
`The LookupDiscovery helper utility class
`DiscoveryManagement and DiscoveryGroupManagement, and on the concrete
`class DiscoveryPermission.
`
`DU.3.4.1 The DiscoveryManagement Interfaces
`
`The LookupDiscovery class implements both the DiscoveryManagement and the
`DiscoveryGroupManagement interfaces, which together define methods related
`to the coordination and management of all group discovery processing. See
`Section DU.2, “The Discovery ManagementInterfaces” for more information on
`those interfaces.
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`51
`
`51
`
`

`

`42
`
`LookupDiscovery UTILITY
`
`DU.3.4.2 Security and Multicast Discovery: The DiscoveryPermission
`Class
`
`When an instance of the LookupDiscovery class is constructed, the entity that
`creates the instance must be granted appropriate discovery permission. For exam-
`ple, if the instance of LookupDiscoveryis currently configured to discover a non-
`empty, non-nu11 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 nul] (ALL_GROUPS), then the entity must have permission to
`attempt discovery of all possible groups. If appropriate permissions are not
`granted, the constructor of LookupDiscovery, as well as the methods addGroups
`and setGroups, will throw a java. lang. SecurityException.
`Discovery permissions are controlled in security policy files using the per-
`mission class DiscoveryPermission. The public methods provided by the
`DiscoveryPermission class are as follows:
`
`package net.jini.discovery;
`
`public final class DiscoveryPermission extends Permission
`implements Serializable
`
`{
`
`public DiscoveryPermission(String group) {...}
`public DiscoveryPermission(String group,
`String actions) {..}
`
`} T
`
`he DiscoveryPermission class is a subclass of Permission, adding no
`additional items of abstractstate.
`
`The Semantics
`
`The equals method for this class returns true if and only if two instances ofthis
`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 namesfor whichto allow discovery.
`The second parameter of the second form of the constructor is a String value
`that is currently ignored becausethere are no actions associated with a discovery
`permission.
`
`52
`
`52
`
`

`

`JINI DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`43
`
`DiscoveryPermission Examples
`
`A number of examples that illustrate the use of this permission are presented.
`Note that each example representsaline in a policyfile.
`permission net.jini.discovery.DiscoveryPermission "*";
`Grant the entity permission to attempt discovery ofall possible groups
`
`;
`permission net.jini.discovery.DiscoveryPermission
`Grant the entity permission to attempt discovery of only the “public” group
`
`permission net.jini.discovery.DiscoveryPermission "foo";
`Grant the entity permission to attempt discovery of the group named “foo”
`Wha
`permission net.jini.discovery.DiscoveryPermission "*.sun.com";
`Grant the entity permission to attempt discovery ofall groups whose names
`end with the substring “.sun.com”
`Each of the above declarations grants permission to attempt discovery of one
`name. A name doesnot necessarily correspond to a single group. Thatis, the fol-
`lowing should be noted:
`
`@ The name “*” grants permission to attempt discovery ofall possible groups.
`@ A name beginning with “*.” grants permission to attempt discovery ofall
`groups that match the remainder of that name; for example, the name
`"* example.org" would match a group named "foonly.example.org"
`and also a group named "sf.ca.example.org”.
`@ The empty name ""denotes the public group.
`@ All other namesare 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 DiscoveryPermission 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
`
`serialVersionUID
`
`Serialized Fields
`
`DiscoveryPermission —3036978025008149170L none
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`53
`
`53
`
`

`

`44
`
`LookupDiscovery UTILITY
`
`54
`
`54
`
`

`

`JINI DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`45
`
`
`
`
`DU.4 The LookupLocatorDiscovery Utility
`
`DU.4.1 Overview
`
`Ti 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 lookupservice 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 responsesto the interested discovering entity.
`The LookupLocatorDiscovery helper utility (belonging to the package
`net.jini.discovery) 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 andclients.
`Because the LookupLocatorDiscoveryhelperutility class will participate in
`only the unicast discovery protocol, and because the unicast discovery protocol
`imposesnorestriction 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 servicesto
`the LookupLocatorDiscoveryutility; 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 LookupLocatorDiscovery
`and the LookupDiscovery 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 LookupLocatorDiscoveryutility is designed to pro-
`vide discovery capabilities that satisfy different needs than those satisfied by the
`LookupDiscoveryutility. These twoutilities differ in the following ways:
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`55
`
`55
`
`

`

`46
`
`¢
`
`THE LookupLocatorDiscovery UTILITY
`
`Whereas the LookupLocatorDiscoveryutility is used to discover lookup
`services by their /Jocators, employing the unicast discovery protocol, the
`LookupDiscoveryutility uses the multicast discovery protocols to discover
`lookupservices by the groups to which the lookupservices belong.
`Whereasthe LookupLocatorDiscoveryutility requires that the discovering
`entity supply the specific location—or address—ofthe desired lookupser-
`vice(s) in the form of a LookupLocator object, the LookupDiscoveryutil-
`ity imposesnosuchrestriction on the discovering entity.
`Whereasthe LookupLocatorDiscoveryutility can be used by a discovering
`entity to discover lookup services that are both “near” and “far,” the
`LookupDiscoveryutility 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 LookupLocatorDiscovery utility
`class are in the net. jini.discovery package. The following additional types
`may also be referenced in this specification. Whenever referenced, these object
`types will be referenced in unqualified form:
`
`net.jini.core.discovery.LookupLocator
`net.jini.discovery.DiscoveryManagement
`net.jini.discovery.DiscoveryLocatorManagement
`
`DU.4.3. The Interface
`
`The public methods provided by the LookupLocatorDiscoveryclassare as fol-
`lows:
`
`package net.jini.discovery;
`
`public class LookupLocatorDiscovery
`implements DiscoveryManagement
`DiscoveryLocatorManagement
`
`public LookupLocatorDiscovery
`(LookupLocator[]
`
`locators) {..}
`
`56
`
`56
`
`

`

`JINI DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`47
`
`public LookupLocator[] getDiscoveredLocators() {...}
`public LookupLocator[] getUndiscoveredLocators() {..}
`
`DU.4.4 The Semantics
`
`the LookupLocatorDiscovery helper utility class
`Including the constructor,
`defines three new public methods. All other public methodsare inherited from the
`DiscoveryManagement and DiscoveryLocatorManagement interfaces.
`Each instance of the LookupLocatorDiscovery class must behaveasifit
`operates independently ofall other instances.
`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 instancesofthis class
`if and only if x == y has the value true.
`The constructor of the LookupLocatorDiscoveryclass takes a single input
`parameter: a set of locators represented as an array of LookupLocator objects,
`none of whose elements may be nu11. Each elementin the input set corresponds
`to a specific lookup service the discovering entity wishes to be discovered.
`Althoughit is acceptable to input nu11, if a non-nu11 array containing at least one
`nul] elementis input, a Nu11PointerException will be thrown.
`Invoking the constructor with an input array that contains duplicate locators
`(as determined by LookupLocator. equals) is equivalent to performing the invo-
`cation with the duplicates removed