US.3. Introduction to the Helper Utilities

US.3.1. The Discovery Utilities

The Jini Discovery Utilities Specification defines a set of general-purpose utility interfaces collectively referred to as the discovery management interfaces. Those interfaces define the policies to apply when implementing helper utilities that manage an entity’s discovery duties. Currently, the set of discovery management interfaces consists of the following three interfaces:

• DiscoveryManagement

• DiscoveryGroupManagement

• DiscoveryLocatorManagement

Because the discovery management interfaces provide a uniform way to define utility classes that perform discovery-related management duties on behalf of an entity, the discovery utilities specification defines a number of helper utility classes that implement one or more of these interfaces. Those classes are:

• LookupDiscovery

• LookupLocatorDiscovery

• LookupDiscoveryManager

The discovery utilities specification closes with a discussion of a set of low-level utility classes that can be useful when applying the discovery management policies to build higher-level helper utilities for discovery. Those classes are:

• Constants

• OutgoingMulticastRequest

• IncomingMulticastRequest

• OutgoingMulticastAnnouncement

• IncomingMulticastAnnouncement

• OutgoingUnicastRequest

• IncomingUnicastRequest

• OutgoingUnicastResponse

• IncomingUnicastResponse

US.3.1.1. The DiscoveryManagement Interface

The DiscoveryManagement interface defines methods related to the discovery event mechanism and discovery process termination. Through this interface an entity can register or unregister DiscoveryListener objects to receive discovery events, retrieve proxies to the currently discovered lookup services, discard a lookup service so that it is eligible for rediscovery, or terminate the discovery process.

US.3.1.2. The DiscoveryGroupManagement Interface

The DiscoveryGroupManagement interface defines methods and constants related to the management of the set containing the names of the groups whose members are the lookup services that are to be discovered via group discovery. The methods of this interface define how an entity retrieves or modifies the managed set of groups to discover.

US.3.1.3. The DiscoveryLocatorManagement Interface

The DiscoveryLocatorManagement interface defines methods related to the management of the set of LookupLocator objects corresponding to the specific lookup services that are to be discovered via locator discovery. The methods of this interface define how an entity retrieves or modifies the managed set of locators to discover.

US.3.1.4. The LookupDiscovery Helper Utility

The LookupDiscovery helper utility 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. This utility provides an implementation that makes the process of acquiring lookup service instances, based on no information other than group membership, which is much simpler for both services and clients.

US.3.1.5. The LookupLocatorDiscovery Helper Utility

The LookupLocatorDiscovery helper utility 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.

US.3.1.6. The LookupDiscoveryManager Helper Utility

The LookupDiscoveryManager is a helper utility class that organizes and manages all discovery-related activities on behalf of a Jini client or service. Rather than providing its own facility for coordinating and maintaining all of the necessary state information related to group names, locators, and listeners, such an entity can employ this class to provide those facilities on its behalf.

US.3.1.7. The Constants Class

The Constants class provides easy access to defined constants that may be useful when participating in the discovery process.

US.3.1.8. The OutgoingMulticastRequest Utility

The OutgoingMulticastRequest class provides facilities for marshalling multicast discovery requests into a form suitable for transmission over a network to announce one’s interest in discovering a lookup service.

US.3.1.9. The IncomingMulticastRequest Utility

The facilities provided by the IncomingMulticastRequest class encapsulate the details of the process of unmarshalling received multicast discovery requests into a form in which the individual parameters of the request may be easily accessed.

US.3.1.10. The OutgoingMulticastAnnouncement Utility

The OutgoingMulticastAnnouncement class encapsulates the details of the process of marshalling multicast discovery announcements into a form suitable for transmission over a network to announce the availability of a lookup service to interested parties.

US.3.1.11. The IncomingMulticastAnnouncement Utility

The IncomingMulticastAnnouncement class encapsulates the details of the process of unmarshalling multicast discovery announcements into a form in which the individual parameters of the announcement may be easily accessed.

US.3.1.12. The OutgoingUnicastRequest Utility

The OutgoingUnicastRequest class encapsulates the details of the process of marshalling unicast discovery requests into a form suitable for transmission over a network to attempt discovery of a specific lookup service.

US.3.1.13. The IncomingUnicastRequest Utility

The IncomingUnicastRequest class encapsulates the details of the process of unmarshalling unicast discovery requests into a form in which the individual parameters of the request may be easily accessed.

US.3.1.14. The OutgoingUnicastResponse Utility

The OutgoingUnicastResponse class encapsulates the details of the process of marshalling a unicast discovery response into a form suitable for transmission over a network to respond to a unicast discovery request.

US.3.1.15. The IncomingUnicastResponse Utility

The IncomingUnicastResponse class encapsulates the details of the process of unmarshalling a unicast discovery response into a form in which the individual parameters of the request may be easily accessed.

US.3.2. The Lease Utilities

The Jini Lease Utilities Specification defines helper utility classes, along with supporting interfaces and supporting classes, that encapsulate functionality which provides for the coordination, systematic renewal, and overall management of a set of leases associated with some object on behalf of another object. Currently, this specification defines only one helper utility class:

• LeaseRenewalManager

US.3.2.1. The LeaseRenewalManager Helper Utility

The LeaseRenewalManager is a helper utility class that organizes and manages all of the activities related to the renewal of the leases granted to a Jini client or service by another Jini service. Rather than providing its own facility for coordinating and maintaining all of the necessary state information related to lease renewal, such an entity can employ this class to provide those facilities on its behalf.

US.3.3. The Join Utilities

The Jini Join Utilities Specification defines helper utility classes, supporting interfaces, and supporting classes, that encapsulate functionality related to discovery and registration interactions that a well-behaved Jini service will typically have with a lookup service. Currently, this specification defines only one helper utility class:

• JoinManager

US.3.3.1. The JoinManager Helper Utility

The JoinManager is a helper utility class that performs all of the functions related to lookup service discovery, joining, lease renewal, and attribute management, functions that the programming model requires of a well-behaved Jini service. Rather than providing its own facility for providing such functions, a Jini service can employ this class to provide those facilities on its behalf.

US.3.4. The Service Discovery Utilities

The Jini Service Discovery Utilities Specification defines helper utility classes (with supporting interfaces and classes) that encapsulate functionality that aids a Jini service or client in acquiring services of interest, registered with the various lookup services with which the service or client wishes to interact. Currently, the service discovery utilities specification defines only one helper utility class:

• ServiceDiscoveryManager

US.3.4.1. The ServiceDiscoveryManager Helper Utility

The ServiceDiscoveryManager class is a helper utility class that any entity can use to create and populate a cache of service references, and with which the entity can register for notification of the availability of services of interest. Although the ServiceDiscoveryManager performs lookup discovery event handling for clients and services, the primary functionality the ServiceDiscoveryManager provides is service discovery and management.

The ServiceDiscoveryManager class can be asked to “discover” services an entity is interested in using and to cache the references to those services as each is found. The cache can be viewed as a set of services that the entity can access through a set of public, non-remote methods. The ServiceDiscoveryManager class also provides a mechanism for an entity to request notification when a service of interest is discovered for the first time or has encountered a state change (such as removal from all lookup services or attribute set changes).

For convenience, the ServiceDiscoveryManager class also provides versions of a method named lookup, which employs invocation semantics similar to the semantics of the lookup method of the ServiceRegistrar interface, specified in The Jini Technology Core Platform Specification, “Lookup Service”. Entities needing to find services on only an infrequent basis, or in which the cost of making a remote call is outweighed by the overhead of maintaining a local cache (for example, because of limited resources), may find this method useful.

All three mechanisms described above—local queries on the cache, service discovery notification, and remote lookups—employ the same template-matching scheme as that described in The Jini Technology Core Platform Specification, “Lookup Service”. Additionally, each mechanism allows the entity to supply an action object referred to as a filter. Such an object is a non-remote object that defines additional matching criteria that will be applied when searching for the entity’s services of interest. This filtering facility is particularly useful to entities that wish to extend the capabilities of the standard template-matching scheme.