`
`
`[TRANSAarrow SPECIFICATION
`erializability might be violated. When a subtransaction commits, its
`
`then S
`erited by the parent transaction.
`are inh
`
`In addition to locks, transactional operations can be defined in terms of object
`
`I, "-0,, and deletion visibility. If an object is defined to be created under a trans-
`J then the existence of the object is visible only within that transaction and
`
`t
`'1
`whims, but will disappear if the transaction aborts. If an object is defined to
`leted under a transaction, then the object is not visible to any transaction
`
`
`mg the deleting transaction) but will reappear if the transaction aborts.
`
`- a nested transaction commits, visibility state is inherited by the parent
`tion.
`
`rice a transaction reaches the VOTING stage, if all execution under the trans-
`
`n (and its subtransactions) has finished, then the only reasons the transaction
`
`bort are:
`
`
`The manager crashes (or has crashed)
`
`
`it One or more participants crash (or have crashed)
`
`c' 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 aborte
`
`An active transaction is an orphan if it or one of its ancestors is guaranteed to
`
`This can occur because an ancestor has explicitly aborted or because some
`
`manager of the transaction or an ancestor has crashed. Orphans are
`
`>guaranteed to be detected by the system, so programmers using transactions
`
`i-bc aware that orphans can see internally inconsistent state and take appropri-
`
`:t tiOl'i.
`
`ausal ordering information about transactions is not guaranteed to be propa-
`First, given two sibling transactions (at any level), it is not possible to tell
`
`' er they were created concurrently or sequentially (or in what order). Sec-
`
`lf two transactions are causally ordered and the 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 abo r't that takes a timeout parameter. Programmers
`
`nan-blocking forms of operations must take this into account.
`
`3' long as a transaction persists in attempting to acquire a lock. that conflicts
`
`another transaction, the participant will persist in attempting to resolve the
`
`the of the transaction that holds the conflicting lock. Attempts to acquire a
`
`include making a blocking call, continuing to make non-blocking calls, and
`
`listing for event notification under a transaction.
`
`223
`
`223
`
`

`

`
`
`TX.3.6 Serialized Forms
`
`Class
`seria'lVer-si onUID
`
`Serialized Fields
`
`Transaction.Created
`
`—5199291723008952986L
`
`Nestab1eTransaction.Created
`
`72979247545926318953L
`
`TransactionManager.Created
`
`—4233846033773471113L
`
`ServerTransaction
`
`4552277137549765374L
`
`NestabieServerTransaction
`
`73438419132543972925L
`
`Transactianxception
`
`—5009935764793203986L
`
`CannotAbortException
`
`3597101646737510009L
`
`CannotComwitException
`
`—4497341152359563957L
`
`CannotloinException
`
`556839304393?204939L
`
`CannotNestException
`
`3409604500491735434L
`
`ailpublicfieids
`
`allpnbiicfields
`
`ailpnblicfields
`
`ail pnblicfields
`
`all pubh‘c fields
`none
`
`none
`
`none
`
`none
`
`none
`
`TimeoutExpiredException
`
`3918773760682958000L
`
`UnknownTransactionException
`
`443798629936327009L
`
`all public fields
`none
`
`4299226125245015671L
`CrashCountException
`
`H0116
`
`
`
`224
`
`224
`
`

`

`$45
`
`$853393
`
`225
`
`225
`
`
`

`

`n.7F—Flfi—.&Tmmnlvn#‘q‘—il.rc :1;er
`
`
`The Jini Lookup service
`Specification
`
`_
`
`.. =_=.=u=
`
`
`
`LU.1 Introduction
`
`THE 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 Jim
`software infrastructure. The lockup service provides a central registry of services
`available within the djinn. This lookup 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
`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 djinn’s lookup service, providing an
`initial collection of attributes. For example, a printer might include attributes indi-
`
`217
`
`
`
`226
`
`226
`
`

`

`
`
`
`
`218
`
`A'ITRIBUT‘ES
`
`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 . ji ni' . co re . transaction . serve r .TransactionManage r 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
`
`227
`
`

`

`
`
`THE JIN! LOOKUP SERVICE SPECIFICATION
`
`219
`
`specification, but a standard foundation schema for Jini systems is defined in the
`Jini Looktip 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 lockup 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:
`
`¢ Java Remote Method Invocation Specification
`
`0 Java Object Serialization Specification
`
`9 Jini Entry Specification
`
`9 .iini Distributed Event Specification
`
`9 Jini Distributed Leasing Specification
`
`9 flat Discovery and Join Specification
`
`
`
`
`
`
`
`228
`
`228
`
`

`

`fl
`
`THE JIM LOOKUP SER VICE SPECH-"ICA new
`
`22 l
`
`
`
`LU.2 The Se rvi ceRegi st r'ar'
`
`fil?HEtypcsdefinedinthisspedficafionzneinthenet.jini.core.lookuppack—
`age. The following types are imported from other packages and are referenced in
`unqualified form in the rest ofthis specification:
`
`java.rmi.Marshalledobject
`java.rmi.RemoteException
`java.rmi.UnmarshalException
`java.io.Serializable
`java.io.DataInput
`java.io.Data0utput
`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
`
`Se r'vi ceID
`
`Every service is assigned a universally unique identifier (UUID), represented as an
`instance of the Se rvi ceID class.
`
`public final class ServiceID implements Serializable {
`public ServiceID(long mostSig,
`long leastSig) {m}
`public ServiceIDCDataInput
`in) throws IOException {m}
`public void writeBytesCDataOutput out) throws IOException
`{m}
`
`public long getMostSignificantBitsC) {m}
`public long getLeastSignificantBits() {m}
`
`
`
`.
`i
`
`
`
`229
`
`229
`
`

`

`a 2
`
`Servi ceItem
`
`22
`
`A service [D 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 Servi ceID constructor merely takes 128 bits of data, to be computed
`in an implementation-dependent manner by the lookup service. The writeBytes
`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:
`
`GXFFFFFFFFBBGQOGOO
`@xOGGQGOBGFFFFDGBG
`@xBOBGGGGDBBGBFGOG
`@xOBGGOGGQfiBGGfiFFF
`
`time_l ow
`ti meJni d
`version
`ti me_hi
`
`The least significant long can be decomposed into the following unsigned fields:
`BXCBBBBQQGGGOOQOBO
`variant
`BXBFFFBOOBGQGGGGQQ
`clock_seq
`oxeeeeFFFFFFFFFFFF
`node
`
`The variant field must be 0x2. The version field must be either 0x1 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 number generator. If the version field is 0x], 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 time_l ow, time_mi d, and ti me_hi fields are set to the least,
`middle, and most significant bits (respectively) of a 60—bit timestamp measured in
`IOU—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: time_l ow, time_mi at, version and
`timefihi treated as a single field, variant and cl ock_seq treated as a single field,
`and node.
`
`LU.2.2
`
`Se rvi cel‘tem
`
`Items are stored in the lookup service using instances of the Se rvi ceItem class.
`
`public class ServiceItem implements Serializable {
`public ServicelteMSer-viceID serviceID,
`Object service,
`
`
`
`230
`
`230
`
`

`

`*
`
`THE JINI LOOKUP SERVICE SPECIFICA TION
`
`223
`
`Entry[] attributeSets) {...}
`public ServiceID serviceID;
`public Object service;
`
`public Entryll 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 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
`lookup service; alternate semantics for individual operations are defined later in
`this section.
`
`LU.2.3 ServiceTempl ate and Item Matching
`
`Items in the lookup service are matched using instances of the Se rvi ceTempl ate
`class.
`
`public class ServiceTemplate implements Serializable {
`public ServiceTemplateCServiceID serviceID,
`ClassE] serviceTypes,
`Entry[] attributeSetTemplates) {m}
`public Servi ceID serviceID;
`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 (tmp'l) if:
`
`9 item. servi ceID equals tmpl .serviceID (or iftmpl .servi ceID is null),
`and
`
`o item.servi ce is an instance of every type in tmpl .serviceTypes, and
`
`o i tem.attribute5ets contains at least one matching entry for each entry
`template in tmpl .attributeSetTemplates.
`
`
`
`!
`
`i
`
`5
`
`i
`
`l
`!
`
`
`
`
`
`231
`
`231
`
`

`

`.._fa
`
`224
`
`OTHER SUPPORTING trans
`
`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-null 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 buteSetTemplates, a null field is equivalent to an
`empty array; both represent a wildcard.
`
`LU.2.4 Other Supporting Types
`
`The Servi ceMatches class is used for the return value when looking up mul-
`tiple items.
`
`public class ServiceMatches implements Serializable {
`public ServiceMatches(ServiceItemfl
`items,
`int totalMatches) {..r}
`items;
`public ServiceItem[]
`public int totalMatches;
`
`}
`
`The constructor simply assigns each parameter to the corresponding field.
`A Servi ceEvent extends RemoteEvent with methods to obtain the service ID
`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 ServiceEventCObject source,
`long eventID,
`long seqNum,
`
`MarshalledObject handback,
`ServiceID serviceID,
`int transition) {m}
`public ServiceID getServiceID() {m}
`public int getTransition() {m}
`public abstract ServceItem getServiceItemC)
`
`{m}
`
`}
`
`The getServiceID and getTransition methods return the value of the corre-
`sponding constructor parameter. The remaining constructor parameters are the
`same as in the RemoteEvent constructor.
`The rest of the semantics of both these classes is explained in the next section.
`
`
`
`232
`
`232
`
`

`

`THE 11m LOOKUP sea VICE SPECIFICATION
`
`225
`
`LU.2.5
`
`Se r-vi ceRegi strar
`
`TheServiceRegistrardefinesthenueflacetothelookupsendce.Thehnen
`face is not a remote interface; each implementation of the lookup service exports
`proxy objects that implement the Servi ceRegi st rar interface local to 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 lookup 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 inter-Face ServiceRegistrar {
`ServiceRegistration registerCServiceItem item,
`
`.
`‘
`
`'
`
`i
`
`_
`!
`
`i
`5
`!
`
`l
`
`long leaseDuration)
`
`th rows Remote Exception;
`
`lookup(ServiceTemplate tmpl)
`Object
`throws RemoteException;
`
`ServiceMatches
`
`lookupCServiceTemplate tmpl,
`throws RemoteException;
`
`int maxMatches)
`
`1 << 0;
`int TRANSITION_MATCH_NOMATCH
`1 << 1;
`int TRANSITIDN_NOMATCH_MATCH
`int TRANSITION_MATCH_MATCH = 1 << 2;
`
`EventRegistration notify(ServiceTemplate tmpl,
`int transitions,
`RemoteEventListener listener
`
`MarshalledObject handback,
`long leaseDuration)
`throws RemoteException;
`
`Class[] getEntryClasses(ServiceTemplate tmpl)
`throws RemoteException;
`
`0bject[] getFieldValuesCServiceTemplate tmpl.
`
`
`
`233
`
`233
`
`

`

`— 2
`
`ServiceRegistrar
`
`26
`
`int setIndex,
`String field)
`throws NoSuchFieldException. RemoteException;
`
`C1ass[] getServi ceTypesCServiceTemp‘late tmpl,
`String prefix)
`throws RemoteException;
`
`ServiceID getServi ceIDO;
`LookupLocator getLocatorO throws RemoteException;
`
`String[] getGroupsO throws RemoteException;
`
`1-
`
`Every method invocation on Servi ceReg‘istr'ar and ServiceRegistration 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 RemoteExcept‘ion (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.serviceID should be null. In that case, if
`item. service does not equal (using MarshalledObject.equa1 5) any existing
`item’s service object, then a new service ID will be assigned and included in the
`returned Se rvi ce Regi strati 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 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 lockup
`service, item . servi 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
`
`234
`
`

`

`
`
`THE .IINI LOOKUF SERVICE SPECIFICATION
`
`227
`
`longer) duration than what was requested. The registration is persisrent across
`restarts (crashes) of the lockup service until the lease expires or is cancelled.
`The single-parameter form of lockup returns the service object (i.e., just
`Se rvi ceItem.servi ce) 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 lockup returns at most maxi/latches 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
`service 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 uni buteSets 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 untii the
`lease expires or is cancelled. The event ID in the returned EventRegi' stration is
`unique at least with respect to all other active event registrations at this lockup ser-
`vice with different service templates or transitions.
`While the event registration is in effect, a Servi ce Event 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:
`
`9 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).
`
`o TRANSITIONANOMATCHnMATCH: 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
`0 TRANSITION_MATCH_MATCH: An event
`matches the template both before and after the operation.
`
`The getTransiticn method of Se rvi ceEvent returns the singleton transi—
`tion value that triggered the match.
`The getServiceItem method of Serv‘i 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 lockup service uses a subclass
`of Se rv-i ceEvent to transmit the new state of the item however it chooses.
`
`
`
`
`
`235
`
`235
`
`

`

`-—fi———fi
`
`228
`
`Serviceflegfsrrar
`
`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 lockup 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 getEntryCl asses method looks at all service items that match the spec-
`ified template, finds every entry (among those service items) that either doesn’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 these 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 FieldVal ues method looks at all service items that match the speci—
`fied template,
`finds every entry (among these service items)
`that matches
`tmpl an m" buteSetTempl ates [setIndex], and returns the set of values of the
`specified field of these entries. Duplicate values are eliminated, and the order of
`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.
`NcSuchFieldException is thrown if field does not name a field of the entry
`template.
`The getServi ceTypes 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 getServiceID 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 getLocatcr' method returns a Lookuchcator that can be used if neces-
`sary for unicast discovery of the lockup service. The definition of this class is
`given in the Jini Technology Discovery and Join Specification.
`
`
`
`236
`
`236
`
`

`

`*. J
`
`THE JINI LOOKUP SERVICE SPECIFICATION
`
`229
`
`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 Jim Tech-
`nology Discovery and Join Specification.
`
`LILZfi ServiceRegistration
`
`A registered service item is manipulated using a Servi ceRegi strati on instance.
`public interface Servi ceRegistration {
`ServiceID getServiceIDO;
`Lease getLeaset);
`void addAttributescEntry[] attrSets)
`throws UnknownLeaseException, RemoteException:
`void modifyAttributesCEntry[] attrSetTemplates,
`EntryE] attrSets)
`th rows UnknownLeaseExcepti on, RemoteExcepti on ;
`void setAttributesCEntryU attrSets)
`throws UnknownLeaseException. RemoteException;
`
`}
`Like ServiceRegistrar. 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 0310 method returns the service 1D 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 addAttri butes 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 modi fyAttri butes method is used to modify existing attribute sets. The
`lengths of the attrSetTempl ates and attrSets arrays must be equal, or
`IT 1 egal ArgumentExce pt‘i on is thrown. The service item’s attribute sets are mod-
`ified as follows. For each array index i: if attrSetsEi] is nul i, then every entry
`that matches attrSetTemp'l ates[i] is deleted; otherwise, for every non-null
`field in attrSets [i]. the value of that 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 attrSetTemp'l atesEi], or
`
`_
`
`i
`i
`
`
`
`i
`.:
`
`
`
`__
`
`'
`
`
`
`237
`
`237
`
`

`

`,
`
`230
`
`I
`
`SERIAIJZED FORMS
`
`I'I'IegalArgumentException is thrown. If the modifications result in duplicate
`entries within
`the
`service
`item,
`the
`duplicates
`are
`eliminated. An
`UnknownLeaseExcepti on is thrown if the registration lease has expired or been
`cancelled.
`
`Note that it is possible to use modi 'FyAttributes 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
`merit fyAttributes 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~
`sary.
`
`The setAttr-i 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.
`UnknownLeaseExcept‘ion is thrown if the registration lease has expired or been
`cancelled.
`
`LU.2.7 Serialized Forms
`
`
`Class
`
`Servi ceID
`
`I
`
`serial VersionUID
`
`Serialized Fields
`
`—7803375959559762239L long mostS‘ig
`long 'Ieastsi'g
`
`Se r‘vi ceItem
`
`717395451032330758L ailpublicfieids
`
`Servi ceTempl ate
`
`7854483807886483216L all publicfieids
`
`Se rvi ceMatches
`
`“551828034353739939814 all pubit‘cfields
`
`13049972740968427011. ServiceID serviceID
`ServiceEvent
`
`- int transition
`
`
`
`238
`
`238
`
`

`

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

`

`THE JINI LOOKUP ATTRIBUTE SCHEMA SPECIFICATION defines a set ofattributes
`that u loco! 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 use for inspiration. This also describes the common
`stylefor entry design, including the eanonieai way to
`present your entry as o. Jo voBean object.
`
`U
`
`INIT”
`
`
`
`240
`
`240
`
`

`

` :1
`
`
`
`The Jini Lookup Attribute
`Schema Specification
`
`LS.1 Introduction
`
`THE 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 registering 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.
`
`
`
`
`
`233
`
`
`
`241
`
`241
`
`

`

`234
`
`TERMINOLOGY
`
`LS.1.1 Terminology
`
`Throughout this 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 Client—an entity that performs queries on the lockup service, in order to
`find particular services
`
`LS.1.2 Design Issues
`
`Several factors influence and constrain the design of the lockup service schema.
`
`Matching Cannot 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 lockup. 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 lockup to a minimum, and not necessarily to just one.
`
`Attributes Are Mostly Static
`
`We have designed the schema for the lookup 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