223
`
`

`
`TX.3.6 Serialized Forms
`
`
`Class
`ser-ia1Vers'ionUIlJ
`Serialized Fields
`
`Transaction.Created
`
`—519929l723008952986L cdlpubhofiekb
`
`Nestab1eTransact1on.Created
`
`~297924754S926318953L cfllpubficfiekk
`
`TransactionManager.Created
`
`—4233846033773471113L aflpmbficjkkfi
`
`Se r've rTransact1' on
`
`4552277137549765374L all public fields
`
`Nestab1eServerTransaction
`
`—3438419132543972925L xfllpubflofiekk
`
`TransactianException
`
`—5009935764793203986L none
`
`CannotAbortException
`
`3597101646737510009L none
`
`CannotCommitException
`
`—4497341l52359563957L none
`
`CannotJo1nException
`Can notNestExcept1' on
`
`5568393043937204939L none_
`3409604500491735434L none
`
`T1‘ meoutExp1' re dExcept1' on
`
`3918773‘760682958000L all publicfields
`
`UnknownTransactionException
`
`443798629936327009[. none
`
`
`
`CrashCountException 4299226125245015671L. none
`
`224
`
`

`
`
`
`1......__?~.E:....=m..._/V
`
`225
`
`

`
`ILTTJ(It1)}oo'[
`
`The Jini Lookup Service
`Specification
`
`LU.1 Introduction
`
`Tim Jini Lookup service is a fundamental part of the federation infrastructure
`for a afliinn, the group of devices, resources, and users that are joined by the Jim
`software infrastructure. The lockup service provides a central registry of services
`available within the djinn. This lockup service is a primary means for 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 purpose of this specification is to define the interface to
`the djinn’s central service registry, the interfaces defined here can readily be used
`5- in other service registries.
`
`LU.1.1 The Lookup Service Model
`
`The lockup service maintains a flat collection of service items. Each service item
`represents an instance of a service available within the djinn. The item contains
`the RMI stub (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 an extensible 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 djimfs lockup service, providing an
`initial collection of attributes. For example, a printer might include attributes indi-
`
`226
`
`

`
`ATTRIBUTES
`
`eating speed (in pages per minute), resolution (in dots per inch), and whether
`duplex printing is supported. Among the attributes might be an indicator that the
`service is new and needs to be configured.
`An administrator uses the event mechanism of the lookup service 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 for it; the service would receive these
`attribute change requests from the applet and respond by making the changes at
`the lookup service.
`-
`Programs {including other services) that need a particular type of service can
`use the lookup service to find an instance. A match can be made based on the spe-
`cific data types for the Java programming language implemented by the service as
`well as the specific attributes attached to the service. For example, a program that
`needs to make use of transactions might look for a service that supports the type
`net . j"I n'i'. core . transaction . server .Tr'ansact1'onManager' and might further
`qualify the match by desired location.
`Although the collection of service items is flat, a wide variety of hierarchical
`views can be imposed on the collection by aggregating items according to service
`types and attributes. The lookup service provides a set of methods to enable incre-
`mental exploration of the 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 another attribute 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 as a set of attribute sets. An indi-
`vidual attribute set is represented as an instance of some class for the Java plat-
`form, each attribute 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 name of the service in a differ-
`ent language, plus an instance of a Location class, an Owner class, and various
`service—specific classes. The schema used for attributes is not constrained by this
`
`227
`
`

`
`THE JEN! LOOKUP SERVICE SPECIFICATION
`
`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 . j 1' ni .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, but the 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:
`
`0 Java Remote Method Invocation Specification
`
`9 Java Object Serialization Specification
`
`0 Jini Entry Specification
`
`9 Jini Distributed Event Specification
`
`4 Jini Distributed Leasing Specification
`
`9 Jini Discovery and Join Specification
`
`228
`
`

`
`THE JIM’ LOOKUP SERVICE SPECIFIC?! TION
`
`-.su11::.~‘§1I£|;Ia=a:«|.v::::;'<;;:-1‘
`
`LU.2 The Ser-V1‘ ceReg'i strar
`
`THE types defined in this specification are in the net . j 1' n1‘ . core .1ookup pack-
`age. The following types axe imported from other packages and are referenced in
`unqualified form in the rest of this specification:
`
`java.rmi.Marsha11edObject
`java.rmi.RemoteException
`java.rmi.Unmarsha1Exception
`java.io.Seria11zab1e
`java.io.DataInput
`java.io.DataOutput
`
`java.io.IOException
`net.jini.core.discovery.LookupLocator
`net.jini.core.entry.Entry
`net.jini.core.1ease.Lease
`net.j1ni.core.event.RemoteEvent
`net.j1ni.core.event.EventRegistration
`net.jini.core.event.RemoteEventListener
`
`LU.2.1 Serv'i ceID
`
`Every service is assigned a universally unique identifier OLJUID), represented as an
`instance of the Serv'i ceID class.
`
`pub‘! 1' c f1‘ rm} :1 ass Ser'v'i ceID 'imp'| ements Se r-1' a1 1‘zab1 e {
`pub'| 'i c Servi ceID('| ong rnostS1' g , 1ong ‘I eastS“i g) {...}
`pub'|1'c Se r'v'i ceID(DataInpu1: in) throws IOExcept1' on {...}
`pub1'ic V0'i d wr1' teBytes (Data0utput out) throws I0Except1' on
`{...}
`
`pub1-ic ‘long getMostS1' gn'i f*i ca.ntB'i ts O {...}
`pubiic long getLeastSignif1cantBits() {N}
`
`229
`
`

`
`Servfceitem
`
`A service ID is a 128-bit value. Service IDs are equal (using the equals
`method) if they represent tl1e 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 Sc rvi ceID constructor merely takes 128 bits of data, to be computed
`in an implementation-dependent manner by the lookup service. The wri teBytes
`method writes out 16 bytes in standard network byte order. The second construc-
`tor reads in 16 bytes in standard network byte order.
`The most significant long can be decomposed into the following unsigned
`fields:
`
`Ox FFFFFFFFO~8060@0@
`GXBBOOOGOOFFFFBOGO
`@x@00000000@@0F000
`OXOBGBPJGEOQQOBO FFF
`
`ti me_'| ow
`ti me_mi d
`version
`ti me-_hi
`
`The least significant long can be decomposed into the following unsigned fields:
`BXCEIBGBGOOGGBOGGO
`va ri ant
`8x3FFFO@0B00@009@0
`clock_seq
`OXBOBOFFFFFFFFFFFF
`node
`
`The variant field must he OX2. The version field must be either 0x1 or 0x4. If
`the version field is OX4, 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 number generator. If the ve rsi on field is Oxl, then the
`node field is set to an IEEE 802 address, the clock_seq field is set to a 14-bit ran-
`dom number, and the ti me__low, ti me_m1’ cl, and ti me'_hi fields are set to the least,
`middle, and most significant bits (respectively) of a 60-bit timestamp measured in
`100—nanosecond units since midnight, October 15, 1582 UTC.
`The tostri ng method returns a 36—character string of six fields separated by
`hyphens, each field represented in lowercase hexadecimal with the same number
`of digits as in the field. The order of fields is: ti me_l ow, ti me_mid, version and
`ti me_hi treated -as a single field, va r1’ ant and c‘Iock_seq treated as a single field,
`and node.
`
`LU.2.2 Servi ce-Item
`
`Items are stored in the lookup service using instances of the Servi celtem class.
`public class Ser'viceIterng implements Serializable {
`public Ser'viceItem(ServiceID serviceID,
`Object service,
`
`230
`
`

`
`THE JINI LOOKUP SERVICE SPECIFICATYON
`
`Entry[] attributesets) {...}
`public Se rvi ceID servi ceID:
`public Object service;
`public Entr'y[] attributesets;
`
`}
`
`The constructor simply assigns each parameter to the corresponding field.
`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 such field is seri-
`alized separateiy as a Mars halledobject, and field equality is defined by
`Marshalled0bject.equal 5. 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
`lookup service; alternate semantics for individual operations are defined later in
`this section.
`
`LU.2.3
`
`Se rvi ceTemp1 ate and Item Matching
`
`Items in the lookup service are matched using instances of the Servi ceTempl ate
`class.
`
`public class ServiceTemplate implements Serializable {
`public ServiceTemplate(ServiceID serviceID,
`Class[] serviceTypes,
`Entry[] attributeSetTemplates) {m}
`public ServiceID 5erviceID;
`public Class[] serviceTypes;
`public Entryl] attributeSetTemplates;
`
`}
`
`The constructor simply assigns each parameter to the corresponding field. A ser-
`vice item (item) matches a service template (tm pl) if:
`
`9 item . servi ceID equals tmpl . servi ceID (or if tmpl . servi ceID is null),
`and
`
`0 item. service is an instance of every type in tmpl .5er‘v1'ceTypes, and
`
`9 i tem.attri butesets contains at least one matching entry for each entry
`template in tmpl . att ri buteSetTemp'! ates.
`
`231
`
`

`
`OTHER SUPPORTING TYPES
`
`An entry matches an entry template if the class of the template is the same as,
`or a superclass of, the class of the entry, and every non-nul l field in the template
`equals the corresponding field 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
`servi ceTypes and attri buteSetTempl ates, a null field is equivalent to an
`empty array; both represent a wildcard.
`
`LU.2.4.- Other Supporting Types
`
`The Se rvi ceMatches class is used for the return value when looking up mul-
`tiple items.
`
`public class ServiceMatches implements Serializable {
`public Ser'viceMatchesCServ1'ceItem[]
`items,
`int total!/latches) {...}
`public ServiceItem[] items;
`public int totallvlatches;
`
`}
`
`The constructor simply assigns each parameter to the corresponding field.
`A Servi ceEvent extends Remote-Event with methods to obtain the service [D
`of the matched item, the transition that triggered the event, and the new state of
`the matched item.
`
`public abstract class ServiceEvent extends RemoteEvent {
`public ServiceEvent(Object source,
`long eventID,
`lmgsmmm,
`
`Marshalledobject handback,
`ServiceID serviceID,
`int transition) {m}
`public ServiceID getServiceID() {m}
`public int getTransition() {W}
`public abstract ServceItem getServiceItem() {m}
`
`}
`
`'The getservi ceID and getTr-ans1'tion methods return the value of the corre-
`sponding constructor parameter. The remaining constructor parameters are the
`same as in the Remote Event constructor.
`The rest of the semantics of both these classes is explained in the next section.
`
`232
`
`

`
`THE JINI LOOKUP SERVICE SPECIFICATION
`
`LU.2.5 Servi ceReg'i strar
`
`The Servi ceRegi strar‘ defines the interface to the lookup service. The inter-
`face is not a remote interface; each implementation of the Iookup service exports
`proxy objects that implement the Se rvi ceReg'i strar interface local to the client,
`using an implementaI:ion—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 lockup service.
`Methods are provided to 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 Se rvi ceReg'i strar {
`Servi ceReg'i st rati on regi ster(Se rvi ceItem item ,
`long 'leaseDu ration)
`
`throws RemoteException;
`
`Object lookup(Servi ceTempT ate tmpl)
`throws RemoteExcepti on;
`
`Se rvi ceMatche5
`
`'|ookup(ServiceTemp'|ate tmp'|,
`throws RemoteExce_ption;
`
`int maxMatches)
`
`int TRANSITION_MATCH_NOMATCH = 1 << 0:
`‘int TRANSITI0N__N0MATCH_|V|ATCH = 1 << 1;
`‘int TRAN5ITION_MATCH_MATCH = 1 << 2;
`
`Eventkegistraticn notifyCServiceTemp1ate tmpl,
`int transitions,
`
`RemoteEventListener listener,
`Marshalledobject handback,
`1ong leaseDuration)
`throws RemoteException;
`
`C1 ass [] getEntryC'| asses (Se rvi ceTemp1 ate tmpl)
`th rows Remote Excepti on;
`
`Object [] getF'I' e'ldVa'| ues (Servi ceTempl ate tmpl ,
`
`ti"t'1"1.‘.I(il"I}|l'I0"[
`
`233
`
`

`
`Servi ceflegfstrar
`
`‘int setIndex,
`String field)
`throws NoSuchF'i elclExcept1'on, Remo1:eExcept'ion;
`
`C1 ass [] getse r'v'i ceTypes(5erv'i ceTemp'| ate tmpl ,
`String pref-ix)
`throws RemoteExcep1:'fon;
`
`Serv-i ceID getSer'v1' ceID();
`LookupLocator' getLoca1:orO throws RemoteExcept'icn;
`
`Stri ng[] getcroups O throws Remo1:eExcept1' on;
`
`}
`
`Every method invocation on Serv1'ceRegistr'ar and Servi ceReg1'strat1' on is
`atomic with respect to other invocations.
`The register method is 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 RemoteExcep1:-i on (in
`which case the item might or might not have been registered), the caller can sim-
`ply repeat the call to register with the same parameters, until it succeeds.
`To register a new service, item. servi ceID should be null. In that case, if
`item.servi ce does not equal (using Marsha11ed0bject.equa1s) any existing
`item’s service object, then a new service ID will be assigned and included in the
`returned Se r'v1' ce Regi st rati on (described in the next section). The service ID is
`unique over time and space with respect to all other service IDs generated by all
`lockup services. If item . service does equal an existing ite1n‘s service object, the
`existing item is first deleted from the lookup service (even if it has difierent
`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 lockup
`service, item. serv1'ceID should be set to the same service ID that was returned
`by the initial registration. If an item is already registered under the same service
`ID, the existing item is first deleted (even if it has different attributes or a different
`service instance) and its lease is cancelled by the lookup service. Note that service
`object equality is not checked in this case, to allow for reasonable evolution of the
`service (for example, the serialized form of the stub changes or 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 returned lease is allowed to have a shorter (but not
`
`234
`
`

`
`THE JINI LOOKUP SERVICEISPECIFICATION
`
`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
`Servi celtem. service) from an item matching the template or null 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 Unmarshal Exception is thrown with the standard RMI semantics.
`
`The two-parameter form of l ookup returns at most maxMatches items match-
`ing the template and the total number of items that match the template. The return
`value is never null, and the returned items array is null only if maxmatches is
`zero. For each returned item, if the service object cannot be deserialized, the
`servi ce field of the item is set to null and no exception is thrown. Similarly, if
`an attribute set cannot be deserialized, that element of the att r'1' butese ts array is
`set to null and no exception is thrown.
`The notify method is 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 EventReg1' strati on is
`unique at least with respect to all other active event registrations at this loolcup ser-
`vice with different service templates or transitions.
`While the event registration is in effect, a Se rvi ce Event is sent to the speci-
`fied listener whenever a regi ster, 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:
`
`0 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).
`
`6 TRAN SITI0N_N0MATCH_|VlATCH: 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
`9 TRANSITION_MATCH_MATCH: An event
`matches the template both before and after the operation.
`
`The getTrans1't1' on method of Serv1'ceEvent returns the singleton transi-
`tion value that triggered the match.
`The getServ1'ceItem method of Se r'v1' ceEvent returns the new state of the
`item (the state after the operation) or null if the item was deleted by the opera-
`tion. Note that this method is declared abstract; a lookup service uses a subclass
`of Se rvi Ce-Event to transmit the new state of the item however it chooses.
`
`235
`
`

`
`Serv1’ceRegfst.r-ar
`
`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 occur if
`the lookup service 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 getEnt r~yc1 asses method looks at all service items that match the spec-
`ified template, finds every entry (among those service items) that either dcesn’t
`match any entry templates or is a subclass of at least one matching entry template,
`and returns the 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
`null reference (not an empty array) is returned if 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 null and no exception is thrown.
`The get Fi el dval ues method looks at all service items that match the speci-
`fied template,
`finds every entry (amcng those service items) that matches
`tmpl .attr'1' buteSetTempl'ates [setlndex], and returns the set of values of the
`specified field of those entries. Duplicate values are eliminated, and the crdercf
`values within the returned array is arbitrary. a null reference (not an empty array)
`is returned if there are no matching items. If a returned value cannot be deserial-
`ized, that element of the returned array is set to null and no exception is thrown.
`NoSuchF1‘eldExcept1' on is thrown if ‘F1’ eld does not name a field of the entry
`template.
`The getSer'v'iceTypes method looks at 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 instance of that are neither equal to, nor a
`superclass of, any of the service types in the template and that have names that
`start with the specified prefix, and returns the 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
`null and no exception is thrown.
`Every lockup service assigns itself a service ID when it is first created; this
`service ID is returned by the getServ1'ceID method. (Note that this does not
`make a remote call.) A lockup service is always registered with itself under this
`service ID, and if a lockup service is configured to register itself with other lockup
`services, it will register with all of them using this same service ID.
`The ge1:Locatcr method returns a LookupLocatcr that can be used if neces-
`sary fcr unicast discovery of the lockup service. The definition of this class is
`given in the Jim’ Technology Discovery and Join. Specification.
`
`236
`
`

`
`THE JINI LOOKUP SERVICE SPECIFICATION
`
`The getc roups method returns the set of groups that this lookup service is
`currently a member of. The semantics of these groups is defined in the Jim Tech-
`nology Discovery and Join Specification.
`
`LU.2.6
`
`Ser-v-i ceReg'i stration
`
`A registered service item is manipulated using a Servi ceReg1' st ration instance.
`public interface Servicekegistration {
`ServiceID getServiceID();
`Lease getLease():
`void addAttributes(Entry[] attrsets)
`throws UnknownLeaseException, RemoteException:
`void modifyAttribute5(Entry[] attrSetTemplates,
`Entry[] attrsets)
`throws UnknownLeaseException, RemoteException;
`void setAttributes(Entry[] attrsets)
`throws UnknownLeaseException, RemoteException:
`
`Like Ser-v1‘ceReg-i strar, this is not a remote interface; each implementation of
`the lookup service exports proxy objects that implement this interface local to the
`client. The proxy methods obey normal RMI remote interface semantics.
`The getservi ceID method returns the service ID for this service. (Note that
`this does not make a remote call.)
`The get Lease 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 addAt1:r'ibutes 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. UnknownLeaseExcepti on is thrown if the reg-
`istration lease has expired or been cancelled.
`The n1od1'fyAttr-ibutes method is used to modify existing attribute sets. The
`lengths of the att rSetTempl ates and attrsets arrays must be equal, or
`I1 legal Ar'gun1entExcept'i on is thrown. The service item’s attribute sets are mod-
`ified as follows. For each array index i 2 if attrSets[1' ] is null, then every entry
`that matches attrSetTemp'l ates [i] is deleted; otherwise, for every non-null
`field in att rsets [i ] , the value of that field is stored into the corresponding field
`of every entry that matches attrSetTemp1 ates [-i ]. The‘ class of attr'Sets[1']
`must be the same as, or a superclass of, the class of attrSetTempl ates [i], or
`
`237
`
`

`
`SERBLIJZED FORMS
`
`Il'|ega'lArgumentExcept1' on is thrown. If the modifications result in duplicate
`entries within
`the
`service
`item,
`the
`duplicates
`are
`eliminated. An
`UnknownLeaseExcept1° on is thrown if the registration lease has expired or been
`cancelled.
`
`Note that it is possible to use mod'i‘FyA1:tr"ibutes in ways that are not idem-
`potent. The attribute schema should be designed in such a way that all intended
`uses of this method can be performed in an idempotent fashion. Also note that
`mod1'fyAttr1'butes does not provide a means for setting a field to null; it is
`assumed that the attribute schema is designed in such a way that this is not neces-
`saty.
`I
`The 5etAttr1' butes 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.
`UnknownLeaseExu:ept1'on is thrown if the registration lease has expired or been
`cancelled.
`
`LU.2.7 Serialized Forms
`
`
`
`Serialized Fields
`ser1'a1Ver-s-ionUID
`Class
` j._
`
`Se rv1' ceID
`
`—7803375959559762239L Tong mos tS1' [.1
`long '|eastS1' g
`
`Se rvi ce Item
`
`71739545 1032330758L all public fields
`
`Servi ceTemp1 ate
`
`78544838078864832l6L all public fields
`
`Se rvi ceMatch es
`
`—5518280843537399398L all publicfielals
`
`1304997274-O96842701L Serv1'ceID 5ery'iceID
`Servi ce-Event
`
`- int transition
`
`238
`
`

`
`239
`
`

`
`THE JIN! LOOKUP ATIRIBUTE SCHEMA SPECIFICATION defines a set ofattributes
`that a local administrator might choose to place on a service. These are
`“serving suggestions”—nobody is required to use these
`attribute definitions, but they give a starting pointfor
`A people who need such attributes to either use directly
`or usefor inspiration. This also describes the common
`stylefor entry design, including the canonical way to
`present your entry as a JavaBean object.
`
`U
`
`240
`
`

`
`Schema Specification
`
`LS.1 Introduction
`
`TEEE Jini Lookup service provides facilities for services to advertise their avail-
`ability and for would-be clients to obtain references to those services based on the
`attributes they provide. The mechanism that it provides for registering and query-
`ing based on attributes is centered on the Java platform type system, and is based
`on the notion of an entry.
`An entry is a class that contains a number of public 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 registeiing itself in the lookup service, which means
`that attributes on each service are provided in a set of sets.
`The purpose of this document is to provide a framework in which services and
`their would-be clients can interoperate. This framework takes two parts:
`
`0 We describe a set of common predefined entries that span much of the basic
`functionality that is needed both by services registering themselves and by
`entities that are searching for services.
`
`0 Since we cannot anticipate all of the future needs of clients of the lookup ser-
`vice, we provide a set of guidelines and design patterns for extending, using,
`and imitating this set in ways that are consistent and predictable. We also
`construct some examples that illustrate the use of these patterns.
`
`241
`
`

`
`TERMINOLOGY
`
`LS.1.1 Terminology -
`
`Throughoutthis document, we will use the following terms in consistent ways:
`
`0 Service-——a service that has registered, or will register, itself with the lookup
`service
`
`9 CZient——an entity 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 Carmot Always Be Automated
`
`No matter how much information it has at its disposal, a client of the lookup ser-
`vice will not always be able to find a single unique match without assistance when
`it performs a lookup. In many instances we expect that more than one service will
`match a particular query. Accordingly, both the lookup service and the attribute
`schema are geared toward reducing the number of matches that are returned on a
`given lookup to a minimum, and not necessarily to just one.
`
`Attributes Are Mostly Static
`
`We have designed the schema for the Iookup service with the assumption that
`most attributes will not need to be changed frequently. For example, we do not
`expect attributes to change more often than once every minute or so. This decision
`is based on our expectation that clients that need to make a choice of service based
`on more frequently updated attributes will be able to talk to whatever small set of
`services the lookup service returns for a query, and on our belief that the benefit of
`updating attributes frequently at the loolcup service is outweighed by the cost in
`network traffic and processing.
`
`Humans Need to Understand Most Attributes
`
`A corollary of the idea that matching cannot always be automated is that
`humans—whether they be users or administrators of services—must be able to
`understand and interpret attributes. This has several implications:
`
`242
`
`

`
`THE IINI LOOKUP ATTRIBUTE SCHEMA SPECIFICATION
`
`9 We must provide a mechanism to deal with localization of attributes
`
`0 Multiple-valued attributes must provide a way for humans to see only one
`value (see Section LS.2)
`
`We will cover human accessibility of attributes soon.
`
`Attributes Can Be Changed by Services or Humans, But Not Both
`
`For any given attribute class we expect that attributes within that class will all be
`set 01' modified either by the service, or via human intervention, but not both.
`What do we mean by this? A service is unlikely to be able to determine that it has
`been moved from one room to another, for example, so we would not expect the
`fields of a “location” attiibute class to be changed by the service itself. Similarly,
`we do not expect that a human operator will need to change the name of the ven-
`dor of a particular service.
`This idea has implications for our approach to ensuring that the values of
`attributes are valid.
`
`Attributes Must Interoperate with JavaBeans Components
`
`The JavaBeans specification provides a number of facilities relating to the local-
`ized display and modification of properties, and has been widely adopted. It is to
`our advantage to provide a familiar set of mechanisms for manipulating attributes
`in these ways.
`
`l.."Il
`
`L’.tt.ta1|.1_r_.';
`
`[[l‘l1-]_f)()"_[_
`
`LS.1.3 Dependencies
`
`This document relies on the following other specifications:
`
`0 Jim‘ Entry Specification
`
`O Jini Entry Utilities Specification
`
`0- .IavaBeans Specification
`
`243
`
`

`
`THE JINI LOOKUPAYTRIBUTE SCHEMA SPECIFICATION
`
`'
`
`" ‘. .F!_£‘fl‘KW&TEQ!mifi‘i
`
`LS.2 Human Access to Attributes
`
`LS.2.1
`Providing a Single View of an Attribute’s Value
`CONSIDER the following entry class:
`
`public class Foo implements net.j1'n1'.cor-e.entry.Entry {
`public Bar baz;
`
`}
`
`public class Bar {
`int quux;
`bcolean zot:
`
`}
`
`A visual search tool is going to have a difficult time rendering the value of an
`instance of class Bar in a manner that is comprehensible to humans. Accordingly,
`to avoid such situations, entry class irnplementors should use