You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@river.apache.org by th...@apache.org on 2010/12/08 17:56:50 UTC
svn commit: r1043519 -
/incubator/river/site/trunk/content/river/docs/specs/discovery-spec.mdtext
Author: thobbs
Date: Wed Dec 8 16:56:49 2010
New Revision: 1043519
URL: http://svn.apache.org/viewvc?rev=1043519&view=rev
Log:
Changed page to mdtext format
Modified:
incubator/river/site/trunk/content/river/docs/specs/discovery-spec.mdtext
Modified: incubator/river/site/trunk/content/river/docs/specs/discovery-spec.mdtext
URL: http://svn.apache.org/viewvc/incubator/river/site/trunk/content/river/docs/specs/discovery-spec.mdtext?rev=1043519&r1=1043518&r2=1043519&view=diff
==============================================================================
--- incubator/river/site/trunk/content/river/docs/specs/discovery-spec.mdtext (original)
+++ incubator/river/site/trunk/content/river/docs/specs/discovery-spec.mdtext Wed Dec 8 16:56:49 2010
@@ -1,1782 +1,752 @@
-<!--
- ! Licensed to the Apache Software Foundation (ASF) under one
- ! or more contributor license agreements. See the NOTICE file
- ! distributed with this work for additional information
- ! regarding copyright ownership. The ASF licenses this file
- ! to you under the Apache License, Version 2.0 (the
- ! "License"); you may not use this file except in compliance
- ! with the License. You may obtain a copy of the License at
- !
- ! http://www.apache.org/licenses/LICENSE-2.0
- !
- ! Unless required by applicable law or agreed to in writing, software
- ! distributed under the License is distributed on an "AS IS" BASIS,
- ! WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- ! See the License for the specific language governing permissions and
- ! limitations under the License.
- !-->
-
-<html>
-
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<meta name="GENERATOR" content="Quadralay WebWorks Publisher 5.0.4">
-<link rel="StyleSheet" href="standard.css" type="text/css" media="screen">
-<title>Jini Discovery & Join Specification</title>
-</head>
-<body bgcolor="#ffffff">
-<a href="#skip" title="Skip navigation bar"></a>
-<table width="90%">
-<tr>
-<td align=left><a href="../../spec-index.html">Spec Index</a></td>
-<td align=right><em>Jini Technology Core Platform Specifications</em></td>
-</tr>
-</table>
-<a name="skip"></a>
-<br clear="all">
-
-
-<hr align="left">
-<table width="90%">
-<tr>
-<td align="right" font size="4"><b>Version 3.0</b></td>
-</tr>
-</table>
-
-<blockquote>
-<h2 align="left">
-<a name="40553"></a>
- <a name="999930"> </a>DJ - Jini<font size="-1"><sup>TM</sup></font> Discovery & Join Specification
-</h2>
-<h3 class="Heading2">
- <a name="18973"> </a>DJ.1 Introduction
-</h3>
-<p class="Body">
- <a name="2506"> </a>Entities that wish to start participating in a distributed system of Jini<font size="-1"><sup>TM</sup></font> technology-enabled services and/or devices, known as a <em class="Emphasis">djinn</em>, must first obtain references to one or more Jini lookup services. The protocols that govern the acquisition of these references are known as the <em class="Emphasis">discovery</em> protocols. Once these references have been obtained, a number of steps must be taken for entities to start communicating usefully with services in a djinn; these steps are described by the <em class="Emphasis">join</em> protocol.
-</p>
-<h4 class="Heading3">
- <a name="2830"> </a>DJ.1.1 Terminology
-</h4>
-<p class="Body">
- <a name="2831"> </a>A <em class="Emphasis">host</em> is a single hardware device that may be connected to one or more networks. An individual host may house one or more Java<font size="-1"><sup>TM</sup></font> virtual machines<a href="#41119"><sup>1</sup></a> (<span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">JVM</span>).
-</p>
-<p class="Body">
- <a name="3843"> </a>Throughout this document we make reference to a <em class="Emphasis">discovering entity</em>, a <em class="Emphasis">joining entity,</em> or simply an <em class="Emphasis">entity</em>.
-</p>
-<ul>
-
- <li class="SmartList1"><a name="3844"> </a>A <em class="Emphasis">discovering entity</em> is simply one or more cooperating objects in the Java programming language on the same host that are about to start, or are in the process of, obtaining references to Jini lookup services.
- <li class="SmartList1"><a name="2834"> </a>A <em class="Emphasis">joining entity</em> comprises one or more cooperating objects in the Java programming language on the same host that have just received a reference to the lookup service and are in the process of obtaining services from, and possibly exporting them to, a djinn.
- <li class="SmartList1"><a name="2835"> </a>An <em class="Emphasis">entity</em> may be a discovering entity, a joining entity, or an entity that is already a member of a djinn; the intended meaning should be clear from the context.
- <li class="SmartList1"><a name="3796"> </a>A <em class="Emphasis">group</em> is a logical name by which a djinn is identified.
-</ul>
-
-<p class="Body">
- <a name="2836"> </a>Since all participants in a djinn are collections of one or more objects in the Java programming language, this document will not make a distinction between an entity that is a dedicated device using Jini technology or something running in a <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">JVM</span> that is hosted on a legacy system. Such distinctions will be made only when necessary.
-</p>
-<h4 class="Heading3">
- <a name="2670"> </a>DJ.1.2 Host Requirements
-</h4>
-<p class="Body">
- <a name="2671"> </a>Hosts that wish to participate in a djinn must have the following properties:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="2672"> </a>A functioning <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">JVM</span>, with access to all packages needed to run software written to the Jini specifications
- <li class="SmartList1"><a name="2735"> </a>A properly configured network protocol stack
-</ul>
-
-<p class="Body">
- <a name="2736"> </a>The properties required of the network protocol stack will vary depending on the network protocol(s) being used. Throughout this document we will assume that IP is being used, and highlight areas that might apply differently to other networking protocols.
-</p>
-<h5 class="Heading4">
- <a name="2737"> </a>DJ.1.2.1 Protocol Stack Requirements for IP Networks
-</h5>
-<p class="Body">
- <a name="2738"> </a>Hosts that make use of IP for networking must have the following properties:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="2741"> </a>An IP address. IP addresses may be statically assigned to some hosts, but we expect that many hosts will have addresses assigned to them dynamically. Dynamic IP addresses are obtained by hosts through use of <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">DHCP</span>.
- <li class="SmartList1"><a name="2742"> </a>Support for unicast <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">TCP</span> and multicast <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">UDP</span>. The former is used by subsystems using Jini technology such as Java Remote Method Invocation (<span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">Java RMI</span>); both are used during discovery.
- <li class="SmartList1"><a name="2743"> </a>Provision of some mechanism, such as a simple <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">HTTP</span> server, that facilitates the downloading of code (for example, for service proxies or Java <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">Java RMI</span> stubs) by remote parties. This mechanism does not have to be provided by the host itself, but the code must be made available by some cooperating party.
-</ul>
-
-<h4 class="Heading3">
- <a name="2540"> </a>DJ.1.3 Protocol Overview
-</h4>
-<p class="Body">
- <a name="3769"> </a>There are three related discovery protocols, each designed with different purposes:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="3770"> </a>The <em class="Emphasis">multicast request protocol</em> is employed by entities that wish to discover nearby lookup services. This is the protocol used by services that are starting up and need to locate whatever djinns happen to be close. It can also be used to support browsing of local lookup services.
- <li class="SmartList1"><a name="3773"> </a>The <em class="Emphasis">multicast announcement protocol</em> is provided to allow lookup services to advertise their existence. This protocol is useful in two situations. When a new lookup service is started, it might need to announce its availability to potential clients. Also, if a network failure occurs and clients lose track of a lookup service, this protocol can be used to make them aware of its availability after network service has been restored.
- <li class="SmartList1"><a name="3774"> </a>The <em class="Emphasis">unicast discovery protocol</em> makes it possible for an entity to communicate with a specific lookup service. This is useful for dealing with non-local djinns and for using services in specific djinns over a long period of time.
-</ul>
-
-<p class="Body">
- <a name="2532"> </a>The discovery protocols require support for multicast or restricted-scope broadcast, along with support for reliable unicast delivery, in the transport layer. The discovery protocols make use of the Java platform's I/O libraries to exchange information in a platform-independent manner.
-</p>
-<h4 class="Heading3">
- <a name="3554"> </a>DJ.1.4 Discovery in Brief
-</h4>
-<p class="Body">
- <a name="4050"> </a>This section provides a brief overview of the operation of the discovery protocols. For a detailed description suitable for use by implementors, see <a href="#19702">Section DJ.2 "The Discovery Protocols"</a>.
-</p>
-<h5 class="Heading4">
- <a name="3814"> </a>DJ.1.4.1 Groups
-</h5>
-<p class="Body">
- <a name="3815"> </a>A group is an arbitrary string that acts as a name. Each lookup service has a set of zero or more groups associated with it. Entities using the multicast request protocol specify a set of groups they want to communicate with, and lookup services advertise the groups they are associated with using the multicast announcement protocol. This allows for flexibility in configuring entities: instead of maintaining a set of <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">URL</span>s for specific lookup services that needs to be updated if any of the services change address, an entity can use a set of group names.
-</p>
-<p class="Body">
- <a name="4237"> </a>Although group names are arbitrary strings, it is recommended that <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">DNS</span>-style names (for example, "eng.sun.com") be used to avoid name conflicts. One group name, represented by the empty string, is predefined as the <em class="Emphasis">public</em> group. Unless otherwise configured, lookup services should default to being members of the public group, and discovering entities should attempt to find lookup services in the public group.
-</p>
-<h5 class="Heading4">
- <a name="40012"> </a>DJ.1.4.2 The Multicast Request Protocol
-</h5>
-<p class="Body">
- <a name="40013"> </a>The multicast request protocol, shown in Figure DJ.1.1, proceeds as follows:
-</p>
-<ol type="1">
- <li class="SmartList3" value="1"><a name="40014"> </a>The entity that wishes to discover a djinn establishes a <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">TCP</span>-based server that accepts references to the lookup service. This server is an instance of the <em class="Emphasis">multicast response</em> service.
- <li class="SmartList3" value="2"><a name="2579"> </a>Lookup services listen for multicast requests for references to lookup services for the groups they manage. These listening entities are instances of the <em class="Emphasis">multicast request</em> service. This is <em class="Emphasis">not</em> an <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">Java RMI</span>-based service; the protocol is described in <a href="#19702">Section DJ.2 "The Discovery Protocols"</a>.
- <li class="SmartList3" value="3"><a name="2578"> </a>The discovering entity performs a multicast that requests references to lookup services; it provides a set of groups in which it is interested, and enough information to allow listeners to connect to its multicast response server.
- <li class="SmartList3" value="4"><a name="39865"> </a>Each multicast request server that receives the multicast checks if it is a member of a group specified in the request; if it is, it connects to the multicast response server described in the request, and uses the unicast discovery protocol to pass an instance of the lookup service's implementation of <code>net.jini.core.lookup.ServiceRegistrar</code>.
- </ol>
-<p class="Body">
- <a name="2593"> </a>At this point, the discovering entity will have obtained one or more remote references to lookup services.
-</p>
-<p>
-<CENTER>
-<img src="images/discovery-speca.gif" alt="This image illustrates the steps listed in DJ.1.4.2, the section immediately above." height="364" width="490">
-</CENTER>
-</p>
-
-
-</p>
-<div style="color: #000000; font-family: Times; font-size: 11pt; font-style: italic; font-weight: bold; margin-bottom: 17pt; margin-left: 54pt; margin-right: 0pt; margin-top: 7pt; text-align: left; text-decoration: none; text-indent: -54pt; text-transform: none; vertical-align: baseline">
-<a name="39235"> </a>Figure DJ.1.1: The Multicast Request Protocol<br>
-</div>
-<h5 class="Heading4">
- <a name="3764"> </a>DJ.1.4.3 The Multicast Announcement Protocol
-</h5>
-<p class="Body">
- <a name="3793"> </a>The multicast announcement protocol follows these steps:
-</p>
-<ol type="1">
- <li class="SmartList3" value="1"><a name="3853"> </a>Interested entities on the network listen for multicast announcements of the existence of lookup services. If an announcement of interest arrives at such an entity, it uses the unicast discovery protocol to contact the given lookup service.
- <li class="SmartList3" value="2"><a name="3856"> </a>Lookup services prepare to take part in the unicast discovery protocol (see below) and send multicast announcements of their existence at regular intervals.
- </ol>
-<h5 class="Heading4">
- <a name="3794"> </a>DJ.1.4.4 The Unicast Discovery Protocol
-</h5>
-<p class="Body">
- <a name="3795"> </a>The unicast discovery protocol works as follows:
-</p>
-<ol type="1">
- <li class="SmartList3" value="1"><a name="3859"> </a>The lookup service establishes a TCP-based server, on which it listens for incoming connections. When a connection is made by a client, the lookup service reads in request data sent by the client; if the request is acceptable, the lookup service responds by sending an object that implements the <code>net.jini.core.lookup.ServiceRegistrar</code> interface over the connection.
- <li class="SmartList3" value="2"><a name="3860"> </a>An entity that wishes to contact a particular lookup service uses known host and port information to establish a connection to that service. It sends a discovery request and, if the request is accepted, receives a <code>ServiceRegistrar</code> object in response.
- </ol>
-<h3 class="Heading2">
- <a name="19702"> </a>DJ.2 The Discovery Protocols
-</h3>
-<p class="Body">
- <a name="41527"> </a>The discovery process involves three closely related protocols: the multicast request protocol, used to discover one or more lookup services on a local area network (<span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">LAN</span>); the multicast announcement protocol, used to announce the presence of a lookup service on a local network; and the unicast discovery protocol, used to establish communications over a local area or wide area network (WAN) with a lookup service whose address is known in advance.
-</p>
-<h4 class="Heading3">
- <a name="41528"> </a>DJ.2.1 Protocol Versions
-</h4>
-<p class="Body">
- <a name="41534"> </a>For each of the three discovery protocols, two versions exist: protocol version 1, which refers to the original protocol described in versions 1.0 through 1.2 of this specification, and protocol version 2, introduced in version 2.0 of this specification. Versions 1 and 2 of the various discovery protocols differ primarily in the encoded representation of data sent between discovering entities and lookup services; the overall pattern of interaction dictated by each of the three protocols is the same in each version. Unless otherwise specified, statements about a particular protocol in this specification apply to both versions 1 and 2 of that protocol.
-</p>
-<h4 class="Heading3">
- <a name="41551"> </a>DJ.2.2 Discovery Formats
-</h4>
-<p class="Body">
- <a name="41553"> </a>For each of the three discovery protocols, version 1 of that protocol dictates a specific encoding for the data to be sent as part of the protocol. For example, version 1 of the multicast request protocol specifies a data encoding for multicast packets in which the first 4 bytes of data (following the protocol version) contain the port number for the multicast response server of the discovering entity; values for the number of lookup services known to the discovering entity, the service IDs for those lookup services, the number of groups of interest, and the names of those groups then follow in fixed order and format, as described in <a href="#19048">Section DJ.2.4.4 "Protocol Version 1 Request Packet Format"</a>.
-</p>
-<p class="Body">
- <a name="42010"> </a>In contrast, version 2 of each of the discovery protocols does not specify a fixed encoding for a subset of the data sent in requests and response messages. Rather, multicast requests, multicast responses, and unicast responses each carry a 64-bit <em class="Emphasis">discovery format ID</em> which uniquely identifies a <em class="Emphasis">discovery format</em>; this format ID is followed by <em class="Emphasis">discovery format data</em> (such as service IDs, group names, host names, and port numbers) encoded according to the indicated discovery format. The discovery format specifies how discovery format data is encoded; the discovery protocol defines a top-level message structure whose primary function is to identify the discovery format in effect for the discovery format data. The set of values that constitute the discovery format data varies depending on whether the data is for the multicast request, multicast announcement, or unicast discovery pr
otocol; the values to be included as part of the discovery format data for each protocol are listed in the section describing version 2 of that protocol.
-</p>
-<p class="Body">
- <a name="43014"> </a>Note that a single discovery format can encompass more than one discovery protocol, though it is not required to cover all three. For example, the <code>net.jini.discovery.x500.SHA1withDSA</code> format (specified in <a href="#43655">Section DJ.3.2</a>) applies to the multicast request and announcement protocols, but not to the unicast discovery protocol.
-</p>
-<h5 class="Heading4">
- <a name="41603"> </a>DJ.2.2.1 Discovery Format Names
-</h5>
-<p class="Body">
- <a name="41612"> </a>Each discovery format is uniquely identified by a <em class="Emphasis">discovery format name</em>, from which its discovery format ID is derived. Discovery format names are case sensitive. To avoid name collisions, discovery format names should follow the same reverse DNS naming convention recommended for Java package names in Section 7.7 of the <em class="Emphasis">Java Language Specification, Second Edition</em>. Examples of format names are <code>net.jini.discovery.x500.SHA1withDSA</code>, <code>net.jini.discovery.ssl</code>, and <code>net.jini.discovery.kerberos</code> (the formats associated with these names are specified in Sections <a href="#43655">DJ.3.2</a>, <a href="#42919">DJ.3.4</a>, and <a href="#43699">DJ.3.5</a>, respectively).
-</p>
-<h5 class="Heading4">
- <a name="41604"> </a>DJ.2.2.2 Discovery Format IDs
-</h5>
-<p class="Body">
- <a name="41623"> </a>The discovery format ID for a given discovery format is a 64-bit value based on a hash of the discovery format name, computed as follows: first, the discovery format name is converted into a byte sequence obtained by generating the UTF-8 encoding for the format name. This byte sequence is then used as input to the SHA-1 hash function; the discovery format ID consists of the first (most significant) 64 bits of the SHA-1 hash result. The discovery format ID with value <code>0</code> is called the <em class="Emphasis">null discovery format ID</em>, and is reserved. The SHA-1 hash function is specified in <em class="Emphasis">Federal Information Processing Standards Publication (FIPS PUB) 180-1</em>. The UTF-8 encoding is specified in <em>RFC 2279</em>.
-</p>
-<h4 class="Heading3">
- <a name="41533"> </a>DJ.2.3 Protocol Roles
-</h4>
-<p class="Body">
- <a name="18995"> </a>The multicast discovery protocols work together over time. When an entity is initially started, it uses the multicast request protocol to actively seek out nearby lookup services. After a limited period of time performing active discovery in this way, it ceases using the multicast request protocol and switches over to listening for multicast lookup announcements via the multicast announcement protocol.
-</p>
-<h4 class="Heading3">
- <a name="40029"> </a>DJ.2.4 The Multicast Request Protocol
-</h4>
-<p class="Body">
- <a name="40030"> </a>The multicast request protocol allows an entity that has just been started, or that needs to provide browsing capabilities to a user, to actively discover nearby lookup services.
-</p>
-<h5 class="Heading4">
- <a name="18998"> </a>DJ.2.4.1 Protocol Participants
-</h5>
-<p class="Body">
- <a name="41633"> </a>Several components take part in the multicast request protocol. Of these, two run on an entity that is performing multicast requests, and two run on the entity that listens for such requests and responds.
-</p>
-<p class="Body">
- <a name="41634"> </a>On the requesting side live the following components:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="41635"> </a>A multicast request client performs multicasts to discover nearby lookup services.
- <li class="SmartList1"><a name="19002"> </a>A multicast response server listens for responses from those lookup services.
-</ul>
-
-<p class="Body">
- <a name="19003"> </a>These components are paired; they do not occur separately. Any number of pairs of such components may coexist in a single <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">JVM</span> at any given time.
-</p>
-<p class="Body">
- <a name="19004"> </a>The lookup service houses the other two participants:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="19005"> </a>A multicast request server listens for incoming multicast requests.
- <li class="SmartList1"><a name="19006"> </a>A multicast response client responds to callers, passing each a proxy that allows it to communicate with its lookup service.
-</ul>
-
-<p class="Body">
- <a name="19007"> </a>Although these components are paired, as on the client side, only a single pair will typically be associated with each lookup service.
-</p>
-<p class="Body">
- <a name="40612"> </a>These local pairings apart, the remote client/server pairings should be clear from the above description and the diagram of protocol participants in Figure DJ.2.1.
-</p>
-<p>
-<CENTER>
-<img src="images/discovery-spec2.gif" alt="This image illustrates the interrelationship of the components discussed in DJ.2.2.1." height="330" width="480">
-</CENTER>
-</p>
-<div style="color: #000000; font-family: Times; font-size: 11pt; font-style: italic; font-weight: bold; margin-bottom: 17pt; margin-left: 54pt; margin-right: 0pt; margin-top: 7pt; text-align: left; text-decoration: none; text-indent: -54pt; text-transform: none; vertical-align: baseline">
-<a name="40654"> </a>Figure DJ.2.1: Multicast Request Protocol Participants<br>
-</div>
-<h5 class="Heading4">
- <a name="19046"> </a>DJ.2.4.2 The Multicast Request Service
-</h5>
-<p class="Body">
- <a name="19047"> </a>The multicast request service is not based on Java <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">Java RMI</span>; instead, it makes use of the multicast datagram facility of the networking transport layer to request that lookup services advertise their availability to a requesting host. In a <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">TCP/IP</span> environment the network protocol used is multicast <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">UDP</span>. Request datagrams are encoded as a sequence of bytes, using the I/O facilities of the Java programming language to provide platform independence.
-</p>
-<h5 class="Heading4">
- <a name="41642"> </a>DJ.2.4.3 Request Packet Contents
-</h5>
-<p class="Body">
- <a name="41643"> </a>Each multicast request packet carries the following values:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="41650"> </a>The<em class="Emphasis"> protocol version</em> value is an integer that indicates the version of the multicast request protocol in use. Currently, the only valid protocol version numbers are 1 and 2.
- <li class="SmartList1"><a name="41645"> </a>The<em class="Emphasis"> multicast response port</em> value is an integer representing the TCP port number of the discovering entity's multicast response server.
- <li class="SmartList1"><a name="41651"> </a>The<em class="Emphasis"> requested groups</em> value is a set of strings naming the groups that the discovering entity wishes to discover. This set may be empty, which indicates that discovery of all groups is requested.
- <li class="SmartList1"><a name="41652"> </a>The<em class="Emphasis"> heard lookup service IDs </em>value is a set of service IDs identifying lookup services from which the discovering entity has already heard, and which do not need to respond to the request.
-</ul>
-
-<p class="Body">
- <a name="41653"> </a>Protocol version 2 multicast request packets additionally carry at least the following values:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="41663"> </a>The<em class="Emphasis"> discovery format ID </em>value is a 64-bit number indicating the discovery format in which the discovery format data of the packet has been encoded.
- <li class="SmartList1"><a name="41664"> </a>The<em class="Emphasis"> packet type</em> value is an integer used to distinguish between multicast request and announcement packets. For request packets, this value is always 1.
- <li class="SmartList1"><a name="41660"> </a>The<em class="Emphasis"> multicast response host</em> value is a string containing the host name or IP address that lookup services should use in order to contact the discovering entity's multicast response server. In version 1 of the multicast request protocol, this information is derived from the multicast packet's source address; the multicast response host is included as an explicit value in version 2 of the multicast request protocol in order to facilitate forwarding or tunneling of multicast request packets to remote networks.
-</ul>
-
-<p class="Body">
- <a name="43160"> </a>Protocol version 2 discovery formats may also specify additional values to be included in multicast request packets.
-</p>
-<h5 class="Heading4">
- <a name="19048"> </a>DJ.2.4.4 Protocol Version 1 Request Packet Format
-</h5>
-<p class="Body">
- <a name="19163"> </a>The table below describes the contents of a multicast request protocol version 1 packet body.
-<p>
-<table border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000"
- cellpadding="5" cellspacing="0">
- <caption></caption>
- <tr bgcolor="#CCCCCC">
- <th><a name="41731"> </a><div class="CellHeading">Count</div></th>
- <th><a name="41733"> </a><div class="CellHeading">Data Type</div></th>
- <th><a name="41735"> </a><div class="CellHeading">Description</div></th>
- </tr>
- <tr>
- <td align="right"><a name="41737"> </a>1</td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: justify; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="41739"> </a><code>int</code><br>
-</div>
-</td>
- <td><a name="41741"> </a><div class="CellBody">protocol version</div></td>
- </tr>
- <tr>
- <td align="right"><a name="41743"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="41745"> </a><code>int</code><br>
-</div>
-</td>
- <td><a name="41747"> </a><div class="CellBody">multicast response port</div></td>
- </tr>
- <tr>
- <td align="right"><a name="41749"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="41751"> </a><code>int</code><br>
-</div>
-</td>
- <td><a name="41753"> </a><div class="CellBody">service ID count</div></td>
- </tr>
- <tr>
- <td><a name="41755"> </a><div class="CellBody"><em class="Emphasis">variable</em></div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="41757"> </a><code>net.jini.core.lookup.ServiceID</code><br>
-</div>
-</td>
- <td><a name="41759"> </a><div class="CellBody">heard lookup service IDs</div></td>
- </tr>
- <tr>
- <td align="right"><a name="41761"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="41763"> </a><code>int</code><br>
-</div>
-</td>
- <td><a name="41765"> </a><div class="CellBody">group count</div></td>
- </tr>
- <tr>
- <td><a name="41767"> </a><div class="CellBody"><em class="Emphasis">variable</em></div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="41769"> </a><code>java.lang.String</code><br>
-</div>
-</td>
- <td><a name="41771"> </a><div class="CellBody">requested groups</div></td>
- </tr>
-</table>
-
-
-
-
-</p>
-<p class="Body">
- <a name="41776"> </a>Packet contents consist of a contiguous series of values in the order listed above from top to bottom. Values of type <code>int</code> and <code>String</code> are encoded in the formats specified for the <code>writeInt</code> and <code>writeUTF</code> methods of the <code>java.io.DataOutput </code>interface, respectively. Values of type <code>ServiceID</code> are encoded in the format specified for the <code>ServiceID.writeBytes </code>method. The number of service IDs written must be equal to the service ID count value. The number of group strings written must be equal to the group count value.
-</p>
-<h5 class="Heading4">
- <a name="41882"> </a>DJ.2.4.5 Protocol Version 2 Request Packet Format
-</h5>
-<p class="Body">
- <a name="41883"> </a>The table below describes the contents of a protocol version 2 multicast request packet body.
-<p>
-<table border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000"
- cellpadding="5" cellspacing="0">
- <caption></caption>
- <tr bgcolor="#CCCCCC">
- <th><a name="41886"> </a><div class="CellHeading">Count</div></th>
- <th><a name="41888"> </a><div class="CellHeading">Data Type</div></th>
- <th><a name="41890"> </a><div class="CellHeading">Description</div></th>
- </tr>
- <tr>
- <td align="right"><a name="41892"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: justify; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="41894"> </a><code>int</code><br>
-</div>
-</td>
- <td><a name="41896"> </a><div class="CellBody">protocol version</div></td>
- </tr>
- <tr>
- <td align="right"><a name="41898"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="41900"> </a><code>byte</code><br>
-</div>
-</td>
- <td><a name="41902"> </a><div class="CellBody">multicast packet type</div></td>
- </tr>
- <tr>
- <td align="right"><a name="41904"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="41906"> </a><code>long</code><br>
-</div>
-</td>
- <td><a name="41908"> </a><div class="CellBody">discovery format ID</div></td>
- </tr>
- <tr>
- <td><a name="41910"> </a><div class="CellBody"><em class="Emphasis">variable</em></div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="41912"> </a><code>byte</code><br>
-</div>
-</td>
- <td><a name="41914"> </a><div class="CellBody">discovery format data</div></td>
- </tr>
-</table>
-
-
-
-
-</p>
-<p class="Body">
- <a name="41772"> </a>Packet contents consist of a contiguous series of values in the order listed above from top to bottom. Values of type <code>byte</code>, <code>int</code>, and <code>long</code> are encoded in the formats specified for the <code>writeByte</code>, <code>writeInt</code>, and <code>writeLong</code> methods of the <code>java.io.DataOutput</code> interface, respectively. Discovery format data encompasses all data from the end of the discovery format ID to the end of the packet, and is encoded according to the discovery format indicated by the discovery format ID. The discovery format data for a protocol version 2 multicast request packet must include at least the following values, described in <a href="#41642">Section DJ.2.4.3 "Request Packet Contents"</a>:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="41921"> </a>Multicast response host
- <li class="SmartList1"><a name="41922"> </a>Multicast response port
- <li class="SmartList1"><a name="41923"> </a>Requested groups
- <li class="SmartList1"><a name="41924"> </a>Heard lookup service IDs
-</ul>
-
-<h5 class="Heading4">
- <a name="41925"> </a>DJ.2.4.6 Request Packet Size
-</h5>
-<p class="Body">
- <a name="41926"> </a>Multicast request packets should be limited in size to avoid packet fragmentation. A size limit of 512 bytes is recommended, though not required. If the size of a multicast request packet body exceeds the limit established for a given deployment, the set of heard lookup service IDs must be left incomplete in the packet body, such that the packet body will conform to the size limit. Discovering entities are not permitted to simply truncate multicast request packets at the size limit.
-</p>
-<p class="Body">
- <a name="19165"> </a>Similarly, if the number of requested groups causes the request packet body to exceed the size limit, the discovering entity must perform several separate multicasts, each with a disjoint subset of the full set of requested groups, until the entire set has been requested. Each request must contain the largest set of heard lookup service IDs possible without exceeding the size limit.
-</p>
-<h5 class="Heading4">
- <a name="19166"> </a>DJ.2.4.7 The Multicast Response Service
-</h5>
-<p class="Body">
- <a name="19167"> </a>Unlike the multicast request service, the multicast response service is a normal <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">TCP</span>-based service. In this service, the multicast response client contacts the multicast response server specified in a multicast request, after which unicast discovery is performed. In version 1 of the multicast request protocol, the multicast response server to contact is determined by using the source address of the request that has been received, along with the port number encapsulated in that request. In version 2 of the multicast request protocol, the host name or IP address of the response server to contact is included as an explicit value in the multicast request, in addition to the port number.
-</p>
-<p class="Body">
- <a name="19168"> </a>The only difference between the unicast discovery performed in this instance and the normal case is that the entity being connected to initiates unicast discovery, not the connecting entity. An alternative way of looking at this is that in both cases, once the connection has been established, the discovering entity initiates unicast discovery.
-</p>
-<h5 class="Heading4">
- <a name="19169"> </a>DJ.2.4.8 Discovery Using the Multicast Request Protocol
-</h5>
-<p class="Body">
- <a name="19170"> </a>Described below is the discovery sequence for local area network (<span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">LAN</span>)-based environments that use the multicast request protocol to discover one or more djinns.
-</p>
-<p class="Body">
- <a name="19172"> </a>The entity that wishes to discover a djinn takes the following steps:
-</p>
-<ol type="1">
- <li class="SmartList3" value="1"><a name="19173"> </a>It establishes a multicast request client, which will send packets to the well-known multicast network endpoint on which the multicast request service operates.
- <li class="SmartList3" value="2"><a name="19174"> </a>It establishes a <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">TCP</span> server socket that listens for incoming connections, over which the unicast discovery protocol is used. This server socket is the multicast response server socket.
- <li class="SmartList3" value="3"><a name="19175"> </a>It creates a set of <code>net.jini.core.lookup.ServiceID</code> objects. This set contains service IDs for lookup services from which it has already heard, and is initially empty.
- <li class="SmartList3" value="4"><a name="40999"> </a>It sends multicast requests at periodic intervals. Each request contains connection information for its multicast response server, a set of requested groups, and the most recent set of service IDs for lookup services it has heard from.
- <li class="SmartList3" value="5"><a name="40127"> </a>For each response it receives via the multicast response service, it adds the service ID for that lookup service to the set it maintains.
- <li class="SmartList3" value="6"><a name="19178"> </a>The entity continues multicasting requests for some period of time. Once this point has been reached, it shuts down its multicast response server and stops making multicast requests.
- <li class="SmartList3" value="7"><a name="19179"> </a>If the entity has received sufficient references to lookup services at this point, it is now finished. Otherwise, it must start using the multicast announcement protocol.
- </ol>
-<p class="Body">
- <a name="40842"> </a>The interval at which requests are performed is not specified, though an interval of five seconds is recommended for most purposes. Similarly, the number of requests to perform is not mandated, but we recommend seven. Since requests may be broken down into a number of separate multicasts, these recommendations do not pertain to the number of packets to be sent.
-</p>
-<p class="Body">
- <a name="19182"> </a>The lookup service that hosts an instance of the multicast request service takes the following steps:
-</p>
-<ol type="1">
- <li class="SmartList3" value="1"><a name="19183"> </a>It binds a datagram socket to the well-known multicast endpoint on which the multicast request service lives so that it can receive incoming multicast requests.
- <li class="SmartList3" value="2"><a name="41979"> </a>When a multicast request is received, the discovery request server determines whether or not it should respond to the requesting entity as follows: if the service ID of the lookup service to which the request server belongs appears in the multicast request's list of heard lookup service IDs, the request server must not respond to the request. If the set of requested groups is non-empty, and none of the lookup service's own member groups appear in the set of requested groups, then the request server must not respond to the request.
- <p>The request server may additionally employ other criteria in deciding whether to respond: for example, a request server may be configured to only respond to protocol version 2 multicast requests that use the <code>net.jini.discovery.x500.SHA1withDSA</code> discovery format (specified in <a href="#43655">Section DJ.3.2</a>) and contain an authentication block with a valid signer. If the multicast request satisfies all additional conditions required by the request server, the request server must respond to the request.
- <li class="SmartList3" value="3"><a name="41982"> </a>If the entity must be responded to, the request server connects to the other party's multicast response server using the information provided in the request, and provides a lookup service registrar using the unicast discovery protocol.
- </ol>
-<h5 class="Heading4">
- <a name="19186"> </a>DJ.2.4.9 Handling Responses from Multiple Djinns
-</h5>
-<p class="Body">
- <a name="19187"> </a>The actions taken when there are several djinns on a network, and calls to an entity's discovery response service are made by principals from more than one of those djinns, will depend on the nature of the discovering entity. Possible approaches include the following:
-</p>
-<p class="Body">
- <a name="43794"> </a>If the entity provides a <em class="Emphasis">finder</em>-style visual interface that allows a user to choose one or more djinns for their system to join, it should loop at step 4 in <a href="#19169">Section DJ.2.4.8</a>, and provide the ability to:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="19189"> </a>Display the names and descriptions of the djinns it has found out about
- <li class="SmartList1"><a name="19190"> </a>Allow the user to select zero or more djinns to join
- <li class="SmartList1"><a name="19191"> </a>Continue to dynamically update its display, until the user has finished their selection
- <li class="SmartList1"><a name="19192"> </a>Attempt to join all of those djinns the user selected
-</ul>
-
-<p class="Body">
- <a name="19193"> </a>On the other hand, if the behavior of the entity is fully automated, it should follow the join protocol described in <a href="#43752">Section DJ.4 "The Join Protocol"</a>.
-</p>
-<h4 class="Heading3">
- <a name="19194"> </a>DJ.2.5 The Multicast Announcement Protocol
-</h4>
-<p class="Body">
- <a name="19195"> </a>The multicast announcement protocol is used by Jini lookup services to announce their availability to interested parties within multicast radius. Participants in this protocol are the multicast announcement client, which resides on the same system as a lookup service, and the multicast announcement server, at least one instance of which exists on every entity that listens for such announcements.
-</p>
-<p class="Body">
- <a name="19196"> </a>The multicast announcement client is a long-lived process; it must start at about the same time as the lookup service itself and remain running as long as the lookup service is alive.
-</p>
-<h5 class="Heading4">
- <a name="42026"> </a>DJ.2.5.1 Announcement Packet Contents
-</h5>
-<p class="Body">
- <a name="19198"> </a>The multicast announcement service uses multicast datagrams to communicate from a single client to an arbitrary number of servers. In a <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">TCP/IP</span> environment the underlying protocol used is multicast <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">UDP</span>. Each multicast announcement packet carries the following values:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="42035"> </a>The<em class="Emphasis"> protocol version</em> value is an integer that indicates the version of the multicast announcement protocol in use. Currently, the only valid protocol version numbers are 1 and 2.
- <li class="SmartList1"><a name="42036"> </a>The<em class="Emphasis"> unicast discovery host</em> value is a string containing the host name or IP address that discovering entities should use in order to connect to the lookup service's unicast discovery server.
- <li class="SmartList1"><a name="42037"> </a>The<em class="Emphasis"> unicast discovery port</em> value is an integer representing the TCP port number of the lookup service's unicast discovery server.
- <li class="SmartList1"><a name="42038"> </a>The<em class="Emphasis"> lookup service ID</em> value is the service ID of the lookup service.
- <li class="SmartList1"><a name="42039"> </a>The<em class="Emphasis"> member groups</em> value is a set of strings naming the discovery groups to which the lookup service belongs.
-</ul>
-
-<p class="Body">
- <a name="42048"> </a>Protocol version 2 multicast announcement packets additionally carry at least the following values:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="42608"> </a>The<em class="Emphasis"> discovery format ID</em> value is a 64-bit number indicating the discovery format in which the discovery format data of the packet has been encoded.
- <li class="SmartList1"><a name="42609"> </a>The<em class="Emphasis"> packet type</em> value is an integer used to distinguish between multicast request and announcement packets. For announcement packets, this value is always 0.
- <li class="SmartList1"><a name="43085"> </a>The<em class="Emphasis"> sequence number</em> value is a 64-bit number used to distinguish outdated multicast announcements from new ones. A lookup service must increase the sequence number for each multicast announcement with changed data that is sent. Use of sequence numbers is discussed further in <a href="#42352">Section DJ.2.5.6, "Announcement Sequence Numbers"</a>.
-</ul>
-
-<p class="Body">
- <a name="43161"> </a>Protocol version 2 discovery formats may also specify additional values to be included in multicast announcement packets.
-</p>
-<h5 class="Heading4">
- <a name="43086"> </a>DJ.2.5.2 Protocol Version 1 Announcement Packet Format
-</h5>
-<p class="Body">
- <a name="42119"> </a>The table below describes the contents of a protocol version 1 multicast announcement packet body.
-<p>
-<table border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000"
- cellpadding="5" cellspacing="0">
- <caption></caption>
- <tr bgcolor="#CCCCCC">
- <th><a name="42124"> </a><div class="CellHeading">Count</div></th>
- <th><a name="42126"> </a><div class="CellHeading">Data Type</div></th>
- <th><a name="42128"> </a><div class="CellHeading">Description</div></th>
- </tr>
- <tr>
- <td align="right"><a name="42130"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: justify; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42132"> </a><code>int</code><br>
-</div>
-</td>
- <td><a name="42134"> </a><div class="CellBody">protocol version</div></td>
- </tr>
- <tr>
- <td align="right"><a name="42136"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42138"> </a><code>java.lang.String</code><br>
-</div>
-</td>
- <td><a name="42140"> </a><div class="CellBody">unicast discovery host</div></td>
- </tr>
- <tr>
- <td align="right"><a name="42142"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42144"> </a><code>int</code><br>
-</div>
-</td>
- <td><a name="42146"> </a><div class="CellBody">unicast discovery port</div></td>
- </tr>
- <tr>
- <td align="right"><a name="42148"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42150"> </a><code>net.jini.core.lookup.ServiceID</code><br>
-</div>
-</td>
- <td><a name="42152"> </a><div class="CellBody">lookup service ID</div></td>
- </tr>
- <tr>
- <td align="right"><a name="42154"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42156"> </a><code>int</code><br>
-</div>
-</td>
- <td><a name="42158"> </a><div class="CellBody">group count</div></td>
- </tr>
- <tr>
- <td><a name="42160"> </a><div class="CellBody"><em class="Emphasis">variable</em></div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42162"> </a><code>java.lang.String</code><br>
-</div>
-</td>
- <td><a name="42164"> </a><div class="CellBody">member groups</div></td>
- </tr>
-</table>
-
-
-
-
-</p>
-<p class="Body">
- <a name="19256"> </a>Packet contents consist of a contiguous series of values in the order listed above from top to bottom. Values of type <code>int</code> and <code>String</code> are encoded in the formats specified for the <code>writeInt</code> and <code>writeUTF</code> methods of the <code>java.io.DataOutput</code> interface, respectively. The <code>ServiceID</code> value is encoded in the format specified for the <code>ServiceID.writeBytes</code> method. The number of group strings written must be equal to the group count value.
-</p>
-<h5 class="Heading4">
- <a name="42188"> </a>DJ.2.5.3 Protocol Version 2 Announcement Packet Format
-</h5>
-<p class="Body">
- <a name="42191"> </a>The table below describes the contents of a protocol version 2 multicast announcement packet body.
-<p>
-<table border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000"
- cellpadding="5" cellspacing="0">
- <caption></caption>
- <tr bgcolor="#CCCCCC">
- <th><a name="42194"> </a><div class="CellHeading">Count</div></th>
- <th><a name="42196"> </a><div class="CellHeading">Data Type</div></th>
- <th><a name="42198"> </a><div class="CellHeading">Description</div></th>
- </tr>
- <tr>
- <td align="right"><a name="42200"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: justify; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42202"> </a><code>int</code><br>
-</div>
-</td>
- <td><a name="42204"> </a><div class="CellBody">protocol version</div></td>
- </tr>
- <tr>
- <td align="right"><a name="42206"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42208"> </a><code>byte</code><br>
-</div>
-</td>
- <td><a name="42210"> </a><div class="CellBody">multicast packet type</div></td>
- </tr>
- <tr>
- <td align="right"><a name="42212"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42214"> </a><code>long</code><br>
-</div>
-</td>
- <td><a name="42216"> </a><div class="CellBody">discovery format ID</div></td>
- </tr>
- <tr>
- <td><a name="42230"> </a><div class="CellBody"><em class="Emphasis">variable</em></div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42232"> </a><code>byte</code><br>
-</div>
-</td>
- <td><a name="42234"> </a><div class="CellBody">discovery format data</div></td>
- </tr>
-</table>
-
-
-
-
-</p>
-<p class="Body">
- <a name="42246"> </a>Packet contents consist of a contiguous series of values in the order listed above from top to bottom. Values of type <code>byte</code>, <code>int</code>, and <code>long</code> are encoded in the formats specified for the <code>writeByte</code>, <code>writeInt</code>, and <code>writeLong</code> methods of the <code>java.io.DataOutput</code> interface, respectively. Discovery format data encompasses all data from the end of the discovery format ID to the end of the packet, and is encoded according to the discovery format indicated by the discovery format ID. The discovery format data for a protocol version 2 multicast announcement packet must include at least the following values, described in <a href="#42026">Section DJ.2.5.1 "Announcement Packet Contents"</a>:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="42261"> </a>Unicast discovery host
- <li class="SmartList1"><a name="42262"> </a>Unicast discovery port
- <li class="SmartList1"><a name="43169"> </a>Lookup service ID
- <li class="SmartList1"><a name="43185"> </a>Member groups
- <li class="SmartList1"><a name="43176"> </a>Sequence number
-</ul>
-
-<h5 class="Heading4">
- <a name="43171"> </a>DJ.2.5.4 Announcement Packet Size
-</h5>
-<p class="Body">
- <a name="42266"> </a>Multicast announcement packets should be limited in size to avoid packet fragmentation. A size limit of 512 bytes is recommended, though not required. If the size of a multicast announcement packet body exceeds the limit established for a given deployment, the lookup service must perform several separate multicasts, each with a disjoint subset of the full set of member groups, such that the full set of member groups is represented by the union of all packets. Lookup services are not permitted to simply truncate multicast announcements at the size limit.
-</p>
-<h5 class="Heading4">
- <a name="19257"> </a>DJ.2.5.5 Discovery Using the Multicast Announcement Protocol
-</h5>
-<p class="Body">
- <a name="19258"> </a>Described below is the sequence of actions that are taken by a lookup service and discovering entity when participating in the multicast announcement protocol.
-</p>
-<p class="Body">
- <a name="42296"> </a>The lookup service takes the following steps:
-</p>
-<ol type="1">
- <li class="SmartList3" value="1"><a name="19259"> </a>It constructs a datagram socket object, set up to send to the well-known multicast endpoint on which the multicast announcement service operates.
- <li class="SmartList3" value="2"><a name="19260"> </a>It establishes the server side of the unicast discovery service.
- <li class="SmartList3" value="3"><a name="19261"> </a>It multicasts announcement packets at intervals. The length of the interval is not mandated, but 120 seconds is recommended.
- </ol>
-<p class="Body">
- <a name="19262"> </a>An entity that wishes to listen for multicast announcements performs the following set of steps:
-</p>
-<ol type="1">
- <li class="SmartList3" value="1"><a name="19263"> </a>It establishes a set of service IDs of lookup services from which it has already heard, using the set discovered by using the multicast request protocol as the initial contents of this set.
- <li class="SmartList3" value="2"><a name="42316"> </a>It binds a datagram socket to the well-known multicast endpoint on which the multicast announcement service operates and listens for incoming multicast announcements.
- <li class="SmartList3" value="3"><a name="42317"> </a>When a multicast announcement is received, the discovering entity determines whether or not to attempt unicast discovery to the announcing lookup service as follows: if the announcement's lookup service ID is contained in the set of service IDs from which the discovering entity has already heard, then the discovering entity must not perform unicast discovery. If the member groups listed in the announcement do not intersect with the discovering entity's groups of interest, then the discovering entity must not perform unicast discovery.
- <p>The discovering entity may additionally employ other criteria in deciding whether to perform unicast discovery: for example, it may be configured to only perform unicast discovery in response to protocol 2 multicast announcements using the <code>net.jini.discovery.x500.SHA1withDSA</code> discovery format (specified in <a href="#43655">Section DJ.3.2</a>) that contain an authentication block with a recognized signer. If the multicast announcement satisfies all additional conditions required by the discovering entity, then the discovering entity should perform unicast discovery using the host and port contained in the announcement; if unicast discovery succeeds, it should then add the service ID of the discovered lookup service to its set of heard lookup service IDs.
- </ol>
-<h5 class="Heading4">
- <a name="42352"> </a>DJ.2.5.6 Announcement Sequence Numbers
-</h5>
-<p class="Body">
- <a name="42372"> </a>Protocol version 2 multicast announcements carry sequence numbers, which can be used by discovering entities to filter out outdated multicast announcements. Lookup services must ensure that a multicast announcement sent in a given announcement interval has a sequence number higher than that of the announcement sent in the preceding interval if the data represented by the two announcements differs. If the data for the two announcements is identical, then the lookup service must use a sequence number higher than or equal to that of the earlier multicast announcement. If the multicast announcement must be split due to size limitations (as described in <a href="#43171">Section DJ.2.5.4 "Announcement Packet Size"</a>), the same rule applies to the resulting announcements as a group--each announcement in the group shares the same sequence number, which must be greater than the sequence number of the multicast announcement(s) sent in the previous interval, if
the represented data differs.
-</p>
-<p class="Body">
- <a name="42410"> </a>Sequence numbers are primarily useful when coupled with a discovery format that guarantees multicast announcement data integrity. In this case, a discovering entity can guard against replayed multicast announcements by verifying that the sequence number of a received announcement is greater than or equal to the sequence number of the announcement most recently received from the announcing lookup service.
-</p>
-<h4 class="Heading3">
- <a name="42373"> </a>DJ.2.6 The Unicast Discovery Protocol
-</h4>
-<p class="Body">
- <a name="42366"> </a>The unicast discovery protocol is used to obtain a reference to a lookup service with a known address. It is also employed as the last step of multicast discovery, after a connection to the lookup service's unicast discovery server has been established through either the multicast announcement or multicast request protocol. Unicast discovery is particularly useful for obtaining references to distant lookup services located outside of multicast range.
-</p>
-<p class="Body">
- <a name="19268"> </a>The unicast discovery protocol uses the underlying reliable unicast transport protocol provided by the network instead of the unreliable multicast transport. In the case of IP-based networks this means that the unicast discovery protocol uses unicast <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">TCP</span> instead of multicast <span style="color: #000000; font-size: 10pt; font-style: normal; font-weight: normal; text-decoration: none; text-transform: none; vertical-align: baseline">UDP</span>.
-</p>
-<h5 class="Heading4">
- <a name="19269"> </a>DJ.2.6.1 The Protocol
-</h5>
-<p class="Body">
- <a name="19270"> </a>The unicast discovery protocol is fundamentally a simple request-response protocol. In version 2 of the protocol, discovery formats may specify additional communication over the unicast connection, though the overall pattern of interaction remains the same: the discovering entity requests a reference to the lookup service, and the lookup service responds by sending its proxy to the client.
-</p>
-<p class="Body">
- <a name="42526"> </a>To initiate unicast discovery, the discovering entity opens a TCP connection to the host and port of the lookup service's unicast discovery server. In the case of standalone unicast discovery, the host and port are typically obtained from a <code>net.jini.core.discovery.LookupLocator</code> instance; if unicast discovery is occurring as the final stage of the multicast announcement protocol, the host and port are obtained from the multicast announcement packet. The discovering entity then sends a unicast discovery request over the connection. If the lookup service determines that the request is acceptable, it responds by transmitting its proxy--an object implementing the <code>net.jini.core.lookup.ServiceRegistrar</code> interface--over the connection to the discovering entity.
-</p>
-<p class="Body">
- <a name="42547"> </a>Unicast discovery may also be initiated by the lookup service. In the final stage of the multicast request protocol, the lookup service responds to a multicast request by opening a TCP connection to the discovering entity's multicast response server, whose host and port are indicated by the multicast request. The multicast response server accepts the connection and sends a unicast discovery request over it to the lookup service. As in the case of discovery entity-initiated unicast discovery, the lookup service may then respond by sending its proxy, if the request is deemed acceptable.
-</p>
-<p class="Body">
- <a name="42576"> </a>The protocol diagram in Figure DJ.2.2</a> illustrates the sequence of events when unicast discovery is initiated by a discovering entity.
-</p>
-<p><CENTER>
-<img src="images/discovery-spec3.gif" alt="This image illustrates the actions described in DJ.2.5.1, when a discovering entity is the initiator." height="207" width="480">
-
-</CENTER></p>
-<div style="color: #000000; font-family: Times; font-size: 11pt; font-style: italic; font-weight: bold; margin-bottom: 17pt; margin-left: 54pt; margin-right: 0pt; margin-top: 7pt; text-align: left; text-decoration: none; text-indent: -54pt; text-transform: none; vertical-align: baseline">
-<a name="42571"> </a>Figure DJ.2.2: Unicast Discovery Initiated by a Discovering Entity<br>
-</div>
-<p class="Body">
- <a name="42514"> </a>The protocol diagram in Figure DJ.2.3 illustrates the sequence of events when a lookup service initiates unicast discovery in response to a multicast request.
-</p>
-<p><CENTER>
-<img src="images/discovery-spec4.gif" alt="This image illustrates the actions described in DJ.2.5.1, when a lookup service is the initiator." height="233" width="480">
-
-</CENTER></p>
-<div style="color: #000000; font-family: Times; font-size: 11pt; font-style: italic; font-weight: bold; margin-bottom: 17pt; margin-left: 54pt; margin-right: 0pt; margin-top: 7pt; text-align: left; text-decoration: none; text-indent: -54pt; text-transform: none; vertical-align: baseline">
-<a name="40189"> </a>Figure DJ.2.3: Unicast Discovery Initiated by a Lookup Service<br>
-</div>
-<h5 class="Heading4">
- <a name="19328"> </a>DJ.2.6.2 Unicast Request Contents
-</h5>
-<p class="Body">
- <a name="42593"> </a>Each unicast request carries the following value:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="42594"> </a>The<em class="Emphasis"> protocol version</em> value is an integer that indicates the version of the unicast discovery protocol in use. Currently, the only valid protocol version numbers are 1 and 2.
-</ul>
-
-<p class="Body">
- <a name="42600"> </a>Protocol version 2 unicast requests additionally carry the following value:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="42601"> </a>The<em class="Emphasis"> proposed format IDs</em> value is a list of 64-bit numbers indicating the discovery formats that the discovering entity is willing to use for unicast discovery. It is ordered in terms of preference, with discovery format IDs for preferred discovery formats appearing first.
-</ul>
-
-<h5 class="Heading4">
- <a name="42618"> </a>DJ.2.6.3 Unicast Response Contents
-</h5>
-<p class="Body">
- <a name="42602"> </a>Each unicast response carries the following values:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="42603"> </a>The<em class="Emphasis"> registrar proxy</em> value is the proxy object for the lookup service, which implements the <code>net.jini.core.lookup.ServiceRegistrar</code> interface.
- <li class="SmartList1"><a name="42604"> </a>The<em class="Emphasis"> member groups</em> value is a set of strings naming the discovery groups to which the lookup service belongs.
-</ul>
-
-<p class="Body">
- <a name="42606"> </a>Protocol version 2 unicast responses additionally carry at least the following values:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="42706"> </a>The<em class="Emphasis"> protocol version</em> value is an integer that indicates the version of the unicast discovery protocol in use. Currently, the only valid protocol version numbers are 1 and 2.
- <li class="SmartList1"><a name="42607"> </a>The<em class="Emphasis"> selected format ID</em> value is a 64-bit number indicating the discovery format in which the rest of the data sent over the connection (potentially in both directions) will be encoded. This value must be one of the proposed format IDs contained in the corresponding unicast request, or the null format ID. In the case of a null format ID, the response only contains the <em>protocol version</em> and <em>format ID</em>.
- <li class="SmartList1"><a name="42615"> </a>The<em class="Emphasis"> unicast discovery host</em> value is a string containing the host name or IP address that discovering entities should use in order to connect to the lookup service's unicast discovery server.
- <li class="SmartList1"><a name="42616"> </a>The<em class="Emphasis"> unicast discovery port</em> value is an integer representing the TCP port number of the lookup service's unicast discovery server.
-</ul>
-
-<p class="Body">
- <a name="43194"> </a>Protocol version 2 discovery formats may also specify additional values to be included in unicast responses.
-</p>
-<h5 class="Heading4">
- <a name="42596"> </a>DJ.2.6.4 Protocol Version 1 Request Format
-</h5>
-<p class="Body">
- <a name="42597"> </a>The table below describes the contents of a protocol version 1 unicast request.
-<p>
-<table border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000"
- cellpadding="5" cellspacing="0">
- <caption></caption>
- <tr bgcolor="#CCCCCC">
- <th><a name="42624"> </a><div class="CellHeading">Count</div></th>
- <th><a name="42626"> </a><div class="CellHeading">Data Type</div></th>
- <th><a name="42628"> </a><div class="CellHeading">Description</div></th>
- </tr>
- <tr>
- <td align="right"><a name="42630"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: justify; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42632"> </a><code>int</code><br>
-</div>
-</td>
- <td><a name="42634"> </a><div class="CellBody">protocol version</div></td>
- </tr>
-</table>
-
-
-
-
-</p>
-<p class="Body">
- <a name="42620"> </a>The <code>int</code> protocol version value is encoded in the format specified for the <code>writeInt</code> method of the <code>java.io.DataOutput</code> interface.
-</p>
-<h5 class="Heading4">
- <a name="42659"> </a>DJ.2.6.5 Protocol Version 1 Response Format
-</h5>
-<p class="Body">
- <a name="42660"> </a>The table below describes the contents of a protocol version 1 unicast response.
-<p>
-<table border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000"
- cellpadding="5" cellspacing="0">
- <caption></caption>
- <tr bgcolor="#CCCCCC">
- <th><a name="42666"> </a><div class="CellHeading">Count</div></th>
- <th><a name="42668"> </a><div class="CellHeading">Data Type</div></th>
- <th><a name="42670"> </a><div class="CellHeading">Description</div></th>
- </tr>
- <tr>
- <td align="right"><a name="42672"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: justify; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42674"> </a><code>java.rmi.MarshalledObject</code><br>
-</div>
-</td>
- <td><a name="42676"> </a><div class="CellBody">registrar proxy</div></td>
- </tr>
- <tr>
- <td align="right"><a name="42678"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42680"> </a><code>int</code><br>
-</div>
-</td>
- <td><a name="42682"> </a><div class="CellBody">group count</div></td>
- </tr>
- <tr>
- <td><a name="42690"> </a><div class="CellBody"><em class="Emphasis">variable</em></div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42692"> </a><code>java.lang.String</code><br>
-</div>
-</td>
- <td><a name="42694"> </a><div class="CellBody">member groups</div></td>
- </tr>
-</table>
-
-
-
-
-</p>
-<p class="Body">
- <a name="42658"> </a>Packet contents consist of a contiguous series of values in the order listed above from top to bottom. The registrar proxy is written in the same format that would be produced by constructing a <code>java.io.ObjectOutputStream</code>, and writing to it an instance of <code>java.rmi.MarshalledObject</code> containing the marshalled registrar proxy. Values of type <code>int</code> and <code>String</code> are encoded in the formats that would be generated by calling the <code>writeInt</code> and <code>writeUTF</code> methods of the same <code>ObjectOutputStream</code> instance used to write the <code>MarshalledObject</code> containing the registrar proxy. The number of group strings written must be equal to the group count value.
-</p>
-<h5 class="Heading4">
- <a name="42723"> </a>DJ.2.6.6 Protocol Version 2 Request Format
-</h5>
-<p class="Body">
- <a name="42724"> </a>The table below describes the contents of a protocol version 2 unicast request.
-</p>
-<p>
-<table border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000"
- cellpadding="5" cellspacing="0">
- <caption></caption>
- <tr bgcolor="#CCCCCC">
- <th><a name="42731"> </a><div class="CellHeading">Count</div></th>
- <th><a name="42733"> </a><div class="CellHeading">Data Type</div></th>
- <th><a name="42735"> </a><div class="CellHeading">Description</div></th>
- </tr>
- <tr>
- <td align="right"><a name="42737"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: justify; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42739"> </a><code>int</code><br>
-</div>
-</td>
- <td><a name="42741"> </a><div class="CellBody">protocol version</div></td>
- </tr>
- <tr>
- <td align="right"><a name="42743"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42745"> </a>unsigned <code>short</code><br>
-</div>
-</td>
- <td><a name="42747"> </a><div class="CellBody">proposed format ID count</div></td>
- </tr>
- <tr>
- <td><a name="42755"> </a><div class="CellBody"><em class="Emphasis">variable</em></div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42757"> </a><code>long</code><br>
-</div>
-</td>
- <td><a name="42759"> </a><div class="CellBody">proposed format IDs</div></td>
- </tr>
-</table>
-
-
-
-<p class="Body">
- <a name="42725"> </a>Packet contents consist of a contiguous series of values in the order listed above from top to bottom. Values of type <code>int</code> and <code>long</code> are encoded in the formats specified for the <code>writeInt</code> and <code>writeLong</code> methods of the <code>java.io.DataOutput</code> interface, respectively. The unsigned <code>short</code> value is encoded as if it were cast to a signed <code>short</code> value, and then written in the format specified for the <code>writeShort</code> method of the <code>java.io.DataOutput</code> interface. The number of discovery format ID values written must be equal to the proposed format ID count value.
-</p>
-<p class="Body">
- <a name="42788"> </a>Note that after the protocol version 2 response has been read, the discovering entity may write additional data to the connection following the last element of the request, if so dictated by the selected discovery format indicated in the response. However, since this data is discovery format dependent and is written (if called for) only after receipt of the unicast response, it is not considered part of the unicast request proper.
-</p>
-<h5 class="Heading4">
- <a name="42796"> </a>DJ.2.6.7 Protocol Version 2 Response Format
-</h5>
-<p class="Body">
- <a name="42824"> </a>The table below describes the contents of a protocol version 2 unicast response.
-<p>
-<table border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000"
- cellpadding="5" cellspacing="0">
- <caption></caption>
- <tr bgcolor="#CCCCCC">
- <th><a name="42801"> </a><div class="CellHeading">Count</div></th>
- <th><a name="42803"> </a><div class="CellHeading">Data Type</div></th>
- <th><a name="42805"> </a><div class="CellHeading">Description</div></th>
- </tr>
- <tr>
- <td align="right"><a name="42807"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: justify; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42809"> </a><code>int</code><br>
-</div>
-</td>
- <td><a name="42811"> </a><div class="CellBody">protocol version</div></td>
- </tr>
- <tr>
- <td align="right"><a name="42813"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42815"> </a><code>long</code><br>
-</div>
-</td>
- <td><a name="42817"> </a><div class="CellBody">selected format ID</div></td>
- </tr>
- <tr>
- <td><a name="42819"> </a><div class="CellBody"><em class="Emphasis">variable</em></div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42821"> </a><code>byte</code><br>
-</div>
-</td>
- <td><a name="42823"> </a><div class="CellBody">discovery format data</div></td>
- </tr>
-</table>
-
-
-
-
-</p>
-<p class="Body">
- <a name="42861"> </a>Packet contents consist of a contiguous series of values in the order listed above from top to bottom. Values of type <code>byte</code>, <code>int</code>, and <code>long</code> are encoded in the formats specified for the <code>writeByte</code>, <code>writeInt</code>, and <code>writeLong</code> methods of the <code>java.io.DataOutput</code> interface, respectively. Discovery format data encompasses all data sent after the end of the discovery format ID, until the connection is closed. If the format ID is the null format ID, then the discovery format data must not be present. Otherwise, the discovery format data must include at least the following values, described in <a href="#42618">Section DJ.2.6.3, "Unicast Response Contents"</a>:
-</p>
-<ul>
-
- <li class="SmartList1"><a name="42868"> </a>Registrar proxy
- <li class="SmartList1"><a name="42869"> </a>Member groups
- <li class="SmartList1"><a name="42870"> </a>Unicast discovery host
- <li class="SmartList1"><a name="42871"> </a>Unicast discovery port
-</ul>
-
-<p class="Body">
- <a name="42862"> </a>Note that the selected discovery format may also call for the discovering entity to send discovery format data, such as authentication information, to the lookup service.
-</p>
-<h5 class="Heading4">
- <a name="42797"> </a>DJ.2.6.8 Protocol Version 2 Discovery Format Negotiation
-</h5>
-<p class="Body">
- <a name="42880"> </a>In version 2 of the unicast discovery protocol, unicast requests carry lists of discovery format IDs representing proposed discovery formats. When a lookup service supporting version 2 of the unicast discovery protocol receives such a request, it should iterate through the list of proposed discovery formats until it encounters a discovery format that it supports. It should then include the discovery format ID for this format as the selected format ID in the response it sends back to the discovering entity, and encode/decode all subsequent data transmitted over the connection according to the selected format. If none of the proposed discovery formats is acceptable, the lookup service must write the null discovery format ID as the selected format ID in its response.
-</p>
-<h3 class="Heading2">
- <a name="19455"> </a>DJ.3 Standard Discovery Formats
-</h3>
-<p class="Body">
- <a name="42924"> </a>This section specifies a set of standard discovery formats to be used with version 2 of the multicast request, multicast announcement, and unicast discovery protocols. The discovery formats presented here should not preclude the creation or use of other discovery formats; rather, they are provided in order to serve as an initial baseline for interoperability.
-</p>
-<h4 class="Heading3">
- <a name="42916"> </a>DJ.3.1 The <code>net.jini.discovery.plaintext</code> Format
-</h4>
-<p class="Body">
- <a name="42930"> </a>The <code>net.jini.discovery.plaintext</code> format specifies plaintext encodings for discovery format data. It does not provide encryption or integrity protection of the discovery format data. It applies to the multicast request, multicast announcement, and unicast discovery protocols. The discovery format ID for this format is <code>8507042184704347702</code>.
-</p>
-<h5 class="Heading4">
- <a name="42932"> </a>DJ.3.1.1 Multicast Requests
-</h5>
-<p class="Body">
- <a name="42947"> </a>The table below illustrates the layout for multicast request discovery format data specified by the <code>net.jini.discovery.plaintext</code> discovery format. The values to encode are described in <a href="#41882">Section DJ.2.4.5, "Protocol Version 2 Request Packet Format"</a>.
-<p>
-<table border="1" bordercolorlight="#FFFFFF" bordercolordark="#000000"
- cellpadding="5" cellspacing="0">
- <caption></caption>
- <tr bgcolor="#CCCCCC">
- <th><a name="42963"> </a><div class="CellHeading">Count</div></th>
- <th><a name="42965"> </a><div class="CellHeading">Data Type</div></th>
- <th><a name="42967"> </a><div class="CellHeading">Description</div></th>
- </tr>
- <tr>
- <td align="right"><a name="42969"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: justify; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42971"> </a><code>java.lang.String</code><br>
-</div>
-</td>
- <td><a name="42973"> </a><div class="CellBody">multicast response host</div></td>
- </tr>
- <tr>
- <td align="right"><a name="42975"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42977"> </a>unsigned <code>short</code><br>
-</div>
-</td>
- <td><a name="42979"> </a><div class="CellBody">multicast response port</div></td>
- </tr>
- <tr>
- <td align="right"><a name="42981"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42983"> </a>unsigned <code>short</code><br>
-</div>
-</td>
- <td><a name="42985"> </a><div class="CellBody">group count</div></td>
- </tr>
- <tr>
- <td><a name="42987"> </a><div class="CellBody"><em class="Emphasis">variable</em></div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="42989"> </a><code>java.lang.String</code><br>
-</div>
-</td>
- <td><a name="42991"> </a><div class="CellBody">requested groups</div></td>
- </tr>
- <tr>
- <td align="right"><a name="43143"> </a><div class="CellBody">1</div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="43145"> </a>unsigned <code>short</code><br>
-</div>
-</td>
- <td><a name="43147"> </a><div class="CellBody">service ID count</div></td>
- </tr>
- <tr>
- <td><a name="43151"> </a><div class="CellBody"><em class="Emphasis">variable</em></div></td>
- <td><div style="color: #000000; font-family: Lucida Sans Typewriter; font-size: 11pt; font-style: normal; font-weight: normal; margin-bottom: 0pt; margin-left: 0pt; margin-right: 0pt; margin-top: 0pt; text-align: left; text-decoration: none; text-indent: 0pt; text-transform: none; vertical-align: sub">
-<a name="43153"> </a><code>net.jini.core.lookup.ServiceID</code><br>
-</div>
-</td>
- <td><a name="43155"> </a><div class="CellBody">heard lookup service IDs</div></td>
- </tr>
-</table>
-
-
-
-
-</p>
-<p class="Body">
[... 1455 lines stripped ...]