Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

See Also:
  `ServiceDiscoveryManager`

Method Summary
`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

    public 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 `ServiceItem`s. 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

    public 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 `ServiceItem`s. 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

    public 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

    public 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

    public 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

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2004 Sun Microsystems, Inc. All rights reserved