DU.3. LookupDiscovery Utility

In a Jini application environment the multicast discovery protocols are often collectively 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 discovered. 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 LookupDiscovery helper utility in the package net.jini.discovery encapsulates the functionality required of an entity that wishes to employ multicast 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 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:

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 LookupDiscovery class are as follows:

package net.jini.discovery; 

public class LookupDiscovery 
                        implements DiscoveryManagement, 
                                   DiscoveryGroupManagement 
{
    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 helper utility class is the constructor. All other public methods implemented by this class are specified in the DiscoveryManagement and the DiscoveryGroupManagement interfaces.

Each instance of the LookupDiscovery class must behave as if it operates independently of all 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 of this class if and only if x==y has the value true.

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 LookupDiscovery class takes a single input parameter: a String array, none of whose elements may be null. If at least one element of the input array is null, a NullPointerException 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 null (ALL_GROUPS) is input to the constructor, then attempts will be made to discover all lookup services located within the current multicast radius, regardless 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 of this 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 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 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

The LookupDiscovery helper utility class depends on the interfaces 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 Management Interfaces” for more information on those interfaces.

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 example, if the instance of LookupDiscovery is currently configured to discover a non-empty, nonnull 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 (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 permission 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) {...} 
} 

The DiscoveryPermission 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 constructor 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.

DiscoveryPermission 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.jini.discovery.DiscoveryPermission "*"; 

Grant the entity permission to attempt discovery of all 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”

permission net.jini.discovery.DiscoveryPermission "*.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 following should be noted:

• The name “*” grants permission to attempt discovery of all possible groups.

• A name beginning with “*.” grants permission to attempt discovery of all 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 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 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