JINI SERVICE DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`121
`
`The effects of modifying the contents of the tmp] parameter while the invo-
`cation is in progress are unpredictable and undefined.
`
`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, whereas the versions from the second cate-
`gory—thosethat return an array of ServiceItem instances—will return an empty
`array.
`The versions of lookup from the first category can be used in a fashion simi-
`lar to the first form of the lookup methoddefined in the ServiceRegistrar inter-
`face described in The Jini Technology Core Platform Specification, “Lookup
`Service”. That is, an entity would typically invoke one of these versions of lookup
`whenit wishesto find a single service reference and the particular lookup service
`with whichthat service reference is registered is unimportantto the entity.
`Each version of lookup defined in the ServiceDiscoveryManager differs
`with the corresponding version of lookup in ServiceRegistrar in the following
`ways:
`
`@ The versions of lookup defined in the ServiceDiscoveryManager query
`multiple lookup services(the order in which the lookup services are queried
`is dependent on the implementation).
`
`@ The versions of lookup defined in the ServiceDiscoveryManager can
`apply additional matchingcriteria, in the form ofa filter object, when decid-
`ing whether a service reference found through standard template matching
`should be returnedto the entity.
`
`The versions of lookup that return an array of ServiceItem objects can be
`used in a fashion similar
`to the second form of lookup defined in the
`ServiceRegistrar interface. That is, an entity would typically invoke these ver-
`sions of lookup whenit wishes to find multiple service references matching the
`input criteria. Each of the versions of lookup that return an array of ServiceItem
`objects takes as one of its arguments an int parameter, maxMatches, that repre-
`sents the maximum number of matches that should be returned. The array
`returned by these methods will contain no more than maxMatches service refer-
`ences, although it may contain fewer than that number.
`Aswith the versions of lookup that return a single instance of ServiceItem,
`multiple queries andfiltering are also notable differences between the second-cat-
`egory versions of this method and their counterpart in ServiceRegistrar.
`For each version of lookup, whenever a lookup service query returns a nul
`service reference,the filter is bypassed, and the service reference is excluded from
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`131
`
`131
`
`

`

`122
`
`THE SEMANTICS
`
`the return object. On the other hand,if the query returns a non-nu11 servicerefer-
`ence in which the associated array of attribute contains one or more null ele-
`ments, the filter is still applied and the service reference is included in the return
`object.
`Each version of lookup may be confronted with duplicate references during a
`search for a service of interest. This is because the same service may register with
`more than one lookup service in the managed set. As with the cache, 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 referencesin the set, as determined
`by the equals methodprovidedby eachreference.
`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 man-
`aged set, all versions of lookup will invoke the discard method onthe instance
`of DiscoveryManagement being employed by the ServiceDiscoveryManager.
`Doing so will result in the unavailable lookup service being discarded and made
`eligible for rediscovery.
`Recall that the propagation of modifications to a service’s attributes across a
`set of lookup services typically occurs asynchronously. It is for this reason that
`while invoking lookup to find a set of matching services, it is possible that the set
`returned may contain multiple references having the same service ID with differ-
`ent attributes. Note that although this sort of inconsistent state can also occurif the
`entity employs a cache, the cache will eventually reflect the correct state.
`
`The Blocking Feature of 1ookup
`
`As noted above, each category contains a version of lookup that provides a fea-
`ture in which the entity can request that if the numberof 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 num-
`ber of service references are discovered or the specified time period has passed.
`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. In addition to RemoteException (described
`previously for these methods), each of these versions of lookup may throw an
`InterruptedException.
`One of these blocking versions of lookup implicitly uses a value of one for
`both the acceptable minimum and the allowable maximum numberofservice ref-
`erences to discover. The other blocking version requires that the entity specify the
`range through the minMatches and maxMatches parameters, respectively.
`Prior to blocking, each of these versions of lookup first queries each available
`lookup service in an attempt to retrieve a satisfactory number of matchingser-
`
`132
`
`132
`
`

`

`JINI SERVICE DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`123
`
`vices. Whether or not the method actually blocks is dependent on how many
`matching service references are found during the query process. 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 the waiting period (mea-
`sured from when blocking first begins) passes before that minimum number of
`service references is found, the methodwill return the service references that have
`been discovered up to that point. If the waiting period passes and no services have
`been found, nu11 or an empty array (depending onthe version of lookup) will be
`returned.
`If, after querying all of the available lookup services, the number of matching
`services found is greater than or equal to the specified minimum butless than the
`specified maximum, the method will return the currently discovered service refer-
`ences without blocking. If the initial query process produces the desired maxi-
`mum number of service references,
`the method will
`return the results
`immediately.
`The blocking versions of lookup are quite useful to entities that cannot pro-
`ceed until such a service of interest is found. If a non-positive value is input to the
`waitDur argument, then the method will not wait. It will simply query the avail-
`able lookup services and employ the return semantics described above.
`The values of the minMatches and maxMatches arguments must both be posi-
`tive, and maxMatches must be greater than or equal to minMatches; otherwise, an
`T1legalArgumentException will be thrown.
`The blocking versions of lookup makea 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—butpreviously unavailable—lookup services is discovered and added to
`the managedset, those new lookupservices will also be queried for the service(s)
`of interest.
`In addition, the blocking versions of lookup throw InterruptedException.
`When an entity invokes either version with valid parameters, the entity may
`decide during the wait period that it no longer wishes to wait the entire period for
`the method to return. 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 inter-
`rupt a blocking lookup in the same way it would a sleeping thread.
`
`SD.4.1.4 The getDiscoveryManager Method
`
`implements the
`that
`The getDiscoveryManager method returns an object
`DiscoveryManagement interface. The object returned by this method providesthe
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`133
`
`133
`
`

`

`124
`
`THE SEMANTICS
`
`ServiceDiscoveryManager with the ability to set discovery listeners and to dis-
`card previously discovered lookup services when they are found to be unavailable.
`This method takes no arguments.
`
`SD.4.1.5 The getLeaseRenewalManager Method
`
`The getLeaseRenewalManager method returns a LeaseRenewalManager object.
`The object returned by this method managesthe leases requested and held by the
`ServiceDiscoveryManager.In general, these leases correspond to the registra-
`tions made by the ServiceDiscoveryManager with the event mechanism of each
`lookup service in the managed set. This method takes no arguments.
`
`SD.4.1.6 The terminate Method
`
`The terminate method performs cleanup duties related to the termination of the
`event mechanism for /ookup service discovery, the event mechanism for service
`discovery, and the cache managementduties of the ServiceDiscoveryManager.
`Thatis, the terminate method will terminate each LookupCache instance created
`and managed by the ServiceDiscoveryManager. Additionally, if the discovery
`manager employed by the ServiceDiscoveryManager was created by the
`ServiceDiscoveryManager itself, then the terminate method will also termi-
`nate that discovery manager.
`Note that if the discovery manager was created externally and supplied to the
`ServiceDiscoveryManager, then any reference to that discovery manager held
`by the entity will remain valid, even after the ServiceDiscoveryManager has
`been terminated. Similarly, if the entity holds a reference to the lease renewal
`manager employed by the ServiceDiscoveryManager,that reference will also
`remain valid after termination, whether lease renewal managerwascreated exter-
`nally or by the ServiceDiscoveryManager itself.
`The ServiceDiscoveryManager makescertain concurrency guarantees with
`respect to an invocation of terminate while other method invocations are in
`progress. The termination process described above will not begin until completion
`of all
`invocations of the public methods defined in the public interface of
`ServiceDiscoveryManager;
`that
`is, until
`completion of
`invocations of
`createLookupCache,
`lookup,
`getDiscoveryManager,
`and
`getLeaseRenewalManager.
`Upon completion of the termination process, the semantics of all current and
`
`
`
`future method on_theinvocations terminated instance of the
`
`
`
`ServiceDiscoveryManager are undefined.
`
`134
`
`134
`
`

`

`JINI SERVICE DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`125
`
`SD.4.2 Defining Service Equality
`
`The ability to accurately determine when two different service references are
`equal is very important to the ServiceDiscoveryManager in general, and the
`LookupCache in particular. Any restriction placed onthat ability can result in inef-
`ficient and undesirable behavior. Storing and managing duplicate service refer-
`ences—that is, proxies that refer to the same version of the same back end
`service—is usually viewed as undesirable. In other words, when storing and man-
`aging service references, it is very desirable to be able to determine not only that
`two different proxies refer to the same back endservice,but if they do refer to the
`same back end, whether or not the current version of the referenced service has
`been replaced with a new version.
`The mechanism employed by the LookupCache to avoid storing duplicate ser-
`vice references is the equals method provided by the discovered services them-
`selves. This is because an individual well-behaved service of interest will usually
`register with multiple lookup services, and for each lookup service with which
`that service registers, the LookupCache will receive a separate event containing a
`reference to the service. When the LookupCache receives events from multiple
`lookupservices, the service ID (retrieved from the service reference in the event)
`together with the equals method providedby the serviceitself, is used to distin-
`guish the service references from each other. In this way, when a new eventarrives
`containing a reference associated with the sameservice as an already-stored refer-
`ence, the LookupCache can determine whether the new reference is a duplicate or
`the service has been replaced with a new version ofitself. In the former case, the
`duplicate would be ignored;in the latter case, the old reference would be replaced
`with the new reference.
`Thus, the LookupCache relies on the provider of each service to override the
`equals method inherited from the class Object with an implementation that
`allows for the identification of duplicate service proxies. In addition to the equals
`method, each service should also provide a proper implementation of the
`hashCode method. This is because even if an entity never explicitly calls on the
`equals method to compareservice references, those references maystill be stored
`in container classes (for example, Hashtable) where such comparisons are made
`“under the covers.” From the point of view of the ServiceDiscoveryManager
`and the LookupCache, providing an appropriate implementation for both the
`equals method and the hashCode methodis a key characteristic of good behavior
`in a Jini service.
`Note that there is no need to override either the equals method or the hash-
`Code methodif the service is implemented as a purely remote object in which the
`service proxy is an RMIstub. In this case, appropriate implementations for both
`methodsare already providedin the stub.
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`135
`
`135
`
`

`

`126
`
`THE SEMANTICS
`
`SD.4.3 Exporting RemoteEventListener Objects
`
`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 a_requestservices. The methods that result in such are
`createLookupCache and the blocking versions of the lookup method.
`Anyentity that invokes one of these methods must export, to each lookupser-
`vice with which
`a
`registration
`occurs,
`the
`stub
`classes
`of
`the
`RemoteEventListener object through which instances of RemoteEvent will be
`received. Furthermore, each of these methods must throw RemoteException. The
`reasons that a RemoteException can occurfall into one of the following catego-
`ries:
`
`@ Each of these methods attempts to export a remote object, a process that can
`throw RemoteException.
`
`@ Each of these methods attempts to register with the event mechanism ofat
`least one lookup service, a process that can throw RemoteException.
`
`Howeachof the affected methods handle the RemoteExceptionis dependent
`on the reason for the exception. If a RemoteException (or any other non-fatal
`exception or error) is thrown during an attempt to register for events from a
`lookupservice, that lookup service will be discarded and madeeligible for redis-
`covery. On the other hand, if a RemoteException occurs during an attempt to
`export the listener, the method from which that attempt is made will re-throw the
`same exception.
`The potential for RemoteException during the export process imposes the
`following requirement: the same instance of the listener must be exported to each
`lookup service from which events will be requested. Furthermore, the creation and
`export of the listener must occur prior to the event registration process. This
`requirement guarantees that should a RemoteException occurafter the registra-
`tion process has begun,the exception will not be propagated and event processing
`will continue.
`To understand the significance of this requirement, consider the scenario in
`which a different instance of the listener is exported to each lookupservice. If a
`new lookupservice is discovered after the event process has begun for the other
`lookup services in the managedset, a new instanceofthe listener must be created
`and exported. Should a RemoteException occur during the export process, the
`exception will be propagated and all event processing will stop—aresult that
`many entities may view as undesirable.
`
`136
`
`136
`
`

`

`JINI SERVICE DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`127
`
`To facilitate exporting the listener, the entity—whetherit is a Jini client or a
`Jini service—is responsible for providing and advertising a mechanism through
`which each lookupservice will acquire the listener’s stub classes.
`For example, one implementation of the ServiceDiscoveryManager might
`provide a special JAR file containing only the listener stub classes to optimize
`
`
`
`download By_including JAR_file the_entity’stime. this in
`
`
`
`java.rmi.server.codebase property (in the appropriate format, specifying
`transport protocol and location), the entity advertises the mechanism that lookup
`services can employ to acquire the stub classes. By executing a process to serve up
`the JAR file (for example, an HTTP server), the mechanism through which each
`lookupservice acquires those stub classesis provided.
`It is important to note that should such a mechanism not be madeavailable to
`each lookupservice with which eventregistration will be requested, a “silent fail-
`ure” can occur repeatedly. If the mechanism is not available, each lookup service
`cannot acquire the exported listener. Because each lookup service cannot acquire
`the exported listener, any attempts to register for events will fail. Whenever an
`attemptto register for events fails, the associated lookup service will be discarded
`and madeeligible for rediscovery. Upon rediscovery of the discarded lookupser-
`vice, the cycle repeats when a new attemptto register for events is made.
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`137
`
`137
`
`

`

`128
`
`THE SEMANTICS
`
`138
`
`138
`
`

`

`JINI SERVICE DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`129
`
`
`
`
`SD.5 Supporting Interfaces and Classes
`
`Tz ServiceDiscoveryManager utility class depends on the following inter-
`faces defined in The Jini Technology Core Platform Specification, “Lookup Ser-
`vice”: ServiceTemplate, ServiceItem, and ServiceMatches. This class also
`depends on a numberofinterfaces, each defined in this section; those interfaces
`are DiscoveryManagement, ServiceItemFilter, ServiceDiscoveryListener,
`and LookupCache.
`The ServiceDiscoveryManager class references the following concrete
`classes: LookupDiscoveryManager and LeaseRenewalManager, each described
`in a separate chapter of this document, and ServiceDiscoveryEvent, which is
`defined in this chapter.
`
`SD.5.1 The DiscoveryManagement Interface
`
`Although it is not necessary for the ServiceDiscoveryManager itself to execute
`the discovery process, it does need to be notified when one of the lookup services
`it wishes to query is discovered or discarded. Thus, at a minimum,
`the
`ServiceDiscoveryManager requires access to the instances of DiscoveryEvent
`sent to the listeners registered with the event mechanism ofthe discovery process.
`The instance of DiscoveryManagement passed to the constructor of the
`ServiceDiscoveryManager provides a mechanism for acquiring access to those
`events. For a complete description of the semantics of the methods ofthis inter-
`face, refer to the Jini Discovery Utilities Specification.
`One noteworthy item about the semantics of the ServiceDi scoveryManager
`is the effect that invocations of the discard method of DiscoveryManagement
`have on any cache objects created by the ServiceDiscoveryManager. The
`DiscoveryManagement interface specifies that the discard method will remove a
`particular lookup service from the managedset of lookupservices already discov-
`ered, allowing that lookup service to be rediscovered. Invoking this method will
`result in the flushing of the lookup service from the appropriate cache. This effect
`ultimately causes a discard notification to be sent to all DiscoveryListener
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`139
`
`139
`
`

`

`130
`
`SUPPORTING INTERFACES AND CLASSES
`
`objects registered with the event mechanism of the discovery process (including
`all listeners registered by the ServiceDiscoveryManager).
`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
`ServiceDiscoveryManager.
`Furthermore, every service reference stored in the cachethat is registered with
`the discarded lookup service but is not registered with any of the remaining
`lookup services in the managedset will be “discarded” as well. Thatis, all previ-
`ously discovered service references that are registered with only unavailable
`lookup services will be removed from the cache and made eligible for service
`rediscovery.
`
`SD.5.2. The ServiceItemFilter Interface
`
`The ServiceItemFi1ter interface defines the methods used by an object such as
`the ServiceDiscoveryManager or the LookupCache to apply additional match-
`ing criteria when searching for services in which an entity has registered interest.
`It is the responsibility of the entity requesting the application of additionalcriteria
`to construct an implementation ofthis interface that defines the additionalcriteria,
`and to pass the resulting object (referred to as a filter) into the object that will
`applyit.
`Thefiltering mechanism provided by implementationsofthis interface is par-
`ticularly useful to entities that wish to extend the capabilities of the standard tem-
`plate matching scheme. For example, because template matching does not allow
`one to search for services based on a range of attribute values, this additional
`matching mechanism can be exploited by the entity to ask the managing object to
`find all registered printer services that have a resolution attribute between say, 300
`dpi and 1200 dpi.
`
`package net.jini. lookup;
`
`public interface ServiceItemFilter {
`public boolean check(ServiceItem item);
`
`}
`
`140
`
`140
`
`

`

`JINI SERVICE DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`131
`
`SD.5.2.1 The Semantics
`
`The check method defines the implementation of the additional matchingcriteria
`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 crite-
`ria and false otherwise.
`Neither a nul] reference nor a ServiceItem object containing nu11 fields
`will be passed into this method by the ServiceDi scoveryManager.
`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.
`Should an exception occur during an invocation of this method, the semantics
`of how that exception is handled are undefined.
`This method must not modify the contents of the input ServiceItem object
`becauseit could result in unpredictable and undesirable effects on future process-
`ing by the ServiceDiscoveryManager.Thatis whythe effects of any such modi-
`fication to the contents of that input parameter are undefined.
`
`SD.5.3. The ServiceDiscoveryEvent Class
`
`The ServiceDiscoveryEvent class encapsulates the service discovery informa-
`tion made available by the event mechanism of the LookupCache. All listeners
`that an entity has registered with the cache’s event mechanism will receive an
`event of type ServiceDiscoveryEvent upon the discovery, removal, or modifica-
`tion of one of the cache’s services, as described previously in “Events and the
`Cache.”
`This class is a subclass of the class EventObject. In addition to the methods
`of the EventObject class, this class provides two additional accessor methods
`that can be used to retrieve the additional state associated with the event:
`getPreEventServicelItem and getPostEventServicelItem.
`The getSource method of the EventObject class returns the instance of
`LookupCache from whichthe given eventoriginated.
`
`package net.jini. lookup;
`
`public class ServiceDiscoveryEvent extends EventObject
`public ServiceDiscoveryEvent(Object source,
`ServiceItem preEventitem,
`ServiceItem postEventItem)
`
`{
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`144
`
`141
`
`

`

`132
`
`SUPPORTING INTERFACES AND CLASSES
`
`{...}
`public ServiceItem getPreEventServicelItem()
`public ServiceItem getPostEventServicelItem() {...}
`
`{...}
`
`SD.5.3.1 The Semantics
`
`The constructor of ServiceDiscoveryEvent takes three arguments:
`
`An instance of Object corresponding to the instance of LookupCache from
`whichthe given event originated
`@ A ServiceItem reference representing the state of the service (associated
`with the given event) prior to the occurrence of the event
`@ A ServiceItem reference representing the state of the service after the
`occurrence of the event
`
`for
`
`the constructor,
`
`a
`
`source parameter
`the
`is passed as
`If null
`Nul1PointerException will be thrown.
`Depending on the nature of the discovery event, a null reference may be
`passed as one orthe other of the remaining parameters, but never both. If nu11 is
`passed as both the preEventItem and the postEventItem parameters, a
`Nul1PointerException will be thrown.
`Note that the constructor will not modify the contents of either ServiceItem
`argument. Doing so can result in unpredictable and undesirable effects on future
`processing by the ServiceDiscoveryManager. That is why the effects of any
`such modification to the contents of either input parameter are undefined.
`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
`occurrenceofthe event.
`If the event is a discovery event (as opposed to a removal or modification
`event), then this method will return nu11 because the discovered service had no
`state in the cachepriorto its discovery.
`The getPostEventServiceItem methodreturns 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
`occurrenceofthe event.
`If the event is a removal event, then this method will return nu11 because the
`discovered service hasnostate in the cacheafter it is removed from the cache.
`
`142
`
`142
`
`

`

`JINI SERVICE DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`133
`
`Because making a copy can be a very expensive process, neither accessor
`method returns a copy ofthe service reference associated with the event. Rather,
`each methodreturns the appropriate service reference from the cache itself. Due
`to this cost, listeners (see Section SD.5.4, “The ServiceDiscoveryListener Inter-
`face” below) that receive a ServiceDiscoveryEvent must not modify the con-
`tents of the object returned by these methods; doing so could causethe state of the
`cache to become corrupted or inconsistent because the objects returned by these
`methods are also membersof the cache. This potential for corruption or inconsis-
`tency is why the effects of modifying the object returned by either accessor
`method are undefined.
`
`SD.5.4 The ServiceDiscoveryListener Interface
`
`The ServiceDiscoveryListener interface defines the methods used by objects
`such as a LookupCache to notify an entity that events of interest related to the ele-
`ments of the cache have occurred.It is the responsibility of the entity wishing to
`be notified of the occurrence of such events to construct an object that implements
`the ServiceDiscoveryListener interface and then register that object with the
`cache’s event mechanism. Any implementation of this interface must define the
`actions to take uponreceipt of an eventnotification. The action taken is dependent
`on both the application and the particular event that has occurred.
`
`package net.jini. lookup;
`
`public interface ServiceDiscoveryListener {
`public void serviceAdded(ServiceDiscoveryEvent event) ;
`public void serviceRemoved(ServiceDiscoveryEvent event);
`public void serviceChanged(ServiceDiscoveryEvent event) ;
`
`SD.5.4.1 The Semantics
`
`As described previously in the section titled “Events and the Cache,’ 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 methodonall
`instances of ServiceDiscoveryListener that are registered with the cache;
`doing so notifies the entity that a service of interest has been discovered. The
`method
`serviceAdded
`takes
`one
`argument:
`an_
`instance’
`of
`ServiceDiscoveryEvent containing references to the service item correspond-
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`143
`
`143
`
`

`

`134
`
`SUPPORTING INTERFACES AND CLASSES
`
`ing to the event, including representations of the service’s state both before and
`after the event.
`Whenthe cache receives, from a managed lookupservice, an event signaling
`the removalof a service of interest from the /ast such lookup service with whichit
`was registered, the cache invokes the serviceRemoved method onall instances of
`ServiceDiscoveryListener that are registered with the cache; doing so notifies
`the entity that a service of interest has been discarded. The serviceRemoved
`method takes one argument: a ServiceDiscoveryEvent object containing refer-
`encesto the service item corresponding to the event, including representations of
`the service’s state both before and after the event.
`Whenthe cache receives, from a managed lookupservice, 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 onall instances of ServiceDiscoveryListener that
`are registered with the cache; doing so notifies the entity that the state of a service
`of interest has changed. The serviceChanged method takes one argument: a
`ServiceDiscoveryEvent object containing references to the service item corre-
`sponding to the event, including representations of the service’s state both before
`and after the event.
`Should an exception occur during an invocation of any of the methods defined
`by this interface, the semantics of how that exception is handled are undefined.
`Each method defined by this interface must not modify the contents of the
`ServiceDiscoveryEvent parameter; doing so can result in unpredictable and
`undesirable effects on future processing by the ServiceDiscoveryManager.It is
`for this reason that if one of these methods modifies the contents of the parameter,
`the effects are undefined.
`This interface makes the following concurrency guarantee: for any givenlis-
`tener object that implements this interface, no two methods(either the same two
`methodsor different methods) defined by the interface can be invoked at the same
`time by the same cache. For example, the serviceRemoved method must not be
`invoked while the invocation of another listener’s serviceAdded method is in
`
`progress.
`Finally, it should be noted that the intent of the methods ofthis interfaceis to
`allow the recipient of the ServiceDiscoveryEvent to be informed that a service
`has been addedto, removed from, or modified in the cache. Calls to these methods
`are synchronousto allow the entity that makesthe call (for example, a thread that
`interacts with the various lookupservices of interest) to determine whether or not
`the call succeeded. However,it is not part of the semantics of the call that the noti-
`fication return can be delayed while the recipient of the call reacts to the occur-
`rence of the event. It is therefore highly recommended that implementations of
`this interface avoid time consuming operations and return from the method as
`
`144
`
`144
`
`

`

`JINI SERVICE DISCOVERY UTILITIES SPECIFICATION, version 1.1
`
`135
`
`quickly as possible. For example, one strategy might be to simply note the occur-
`rence of the ServiceDiscoveryEvent and perform any time-consuming event
`handling asynchronously.
`
`SD.5.5 The LookupCache Interface
`
`The LookupCache interface defines the methods provided by the object created
`and returned by the ServiceDiscoveryManager when an entity invokes the
`createLookup