net.jini.lookup
Interface LookupCache

public abstract interface LookupCache

The LookupCache interface defines the methods provided by the object created and returned by the ClientLookupManager when a client-like entity invokes the createLookupCache method. It is within that object that discovered service references, which match 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, and terminate all of the cache's processing. This interface is used by ClientLookupManager

See Also:

ClientLookupManager

Method Summary

void	addListener(ServiceDiscoveryListener l) Registers a ServiceDiscoveryListener object with the event mechanism of a LookupCache.
void	discard(java.lang.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 filter.
ServiceItem[]	lookup(ServiceItemFilter filter, int maxMatches) Finds an array of ServiceItems that satisfy the filter.
void	removeListener(ServiceDiscoveryListener l) 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

public ServiceItem lookup(ServiceItemFilter filter)

Finds a ServiceItem object that satisfies the filter.

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 ClientLookupManager 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 ClientLookupManager, 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 filter 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

public ServiceItem[] lookup(ServiceItemFilter filter,
                            int maxMatches)

Finds an array of ServiceItems that satisfy the filter.

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 ClientLookupManager 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 ClientLookupManager, 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 filter 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[] that 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:

java.lang.IllegalArgumentException - if maxMatches is a negative number.

addListener

public void addListener(ServiceDiscoveryListener l)

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 is null, no action will be taken.

Parameters:

l - the ServiceDiscoveryListener object to register.

removeListener

public void removeListener(ServiceDiscoveryListener l)

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.

Parameters:

l - the ServiceDiscoveryListener object to remove.

discard

public void discard(java.lang.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 . Note that after the service has been discarded, there is no guarantee that the service will again become eligible for discovery.

Parameters:

serviceReference - the service reference to discard.

terminate

public 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.