|
ID |
ClientLookupManager
Utilility Requirement |
Section |
Comments |
|
|
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. |
7.4 |
Func: LCFT |
|
|
When a method of the ClientLookupManager invokes a remote method, although such an invocation may block other
remote calls made in the ClientLookupManager, invocations of local methods will
not be blocked. |
|
IF: CLMIF Func: LCFT |
|
|
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. |
|
IF: CLMIF |
|
|
A subset of the methods on the ClientLookupManager, 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 so-called blocking versions of the lookup method described below. |
|
Func: CLMRET1-3 |
|
|
Furthermore, each of these methods must throw RemoteException. |
|
Func: CLMRET1-3 |
|
|
If a RemoteException (or any other
non-fatal exception or error) is thrown during an attempt to register for
events from a lookup service, that lookup service will be discarded and made
eligible for re-discovery. |
|
Func: CLMRET1-3, CLMLT |
|
|
On the other hand, if the RemoteException is thrown during an attempt to export the listener, the method will
exit and the exception will be propagated. |
|
Func: CLMRET1-3 |
|
|
In order to facilitate exporting the listener, the
entity — whether it is a Jini client or a Jini service — is responsible for providing
and advertising a mechanism through which each lookup service will acquire
the listener’s stub classes. |
|
Func: CLMRET1-3 |
|
|
The constructor of the ClientLookupManager takes two arguments: an object that implements the DiscoveryManagement interface and a reference to a LeaseRenewalManager object. |
|
IF tests: DMIF, DGMIF, DLMIF, LCIF, CLMIF, LCEIFT Func tests: DMAR, DGMAR1, LCFT, LCF2T, LCEFT |
|
|
The constructor throws an IOException because construction of a ClientLookupManager may
initiate the multicast discovery process, a process that can throw IOException. |
|
Func: CLMIOET |
|
|
A value of null may be passed as the DiscoveryManagement argument. If the value of the argument is null, then an instance of the LookupDiscoveryManager utility
class will be constructed to listen for events announcing the discovery of
only those lookup services that are members of the public group. |
|
IF tests: DMIF, DGMIF, DLMIF, LCIF, CLMIF, LCEIFT Func tests: DMAR, DGMAR1, LCFT, LCF2T, LCEFT |
|
|
A value of null may be passed as the LeaseRenewalManager argument. If the value of the argument is null, an instance of the LeaseRenewalManager class
will be created, initially managing no Lease objects. |
|
IF tests: DMIF, DGMIF, DLMIF, LCIF, CLMIF, LCEIFT Func tests: DMAR, DGMAR1, LCFT, LCF2T, LCEFT |
|
|
The createLookupCache … This
method returns an object of type LookupCache. |
|
IF tests: LCIF, CLMIF, LCEIFT Func tests: LCFT, LCF2T, LCEFT |
|
|
The createLookupCache method
takes three arguments: an instance of ServiceTemplate, an instance
of ServiceItemFilter, and an instance of ServiceDiscoveryListener. |
|
IF tests: LCIF, CLMIF, LCEIFT Func tests: LCFT, LCF2T, LCEFT |
|
|
As a convenience, a null reference input
to the template argument is treated as equivalent to inputting a ServiceTemplate constructed with all null arguments (all wildcards). |
|
IF tests: LCIF, CLMIF, LCEIFT Func tests: LCFT, LCF2T |
|
|
It is for this reason that the effects of modifying
the contents of the input template, after this method is invoked, are
undefined. |
|
Not testable |
|
|
If a null value is passed as the filter
argument, then only template-matching will be employed to find the desired
services. |
|
Func tests: LCIF, CLMIF, LCEIFT, LCEFT |
|
|
Furthermore, once an instance of the cache is created,
any filter associated with that instance will not change during the life of
that particular cache. |
|
Not testable |
|
|
The listener argument references an object that will
receive notifications when services matching the input criteria are
discovered for the first time |
|
Func tests: LCFT, LCF2T, LCEFT |
|
|
The listener argument references an object that will
receive notifications when services … have encountered a state change such as
removal from all lookup services or attribute set changes. |
|
Func tests: LCFT, LCEFT |
|
|
for any matching service … The cache will send a
service discovery event to the entity only once: after the cache acquires the
first reference to the matching service. |
|
Func tests: LCFT |
|
|
for any matching service … The cache will send a
service removal event to the entity only once: after every reference to the
service has had its lease expire or cancelled; that is, only after all
references to the matching service have been removed from every lookup
service in the cache’s managed set. |
|
Func tests: LCEFT |
|
|
for any matching service … For each set of event(s)
notifying the cache that a particular modification has been made to the
attribute set associated with one of the service references, one service
modification event will be sent to the entity; 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 cache). |
|
Func tests: LCFT, LCF2T |
|
|
… the cache should be viewed as maintaining 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 cache. |
|
Func: CLMCST |
|
|
The lookup method …
[takes] an instance of ServiceTemplate and an instance of ServiceItemFilter. |
|
IF: CLMIF Func: CLMLT |
|
|
The lookup method … A null reference value for the template argument is
treated as the equivalent of a “wildcarded” ServiceTemplate. |
|
IF: CLMIF Func: CLMLT |
|
|
The effects of modifying the contents of the template while the invocation is in progress are unpredictable and undefined |
|
Not testable |
|
|
The lookup method … If null is the value for the filter argument, then
only template-matching will be employed to find the desired services. |
|
IF: CLMIF Func: CLMLT |
|
|
The lookup method … If no
service can be found that matches the desired criteria, then the versions of lookup from the first category — those that return a single instance of ServiceItem — will return null; |
|
IF: CLMIF Func: CLMLT |
|
|
The lookup method … If no
service can be found that matches the desired criteria, then the versions
from the second category — those that return an array of ServiceItem instances — will return an empty array. |
|
IF: CLMIF Func: CLMLT |
|
|
Each of the versions of lookup that return return
an array of ServiceItem
objects takes as one of arguments an int that represents the maximum number of matches that should be returned.
The array returned by these methods will contain no more than that number of
service references, although it may contain fewer than that number. |
|
Func: CLMLT |
|
|
For all of the versions of lookup, whenever a lookup service query returns a null service reference, the filter will be by-passed. |
|
Func: CLMLT |
|
|
For all of the versions of lookup … whenever a lookup service query returns a non-null service reference in which one or more elements of the associated attributeSets array is null, the filter will be applied, but with the null elements of the attributeSets array removed. |
|
Func: CLMLT |
|
|
For all of the versions of lookup … Upon finding a successful match, the service item will be returned in
the appropriate way, with the null elements of the attributeSets array removed. |
|
Func: CLMLT |
|
|
For all of the versions of lookup … when a set of service references is returned by lookup, each service reference in the return set will be unique with respect
to all other service references in the set. |
|
Func: CLMLT |
|
|
If 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, all versions of lookup will invoke the discard method on the instance of DiscoveryManagement being employed by the ClientLookupManager. |
|
Func: CLMLT |
|
|
As noted above, each category contains a version of lookup that provides a feature in which the entity can request that if the
number of service references found throughout the available lookup services
does not fall into a desired range, the method will wait a finite period of
time until either an acceptable minimum number of service references are
discovered, or the specified time period has passed. |
|
IF: CLMIF Func: CLMLT |
|
|
The versions of lookup providing this
blocking feature each takes as one of its parameters a value of type long that represents the number of milliseconds to wait for the service to
be discovered. |
|
IF: CLMIF Func: CLMLT |
|
|
The versions of lookup providing this
blocking feature may throw an InterruptedException. |
|
IF: CLMIF |
|
|
Thus, while the method is blocking on the discovery of
matching service(s), it may be interrupted by invoking the interrupt method from the Thread class. The intent of this mechanism is to allow the
entity to interrupt a blocking lookup in the same way
it would a sleeping thread. |
|
IF: CLMIF |
|
|
Prior to blocking, each of these versions of lookup first queries each available lookup service in an attempt to retrieve a
satisfactory number of matching services. |
|
Func: CLMLT |
|
|
Blocking occurs only if after querying all of the
available lookup services, the number of matching services found is less than
the acceptable minimum. |
|
IF: CLMIF Func: CLMLT |
|
|
If the waiting period passes before that minimum
number of service references is found, the method will return the service
references that have been discovered up to that point. |
|
IF: CLMIF Func: CLMLT |
|
|
If the waiting period passes and no services have been
found, null or an empty array (depending on the version of lookup) will be returned. |
|
Func: CLMLT |
|
|
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. If the
initial query process produces the desired maximum number of service
references, the method will return the results immediately. |
|
Func: CLMLT |
|
|
If a non-positive value is input to the waitDur argument, then the method will not wait. It will simply query the
available lookup services and employ the return semantics described above. |
|
IF: CLMIF Func: CLMLT |
|
|
The values of the minMatches and maxMatches arguments must both be positive, otherwise, an IllegalArgumentException will be thrown. |
|
IF: CLMIF Func: CLMLT |
|
|
and maxMatches must be greater
than or equal to minMatches; otherwise, an IllegalArgumentException will be thrown. |
|
IF: CLMIF Func: CLMLT |
|
|
The blocking versions of lookup make a concurrency guarantee with respect to the discovery of new
lookup services during the wait period. That is, 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. |
|
Func: CLMLT |
|
|
The getDiscoveryManager method
will return an instance of the DiscoveryManagement interface. |
|
IF tests: DMIF, DGMIF, DLMIF, CLMIF Func tests: DMAR, DGMAR1 |
|
|
The getLeaseRenewalManager method
will return an instance of the LeaseRenewalManager class. |
|
IF: CLMIF |
|
|
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 ClientLookupManager. |
|
Func: CLMTT |
|
|
… the terminate method will do
the following: Either remove all listener objects registered for receipt of DiscoveryEvent objects or, if the discovery manager employed by the ClientLookupManager was created by the ClientLookupManager itself, terminate all discovery processing
being performed by that manager object on behalf of the entity. |
|
Func: CLMTT |
|
|
… the terminate method will do
the following: Cancel all event leases granted by each lookup service in the managed
set of lookup services. |
|
Func: CLMTT |
|
|
… the terminate method will do
the following: Un-export all remote listener objects registered with each lookup
service in the managed set. |
|
Not testable - Can't tell which exported classes are listener objects |
|
|
… the terminate method will do
the following: Terminate all threads involved in the process of retrieving and storing
references to discovered services of interest. |
|
Not testable - Can't tell which threads are associated with discovery |
|
|
The termination process described above will not begin
until completion of all invocations of the methods defined in the public
interface of the ClientLookupManager; that is, until completion of
invocations of createLookupCache, lookup, getDiscoveryManager, and getLeaseRenewalManager. |
|
Func: CLMTT |
|
|
Additionally, once the termination process has begun,
no remote method invocations will be made by the ClientLookupManager, and all other method invocations on the ClientLookupManager will not return until the termination process has completed. |
|
Not (easily) testable |
|
|
Upon completion of the termination process, the
semantics of all current and future method invocations on the current
instance of the ClientLookupManager are undefined. |
|
Not testable |
|
|
The receipt of an event notification indicating that a
lookup service from the managed set 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 ClientLookupManager. |
|
Func: CLMTT |
|
|
Furthermore, every service reference stored in the
cache that is registered with the discarded lookup service but is not
registered with any of the remaining lookup services in the managed set, will
be “discarded” as well. |
|
Func: CLMTT |
|
|
ServiceItemFilter Interface --The check method 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. |
7.5.2 |
Func: LCFT, LCF2T |
|
|
The check method … This
method returns true
if the input object satisfies the additional criteria,
and false otherwise. |
|
Func: LCFT, LCF2T |
|
|
Neither a null reference nor a ServiceItem object containing null fields will be passed into this method by the ClientLookupManager. |
|
Func: LCFT, LCF2T |
|
|
If the parameter input to this method 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. |
|
Untestable requirement |
|
|
This method must not modify the contents of the input ServiceItem object. |
|
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 |
7.5.3 |
IF: LCEIFT |
|
|
The constructor of ServiceDiscoveryEvent takes three arguments: …A ServiceItem reference
representing the state of the service (associated with the given event) prior
to the occurrence of the event |
|
IF: LCEIFT |
|
|
Note that the constructor will not modify the contents
of either ServiceItem
argument. |
|
IF: LCEIFT |
|
|
The constructor of ServiceDiscoveryEvent takes three arguments: … A ServiceItem reference
representing the state of the service after the occurrence of the event |
|
IF: LCEIFT |
|
|
Depending on the nature of the discovery event, a null reference may be passed as one or the other of the remaining
parameters, but never both. |
|
IF: LCEIFT |
|
|
If null is passed as both the preEventItem and the postEventItem parameters, a NullPointerException will be thrown. |
|
IF: LCEIFT |
|
|
The getPreEventServiceItem method
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. |
|
IF: LCEIFT Func: LCEFT |
|
|
If the event is a discovery event (as opposed to a
removal or modification event), then this method will return null because the discovered service had no state in the cache prior to its
discovery. |
|
IF: LCEIFT Func: LCEFT |
|
|
The getPostEventServiceItem method
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. |
|
IF: LCEIFT Func: LCEFT |
|
|
If the event is a removal event, then this method will
return null because the discovered service has no state in the cache after it is removed
from the cache. |
|
IF: LCEIFT Func: LCEFT |
|
|
Because making a copy can be a very expensive process,
neither accessor method returns a copy of the service reference associated
with the given event. listeners (see ServiceDiscoveryListener next) that receive a ServiceDiscoveryEvent must not
modify the contents of the object returned by these methods. |
|
IF: LCEIFT |
|
|
… when the cache 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), the cache invokes the serviceAdded method on all
instances of ServiceDiscoveryListener that are registered with the cache. |
7.5.4 |
Func: LCEFT |
|
|
This method 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. |
|
Func: LCEFT |
|
|
When the cache receives, from a managed lookup
service, an event signaling the removal of a service of interest from the
last such lookup service with which it was registered, the cache invokes the serviceRemoved method on all instances of ServiceDiscoveryListener that are registered with the cache. |
|
Func: LCEFT |
|
|
This method 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. |
|
Func: LCEFT |
|
|
When the cache receives, from a managed lookup
service, an event signaling the unique modification of the attributes of a
service of interest (across the attribute sets of all references to the
service), the cache invokes the serviceChanged method on all
instances of ServiceDiscoveryListener
that are registered with the cache. Doing so notifies
the entity that the state of a service of interest has changed. |
|
Func: LCEFT |
|
|
The serviceChanged method 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. |
|
Func: LCEFT |
|
|
Each method defined by this interface must not modify
the contents of the ServiceDiscoveryEvent parameter. |
|
Not testable |
|
|
This 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 cache. |
|
Func: LCECT |
|
|
(LookupCache)
Depending on which version is invoked, the lookup method of the LookupCache interface returns one or more elements, which match the input criteria,
and that were stored in the associated cache. The object returned is either a
single instance of ServiceItem, or a set of service references in
the form of an array of ServiceItem objects. |
7.5.5 |
IF: LCIF Func: LCFT, LCF2T, LCEFT |
|
|
One argument is common to both forms of lookup: an instance of ServiceItemFilter. 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. |
|
IF: LCIFT Func: LCFT, LCEFT |
|
|
… if null is the value of this argument, then
no additional filtering will be performed. |
|
IF: LCIF Func: LCFT, LCEFT, LCF2T |
|
|
The second form of the lookup method of the LookupCache interface takes an additional argument: a parameter of type int that represents the maximum number of matches that should be returned. The
array returned by this form of lookup will contain no
more than the requested number of service references, although it may contain
less than that number. |
|
IF: LCIF Func: LCFT, LCF2T, LCEFT |
|
|
The value input to this argument must be positive,
otherwise an IllegalArgumentException
will be thrown. |
|
IF: LCIF Func: LCFT |
|
|
If the cache is empty, or if no service can be found
that matches the input criteria, then the first from of lookup will return null; |
|
IF: LCIF Func: LCFT, LCEFT |
|
|
… whereas the second form of lookup will return an empty array. |
|
IF: LCIF Func: LCFT, LCEFT |
|
|
… each form returns the actual service reference(s)
from the cache itself. Because of this, entities that invoke either form of
this method must not modify the contents of the service reference(s)
returned. |
|
Not testable |
|
|
The addListener method will
register a ServiceDiscoveryListener
object with the event mechanism of a LookupCache. |
|
IF: LCIF Func: LCFT, LCEFT |
|
|
Once a listener is
registered, it will be notified of all service references discovered to date,
|
|
IF: Func: LCFT, LCEFT |
|
|
Once a listener is
registered, ... will be notified as new services are discovered |
|
IF: Func: LCFT, LCF2T, LCEFT, |
|
|
Once a listener is
registered, ... will be notified as existing services are modified |
|
IF: Func: LCFT, LCF2T, LCEFT, |
|
|
Once a listener is
registered, ... will be notified as existing services are discarded. |
|
IF: Func: LCFT, LCEFT, |
|
|
If the parameter value is null,no action will be taken. |
|
IF: LCIF Func: LCFT |
|
|
Should the LookupCache invoke a method
on a registered listener (a local call), any call from that method to a local
method of the LookupCache
is guaranteed not to result in a deadlock condition. |
|
Func: CLMLCRT |
|
|
The removeListener method will
remove a ServiceDiscoveryListener
object from the set of listeners currently registered
with a LookupCache. |
|
IF: LCIF Func: LCFT, LCEFT |
|
|
Once all listeners are removed from the cache’s set of
listeners, the cache will send no more ServiceDiscoveryEvent notifications. |
|
Func: LCFT |
|
|
If the parameter value to removeListener is null, or if the listener passed to this method does not exist in the set of
listeners maintained by the implementation class, then this method will take
no action. |
|
IF: LCIF Func: LCFT |
|
|
The discard method takes one argument: an instance of Object referencing the service reference to remove from the cache. |
|
IF: Func: LCFT |
|
|
The discard method not only
deletes the service reference from the cache, |
|
IF: Func: LCFT |
|
|
The discard method … sends
a notification to all registered listeners indicating that the service has
been discarded. |
|
IF: Func: LCFT |
|
|
The terminate method …
cancels all event leases granted by the lookup services that supplied the
contents of the cache, |
|
IF: Func: LCFT |
|
|
The terminate method …
un-exports all remote listener objects registered with those lookup services. |
|
IF: Func: LCFT |