A service reference added to the cache will be removed from the cache when all of the lookup services with which that service is registered have been discarded.

SD.2

Tests:

org.apache.river.qa.impl.

servicediscovery.event.

DiscardDownReDiscover,

DiscardServiceDown,

ServiceDiscardCacheTerminate

When a method of the ServiceDiscoveryManager invokes a remote method, although such an invocation may block other remote calls made in the ServiceDiscoveryManager, invocations of local methods will not be blocked.

SD.4

Tests:

org.apache.river.qa.spec.

servicediscovery.cache.

CacheDiscard,

CacheLookup,

CacheLookupFilterFilter,

CacheLookupFilterNoFilter,

CacheLookupNoFilterFilter

org.apache.river.qa.spec.

servicediscovery.event.

AddAttrServiceChanged,

ModifyAttrServiceChanged,

SetAttrServiceChanged

org.apache.river.qa.impl.

servicediscovery.event.

DiscardDownReDiscover,

DiscardServiceDown,

DiscardServiceUp,

ReRegisterBadEquals,

ReRegisterGoodEquals,

ServiceDiscardCacheTerminate

The equals method for this class returns true if and only if two instances of this class refer to the same object. That is, x and y are equal instances of this class if and only if x == y has the value true.

SD.4.1

Tests:

org.apache.river.qa.spec.

servicediscovery.

Equality

The constructor of the ServiceDiscoveryManager takes two arguments: an object that implements the DiscoveryManagement interface and a reference to a LeaseRenewalManager object.

SD.4.1.1

The constructor throws an IOException because construction of a ServiceDiscoveryManager may initiate the multicast discovery process, a process that can throw IOException.

SD.4.1.1

If a value of null is passed to the constructor as the DiscoveryManagement argument, an instance of the LookupDiscoveryManager utility class will be constructed to discover only those lookup services that are members of the public groups.

SD.4.1.1

Tests:

org.apache.river.qa.spec.

servicediscovery.

DefaultDiscoveryPublic

If a value of null is passed to the constructor as the LeaseRenewalManager argument, an instance of the LeaseRenewalManager utility class will be constructed, initially managing no Lease objects.

SD.4.1.1

The createLookupCache method takes three arguments: an instance of ServiceTemplate, an instance of ServiceItemFilter, and an instance of ServiceDiscoveryListener; and returns an object of type LookupCache.

SD.4.1.2

Tests:

org.apache.river.qa.spec.

servicediscovery.cache.

CacheDiscard,

CacheLookup,

CacheLookupFilterFilter,

CacheLookupFilterNoFilter,

CacheLookupNoFilterFilter

org.apache.river.qa.spec.

servicediscovery.event.

AddAttrServiceChanged,

ModifyAttrServiceChanged,

SetAttrServiceChanged

org.apache.river.qa.impl.

servicediscovery.event.

DiscardDownReDiscover,

DiscardServiceDown,

DiscardServiceUp,

ReRegisterBadEquals,

ReRegisterGoodEquals,

ServiceDiscardCacheTerminate

The ServiceDiscoveryListener argument of the createLookupCache method references an object that will receive notifications when services matching the input criteria are discovered for the first time.

SD.4.1.2

Tests:

org.apache.river.qa.spec.

servicediscovery.cache.

CacheDiscard,

CacheLookup,

CacheLookupFilterFilter,

CacheLookupFilterNoFilter,

CacheLookupNoFilterFilter

org.apache.river.qa.spec.

servicediscovery.event.

AddAttrServiceChanged,

ModifyAttrServiceChanged,

SetAttrServiceChanged

org.apache.river.qa.impl.

servicediscovery.event.

DiscardDownReDiscover,

DiscardServiceDown,

DiscardServiceUp,

ReRegisterBadEquals,

ReRegisterGoodEquals,

ServiceDiscardCacheTerminate

The ServiceDiscoveryListener argument of the createLookupCache method references an object that will receive notifications when services matching the input criteria have encountered a state change such as removal from all lookup services or attribute set changes.

SD.4.1.2

Tests:

org.apache.river.qa.spec.

servicediscovery.event.

AddAttrServiceChanged,

ModifyAttrServiceChanged,

SetAttrServiceChanged

org.apache.river.qa.impl.

servicediscovery.event.

DiscardDownReDiscover,

DiscardServiceDown,

DiscardServiceUp,

ReRegisterBadEquals,

ReRegisterGoodEquals,

ServiceDiscardCacheTerminate

If createLookupCache is invoked with a null ServiceDiscoveryListener argument, the instance of LookupCache returned by the invocation will send no instances of ServiceDiscoveryEvent.

SD.4.1.2

Once an instance of LookupCache is created, the filter associated with that instance will not change during the life of that LookupCache instance.

SD.4.1.2

Not testable

Once an instance of LookupCache is created, if the filter associated with that instance is changed so that its original behavior is modified, the effect on that LookupCache instance is undefined.

SD.4.1.2

If createLookupCache is invoked with a null ServiceTemplate argument, such an invocation is treated as equivalent to invoking createLookupCache with a ServiceTemplate argument constructed with all null arguments (all wildcards).

SD.4.1.2

If createLookupCache is invoked with a null ServiceItemFilter argument, then only template-matching will be employed to find the desired services.

SD.4.1.2

Tests:

org.apache.river.qa.spec.

servicediscovery.cache.

CacheLookup,

CacheLookupNoFilterFilter

org.apache.river.qa.spec.

servicediscovery.event.

AddAttrServiceChanged,

ModifyAttrServiceChanged,

SetAttrServiceChanged

org.apache.river.qa.impl.

servicediscovery.event.

DiscardDownReDiscover,

DiscardServiceDown,

DiscardServiceUp,

ReRegisterBadEquals,

ReRegisterGoodEquals,

ServiceDiscardCacheTerminate

The effects of modifying the contents of the object input to createLookupCache as the ServiceTemplate parameter – after the invocation of createLookupCache – are undefined.

SD.4.1.2

Although instances of LookupCache may receive – from one or more lookup services – multiple events signaling a state change related to a particular matching service, the LookupCache will send only a single corresponding event to the client’s listener. That is, for any matching service, the LookupCache will send a service discovery event to the client’s listener only once; after the LookupCache acquires the first reference to the matching service.

SD.4.1.2

For any matching service, the LookupCache will send a service removal event to the client’s listener only once; after all references to the matching service have been removed from every lookup service in the LookupCache’s managed set of lookup services.

SD.4.1.2

For any matching service, for each set of event(s) notifying the LookupCache that a particular modification has been made the attribute set associated with one of the service references, one service modification event will be sent to the client’s listener, but only if the attribute set state reflected in the received event represents an actual change in the service’s current attribute set state (as maintained by the LookupCache’s).

SD.4.1.2

The LookupCache will maintain a single attribute set state for each collection of service references that represent the same service. That single state will always be equivalent to the state reflected in the last attribute set modification event received by the LookupCache.

SD.4.1.2

All versions of the lookup method on the ServiceDiscoveryManager takes an instance of ServiceTemplate and an instance of ServiceItemFilter.

SD.4.1.3

If the lookup method on the ServiceDiscoveryManager is invoked with a null ServiceTemplate argument, such an invocation is treated as equivalent to invoking lookup with a ServiceTemplate argument constructed with all null arguments (all wildcards).

SD.4.1.3

If the lookup method on the ServiceDiscoveryManager is invoked with a null ServiceItemFilter argument, then only template-matching will be employed to find the desired services.

SD.4.1.3

The effects of modifying the contents of the object input as the ServiceTemplate parameter to the lookup method on the ServiceDiscoveryManager – while the invocation of lookup is in progress – are undefined.

SD.4.1.3

With respect to the versions of the lookup method on the ServiceDiscoveryManager that return a single instance of ServiceItem, whenever any of those versions of lookup are invoked and no service can be found that matches the desired criteria, null is returned.

SD.4.1.3

With respect to the versions of the lookup method on the ServiceDiscoveryManager that return an array of ServiceItem instances, whenever any of those versions of lookup are invoked and no service can be found that matches the desired criteria, an empty array is returned.

SD.4.1.3

With respect to the versions of the lookup method on the ServiceDiscoveryManager that return an array of ServiceItem instances, those versions of lookup take an int argument whose value represents the maximum number of matches that should be returned; the array returned by those versions of lookup will contain no more than that number of service references, but may contain fewer than that number.

SD.4.1.3

For each version of the lookup method on the ServiceDiscoveryManager, whenever a lookup service query returns a null service reference, the filter is bypassed, and the null service reference is excluded from the returned object.

SD.4.1.3

For each version of the lookup method on the ServiceDiscoveryManager, whenever a lookup service query returns a non-null service reference in which the associated array of attributes contains one or more null elements, the filter is still applied, and the (matching) service reference is included in the return object.

SD.4.1.3

With respect to the versions of the lookup method on the ServiceDiscoveryManager that return an array of ServiceItem instances, each service reference in the returned array will be unique with respect to all other service references in the array.

SD.4.1.3

For each version of the lookup method on the ServiceDiscoveryManager, whenever it is determined that a lookup service is unavailable (due to an exception or some other non-fatal error) while interacting with a lookup service from the managed set, the discard method will be invoked on the instance of DiscoveryManagement being employed by the ServiceDiscoveryManager.

SD.4.1.3

With respect to the versions of the lookup method on the ServiceDiscoveryManager that employ the blocking mechanism, each version takes a long argument whose value represents the number of milliseconds to wait for the desired service reference(s) to be discovered.

SD.4.1.3

For each version of the lookup method on the ServiceDiscoveryManager that employs the blocking mechanism, if the number of matching service references found throughout the available lookup services does not fall into the given desired range, as indicated by the parameters (or lack of parameters) of the particular version of lookup invoked, the method will wait the desired number of milliseconds until either an acceptable minimum number of service references are discovered, or the specified time period has passed.

SD.4.1.3

One version of the lookup method on the ServiceDiscoveryManager that employs the blocking mechanism takes two int arguments whose values represent, respectively, the acceptable minimum and the allowable maximum number of service references to discover.

SD.4.1.3

One version of the lookup method on the ServiceDiscoveryManager that employs the blocking mechanism implicitly uses a value of one for both the acceptable minimum and the allowable maximum number of service references to discover.

SD.4.1.3

Prior to blocking, each version of the lookup method on the ServiceDiscoveryManager that employs the blocking mechanism first queries each available lookup service in an attempt to retrieve a satisfactory number of matching services. Blocking occurs only if, after querying all of the available lookup services, the number of matching services found is less than the acceptable minimum.

SD.4.1.3

With respect to the versions of the lookup method on the ServiceDiscoveryManager that employ the blocking mechanism, if the waiting period passes before the desired minimum number of service references is found, the method will return the service references that have been discovered up to that point.

SD.4.1.3

With respect to the version of the lookup method on the ServiceDiscoveryManager that employs the blocking mechanism and returns an array of ServiceItem instances, if the waiting period passes and none of the desired services have been found, an empty array is returned.

SD.4.1.3

With respect to the version of the lookup method on the ServiceDiscoveryManager that employs the blocking mechanism and returns a single instance of ServiceItem, if the waiting period passes and the desired service has not been found, null is returned.

SD.4.1.3

With respect to the versions of the lookup method on the ServiceDiscoveryManager that employ the blocking mechanism, if – after querying all of the available lookup services – that initial query process produces the desired maximum number of service references, the method will return the results immediately, without blocking.

SD.4.1.3

Tests:

org.apache.river.qa.spec.

servicediscovery.lookup.

LookupWaitNoBlock

With respect to the version of the lookup method on the ServiceDiscoveryManager that employs the blocking mechanism and returns an array of ServiceItem instances, if – after querying all of the available lookup services – the number of matching services found is greater than or equal to the specified minimum, but less than the specified maximum, the method will return the currently discovered service references without blocking.

SD.4.1.3

Tests:

org.apache.river.qa.spec.

servicediscovery.lookup.

LookupMinMaxNoBlock,

LookupMinMaxNoBlockFilter,

With respect to the version of the lookup method on the ServiceDiscoveryManager that employs the blocking mechanism and returns an array of ServiceItem instances, if while blocking (after having queried all of the available lookup services, and finding less than the specified minimum number of matching services), the number of currently running matching services increases to a number greater than the specified minimum number, upon discovering that minimum number of services, the method will immediately stop blocking, and will return only that minimum number of services.

Note: the above is not expressed explicitly as a requirement in the specification. Should the spec be changed to make the requirement explicit, or should we leave it as a ‘derived’ requirement?

SD.4.1.3

Tests:

org.apache.river.qa.spec.

servicediscovery.lookup.

LookupMinMaxNoBlock,

LookupMinMaxNoBlockFilter

With respect to the versions of the lookup method on the ServiceDiscoveryManager that employ the blocking mechanism, if a non-positive value is input to the long argument that represents the number of milliseconds to wait for discovery of the desired service reference(s), the method will not block, but simply query the available lookup services and return whatever service reference(s) result from that query (or null or an empty array, depending the particular version of lookup).

SD.4.1.3

With respect to the version of the lookup method on the ServiceDiscoveryManager that employs the blocking mechanism and returns an array of ServiceItem instances, the values of the specified minimum and than the specified maximum must both be positive, otherwise, an IllegalArgumentException results.

SD.4.1.3

With respect to the version of the lookup method on the ServiceDiscoveryManager that employs the blocking mechanism and returns an array of ServiceItem instances, the value of the specified minimum must be less than or equal to the value of the specified, an IllegalArgumentException results.

SD.4.1.3

The versions of the lookup method on the ServiceDiscoveryManager that employ the blocking mechanism make a concurrency guarantee with respect to the discovery of new lookup services while blocking: while waiting for matching service reference(s) to be discovered, if one or more of the desired — but previously unavailable — lookup services is discovered and added to the managed set, those new lookup services will also be queried for the service(s) of interest.

SD.4.1.3

Tests:

org.apache.river.qa.spec.

servicediscovery.lookup.

LookupWait,

LookupWaitFilter

Each version of the lookup method on the ServiceDiscoveryManager that employs the blocking mechanism may throw an InterruptedException.

Each version of the lookup method on the ServiceDiscoveryManager that employs the blocking mechanism – while blocking on the discovery of matching service(s) – may be interrupted by invoking the interrupt method from the Thread class; which allows client’s of the ServiceDiscoveryManager to interrupt a blocking lookup method in the same way they would a sleeping thread.

SD.4.1.3

The getDiscoveryManager method returns an instance of the DiscoveryManagement interface.

SD.4.1.4

Tests:

org.apache.river.qa.spec.

servicediscovery.

DefaultDiscoveryPublic

The getLeaseRenewalManager method will return an instance of the LeaseRenewalManager class.

SD.4.1.5

The terminate method performs cleanup duties related to the termination of the event mechanism for lookup service discovery, the event mechanism for service discovery, and the cache management duties of the ServiceDiscoveryManager.

SD.4.1.6

The terminate method will terminate each LookupCache instance created and managed by the ServiceDiscoveryManager.

SD.4.1.6

If the discovery manager employed by the ServiceDiscoveryManager was created by the ServiceDiscoveryManager itself, the terminate method will terminate that discovery manager as well.

SD.4.1.6

If the discovery manager employed by the ServiceDiscoveryManager was not created by the ServiceDiscoveryManager, but was created externally and supplied to the ServiceDiscoveryManager, the terminate method will not terminate that discovery manager, and any reference to that discovery manager held by the client will remain valid, even after the termination of the ServiceDiscoveryManager has completed.

SD.4.1.6

If the client holds a reference to the lease renewal manager employed by the ServiceDiscoveryManager, that reference will remain valid after the termination of the ServiceDiscoveryManager, whether that lease renewal manager was created externally or by the ServiceDiscoveryManager itself.

SD.4.1.6

The ServiceDiscoveryManager makes certain concurrency guarantees with respect to an invocation of the terminate method while other method invocations are in progress: The termination process provided by the terminate method will not begin until completion of all invocations of the methods defined in the public interface of the ServiceDiscoveryManager; that is, until completion of invocations of createLookupCache, lookup, getDiscoveryManager, and getLeaseRenewalManager.

SD.4.1.6

Upon completion of the termination process, the semantics of all current and future method invocations on the current instance of the ServiceDiscoveryManager are undefined.

SD.4.1.6

A subset of the methods on the ServiceDiscoveryManager, when invoked, will result in a request for registration with the event mechanism of one or more lookup services. Those methods are createLookupCache and the versions of the lookup method that employ the blocking mechanism; and each of those methods must throw RemoteException.

SD.4.3

During the invocation of one of the methods on the ServiceDiscoveryManager that causes a registration request with a lookup service’s event mechanism, if a RemoteException (or any other non-fatal exception or error) is thrown during the attempt to register for lookup service events, that lookup service will be discarded and made eligible for re-discovery.

SD.4.3

During the invocation of one of the methods on the ServiceDiscoveryManager that causes a registration request with a lookup service’s event mechanism, if a RemoteException (or any other non-fatal exception or error) is thrown during an attempt to export the listener, the method from which that attempt is made will re-throw the same exception.

SD.4.3

During the invocation of one of the methods on the ServiceDiscoveryManager that causes a registration request with a lookup service’s event mechanism, the same listener instance must be exported to each lookup service from which events will be requested.

SD.4.3

During the invocation of one of the methods on the ServiceDiscoveryManager that causes a registration request with a lookup service’s event mechanism, the creation and export of the listener must occur prior to the event registration process.

SD.4.3

The receipt of an event notification indicating that a previously discovered lookup has been discarded must ultimately result in the cancellation and removal of all event leases that were granted by the discarded lookup service, and that are managed by the LeaseRenewalManager on behalf of the ServiceDiscoveryManager.

SD.5.1

Whenever a previously discovered lookup service is discarded, every previously discovered service reference that is registered with only that discarded lookup service (that is, which is not also registered with any of the currently discovered lookup services), must also be discarded from each instance of LookupCache that contains the service reference.

SD.5.1

The check method of the ServiceItemFilter interface defines the implementation of the additional matching criteria to apply to a ServiceItem object found through standard template matching. This method takes one argument: the ServiceItem object to test against the additional criteria. This method returns true if the input object satisfies the additional criteria, and false otherwise.

SD.5.2

Tests:

org.apache.river.qa.spec.

servicediscovery.cache.

CacheLookupFilterFilter,

CacheLookupFilterNoFilter,

CacheLookupNoFilterFilter

org.apache.river.qa.spec.

servicediscovery.cache.

LookupFilter,

LookupMaxFilter,

LookupMinEqualsMaxFilter,

LookupMinLessMaxFilter,

LookupMinMaxNoblockFilter,

LookupWaitFilter

Neither a null reference nor a ServiceItem object containing null fields will be passed into the check method of the ServiceItemFilter interface by the ServiceDiscoveryManager.

SD.5.2

Tests:

org.apache.river.qa.spec.

servicediscovery.cache.

LookupFilter,

LookupMaxFilter,

LookupMinEqualsMaxFilter,

LookupMinLessMaxFilter,

LookupMinMaxNoblockFilter,

LookupWaitFilter

If the parameter input to the check method of the ServiceItemFilter interface is a ServiceItem object that has non-null fields, but is associated with attribute sets containing null entries, this method must process that parameter in a reasonable manner.

SD.5.2

Untestable requirement

Should an exception occur during an invocation of the check method of the ServiceItemFilter interface, the semantics of how that exception is handled are undefined.

SD.5.2

Untestable

The check method of the ServiceItemFilter interface must not modify the contents of the input ServiceItem object; and the effects of any modification to that input parameter are undefined.

SD.5.2

Untestable requirement

The constructor of ServiceDiscoveryEvent takes three arguments: An instance of Object corresponding to the instance of LookupCache from which the given event originated, a ServiceItem reference representing the state of the service (associated with the given event) prior to the occurrence of the event, and ServiceItem reference representing the state of the service after the occurrence of the event.

SD.5.3

Tests:

org.apache.river.qa.spec.

servicediscovery.event.

AddAttrServiceChanged,

ModifyAttrServiceChanged,

SetAttrServiceChanged

org.apache.river.qa.impl.

servicediscovery.event.

DiscardDownReDiscover,

DiscardServiceDown,

DiscardServiceUp,

ReRegisterBadEquals,

ReRegisterGoodEquals,

ServiceDiscardCacheTerminate

If null is passed as the source parameter to the constructor of the ServiceDiscoveryEvent class, a NullPointerException is thrown.

SD.5.3

If null is passed as both the preEventItem and the postEventItem parameters to the constructor of the ServiceDiscoveryEvent class, a NullPointerException is thrown.

SD.5.3

The constructor of the ServiceDiscoveryEvent class will not modify the contents of either ServiceItem argument; and the effects of any modification to either input parameter are undefined

SD.5.3

Untestable requirement

The getPreEventServiceItem method of the ServiceDiscoveryEvent class returns an instance of ServiceItem containing the service reference corresponding to the given event. The service state reflected in the returned service item is the state of the service prior to the occurrence of the event.

SD.5.3

Tests:

org.apache.river.qa.spec.

servicediscovery.event.

AddAttrServiceChanged,

ModifyAttrServiceChanged,

SetAttrServiceChanged

org.apache.river.qa.impl.

servicediscovery.event.

DiscardDownReDiscover,

DiscardServiceDown,

DiscardServiceUp,

ReRegisterBadEquals,

ReRegisterGoodEquals,

ServiceDiscardCacheTerminate

If the event is a discovery event (as opposed to a removal or modification event), then the getPreEventServiceItem method of the ServiceDiscoveryEvent class will return null because the discovered service had no state in the cache prior to its discovery.

SD.5.3

The getPostEventServiceItem method of the ServiceDiscoveryEvent class returns an instance of ServiceItem containing the service reference corresponding to the given event. The service state reflected in the returned service item is the state of the service after the occurrence of the event.

SD.5.3

Tests:

org.apache.river.qa.spec.

servicediscovery.event.

AddAttrServiceChanged,

ModifyAttrServiceChanged,

SetAttrServiceChanged

org.apache.river.qa.impl.

servicediscovery.event.

DiscardDownReDiscover,

DiscardServiceDown,

DiscardServiceUp,

ReRegisterBadEquals,

ReRegisterGoodEquals,

ServiceDiscardCacheTerminate

If the event is a removal event, then the getPostEventServiceItem method of the ServiceDiscoveryEvent class will return null because the discovered service has no state in the cache after it is removed from the cache.

SD.5.3

The getPreEventServiceItem method of the ServiceDiscoveryEvent class does not return a copy of the service reference associated with the given event; but returns the appropriate service reference from the LookupCache instance itself.

SD.5.3

The getPostEventServiceItem method of the ServiceDiscoveryEvent class does not return a copy of the service reference associated with the given event; but returns the appropriate service reference from the LookupCache instance itself.

SD.5.3

Any instance of ServiceDiscoveryListener that receives an instance of the ServiceDiscoveryEvent class must not modify the contents of the object returned by getPreEventServiceItem; and the effects of any modification to that ServiceDiscoveryEvent instance are undefined.

SD.5.3

Any instance of ServiceDiscoveryListener that receives an instance of the ServiceDiscoveryEvent class must not modify the contents of the object returned by getPostEventServiceItem; and the effects of any modification to that ServiceDiscoveryEvent instance are undefined.

SD.5.3

When an instance of LookupCache receives from one of the managed lookup services, an event signaling the registration of a service of interest for the first time (or for the first time since the service has been discarded), that instance invokes the serviceAdded method on all instances of ServiceDiscoveryListener that are registered with the LookupCache instance.

SD.5.4

The serviceAdded method of the ServiceDiscoveryListener interface takes one argument: an instance of ServiceDiscoveryEvent containing references to the service item corresponding to the event, including representations of the service’s state both before and after the event.

SD.5.4

When an instance of LookupCache receives from one of the managed lookup services, an event signaling the removal of a service of interest from the last such lookup service with which it was registered, that instance invokes the serviceRemoved method on all instances of ServiceDiscoveryListener that are registered with the LookupCache instance.

SD.5.4

The serviceRemoved method of the ServiceDiscoveryListener interface takes one argument: a ServiceDiscoveryEvent object containing references to the service item corresponding to the event, including representations of the service’s state both before and after the event.

SD.5.4

When an instance of LookupCache receives from one of the managed lookup services, an event signaling the unique modification of the attributes of a service of interest (across the attribute sets of all references to the service), that instance invokes the serviceChanged method on all instances of ServiceDiscoveryListener that are registered with the LookupCache instance;

doing so notifies the client that the state of a service of interest has changed.

SD.5.4

The serviceChanged method of the ServiceDiscoveryListener interface takes one argument: a ServiceDiscoveryEvent object containing references to the service item corresponding to the event, including representations of the service’s state both before and after the event.

SD.5.4

Should an exception occur during an invocation of any of the methods defined by the ServiceDiscoveryListener interface, the semantics of how that exception is handled are undefined.

SD.5.4

Not testable

Each method defined by the ServiceDiscoveryListener interface must not modify the contents of the ServiceDiscoveryEvent parameter; the effects of any modification to that ServiceDiscoveryEvent instance are undefined.

SD.5.4

Not testable

The ServiceDiscoveryListener interface makes the following concurrency guarantee: for any given listener object that implements this interface, no two methods (either the same two methods or different methods) defined by the interface can be invoked at the same time by the same by the same instance of LookupCache.

SD.5.4

One version of the lookup method on the LookupCache takes only one argument: an instance of ServiceItemFilter; and returns only a single instance of ServiceItem that corresponds to the desired matching criteria.

SD.5.5.1

One version of the lookup method on the LookupCache takes two arguments: an instance of ServiceItemFilter and an int parameter whose value represents the maximum number of matches that should be returned. This version of lookup returns an array of service references in the form of an array of ServiceItem instances, each corresponding to the desired matching criteria. The array returned by this form of lookup will contain no more than the number of service references indicated by the value of the given int parameter, although it may contain less than that number.

SD.5.5.1

With respect to either version of the lookup method on the LookupCache, if null is the value of the ServiceItemFilter parameter, then no additional filtering will be performed. If ServiceItemFilter parameter is non-null, the semantics of that parameter are identical to those of the ServiceItemFilter parameter specified for a number of the methods defined in the interface of the ServiceDiscoveryManager utility class.

SD.5.5.1

With respect to the version of the lookup method on the LookupCache that returns an array of ServiceItem instances, the array returned will contain no more than the maximum number of service references indicated by the int parameter; and the service references in the returned array will be unique with respect to all other service references in the array.

SD.5.5.1

With respect to the version of the lookup method on the LookupCache that returns an array of ServiceItem instances, the value of the int parameter representing the maximum number of service references desired must be positive, otherwise an IllegalArgumentException will be thrown.

SD.5.5.1

With respect to the version of the lookup method on the LookupCache that returns a single instance of ServiceItem, if the associated LookupCache instance is empty, or if no service can be found that matches the desired criteria, then null is returned.

SD.5.5.1

With respect to the version of the lookup method on the LookupCache that returns an array of ServiceItem instances, if the associated LookupCache instance is empty, or if no service can be found that matches the desired criteria, then an empty array is returned.

SD.5.5.1

With respect to either version of the lookup method on the LookupCache, each version returns the actual service reference(s) selected from the associated LookupCache rather than copies of those reference(s).

SD.5.5.1

Not testable

With respect to either version of the lookup method on the LookupCache, the service reference(s) returned must not be modified; the effects of any modification to the returned service reference(s) are undefined.

SD.5.5.1

Not testable

The addListener method on the LookupCache will register a ServiceDiscoveryListener object with the event mechanism of a LookupCache instance. This method takes a single argument: a reference to the ServiceDiscoveryListener object register.

SD.5.5.1

If null is input to the addlistener method on the LookupCache, a NullPointerException results.

SD.5.5.1

Once an instance of ServiceDiscoveryListener is registered with a LookupCache object, that instance will be notified of all service references discovered to date.

SD.5.5.1

Once an instance of ServiceDiscoveryListener is registered with a LookupCache object, that instance will be notified as new services are discovered.

SD.5.5.1

Once an instance of ServiceDiscoveryListener is registered with a LookupCache object, that instance will be notified as existing services are modified.

SD.5.5.1

Once an instance of ServiceDiscoveryListener is registered with a LookupCache object, that instance will be notified as existing services are discarded.

SD.5.5.1

Should the LookupCache invoke a method on a registered instance of ServiceDiscoveryListener (a local call), any call from that method to a local method of the LookupCache is guaranteed not to result in a deadlock condition.

SD.5.5.1

The removeListener method on the LookupCache will remove a ServiceDiscoveryListener object from the set of listeners currently registered with a LookupCache instance. This method takes a single argument: a reference to the ServiceDiscoveryListener object to remove.

SD.5.5.1

Once all listeners are removed from the set of listeners associated with a particular instance of LookupCache, that instance will send no more ServiceDiscoveryEvent notifications.

SD.5.5.1

If the parameter value to the removeListener method on the LookupCache is null, or if the instance of ServiceDiscoveryListener passed to removeListener does not exist in the set of listeners maintained by the associated instance of LookupCache, then removeListener takes no action.

SD.5.5.1

The discard method on the LookupCache takes one argument: an instance of Object referencing the service reference to remove from the associated LookupCache instance.

SD.5.5.1

If null is input to the discard method on the LookupCache, the discard method takes no action.

SD.5.5.1

If the object input to the discard method on the LookupCache, matches (using the equals method) none of the service references in the associated instance of LookupCache, the discard method takes no action.

SD.5.5.1

The discard method on the LookupCache deletes the given service reference from the associated LookupCache instance, and sends a notification – indicating that the service reference has been discarded – to all instances of ServiceDiscoveryListener registered with that LookupCache instance.

SD.5.5.1

Upon successful completion of the discard method on the LookupCache, the given service reference is guaranteed to have been removed from the associated LookupCache instance.

SD.5.5.1

With respect to discarding a service reference from an instance of LookupCache, all implementations of the LookupCache interface – to prevent service references that have been discarded from the LookupCache instance from never being re-discovered – must do the following when a service is discarded from that LookupCache:

• place the reference to the discarded service in separate storage, and remove the reference from the storage maintained by the LookupCache instance

• wait an (implementation-dependent) amount of time that is likely to exceed the typical service lease duration

• flush the service reference that was set aside if, during the wait period, a ServiceEvent instance with a transition equal to TRANSITION_MATCH_NOMATCH is received

• place back into the local storage of the LookupCache instance, the service reference that was set aside if, during the wait period, a ServiceEvent instance with a transition equal to TRANSITION_MATCH_NOMATCH is not received; and send the appropriate event to any ServiceDiscoveryListener instances that may be registered with the LookupCache instance

SD.5.5.1

The terminate method of the LookupCache cancels all event leases granted by the lookup services that supplied the contents of LookupCache instance on which terminate is invoked, and unexports all remote listener objects registered with those lookup services.

SD.5.5.1

Not testable - Can't tell which exported classes are listener objects

Upon completion of the termination process, the semantics of all current and future method invocations on the current instance of LookupCache are undefined.

SD.5.5.1