net.jini.lookup

Interface LookupCache

public interface LookupCache

The LookupCache interface defines the methods provided by the object created and returned by the ServiceDiscoveryManager when a client-like entity invokes the createLookupCache method. It is within the object returned by that method that discovered service references, matching criteria defined by the entity, are stored. Through this interface, the entity may retrieve one or more of the stored service references, register and un-register with the cache's event mechanism, discard previously discovered service references to make them eligible for re-discovery, and terminate all of the cache's processing.

Author:

Sun Microsystems, Inc.

See Also:

ServiceDiscoveryManager

Method Summary

Modifier and Type	Method and Description
void	addListener(ServiceDiscoveryListener listener) Registers a ServiceDiscoveryListener object with the event mechanism of a LookupCache.
void	discard(Object serviceReference) Deletes a service reference from the cache and causes a notification to be sent to all registered listeners indicating that the service has been discarded.
ServiceItem	lookup(ServiceItemFilter filter) Finds a ServiceItem object that satisfies the given filter parameter.
ServiceItem[]	lookup(ServiceItemFilter filter, int maxMatches) Finds an array of instances of ServiceItem that each satisfy the given filter parameter.
void	removeListener(ServiceDiscoveryListener listener) Removes a ServiceDiscoveryListener object from the set of listeners currently registered with the LookupCache.
void	terminate() Performs cleanup duties related to the termination of the processing being performed by a particular instance of LookupCache.

Method Detail

lookup

ServiceItem lookup(ServiceItemFilter filter)

Finds a ServiceItem object that satisfies the given filter parameter.

The service item returned must have been previously discovered to be both registered with one or more of the lookup services in the managed set, and to match criteria defined by the entity.

The semantics of the filter argument are identical to those of the filter argument specified for a number of the methods defined in the interface of the ServiceDiscoveryManager utility class. This argument is intended to allow an entity to separate its filtering into two steps: an initial filter applied during the discovery phase, and a finer resolution filter applied upon retrieval from the cache. As with the methods of the ServiceDiscoveryManager, if null is the value of this argument, then no additional filtering will be performed.

Parameters:

filter - used for matching ServiceItems. A null value means no additional filtering should be applied.

Returns:

ServiceItem that satisfies the filter, and that was previously discovered to be registered with one or more lookup services in the managed set. A null value will be returned if no ServiceItem is found that matches the criteria or if the cache is empty.

lookup

ServiceItem[] lookup(ServiceItemFilter filter,
                     int maxMatches)

Finds an array of instances of ServiceItem that each satisfy the given filter parameter.

Each service item contained in the returned array must have been previously discovered to be both registered with one or more of the lookup services in the managed set, and to match criteria defined by the entity.

The semantics of the filter argument are identical to those of the filter argument specified for a number of the methods defined in the interface of the ServiceDiscoveryManager utility class. This argument is intended to allow an entity to separate its filtering into two steps: an initial filter applied during the discovery phase, and a finer resolution filter applied upon retrieval from the cache. As with the methods of the ServiceDiscoveryManager, if null is the value of this argument, then no additional filtering will be performed.

Parameters:

filter - used for matching ServiceItems. A null value means no additional filtering should be applied.

maxMatches - maximum number of matches to return. If this value is set to Integer.MAX_VALUE then all elements in the cache that match the criteria will be returned.

Returns:

ServiceItem[] array whose elements each satisfy the filter, and that were previously discovered to be registered with one or more lookup services in the managed set. An empty array will be returned if no ServiceItem is found that matches the criteria or if the cache is empty.

Throws:

IllegalArgumentException - if maxMatches is a negative number.

addListener

void addListener(ServiceDiscoveryListener listener)

Registers a ServiceDiscoveryListener object with the event mechanism of a LookupCache. The listener object will receive a ServiceDiscoveryEvent upon the discovery, removal, or modification of one of the cache's services. Once a listener is registered, it will be notified of all service references discovered to date, and will be notified as new services are discovered and existing services are modified or discarded. If the parameter value duplicates (using equals) another element in the set of listeners, no action is taken. If the parameter value is null, a NullPointerException is thrown.

Parameters:

listener - the ServiceDiscoveryListener object to register.

Throws:

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

See Also:

removeListener(net.jini.lookup.ServiceDiscoveryListener)

removeListener

void removeListener(ServiceDiscoveryListener listener)

Removes a ServiceDiscoveryListener object from the set of listeners currently registered with the LookupCache. Once all listeners are removed from the cache's set of listeners, the cache will send no more ServiceDiscoveryEvent notifications. If the parameter value is null, or if the parameter value does not exist in the managed set of listeners, no action is taken.

Parameters:

listener - the ServiceDiscoveryListener object to remove.

See Also:

addListener(net.jini.lookup.ServiceDiscoveryListener)

discard

void discard(Object serviceReference)

Deletes a service reference from the cache and causes a notification to be sent to all registered listeners indicating that the service has been discarded.

Parameters:

serviceReference - the service reference to discard.

terminate

void terminate()

Performs cleanup duties related to the termination of the processing being performed by a particular instance of LookupCache. For that instance, this method cancels all event leases granted by the lookup services that supplied the contents of the cache, and un-exports all remote listener objects registered with those lookup services. The terminate method is typically called when the entity is no longer interested in the contents of the LookupCache.