ais
`
`213
`
`
`
`tion.
`
`
`[TRANSACTION SPECIFICATION
`erializability might be violated. Whena subtransaction commits,its
`
`then §
`are inherited by the parent transaction.
`
`Inaddition to locks, transactional operations can be defined in terms of object
`
`2on and deletion visibility. If an object is defined to be created undera trans-
`E "then the existence of the object is visible only within that transaction and
`
`inferiors put will disappear if the transaction aborts. If an object is defined to
`
`jeted under a transaction, then the object is not visible to any transaction
`
`leting transaction) but will reappear if the transaction aborts.
`
`ing the de
`we
`ee
`, q nested transaction commits, visibility state is inherited by the parent
`
`nce a transaction reaches the VOTINGstage, if all execution under the trans-
`
`n (andits subtransactions) hasfinished, then the only reasons the transaction
`
`bort are:
`
`The manager crashes (or has crashed)
`
`
`; One or more participants crash (or have crashed)
`
`
`»There is an explicit abort
`
`
`Transaction deadlocks are not guaranteed to be prevented or even detected,
`
`managers and participants are permitted to break known deadlocks by abort-
`
`Anactive transaction is an orphanifit or oneof its ancestors is guaranteed to
`This can occur because an ancestor has explicitly aborted or because some
`
`icipant or manager of the transaction or an ancestor has crashed. Orphansare
`
`guaranteed to be detected by the system, so programmersusing transactions
`
`{be aware that orphanscansee internally inconsistent state and take appropri-
`
`action.
`
`ausal ordering information abouttransactionsis not guaranteed to be propa-
`First, given two sibling transactions (at any level), it is not possible to tell
`
`ther they were created concurrently or sequentially (or in what order). Sec-
`
`if two transactions are causally ordered andthe earlier transaction has com-
`
`_ the outcome of the earlier transaction is not guaranteed to be known at
`
`participant used by the later transaction, unless the client is successful in
`
`the variant of commit or abort that takes a timeout parameter. Programmers
`
`non-blocking forms of operations musttake this into account.
`
`s long as a transaction persists in attempting to acquire a lockthat conflicts
`
`another transaction, the participant will persist in attempting to resolve the
`
`me of the transaction that holds the conflicting lock. Attempts to acquire a
`
`include making a blocking call, continuing to make non-blocking calls, and
`tering for event notification undera transaction.
`
`
`
`223
`
`223
`
`

`

`
`
`TX.3.6 Serialized Forms
`
`
`Class
`
`serialVersionUID
`
`Serialized Fields
`
`Transaction. Created
`
`—5199291723008952986L
`
`all public fields
`
`NestableTransaction. Created
`
`~2979247545926318953L
`
`all public fields
`
`TransactionManager.Created
`
`—4233846033773471113L
`
`all public fields
`
`ServerTransaction
`
`4552277137549765374L
`
`all public fields
`
`NestableServerTransaction
`
`—3438419132543972925L
`
`TransactionException
`
`—5009935764793203986L
`
`CannotAbortException
`
`35971016467375 10009L
`
`CannotCommi tException
`
`—4497341152359563957L
`
`CannotjJoinException
`
`5568393043937204939L
`
`CannotNestException
`
`340960450049 1735434L
`
`TimeoutExpi redException
`
`3918773760682958000L
`
`UnknownTransactionException
`
`443798629936327009L
`
`all public fields
`none
`
`none
`
`none
`
`none
`
`none
`
`all public fields
`none
`
`CrashCountException
`4299226125245015671L
`
`none
`
`
`
`224
`
`224
`
`

`

`MWestieait)
`
`(TX)
`
`225
`
`225
`
`

`

`SSSSSTY
`
`
`pea ct ee
`
`
`The Jini Lookup Service
`Specification
`
`
`
`LU.1 Introduction
`
`Tx Jini Lookup service is a fundamental part of the federation infrastructure
`for a djinn, the group of devices, resources, and users that are joined by the Jini
`software infrastructure. The lookup service provides a central registry of services
`available within the djinn. This lookup service is a primary meansfor programs to
`find services within the djinn, and is the foundation for providing user interfaces
`through which users and administrators can discover and interact with services in
`the djinn.
`Although the primary purposeofthis specification is to define the interface to
`the djinn’s central service registry, the interfaces defined here can readily be used
`in other service registries.
`
`LU.1.1 The Lookup Service Model
`
`The lookupservice maintainsa flat collection of service items. Each service item
`represents an instance of a service available within the djinn. The item contains
`the RMIstub (if the service is implemented as a remote object) or other object (if
`the service makes use of a local proxy) that programs use to access the service,
`and anextensible collection of attributes that describe the service or provide sec-
`ondary interfaces to the service.
`When a new service is created (for example, when a new device is added to
`the djinn), the service registers itself with the djinn’s lookupservice, providing an
`initial collection of attributes. For example, a printer might includeattributes indi-
`
`217
`
`
`
`226
`
`226
`
`

`

`
`
`
`
`218
`
`ATTRIBUTES
`
`cating speed (in pages per minute), resolution (in dots per inch), and whether
`duplex printing is supported. Amongthe attributes might be an indicator that the
`service is new and needsto be configured.
`An administrator uses the event mechanismof the lookupservice to receive
`notifications as new services are registered. To configure the service, the adminis-
`trator might look for an attribute that provides an applet for this purpose. The
`administrator might also use an applet to add new attributes, such as the physical
`location of the service and a common name forit; the service would receive these
`attribute change requests from the applet and respond by making the changesat
`the lookup service.
`Programs(including other services) that need a particular type of service can
`use the lookupserviceto find an instance. A match can be made basedonthe spe-
`cific data types for the Java programming language implemented bythe service as
`well as the specific attributes attachedto the service. For example, a program that
`needs to make use of transactions might look for a service that supports the type
`net.jini.core.transaction.server.TransactionManager and mightfurther
`qualify the match by desired location.
`Although the collection of service itemsis flat, a wide variety of hierarchical
`views can be imposed on the collection by aggregating items according to service
`typesandattributes. The lookup service provides a set of methodsto enableincre-
`mental exploration ofthe collection, and a variety of user interfaces can be built
`by using these methods, allowing users and administrators to browse. Once an
`appropriate service is found, the user might interact with the service by loading a
`user interface applet, attached as anotherattribute on the item.
`If a service encounters some problem that needs administrative attention, such
`as a printer running out of toner, the service can add an attribute that indicates
`what the problem is. Administrators again use the event mechanism to receive
`notification of such problems.
`
`LU.1.2 Attributes
`
`The attributes of a service item are represented asaset of attribute sets. An indi-
`vidual attribute set is represented as an instance of someclass for the Java plat-
`form, eachattribute being a public field of that class. The class provides strong
`typing of both the set and the individual attributes. A service item can contain
`multiple instances of the same class with different attribute values, as well as mul-
`tiple instances of different classes. For example, an item might have multiple
`instances of a Name class, each giving the common nameofthe service in a differ-
`ent language, plus an instance of a Location class, an Owner class, and various
`service-specific classes. The schemaused forattributes is not constrained bythis
`
`
`
`227
`
`227
`
`

`

`
`
`THE JINI LOOKUP SERVICE SPECIFICATION
`
`219
`
`specification, but a standard foundation schema for Jini systems is defined in the
`Jini Lookup Attribute Schema Specification.
`Concretely, a set of attributes is implemented with a class that correctly imple-
`ments the interface net.jini.core.entry.Entry, as described in the Jini Entry
`Specification. Operations on the lookup service are defined in terms of template
`matching, using the same semantics as in the Jini Entry Specification, butthe def-
`inition is augmented to deal with sets of entries and sets of templates. A set of
`entries matches a set of templates if there is at least one matching entry for every
`template (with every entry usable as the match for more than one template).
`
`LU.1.3 Dependencies
`
`This specification relies on the following other specifications:
`
`Java Remote Method Invocation Specification
`@ Java Object Serialization Specification
`@ Jini Entry Specification
`@ Jini Distributed Event Specification
`@ Jini Distributed Leasing Specification
`
`@ Jini Discovery and Join Specification
`
`;
`
`|
`
`
`
`
`Deereerea
`
`
`228
`
`228
`
`

`

`EE
`
`THE JINI LOOKUP SERVICE SPECIFICATION
`
`221
`
`
`
`
`
`LU.2 The ServiceRegistrar
`
`Tire typesdefined in this specification are in the net. jini .core. lookup pack-
`age. The following types are imported from other packages andare referenced in
`unqualified form in the restofthis specification:
`
`java.rmi.MarshalledObject
`java.rmi.RemoteException
`java.rmi.UnmarshalException
`java.io.Serializable
`java.io.DataInput
`java.io.DataQutput
`java.io. IOException
`net. jini.core.discovery.LookupLocator
`net.jini.core.entry.Entry
`net.jini.core, lease.Lease
`net. jini.core.event.RemoteEvent
`net.jini.core.event.EventRegistration
`net.jini.core.event.RemoteEventListener
`
`LU.2.1 ServiceID
`
`Every service is assigned a universally unique identifier (UUID), represented as an
`instance of the ServicelID class.
`
`public final class ServiceID implements Serializable {
`public ServiceID(long mostSig,
`long leastSig) {..}
`public ServiceID(DataInput
`in) throws IOException {..}
`public void writeBytes(DataOutput out) throws IOException
`{...}
`public long getMostSignificantBits() {..}
`public long getLeastSignificantBits() {..}
`
`
`
`229
`
`229
`
`

`

`| 2
`
`22
`
`ServiceItem
`A service ID is a 128-bit value. Service IDs are equal (using the equals
`method)if they represent the same 128-bit value. For simplicity and reliability,
`service IDs are intended to be generated only by lookup services, not by clients.
`As such, the ServiceID constructor merely takes 128bits of data, to be computed
`in an implementation-dependent manner by the lookupservice. The writeBytes
`method writes out 16 bytes in standard network byte order. The second construc-
`tor readsin 16 bytes in standard network byte order.
`The most significant long can be decomposed into the following unsigned
`
`fields:
`
`OxFFFFFFFFQ@Q@ee000
`time_low
`Ox@0@0Q000FFFFOQRG
`time_mid
`0x000020000000FR00
`version
`Qx@0000G0000000FFF
`time_hi
`Theleast significant long can be decomposedinto the following unsignedfields:
`0xCGGG000000000000
`variant
`Ox3FFFOGQe@RGeoR000
`clock_seq
`@xQQQ0FFFFFFFFFFFF
`node
`The variant field must be 0x2. The version field must be either Ox1 or 0x4. If
`the version field is 0x4, then the most significant bit of the node field must be set
`to 1, and the remaining fields are set to values produced by a cryptographically
`strong pseudo-random numbergenerator. If the version field is Ox1, then the
`nodefield is set to an IEEE 802 address, the clock_seqfieldis set to a 14-bit ran-
`dom number, and the time_1 ow, time_mid, and time_hifieldsaresetto the least,
`middle, and mostsignificantbits (respectively) of a 60-bit timestamp measured in
`100-nanosecondunits since midni ght, October 15, 1582 UTC.
`The toString method returns a 36-character string ofsix fields separated by
`hyphens, eachfield represented in lowercase hexadecimal with the same number
`of digits as in the field. The order of fields is: time_low, time_mi d, version and
`time_hi treated as a single field, variant and cl ock_seqtreated asa singlefield,
`and node.
`
`LU.2.2. Servicertem
`
`Items are stored in the lookupservice using instances of the ServiceItem class,
`public class ServiceItem implements Serializable {
`public ServiceItem(ServiceID servicelID,
`Object service,
`
`
`
`230
`
`230
`
`

`

`nL
`
`THE JINI LOOKUP SERVICE SPECIFICATION
`
`223
`
`Entry[] attributeSets) {..}
`public ServiceID serviceID;
`public Object service;
`public Entry[{] attributeSets;
`
`}
`
`The constructor simply assigns each parameterto the correspondingfield.
`Each Entry represents an attribute set. The class must have a public no-arg
`constructor, and all non-static, non-final, non-transient public fields must be
`declared with reference types, holding serializable objects. Each suchfieldis seri-
`alized separately as a MarshalledObject, and field equality is defined by
`MarshalledObject.equals. The only relationship constraint on attribute sets
`within an item is that exact duplicates are eliminated; other than that, multiple
`attribute sets of the same type are permitted, multiple attribute set types can have a
`common superclass, and so on.
`The net.jini.core.entry.UnusableEntryException is not used in the
`lookupservice; alternate semantics for individual operations are definedlater in
`this section.
`
`LU.2.3_ ServiceTemplate and Item Matching
`
`Items in the lookup service are matchedusinginstances of the Servi ceTemplate
`class.
`
`public class ServiceTemplate implements Serializable {
`public ServiceTemplate(ServiceID servicelD,
`Class[] serviceTypes,
`Entry[] attributeSetTemplates) {..}
`public ServiceID servicelID;
`public Class[] serviceTypes;
`public Entry[] attributeSetTemplates;
`
`}
`
`The constructor simply assigns each parameterto the corresponding field. A ser-
`vice item (item) matches a service template (tmp1) if:
`
`¢ item.serviceID equals tmp].serviceID(or if tmp1.serviceIDis nu11),
`and
`
`@ item.service is an instance of every type in tmp1.serviceTypes, and
`# item.attributeSets contains at least one matching entry for each entry
`template in tmp].attributeSetTemplates.
`
`
`
`231
`
`
`
`|
`
`|
`
`|
`‘Bi
`
`
`
`231
`
`

`

`LE
`
`224
`
`OTHER SUPPORTING TYPES
`An entry matches anentry templateif the class of the template is the sameas,
`or a superclass of, the class of the entry, and every non-nul1 field in the template
`equals the correspondingfield of the entry. Every entry can be used to match more
`than one template. For both service types and entry classes,
`type matching is
`based simply on fully qualified class names. Note that in a service template, for
`serviceTypes and attri buteSetTemplates, a nul) field is equivalent to an
`empty array; both represent a wildcard.
`
`LU.2.4. Other Supporting Types
`
`The ServiceMatches classis used for the return value when looking up mul-
`tiple items,
`public class ServiceMatches implements Serializable {
`public ServiceMatches (ServicelItem[]
`items,
`int totalMatches) {..}
`items;
`public ServiceItem[]
`public int totalMatches;
`
`}
`The constructor simply assigns each parameterto the correspondingfield.
`A ServiceEvent extends RemoteEvent with methodsto obtain the service ID
`of the matched item,the transition that triggered the event, and the new state of
`the matcheditem.
`
`public abstract class ServiceEvent extends RemoteEvent {
`public ServiceEvent (Object source,
`long eventID,
`long seqNum,
`MarshalledObject handback,
`ServiceID serviceID,
`int transition) {..}
`public ServiceID getServiceID() {..}
`public int getTransitiong® {..}
`public abstract ServcelItem getServiceItem() {..}
`
`}
`The getServiceID and getTransition methods return the value of the corre-
`sponding constructor parameter. The remaining constructor parameters are the
`sameas in the RemoteEvent constructor.
`The rest of the semantics of both these classesis explained in the nextsection.
`
`
`
`232
`
`232
`
`

`

`THE JINI LOOKUP SERVICE SPECIFICATION
`
`LU.2.5 ServiceRegistrar
`
`225
`
`The ServiceRegistrar defines the interface to the lookupservice. The inter-
`face is not a remote interface; each implementation of the lookup service exports
`proxy objects that implement the ServiceRegistrar interface localto the client,
`using an implementation-specific protocol to communicate with the actual remote
`server. All of the proxy methods obey normal RMI remote interface semantics
`except where explicitly noted. Two proxy objects are equal (using the equals
`method) if they are proxies for the same lookupservice.
`Methodsare providedto register service items, find items that match a tem-
`plate, receive event notifications when items are modified, and incrementally
`explore the collection of items along the three major axes: entry class, attribute
`value, and service type.
`
`public interface ServiceRegistrar {
`ServiceRegistration register(ServiceItem item,
`
`i
`
`i
`
`|
`
`|
`|
`
`|
`|
`
`|
`
`long TeaseDuration)
`
`throws RemoteException;
`
`lookup(ServiceTemplate tmp1)
`Object
`throws RemoteException;
`
`ServiceMatches
`lookup(ServiceTemplate tmp],
`throws RemoteException;
`
`int maxMatches)
`
`int TRANSITION_MATCH_NOMATCH=1 << 0;
`int TRANSITION_NOMATCH_MATCH = 1 << 1;
`int TRANSITION_MATCH_MATCH = 1 << 2;
`
`EventRegistration notify(ServiceTemplate tmp],
`int transitions,
`RemoteEventListener listener,
`MarshalledObject handback,
`long leaseDuration)
`throws RemoteException;
`
`Class[] getEntryClasses(ServiceTemplate tmp1)
`throws RemoteException;
`
`Object[] getFieldValues(ServiceTemplate tmp,
`
`sre
`
`
`
`233
`
`233
`
`

`

`a_
`
`226
`
`ServiceRegistrar
`
`int setIndex,
`String field)
`throws NoSuchFieldException, RemoteException;
`
`Class[] getServiceTypes(ServiceTemplate tmpl,
`String prefix)
`throws RemoteException;
`
`ServiceID getServiceID();
`LookupLocator getLocator() throws RemoteException;
`
`String[] getGroups() throws RemoteException;
`
`}
`
`Every method invocation on ServiceRegistrar and ServiceRegistration is
`atomic with respect to other invocations.
`The register methodis used to register a new service and to re-register an
`existing service. The method is defined so that it can be used in an idempotent
`fashion. Specifically, if a call to register results in a RemoteException (in
`which case the item might or might not have beenregistered), the caller can sim-
`ply repeat the call to register with the same parameters, until it succeeds.
`To register a new service, item.serviceID should be nu11. In thatcase, if
`item.service does not equal (using Marshal ledObject.equals) any existing
`item’s service object, then a new service ID will be assigned and includedin the
`returned ServiceRegistration (described in the next section). The service ID is
`unique over time and space with respecttoall other service IDs generated by all
`lookupservices. If item. service does equalan existing item’s service object, the
`existing item is first deleted from the lookup service (even if it has different
`attributes) and its lease is cancelled, but that item’s service ID is reused for the
`newly registered item.
`To re-register an existing service,or to register the service in any other lookup
`service, item.serviceID should be set to the same service ID that was returned
`by the initial registration. If an item is already registered under the sameservice
`ID, the existing item is first deleted (even if it has different attributes or a different
`service instance) andits lease is cancelled by the lookupservice. Note that service
`object equality is not checked in this case, to allow for reasonable evolution ofthe
`service (for example, the serialized form of the stub changesor the service imple-
`ments a new interface).
`Any duplicate attribute sets that are included in a service item are eliminated
`in the stored representation of the item. The lease duration request (specified in
`milliseconds) is not exact; the returnedlease is allowed to have a shorter (but not
`
`
`
`234
`
`234
`
`

`

`
`
`THE JINI LOOKUP SERVICE SPECIFICATION
`
`227
`
`longer) duration than what was requested. The registration is persistent across
`restarts (crashes) of the lookup service until the lease expires or is cancelled.
`The single-parameter form of lookup returns the service object (i.e., just
`ServiceItem.service) from an item matching the template or nu11 if there is
`no match. If multiple items match the template, it is arbitrary as to which service
`object is returned by the invocation. If the returned object cannot be deserialized,
`an UnmarshalException is thrown with the standard RMI semantics.
`The two-parameter form of lookup returns at most maxMatches items match-
`ing the template and the total numberof items that match the template. The return
`value is never nul1, and the returned items array is nul] only if maxMatches is
`zero, For each returned item, if the service object cannot be deserialized, the
`service field of the item is set to nul] and no exception is thrown. Similarly, if
`an attribute set cannot be deserialized, that elementof the attributeSets arrayis
`set to nu11 and no exception is thrown.
`The notify methodis used to register for event notification. The registration
`is leased; the lease duration request (specified in milliseconds) is not exact. The
`registration is persistent across restarts (crashes) of the lookup service until the
`lease expires or is cancelled. The event ID in the returned EventRegistrationis
`unique at least with respect to all other active eventregistrations at this lookupser-
`vice with different service templates or transitions.
`While the event registration is in effect, a Servi ceEvent is sent to the speci-
`fied listener whenever a register, lease cancellation or expiration, or attribute
`change operation results in an item changing state in a way that satisfies the tem-
`plate and transition combination. The transitions parameter is the bitwise OR
`of any non-empty set of transition values:
`
`@ TRANSITION_MATCH_NOMATCH: An event is sent when the changed item
`matches the template before the operation, but doesn’t match the template
`after the operation (this includes deletion of the item).
`
`# TRANSITION_NOMATCH_MATCH: An event is sent when the changed item
`doesn’t match the template before the operation (this includes not existing),
`but does match the template after the operation.
`
`is sent when the changed item
`@ TRANSITION_MATCH_MATCH: An event
`matches the template both before and after the operation.
`The getTransition method of ServiceEvent returns the singleton transi-
`tion value that triggered the match.
`The getServiceItem method of ServiceEvent returns the new state of the
`item (the state after the operation) or nu11 if the item was deleted by the opera-
`tion. Note that this method is declared abstract; a lookup service uses a subclass
`of ServiceEvent to transmit the new state of the item howeverit chooses.
`
`
`
`
`
`235
`
`235
`
`

`

`228
`
`ServiceRegistrar
`
`Sequence numbers for a given event ID are strictly increasing. If there is no
`gap between two sequence numbers, no events have been missed;if there is a gap,
`events might (but might not) have been missed. For example, a gap might occurif
`the lookupservice crashes, even if no events are lost due to the crash.
`As mentioned earlier, users are allowed to explore a collection of items down
`each of the major axes: entry class, attribute value, and service type.
`The getEntryClasses method looks at all service items that match the spec-
`ified template, finds every entry (amongthoseservice items) that either doesn’t
`match any entry templates or is a subclassof at least one matching entry template,
`andreturnsthe set of the (most specific) classes of those entries. Duplicate classes
`are eliminated, and the order of classes within the returned array is arbitrary. A
`nul1 reference (not an empty array) is returnedif there are no such entries or no
`matching items. If a returned class cannot be deserialized, that element of the
`returned array is set to nu11 and no exceptionis thrown.
`The getFieldValues method looksatall service items that match the speci-
`fied template,
`finds every entry (among those service items)
`that matches
`tmp].attributeSetTemplates[setIndex], and returns the set of values of the
`specified field of those entries. Duplicate values are eliminated, and the order of
`values within the returned array is arbitrary. a nu11 reference (not an empty array)
`is returned if there are no matchingitems. If a returned value cannotbe deserial-
`ized, that element of the returned arrayis set to nu11 and no exception is thrown.
`NoSuchFieldException is thrown if field does not namea field of the entry
`template.
`The getServiceTypes method looksat all service items that match the spec-
`ified template and, for every service item, finds the most specific type (class or
`interface) or types the service item is an instanceofthat are neither equal to, nora
`superclass of, any of the service types in the template and that have namesthat
`start with the specified prefix, and returnsthe set of all such types. Duplicate types
`are eliminated, and the order of types within the returned array is arbitrary. A
`null reference (not an empty array) is returned if there are no such types. If a
`returned type cannot be deserialized, that element of the returned array is set to
`nul] and no exception is thrown.
`Every lookup service assignsitself a service ID whenitis first created; this
`service ID is returned by the getServiceID method. (Note that this does not
`make a remote call.) A lookup service is always registered with itself underthis
`service ID,andif a lookup service is configuredto registeritself with other lookup
`services,it will register with all of them using this sameservice ID.
`The getLocator method returns a LookupLocator that can be used if neces-
`sary for unicast discovery of the lookup service. The definition of this class is
`given in the Jini Technology Discovery and Join Specification.
`
`
`
`236
`
`236
`
`

`

`———————————_———t—“‘“_“‘“‘ié—S
`
`a
`
`
`
`|
`
`
`
`r
`
`THE JINI LOOKUP SERVICE SPECIFICATION
`The getGroups method returns the set of groups that this lookup service is
`currently a member of. The semantics of these groups is defined in the Jini Tech-
`nology Discovery and Join Specification.
`
`229
`
`LU.2.6 ServiceRegistration
`
`A registered service item is manipulated using a ServiceRegi stration instance.
`public interface ServiceRegistration {
`ServiceID getServiceID();
`Lease getLease(Q);
`void addAttributes(Entry[] attrSets)
`throws UnknownLeaseException, RemoteException;
`void modifyAttributes(Entry[] attrSetTemplates,
`Entry[] attrSets)
`throws UnknownLeaseException, RemoteException;
`void setAttributes(Entry[] attrSets)
`throws UnknownLeaseException, RemoteException;
`
`}
`Like ServiceRegistrar, this is not a remote interface; each implementation of
`the lookup service exports proxy objects that implementthis interface local to the
`client. The proxy methods obey normal RMIremote interface semantics.
`The getServiceID method returns the service ID for this service. (Note that
`this does not make a remote call.)
`The getLease method returns the lease that controls the service registration,
`allowing the lease to be renewed or cancelled. (Note that getLease does not make
`a remote call.)
`The addAttributes method adds the specified attribute sets (those that aren’t
`duplicates of existing attribute sets) to the registered service item. Note that this
`operation has no effect on existing attribute sets of the service item and can be
`repeated in an idempotent fashion. UnknownLeaseExceptionis thrownif the reg-
`istration lease has expired or been cancelled.
`The modifyAttributes methodis used to modify existing attribute sets. The
`lengths of the attrSetTemplates and attrSets arrays must be equal, or
`I] legalArgumentExceptionis thrown. The service item’s attribute sets are mod-
`ified as follows. For each array index 7: if attrSets[7] is null, then every entry
`that matches attrSetTemplates[i] is deleted; otherwise, for every non-nul]
`field in attrSets[iJ, the value ofthat field is stored into the corresponding field
`of every entry that matches attrSetTemplates[i]. The class of attrSets[i]
`must be the same as, or a superclass of, the class of attrSetTemplates[i], or
`
`
`
`237
`
`237
`
`

`

`|
`
`230
`
`=
`
`SERIALIZED FORMS
`
`Tl JegalArgumentException is thrown. If the modifications result in duplicate
`entries within
`the
`service
`item,
`the
`duplicates
`are
`eliminated. An
`UnknownLeaseException is thrownif the registration lease has expired or been
`cancelled.
`Note that it is possible to use modi fyAttributes in waysthat are not idem-
`potent. The attribute schema should be designed in such a way thatall intended
`uses of this method can be performed in an idempotent fashion. Also note that
`modifyAttributes does not provide a means for setting a field to nul]; it is
`assumed that the attribute schemais designed in such a way that this is not neces-
`sary.
`The setAttributes method deletes all of the service item’s existing
`attributes and replaces them with the specified attribute sets. Any duplicate
`attribute
`sets
`are
`eliminated in the stored representation of
`the
`item.
`UnknownLeaseException is thrownif the registration lease has expired or been
`cancelled.
`
`LU.2.7 Serialized Forms
`
`
`Class
`serial VersionUID
`Serialized Fields
`ServiceID
`-7803375959559762239L long mostSig
`long leastSig
`717395451032330758L all publicfields
`ServiceItem
`7854483807886483216L all public fields
`ServiceTemplate
`~5518280843537399398L all public fields
`ServiceMatches
`1304997274096842701L ServiceID serviceID
`ServiceEvent
`
`. int transition
`
`
`
`238
`
`238
`
`

`

`
`
`
`
`
`239
`
`239
`
`

`

`THE JINI LOOKUP ATTRIBUTE SCHEMA SPECIFICATION defines a set ofattributes
`that a local administrator might choose to place on aservice. These are
`“serving suggestions”—nobodyis required to use these
`attribute definitions, but they give a starting pointfor
`people who need suchattributes to either use directly
`or usefor inspiration. This also describes the common
`stylefor entry design, including the canonical wayto
`present your entry as a JavaBean object.
`
`ons
`
`INT
`
`
`
`240
`
`240
`
`

`

` ar
`
`
`
`The Jini Lookup Attribute
`Schema Specification
`
`LS.1 Introduction
`
`Tix Jini Lookupservice providesfacilities for services to advertise their avail-
`ability and for would-be clients to obtain referencesto those services based on the
`attributes they provide. The mechanism thatit provides for registering and query-
`ing based onattributes is centered on the Java platform type system, and is based
`on the notion of an entry,
`Anentry is a class that contains a numberofpublic fields of object type. Ser-
`vices provide concrete values for each of these fields; each value acts as an
`attribute. Entries thus provide aggregation of attributes into sets: a service may
`provide several entries when registering itself in the lookup service, which means
`that attributes on each service are provided inaset ofsets.
`The purpose ofthis documentis to provide a framework in which services and
`their would-beclients can interoperate. This framework takes two parts:
`
`
`
`¢ Wedescribe a set of commonpredefined entries that span muchofthe basic
`functionality that is needed both by services registering themselves and by
`entities that are searching for services.
`@ Since we cannotanticipateall of the future needsof clients of the lookup ser-
`vice, we providea set of guidelines and design patterns for extending, using,
`and imitating this set in ways that are consistent and predictable. We also
`construct some examplesthatillustrate the use of these patterns.
`
`233
`
`
`
`241
`
`
`
`241
`
`

`

`234
`
`LS.1.1 Terminology
`
`TERMINOLOGY
`
`Throughout this document, we will use the following terms in consistent ways:
`
`@ Service—aservice that has registered,or will register, itself with the lookup
`service
`¢ Client—anentity that performs queries on the lookup service, in order to
`find particular services
`
`LS.1.2 Design Issues
`
`Several factors influence and constrain the design of the lookup service schema.
`
`Matching Cannot Always Be Automated
`
`No matter how muchinformationit hasat its disposal, a client of the lookup ser-
`vice will not alwaysbe ableto find a single unique match without assistance when
`it performsa lookup. In many instances we expect that more than oneservice will
`match a particular query. Accordingly, both the lookup service and the attribute
`schema are geared toward reducing the numberof matchesthat are returned on a
`given lookup to a minimum,and not necessarily to just one.
`
`Attributes Are Mostly Static
`
`We have designed the schemafor the lookup service with the assumption that
`most attributes will not need to be changed frequently. For example, we do not
`expectattributes to change moreoften than once every minute or so. This decision
`is based on our expectation thatclients that need to make a choice of service based
`on more frequently updatedattributes will be able to talk to whatever small set of
`services the lookup servicereturns for a query, and on our belief that the benefit of
`updating attributes frequently at the lookup service is outweighed by the cost in
`networktraffic and processing.
`
`Humans Need to Understand MostAttributes
`
`A corollary of the idea that ma