JINI SER VICE DISCOVERY UTILITIES SPECIFICA TION, version 1. I
`
`1 2 1
`
`9 The effects of modifying the contents of the tmp1 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
`
`return a single instance of
`1ookup from the first category—those that
`Se rvi ceItem—will return nu11, whereas the versions from the second cate-
`
`gory—those that return an array of Se rv1' ceItem instances—will return an empty
`array.
`
`The versions of 1 ookup from the first category can be used in a fashion simi-
`lar to the first form of the 1ookup method defined in the Se rv1' ceRegi st rar‘ inter-
`
`face described in The Jini Technology Core Platform Specification, “Lookup
`Service”. That is, an entity would typically invoke one of these versions of 1 ookup
`when it wishes to find a single service reference and the particular lookup service
`with which that service reference is registered is unimportant to the entity.
`Each version of 1ookup defined in the Servi ceDi scoveryManager differs
`
`with the corresponding version of 1 ookup in Se rvi ceRegi st rar in the following
`ways:
`
`9 The versions of 1ookup defined in the Se rv1' ceDi scove ryManager query
`multiple lookup services (the order in which the lookup services are queried
`is dependent on the implementation).
`
`9 The versions of 1ookup defined in the Se rv1' ceD1' scove ryManager can
`
`apply additional matching criteria, in the form of a filter object, when decid-
`ing whether a service reference found through standard template matching
`should be returned to the entity.
`
`The versions of 1ookup that return an array of Se rv1' ceItem objects can be
`used in a fashion similar
`to the second form of 1ookup defined in the
`
`Se rvi ceRegi st rar interface. That is, an entity would typically invoke these ver-
`sions of 1ookup when it wishes to find multiple service references matching the
`input criteria. Each of the versions of 1 ookup that return an array of Se rv1' ceItem
`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.
`As with the versions of 1 ookup that return a single instance of Se rvi ceItem,
`multiple queries and filtering are also notable differences between the second-cat-
`egory versions of this method and their counterpart in Se rvi ceRegi st ra r.
`For each version of 1 ookup, whenever a lookup service query returns a nu11
`service reference, the filter is bypassed, and the service reference is excluded from
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`131
`
`131
`
`

`

`122
`
`THE SEMANTICS
`
`the return object. On the other hand, if the query returns a non-nu11 service refer-
`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 1 ookup 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 references in the set, as determined
`by the eq ua1 5 method provided by each reference.
`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 on the instance
`of Di scoveryManagement being employed by the Se rvi ceD1' scove ryManage r.
`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 Tookup 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 occur if the
`entity employs a cache, the cache will eventually reflect the correct state.
`
`The Blocking Feature of 'l ookup
`
`As noted above, each category contains a version of Tookup that provides a fea-
`ture 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 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 RemoteExcepti on (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 number of service ref-
`erences to discover. The other blocking version requires that the entity specify the
`range through the m1' nMatches and maxMatches parameters, respectively.
`Prior to blocking, each of these versions of 1 ookup first queries each available
`lookup service in an attempt to retrieve a satisfactory number of matching ser-
`
`132
`
`132
`
`

`

`JINI SER VICE DISCOVERY UTILITIES SPECIFICA TION, 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 method will return the service references that have
`
`been discovered up to that point. If the waiting period passes and no services have
`been found, null or an empty array (depending on the version of 1 ooku p) 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 but less 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
`wa1' tDu r 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 m1" nMatches and maxMatches arguments must both be posi-
`tive, and maxMatches must be greater than or equal to m1' nMatches; otherwise, an
`IT 'I egalArgumentExcepti on will be thrown.
`
`The blocking versions of 1 ookup 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.
`
`In addition, the blocking versions of Tookup 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 Th read 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 getD'i scoveryManager Method
`
`implements the
`that
`The getDi scove ryManage r method returns an object
`Di scove ryManagement interface. The object returned by this method provides the
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`133
`
`133
`
`

`

`124
`
`THE SEMANTICS
`
`Se rv1' ceD1' scove ryManager 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 getLeaseRenewa'l Manager Method
`
`The getLeaseRenewal Manager method returns a LeaseRenewal Manager object.
`The object returned by this method manages the leases requested and held by the
`Se rv1' ceD1' scove ryManager. In general, these leases correspond to the registra-
`tions made by the Se rv1' ceD1' scove ryManager 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 lookup service discovery, the event mechanism for service
`discovery, and the cache management duties of the Se rv1' ceD1' scove ryManage r.
`That is, the terminate method will terminate each LookupCache instance created
`
`and managed by the Se rv1' ceD1' scove ryManager. Additionally, if the discovery
`manager employed by the Se rv1' ceD1' scove ryManager was created by the
`Serv1' ceD1' scoveryManager itself, then the term1' nate method will also termi-
`
`nate that discovery manager.
`Note that if the discovery manager was created externally and supplied to the
`Se rv1' ceD1' scove ryManager, then any reference to that discovery manager held
`by the entity will remain valid, even after the Se rv1' ceD1' scove ryManager has
`been terminated. Similarly, if the entity holds a reference to the lease renewal
`manager employed by the Se rv1' ceD1' scove ryManage r, that reference will also
`remain valid after termination, whether lease renewal manager was created exter-
`nally or by the Se rv1' ceD1' scove ryManager itself.
`The Se rv1' ceD1' scove ryManager makes certain concurrency guarantees with
`respect to an invocation of term1' nate 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
`Se rv1' ceD1' scove ryManager;
`that
`is, until
`completion of
`invocations of
`createLookupCache,
`lookup,
`getD1' scoveryManager,
`and
`
`getLeaseRenewa'l Manager.
`
`Upon completion of the termination process, the semantics of all current and
`future method
`invocations
`on
`the
`terminated
`instance
`of
`the
`
`Se rv1' ceD1' scove ryManager are undefined.
`
`134
`
`134
`
`

`

`JINI SER VICE DISCOVERY UTILITIES SPECIFICA TION, version 1. I
`
`1 25
`
`SD.4.2 Defining Service Equality
`
`The ability to accurately determine when two different service references are
`equal is very important to the Se rvi ceDi scove ryManager in general, and the
`LookupCache in particular. Any restriction placed on that 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 end service, 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
`lookup services, the service ID (retrieved from the service reference in the event)
`together with the equals method provided by the service itself, is used to distin-
`guish the service references from each other. In this way, when a new event arrives
`containing a reference associated with the same service 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 of itself. 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 compare service references, those references may still be stored
`in container classes (for example, Hashtabl e) where such comparisons are made
`“under the covers.” From the point of View of the Se rv1' ceDi scove ryManager
`and the LookupCache, providing an appropriate implementation for both the
`equals method and the hashCode method is 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 method if the service is implemented as a purely remote object in which the
`service proxy is an RMI stub. In this case, appropriate implementations for both
`methods are already provided in the stub.
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`135
`
`135
`
`

`

`126
`
`THE SEMANTICS
`
`SD.4.3 Exporting RemoteEventL'i stener' Objects
`
`A subset of the methods on the Se rvi ceDi scove ryManage r, when invoked, will
`
`result in a request for registration with the event mechanism of one or more
`lookup
`services. The methods
`that
`result
`in
`such
`a
`request
`are
`createLookupCache and the blocking versions of the Tookup method.
`Any entity that invokes one of these methods must export, to each lookup ser-
`vice with which
`a
`registration
`occurs,
`the
`stub
`classes
`of
`the
`RemoteEventLi stener object through which instances of RemoteEvent will be
`received. Furthermore, each of these methods must throw Remote Excepti on. The
`
`reasons that a RemoteExcepti on can occur fall into one of the following catego-
`ries:
`
`0 Each of these methods attempts to export a remote object, a process that can
`throw RemoteExcepti on.
`
`0 Each of these methods attempts to register with the event mechanism of at
`least one lookup service, a process that can throw RemoteExcepti on.
`
`How each of the affected methods handle the Remote Excepti on is dependent
`on the reason for the exception. If a RemoteExcepti on (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 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 RemoteExcepti on occur after 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 lookup service. If a
`new lookup service is discovered after the event process has begun for the other
`lookup services in the managed set, a new instance of the 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—a result that
`many entities may view as undesirable.
`
`136
`
`136
`
`

`

`JINI SER VICE DISCOVERY UTILITIES SPECIFICA TION, version 1. I
`
`1 27
`
`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.
`For example, one implementation of the Se rv1' ceD1' scove ryManager might
`provide a special JAR file containing only the listener stub classes to optimize
`download
`time.
`By
`including
`this
`JAR
`file
`in
`the
`entity’s
`java. rm1' .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
`lookup service acquires those stub classes is provided.
`It is important to note that should such a mechanism not be made available to
`each lookup service with which event registration 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
`attempt to register for events fails, the associated lookup service will be discarded
`and made eligible for rediscovery. Upon rediscovery of the discarded lookup ser-
`vice, the cycle repeats when a new attempt to register for events is made.
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`137
`
`137
`
`

`

`1 28
`
`THE SEMANTICS
`
`138
`
`138
`
`

`

`JINI SER VICE DISCOVERY UTILITIES SPECIFICA TION, version 1. I
`
`1 29
`
`
`
`
`SD.5 Supporting Interfaces and Classes
`
`THE Se rvi ceDi scove ryManager utility class depends on the following inter-
`faces defined in The Jini Technology Core Platform Specification, “Lookup Ser-
`vice”: Servi ceTemp'l ate, Servi ceItem, and Servi ceMatches. This class also
`
`depends on a number of interfaces, each defined in this section; those interfaces
`
`are Di scove ryManagement, Se rvi ceItemFi 'I te r, Se rvi ceDi scove ryLi stene r,
`
`and LookupCache.
`
`The Se rvi ceDi scove ryManager class references the following concrete
`classes: LookupDiscove ryManager and LeaseRenewa'l Manager, each described
`
`in a separate chapter of this document, and Se rvi ceDi scove ryEvent, which is
`defined in this chapter.
`
`SD.5.1 The Di scover-yManagement Interface
`
`Although it is not necessary for the Se rvi ceDi scove ryManager 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
`Se rvi ceDi scove ryManager requires access to the instances of Di scoveryEvent
`sent to the listeners registered with the event mechanism of the discovery process.
`The instance of Di scove ryManagement passed to the constructor of the
`Se rvi ceDi scove ryManager provides a mechanism for acquiring access to those
`events. For a complete description of the semantics of the methods of this inter-
`face, refer to the Jini Discovery Utilities Specification.
`One noteworthy item about the semantics of the Se rvi ceDi scove ryMan ager
`is the effect that invocations of the discard method of Di scoveryManagement
`
`have on any cache objects created by the Se rvi ceDi scove ryManage r. The
`Di scove ryManagement interface specifies that the di scard method will remove a
`particular lookup service from the managed set of lookup services 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 Di scove ryLi stener‘
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`139
`
`139
`
`

`

`130
`
`SUPPORTING INTERFA CES AND CLASSES
`
`objects registered with the event mechanism of the discovery process (including
`all listeners registered by the Se rvi ceDi scove ryManage r).
`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 LeaseRenewal Manager
`on behalf of
`the
`
`Se rvi ceDi scove ryManage r.
`
`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. That is, 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 Ser'vi ceItemFil ter' Interface
`
`The Se rvi ceItem Fi l ter interface defines the methods used by an object such as
`the Se rvi ceDi scove ryManager 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 additional criteria
`to construct an implementation of this interface that defines the additional criteria,
`and to pass the resulting object (referred to as a filter) into the object that will
`apply it.
`The filtering mechanism provided by implementations of this 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 checkCServiceItem item);
`
`}
`
`14o
`
`140
`
`

`

`JINI SER VICE DISCOVERY UTILITIES SPECIFICA TION, version 1. I
`
`1 3 1
`
`SD.5.2.1 The Semantics
`
`The check method defines the implementation of the additional matching criteria
`to apply to a Se rv1' ceItem object found through standard template matching. This
`method takes one argument: the Se rv1' ceItem 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 null reference nor a Se rv1' ceItem object containing null fields
`will be passed into this method by the Se rv1' ceD1' scove ryManager.
`If the parameter input to this method is a Se rv1' ceItem 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 Se rv1' ceItem object
`because it could result in unpredictable and undesirable effects on future process-
`ing by the Se rv1' ceD1' scove ryManager. That is why the effects of any such modi-
`fication to the contents of that input parameter are undefined.
`
`SD.5.3 The Ser'V'iceD'i scover'yEvent Class
`
`The Se rv1' ceD1' scove ryEvent 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 Se rv1' ceD1' scoveryEvent 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:
`
`getPreEventSe rv1' ceItem and getPostEventSe rv1' ceItem.
`
`The getSource method of the EventObject class returns the instance of
`
`LookupCache from which the given event originated.
`
`package net.jini.lookup;
`
`public class ServiceDiscoveryEvent extends EventObject {
`
`public ServiceDiscoveryEventCObject source,
`
`ServiceItem preEventItem,
`
`Servi ceItem postEventItem)
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`141
`
`141
`
`

`

`132
`
`SUPPORTING INTERFACES AND CLASSES
`
`public ServiceItem getPr‘eEventServiceItemO {...}
`
`public ServiceItem getPostEventSerV‘iceItemO {...}
`
`{...}
`
`SD.5.3.1 The Semantics
`
`The constructor of Se rvi ceD1' scove ryEvent takes three arguments:
`
`9 An instance of Object corresponding to the instance of LookupCache from
`which the given event originated
`
`o A Se rv1' ceItem reference representing the state of the service (associated
`with the given event) prior to the occurrence of the event
`
`0 A Se rvi ceItem reference representing the state of the service after the
`occurrence of the event
`
`source parameter
`the
`is passed as
`If null
`Null Po1' nterException will be thrown.
`
`for
`
`the constructor,
`
`a
`
`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 nu'l'l is
`passed as both the preEventItem and the postEventItem parameters, a
`Null Po1' nterException will be thrown.
`
`Note that the constructor will not modify the contents of either Se rvi ceItem
`argument. Doing so can result in unpredictable and undesirable effects on future
`processing by the Servi ceDiscoveryManager. That is why the effects of any
`such modification to the contents of either input parameter are undefined.
`The getPreEventSe rv1' ceItem method returns an instance of Servi ceItem
`
`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 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.
`The getPostEventSe rv1' ceItem method returns an instance of Se rvi ceItem
`
`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 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.
`
`142
`
`142
`
`

`

`JINI SER VICE DISCOVERY UTILITIES SPECIFICA TION, version 1. I
`
`1 33
`
`Because making a copy can be a very expensive process, neither accessor
`method returns a copy of the service reference associated with the event. Rather,
`each method returns 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 Se rvi ceDi scove ryEvent must not modify the con-
`tents of the object returned by these methods; doing so could cause the state of the
`cache to become corrupted or inconsistent because the objects returned by these
`methods are also members of 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 ServiceDi scover'yLi stener' Interface
`
`The Se rvi ceDi scove ryLi stener 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 Se rvi ceDi scove ryLi stener interface and then register that object with the
`cache’s event mechanism. Any implementation of this interface must define the
`actions to take upon receipt of an event notification. The action taken is dependent
`on both the application and the particular event that has occurred.
`
`package net.jini.lookup;
`
`pub11'c interface Se rvi ceDi scove ryLi stener‘ {
`
`public void servi ceAddedCServi ceDi scove ryEvent event) ;
`
`pub] 1' c void servi ceRemoved (Servi ceDi scove r'yEvent event);
`
`public void servi ceChanged (Servi ceDi scove ryEvent 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 servi ceAdded method on all
`instances of Servi ceDi scoveryLi stener that are registered with the cache;
`doing so notifies the entity that a service of interest has been discovered. The
`method
`servi ceAdded
`takes
`one
`argument:
`an
`instance
`of
`Se rvi ceDi scove ryEvent containing references to the service item correspond-
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`143
`
`143
`
`

`

`134
`
`SUPPORTING INTERFA CES AND CLASSES
`
`ing to the event, including representations of the service’s state both before and
`after the event.
`
`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 servi ceRemoved method on all instances of
`Se rv1' ceD1' scove ryLi stener that are registered with the cache; doing so notifies
`the entity that a service of interest has been discarded. The servi ceRemoved
`method takes one argument: a Se rv1' ceD1' scove ryEvent object containing refer-
`ences to the service item corresponding to the event, including representations of
`the service’s state both before and after the event.
`
`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
`serv1' ceChanged method on all instances of Servi ceD1' scoveryL1' stener that
`
`are registered with the cache; doing so notifies the entity that the state of a service
`of interest has changed. The servi ceChanged method takes one argument: a
`Se rv1' ceD1' scove ryEvent 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
`Se rv1' ceD1' scove ryEvent parameter; doing so can result in unpredictable and
`undesirable effects on future processing by the Se rv1' ceD1' scove ryManage r. 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 given lis-
`tener 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. For example, the servi ceRemoved method must not be
`invoked while the invocation of another listener’s servi ceAdded method is in
`
`progress.
`
`Finally, it should be noted that the intent of the methods of this interface is to
`allow the recipient of the Se rv1' ceD1' scove ryEvent to be informed that a service
`has been added to, removed from, or modified in the cache. Calls to these methods
`
`are synchronous to allow the entity that makes the call (for example, a thread that
`interacts with the various lookup services of interest) to determine whether or not
`the call succeeded. However, it is not part of the semantics of the call tha