INIT
`
`A Collection of Jini™
`Technology Helper
`Utilities and Services
`Specifications
`
`This Collection of Jini™ Technology Helper Utilities and
`Services Specifications definesaset ofstandard helper utilities
`and services which extendthe Jini Technology Core Platform.
`These helper utilities and services encapsulate desirable
`behaviorsin the form ofa set ofreusable componentsthat can be
`used to help simplify the process ofdeveloping Jini technology-
`enabled clients and services (Jini clients andservices) forthe Jini
`technology application environment. Employingtheseutilities
`andservices to build such desirable behaviorinto a Jini client or
`service can help to avoid poor design and implementation
`decisions, greatly simplifying the developmentprocess.
`
`Ss&Sun
`
`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 U.S. or other countries. Your limited right to use this publication does not grant you any
`right or license to Sun IPR noranyright 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 ............. 0... ees 1
`US.2 Terminology ...................0 0.00 cece eee 3
`US.2.1 Terms Related to Discovery and Join .................04.. 3
`US.2.2 Jini Clients and Services .......... 0... c cece cece nee 4
`US.2.3 Helper Service ......... 0... cece cece tenes 4
`US.2.4 Helper Utility... 0... cee ene 5
`US.2.5 Managed Sets... 00... cee cence teens 5
`US.2.6 What Exceptions Imply about Future Behavior ............. 5
`US.2.7 Unavailable Lookup Services ............. 000s eee eens 7
`US.2.8 Discarding a Lookup Service ........... 0... c eee eee eee 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 ....... 0.0... 00. cece eee ee eee 10
`US.2.8.6 Remote Objects, Stubs, and Proxies............. 10
`US.2.9 Activation 2.0... . 0... ccc ccc en ene nes 12
`US.3 Introduction to the Helper Utilities ..................... 13
`US.3.1 The Discovery Utilities ....... 0.0.0... cece eee eee 13
`US.3.1.1
`The DiscoveryManagement Interface .......... 14
`US.3.1.2. The DiscoveryGroupManagement Interface ..... 14
`US.3.1.3. The DiscoveryLocatorManagement Interface ... 14
`US.3.1.4 The LookupDiscovery Helper Utility .......... 14
`US.3.1.5 The LookupLocatorDiscovery HelperUtility ... 15
`US.3.1.6 The LookupDiscoveryManager Helper Utility ... 15
`US.3.1.7 The Constants Class .......... 0.0.00 ce eens 15
`US.3.1.8 The OutgoingMulticastRequest Utility ....... 15
`US.3.1.9 The IncomingMulticastRequest Utility ....... 15
`US.3.1.10 The OutgoingMulticastAnnouncement Utility .. 16
`
`3
`
`

`

`iv
`
` US.3.1.11 The IncomingMulticastAnnouncement Utility . 16
`
`US.3.1.12 The OutgoingUnicastRequest Utility ........ 16
`US.3.1.13. The IncomingUnicastRequest Utility ........ 16
`US.3.1.14 The OutgoingUnicastResponse Utility ....... 16
`US.3.1.15 The IncomingUnicastResponse Utility ....... 16
`US.3.2 The Lease Utilities 2.0.0... cc eee 17
`US.3.2.1
`The LeaseRenewalManager HelperUtility ...... 17
`US.3.3. The Join Utilities 0.0.0... eens 17
`US.3.3.1.
`The JoinManager Helper Utility .............. 17
`US.3.4 The Service Discovery Utilities ................ 0000000 18
`US.3.4.1
`The ServiceDiscoveryManager Helper Utility..
`18
`US.4 Introduction to the Helper Services ..................... 19
`US.4.1 The Lookup Discovery Service .............. 000 eee ee 19
`US.4.2 The Lease Renewal Service ........... 0. cece eee 19
`US.4.3. The Event Mailbox Service ......... 0.0.00 cece eee eens 20
`US.5 Dependencies ..................0... 21
`
`DU Jini Discovery Utilities Specification .................... 23
`DU.1 Introduction ................ 0000. 23
`DU.1.1 Dependencies ......... 0.0... cette 23
`DU.2 The Discovery ManagementInterfaces ................. 25
`DU.2.1 Overview .. 0... eee e ete 25
`DU.2.2 Other Types ....... 0... cece cece een eae 26
`DU.2.3 The DiscoveryManagement Interface ..................0. 27
`DU.2.3.1 The Semantics .......... 0.0.0 cece cece 27
`DU.2.4 The DiscoveryGroupManagement Interface .............. 30
`DU.2.4.1 The Semantics ......... 0.0.0.0 ccc eee ences 30
`DU.2.5 The DiscoveryLocatorManagement Interface ............ 32
`DU.2.5.1 The Semantics .......... 00.0 eee 33
`DU.2.6 Supporting Interfaces and Classes .............. 00000 34
`DU.2.6.1 The DiscoveryListener Interface ............ 34
`DU.2.6.2 The DiscoveryChangeListener Interface ...... 35
`DU.2.6.3 The DiscoveryEvent Class .................. 36
`DU.2.7 Serialized Forms .......... 0.00 eee eens 38
`DU.3 LookupDiscovery Utility ...........................000. 39
`DU.3.1 Other Types ........ 0. ccc ccc cen e ence 39
`DU.3.2 The Interface .... 0... cc en eens 40
`DU.3.3 The Semantics ......... 00... cette eens 40
`DU.3.4 Supporting Interfaces and Classes .................00005 4l
`DU.3.4.1 The DiscoveryManagement Interfaces ......... Al
`DU.3.4.2 Security and Multicast Discovery: The
`42
`DiscoveryPermission Class
`DU.3.5 Serialized Forms ......... 0.0... c cece cece eee 43
`
`4
`
`

`

`DU.S5
`
`DU.6
`
`DU.4 The LookupLocatorDiscovery Utility .................. 45
`DU.4.1 Overview 2.0.0... cee een e ene nnees 45
`DU.4.2 Other Types ....... 0... ccc cece eee eens 46
`DU.4.3 The Interface 2.0.0.0... 0. cece eens 46
`DU.4.4 The Semantics ...... 0.0.0... ccc cc cece teens 47
`DU.4.5 Supporting Interfaces ........ 0.0... . cece eee 48
`DU.4.5.1 The DiscoveryManagement Interfaces .......... 48
`The LookupDiscoveryManager Utility .................. 49
`DU.5.1 Overview .. 0.0... ccc eee nent n eens 49
`DU.5.2 Other Types ...... 0.0.0.0 ccc cece eee eens 49
`DU.5.3 The Interface .... 0.0... ce cence eens 50
`DU.5.4 The Semantics ....... 0.0... ccc eee 50
`DU.5.5 Supporting Interfaces and Classes ............. 00.0000 53
`DU.5.5.1 The DiscoveryManagement Interfaces .......... 53
`DU.5.5.2 Security and Multicast Discovery: The
`53
`DiscoveryPermission Class
`Low-Level Discovery Protocol Utilities .................. 55
`DU.6.1 The Constants Class ...... 0.0... ccc ccc ce tenes 55
`DU.6.1.1 Overview .... 0.00... ccc nnn ene 55
`DU.6.1.2 Other Types ...... 0.0... ee eee eee ee 55
`DU.6.1.3 The Class Definition .............. 00.00.0000) 56
`DU.6.1.4 The Semantics ....... 0.0.0... cc cece eee eee 56
`DU.6.2 The OutgoingMulticastRequest Utility ................ 57
`DU.6.2.1 Overview ..... 0... ccc cece 57
`DU.6.2.2 Other Types ...... 0.0... cece cece eens 57
`DU.6.2.3. The Interface... 0.0... cc eee 57
`DU.6.2.4 The Semantics ....... 0.0... cc cee cece eee 58
`DU.6.3. The IncomingMulticastRequest Utility ................ 58
`DU.6.3.1 Overview ...... 0... eens 58
`DU.6.3.2 Other Types ...... 0... cc eee cece eee 59
`DU.6.3.3 The Interface... 0.0... 0. cee 59
`DU.6.3.4 The Semantics ....... 0.0... ccc cece eee eee 59
`DU.6.4 The OutgoingMulticastAnnouncement Utility ........... 60
`DU.6.4.1 Overview ..... 0... ccc cect eens 60
`DU.6.4.2 Other Types ...... 0.0... ccc eee 60
`DU.6.4.3 The Interface... 0.0.0... cc eee 61
`DU.6.4.4 The Semantics ....... 0.0... cc cece eee eee 61
`DU.6.5 The IncomingMulticastAnnouncement Utility ........... 62
`DU.6.5.1 Overview ...... 00.0 cece ne 62
`DU.6.5.2 Other Types ...... 0.0... ccc eens 62
`DU.6.5.3. The Interface... 0.0... 63
`DU.6.5.4 The Semantics ....... 0.0... cc ccc cee eee eee 63
`DU.6.6 The OutgoingUnicastRequest Utility .................. 64
`DU.6.6.1 Overview ..... 0... ccc cee eens 64
`DU.6.6.2 Other Types ...... 0... cc eee eee eee 64
`
`
`
`5
`
`

`

`vi
`
`DU.6.6.3 The Interface ........ 0.0.0.0. eee 64
`DU.6.6.4 The Semantics ...... 0.0.0.0... cece eee ee 64
`DU.6.7 The IncomingUnicastRequest Utility .................. 65
`DU.6.7.1 Overview 0.0... cece 65
`DU.6.7.2 Other Types .. 0.0.0.0... cece eens 65
`DU.6.7.3 The Interface ....... 0.0... cc eee 65
`DU.6.7.4 The Semantics ....... 0.0.0.0... cece eee ee 66
`DU.6.8 The OutgoingUnicastResponse Utility ................. 66
`DU.6.8.1 Overview ..... 0.00. ce eens 66
`DU.6.8.2 Other Types ....... 20.0... cece ence eee 66
`DU.6.8.3 The Interface ........ 0.0.0.0. ccc ce ee 67
`DU.6.8.4 The Semantics ......... 0.0.00. e ccc eee ee 67
`DU.6.9 The IncomingUnicastResponse Utility................. 68
`DU.6.9.1 Overview .... 0.0.00. ccc eee ences 68
`DU.6.9.2 Other Types ...... 0.0... ccc cc eee 68
`DU.6.9.3 The Interface .... 0.0.0... ce eee 68
`DU.6.9.4 The Semantics ....... 0.0.00... c cece eee 68
`
`EU Jini Entry Utilities Specification ......................... 71
`EU.1 Entry Utilities .......0..00..0 0000s 71
`EU.1.1 AbstractEntry ...... 0.0.0... ccc cee eee 71
`EU.1.2 Serialized Form .. 0.0... ee een eens 72
`
`LM Jini Lease Utilities Specification ......................... 73
`LM.1 Introduction ................. 000000 73
`LM.2 The LeaseRenewalManager .........................00.. 75
`LM.2.1 Other Types ......... 0... cece eects 76
`LM.3 The Interface .............0.0.0. 77
`LM.4 The Semantics ............0.0 0000000 79
`LM.5 Supporting Interfaces and Classes ...................... 87
`LM.5.1 The LeaseListener Interface .......... 0.0.0... c ce eee 87
`LM.5.1.1 The Semantics ........ 0.0.0.0... 0. cece eee eee 88
`LM.5.2 The DesiredExpirationListener Interface............. 88
`LM.5.2.1 The Semantics ......... 0.0... e cece eee eee 89
`LM.5.3 The LeaseRenewalEvent Class............. 0.000000 eee 89
`LM.5.3.1 The Semantics ......... 0.0... e cece eee ee 90
`LM.5.4 Serialized Forms ....... 0.0... 0c ccc teens 91
`
`JU Jini Join Utilities Specification ........................... 93
`JU.1 Introduction ............00. 0.00.00 93
`JU.2 The JoinManager ................0. 0.0.0. 95
`JU.2.1 Other Types .... 2.0... cee ccc eee eens 96
`
`6
`
`

`

`Vii
`
`JU.3 The Interface .............. 0... ccc ccc een 97
`JU.4 The Semantics ............... 0... en 99
`JU.5 Supporting Interfaces and Classes .................... 105
`JU.5.1 The DiscoveryManagement Interface .................. 105
`JU.5.2. The ServiceIDListener Interface .................... 106
`
`SD Jini Service Discovery Utilities Specification ......... 107
`SD.1 Introduction ................. 00.0. 107
`SD.2. The ServiceDiscoveryManager ...................... 109
`SD.2.1 The Object Types... 0.0.0.0... cc cece cece eens 111
`SD.3. The Interface ..............0.0 0.0... ccc ccna 113
`SD.4 The Semantics ................ 0.0.0.0 115
`SD.4.1 The Methods ....... 0... 0c ccc ccc ete 115
`SD.4.1.1. The Constructor ....... 0.0.0.0... cece eee eee 115
`SD.4.1.2 The createLookupCache Method............. 116
`SD.4.1.3. The lookup Method ....................008. 120
`SD.4.1.4 The getDiscoveryManager Method .......... 123
`SD.4.1.5 The getLeaseRenewalManager Method ....... 124
`SD.4.1.6 The terminate Method...................5. 124
`SD.4.2 Defining Service Equality .......... 0.0... cee eee eee 125
`SD.4.3 Exporting RemoteEventListener Objects .............. 126
`SD.5 Supporting Interfaces and Classes .................... 129
`SD.5.1 The DiscoveryManagement Interface .................. 129
`SD.5.2. The ServiceItemFilter Interface .................0.. 130
`
`SD.5.2.1 The Semantics ........ 0.0.0.0 ccc ee eee eee 131
`SD.5.3 The ServiceDiscoveryEvent Class ...............008. 131
`SD.5.3.1 The Semantics ......... 0.0.0.0. e ee eee eee 132
`SD.5.4. The ServiceDiscoveryListener Interface ............. 133
`SD.5.4.1 The Semantics ........... 00... e cece eens 133
`SD.5.5 The LookupCache Interface .............. 0... .0000 0085 135
`SD.5.5.1 The Semantics .......... 0.00. c cece cee eee 135
`
`LS Jini Lookup Attribute SchemaSpecification ......... 141
`LS.1 Introduction. ...............00 0.0.0. c ccc cece aes 141
`LS.1.1 Terminology ........ 0.0... cece cece een eens 142
`LS.1.2 Design Issues ...... 0... 0. cece ccc eens 142
`LS.1.3. Dependencies ........ 0.0.00 cece cee eee eens 143
`LS.2. HumanAccess to Attributes .......................... 145
`LS.2.1 Providing a Single View of an Attribute’s Value .......... 145
`JavaBeans Components and Design Patterns ......... 147
`LS.3.1 Allowing Display and Modification of Attributes .......... 147
`LS.3.1.1 Using JavaBeans Components with Entry Classes
`147
`
`LS.3.
`
`7
`
`

`

`Viii
`
`LS.3.2 Associating JavaBeans Components with Entry Classes .... 148
`LS.3.3 Supporting Interfaces and Classes
`...............000005 150
`LS.4 Generic Attribute Classes ............................. 151
`LS.4.1
`Indicating User Modifiability ....................0.005 151
`LS.4.2 Basic Service Information ............ 0.0.0.0. cee eee 151
`LS.4.3 More Specific Information .................. 00 eee eee 153
`LS.4.4 Naminga Service ........... cece cee eee een ees 154
`LS.4.5 Adding a Comment to a Service ............ 02.000 ee eee 154
`LS.4.6 Physical Location ............ 0.0 cee cece eee eee eee 155
`LS.4.7 Status Information..........0. 0.0.00 ccc cece eee 156
`LS.4.8 Serialized Forms .........0.. 00.0. eens 157
`
`LD Jini Lookup Discovery Service ......................... 159
`LD.1 Introduction ...............0.. 000000 c ccc eee es 159
`LD.1.1 Goals and Requirements ............. 00.0 c eee eee eee 162
`LD.1.2 Other Types ......... 0... cece cee eee ene eee 162
`LD.2 The Interface ................ 0.000 163
`LD.3 The Semantics ..............0000 000.00 165
`LD.3.1 Registration Semantics ........ 0.0.0... cece eee eee eee 165
`LD.3.2 Event Semantics ........ 0.0.00 c ccc eee eens 168
`LD.3.3 Leasing Semantics ......... 00... c ccc eee ences 170
`LD.4 Supporting Interfaces and Classes ..................... 171
`LD.4.1 The LookupDiscoveryRegistration Interface .......... 171
`LD.4.1.1 The Semantics ...........0 0.0. ccc cece eee 173
`LD.4.2 The RemoteDiscoveryEvent Class...............00005 180
`LD.4.2.1 The Semantics ........... 00... 00 cee eee eee 182
`LD.4.2.2 Serialized Forms .......... 0.0.00. ce cee eee 184
`LD.4.3. The LookupUnmarshalException Class ............... 184
`LD.4.3.1 The Semantics ........... 000.000 cee eee ee 186
`LD.4.3.2 Serialized Forms .......... 0.0.00. cece eens 187
`
`LR Jini Lease RenewalService Specification ............. 189
`LR.1 Introduction ................0000 00... 189
`LR.1.1 Goals and Requirements ............... 00 cece eee eee 190
`LR.1.2 Other Types .... 0.0... cece eee ees 191
`LR.2 The Interface ................. 000000 193
`LR.2.1 Events 0.0.0.0... ccc ete e eee n ees 200
`LR.2.2 Serialized Forms ....... 0.0... 0c ccc cee eee 204
`
`EM Jini Event Mailbox Service Specification ............. 205
`EM.1 Introduction .................000 00... ccc eee ees 205
`EM.1.1 Goals and Requirements ........... 0.0.0. e cece eee eee 206
`
`8
`
`

`

`EM.1.2 Other Types ........ 0... c ccc cece eens 206
`EM.2 The Interface ...............00.0 0... c ccc cece nae 207
`EM.3 The Semantics ...............0 00... cece cece eens 209
`EM.4 Supporting Interfaces and Classes .................... 211
`EM.4.1 The Semantics ......... 00... c cece cece een enn 212
`
`ix
`
`9
`
`

`

`10
`
`

`

`
`
`
`US
`
`Introduction to Helper
`Utilities and Services
`
`US.1 Summary
`
`Warn developing clients and services that will participate in the application
`environmentfor Jini™ technology, there are a numberof 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. Examplesof the sort of behavior that
`is required or desirable include the following:
`
`@ It is a requirementof the Jini discovery protocols that a service must con-
`tinue to listen for and act on announcements from lookup services in which
`the service hasregistered interest.
`It is arequirementofthe Jini discovery protocolsthat, until successful, a ser-
`vice must continue to attempt to join the specific lookup services with which
`it has been configuredto join.
`@ Under many conditions, a Jini technology-enabled client (Jini client) or ser-
`vice will wish to regularly renew leases that it holds. For example, when a
`Jini technology-enabled service (Jini service) registers with a Jini lookup
`service, the service is requesting residency in the lookup service. Residency
`in a lookupservice is a leased resource. Thus, when the requested residency
`is granted, the lookup service also imposesa lease on that residency. Typi-
`cally, such a registered service will wish to extend the lease on its residency
`
`11
`
`

`

`SUMMARY
`
`beyondthe original expiration time, resulting in a need to renew the lease on
`a regularbasis.
`@ Many Jini services will need to maintain a dormant(inactive) state, becom-
`ing active only when needed.
`@ ManyJini clients and services will need to have a mechanism for finding and
`managing Jini services.
`@ 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 documentcollection define reusable components that encap-
`sulate behaviors such as those outlined above. Employing such utilities and ser-
`vices to build such desirable behaviorinto 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
`
`

`

`INTRODUCTION TO HELPER UTILITIES AND SERVICES, version 1.1
`
`3
`
`
`
`
`US.2. Terminology
`
`Tus 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 makesuse of a numberof terms defined in the “Jini™
`Technology Glossary”, reviewing the glossary is recommended. A numberofthe
`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 Jini™ 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 helperutili-
`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
`Java™ 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 djinn. The lookupservices comprising a djinn may be
`
`A COLLECTION OF JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`13
`
`

`

`TERMINOLOGY
`
`organized into one or more sets known as groups. Multiple groups may or may not
`be disjoint. Each group of lookup servicesis identified by a logical name repre-
`sented by a String object.
`The Jini Technology Core Platform Specification, “Discovery and Join”
`defines two protocols used in the discovery process: the multicast discoveryproto-
`col and the unicast discovery protocol.
`Whena 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 processis referred to as group discovery.
`The utility class net. jini.core.discovery.LookupLocator is defined in
`The Jini Technology Core Platform Specification, “Discovery and Join”. Any
`instance of that class is referred to as a Jocator. When a discovering entity
`employs the unicast discovery protocol to discover specific lookup services, each
`corresponding to an elementin a set of locators, that discovery processis 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 lookupservice.
`A Jini service is defined as both a discovering and a joining entity containing
`methods that may be of use to someother Jini client or service, and whichregis-
`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, whenreferring to Jini cli-
`ents and Jini servicesthat act as clients.
`Note that when the term entity is used, that term maybereferring to a discov-
`ering entity, a joining entity, a client-like entity, a service, or some combination of
`these types of entities. Wheneverthat general term is used, it should be clear from
`the context whattype of entity is being discussed.
`
`US.2.3 Helper Service
`
`A Jini technology-enabled helper service is defined in this documentas an inter-
`face or set of interfaces, with an associated implementation, that encapsulates
`behaviorthat is either required or highly desirable in service entities that adhere to
`
`14
`
`

`

`INTRODUCTION TO HELPER UTILITIES AND SERVICES, version 1.1
`
`5
`
`the Jini technology programming model(or simply the Jini programming model).
`A helperserviceis a Jini service that can be registered with any numberof 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 documentdistinguishes betweena helperutility and a helper service. Helper
`utilities are programming components that can be used during the construction of
`Jini services and/orclients. 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 ManagedSets
`
`Whenperforming discovery duties, entities will often maintain referencesto dis-
`covered lookup services in a set referred to as the managedset oflookup services.
`The entity may also maintain two other notable sets: the managed set ofgroups
`and the managedset oflocators.
`Each element of the managedset of groupsis a name of a group whose mem-
`bers are lookupservices that the entity wishes to be discovered via group discov-
`ery. The managed set of groupsis typically represented as a String array, or a
`Collection of String elements.
`Each element of the managed set of locators correspondsto a specific lookup
`service that the entity wishes to be discoveredvia locator discovery. Typically, this
`set is represented as an array of net.jini.core.discovery.LookupLocator
`objects or some other Collection type whose elements are LookupLocator
`objects.
`Note that when the general term managedsetis 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
`
`Wheninteracting with a remote object, an entity may call methodsthat 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 JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`15
`
`

`

`TERMINOLOGY
`
`aspect of an object’s state is whether or not further interactions with the object are
`likely to be fruitful. Throughoutthe helper utilities and services specifications, the
`following general terms may be usedto classify what a given exception implies
`about the probability of success of future operations on the object that threw the
`exception:
`
`@ Bad object exception: If a method invocation on an object throws a bad
`object exception, it can be assumedthat any further operations on that object
`will also fail.
`
`@ Bad invocation exception: If a method invocation on an object throws a bad
`invocation exception, it can be assumedthat any retries of the same method
`with the same argumentsthat are expected to return the samevalue will also
`fail. No new assertions can be madeaboutthe 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 aboutthe prob-
`ability of success of invocations of the object’s other methods.
`Indefinite exception: If a method invocation on an object throwsan indefinite
`exception, no new assertions can be madeaboutthe probability of success of
`any future invocation of that method, regardless of the arguments used or
`return value expected, nor can any newassertions be made aboutthe 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 remoteentity.
`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 whenit 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:
`
`@ Bad object exceptions:
`
`¢« Any java.lang.RuntimeException
`+ Any java.lang.Error except onethat is a java. lang.LinkageError or
`java. lang.OutOfMemoryError
`
`¢ Any java.rmi.NoSuchObjectException
`
`16
`
`

`

`INTRODUCTION TO HELPER UTILITIES AND SERVICES, version 1.1
`
`7
`
`¢ Any java.rmi.ServerError with a detail field that is a bad object
`exception
`+ Any java.rmi.ServerException with a detai1 field that is a bad object
`exception
`
`@ Bad invocation exceptions:
`¢ Any java.rmi.MarshalException with a detail
`java.io.ObjectStreamException
`
`field that
`
`is a
`
`¢ Any java.rmi.UnmarshalException with a detail
`java.io.ObjectStreamException
`
`field that
`
`is a
`
`¢ Any java.rmi.ServerException with a detai1 field that is a bad invo-
`cation exception
`
`@ Indefinite exceptions
`
`¢« Any java.lang.OutOfMemoryError
`
`¢ Any java.lang.LinkageError
`¢ Any java.rmi.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 aboutthe 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 usetothe entity.
`If an indefinite exception occurs while interacting with a lookupservice, the
`entity can interpret such an occurrence as a communication failure that may or
`maynot 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 JINI™ TECHNOLOGYHELPER UTILITIES AND SERVICES SPECIFICATIONS
`
`17
`
`

`

`TERMINOLOGY
`
`possibly corrupt state, and should discontinue further interaction with that lookup
`service until the problem is resolved.
`Wheneveran 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 othersit-
`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 exceptionor error indicating that the lookup service is unavailable should
`be caught and handled, usually by requesting that the lookup service be discarded
`(see the next section), and the entity should continue its processing.
`
`US.2.8 Discarding a Lookup Service
`
`Whenan already discovered lookup service is removed from the managedset of
`lookupservices,it is said to be discarded. The processof discarding a lookupser-
`vice is initiated either directly or indirectly by the discovering entity itself or by
`the utility that the entity employs to perform the actual discovery duties.
`Whenevera lookup service is discarded by a utility employed bythe entity,
`the utility sendsto all of the entity’s discovery listeners, a notification event refer-
`encing both the discarded lookup service and the member groups to which the
`lookup service belongs. This event is referred to as a discarded event. It may be
`useful to note that discarded events can beclassified by two characteristics:
`
`@ Whether the event was generated as a direct consequence of an explicit
`request madebytheentity itself (active) or as a consequenceof a determi-
`nation made by someutility employed by the entity (passive)
`@ Whether the event is related to communication problemsorto the entity los-
`ing interest in discovering the affected lookup services
`
`US.2.8.1 Active Communication Discarded Event
`
`Whenthe occurrence of exceptional conditions causes an entity to concludethat a
`lookup service is unreachable, the entity typically will request that the lookup ser-
`vice be discarded. Whentheentity itself requests that such an unreachable lookup
`service be discarded, the resulting discarded event may bereferred to as an