net.jini.discovery
Interface DiscoveryGroupManagement

All Known Implementing Classes:

LookupDiscovery, LookupDiscoveryManager

public interface DiscoveryGroupManagement

This interface defines methods and constants related to the management of the sets of lookup services that are to be discovered using the multicast discovery protocol; that is, lookup services that are discovered by way of group discovery. The methods of this interface define how an entity retrieves or modifies the set of groups associated with those lookup services.

Author:

Sun Microsystems, Inc.

Field Summary

static String[]	ALL_GROUPS Convenience constant used to request that attempts be made to discover all lookup services that are within range, and which belong to any group.
static String[]	NO_GROUPS Convenience constant used to request that discovery by group membership be halted (or not started, if the group discovery mechanism is simply being instantiated).

Method Summary

void	addGroups(String[] groups) Adds a set of group names to the managed set of groups.
String[]	getGroups() Returns an array consisting of the elements of the managed set of groups; that is, the names of the groups whose members are the lookup services to discover.
void	removeGroups(String[] groups) Deletes a set of group names from the managed set of groups.
void	setGroups(String[] groups) Replaces all of the group names in the managed set with names from a new set.

Field Detail

ALL_GROUPS

static final String[] ALL_GROUPS

Convenience constant used to request that attempts be made to discover all lookup services that are within range, and which belong to any group.

NO_GROUPS

static final String[] NO_GROUPS

Convenience constant used to request that discovery by group membership be halted (or not started, if the group discovery mechanism is simply being instantiated).

Method Detail

getGroups

String[] getGroups()

Returns an array consisting of the elements of the managed set of groups; that is, the names of the groups whose members are the lookup services to discover. If the managed set of groups is empty, this method will return the empty array. If there is no managed set of groups, then null is returned; indicating that all groups are to be discovered. This method returns a new array upon each invocation.

Returns:

String array consisting of the elements of the managed set of groups

See Also:

setGroups(java.lang.String[])

addGroups

void addGroups(String[] groups)
               throws IOException

Adds a set of group names to the managed set of groups. Elements in the input set that duplicate elements already in the managed set will be ignored. Once a new name is added to the managed set, attempts will be made to discover all (as yet) undiscovered lookup services that are members of the group having that name. If the empty array (NO_GROUPS) is input, the managed set of groups will not change. Note that any entity that invokes this method must have DiscoveryPermission on each of the groups in the new set, otherwise a SecurityException will be propagated through this method.

Parameters:

groups - String array consisting of the group names to add to the managed set.

Throws:

IOException - because an invocation of this method may result in the re-initiation of the discovery process, which can throw an IOException when socket allocation occurs.

UnsupportedOperationException - this exception occurs when there is no managed set of groups to augment. That is, the current managed set of groups is null. If the managed set of groups is null, all groups are being discovered; thus, requesting that a set of groups be added to the set of all groups makes no sense.

NullPointerException - this exception occurs when either null is input to the groups parameter, or one or more of the elements of the groups parameter is null. If a null is input, then the entity is effectively requesting that "all groups" be added to the current managed set of groups; which is not allowed. (Note that if the entity wishes to change the managed set of groups from a finite set of names to "all groups", the setGroups method should be invoked with null input.)

See Also:

removeGroups(java.lang.String[])

setGroups

void setGroups(String[] groups)
               throws IOException

Replaces all of the group names in the managed set with names from a new set. Once a new group name has been placed in the managed set, if there are lookup services belonging to that group that have already been discovered, no event will be sent to the entity's listener for those particular lookup services. Attempts to discover all (as yet) undiscovered lookup services belonging to that group will continue to be made.

If null (ALL_GROUPS) is input to this method, then attempts will be made to discover all (as yet) undiscovered lookup services that are within range, and which are members of any group. If the empty array (NO_GROUPS) is input, then group discovery will cease until this method is invoked with an input parameter that is non-null and non-empty. Note that any entity that invokes this method must have DiscoveryPermission on each of the groups in the new set, otherwise a SecurityException will be propagated through this method.

Parameters:

groups - String array consisting of the group names that will replace the current names in the managed set.

Throws:

IOException - because an invocation of this method may result in the re-initiation of the discovery process, which can throw an IOException when socket allocation occurs.

See Also:

getGroups()

removeGroups

void removeGroups(String[] groups)

Deletes a set of group names from the managed set of groups. If the empty array (NO_GROUPS) is input, this method takes no action.

Parameters:

groups - String array consisting of the group names that will be removed from the managed set.

Throws:

UnsupportedOperationException - this exception occurs when there is no managed set of groups from which remove elements.

NullPointerException - this exception occurs when null is input to the groups parameter.

See Also:

addGroups(java.lang.String[])