INIW
`
`A Collection of JiniTM
`
`Technology Helper
`Utilities and Services
`
`Specifications
`
`This Collection of JiniTM Technology Helper Utilities and
`Services Specifications defines a set of standard helper utilities
`and services which extend the Jini Technology Core Platform.
`These helper utilities and services encapsulate desirable
`behaviors in the form of a set ofreusable components that can be
`used to help simplify the process ofdeveloping Jini technology-
`enabled clients and services (Jim' clients andservices) for the Jini
`technology application environment. Employing these utilities
`and services to build such desirable behavior into a Jini client or
`
`service can help to avoid poor design and implementation
`decisions, greatly simplifying the development process.
`
`®«Mun
`
`microsystems
`
`Version 1.1
`October 2000
`
`1
`
`APPLE 1020
`
`1
`
`APPLE 1020
`
`

`

`ii
`
`Copyright © 2000 Sun Microsystems, Inc.
`901 San Antonio Road, Palo Alto, CA 94303 USA.
`All rights reserved.
`
`Sun Microsystems, Inc. has intellectual property rights (“Sun IPR”) relating to implementations of the technology
`described in this publication (“the Technology”). In particular, and without limitation, Sun IPR may include one or more
`patents or patent applications in the US. or other countries. Your limited right to use this publication does not grant you any
`right or license to Sun IPR nor any right or license to implement the Technology. Sun may, in its sole discretion, make
`available a limited license to Sun IPR and/or to the Technology under a separate license agreement. Please visit http://
`WWW. sun. com/software/communitysource/.
`
`Sun, the Sun logo, Sun Microsystems, Jini, the Jini logo, JavaSpaces, Java, and JavaBeans are trademarks or registered
`trademarks of Sun Microsystems, Inc. in the United States and other countries.
`
`THIS SPECIFICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
`IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FIT-
`NESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
`
`THIS SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS.
`CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE
`INCORPORATED IN NEW EDITIONS OF THE SPECIFICATION. SUN MICROSYSTEMS, INC. MAY MAKE
`IMPROVEMENTS AND/OR CHANGES IN ANY TECHNOLOGY, PRODUCT, OR PROGRAM DESCRIBED IN
`THIS SPECIFICATION AT ANY TIME.
`
`2
`
`

`

`
`
`
`
`Contents
`
`US Introduction to Helper Utilities and Services ............ 1
`
`US.1 Summary ................................................ 1
`US.2 Terminology ............................................. 3
`US.2.1 Terms Related to Discovery and Join ..................... 3
`US.2.2 Jini Clients and Services ............................... 4
`
`US.2.3 Helper Service ....................................... 4
`
`US.2.4 Helper Utility ........................................ 5
`US.2.5 Managed Sets ........................................ 5
`US.2.6 What Exceptions Imply about Future Behavior ............. 5
`US.2.7 Unavailable Lookup Services ........................... 7
`US.2.8 Discarding a Lookup Service ........................... 8
`US.2.8.1 Active Communication Discarded Event .......... 8
`
`US.2.8.2 Active No-Interest Discarded Event .............. 9
`
`US.2.8.3 Passive Communication Discarded Event ......... 9
`
`US.2.8.4 Passive No-Interest Discarded Event ............. 9
`
`US.2.8.5 Changed Event ............................. 10
`US.2.8.6 Remote Objects, Stubs, and Proxies ............. 10
`US.2.9 Activation ......................................... 12
`
`US.3 Introduction to the Helper Utilities ..................... 13
`US.3.1 The Discovery Utilities ............................... 13
`US.3.1.1
`The D'i scove ryManagement Interface .......... 14
`
`US.3.1.2 The D1" scove ryGroupManagement Interface ..... 14
`
`US.3.1.3 The D'i scoveryLocatorManagement Interface .
`
`.
`
`. 14
`
`US.3.1.4 The LookupD‘i scove ry Helper Utility .......... 14
`US.3.1.5 The LookupLocatorDi scovery Helper Utility .
`.
`. 15
`US.3.1.6 The LookupD‘i scoveryManager Helper Utility .
`.
`. 15
`US.3.1.7 The Constants Class ....................... 15
`
`US.3.1.8 The Outgoi ngMul t1" castRequest Utility ....... 15
`US.3.1.9 The Incom‘i ngMu'l t'i castRequest Utility ....... 15
`US.3.1.10 The Outgoi ngMul t1" castAnnouncement Utility .
`. 16
`
`3
`
`

`

`iv
`
`[38.31.11 The Incomi ngMul ti castAnnouncement Utility . 16
`US.3.1.12 The Outgoi ngUni castRequest Utility ........ 16
`[38.31.13 The Incomi ngUm' castRequest Utility ........ 16
`
`[38.31.14 The Outgoi ngUm' castResponse Utility ....... 16
`US.3.1.15 The Incomi ngUni castResponse Utility ....... 16
`US.3.2 The Lease Utilities .................................. 17
`
`The LeaseRenewal Manager Helper Utility ...... 17
`US.3.2.1
`US.3.3 The Join Utilities .................................... 17
`
`
`
`The 301' nManager Helper Utility .............. l7
`[38.3.3.1
`US.3.4 The Service Discovery Utilities ........................ 18
`[38.341
`The Se rvi ceDi scoveryManager Helper Utility. . 18
`USA Introduction to the Helper Services ..................... 19
`US.4.1 The Lookup Discovery Service ........................ l9
`US.4.2 The Lease Renewal Service ........................... 19
`
`US.4.3 The Event Mailbox Service ........................... 20
`
`USS Dependencies ........................................... 21
`
`DU Jini Discovery Utilities Specification .................... 23
`
`DU.1 Introduction ............................................ 23
`
`DU.1.1 Dependencies ...................................... 23
`DU.2 The Discovery Management Interfaces ................. 25
`DU.2.1 Overview .......................................... 25
`
`DU.2.2 Other Types ........................................ 26
`DU.2.3 The D1" scove ryManagement Interface ................... 27
`DU.2.3.1 The Semantics ............................. 27
`
`DU.2.4 The D1" scove ryGroupManagement Interface .............. 30
`DU.2.4.1 The Semantics ............................. 30
`
`DU.2.5 The D'i scove ryLocatorManagement Interface ............ 32
`DU.2.5.1 The Semantics ............................. 33
`
`DU.2.6 Supporting Interfaces and Classes ...................... 34
`DU.2.6.1 The Di scoveryL‘i stener Interface ............ 34
`
`DU.2.6.2 The D1' scoveryChangeLi stener Interface ...... 35
`
`DU.2.6.3 The Di scoveryEvent Class .................. 36
`DU.2.7 Serialized Forms .................................... 38
`
`DU.3 LookupD'i scover'y Utility ............................... 39
`DU.3.1 Other Types ........................................ 39
`DU.3.2 The Interface ....................................... 40
`
`DU.3.3 The Semantics ...................................... 40
`
`DU.3.4 Supporting Interfaces and Classes ...................... 41
`DU.3.4.1 The D1' scove ryManagement Interfaces ......... 41
`
`DU.3.4.2 Security and Multicast Discovery: The
`42
`D1" scove ryPe mi 551' on Class
`DU.3.5 Serialized Forms .................................... 43
`
`4
`
`

`

`DU.4 The LookupLocator'Di scover'y Utility .................. 45
`DU.4.1 Overview .......................................... 45
`
`DU.4.2 Other Types ........................................ 46
`DU.4.3 The Interface ....................................... 46
`
`DU.4.4 The Semantics ...................................... 47
`
`DU.4.5 Supporting Interfaces ................................. 48
`DU.4.5.1 The Di scove ryManagement Interfaces .......... 48
`The LookupDi scover'yManager' Utility .................. 49
`DU.5.1 Overview .......................................... 49
`
`DU.5
`
`DU.5.2 Other Types ........................................ 49
`DU.5.3 The Interface ....................................... 50
`
`DU.5.4 The Semantics ...................................... 50
`
`DU.5.5 Supporting Interfaces and Classes ....................... 53
`DU.5.5.1 The Di scove ryManagement Interfaces .......... 53
`
`DU.5.5.2 Security and Multicast Discovery: The
`Di scoveryPermission Class
`53
`Low-Level Discovery Protocol Utilities .................. 55
`DU.6.1 The Constants Class ................................ 55
`DL'.6.1.1 Overview ................................. 55
`
`DU.6
`
`DU.6.1.2 Other Types ............................... 55
`DU.6.1.3 The Class Definition ......................... 56
`
`DL'.6.1.4 The Semantics ............................. 56
`
`DU.6.2 The Outgoi ngMuI ti castRequest Utility ................ 57
`DU.6.2.1 Overview ................................. 57
`
`DL'.6.2.2 Other Types ............................... 57
`DL'.6.2.3 The Interface ............................... 57
`
`DU.6.2.4 The Semantics ............................. 58
`
`DU.6.3 The Incomi ngMuI ti castRequest Utility ................ 58
`DL'.6.3.1 Overview ................................. 58
`
`DU.6.3.2 Other Types ............................... 59
`DU.6.3.3 The Interface ............................... 59
`
`DL'.6.3.4 The Semantics ............................. 59
`
`DU.6.4 The Outgoi ngMuI ti castAnnouncement Utility ........... 60
`DU.6.4.1 Overview ................................. 60
`
`DL'.6.4.2 Other Types ............................... 60
`DL'.6.4.3 The Interface ............................... 61
`
`DU.6.4.4 The Semantics ............................. 61
`
`DU.6.5 The Incomi ngMuI ti castAnnouncement Utility ........... 62
`DL'.6.5.1 Overview ................................. 62
`
`
`
`DL'.6.5.2 Other Types ............................... 62
`DU.6.5.3 The Interface ............................... 63
`
`DL'.6.5.4 The Semantics ............................. 63
`
`DU.6.6 The Outgoi ngUni castRequest Utility .................. 64
`DU.6.6.1 Overview ................................. 64
`
`DU.6.6.2 Other Types ............................... 64
`
`5
`
`

`

`vi
`
`DU.6.6.3 The Interface .............................. 64
`
`DU.6.6.4 The Semantics ............................. 64
`
`DU.6.7 The Incomi ngUn1' castRequest Utility .................. 65
`DU.6.7.1 Overview ................................. 65
`
`DU.6.7.2 Other Types ............................... 65
`DU.6.7.3 The Interface .............................. 65
`
`DU.6.7.4 The Semantics ............................. 66
`
`DU.6.8 The Outgoi ngUn'i castResponse Utility ................. 66
`DU.6.8.1 Overview ................................. 66
`
`DU.6.8.2 Other Types ............................... 66
`DU.6.8.3 The Interface .............................. 67
`
`DU.6.8.4 The Semantics ............................. 67
`
`DU.6.9 The Incomi ngUn1' castResponse Utility ................. 68
`DU.6.9.1 Overview ................................. 68
`
`DU.6.9.2 Other Types ............................... 68
`DU.6.9.3 The Interface .............................. 68
`
`DU.6.9.4 The Semantics ............................. 68
`
`EU Jini Entry Utilities Specification ......................... 71
`
`EU.1 Entry Utilities .......................................... 71
`EU.1.1 AbstractEntry .................................... 71
`EU.1.2 Serialized Form ..................................... 72
`
`LM Jini Lease Utilities Specification ......................... 73
`
`LM.1 Introduction ............................................ 73
`
`LM.2 The LeaseRenewa'l Manager ............................. 75
`LM.2.1 Other Types ........................................ 76
`LM.3 The Interface ........................................... 77
`
`LM.4 The Semantics .......................................... 79
`
`LM.5 Supporting Interfaces and Classes ...................... 87
`LM.5.1 The LeaseL'i stener Interface ......................... 87
`
`LM.5.1.1 The Semantics ............................. 88
`
`LM.5.2 The Desi redExpi rationLi stener Interface ............. 88
`LM.5.2.1 The Semantics ............................. 89
`
`LM.5.3 The LeaseRenewal Event Class ........................ 89
`
`LM.5.3.1 The Semantics ............................. 90
`
`LM.5.4 Serialized Forms .................................... 91
`
`JU Jini Join Utilities Specification ........................... 93
`
`JU.1 Introduction ............................................ 93
`
`JU.2 The Jo-i nManager' ....................................... 95
`JU.2.1 Other Types ........................................ 96
`
`6
`
`

`

`vii
`
`JU.3 The Interface ........................................... 97
`
`JU.4 The Semantics .......................................... 99
`
`JU.5 Supporting Interfaces and Classes .................... 105
`JU.5.1 The D1' scove ryManagement Interface .................. 105
`IU.5.2 The Se rvi ceIDLi stener Interface .................... 106
`
`SD Jini Service Discovery Utilities Specification ......... 107
`
`SD.1 Introduction .......................................... 107
`
`SD.2 The Ser'V'i ceD'i scover'yManager' ...................... 109
`SD.2.1 The Object Types ................................... 111
`SD.3 The Interface ......................................... 113
`
`SD.4 The Semantics ........................................ 115
`SD.4.1 The Methods ...................................... 115
`
`SD.4.1.1 The Constructor ........................... 115
`
`SD.4.1.2 The createLookupCache Method ............. 116
`
`SD.4.1.3 The ‘Iookup Method ........................ 120
`
`SD.4.1.4 The getDi scove ryManager Method .......... 123
`
`SD.4.1.5 The getLeaseRenewa'l Manager Method ....... 124
`SD.4.1.6 The terminate Method ..................... 124
`
`SD.4.2 Defining Service Equality ............................ 125
`SD.4.3 Exporting RemoteEventL'i stener Objects .............. 126
`SD.5 Supporting Interfaces and Classes .................... 129
`SD.5.1 The Di scove ryManagement Interface .................. 129
`SD.5.2 The Se rvi ceItemFi 1 ter Interface .................... 130
`
`SD.5.2.1 The Semantics ............................ 131
`
`SD.5.3 The Se rV'i ceD'i scoveryEvent Class ................... 131
`SD.5.3.1 The Semantics ............................ 132
`
`SD.5.4 The Se rV'i ceD'i scoveryL'i stener Interface ............. 133
`SD.5.4.1 The Semantics ............................ 133
`
`SD.5.5 The LookupCache Interface .......................... 135
`SD.5.5.1 The Semantics ............................ 135
`
`LS Jini Lookup Attribute Schema Specification ......... 141
`
`LS.1 Introduction ........................................... 141
`
`LS.1.1 Terminology ...................................... 142
`LS.1.2 Design Issues ...................................... 142
`LS.1.3 Dependencies ...................................... 143
`LS.2 Human Access to Attributes .......................... 145
`
`L821 Providing a Single View of an Attribute’s Value .......... 145
`LS.3 JavaBeans Components and Design Patterns ......... 147
`L831 Allowing Display and Modification of Attributes .......... 147
`LS.3.1.1 Using JavaBeans Components with Entry Classes
`147
`
`7
`
`

`

`viii
`
`. 148
`.
`.
`LS.3.2 Associating JavaBeans Components with Entry Classes .
`LS.3.3 Supporting Interfaces and Classes ..................... 150
`LS.4 Generic Attribute Classes ............................. 151
`
`L841 Indicating User Modifiability ......................... 151
`LS.4.2 Basic Service Information ........................... 151
`
`LS.4.3 More Specific Information ........................... 153
`
`LS.4.4 Naming a Service .................................. 154
`LS.4.5 Adding a Comment to a Service ....................... 154
`LS.4.6 Physical Location .................................. 155
`LS.4.7 Status Information .................................. 156
`
`LS.4.8 Serialized Forms ................................... 157
`
`LD Jini Lookup Discovery Service ......................... 159
`
`LD.1 Introduction ........................................... 159
`
`LD.1.1 Goals and Requirements ............................. 162
`LD.1.2 Other Types ....................................... 162
`LD.2 The Interface .......................................... 163
`
`LD.3 The Semantics ......................................... 165
`
`LD.3.1 Registration Semantics .............................. 165
`LD.3.2 Event Semantics ................................... 168
`
`LD.3.3 Leasing Semantics ................................. 170
`LD.4 Supporting Interfaces and Classes ..................... 171
`LD.4.1 The LookupDi scove ryRegi st ration Interface .......... 171
`LD.4.1.1 The Semantics ............................ 173
`
`LD.4.2 The RemoteD‘i scove ryEvent Class .................... 180
`LD.4.2.1 The Semantics ............................ 182
`
`LD.4.2.2 Serialized Forms .......................... 184
`
`LD.4.3 The LookupUnmarshal Exception Class ............... 184
`LD.4.3.1 The Semantics ............................ 186
`
`LD.4.3.2 Serialized Forms .......................... 187
`
`LR Jini Lease Renewal Service Specification ............. 189
`
`LR.1 Introduction ........................................... 189
`
`LR.1.1 Goals and Requirements ............................ 190
`
`LR.1.2 Other Types ....................................... 191
`LR.2 The Interface .......................................... 193
`LR.2.1 Events ........................................... 200
`
`LR.2.2 Serialized Forms ................................... 204
`
`EM Jini Event Mailbox Service Specification ............. 205
`
`EM.1 Introduction ........................................... 205
`
`EM.1.1 Goals and Requirements ............................. 206
`
`8
`
`

`

`EM.1.2 Other Types ....................................... 206
`EM.2 The Interface ......................................... 207
`
`EM.3 The Semantics ........................................ 209
`
`EM.4 Supporting Interfaces and Classes .................... 211
`EM.4.1 The Semantics ..................................... 212
`
`ix
`
`9
`
`

`

`10
`
`10
`
`

`

`
`
`US
`
`
`
`Introduction to Helper
`Utilities and Services
`
`US.1 Summary
`
`WHEN developing clients and services that will participate in the application
`environment for JiniTM technology, there are a number of behaviors that the devel-
`oper may find desirable to incorporate in the client or service. Some of these
`behaviors may satisfy requirements described in the specifications of various Jini
`technology components; some behaviors may simply represent design practices
`that are desirable and should be encouraged. Examples of the sort of behavior that
`is required or desirable include the following:
`
`9 It is a requirement of the Jini discovery protocols that a service must con-
`tinue to listen for and act on announcements from lookup services in which
`the service has registered interest.
`
`9 It is a requirement of the Jini discovery protocols that, until successful, a ser-
`vice must continue to attempt to join the specific lookup services with which
`it has been configured to join.
`
`9 Under many conditions, a Jini technology-enabled client (Jim' client) or ser-
`vice will wish to regularly renew leases that it holds. For example, when a
`Jini technology-enabled service (Jim' service) registers with a Jini lookup
`service, the service is requesting residency in the lookup service. Residency
`in a lookup service is a leased resource. Thus, when the requested residency
`is granted, the lookup service also imposes a lease on that residency. Typi-
`cally, such a registered service will wish to extend the lease on its residency
`
`11
`
`11
`
`

`

`SUMMAR Y
`
`beyond the original expiration time, resulting in a need to renew the lease on
`a regular basis.
`
`9 Many Jini services will need to maintain a dormant (inactive) state, becom-
`ing active only when needed.
`
`9 Many Jini clients and services will need to have a mechanism for finding and
`managing Jini services.
`
`0 Many Jini clients and services will find it desirable to employ a separate ser-
`vice that will handle events, in some useful way, on behalf of the participant.
`
`To help simplify the process of developing clients and services for the appli-
`cation environment for Jini technology (Jini application environment), several
`specifications in this document collection define reusable components that encap-
`sulate behaviors such as those outlined above. Employing such utilities and ser-
`vices to build such desirable behavior into a Jini client or service can help to avoid
`poor design and implementation decisions, greatly simplifying the development
`process.
`
`What is presented first is terminology that may be helpful when analyzing
`these specifications. Following the section on terminology, brief summaries of the
`content of each of the current helper utilities and services specifications are pro-
`vided. Finally, the other specifications on which these specifications depend are
`listed for reference.
`
`12
`
`12
`
`

`

`INTRODUCTION TO HELPER UTILITIES AND SERVICES, version 1.1
`
`3
`
`
`
`
`US.2 Terminology
`
`THIS section defines terms and discusses concepts that may be referenced
`throughout the helper utilities and services specifications. While the terms and
`concepts that appear in this section are general in nature and may apply to multi-
`ple components specified in this collection, each specification may define addi-
`tional terms and concepts to further facilitate the understanding of a particular
`component. Each specification may also present supplemental information about
`some of the terms defined in this section and their relationship with the compo-
`nent being specified.
`Because this document makes use of a number of terms defined in the “JiniTM
`
`Technology Glossary”, reviewing the glossary is recommended. A number of the
`terms defined in the glossary are also defined in this section to provide easy refer-
`ence because those terms are used extensively in the helper utilities and services
`specifications. Additionally, this section augments the definitions of some of the
`terms from the glossary with details relevant to those specifications.
`In addition to the glossary, the JiniTM Technology Core Platform Specification
`(referred to as the core specification) presents detailed definitions of a number of
`terms and concepts appearing both in this section and throughout the helper utili-
`ties and services specifications. When appropriate, the relevant specification will
`be referenced.
`
`US.2.1 Terms Related to Discovery and Join
`
`The Jini Technology Core Platform Specification, “Discovery and Join ”, defines a
`discovering entity as one or more cooperating software objects written in the
`JavaTM programming language (Java software objects), executing on the same
`host, that are in the process of obtaining references to Jini lookup services. That
`specification also defines a joining entity as one or more cooperating Java soft-
`ware objects, on the same host, that have received a reference to a lookup service
`and are in the process of obtaining services from, and possibly exporting services
`to, a federation of Jini technology-enabled services and/or devices and Jini lookup
`services referred to as a aj'inn. The lookup services comprising a djinn may be
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`13
`
`13
`
`

`

`TERMINOLOGY
`
`organized into one or more sets known as groups. Multiple groups may or may not
`be disjoint. Each group of lookup services is identified by a logical name repre-
`sented by a St ri ng object.
`The Jini Technology Core Platform Specification, “Discovery and Join”
`defines two protocols used in the discovery process: the multicast discovery proto-
`col and the unicast discovery protocol.
`When a discovering entity employs the multicast discovery protocol to dis-
`cover lookup services that are members of one or more groups belonging to a set
`of groups, that discovery process is referred to as group discovery.
`The utility class net.j1'n1' .core.d1' scovery. LookupLocator is defined in
`The Jini Technology Core Platform Specification, “Discovery and Join”. Any
`instance of that class is referred to as a locator. When a discovering entity
`employs the unicast discovery protocol to discover specific lookup services, each
`corresponding to an element in a set of locators, that discovery process is referred
`to as locator discovery.
`
`US.2.2
`
`Jini Clients and Services
`
`For the purposes of the helper utilities and services specifications, a Jini client is
`defined as a discovering entity that can retrieve a service (or a remote reference to
`a service) registered with a discovered lookup service and invoke the methods of
`the service to meet the entity’s requirements. An entity that acts only as a client
`never registers with (requests residency in) a lookup service.
`A Jini service is defined as both a discovering and a joining entity containing
`methods that may be of use to some other Jini client or service, and which regis-
`ters with discovered lookup services to provide access to those methods. Note that
`a Jini service can also act as a Jini client.
`
`The term client-like entity may be used, in general, when referring to Jini cli-
`ents and Jini services that act as clients.
`
`Note that when the term entity is used, that term may be referring to a discov-
`ering entity, a joining entity, a client-like entity, a service, or some combination of
`these types of entities. Whenever that general term is used, it should be clear from
`the context what type of entity is being discussed.
`
`US.2.3 Helper Service
`
`A Jini technology-enabled helper service is defined in this document as an inter-
`face or set of interfaces, with an associated implementation, that encapsulates
`behavior that is either required or highly desirable in service entities that adhere to
`
`14
`
`14
`
`

`

`INTRODUCTION TO HELPER UTILITIES AND SERVICES, version 1.1
`
`the Jini technology programming model (or simply the Jini programming model).
`A helper service is a Jini service that can be registered with any number of lookup
`services and whose methods can execute on remote hosts.
`
`In general, a helper service should be of use to more than one type of entity
`participating in the Jini application environment and should provide a significant
`reduction in development complexity for developers of such entities.
`
`US.2.4 Helper Utility
`
`This document distinguishes between a helper utility and a helper service. Helper
`utilities are programming components that can be used during the construction of
`Jini services and/or clients. Helper utilities are not remote and do not register with
`a lookup service. Helper utilities are instantiated locally by entities wishing to
`employ them.
`
`US.2.5 Managed Sets
`
`When performing discovery duties, entities will often maintain references to dis-
`covered lookup services in a set referred to as the managed set of lookup services.
`The entity may also maintain two other notable sets: the managed set of groups
`and the managed set aflocators.
`Each element of the managed set of groups is a name of a group whose mem-
`bers are lookup services that the entity wishes to be discovered via group discov-
`ery. The managed set of groups is typically represented as a String array, or a
`Co11ect1'on of Stri ng elements.
`
`Each element of the managed set of locators corresponds to a specific lookup
`service that the entity wishes to be discovered Via locator discovery. Typically, this
`set is represented as an array of net .j1'n1' .core . d1' scove ry. LookupLocator
`objects or some other C01 1 ecti on type whose elements are LookupLocator
`objects.
`Note that when the general term managed set is used, it should be clear from
`the context whether groups, locators, or lookup services are being discussed.
`
`US.2.6 What Exceptions Imply about Future Behavior
`
`When interacting with a remote object, an entity may call methods that result in
`exceptions. The specification of those methods should define what each possible
`exception implies (if anything) about the current state of the object. One important
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`15
`
`15
`
`

`

`TERMINOLOGY
`
`aspect of an object’s state is whether or not fiirther interactions with the object are
`likely to be fruitfiJl. Throughout the helper utilities and services specifications, the
`following general terms may be used to classify what a given exception implies
`about the probability of success of future operations on the object that threw the
`exception:
`
`0 Bad object exception: If a method invocation on an object throws a bad
`object exception, it can be assumed that any further operations on that object
`will also fail.
`
`9 Bad invocation exception: If a method invocation on an object throws a bad
`invocation exception, it can be assumed that any retries of the same method
`with the same arguments that are expected to return the same value will also
`fail. No new assertions can be made about the probability of success of any
`future invocation of that method with different arguments or if a different
`return value is expected, nor can any new assertions be made about the prob-
`ability of success of invocations of the object’s other methods.
`
`0 Indefinite exception: If a method invocation on an object throws an indefinite
`exception, no new assertions can be made about the probability of success of
`any future invocation of that method, regardless of the arguments used or
`return value expected, nor can any new assertions be made about the proba-
`bility of success of any other operation on the same object.
`
`Unless otherwise noted, the throwing of a bad object, bad invocation, or indef-
`inite exception by one object does not imply anything about the state of another
`object, even if both objects are associated with the same remote entity.
`These terms can be used in the specification of a method to describe the mean-
`ing of exceptions that might be thrown, as well as in the specification of what a
`given utility or service will, may, or should do when it receives an exception in the
`course of interacting with a given object.
`If a specification does not say otherwise, the following classification is used to
`categorize each RuntimeException, Error, or java. rmi .RemoteExceptions as
`a bad object, bad invocation, or indefinite exception:
`
`0 Bad object exceptions:
`
`' Any java. 1ang . Runt‘imeExcepti on
`
`‘ Any java. 1ang . Error except one that is a java. 1 ang . L1' nkageError or
`
`java. 1 ang .OutOfMemoryError
`
`‘ Any java. rm1' .NoSuchObjectExcepti on
`
`16
`
`16
`
`

`

`INTRODUCTION TO HELPER UTILITIES AND SERVICES, version 1.1
`
`7
`
`a Any java. rm1' .Ser‘verEr‘ror‘ with a detail field that is a bad object
`exception
`
`‘ Any java. rmi . Se rverExcepti on with a detail field that is a bad object
`exception
`
`9 Bad invocation exceptions:
`
`‘ Any java.rmi.MarshalException with a detail
`
`field that
`
`is a
`
`java.1'o.0bjectStreamExcept1'on
`
`‘ Any java.rmi.Unmarsha1 Exception with a detail
`
`field that
`
`is a
`
`java.1'o.0bjectStreamExcept1'on
`
`‘ Any java. rmi . Se rverExcepti on with a detail field that is a bad invo-
`cation exception
`
`9 Indefinite exceptions
`
`‘ Any java.1ang.0utOfMemoryError
`
`' Any java.1ang . L1' nkageError
`
`' Any java. rm1' .RemoteException except those that can be classified as
`either a bad invocation or bad object exception
`
`US.2.7 Unavailable Lookup Services
`
`While interacting (or attempting to interact) with a lookup service, an entity may
`encounter one of the exception types described in the previous section. When the
`entity does receive such an exception, what may be concluded about the state of
`the lookup service is dependent on the type of exception encountered.
`If an entity encounters a bad object exception while interacting with a lookup
`service, the entity can usually conclude that the associated proxy it holds can no
`longer be used to interact with the lookup service. This can be due to any number
`of reasons. For example, if the lookup service is administratively destroyed, the
`old proxy will never be capable of communicating with any new incarnations of
`the lookup service, allowing the entity to dispose of the old proxy since it is no
`longer of any use to the entity.
`If an indefinite exception occurs while interacting with a lookup service, the
`entity can interpret such an occurrence as a communication failure that may or
`may not be only temporary.
`Finally, entities that encounter a bad invocation exception while interacting
`with a lookup service should view the lookup service as being in an unknown,
`
`A COLLECTION OF JINITM TECHNOLOGY HELPER UTILITIES AND SER VICES SPECIFICA TIONS
`
`17
`
`17
`
`

`

`TERMINOLOGY
`
`possibly corrupt state, and should discontinue further interaction with that lookup
`service until the problem is resolved.
`Whenever an entity receives any of these exceptions while interacting with a
`lookup service,
`the affected lookup service is referred to as unavailable or
`unreachable. For most entities the unavailability of a particular lookup service
`should not prevent the entity from continuing its processing, although in other sit-
`uations an entity might consider at least some of these exceptional conditions
`unrecoverable. In general, when an entity encounters an unreachable lookup ser-
`vice, the exception or error indicating that the lookup service is unavailable should
`be caught and handled, usually by requesting